Collections and Data Structures
Iteration
Sequential iteration is implemented by the iterate
function. The general for
loop:
for i in iter # or "for i = iter"
# body
end
is translated into:
next = iterate(iter)
while next !== nothing
(i, state) = next
# body
next = iterate(iter, state)
end
The state
object may be anything, and should be chosen appropriately for each iterable type. See the manual section on the iteration interface for more details about defining a custom iterable type.
Base.iterate
— Functioniterate(iter [, state]) -> Union{Nothing, Tuple{Any, Any}}
Advance the iterator to obtain the next element. If no elements remain, nothing
should be returned. Otherwise, a 2-tuple of the next element and the new iteration state should be returned.
Base.IteratorSize
— TypeIteratorSize(itertype::Type) -> IteratorSize
Given the type of an iterator, return one of the following values:
SizeUnknown()
if the length (number of elements) cannot be determined in advance.HasLength()
if there is a fixed, finite length.HasShape{N}()
if there is a known length plus a notion of multidimensional shape (as for an array). In this caseN
should give the number of dimensions, and theaxes
function is valid for the iterator.IsInfinite()
if the iterator yields values forever.
The default value (for iterators that do not define this function) is HasLength()
. This means that most iterators are assumed to implement length
.
This trait is generally used to select between algorithms that pre-allocate space for their result, and algorithms that resize their result incrementally.
julia> Base.IteratorSize(1:5)
Base.HasShape{1}()
julia> Base.IteratorSize((2,3))
Base.HasLength()
Base.IteratorEltype
— TypeIteratorEltype(itertype::Type) -> IteratorEltype
Given the type of an iterator, return one of the following values:
EltypeUnknown()
if the type of elements yielded by the iterator is not known in advance.HasEltype()
if the element type is known, andeltype
would return a meaningful value.
HasEltype()
is the default, since iterators are assumed to implement eltype
.
This trait is generally used to select between algorithms that pre-allocate a specific type of result, and algorithms that pick a result type based on the types of yielded values.
julia> Base.IteratorEltype(1:5)
Base.HasEltype()
Fully implemented by:
AbstractRange
UnitRange
Tuple
Number
AbstractArray
BitSet
IdDict
Dict
WeakKeyDict
EachLine
AbstractString
Set
Pair
NamedTuple
Constructors and Types
Base.AbstractRange
— TypeAbstractRange{T} <: AbstractVector{T}
Supertype for linear ranges with elements of type T
. UnitRange
, LinRange
and other types are subtypes of this.
All subtypes must define step
. Thus LogRange
is not a subtype of AbstractRange
.
Base.OrdinalRange
— TypeOrdinalRange{T, S} <: AbstractRange{T}
Supertype for ordinal ranges with elements of type T
with spacing(s) of type S
. The steps should be always-exact multiples of oneunit
, and T
should be a "discrete" type, which cannot have values smaller than oneunit
. For example, Integer
or Date
types would qualify, whereas Float64
would not (since this type can represent values smaller than oneunit(Float64)
. UnitRange
, StepRange
, and other types are subtypes of this.
Base.AbstractUnitRange
— TypeAbstractUnitRange{T} <: OrdinalRange{T, T}
Supertype for ranges with a step size of oneunit(T)
with elements of type T
. UnitRange
and other types are subtypes of this.
Base.StepRange
— TypeStepRange{T, S} <: OrdinalRange{T, S}
Ranges with elements of type T
with spacing of type S
. The step between each element is constant, and the range is defined in terms of a start
and stop
of type T
and a step
of type S
. Neither T
nor S
should be floating point types. The syntax a:b:c
with b != 0
and a
, b
, and c
all integers creates a StepRange
.
Examples
julia> collect(StepRange(1, Int8(2), 10))
5-element Vector{Int64}:
1
3
5
7
9
julia> typeof(StepRange(1, Int8(2), 10))
StepRange{Int64, Int8}
julia> typeof(1:3:6)
StepRange{Int64, Int64}
Base.UnitRange
— TypeUnitRange{T<:Real}
A range parameterized by a start
and stop
of type T
, filled with elements spaced by 1
from start
until stop
is exceeded. The syntax a:b
with a
and b
both Integer
s creates a UnitRange
.
Examples
julia> collect(UnitRange(2.3, 5.2))
3-element Vector{Float64}:
2.3
3.3
4.3
julia> typeof(1:10)
UnitRange{Int64}
Base.LinRange
— TypeLinRange{T,L}
A range with len
linearly spaced elements between its start
and stop
. The size of the spacing is controlled by len
, which must be an Integer
.
Examples
julia> LinRange(1.5, 5.5, 9)
9-element LinRange{Float64, Int64}:
1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5
Compared to using range
, directly constructing a LinRange
should have less overhead but won't try to correct for floating point errors:
julia> collect(range(-0.1, 0.3, length=5))
5-element Vector{Float64}:
-0.1
0.0
0.1
0.2
0.3
julia> collect(LinRange(-0.1, 0.3, 5))
5-element Vector{Float64}:
-0.1
-1.3877787807814457e-17
0.09999999999999999
0.19999999999999998
0.3
See also Logrange
for logarithmically spaced points.
General Collections
Base.isempty
— Functionisempty(collection) -> Bool
Determine whether a collection is empty (has no elements).
isempty(itr)
may consume the next element of a stateful iterator itr
unless an appropriate Base.isdone(itr)
method is defined. Stateful iterators should implement isdone
, but you may want to avoid using isempty
when writing generic code which should support any iterator type.
Examples
julia> isempty([])
true
julia> isempty([1 2 3])
false
isempty(condition)
Return true
if no tasks are waiting on the condition, false
otherwise.
Base.isdone
— Functionisdone(itr, [state]) -> Union{Bool, Missing}
This function provides a fast-path hint for iterator completion. This is useful for stateful iterators that want to avoid having elements consumed if they are not going to be exposed to the user (e.g. when checking for done-ness in isempty
or zip
).
Stateful iterators that want to opt into this feature should define an isdone
method that returns true/false depending on whether the iterator is done or not. Stateless iterators need not implement this function.
If the result is missing
, callers may go ahead and compute iterate(x, state) === nothing
to compute a definite answer.
Base.empty!
— Functionempty!(collection) -> collection
Remove all elements from a collection
.
Examples
julia> A = Dict("a" => 1, "b" => 2)
Dict{String, Int64} with 2 entries:
"b" => 2
"a" => 1
julia> empty!(A);
julia> A
Dict{String, Int64}()
empty!(c::Channel)
Empty a Channel c
by calling empty!
on the internal buffer. Return the empty channel.
Base.length
— Functionlength(collection) -> Integer
Return the number of elements in the collection.
Use lastindex
to get the last valid index of an indexable collection.
See also: size
, ndims
, eachindex
.
Examples
julia> length(1:5)
5
julia> length([1, 2, 3, 4])
4
julia> length([1 2; 3 4])
4
Base.checked_length
— FunctionBase.checked_length(r)
Calculates length(r)
, but may check for overflow errors where applicable when the result doesn't fit into Union{Integer(eltype(r)),Int}
.
Fully implemented by:
AbstractRange
UnitRange
Tuple
Number
AbstractArray
BitSet
IdDict
Dict
WeakKeyDict
AbstractString
Set
NamedTuple
Iterable Collections
Base.in
— Functionin(item, collection) -> Bool
∈(item, collection) -> Bool
Determine whether an item is in the given collection, in the sense that it is ==
to one of the values generated by iterating over the collection. Can equivalently be used with infix syntax:
item in collection
item ∈ collection
Return a Bool
value, except if item
is missing
or collection
contains missing
but not item
, in which case missing
is returned (three-valued logic, matching the behavior of any
and ==
). Some collections follow a slightly different definition. For example, Set
s check whether the item isequal
to one of the elements; Dict
s look for key=>value
pairs, and the key
is compared using isequal
.
To test for the presence of a key in a dictionary, use haskey
or k in keys(dict)
. For the collections mentioned above, the result is always a Bool
.
When broadcasting with in.(items, collection)
or items .∈ collection
, both items
and collection
are broadcasted over, which is often not what is intended. For example, if both arguments are vectors (and the dimensions match), the result is a vector indicating whether each value in collection items
is in
the value at the corresponding position in collection
. To get a vector indicating whether each value in items
is in collection
, wrap collection
in a tuple or a Ref
like this: in.(items, Ref(collection))
or items .∈ Ref(collection)
.
See also: ∉
, insorted
, contains
, occursin
, issubset
.
Examples
julia> a = 1:3:20
1:3:19
julia> 4 in a
true
julia> 5 in a
false
julia> missing in [1, 2]
missing
julia> 1 in [2, missing]
missing
julia> 1 in [1, missing]
true
julia> missing in Set([1, 2])
false
julia> (1=>missing) in Dict(1=>10, 2=>20)
missing
julia> [1, 2] .∈ [2, 3]
2-element BitVector:
0
0
julia> [1, 2] .∈ ([2, 3],)
2-element BitVector:
0
1
Base.:∉
— Function∉(item, collection) -> Bool
∌(collection, item) -> Bool
Negation of ∈
and ∋
, i.e. checks that item
is not in collection
.
When broadcasting with items .∉ collection
, both items
and collection
are broadcasted over, which is often not what is intended. For example, if both arguments are vectors (and the dimensions match), the result is a vector indicating whether each value in collection items
is not in the value at the corresponding position in collection
. To get a vector indicating whether each value in items
is not in collection
, wrap collection
in a tuple or a Ref
like this: items .∉ Ref(collection)
.
Examples
julia> 1 ∉ 2:4
true
julia> 1 ∉ 1:3
false
julia> [1, 2] .∉ [2, 3]
2-element BitVector:
1
1
julia> [1, 2] .∉ ([2, 3],)
2-element BitVector:
1
0
Base.hasfastin
— FunctionBase.hasfastin(T)
Determine whether the computation x ∈ collection
where collection::T
can be considered as a "fast" operation (typically constant or logarithmic complexity). The definition hasfastin(x) = hasfastin(typeof(x))
is provided for convenience so that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types.
The default for hasfastin(T)
is true
for subtypes of AbstractSet
, AbstractDict
and AbstractRange
and false
otherwise.
Base.eltype
— Functioneltype(type)
Determine the type of the elements generated by iterating a collection of the given type
. For dictionary types, this will be a Pair{KeyType,ValType}
. The definition eltype(x) = eltype(typeof(x))
is provided for convenience so that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types.
Examples
julia> eltype(fill(1f0, (2,2)))
Float32
julia> eltype(fill(0x1, (2,2)))
UInt8
Base.indexin
— Functionindexin(a, b)
Return an array containing the first index in b
for each value in a
that is a member of b
. The output array contains nothing
wherever a
is not a member of b
.
See also: sortperm
, findfirst
.
Examples
julia> a = ['a', 'b', 'c', 'b', 'd', 'a'];
julia> b = ['a', 'b', 'c'];
julia> indexin(a, b)
6-element Vector{Union{Nothing, Int64}}:
1
2
3
2
nothing
1
julia> indexin(b, a)
3-element Vector{Union{Nothing, Int64}}:
1
2
3
Base.unique
— Functionunique(itr)
Return an array containing only the unique elements of collection itr
, as determined by isequal
and hash
, in the order that the first of each set of equivalent elements originally appears. The element type of the input is preserved.
See also: unique!
, allunique
, allequal
.
Examples
julia> unique([1, 2, 6, 2])
3-element Vector{Int64}:
1
2
6
julia> unique(Real[1, 1.0, 2])
2-element Vector{Real}:
1
2
unique(f, itr)
Return an array containing one value from itr
for each unique value produced by f
applied to elements of itr
.
Examples
julia> unique(x -> x^2, [1, -1, 3, -3, 4])
3-element Vector{Int64}:
1
3
4
This functionality can also be used to extract the indices of the first occurrences of unique elements in an array:
julia> a = [3.1, 4.2, 5.3, 3.1, 3.1, 3.1, 4.2, 1.7];
julia> i = unique(i -> a[i], eachindex(a))
4-element Vector{Int64}:
1
2
3
8
julia> a[i]
4-element Vector{Float64}:
3.1
4.2
5.3
1.7
julia> a[i] == unique(a)
true
unique(A::AbstractArray; dims::Int)
Return unique regions of A
along dimension dims
.
Examples
julia> A = map(isodd, reshape(Vector(1:8), (2,2,2)))
2×2×2 Array{Bool, 3}:
[:, :, 1] =
1 1
0 0
[:, :, 2] =
1 1
0 0
julia> unique(A)
2-element Vector{Bool}:
1
0
julia> unique(A, dims=2)
2×1×2 Array{Bool, 3}:
[:, :, 1] =
1
0
[:, :, 2] =
1
0
julia> unique(A, dims=3)
2×2×1 Array{Bool, 3}:
[:, :, 1] =
1 1
0 0
Base.unique!
— Functionunique!(f, A::AbstractVector)
Selects one value from A
for each unique value produced by f
applied to elements of A
, then return the modified A.
This method is available as of Julia 1.1.
Examples
julia> unique!(x -> x^2, [1, -1, 3, -3, 4])
3-element Vector{Int64}:
1
3
4
julia> unique!(n -> n%3, [5, 1, 8, 9, 3, 4, 10, 7, 2, 6])
3-element Vector{Int64}:
5
1
9
julia> unique!(iseven, [2, 3, 5, 7, 9])
2-element Vector{Int64}:
2
3
unique!(A::AbstractVector)
Remove duplicate items as determined by isequal
and hash
, then return the modified A
. unique!
will return the elements of A
in the order that they occur. If you do not care about the order of the returned data, then calling (sort!(A); unique!(A))
will be much more efficient as long as the elements of A
can be sorted.
Examples
julia> unique!([1, 1, 1])
1-element Vector{Int64}:
1
julia> A = [7, 3, 2, 3, 7, 5];
julia> unique!(A)
4-element Vector{Int64}:
7
3
2
5
julia> B = [7, 6, 42, 6, 7, 42];
julia> sort!(B); # unique! is able to process sorted data much more efficiently.
julia> unique!(B)
3-element Vector{Int64}:
6
7
42
Base.allunique
— Functionallunique(itr) -> Bool
allunique(f, itr) -> Bool
Return true
if all values from itr
are distinct when compared with isequal
. Or if all of [f(x) for x in itr]
are distinct, for the second method.
Note that allunique(f, itr)
may call f
fewer than length(itr)
times. The precise number of calls is regarded as an implementation detail.
allunique
may use a specialized implementation when the input is sorted.
See also: unique
, issorted
, allequal
.
The method allunique(f, itr)
requires at least Julia 1.11.
Examples
julia> allunique([1, 2, 3])
true
julia> allunique([1, 2, 1, 2])
false
julia> allunique(Real[1, 1.0, 2])
false
julia> allunique([NaN, 2.0, NaN, 4.0])
false
julia> allunique(abs, [1, -1, 2])
false
Base.allequal
— Functionallequal(itr) -> Bool
allequal(f, itr) -> Bool
Return true
if all values from itr
are equal when compared with isequal
. Or if all of [f(x) for x in itr]
are equal, for the second method.
Note that allequal(f, itr)
may call f
fewer than length(itr)
times. The precise number of calls is regarded as an implementation detail.
The allequal
function requires at least Julia 1.8.
The method allequal(f, itr)
requires at least Julia 1.11.
Examples
julia> allequal([])
true
julia> allequal([1])
true
julia> allequal([1, 1])
true
julia> allequal([1, 2])
false
julia> allequal(Dict(:a => 1, :b => 1))
false
julia> allequal(abs2, [1, -1])
true
Base.reduce
— Methodreduce(op, itr; [init])
Reduce the given collection itr
with the given binary operator op
. If provided, the initial value init
must be a neutral element for op
that will be returned for empty collections. It is unspecified whether init
is used for non-empty collections.
For empty collections, providing init
will be necessary, except for some special cases (e.g. when op
is one of +
, *
, max
, min
, &
, |
) when Julia can determine the neutral element of op
.
Reductions for certain commonly-used operators may have special implementations, and should be used instead: maximum
(itr)
, minimum
(itr)
, sum
(itr)
, prod
(itr)
, any
(itr)
, all
(itr)
. There are efficient methods for concatenating certain arrays of arrays by calling reduce(
vcat
, arr)
or reduce(
hcat
, arr)
.
The associativity of the reduction is implementation dependent. This means that you can't use non-associative operations like -
because it is undefined whether reduce(-,[1,2,3])
should be evaluated as (1-2)-3
or 1-(2-3)
. Use foldl
or foldr
instead for guaranteed left or right associativity.
Some operations accumulate error. Parallelism will be easier if the reduction can be executed in groups. Future versions of Julia might change the algorithm. Note that the elements are not reordered if you use an ordered collection.
Examples
julia> reduce(*, [2; 3; 4])
24
julia> reduce(*, Int[]; init=1)
1
Base.reduce
— Methodreduce(f, A::AbstractArray; dims=:, [init])
Reduce 2-argument function f
along dimensions of A
. dims
is a vector specifying the dimensions to reduce, and the keyword argument init
is the initial value to use in the reductions. For +
, *
, max
and min
the init
argument is optional.
The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop or consider using foldl
or foldr
. See documentation for reduce
.
Examples
julia> a = reshape(Vector(1:16), (4,4))
4×4 Matrix{Int64}:
1 5 9 13
2 6 10 14
3 7 11 15
4 8 12 16
julia> reduce(max, a, dims=2)
4×1 Matrix{Int64}:
13
14
15
16
julia> reduce(max, a, dims=1)
1×4 Matrix{Int64}:
4 8 12 16
Base.foldl
— Methodfoldl(op, itr; [init])
Like reduce
, but with guaranteed left associativity. If provided, the keyword argument init
will be used exactly once. In general, it will be necessary to provide init
to work with empty collections.
See also mapfoldl
, foldr
, accumulate
.
Examples
julia> foldl(=>, 1:4)
((1 => 2) => 3) => 4
julia> foldl(=>, 1:4; init=0)
(((0 => 1) => 2) => 3) => 4
julia> accumulate(=>, (1,2,3,4))
(1, 1 => 2, (1 => 2) => 3, ((1 => 2) => 3) => 4)
Base.foldr
— Methodfoldr(op, itr; [init])
Like reduce
, but with guaranteed right associativity. If provided, the keyword argument init
will be used exactly once. In general, it will be necessary to provide init
to work with empty collections.
Examples
julia> foldr(=>, 1:4)
1 => (2 => (3 => 4))
julia> foldr(=>, 1:4; init=0)
1 => (2 => (3 => (4 => 0)))
Base.maximum
— Functionmaximum(f, itr; [init])
Return the largest result of calling function f
on each element of itr
.
The value returned for empty itr
can be specified by init
. It must be a neutral element for max
(i.e. which is less than or equal to any other element) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
Examples
julia> maximum(length, ["Julion", "Julia", "Jule"])
6
julia> maximum(length, []; init=-1)
-1
julia> maximum(sin, Real[]; init=-1.0) # good, since output of sin is >= -1
-1.0
maximum(itr; [init])
Return the largest element in a collection.
The value returned for empty itr
can be specified by init
. It must be a neutral element for max
(i.e. which is less than or equal to any other element) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
Examples
julia> maximum(-20.5:10)
9.5
julia> maximum([1,2,3])
3
julia> maximum(())
ERROR: ArgumentError: reducing over an empty collection is not allowed; consider supplying `init` to the reducer
Stacktrace:
[...]
julia> maximum((); init=-Inf)
-Inf
maximum(A::AbstractArray; dims)
Compute the maximum value of an array over the given dimensions. See also the max(a,b)
function to take the maximum of two or more arguments, which can be applied elementwise to arrays via max.(a,b)
.
See also: maximum!
, extrema
, findmax
, argmax
.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> maximum(A, dims=1)
1×2 Matrix{Int64}:
3 4
julia> maximum(A, dims=2)
2×1 Matrix{Int64}:
2
4
maximum(f, A::AbstractArray; dims)
Compute the maximum value by calling the function f
on each element of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> maximum(abs2, A, dims=1)
1×2 Matrix{Int64}:
9 16
julia> maximum(abs2, A, dims=2)
2×1 Matrix{Int64}:
4
16
Base.maximum!
— Functionmaximum!(r, A)
Compute the maximum value of A
over the singleton dimensions of r
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> maximum!([1; 1], A)
2-element Vector{Int64}:
2
4
julia> maximum!([1 1], A)
1×2 Matrix{Int64}:
3 4
Base.minimum
— Functionminimum(f, itr; [init])
Return the smallest result of calling function f
on each element of itr
.
The value returned for empty itr
can be specified by init
. It must be a neutral element for min
(i.e. which is greater than or equal to any other element) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
Examples
julia> minimum(length, ["Julion", "Julia", "Jule"])
4
julia> minimum(length, []; init=typemax(Int64))
9223372036854775807
julia> minimum(sin, Real[]; init=1.0) # good, since output of sin is <= 1
1.0
minimum(itr; [init])
Return the smallest element in a collection.
The value returned for empty itr
can be specified by init
. It must be a neutral element for min
(i.e. which is greater than or equal to any other element) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
Examples
julia> minimum(-20.5:10)
-20.5
julia> minimum([1,2,3])
1
julia> minimum([])
ERROR: ArgumentError: reducing over an empty collection is not allowed; consider supplying `init` to the reducer
Stacktrace:
[...]
julia> minimum([]; init=Inf)
Inf
minimum(A::AbstractArray; dims)
Compute the minimum value of an array over the given dimensions. See also the min(a,b)
function to take the minimum of two or more arguments, which can be applied elementwise to arrays via min.(a,b)
.
See also: minimum!
, extrema
, findmin
, argmin
.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> minimum(A, dims=1)
1×2 Matrix{Int64}:
1 2
julia> minimum(A, dims=2)
2×1 Matrix{Int64}:
1
3
minimum(f, A::AbstractArray; dims)
Compute the minimum value by calling the function f
on each element of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> minimum(abs2, A, dims=1)
1×2 Matrix{Int64}:
1 4
julia> minimum(abs2, A, dims=2)
2×1 Matrix{Int64}:
1
9
Base.minimum!
— Functionminimum!(r, A)
Compute the minimum value of A
over the singleton dimensions of r
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> minimum!([1; 1], A)
2-element Vector{Int64}:
1
3
julia> minimum!([1 1], A)
1×2 Matrix{Int64}:
1 2
Base.extrema
— Functionextrema(itr; [init]) -> (mn, mx)
Compute both the minimum mn
and maximum mx
element in a single pass, and return them as a 2-tuple.
The value returned for empty itr
can be specified by init
. It must be a 2-tuple whose first and second elements are neutral elements for min
and max
respectively (i.e. which are greater/less than or equal to any other element). As a consequence, when itr
is empty the returned (mn, mx)
tuple will satisfy mn ≥ mx
. When init
is specified it may be used even for non-empty itr
.
Keyword argument init
requires Julia 1.8 or later.
Examples
julia> extrema(2:10)
(2, 10)
julia> extrema([9,pi,4.5])
(3.141592653589793, 9.0)
julia> extrema([]; init = (Inf, -Inf))
(Inf, -Inf)
extrema(f, itr; [init]) -> (mn, mx)
Compute both the minimum mn
and maximum mx
of f
applied to each element in itr
and return them as a 2-tuple. Only one pass is made over itr
.
The value returned for empty itr
can be specified by init
. It must be a 2-tuple whose first and second elements are neutral elements for min
and max
respectively (i.e. which are greater/less than or equal to any other element). It is used for non-empty collections. Note: it implies that, for empty itr
, the returned value (mn, mx)
satisfies mn ≥ mx
even though for non-empty itr
it satisfies mn ≤ mx
. This is a "paradoxical" but yet expected result.
This method requires Julia 1.2 or later.
Keyword argument init
requires Julia 1.8 or later.
Examples
julia> extrema(sin, 0:π)
(0.0, 0.9092974268256817)
julia> extrema(sin, Real[]; init = (1.0, -1.0)) # good, since -1 ≤ sin(::Real) ≤ 1
(1.0, -1.0)
extrema(A::AbstractArray; dims) -> Array{Tuple}
Compute the minimum and maximum elements of an array over the given dimensions.
See also: minimum
, maximum
, extrema!
.
Examples
julia> A = reshape(Vector(1:2:16), (2,2,2))
2×2×2 Array{Int64, 3}:
[:, :, 1] =
1 5
3 7
[:, :, 2] =
9 13
11 15
julia> extrema(A, dims = (1,2))
1×1×2 Array{Tuple{Int64, Int64}, 3}:
[:, :, 1] =
(1, 7)
[:, :, 2] =
(9, 15)
extrema(f, A::AbstractArray; dims) -> Array{Tuple}
Compute the minimum and maximum of f
applied to each element in the given dimensions of A
.
This method requires Julia 1.2 or later.
Base.extrema!
— Functionextrema!(r, A)
Compute the minimum and maximum value of A
over the singleton dimensions of r
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
This method requires Julia 1.8 or later.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> extrema!([(1, 1); (1, 1)], A)
2-element Vector{Tuple{Int64, Int64}}:
(1, 2)
(3, 4)
julia> extrema!([(1, 1);; (1, 1)], A)
1×2 Matrix{Tuple{Int64, Int64}}:
(1, 3) (2, 4)
Base.argmax
— Functionargmax(r::AbstractRange)
Ranges can have multiple maximal elements. In that case argmax
will return a maximal index, but not necessarily the first one.
argmax(f, domain)
Return a value x
from domain
for which f(x)
is maximised. If there are multiple maximal values for f(x)
then the first one will be found.
domain
must be a non-empty iterable.
Values are compared with isless
.
This method requires Julia 1.7 or later.
Examples
julia> argmax(abs, -10:5)
-10
julia> argmax(cos, 0:π/2:2π)
0.0
argmax(itr)
Return the index or key of the maximal element in a collection. If there are multiple maximal elements, then the first one will be returned.
The collection must not be empty.
Indices are of the same type as those returned by keys(itr)
and pairs(itr)
.
Values are compared with isless
.
Examples
julia> argmax([8, 0.1, -9, pi])
1
julia> argmax([1, 7, 7, 6])
2
julia> argmax([1, 7, 7, NaN])
4
argmax(A; dims) -> indices
For an array input, return the indices of the maximum elements over the given dimensions. NaN
is treated as greater than all other values except missing
.
Examples
julia> A = [1.0 2; 3 4]
2×2 Matrix{Float64}:
1.0 2.0
3.0 4.0
julia> argmax(A, dims=1)
1×2 Matrix{CartesianIndex{2}}:
CartesianIndex(2, 1) CartesianIndex(2, 2)
julia> argmax(A, dims=2)
2×1 Matrix{CartesianIndex{2}}:
CartesianIndex(1, 2)
CartesianIndex(2, 2)
Base.argmin
— Functionargmin(r::AbstractRange)
Ranges can have multiple minimal elements. In that case argmin
will return a minimal index, but not necessarily the first one.
argmin(f, domain)
Return a value x
from domain
for which f(x)
is minimised. If there are multiple minimal values for f(x)
then the first one will be found.
domain
must be a non-empty iterable.
NaN
is treated as less than all other values except missing
.
This method requires Julia 1.7 or later.
Examples
julia> argmin(sign, -10:5)
-10
julia> argmin(x -> -x^3 + x^2 - 10, -5:5)
5
julia> argmin(acos, 0:0.1:1)
1.0
argmin(itr)
Return the index or key of the minimal element in a collection. If there are multiple minimal elements, then the first one will be returned.
The collection must not be empty.
Indices are of the same type as those returned by keys(itr)
and pairs(itr)
.
NaN
is treated as less than all other values except missing
.
Examples
julia> argmin([8, 0.1, -9, pi])
3
julia> argmin([7, 1, 1, 6])
2
julia> argmin([7, 1, 1, NaN])
4
argmin(A; dims) -> indices
For an array input, return the indices of the minimum elements over the given dimensions. NaN
is treated as less than all other values except missing
.
Examples
julia> A = [1.0 2; 3 4]
2×2 Matrix{Float64}:
1.0 2.0
3.0 4.0
julia> argmin(A, dims=1)
1×2 Matrix{CartesianIndex{2}}:
CartesianIndex(1, 1) CartesianIndex(1, 2)
julia> argmin(A, dims=2)
2×1 Matrix{CartesianIndex{2}}:
CartesianIndex(1, 1)
CartesianIndex(2, 1)
Base.findmax
— Functionfindmax(f, domain) -> (f(x), index)
Return a pair of a value in the codomain (outputs of f
) and the index or key of the corresponding value in the domain
(inputs to f
) such that f(x)
is maximised. If there are multiple maximal points, then the first one will be returned.
domain
must be a non-empty iterable supporting keys
. Indices are of the same type as those returned by keys(domain)
.
Values are compared with isless
.
This method requires Julia 1.7 or later.
Examples
julia> findmax(identity, 5:9)
(9, 5)
julia> findmax(-, 1:10)
(-1, 1)
julia> findmax(first, [(1, :a), (3, :b), (3, :c)])
(3, 2)
julia> findmax(cos, 0:π/2:2π)
(1.0, 1)
findmax(itr) -> (x, index)
Return the maximal element of the collection itr
and its index or key. If there are multiple maximal elements, then the first one will be returned. Values are compared with isless
.
Indices are of the same type as those returned by keys(itr)
and pairs(itr)
.
See also: findmin
, argmax
, maximum
.
Examples
julia> findmax([8, 0.1, -9, pi])
(8.0, 1)
julia> findmax([1, 7, 7, 6])
(7, 2)
julia> findmax([1, 7, 7, NaN])
(NaN, 4)
findmax(A; dims) -> (maxval, index)
For an array input, returns the value and index of the maximum over the given dimensions. NaN
is treated as greater than all other values except missing
.
Examples
julia> A = [1.0 2; 3 4]
2×2 Matrix{Float64}:
1.0 2.0
3.0 4.0
julia> findmax(A, dims=1)
([3.0 4.0], CartesianIndex{2}[CartesianIndex(2, 1) CartesianIndex(2, 2)])
julia> findmax(A, dims=2)
([2.0; 4.0;;], CartesianIndex{2}[CartesianIndex(1, 2); CartesianIndex(2, 2);;])
findmax(f, A; dims) -> (f(x), index)
For an array input, returns the value in the codomain and index of the corresponding value which maximize f
over the given dimensions.
Examples
julia> A = [-1.0 1; -0.5 2]
2×2 Matrix{Float64}:
-1.0 1.0
-0.5 2.0
julia> findmax(abs2, A, dims=1)
([1.0 4.0], CartesianIndex{2}[CartesianIndex(1, 1) CartesianIndex(2, 2)])
julia> findmax(abs2, A, dims=2)
([1.0; 4.0;;], CartesianIndex{2}[CartesianIndex(1, 1); CartesianIndex(2, 2);;])
Base.findmin
— Functionfindmin(f, domain) -> (f(x), index)
Return a pair of a value in the codomain (outputs of f
) and the index or key of the corresponding value in the domain
(inputs to f
) such that f(x)
is minimised. If there are multiple minimal points, then the first one will be returned.
domain
must be a non-empty iterable.
Indices are of the same type as those returned by keys(domain)
and pairs(domain)
.
NaN
is treated as less than all other values except missing
.
This method requires Julia 1.7 or later.
Examples
julia> findmin(identity, 5:9)
(5, 1)
julia> findmin(-, 1:10)
(-10, 10)
julia> findmin(first, [(2, :a), (2, :b), (3, :c)])
(2, 1)
julia> findmin(cos, 0:π/2:2π)
(-1.0, 3)
findmin(itr) -> (x, index)
Return the minimal element of the collection itr
and its index or key. If there are multiple minimal elements, then the first one will be returned. NaN
is treated as less than all other values except missing
.
Indices are of the same type as those returned by keys(itr)
and pairs(itr)
.
See also: findmax
, argmin
, minimum
.
Examples
julia> findmin([8, 0.1, -9, pi])
(-9.0, 3)
julia> findmin([1, 7, 7, 6])
(1, 1)
julia> findmin([1, 7, 7, NaN])
(NaN, 4)
findmin(A; dims) -> (minval, index)
For an array input, returns the value and index of the minimum over the given dimensions. NaN
is treated as less than all other values except missing
.
Examples
julia> A = [1.0 2; 3 4]
2×2 Matrix{Float64}:
1.0 2.0
3.0 4.0
julia> findmin(A, dims=1)
([1.0 2.0], CartesianIndex{2}[CartesianIndex(1, 1) CartesianIndex(1, 2)])
julia> findmin(A, dims=2)
([1.0; 3.0;;], CartesianIndex{2}[CartesianIndex(1, 1); CartesianIndex(2, 1);;])
findmin(f, A; dims) -> (f(x), index)
For an array input, returns the value in the codomain and index of the corresponding value which minimize f
over the given dimensions.
Examples
julia> A = [-1.0 1; -0.5 2]
2×2 Matrix{Float64}:
-1.0 1.0
-0.5 2.0
julia> findmin(abs2, A, dims=1)
([0.25 1.0], CartesianIndex{2}[CartesianIndex(2, 1) CartesianIndex(1, 2)])
julia> findmin(abs2, A, dims=2)
([1.0; 0.25;;], CartesianIndex{2}[CartesianIndex(1, 1); CartesianIndex(2, 1);;])
Base.findmax!
— Functionfindmax!(rval, rind, A) -> (maxval, index)
Find the maximum of A
and the corresponding linear index along singleton dimensions of rval
and rind
, and store the results in rval
and rind
. NaN
is treated as greater than all other values except missing
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Base.findmin!
— Functionfindmin!(rval, rind, A) -> (minval, index)
Find the minimum of A
and the corresponding linear index along singleton dimensions of rval
and rind
, and store the results in rval
and rind
. NaN
is treated as less than all other values except missing
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Base.sum
— Functionsum(f, itr; [init])
Sum the results of calling function f
on each element of itr
.
The return type is Int
for signed integers of less than system word size, and UInt
for unsigned integers of less than system word size. For all other arguments, a common return type is found to which all arguments are promoted.
The value returned for empty itr
can be specified by init
. It must be the additive identity (i.e. zero) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
Examples
julia> sum(abs2, [2; 3; 4])
29
Note the important difference between sum(A)
and reduce(+, A)
for arrays with small integer eltype:
julia> sum(Int8[100, 28])
128
julia> reduce(+, Int8[100, 28])
-128
In the former case, the integers are widened to system word size and therefore the result is 128. In the latter case, no such widening happens and integer overflow results in -128.
sum(itr; [init])
Return the sum of all elements in a collection.
The return type is Int
for signed integers of less than system word size, and UInt
for unsigned integers of less than system word size. For all other arguments, a common return type is found to which all arguments are promoted.
The value returned for empty itr
can be specified by init
. It must be the additive identity (i.e. zero) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
See also: reduce
, mapreduce
, count
, union
.
Examples
julia> sum(1:20)
210
julia> sum(1:20; init = 0.0)
210.0
sum(A::AbstractArray; dims)
Sum elements of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> sum(A, dims=1)
1×2 Matrix{Int64}:
4 6
julia> sum(A, dims=2)
2×1 Matrix{Int64}:
3
7
sum(f, A::AbstractArray; dims)
Sum the results of calling function f
on each element of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> sum(abs2, A, dims=1)
1×2 Matrix{Int64}:
10 20
julia> sum(abs2, A, dims=2)
2×1 Matrix{Int64}:
5
25
Base.sum!
— Functionsum!(r, A)
Sum elements of A
over the singleton dimensions of r
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> sum!([1; 1], A)
2-element Vector{Int64}:
3
7
julia> sum!([1 1], A)
1×2 Matrix{Int64}:
4 6
Base.prod
— Functionprod(f, itr; [init])
Return the product of f
applied to each element of itr
.
The return type is Int
for signed integers of less than system word size, and UInt
for unsigned integers of less than system word size. For all other arguments, a common return type is found to which all arguments are promoted.
The value returned for empty itr
can be specified by init
. It must be the multiplicative identity (i.e. one) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
Examples
julia> prod(abs2, [2; 3; 4])
576
prod(itr; [init])
Return the product of all elements of a collection.
The return type is Int
for signed integers of less than system word size, and UInt
for unsigned integers of less than system word size. For all other arguments, a common return type is found to which all arguments are promoted.
The value returned for empty itr
can be specified by init
. It must be the multiplicative identity (i.e. one) as it is unspecified whether init
is used for non-empty collections.
Keyword argument init
requires Julia 1.6 or later.
See also: reduce
, cumprod
, any
.
Examples
julia> prod(1:5)
120
julia> prod(1:5; init = 1.0)
120.0
prod(A::AbstractArray; dims)
Multiply elements of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> prod(A, dims=1)
1×2 Matrix{Int64}:
3 8
julia> prod(A, dims=2)
2×1 Matrix{Int64}:
2
12
prod(f, A::AbstractArray; dims)
Multiply the results of calling the function f
on each element of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> prod(abs2, A, dims=1)
1×2 Matrix{Int64}:
9 64
julia> prod(abs2, A, dims=2)
2×1 Matrix{Int64}:
4
144
Base.prod!
— Functionprod!(r, A)
Multiply elements of A
over the singleton dimensions of r
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> prod!([1; 1], A)
2-element Vector{Int64}:
2
12
julia> prod!([1 1], A)
1×2 Matrix{Int64}:
3 8
Base.any
— Methodany(itr) -> Bool
Test whether any elements of a boolean collection are true
, returning true
as soon as the first true
value in itr
is encountered (short-circuiting). To short-circuit on false
, use all
.
If the input contains missing
values, return missing
if all non-missing values are false
(or equivalently, if the input contains no true
value), following three-valued logic.
See also: all
, count
, sum
, |
, ||
.
Examples
julia> a = [true,false,false,true]
4-element Vector{Bool}:
1
0
0
1
julia> any(a)
true
julia> any((println(i); v) for (i, v) in enumerate(a))
1
true
julia> any([missing, true])
true
julia> any([false, missing])
missing
Base.any
— Methodany(p, itr) -> Bool
Determine whether predicate p
returns true
for any elements of itr
, returning true
as soon as the first item in itr
for which p
returns true
is encountered (short-circuiting). To short-circuit on false
, use all
.
If the input contains missing
values, return missing
if all non-missing values are false
(or equivalently, if the input contains no true
value), following three-valued logic.
Examples
julia> any(i->(4<=i<=6), [3,5,7])
true
julia> any(i -> (println(i); i > 3), 1:10)
1
2
3
4
true
julia> any(i -> i > 0, [1, missing])
true
julia> any(i -> i > 0, [-1, missing])
missing
julia> any(i -> i > 0, [-1, 0])
false
Base.any!
— Functionany!(r, A)
Test whether any values in A
along the singleton dimensions of r
are true
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> A = [true false; true false]
2×2 Matrix{Bool}:
1 0
1 0
julia> any!([1; 1], A)
2-element Vector{Int64}:
1
1
julia> any!([1 1], A)
1×2 Matrix{Int64}:
1 0
Base.all
— Methodall(itr) -> Bool
Test whether all elements of a boolean collection are true
, returning false
as soon as the first false
value in itr
is encountered (short-circuiting). To short-circuit on true
, use any
.
If the input contains missing
values, return missing
if all non-missing values are true
(or equivalently, if the input contains no false
value), following three-valued logic.
See also: all!
, any
, count
, &
, &&
, allunique
.
Examples
julia> a = [true,false,false,true]
4-element Vector{Bool}:
1
0
0
1
julia> all(a)
false
julia> all((println(i); v) for (i, v) in enumerate(a))
1
2
false
julia> all([missing, false])
false
julia> all([true, missing])
missing
Base.all
— Methodall(p, itr) -> Bool
Determine whether predicate p
returns true
for all elements of itr
, returning false
as soon as the first item in itr
for which p
returns false
is encountered (short-circuiting). To short-circuit on true
, use any
.
If the input contains missing
values, return missing
if all non-missing values are true
(or equivalently, if the input contains no false
value), following three-valued logic.
Examples
julia> all(i->(4<=i<=6), [4,5,6])
true
julia> all(i -> (println(i); i < 3), 1:10)
1
2
3
false
julia> all(i -> i > 0, [1, missing])
missing
julia> all(i -> i > 0, [-1, missing])
false
julia> all(i -> i > 0, [1, 2])
true
Base.all!
— Functionall!(r, A)
Test whether all values in A
along the singleton dimensions of r
are true
, and write results to r
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> A = [true false; true false]
2×2 Matrix{Bool}:
1 0
1 0
julia> all!([1; 1], A)
2-element Vector{Int64}:
0
0
julia> all!([1 1], A)
1×2 Matrix{Int64}:
1 0
Base.count
— Functioncount([f=identity,] itr; init=0) -> Integer
Count the number of elements in itr
for which the function f
returns true
. If f
is omitted, count the number of true
elements in itr
(which should be a collection of boolean values). init
optionally specifies the value to start counting from and therefore also determines the output type.
init
keyword was added in Julia 1.6.
Examples
julia> count(i->(4<=i<=6), [2,3,4,5,6])
3
julia> count([true, false, true, true])
3
julia> count(>(3), 1:7, init=0x03)
0x07
count(
pattern::Union{AbstractChar,AbstractString,AbstractPattern},
string::AbstractString;
overlap::Bool = false,
)
Return the number of matches for pattern
in string
. This is equivalent to calling length(findall(pattern, string))
but more efficient.
If overlap=true
, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from disjoint character ranges.
This method requires at least Julia 1.3.
Using a character as the pattern requires at least Julia 1.7.
Examples
julia> count('a', "JuliaLang")
2
julia> count(r"a(.)a", "cabacabac", overlap=true)
3
julia> count(r"a(.)a", "cabacabac")
2
count([f=identity,] A::AbstractArray; dims=:)
Count the number of elements in A
for which f
returns true
over the given dimensions.
dims
keyword was added in Julia 1.5.
init
keyword was added in Julia 1.6.
Examples
julia> A = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> count(<=(2), A, dims=1)
1×2 Matrix{Int64}:
1 1
julia> count(<=(2), A, dims=2)
2×1 Matrix{Int64}:
2
0
Base.foreach
— Functionforeach(f, c...) -> Nothing
Call function f
on each element of iterable c
. For multiple iterable arguments, f
is called elementwise, and iteration stops when any iterator is finished.
foreach
should be used instead of map
when the results of f
are not needed, for example in foreach(println, array)
.
Examples
julia> tri = 1:3:7; res = Int[];
julia> foreach(x -> push!(res, x^2), tri)
julia> res
3-element Vector{Int64}:
1
16
49
julia> foreach((x, y) -> println(x, " with ", y), tri, 'a':'z')
1 with a
4 with b
7 with c
Base.map
— Functionmap(f, c...) -> collection
Transform collection c
by applying f
to each element. For multiple collection arguments, apply f
elementwise, and stop when any of them is exhausted.
The element type of the result is determined in the same manner as in collect
.
See also map!
, foreach
, mapreduce
, mapslices
, zip
, Iterators.map
.
Examples
julia> map(x -> x * 2, [1, 2, 3])
3-element Vector{Int64}:
2
4
6
julia> map(+, [1, 2, 3], [10, 20, 30, 400, 5000])
3-element Vector{Int64}:
11
22
33
map(f, A::AbstractArray...) -> N-array
When acting on multi-dimensional arrays of the same ndims
, they must all have the same axes
, and the answer will too.
See also broadcast
, which allows mismatched sizes.
Examples
julia> map(//, [1 2; 3 4], [4 3; 2 1])
2×2 Matrix{Rational{Int64}}:
1//4 2//3
3//2 4//1
julia> map(+, [1 2; 3 4], zeros(2,1))
ERROR: DimensionMismatch
julia> map(+, [1 2; 3 4], [1,10,100,1000], zeros(3,1)) # iterates until 3rd is exhausted
3-element Vector{Float64}:
2.0
13.0
102.0
Base.map!
— Functionmap!(function, destination, collection...)
Like map
, but stores the result in destination
rather than a new collection. destination
must be at least as large as the smallest collection.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
See also: map
, foreach
, zip
, copyto!
.
Examples
julia> a = zeros(3);
julia> map!(x -> x * 2, a, [1, 2, 3]);
julia> a
3-element Vector{Float64}:
2.0
4.0
6.0
julia> map!(+, zeros(Int, 5), 100:999, 1:3)
5-element Vector{Int64}:
101
103
105
0
0
map!(f, values(dict::AbstractDict))
Modifies dict
by transforming each value from val
to f(val)
. Note that the type of dict
cannot be changed: if f(val)
is not an instance of the value type of dict
then it will be converted to the value type if possible and otherwise raise an error.
map!(f, values(dict::AbstractDict))
requires Julia 1.2 or later.
Examples
julia> d = Dict(:a => 1, :b => 2)
Dict{Symbol, Int64} with 2 entries:
:a => 1
:b => 2
julia> map!(v -> v-1, values(d))
ValueIterator for a Dict{Symbol, Int64} with 2 entries. Values:
0
1
Base.mapreduce
— Methodmapreduce(f, op, itrs...; [init])
Apply function f
to each element(s) in itrs
, and then reduce the result using the binary function op
. If provided, init
must be a neutral element for op
that will be returned for empty collections. It is unspecified whether init
is used for non-empty collections. In general, it will be necessary to provide init
to work with empty collections.
mapreduce
is functionally equivalent to calling reduce(op, map(f, itr); init=init)
, but will in general execute faster since no intermediate collection needs to be created. See documentation for reduce
and map
.
mapreduce
with multiple iterators requires Julia 1.2 or later.
Examples
julia> mapreduce(x->x^2, +, [1:3;]) # == 1 + 4 + 9
14
The associativity of the reduction is implementation-dependent. Additionally, some implementations may reuse the return value of f
for elements that appear multiple times in itr
. Use mapfoldl
or mapfoldr
instead for guaranteed left or right associativity and invocation of f
for every value.
Base.mapfoldl
— Methodmapfoldl(f, op, itr; [init])
Like mapreduce
, but with guaranteed left associativity, as in foldl
. If provided, the keyword argument init
will be used exactly once. In general, it will be necessary to provide init
to work with empty collections.
Base.mapfoldr
— Methodmapfoldr(f, op, itr; [init])
Like mapreduce
, but with guaranteed right associativity, as in foldr
. If provided, the keyword argument init
will be used exactly once. In general, it will be necessary to provide init
to work with empty collections.
Base.first
— Functionfirst(coll)
Get the first element of an iterable collection. Return the start point of an AbstractRange
even if it is empty.
See also: only
, firstindex
, last
.
Examples
julia> first(2:2:10)
2
julia> first([1; 2; 3; 4])
1
first(itr, n::Integer)
Get the first n
elements of the iterable collection itr
, or fewer elements if itr
is not long enough.
See also: startswith
, Iterators.take
.
This method requires at least Julia 1.6.
Examples
julia> first(["foo", "bar", "qux"], 2)
2-element Vector{String}:
"foo"
"bar"
julia> first(1:6, 10)
1:6
julia> first(Bool[], 1)
Bool[]
first(s::AbstractString, n::Integer)
Get a string consisting of the first n
characters of s
.
Examples
julia> first("∀ϵ≠0: ϵ²>0", 0)
""
julia> first("∀ϵ≠0: ϵ²>0", 1)
"∀"
julia> first("∀ϵ≠0: ϵ²>0", 3)
"∀ϵ≠"
Base.last
— Functionlast(coll)
Get the last element of an ordered collection, if it can be computed in O(1) time. This is accomplished by calling lastindex
to get the last index. Return the end point of an AbstractRange
even if it is empty.
Examples
julia> last(1:2:10)
9
julia> last([1; 2; 3; 4])
4
last(itr, n::Integer)
Get the last n
elements of the iterable collection itr
, or fewer elements if itr
is not long enough.
This method requires at least Julia 1.6.
Examples
julia> last(["foo", "bar", "qux"], 2)
2-element Vector{String}:
"bar"
"qux"
julia> last(1:6, 10)
1:6
julia> last(Float64[], 1)
Float64[]
last(s::AbstractString, n::Integer)
Get a string consisting of the last n
characters of s
.
Examples
julia> last("∀ϵ≠0: ϵ²>0", 0)
""
julia> last("∀ϵ≠0: ϵ²>0", 1)
"0"
julia> last("∀ϵ≠0: ϵ²>0", 3)
"²>0"
Base.front
— Functionfront(x::Tuple)::Tuple
Return a Tuple
consisting of all but the last component of x
.
Examples
julia> Base.front((1,2,3))
(1, 2)
julia> Base.front(())
ERROR: ArgumentError: Cannot call front on an empty tuple.
Base.tail
— Functiontail(x::Tuple)::Tuple
Return a Tuple
consisting of all but the first component of x
.
See also: front
, rest
, first
, Iterators.peel
.
Examples
julia> Base.tail((1,2,3))
(2, 3)
julia> Base.tail(())
ERROR: ArgumentError: Cannot call tail on an empty tuple.
Base.step
— Functionstep(r)
Get the step size of an AbstractRange
object.
Examples
julia> step(1:10)
1
julia> step(1:2:10)
2
julia> step(2.5:0.3:10.9)
0.3
julia> step(range(2.5, stop=10.9, length=85))
0.1
Base.collect
— Methodcollect(iterator)
Return an Array
of all items in a collection or iterator. For dictionaries, returns a Vector
of key=>value
Pairs. If the argument is array-like or is an iterator with the HasShape
trait, the result will have the same shape and number of dimensions as the argument.
Used by comprehensions to turn a generator expression into an Array
. Thus, on generators, the square-brackets notation may be used instead of calling collect
, see second example.
The element type of the returned array is based on the types of the values collected. However, if the iterator is empty then the element type of the returned (empty) array is determined by type inference.
Examples
Collect items from a UnitRange{Int64}
collection:
julia> collect(1:3)
3-element Vector{Int64}:
1
2
3
Collect items from a generator (same output as [x^2 for x in 1:3]
):
julia> collect(x^2 for x in 1:3)
3-element Vector{Int64}:
1
4
9
Collecting an empty iterator where the result type depends on type inference:
julia> [rand(Bool) ? 1 : missing for _ in []]
Union{Missing, Int64}[]
When the iterator is non-empty, the result type depends only on values:
julia> [rand(Bool) ? 1 : missing for _ in [""]]
1-element Vector{Int64}:
1
Base.collect
— Methodcollect(element_type, collection)
Return an Array
with the given element type of all items in a collection or iterable. The result has the same shape and number of dimensions as collection
.
Examples
julia> collect(Float64, 1:2:5)
3-element Vector{Float64}:
1.0
3.0
5.0
Base.filter
— Functionfilter(f, a)
Return a copy of collection a
, removing elements for which f
is false
. The function f
is passed one argument.
Support for a
as a tuple requires at least Julia 1.4.
See also: filter!
, Iterators.filter
.
Examples
julia> a = 1:10
1:10
julia> filter(isodd, a)
5-element Vector{Int64}:
1
3
5
7
9
filter(f)
Create a function that filters its arguments with function f
using filter
, i.e. a function equivalent to x -> filter(f, x)
.
The returned function is of type Base.Fix1{typeof(filter)}
, which can be used to implement specialized methods.
Examples
julia> (1, 2, Inf, 4, NaN, 6) |> filter(isfinite)
(1, 2, 4, 6)
julia> map(filter(iseven), [1:3, 2:4, 3:5])
3-element Vector{Vector{Int64}}:
[2]
[2, 4]
[4]
This method requires at least Julia 1.9.
filter(f, d::AbstractDict)
Return a copy of d
, removing elements for which f
is false
. The function f
is passed key=>value
pairs.
Examples
julia> d = Dict(1=>"a", 2=>"b")
Dict{Int64, String} with 2 entries:
2 => "b"
1 => "a"
julia> filter(p->isodd(p.first), d)
Dict{Int64, String} with 1 entry:
1 => "a"
filter(f, itr::SkipMissing{<:AbstractArray})
Return a vector similar to the array wrapped by the given SkipMissing
iterator but with all missing elements and those for which f
returns false
removed.
This method requires Julia 1.2 or later.
Examples
julia> x = [1 2; missing 4]
2×2 Matrix{Union{Missing, Int64}}:
1 2
missing 4
julia> filter(isodd, skipmissing(x))
1-element Vector{Int64}:
1
Base.filter!
— Functionfilter!(f, a)
Update collection a
, removing elements for which f
is false
. The function f
is passed one argument.
Examples
julia> filter!(isodd, Vector(1:10))
5-element Vector{Int64}:
1
3
5
7
9
filter!(f, d::AbstractDict)
Update d
, removing elements for which f
is false
. The function f
is passed key=>value
pairs.
Examples
julia> d = Dict(1=>"a", 2=>"b", 3=>"c")
Dict{Int64, String} with 3 entries:
2 => "b"
3 => "c"
1 => "a"
julia> filter!(p->isodd(p.first), d)
Dict{Int64, String} with 2 entries:
3 => "c"
1 => "a"
Base.replace
— Methodreplace(A, old_new::Pair...; [count::Integer])
Return a copy of collection A
where, for each pair old=>new
in old_new
, all occurrences of old
are replaced by new
. Equality is determined using isequal
. If count
is specified, then replace at most count
occurrences in total.
The element type of the result is chosen using promotion (see promote_type
) based on the element type of A
and on the types of the new
values in pairs. If count
is omitted and the element type of A
is a Union
, the element type of the result will not include singleton types which are replaced with values of a different type: for example, Union{T,Missing}
will become T
if missing
is replaced.
See also replace!
, splice!
, delete!
, insert!
.
Version 1.7 is required to replace elements of a Tuple
.
Examples
julia> replace([1, 2, 1, 3], 1=>0, 2=>4, count=2)
4-element Vector{Int64}:
0
4
1
3
julia> replace([1, missing], missing=>0)
2-element Vector{Int64}:
1
0
Base.replace
— Methodreplace(new::Union{Function, Type}, A; [count::Integer])
Return a copy of A
where each value x
in A
is replaced by new(x)
. If count
is specified, then replace at most count
values in total (replacements being defined as new(x) !== x
).
Version 1.7 is required to replace elements of a Tuple
.
Examples
julia> replace(x -> isodd(x) ? 2x : x, [1, 2, 3, 4])
4-element Vector{Int64}:
2
2
6
4
julia> replace(Dict(1=>2, 3=>4)) do kv
first(kv) < 3 ? first(kv)=>3 : kv
end
Dict{Int64, Int64} with 2 entries:
3 => 4
1 => 3
Base.replace!
— Functionreplace!(A, old_new::Pair...; [count::Integer])
For each pair old=>new
in old_new
, replace all occurrences of old
in collection A
by new
. Equality is determined using isequal
. If count
is specified, then replace at most count
occurrences in total. See also replace
.
Examples
julia> replace!([1, 2, 1, 3], 1=>0, 2=>4, count=2)
4-element Vector{Int64}:
0
4
1
3
julia> replace!(Set([1, 2, 3]), 1=>0)
Set{Int64} with 3 elements:
0
2
3
replace!(new::Union{Function, Type}, A; [count::Integer])
Replace each element x
in collection A
by new(x)
. If count
is specified, then replace at most count
values in total (replacements being defined as new(x) !== x
).
Examples
julia> replace!(x -> isodd(x) ? 2x : x, [1, 2, 3, 4])
4-element Vector{Int64}:
2
2
6
4
julia> replace!(Dict(1=>2, 3=>4)) do kv
first(kv) < 3 ? first(kv)=>3 : kv
end
Dict{Int64, Int64} with 2 entries:
3 => 4
1 => 3
julia> replace!(x->2x, Set([3, 6]))
Set{Int64} with 2 elements:
6
12
Base.rest
— FunctionBase.rest(collection[, itr_state])
Generic function for taking the tail of collection
, starting from a specific iteration state itr_state
. Return a Tuple
, if collection
itself is a Tuple
, a subtype of AbstractVector
, if collection
is an AbstractArray
, a subtype of AbstractString
if collection
is an AbstractString
, and an arbitrary iterator, falling back to Iterators.rest(collection[, itr_state])
, otherwise.
Can be overloaded for user-defined collection types to customize the behavior of slurping in assignments in final position, like a, b... = collection
.
Base.rest
requires at least Julia 1.6.
See also: first
, Iterators.rest
, Base.split_rest
.
Examples
julia> a = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> first, state = iterate(a)
(1, 2)
julia> first, Base.rest(a, state)
(1, [3, 2, 4])
Base.split_rest
— FunctionBase.split_rest(collection, n::Int[, itr_state]) -> (rest_but_n, last_n)
Generic function for splitting the tail of collection
, starting from a specific iteration state itr_state
. Returns a tuple of two new collections. The first one contains all elements of the tail but the n
last ones, which make up the second collection.
The type of the first collection generally follows that of Base.rest
, except that the fallback case is not lazy, but is collected eagerly into a vector.
Can be overloaded for user-defined collection types to customize the behavior of slurping in assignments in non-final position, like a, b..., c = collection
.
Base.split_rest
requires at least Julia 1.9.
See also: Base.rest
.
Examples
julia> a = [1 2; 3 4]
2×2 Matrix{Int64}:
1 2
3 4
julia> first, state = iterate(a)
(1, 2)
julia> first, Base.split_rest(a, 1, state)
(1, ([3, 2], [4]))
Indexable Collections
Base.getindex
— Functiongetindex(collection, key...)
Retrieve the value(s) stored at the given key or index within a collection. The syntax a[i,j,...]
is converted by the compiler to getindex(a, i, j, ...)
.
See also get
, keys
, eachindex
.
Examples
julia> A = Dict("a" => 1, "b" => 2)
Dict{String, Int64} with 2 entries:
"b" => 2
"a" => 1
julia> getindex(A, "a")
1
Base.setindex!
— Functionsetindex!(collection, value, key...)
Store the given value at the given key or index within a collection. The syntax a[i,j,...] = x
is converted by the compiler to (setindex!(a, x, i, j, ...); x)
.
Examples
julia> a = Dict("a"=>1)
Dict{String, Int64} with 1 entry:
"a" => 1
julia> setindex!(a, 2, "b")
Dict{String, Int64} with 2 entries:
"b" => 2
"a" => 1
Base.firstindex
— Functionfirstindex(collection) -> Integer
firstindex(collection, d) -> Integer
Return the first index of collection
. If d
is given, return the first index of collection
along dimension d
.
The syntaxes A[begin]
and A[1, begin]
lower to A[firstindex(A)]
and A[1, firstindex(A, 2)]
, respectively.
See also: first
, axes
, lastindex
, nextind
.
Examples
julia> firstindex([1,2,4])
1
julia> firstindex(rand(3,4,5), 2)
1
Base.lastindex
— Functionlastindex(collection) -> Integer
lastindex(collection, d) -> Integer
Return the last index of collection
. If d
is given, return the last index of collection
along dimension d
.
The syntaxes A[end]
and A[end, end]
lower to A[lastindex(A)]
and A[lastindex(A, 1), lastindex(A, 2)]
, respectively.
See also: axes
, firstindex
, eachindex
, prevind
.
Examples
julia> lastindex([1,2,4])
3
julia> lastindex(rand(3,4,5), 2)
4
Fully implemented by:
Array
BitArray
AbstractArray
SubArray
Partially implemented by:
Dictionaries
Dict
is the standard dictionary. Its implementation uses hash
as the hashing function for the key, and isequal
to determine equality. Define these two functions for custom types to override how they are stored in a hash table.
IdDict
is a special hash table where the keys are always object identities.
WeakKeyDict
is a hash table implementation where the keys are weak references to objects, and thus may be garbage collected even when referenced in a hash table. Like Dict
it uses hash
for hashing and isequal
for equality, unlike Dict
it does not convert keys on insertion.
Dict
s can be created by passing pair objects constructed with =>
to a Dict
constructor: Dict("A"=>1, "B"=>2)
. This call will attempt to infer type information from the keys and values (i.e. this example creates a Dict{String, Int64}
). To explicitly specify types use the syntax Dict{KeyType,ValueType}(...)
. For example, Dict{String,Int32}("A"=>1, "B"=>2)
.
Dictionaries may also be created with generators. For example, Dict(i => f(i) for i = 1:10)
.
Given a dictionary D
, the syntax D[x]
returns the value of key x
(if it exists) or throws an error, and D[x] = y
stores the key-value pair x => y
in D
(replacing any existing value for the key x
). Multiple arguments to D[...]
are converted to tuples; for example, the syntax D[x,y]
is equivalent to D[(x,y)]
, i.e. it refers to the value keyed by the tuple (x,y)
.
Base.AbstractDict
— TypeAbstractDict{K, V}
Supertype for dictionary-like types with keys of type K
and values of type V
. Dict
, IdDict
and other types are subtypes of this. An AbstractDict{K, V}
should be an iterator of Pair{K, V}
.
Base.Dict
— TypeDict([itr])
Dict{K,V}()
constructs a hash table with keys of type K
and values of type V
. Keys are compared with isequal
and hashed with hash
.
Given a single iterable argument, constructs a Dict
whose key-value pairs are taken from 2-tuples (key,value)
generated by the argument.
Examples
julia> Dict([("A", 1), ("B", 2)])
Dict{String, Int64} with 2 entries:
"B" => 2
"A" => 1
Alternatively, a sequence of pair arguments may be passed.
julia> Dict("A"=>1, "B"=>2)
Dict{String, Int64} with 2 entries:
"B" => 2
"A" => 1
Keys are allowed to be mutable, but if you do mutate stored keys, the hash table may become internally inconsistent, in which case the Dict
will not work properly. IdDict
can be an alternative if you need to mutate keys.
Base.IdDict
— TypeIdDict([itr])
IdDict{K,V}()
constructs a hash table using objectid
as hash and ===
as equality with keys of type K
and values of type V
. See Dict
for further help and IdSet
for the set version of this.
In the example below, the Dict
keys are all isequal
and therefore get hashed the same, so they get overwritten. The IdDict
hashes by object-id, and thus preserves the 3 different keys.
Examples
julia> Dict(true => "yes", 1 => "no", 1.0 => "maybe")
Dict{Real, String} with 1 entry:
1.0 => "maybe"
julia> IdDict(true => "yes", 1 => "no", 1.0 => "maybe")
IdDict{Any, String} with 3 entries:
true => "yes"
1.0 => "maybe"
1 => "no"
Base.WeakKeyDict
— TypeWeakKeyDict([itr])
WeakKeyDict()
constructs a hash table where the keys are weak references to objects which may be garbage collected even when referenced in a hash table.
See Dict
for further help. Note, unlike Dict
, WeakKeyDict
does not convert keys on insertion, as this would imply the key object was unreferenced anywhere before insertion.
See also WeakRef
.
Base.ImmutableDict
— TypeImmutableDict
ImmutableDict
is a dictionary implemented as an immutable linked list, which is optimal for small dictionaries that are constructed over many individual insertions. Note that it is not possible to remove a value, although it can be partially overridden and hidden by inserting a new value with the same key.
ImmutableDict(KV::Pair)
Create a new entry in the ImmutableDict
for a key => value
pair
- use
(key => value) in dict
to see if this particular combination is in the properties set - use
get(dict, key, default)
to retrieve the most recent value for a particular key
Base.PersistentDict
— TypePersistentDict
PersistentDict
is a dictionary implemented as an hash array mapped trie, which is optimal for situations where you need persistence, each operation returns a new dictionary separate from the previous one, but the underlying implementation is space-efficient and may share storage across multiple separate dictionaries.
It behaves like an IdDict.
PersistentDict(KV::Pair)
Examples
julia> dict = Base.PersistentDict(:a=>1)
Base.PersistentDict{Symbol, Int64} with 1 entry:
:a => 1
julia> dict2 = Base.delete(dict, :a)
Base.PersistentDict{Symbol, Int64}()
julia> dict3 = Base.PersistentDict(dict, :a=>2)
Base.PersistentDict{Symbol, Int64} with 1 entry:
:a => 2
Base.haskey
— Functionhaskey(collection, key) -> Bool
Determine whether a collection has a mapping for a given key
.
Examples
julia> D = Dict('a'=>2, 'b'=>3)
Dict{Char, Int64} with 2 entries:
'a' => 2
'b' => 3
julia> haskey(D, 'a')
true
julia> haskey(D, 'c')
false
Base.get
— Functionget(collection, key, default)
Return the value stored for the given key, or the given default value if no mapping for the key is present.
For tuples and numbers, this function requires at least Julia 1.7.
Examples
julia> d = Dict("a"=>1, "b"=>2);
julia> get(d, "a", 3)
1
julia> get(d, "c", 3)
3
get(f::Union{Function, Type}, collection, key)
Return the value stored for the given key, or if no mapping for the key is present, return f()
. Use get!
to also store the default value in the dictionary.
This is intended to be called using do
block syntax
get(dict, key) do
# default value calculated here
time()
end
Base.get!
— Functionget!(collection, key, default)
Return the value stored for the given key, or if no mapping for the key is present, store key => default
, and return default
.
Examples
julia> d = Dict("a"=>1, "b"=>2, "c"=>3);
julia> get!(d, "a", 5)
1
julia> get!(d, "d", 4)
4
julia> d
Dict{String, Int64} with 4 entries:
"c" => 3
"b" => 2
"a" => 1
"d" => 4
get!(f::Union{Function, Type}, collection, key)
Return the value stored for the given key, or if no mapping for the key is present, store key => f()
, and return f()
.
This is intended to be called using do
block syntax.
Examples
julia> squares = Dict{Int, Int}();
julia> function get_square!(d, i)
get!(d, i) do
i^2
end
end
get_square! (generic function with 1 method)
julia> get_square!(squares, 2)
4
julia> squares
Dict{Int64, Int64} with 1 entry:
2 => 4
Base.getkey
— Functiongetkey(collection, key, default)
Return the key matching argument key
if one exists in collection
, otherwise return default
.
Examples
julia> D = Dict('a'=>2, 'b'=>3)
Dict{Char, Int64} with 2 entries:
'a' => 2
'b' => 3
julia> getkey(D, 'a', 1)
'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
julia> getkey(D, 'd', 'a')
'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
Base.delete!
— Functiondelete!(collection, key)
Delete the mapping for the given key in a collection, if any, and return the collection.
Examples
julia> d = Dict("a"=>1, "b"=>2)
Dict{String, Int64} with 2 entries:
"b" => 2
"a" => 1
julia> delete!(d, "b")
Dict{String, Int64} with 1 entry:
"a" => 1
julia> delete!(d, "b") # d is left unchanged
Dict{String, Int64} with 1 entry:
"a" => 1
Base.pop!
— Methodpop!(collection, key[, default])
Delete and return the mapping for key
if it exists in collection
, otherwise return default
, or throw an error if default
is not specified.
Examples
julia> d = Dict("a"=>1, "b"=>2, "c"=>3);
julia> pop!(d, "a")
1
julia> pop!(d, "d")
ERROR: KeyError: key "d" not found
Stacktrace:
[...]
julia> pop!(d, "e", 4)
4
Base.keys
— Functionkeys(iterator)
For an iterator or collection that has keys and values (e.g. arrays and dictionaries), return an iterator over the keys.
Base.values
— Functionvalues(iterator)
For an iterator or collection that has keys and values, return an iterator over the values. This function simply returns its argument by default, since the elements of a general iterator are normally considered its "values".
Examples
julia> d = Dict("a"=>1, "b"=>2);
julia> values(d)
ValueIterator for a Dict{String, Int64} with 2 entries. Values:
2
1
julia> values([2])
1-element Vector{Int64}:
2
values(a::AbstractDict)
Return an iterator over all values in a collection. collect(values(a))
returns an array of values. When the values are stored internally in a hash table, as is the case for Dict
, the order in which they are returned may vary. But keys(a)
and values(a)
both iterate a
and return the elements in the same order.
Examples
julia> D = Dict('a'=>2, 'b'=>3)
Dict{Char, Int64} with 2 entries:
'a' => 2
'b' => 3
julia> collect(values(D))
2-element Vector{Int64}:
2
3
Base.pairs
— Functionpairs(IndexLinear(), A)
pairs(IndexCartesian(), A)
pairs(IndexStyle(A), A)
An iterator that accesses each element of the array A
, returning i => x
, where i
is the index for the element and x = A[i]
. Identical to pairs(A)
, except that the style of index can be selected. Also similar to enumerate(A)
, except i
will be a valid index for A
, while enumerate
always counts from 1 regardless of the indices of A
.
Specifying IndexLinear()
ensures that i
will be an integer; specifying IndexCartesian()
ensures that i
will be a Base.CartesianIndex
; specifying IndexStyle(A)
chooses whichever has been defined as the native indexing style for array A
.
Mutation of the bounds of the underlying array will invalidate this iterator.
Examples
julia> A = ["a" "d"; "b" "e"; "c" "f"];
julia> for (index, value) in pairs(IndexStyle(A), A)
println("$index $value")
end
1 a
2 b
3 c
4 d
5 e
6 f
julia> S = view(A, 1:2, :);
julia> for (index, value) in pairs(IndexStyle(S), S)
println("$index $value")
end
CartesianIndex(1, 1) a
CartesianIndex(2, 1) b
CartesianIndex(1, 2) d
CartesianIndex(2, 2) e
See also IndexStyle
, axes
.
pairs(collection)
Return an iterator over key => value
pairs for any collection that maps a set of keys to a set of values. This includes arrays, where the keys are the array indices.
Examples
julia> a = Dict(zip(["a", "b", "c"], [1, 2, 3]))
Dict{String, Int64} with 3 entries:
"c" => 3
"b" => 2
"a" => 1
julia> pairs(a)
Dict{String, Int64} with 3 entries:
"c" => 3
"b" => 2
"a" => 1
julia> foreach(println, pairs(["a", "b", "c"]))
1 => "a"
2 => "b"
3 => "c"
julia> (;a=1, b=2, c=3) |> pairs |> collect
3-element Vector{Pair{Symbol, Int64}}:
:a => 1
:b => 2
:c => 3
julia> (;a=1, b=2, c=3) |> collect
3-element Vector{Int64}:
1
2
3
Base.merge
— Functionmerge(initial::Face, others::Face...)
Merge the properties of the initial
face and others
, with later faces taking priority.
merge(d::AbstractDict, others::AbstractDict...)
Construct a merged collection from the given collections. If necessary, the types of the resulting collection will be promoted to accommodate the types of the merged collections. If the same key is present in another collection, the value for that key will be the value it has in the last collection listed. See also mergewith
for custom handling of values with the same key.
Examples
julia> a = Dict("foo" => 0.0, "bar" => 42.0)
Dict{String, Float64} with 2 entries:
"bar" => 42.0
"foo" => 0.0
julia> b = Dict("baz" => 17, "bar" => 4711)
Dict{String, Int64} with 2 entries:
"bar" => 4711
"baz" => 17
julia> merge(a, b)
Dict{String, Float64} with 3 entries:
"bar" => 4711.0
"baz" => 17.0
"foo" => 0.0
julia> merge(b, a)
Dict{String, Float64} with 3 entries:
"bar" => 42.0
"baz" => 17.0
"foo" => 0.0
merge(a::NamedTuple, bs::NamedTuple...)
Construct a new named tuple by merging two or more existing ones, in a left-associative manner. Merging proceeds left-to-right, between pairs of named tuples, and so the order of fields present in both the leftmost and rightmost named tuples take the same position as they are found in the leftmost named tuple. However, values are taken from matching fields in the rightmost named tuple that contains that field. Fields present in only the rightmost named tuple of a pair are appended at the end. A fallback is implemented for when only a single named tuple is supplied, with signature merge(a::NamedTuple)
.
Merging 3 or more NamedTuple
requires at least Julia 1.1.
Examples
julia> merge((a=1, b=2, c=3), (b=4, d=5))
(a = 1, b = 4, c = 3, d = 5)
julia> merge((a=1, b=2), (b=3, c=(d=1,)), (c=(d=2,),))
(a = 1, b = 3, c = (d = 2,))
merge(a::NamedTuple, iterable)
Interpret an iterable of key-value pairs as a named tuple, and perform a merge.
julia> merge((a=1, b=2, c=3), [:b=>4, :d=>5])
(a = 1, b = 4, c = 3, d = 5)
Base.mergewith
— Functionmergewith(combine, d::AbstractDict, others::AbstractDict...)
mergewith(combine)
merge(combine, d::AbstractDict, others::AbstractDict...)
Construct a merged collection from the given collections. If necessary, the types of the resulting collection will be promoted to accommodate the types of the merged collections. Values with the same key will be combined using the combiner function. The curried form mergewith(combine)
returns the function (args...) -> mergewith(combine, args...)
.
Method merge(combine::Union{Function,Type}, args...)
as an alias of mergewith(combine, args...)
is still available for backward compatibility.
mergewith
requires Julia 1.5 or later.
Examples
julia> a = Dict("foo" => 0.0, "bar" => 42.0)
Dict{String, Float64} with 2 entries:
"bar" => 42.0
"foo" => 0.0
julia> b = Dict("baz" => 17, "bar" => 4711)
Dict{String, Int64} with 2 entries:
"bar" => 4711
"baz" => 17
julia> mergewith(+, a, b)
Dict{String, Float64} with 3 entries:
"bar" => 4753.0
"baz" => 17.0
"foo" => 0.0
julia> ans == mergewith(+)(a, b)
true
Base.merge!
— Functionmerge!(d::AbstractDict, others::AbstractDict...)
Update collection with pairs from the other collections. See also merge
.
Examples
julia> d1 = Dict(1 => 2, 3 => 4);
julia> d2 = Dict(1 => 4, 4 => 5);
julia> merge!(d1, d2);
julia> d1
Dict{Int64, Int64} with 3 entries:
4 => 5
3 => 4
1 => 4
Base.mergewith!
— Functionmergewith!(combine, d::AbstractDict, others::AbstractDict...) -> d
mergewith!(combine)
merge!(combine, d::AbstractDict, others::AbstractDict...) -> d
Update collection with pairs from the other collections. Values with the same key will be combined using the combiner function. The curried form mergewith!(combine)
returns the function (args...) -> mergewith!(combine, args...)
.
Method merge!(combine::Union{Function,Type}, args...)
as an alias of mergewith!(combine, args...)
is still available for backward compatibility.
mergewith!
requires Julia 1.5 or later.
Examples
julia> d1 = Dict(1 => 2, 3 => 4);
julia> d2 = Dict(1 => 4, 4 => 5);
julia> mergewith!(+, d1, d2);
julia> d1
Dict{Int64, Int64} with 3 entries:
4 => 5
3 => 4
1 => 6
julia> mergewith!(-, d1, d1);
julia> d1
Dict{Int64, Int64} with 3 entries:
4 => 0
3 => 0
1 => 0
julia> foldl(mergewith!(+), [d1, d2]; init=Dict{Int64, Int64}())
Dict{Int64, Int64} with 3 entries:
4 => 5
3 => 0
1 => 4
Base.sizehint!
— Functionsizehint!(s, n; first::Bool=false, shrink::Bool=true) -> s
Suggest that collection s
reserve capacity for at least n
elements. That is, if you expect that you're going to have to push a lot of values onto s
, you can avoid the cost of incremental reallocation by doing it once up front; this can improve performance.
If first
is true
, then any additional space is reserved before the start of the collection. This way, subsequent calls to pushfirst!
(instead of push!
) may become faster. Supplying this keyword may result in an error if the collection is not ordered or if pushfirst!
is not supported for this collection.
If shrink=true
(the default), the collection's capacity may be reduced if its current capacity is greater than n
.
See also resize!
.
Notes on the performance model
For types that support sizehint!
,
push!
andappend!
methods generally may (but are not required to) preallocate extra storage. For types implemented inBase
, they typically do, using a heuristic optimized for a general use case.sizehint!
may control this preallocation. Again, it typically does this for types inBase
.empty!
is nearly costless (and O(1)) for types that support this kind of preallocation.
The shrink
and first
arguments were added in Julia 1.11.
Base.keytype
— Functionkeytype(T::Type{<:AbstractArray})
keytype(A::AbstractArray)
Return the key type of an array. This is equal to the eltype
of the result of keys(...)
, and is provided mainly for compatibility with the dictionary interface.
Examples
julia> keytype([1, 2, 3]) == Int
true
julia> keytype([1 2; 3 4])
CartesianIndex{2}
For arrays, this function requires at least Julia 1.2.
keytype(type)
Get the key type of a dictionary type. Behaves similarly to eltype
.
Examples
julia> keytype(Dict(Int32(1) => "foo"))
Int32
Base.valtype
— Functionvaltype(T::Type{<:AbstractArray})
valtype(A::AbstractArray)
Return the value type of an array. This is identical to eltype
and is provided mainly for compatibility with the dictionary interface.
Examples
julia> valtype(["one", "two", "three"])
String
For arrays, this function requires at least Julia 1.2.
valtype(type)
Get the value type of a dictionary type. Behaves similarly to eltype
.
Examples
julia> valtype(Dict(Int32(1) => "foo"))
String
Fully implemented by:
Partially implemented by:
Set-Like Collections
Base.AbstractSet
— TypeAbstractSet{T}
Supertype for set-like types whose elements are of type T
. Set
, BitSet
and other types are subtypes of this.
Base.Set
— TypeSet{T} <: AbstractSet{T}
Set
s are mutable containers that provide fast membership testing.
Set
s have efficient implementations of set operations such as in
, union
and intersect
. Elements in a Set
are unique, as determined by the elements' definition of isequal
. The order of elements in a Set
is an implementation detail and cannot be relied on.
See also: AbstractSet
, BitSet
, Dict
, push!
, empty!
, union!
, in
, isequal
Examples
julia> s = Set("aaBca")
Set{Char} with 3 elements:
'a'
'c'
'B'
julia> push!(s, 'b')
Set{Char} with 4 elements:
'a'
'b'
'B'
'c'
julia> s = Set([NaN, 0.0, 1.0, 2.0]);
julia> -0.0 in s # isequal(0.0, -0.0) is false
false
julia> NaN in s # isequal(NaN, NaN) is true
true
Base.BitSet
— TypeBitSet([itr])
Construct a sorted set of Int
s generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. If the set will be sparse (for example, holding a few very large integers), use Set
instead.
Base.IdSet
— TypeIdSet{T}([itr])
IdSet()
IdSet{T}() constructs a set (see Set
) using ===
as equality with values of type T
.
In the example below, the values are all isequal
so they get overwritten in the ordinary Set
. The IdSet
compares by ===
and so preserves the 3 different values.
Examples
julia> Set(Any[true, 1, 1.0])
Set{Any} with 1 element:
1.0
julia> IdSet{Any}(Any[true, 1, 1.0])
IdSet{Any} with 3 elements:
1.0
1
true
Base.union
— Functionunion(s, itrs...)
∪(s, itrs...)
Construct an object containing all distinct elements from all of the arguments.
The first argument controls what kind of container is returned. If this is an array, it maintains the order in which elements first appear.
Unicode ∪
can be typed by writing \cup
then pressing tab in the Julia REPL, and in many editors. This is an infix operator, allowing s ∪ itr
.
See also unique
, intersect
, isdisjoint
, vcat
, Iterators.flatten
.
Examples
julia> union([1, 2], [3])
3-element Vector{Int64}:
1
2
3
julia> union([4 2 3 4 4], 1:3, 3.0)
4-element Vector{Float64}:
4.0
2.0
3.0
1.0
julia> (0, 0.0) ∪ (-0.0, NaN)
3-element Vector{Real}:
0
-0.0
NaN
julia> union(Set([1, 2]), 2:3)
Set{Int64} with 3 elements:
2
3
1
Base.union!
— Functionunion!(s::Union{AbstractSet,AbstractVector}, itrs...)
Construct the union
of passed in sets and overwrite s
with the result. Maintain order with arrays.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> a = Set([3, 4, 5]);
julia> union!(a, 1:2:7);
julia> a
Set{Int64} with 5 elements:
5
4
7
3
1
Base.intersect
— Functionintersect(s, itrs...)
∩(s, itrs...)
Construct the set containing those elements which appear in all of the arguments.
The first argument controls what kind of container is returned. If this is an array, it maintains the order in which elements first appear.
Unicode ∩
can be typed by writing \cap
then pressing tab in the Julia REPL, and in many editors. This is an infix operator, allowing s ∩ itr
.
See also setdiff
, isdisjoint
, issubset
, issetequal
.
As of Julia 1.8 intersect returns a result with the eltype of the type-promoted eltypes of the two inputs
Examples
julia> intersect([1, 2, 3], [3, 4, 5])
1-element Vector{Int64}:
3
julia> intersect([1, 4, 4, 5, 6], [6, 4, 6, 7, 8])
2-element Vector{Int64}:
4
6
julia> intersect(1:16, 7:99)
7:16
julia> (0, 0.0) ∩ (-0.0, 0)
1-element Vector{Real}:
0
julia> intersect(Set([1, 2]), BitSet([2, 3]), 1.0:10.0)
Set{Float64} with 1 element:
2.0
Base.setdiff
— Functionsetdiff(s, itrs...)
Construct the set of elements in s
but not in any of the iterables in itrs
. Maintain order with arrays.
See also setdiff!
, union
and intersect
.
Examples
julia> setdiff([1,2,3], [3,4,5])
2-element Vector{Int64}:
1
2
Base.setdiff!
— Functionsetdiff!(s, itrs...)
Remove from set s
(in-place) each element of each iterable from itrs
. Maintain order with arrays.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Examples
julia> a = Set([1, 3, 4, 5]);
julia> setdiff!(a, 1:2:6);
julia> a
Set{Int64} with 1 element:
4
Base.symdiff
— Functionsymdiff(s, itrs...)
Construct the symmetric difference of elements in the passed in sets. When s
is not an AbstractSet
, the order is maintained.
See also symdiff!
, setdiff
, union
and intersect
.
Examples
julia> symdiff([1,2,3], [3,4,5], [4,5,6])
3-element Vector{Int64}:
1
2
6
julia> symdiff([1,2,1], [2, 1, 2])
Int64[]
Base.symdiff!
— Functionsymdiff!(s::Union{AbstractSet,AbstractVector}, itrs...)
Construct the symmetric difference of the passed in sets, and overwrite s
with the result. When s
is an array, the order is maintained. Note that in this case the multiplicity of elements matters.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Base.intersect!
— Functionintersect!(s::Union{AbstractSet,AbstractVector}, itrs...)
Intersect all passed in sets and overwrite s
with the result. Maintain order with arrays.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Base.issubset
— Functionissubset(a, b) -> Bool
⊆(a, b) -> Bool
⊇(b, a) -> Bool
Determine whether every element of a
is also in b
, using in
.
See also ⊊
, ⊈
, ∩
, ∪
, contains
.
Examples
julia> issubset([1, 2], [1, 2, 3])
true
julia> [1, 2, 3] ⊆ [1, 2]
false
julia> [1, 2, 3] ⊇ [1, 2]
true
Base.in!
— Functionin!(x, s::AbstractSet) -> Bool
If x
is in s
, return true
. If not, push x
into s
and return false
. This is equivalent to in(x, s) ? true : (push!(s, x); false)
, but may have a more efficient implementation.
This function requires at least 1.11.
Examples
julia> s = Set{Any}([1, 2, 3]); in!(4, s)
false
julia> length(s)
4
julia> in!(0x04, s)
true
julia> s
Set{Any} with 4 elements:
4
2
3
1
Base.:⊈
— Function⊈(a, b) -> Bool
⊉(b, a) -> Bool
Negation of ⊆
and ⊇
, i.e. checks that a
is not a subset of b
.
Examples
julia> (1, 2) ⊈ (2, 3)
true
julia> (1, 2) ⊈ (1, 2, 3)
false
Base.:⊊
— Function⊊(a, b) -> Bool
⊋(b, a) -> Bool
Determines if a
is a subset of, but not equal to, b
.
Examples
julia> (1, 2) ⊊ (1, 2, 3)
true
julia> (1, 2) ⊊ (1, 2)
false
Base.issetequal
— Functionissetequal(a, b) -> Bool
Determine whether a
and b
have the same elements. Equivalent to a ⊆ b && b ⊆ a
but more efficient when possible.
See also: isdisjoint
, union
.
Examples
julia> issetequal([1, 2], [1, 2, 3])
false
julia> issetequal([1, 2], [2, 1])
true
issetequal(x)
Create a function that compares its argument to x
using issetequal
, i.e. a function equivalent to y -> issetequal(y, x)
. The returned function is of type Base.Fix2{typeof(issetequal)}
, which can be used to implement specialized methods.
This functionality requires at least Julia 1.11.
Base.isdisjoint
— Functionisdisjoint(a, b) -> Bool
Determine whether the collections a
and b
are disjoint. Equivalent to isempty(a ∩ b)
but more efficient when possible.
See also: intersect
, isempty
, issetequal
.
This function requires at least Julia 1.5.
Examples
julia> isdisjoint([1, 2], [2, 3, 4])
false
julia> isdisjoint([3, 1], [2, 4])
true
isdisjoint(x)
Create a function that compares its argument to x
using isdisjoint
, i.e. a function equivalent to y -> isdisjoint(y, x)
. The returned function is of type Base.Fix2{typeof(isdisjoint)}
, which can be used to implement specialized methods.
This functionality requires at least Julia 1.11.
Fully implemented by:
Partially implemented by:
Dequeues
Base.push!
— Functionpush!(collection, items...) -> collection
Insert one or more items
in collection
. If collection
is an ordered container, the items are inserted at the end (in the given order).
Examples
julia> push!([1, 2, 3], 4, 5, 6)
6-element Vector{Int64}:
1
2
3
4
5
6
If collection
is ordered, use append!
to add all the elements of another collection to it. The result of the preceding example is equivalent to append!([1, 2, 3], [4, 5, 6])
. For AbstractSet
objects, union!
can be used instead.
See sizehint!
for notes about the performance model.
See also pushfirst!
.
Base.pop!
— Functionpop!(collection) -> item
Remove an item in collection
and return it. If collection
is an ordered container, the last item is returned; for unordered containers, an arbitrary element is returned.
See also: popfirst!
, popat!
, delete!
, deleteat!
, splice!
, and push!
.
Examples
julia> A=[1, 2, 3]
3-element Vector{Int64}:
1
2
3
julia> pop!(A)
3
julia> A
2-element Vector{Int64}:
1
2
julia> S = Set([1, 2])
Set{Int64} with 2 elements:
2
1
julia> pop!(S)
2
julia> S
Set{Int64} with 1 element:
1
julia> pop!(Dict(1=>2))
1 => 2
pop!(collection, key[, default])
Delete and return the mapping for key
if it exists in collection
, otherwise return default
, or throw an error if default
is not specified.
Examples
julia> d = Dict("a"=>1, "b"=>2, "c"=>3);
julia> pop!(d, "a")
1
julia> pop!(d, "d")
ERROR: KeyError: key "d" not found
Stacktrace:
[...]
julia> pop!(d, "e", 4)
4
Base.popat!
— Functionpopat!(a::Vector, i::Integer, [default])
Remove the item at the given i
and return it. Subsequent items are shifted to fill the resulting gap. When i
is not a valid index for a
, return default
, or throw an error if default
is not specified.
See also: pop!
, popfirst!
, deleteat!
, splice!
.
This function is available as of Julia 1.5.
Examples
julia> a = [4, 3, 2, 1]; popat!(a, 2)
3
julia> a
3-element Vector{Int64}:
4
2
1
julia> popat!(a, 4, missing)
missing
julia> popat!(a, 4)
ERROR: BoundsError: attempt to access 3-element Vector{Int64} at index [4]
[...]
Base.pushfirst!
— Functionpushfirst!(collection, items...) -> collection
Insert one or more items
at the beginning of collection
.
This function is called unshift
in many other programming languages.
Examples
julia> pushfirst!([1, 2, 3, 4], 5, 6)
6-element Vector{Int64}:
5
6
1
2
3
4
Base.popfirst!
— Functionpopfirst!(collection) -> item
Remove the first item
from collection
.
This function is called shift
in many other programming languages.
See also: pop!
, popat!
, delete!
.
Examples
julia> A = [1, 2, 3, 4, 5, 6]
6-element Vector{Int64}:
1
2
3
4
5
6
julia> popfirst!(A)
1
julia> A
5-element Vector{Int64}:
2
3
4
5
6
Base.insert!
— Functioninsert!(a::Vector, index::Integer, item)
Insert an item
into a
at the given index
. index
is the index of item
in the resulting a
.
See also: push!
, replace
, popat!
, splice!
.
Examples
julia> insert!(Any[1:6;], 3, "here")
7-element Vector{Any}:
1
2
"here"
3
4
5
6
Base.deleteat!
— Functiondeleteat!(a::Vector, i::Integer)
Remove the item at the given i
and return the modified a
. Subsequent items are shifted to fill the resulting gap.
See also: keepat!
, delete!
, popat!
, splice!
.
Examples
julia> deleteat!([6, 5, 4, 3, 2, 1], 2)
5-element Vector{Int64}:
6
4
3
2
1
deleteat!(a::Vector, inds)
Remove the items at the indices given by inds
, and return the modified a
. Subsequent items are shifted to fill the resulting gap.
inds
can be either an iterator or a collection of sorted and unique integer indices, or a boolean vector of the same length as a
with true
indicating entries to delete.
Examples
julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5)
3-element Vector{Int64}:
5
3
1
julia> deleteat!([6, 5, 4, 3, 2, 1], [true, false, true, false, true, false])
3-element Vector{Int64}:
5
3
1
julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2))
ERROR: ArgumentError: indices must be unique and sorted
Stacktrace:
[...]
Base.keepat!
— Functionkeepat!(a::Vector, inds)
keepat!(a::BitVector, inds)
Remove the items at all the indices which are not given by inds
, and return the modified a
. Items which are kept are shifted to fill the resulting gaps.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
inds
must be an iterator of sorted and unique integer indices. See also deleteat!
.
This function is available as of Julia 1.7.
Examples
julia> keepat!([6, 5, 4, 3, 2, 1], 1:2:5)
3-element Vector{Int64}:
6
4
2
keepat!(a::Vector, m::AbstractVector{Bool})
keepat!(a::BitVector, m::AbstractVector{Bool})
The in-place version of logical indexing a = a[m]
. That is, keepat!(a, m)
on vectors of equal length a
and m
will remove all elements from a
for which m
at the corresponding index is false
.
Examples
julia> a = [:a, :b, :c];
julia> keepat!(a, [true, false, true])
2-element Vector{Symbol}:
:a
:c
julia> a
2-element Vector{Symbol}:
:a
:c
Base.splice!
— Functionsplice!(a::Vector, index::Integer, [replacement]) -> item
Remove the item at the given index, and return the removed item. Subsequent items are shifted left to fill the resulting gap. If specified, replacement values from an ordered collection will be spliced in place of the removed item.
See also: replace
, delete!
, deleteat!
, pop!
, popat!
.
Examples
julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5)
2
julia> A
5-element Vector{Int64}:
6
5
4
3
1
julia> splice!(A, 5, -1)
1
julia> A
5-element Vector{Int64}:
6
5
4
3
-1
julia> splice!(A, 1, [-1, -2, -3])
6
julia> A
7-element Vector{Int64}:
-1
-2
-3
5
4
3
-1
To insert replacement
before an index n
without removing any items, use splice!(collection, n:n-1, replacement)
.
splice!(a::Vector, indices, [replacement]) -> items
Remove items at specified indices, and return a collection containing the removed items. Subsequent items are shifted left to fill the resulting gaps. If specified, replacement values from an ordered collection will be spliced in place of the removed items; in this case, indices
must be a AbstractUnitRange
.
To insert replacement
before an index n
without removing any items, use splice!(collection, n:n-1, replacement)
.
Behavior can be unexpected when any mutated argument shares memory with any other argument.
Prior to Julia 1.5, indices
must always be a UnitRange
.
Prior to Julia 1.8, indices
must be a UnitRange
if splicing in replacement values.
Examples
julia> A = [-1, -2, -3, 5, 4, 3, -1]; splice!(A, 4:3, 2)
Int64[]
julia> A
8-element Vector{Int64}:
-1
-2
-3
2
5
4
3
-1
Base.resize!
— Functionresize!(a::Vector, n::Integer) -> Vector
Resize a
to contain n
elements. If n
is smaller than the current collection length, the first n
elements will be retained. If n
is larger, the new elements are not guaranteed to be initialized.
Examples
julia> resize!([6, 5, 4, 3, 2, 1], 3)
3-element Vector{Int64}:
6
5
4
julia> a = resize!([6, 5, 4, 3, 2, 1], 8);
julia> length(a)
8
julia> a[1:6]
6-element Vector{Int64}:
6
5
4
3
2
1
Base.append!
— Functionappend!(collection, collections...) -> collection.
For an ordered container collection
, add the elements of each collections
to the end of it.
Specifying multiple collections to be appended requires at least Julia 1.6.
Examples
julia> append!([1], [2, 3])
3-element Vector{Int64}:
1
2
3
julia> append!([1, 2, 3], [4, 5], [6])
6-element Vector{Int64}:
1
2
3
4
5
6
Use push!
to add individual items to collection
which are not already themselves in another collection. The result of the preceding example is equivalent to push!([1, 2, 3], 4, 5, 6)
.
See sizehint!
for notes about the performance model.
See also vcat
for vectors, union!
for sets, and prepend!
and pushfirst!
for the opposite order.
Base.prepend!
— Functionprepend!(a::Vector, collections...) -> collection
Insert the elements of each collections
to the beginning of a
.
When collections
specifies multiple collections, order is maintained: elements of collections[1]
will appear leftmost in a
, and so on.
Specifying multiple collections to be prepended requires at least Julia 1.6.
Examples
julia> prepend!([3], [1, 2])
3-element Vector{Int64}:
1
2
3
julia> prepend!([6], [1, 2], [3, 4, 5])
6-element Vector{Int64}:
1
2
3
4
5
6
Fully implemented by:
Utility Collections
Core.Pair
— TypePair(x, y)
x => y
Construct a Pair
object with type Pair{typeof(x), typeof(y)}
. The elements are stored in the fields first
and second
. They can also be accessed via iteration (but a Pair
is treated as a single "scalar" for broadcasting operations).
See also Dict
.
Examples
julia> p = "foo" => 7
"foo" => 7
julia> typeof(p)
Pair{String, Int64}
julia> p.first
"foo"
julia> for x in p
println(x)
end
foo
7
julia> replace.(["xops", "oxps"], "x" => "o")
2-element Vector{String}:
"oops"
"oops"
Base.Pairs
— TypeBase.Pairs(values, keys) <: AbstractDict{eltype(keys), eltype(values)}
Transforms an indexable container into a Dictionary-view of the same data. Modifying the key-space of the underlying data may invalidate this object.