Collections and Data Structures
Iteration
Sequential iteration is implemented by the methods start()
, done()
, and next()
. The general for
loop:
for i = I # or "for i in I" # body end
is translated into:
state = start(I) while !done(I, state) (i, state) = next(I, state) # body 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.start
Function
start(iter) -> state
Get initial iteration state for an iterable object.
Examples
julia> start(1:5) 1 julia> start([1;2;3]) 1 julia> start([4;2;3]) 1source
Base.done
Function
done(iter, state) -> Bool
Test whether we are done iterating.
Examples
julia> done(1:5, 3) false julia> done(1:5, 5) false julia> done(1:5, 6) truesource
Base.next
Function
next(iter, state) -> item, state
For a given iterable object and iteration state, return the current item and the next iteration state.
Examples
julia> next(1:5, 3) (3, 4) julia> next(1:5, 5) (5, 6)source
Base.iteratorsize
Function
iteratorsize(itertype::Type) -> IteratorSize
Given the type of an iterator, returns 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()
if there is a known length plus a notion of multidimensional shape (as for an array). In this case thesize
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() julia> Base.iteratorsize((2,3)) Base.HasLength()source
Base.iteratoreltype
Function
iteratoreltype(itertype::Type) -> IteratorEltype
Given the type of an iterator, returns 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()source
Fully implemented by:
Range
UnitRange
Tuple
Number
EachLine
AbstractString
General Collections
Base.isempty
Function
isempty(collection) -> Bool
Determine whether a collection is empty (has no elements).
Examples
julia> isempty([]) true julia> isempty([1 2 3]) falsesource
Base.empty!
Function
empty!(collection) -> collection
Remove all elements from a collection
.
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} with 0 entriessource
Base.length
Method
length(collection) -> Integer
For ordered, indexable collections, returns the maximum index i
for which getindex(collection, i)
is valid. For unordered collections, returns the number of elements.
Examples
julia> length(1:5) 5 julia> length([1; 2; 3; 4]) 4source
Base.endof
Function
endof(collection) -> Integer
Returns the last index of the collection.
Example
julia> endof([1,2,4]) 3source
Fully implemented by:
Range
UnitRange
Tuple
Number
AbstractString
Iterable Collections
Base.in
Function
in(item, collection) -> Bool ∈(item,collection) -> Bool ∋(collection,item) -> Bool ∉(item,collection) -> Bool ∌(collection,item) -> 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. Some collections need 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)
.
julia> a = 1:3:20 1:3:19 julia> 4 in a true julia> 5 in a falsesource
Base.eltype
Function
eltype(type)
Determine the type of the elements generated by iterating a collection of the given type
. For associative collection 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.
julia> eltype(ones(Float32,2,2)) Float32 julia> eltype(ones(Int8,2,2)) Int8source
Base.indexin
Function
indexin(a, b)
Returns a vector containing the highest index in b
for each value in a
that is a member of b
. The output vector contains 0 wherever a
is not a member of b
.
Examples
julia> a = ['a', 'b', 'c', 'b', 'd', 'a']; julia> b = ['a','b','c']; julia> indexin(a,b) 6-element Array{Int64,1}: 1 2 3 2 0 1 julia> indexin(b,a) 3-element Array{Int64,1}: 6 4 3source
Base.findin
Function
findin(a, b)
Returns the indices of elements in collection a
that appear in collection b
.
Examples
julia> a = collect(1:3:15) 5-element Array{Int64,1}: 1 4 7 10 13 julia> b = collect(2:4:10) 3-element Array{Int64,1}: 2 6 10 julia> findin(a,b) # 10 is the only common element 1-element Array{Int64,1}: 4source
Base.unique
Function
unique(itr)
Returns an array containing one value from itr
for each unique value, as determined by isequal
.
julia> unique([1; 2; 2; 6]) 3-element Array{Int64,1}: 1 2 6source
unique(f, itr)
Returns an array containing one value from itr
for each unique value produced by f
applied to elements of itr
.
julia> unique(isodd, [1; 2; 2; 6]) 2-element Array{Int64,1}: 1 2source
unique(itr[, dim])
Returns an array containing only the unique elements of the iterable itr
, in the order that the first of each set of equivalent elements originally appears. If dim
is specified, returns unique regions of the array itr
along dim
.
julia> A = map(isodd, reshape(collect(1:8), (2,2,2))) 2×2×2 Array{Bool,3}: [:, :, 1] = true true false false [:, :, 2] = true true false false julia> unique(A) 2-element Array{Bool,1}: true false julia> unique(A, 2) 2×1×2 Array{Bool,3}: [:, :, 1] = true false [:, :, 2] = true false julia> unique(A, 3) 2×2×1 Array{Bool,3}: [:, :, 1] = true true false falsesource
Base.allunique
Function
allunique(itr) -> Bool
Return true
if all values from itr
are distinct when compared with isequal
.
julia> a = [1; 2; 3] 3-element Array{Int64,1}: 1 2 3 julia> allunique([a, a]) falsesource
Base.reduce
Method
reduce(op, v0, itr)
Reduce the given collection ìtr
with the given binary operator op
. v0
must be a neutral element for op
that will be returned for empty collections. It is unspecified whether v0
is used for non-empty collections.
Reductions for certain commonly-used operators have special implementations which should be used instead: maximum(itr)
, minimum(itr)
, sum(itr)
, prod(itr)
, any(itr)
, all(itr)
.
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, and parallelism will also 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(*, 1, [2; 3; 4]) 24source
Base.reduce
Method
reduce(op, itr)
Like reduce(op, v0, itr)
. This cannot be used with empty collections, except for some special cases (e.g. when op
is one of +
, *
, max
, min
, &
, |
) when Julia can determine the neutral element of op
.
julia> reduce(*, [2; 3; 4]) 24source
Base.foldl
Method
foldl(op, v0, itr)
Like reduce
, but with guaranteed left associativity. v0
will be used exactly once.
julia> foldl(-, 1, 2:5) -13source
Base.foldl
Method
foldl(op, itr)
Like foldl(op, v0, itr)
, but using the first element of itr
as v0
. In general, this cannot be used with empty collections (see reduce(op, itr)
).
julia> foldl(-, 2:5) -10source
Base.foldr
Method
foldr(op, v0, itr)
Like reduce
, but with guaranteed right associativity. v0
will be used exactly once.
julia> foldr(-, 1, 2:5) -1source
Base.foldr
Method
foldr(op, itr)
Like foldr(op, v0, itr)
, but using the last element of itr
as v0
. In general, this cannot be used with empty collections (see reduce(op, itr)
).
julia> foldr(-, 2:5) -2source
Base.maximum
Method
maximum(itr)
Returns the largest element in a collection.
julia> maximum(-20.5:10) 9.5 julia> maximum([1,2,3]) 3source
Base.maximum
Method
maximum(A, 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)
.
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> maximum(A, 1) 1×2 Array{Int64,2}: 3 4 julia> maximum(A, 2) 2×1 Array{Int64,2}: 2 4source
Base.maximum!
Function
maximum!(r, A)
Compute the maximum value of A
over the singleton dimensions of r
, and write results to r
.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> maximum!([1; 1], A) 2-element Array{Int64,1}: 2 4 julia> maximum!([1 1], A) 1×2 Array{Int64,2}: 3 4source
Base.minimum
Method
minimum(itr)
Returns the smallest element in a collection.
julia> minimum(-20.5:10) -20.5 julia> minimum([1,2,3]) 1source
Base.minimum
Method
minimum(A, 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)
.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> minimum(A, 1) 1×2 Array{Int64,2}: 1 2 julia> minimum(A, 2) 2×1 Array{Int64,2}: 1 3source
Base.minimum!
Function
minimum!(r, A)
Compute the minimum value of A
over the singleton dimensions of r
, and write results to r
.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> minimum!([1; 1], A) 2-element Array{Int64,1}: 1 3 julia> minimum!([1 1], A) 1×2 Array{Int64,2}: 1 2source
Base.extrema
Method
extrema(itr) -> Tuple
Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple.
julia> extrema(2:10) (2, 10) julia> extrema([9,pi,4.5]) (3.141592653589793, 9.0)source
Base.extrema
Method
extrema(A, dims) -> Array{Tuple}
Compute the minimum and maximum elements of an array over the given dimensions.
Example
julia> A = reshape(collect(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, (1,2)) 1×1×2 Array{Tuple{Int64,Int64},3}: [:, :, 1] = (1, 7) [:, :, 2] = (9, 15)source
Base.indmax
Function
indmax(itr) -> Integer
Returns the index of the maximum element in a collection. If there are multiple maximal elements, then the first one will be returned. NaN
values are ignored, unless all elements are NaN
.
The collection must not be empty.
Examples
julia> indmax([8,0.1,-9,pi]) 1 julia> indmax([1,7,7,6]) 2 julia> indmax([1,7,7,NaN]) 2source
Base.indmin
Function
indmin(itr) -> Integer
Returns the index of the minimum element in a collection. If there are multiple minimal elements, then the first one will be returned. NaN
values are ignored, unless all elements are NaN
.
The collection must not be empty.
Examples
julia> indmin([8,0.1,-9,pi]) 3 julia> indmin([7,1,1,6]) 2 julia> indmin([7,1,1,NaN]) 2source
Base.findmax
Method
findmax(itr) -> (x, index)
Returns the maximum element of the collection itr
and its index. If there are multiple maximal elements, then the first one will be returned. NaN
values are ignored, unless all elements are NaN
.
The collection must not be empty.
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]) (7.0, 2)source
Base.findmax
Method
findmax(A, region) -> (maxval, index)
For an array input, returns the value and index of the maximum over the given region.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> findmax(A,1) ([3 4], [2 4]) julia> findmax(A,2) ([2; 4], [3; 4])source
Base.findmin
Method
findmin(itr) -> (x, index)
Returns the minimum element of the collection itr
and its index. If there are multiple minimal elements, then the first one will be returned. NaN
values are ignored, unless all elements are NaN
.
The collection must not be empty.
Examples
julia> findmin([8,0.1,-9,pi]) (-9.0, 3) julia> findmin([7,1,1,6]) (1, 2) julia> findmin([7,1,1,NaN]) (1.0, 2)source
Base.findmin
Method
findmin(A, region) -> (minval, index)
For an array input, returns the value and index of the minimum over the given region.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> findmin(A, 1) ([1 2], [1 3]) julia> findmin(A, 2) ([1; 3], [1; 2])source
Base.findmax!
Function
findmax!(rval, rind, A, [init=true]) -> (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
.
Base.findmin!
Function
findmin!(rval, rind, A, [init=true]) -> (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
.
Base.sum
Function
sum(f, itr)
Sum the results of calling function f
on each element of itr
.
julia> sum(abs2, [2; 3; 4]) 29source
sum(itr)
Returns the sum of all elements in a collection.
julia> sum(1:20) 210source
sum(A, dims)
Sum elements of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> sum(A, 1) 1×2 Array{Int64,2}: 4 6 julia> sum(A, 2) 2×1 Array{Int64,2}: 3 7source
Base.sum!
Function
sum!(r, A)
Sum elements of A
over the singleton dimensions of r
, and write results to r
.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> sum!([1; 1], A) 2-element Array{Int64,1}: 3 7 julia> sum!([1 1], A) 1×2 Array{Int64,2}: 4 6source
Base.prod
Function
prod(f, itr)
Returns the product of f
applied to each element of itr
.
julia> prod(abs2, [2; 3; 4]) 576source
prod(itr)
Returns the product of all elements of a collection.
julia> prod(1:20) 2432902008176640000source
prod(A, dims)
Multiply elements of an array over the given dimensions.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> prod(A, 1) 1×2 Array{Int64,2}: 3 8 julia> prod(A, 2) 2×1 Array{Int64,2}: 2 12source
Base.prod!
Function
prod!(r, A)
Multiply elements of A
over the singleton dimensions of r
, and write results to r
.
Examples
julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> prod!([1; 1], A) 2-element Array{Int64,1}: 2 12 julia> prod!([1 1], A) 1×2 Array{Int64,2}: 3 8source
Base.any
Method
any(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).
julia> a = [true,false,false,true] 4-element Array{Bool,1}: true false false true julia> any(a) true julia> any((println(i); v) for (i, v) in enumerate(a)) 1 truesource
Base.any
Method
any(A, dims)
Test whether any values along the given dimensions of an array are true
.
Examples
julia> A = [true false; true false] 2×2 Array{Bool,2}: true false true false julia> any(A, 1) 1×2 Array{Bool,2}: true false julia> any(A, 2) 2×1 Array{Bool,2}: true truesource
Base.any!
Function
any!(r, A)
Test whether any values in A
along the singleton dimensions of r
are true
, and write results to r
.
Examples
julia> A = [true false; true false] 2×2 Array{Bool,2}: true false true false julia> any!([1; 1], A) 2-element Array{Int64,1}: 1 1 julia> any!([1 1], A) 1×2 Array{Int64,2}: 1 0source
Base.all
Method
all(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).
julia> a = [true,false,false,true] 4-element Array{Bool,1}: true false false true julia> all(a) false julia> all((println(i); v) for (i, v) in enumerate(a)) 1 2 falsesource
Base.all
Method
all(A, dims)
Test whether all values along the given dimensions of an array are true
.
Examples
julia> A = [true false; true true] 2×2 Array{Bool,2}: true false true true julia> all(A, 1) 1×2 Array{Bool,2}: true false julia> all(A, 2) 2×1 Array{Bool,2}: false truesource
Base.all!
Function
all!(r, A)
Test whether all values in A
along the singleton dimensions of r
are true
, and write results to r
.
Examples
julia> A = [true false; true false] 2×2 Array{Bool,2}: true false true false julia> all!([1; 1], A) 2-element Array{Int64,1}: 0 0 julia> all!([1 1], A) 1×2 Array{Int64,2}: 1 0source
Base.count
Function
count(p, itr) -> Integer count(itr) -> Integer
Count the number of elements in itr
for which predicate p
returns true
. If p
is omitted, counts the number of true
elements in itr
(which should be a collection of boolean values).
julia> count(i->(4<=i<=6), [2,3,4,5,6]) 3 julia> count([true, false, true, true]) 3source
Base.any
Method
any(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).
julia> any(i->(4<=i<=6), [3,5,7]) true julia> any(i -> (println(i); i > 3), 1:10) 1 2 3 4 truesource
Base.all
Method
all(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).
julia> all(i->(4<=i<=6), [4,5,6]) true julia> all(i -> (println(i); i < 3), 1:10) 1 2 3 falsesource
Base.foreach
Function
foreach(f, c...) -> Void
Call function f
on each element of iterable c
. For multiple iterable arguments, f
is called elementwise. foreach
should be used instead of map
when the results of f
are not needed, for example in foreach(println, array)
.
Example
julia> a = 1:3:7; julia> foreach(x -> println(x^2), a) 1 16 49source
Base.map
Function
map(f, c...) -> collection
Transform collection c
by applying f
to each element. For multiple collection arguments, apply f
elementwise.
Examples
julia> map(x -> x * 2, [1, 2, 3]) 3-element Array{Int64,1}: 2 4 6 julia> map(+, [1, 2, 3], [10, 20, 30]) 3-element Array{Int64,1}: 11 22 33source
map(f, x::Nullable)
Return f
applied to the value of x
if it has one, as a Nullable
. If x
is null, then return a null value of type Nullable{S}
. S
is guaranteed to be either Union{}
or a concrete type. Whichever of these is chosen is an implementation detail, but typically the choice that maximizes performance would be used. If x
has a value, then the return type is guaranteed to be of type Nullable{typeof(f(x))}
.
Base.map!
Function
map!(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 first collection.
Example
julia> x = zeros(3); julia> map!(x -> x * 2, x, [1, 2, 3]); julia> x 3-element Array{Float64,1}: 2.0 4.0 6.0source
Base.mapreduce
Method
mapreduce(f, op, v0, itr)
Apply function f
to each element in itr
, and then reduce the result using the binary function op
. v0
must be a neutral element for op
that will be returned for empty collections. It is unspecified whether v0
is used for non-empty collections.
mapreduce
is functionally equivalent to calling reduce(op, v0, map(f, itr))
, but will in general execute faster since no intermediate collection needs to be created. See documentation for reduce
and map
.
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.mapreduce
Method
mapreduce(f, op, itr)
Like mapreduce(f, op, v0, itr)
. In general, this cannot be used with empty collections (see reduce(op, itr)
).
Base.mapfoldl
Method
mapfoldl(f, op, v0, itr)
Like mapreduce
, but with guaranteed left associativity, as in foldl
. v0
will be used exactly once.
Base.mapfoldl
Method
mapfoldl(f, op, itr)
Like mapfoldl(f, op, v0, itr)
, but using the first element of itr
as v0
. In general, this cannot be used with empty collections (see reduce(op, itr)
).
Base.mapfoldr
Method
mapfoldr(f, op, v0, itr)
Like mapreduce
, but with guaranteed right associativity, as in foldr
. v0
will be used exactly once.
Base.mapfoldr
Method
mapfoldr(f, op, itr)
Like mapfoldr(f, op, v0, itr)
, but using the first element of itr
as v0
. In general, this cannot be used with empty collections (see reduce(op, itr)
).
Base.first
Function
first(coll)
Get the first element of an iterable collection. Returns the start point of a Range
even if it is empty.
julia> first(2:2:10) 2 julia> first([1; 2; 3; 4]) 1source
Base.last
Function
last(coll)
Get the last element of an ordered collection, if it can be computed in O(1) time. This is accomplished by calling endof
to get the last index. Returns the end point of a Range
even if it is empty.
julia> last(1:2:10) 9 julia> last([1; 2; 3; 4]) 4source
Base.step
Function
step(r)
Get the step size of a Range
object.
julia> step(1:10) 1 julia> step(1:2:10) 2 julia> step(2.5:0.3:10.9) 0.3 julia> step(linspace(2.5,10.9,85)) 0.1source
Base.collect
Method
collect(collection)
Return an Array
of all items in a collection or iterator. For associative collections, returns Pair{KeyType, ValType}
. 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.
Example
julia> collect(1:2:13) 7-element Array{Int64,1}: 1 3 5 7 9 11 13source
Base.collect
Method
collect(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
.
julia> collect(Float64, 1:2:5) 3-element Array{Float64,1}: 1.0 3.0 5.0source
Base.issubset
Method
issubset(a, b) ⊆(a,b) -> Bool ⊈(a,b) -> Bool ⊊(a,b) -> Bool
Determine whether every element of a
is also in b
, using in
.
Examples
julia> issubset([1, 2], [1, 2, 3]) true julia> issubset([1, 2, 3], [1, 2]) falsesource
Base.filter
Function
filter(function, collection)
Return a copy of collection
, removing elements for which function
is false
. For associative collections, the function is passed two arguments (key and value).
Examples
julia> a = 1:10 1:10 julia> filter(isodd, a) 5-element Array{Int64,1}: 1 3 5 7 9 julia> d = Dict(1=>"a", 2=>"b") Dict{Int64,String} with 2 entries: 2 => "b" 1 => "a" julia> filter((x,y)->isodd(x), d) Dict{Int64,String} with 1 entry: 1 => "a"source
filter(p, x::Nullable)
Return null if either x
is null or p(get(x))
is false, and x
otherwise.
Base.filter!
Function
filter!(function, collection)
Update collection
, removing elements for which function
is false
. For associative collections, the function is passed two arguments (key and value).
Example
julia> filter!(isodd, collect(1:10)) 5-element Array{Int64,1}: 1 3 5 7 9source
Indexable Collections
Base.getindex
Method
getindex(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, ...)
.
Example
julia> A = Dict("a" => 1, "b" => 2) Dict{String,Int64} with 2 entries: "b" => 2 "a" => 1 julia> getindex(A, "a") 1source
Base.setindex!
Method
setindex!(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)
.
Fully implemented by:
SubArray
AbstractString
Partially implemented by:
Range
UnitRange
Tuple
Associative Collections
Dict
is the standard associative collection. 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.
ObjectIdDict
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.
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)
.
Associative collections 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.Dict
Type
Dict([itr])
Dict{K,V}()
constructs a hash table with keys of type K
and values of type V
.
Given a single iterable argument, constructs a Dict
whose key-value pairs are taken from 2-tuples (key,value)
generated by the argument.
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" => 1source
Base.ObjectIdDict
Type
ObjectIdDict([itr])
ObjectIdDict()
constructs a hash table where the keys are (always) object identities. Unlike Dict
it is not parameterized on its key and value type and thus its eltype
is always Pair{Any,Any}
.
See Dict
for further help.
Base.WeakKeyDict
Type
WeakKeyDict([itr])
WeakKeyDict()
constructs a hash table where the keys are weak references to objects, and thus may be garbage collected even when referenced in a hash table.
See Dict
for further help.
Base.haskey
Function
haskey(collection, key) -> Bool
Determine whether a collection has a mapping for a given key.
julia> a = Dict('a'=>2, 'b'=>3) Dict{Char,Int64} with 2 entries: 'b' => 3 'a' => 2 julia> haskey(a,'a') true julia> haskey(a,'c') falsesource
Base.get
Method
get(collection, key, default)
Return the value stored for the given key, or the given default value if no mapping for the key is present.
Examples
julia> d = Dict("a"=>1, "b"=>2); julia> get(d, "a", 3) 1 julia> get(d, "c", 3) 3source
Base.get
Function
get(f::Function, 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() endsource
Base.get!
Method
get!(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" => 4source
Base.get!
Method
get!(f::Function, 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:
get!(dict, key) do # default value calculated here time() endsource
Base.getkey
Function
getkey(collection, key, default)
Return the key matching argument key
if one exists in collection
, otherwise return default
.
julia> a = Dict('a'=>2, 'b'=>3) Dict{Char,Int64} with 2 entries: 'b' => 3 'a' => 2 julia> getkey(a,'a',1) 'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase) julia> getkey(a,'d','a') 'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)source
Base.delete!
Function
delete!(collection, key)
Delete the mapping for the given key in a collection, and return the collection.
Example
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" => 1source
Base.pop!
Method
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: [1] pop!(::Dict{String,Int64}, ::String) at ./dict.jl:539 julia> pop!(d, "e", 4) 4source
Base.keys
Function
keys(a::Associative)
Return an iterator over all keys in a collection. collect(keys(a))
returns an array of keys. Since the keys are stored internally in a hash table, 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.
julia> a = Dict('a'=>2, 'b'=>3) Dict{Char,Int64} with 2 entries: 'b' => 3 'a' => 2 julia> collect(keys(a)) 2-element Array{Char,1}: 'b' 'a'source
Base.values
Function
values(a::Associative)
Return an iterator over all values in a collection. collect(values(a))
returns an array of values. Since the values are stored internally in a hash table, 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.
julia> a = Dict('a'=>2, 'b'=>3) Dict{Char,Int64} with 2 entries: 'b' => 3 'a' => 2 julia> collect(values(a)) 2-element Array{Int64,1}: 3 2source
Base.merge
Function
merge(d::Associative, others::Associative...)
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.
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.0source
merge(combine, d::Associative, others::Associative...)
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.
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" => 4753.0 "baz" => 17.0 "foo" => 0.0source
Base.merge!
Function
merge!(d::Associative, others::Associative...)
Update collection with pairs from the other collections. See also merge
.
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 => 4source
merge!(combine, d::Associative, others::Associative...)
Update collection with pairs from the other collections. Values with the same key will be combined using the combiner function.
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 => 6 julia> merge!(-, d1, d1); julia> d1 Dict{Int64,Int64} with 3 entries: 4 => 0 3 => 0 1 => 0source
Merge changes into current head
sourceInternal implementation of merge. Returns true
if merge was successful, otherwise false
merge!(repo::GitRepo; kwargs...) -> Bool
Perform a git merge on the repository repo
, merging commits with diverging history into the current branch. Returns true
if the merge succeeded, false
if not.
The keyword arguments are:
committish::AbstractString=""
: Merge the named commit(s) incommittish
.branch::AbstractString=""
: Merge the branchbranch
and all its commits since it diverged from the current branch.fastforward::Bool=false
: Iffastforward
istrue
, only merge if the merge is a fast-forward (the current branch head is an ancestor of the commits to be merged), otherwise refuse to merge and returnfalse
. This is equivalent to the git CLI option--ff-only
.merge_opts::MergeOptions=MergeOptions()
:merge_opts
specifies options for the merge, such as merge strategy in case of conflicts.checkout_opts::CheckoutOptions=CheckoutOptions()
:checkout_opts
specifies options for the checkout step.
Equivalent to git merge [--ff-only] [<committish> | <branch>]
.
If you specify a branch
, this must be done in reference format, since the string will be turned into a GitReference
. For example, if you wanted to merge branch branch_a
, you would call merge!(repo, branch="refs/heads/branch_a")
.
Base.sizehint!
Function
sizehint!(s, n)
Suggest that collection s
reserve capacity for at least n
elements. This can improve performance.
Base.keytype
Function
keytype(type)
Get the key type of an associative collection type. Behaves similarly to eltype
.
julia> keytype(Dict(Int32(1) => "foo")) Int32source
Base.valtype
Function
valtype(type)
Get the value type of an associative collection type. Behaves similarly to eltype
.
julia> valtype(Dict(Int32(1) => "foo")) Stringsource
Fully implemented by:
Partially implemented by:
Set-Like Collections
Base.Set
Type
Set([itr])
Construct a Set
of the values generated by the given iterable object, or an empty set. Should be used instead of IntSet
for sparse integer sets, or for sets of arbitrary objects.
Base.IntSet
Type
IntSet([itr])
Construct a sorted set of positive Int
s generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only Int
s greater than 0 can be stored. If the set will be sparse (for example holding a few very large integers), use Set
instead.
Base.union
Function
union(s1,s2...) ∪(s1,s2...)
Construct the union of two or more sets. Maintains order with arrays.
Examples
julia> union([1, 2], [3, 4]) 4-element Array{Int64,1}: 1 2 3 4 julia> union([1, 2], [2, 4]) 3-element Array{Int64,1}: 1 2 4 julia> union([4, 2], [1, 2]) 3-element Array{Int64,1}: 4 2 1source
Base.union!
Function
union!(s, iterable)
Union each element of iterable
into set s
in-place.
Base.intersect
Function
intersect(s1,s2...) ∩(s1,s2)
Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges.
source
Base.setdiff
Function
setdiff(a, b)
Construct the set of elements in a
but not b
. Maintains order with arrays. Note that both arguments must be collections, and both will be iterated over. In particular, setdiff(set,element)
where element
is a potential member of set
, will not work in general.
Example
julia> setdiff([1,2,3],[3,4,5]) 2-element Array{Int64,1}: 1 2source
Base.setdiff!
Function
setdiff!(s, iterable)
Remove each element of iterable
from set s
in-place.
Base.symdiff
Function
symdiff(a, b, rest...)
Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays.
Example
julia> symdiff([1,2,3],[3,4,5],[4,5,6]) 3-element Array{Int64,1}: 1 2 6source
Base.symdiff!
Method
symdiff!(s, n)
The set s
is destructively modified to toggle the inclusion of integer n
.
Base.symdiff!
Method
symdiff!(s, itr)
For each element in itr
, destructively toggle its inclusion in set s
.
Base.symdiff!
Method
symdiff!(s, itr)
For each element in itr
, destructively toggle its inclusion in set s
.
Base.intersect!
Function
intersect!(s1::IntSet, s2::IntSet)
Intersects sets s1
and s2
and overwrites the set s1
with the result. If needed, s1
will be expanded to the size of s2
.
Base.issubset
Function
issubset(A, S) -> Bool ⊆(A,S) -> Bool
Return true
if A
is a subset of or equal to S
.
Fully implemented by:
Partially implemented by:
Dequeues
Base.push!
Function
push!(collection, items...) -> collection
Insert one or more items
at the end of collection
.
Example
julia> push!([1, 2, 3], 4, 5, 6) 6-element Array{Int64,1}: 1 2 3 4 5 6
Use append!
to add all the elements of another collection to collection
. The result of the preceding example is equivalent to append!([1, 2, 3], [4, 5, 6])
.
Base.pop!
Method
pop!(collection) -> item
Remove the last item in collection
and return it.
Examples
julia> A=[1, 2, 3, 4, 5, 6] 6-element Array{Int64,1}: 1 2 3 4 5 6 julia> pop!(A) 6 julia> A 5-element Array{Int64,1}: 1 2 3 4 5source
Base.unshift!
Function
unshift!(collection, items...) -> collection
Insert one or more items
at the beginning of collection
.
Example
julia> unshift!([1, 2, 3, 4], 5, 6) 6-element Array{Int64,1}: 5 6 1 2 3 4source
Base.shift!
Function
shift!(collection) -> item
Remove the first item
from collection
.
Example
julia> A = [1, 2, 3, 4, 5, 6] 6-element Array{Int64,1}: 1 2 3 4 5 6 julia> shift!(A) 1 julia> A 5-element Array{Int64,1}: 2 3 4 5 6source
Base.insert!
Function
insert!(a::Vector, index::Integer, item)
Insert an item
into a
at the given index
. index
is the index of item
in the resulting a
.
Example
julia> insert!([6, 5, 4, 2, 1], 4, 3) 6-element Array{Int64,1}: 6 5 4 3 2 1source
Base.deleteat!
Function
deleteat!(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.
Example
julia> deleteat!([6, 5, 4, 3, 2, 1], 2) 5-element Array{Int64,1}: 6 4 3 2 1source
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 Array{Int64,1}: 5 3 1 julia> deleteat!([6, 5, 4, 3, 2, 1], [true, false, true, false, true, false]) 3-element Array{Int64,1}: 5 3 1 julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) ERROR: ArgumentError: indices must be unique and sorted Stacktrace: [1] _deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:926 [2] deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:913source
Base.splice!
Function
splice!(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.
Examples
julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5) 2 julia> A 5-element Array{Int64,1}: 6 5 4 3 1 julia> splice!(A, 5, -1) 1 julia> A 5-element Array{Int64,1}: 6 5 4 3 -1 julia> splice!(A, 1, [-1, -2, -3]) 6 julia> A 7-element Array{Int64,1}: -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, range, [replacement]) -> items
Remove items in the specified index range, and return a collection containing the removed items. 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 items.
To insert replacement
before an index n
without removing any items, use splice!(collection, n:n-1, replacement)
.
Example
julia> splice!(A, 4:3, 2) 0-element Array{Int64,1} julia> A 8-element Array{Int64,1}: -1 -2 -3 2 5 4 3 -1source
Base.resize!
Function
resize!(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 Array{Int64,1}: 6 5 4 julia> a = resize!([6, 5, 4, 3, 2, 1], 8); julia> length(a) 8 julia> a[1:6] 6-element Array{Int64,1}: 6 5 4 3 2 1source
Base.append!
Function
append!(collection, collection2) -> collection.
Add the elements of collection2
to the end of collection
.
Examples
julia> append!([1],[2,3]) 3-element Array{Int64,1}: 1 2 3 julia> append!([1, 2, 3], [4, 5, 6]) 6-element Array{Int64,1}: 1 2 3 4 5 6
Use push!
to add individual items to collection
which are not already themselves in another collection. The result is of the preceding example is equivalent to push!([1, 2, 3], 4, 5, 6)
.
Base.prepend!
Function
prepend!(a::Vector, items) -> collection
Insert the elements of items
to the beginning of a
.
Example
julia> prepend!([3],[1,2]) 3-element Array{Int64,1}: 1 2 3source
Fully implemented by:
© 2009–2016 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
https://docs.julialang.org/en/release-0.6/stdlib/collections/