W3cubDocs

/Julia 0.6

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.startFunction

start(iter) -> state

Get initial iteration state for an iterable object.

julia> start(1:5)
1

julia> start([1;2;3])
1

julia> start([4;2;3])
1
source

Base.doneFunction

done(iter, state) -> Bool

Test whether we are done iterating.

julia> done(1:5, 3)
false

julia> done(1:5, 5)
false

julia> done(1:5, 6)
true
source

Base.nextFunction

next(iter, state) -> item, state

For a given iterable object and iteration state, return the current item and the next iteration state.

julia> next(1:5, 3)
(3, 4)

julia> next(1:5, 5)
(5, 6)
source

Base.iteratorsizeFunction

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 the size 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.iteratoreltypeFunction

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, and eltype 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:

General Collections

Base.isemptyFunction

isempty(collection) -> Bool

Determine whether a collection is empty (has no elements).

julia> isempty([])
true

julia> isempty([1 2 3])
false
source

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 entries
source

Base.lengthMethod

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.

julia> length(1:5)
5

julia> length([1; 2; 3; 4])
4
source

Base.endofFunction

endof(collection) -> Integer

Returns the last index of the collection.

julia> endof([1,2,4])
3
source

Fully implemented by:

Iterable Collections

Base.inFunction

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 Sets check whether the item isequal to one of the elements. Dicts 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
false
source

Base.eltypeFunction

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))
Int8
source

Base.indexinFunction

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.

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
 3
source

Base.findinFunction

findin(a, b)

Returns the indices of elements in collection a that appear in collection b.

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}:
 4
source

Base.uniqueFunction

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
 6
source
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
 2
source
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  false
source

Base.alluniqueFunction

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])
false
source

Base.reduceMethod

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])
24
source

Base.reduceMethod

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])
24
source

Base.foldlMethod

foldl(op, v0, itr)

Like reduce, but with guaranteed left associativity. v0 will be used exactly once.

julia> foldl(-, 1, 2:5)
-13
source

Base.foldlMethod

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)
-10
source

Base.foldrMethod

foldr(op, v0, itr)

Like reduce, but with guaranteed right associativity. v0 will be used exactly once.

julia> foldr(-, 1, 2:5)
-1
source

Base.foldrMethod

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)
-2
source

Base.maximumMethod

maximum(itr)

Returns the largest element in a collection.

julia> maximum(-20.5:10)
9.5

julia> maximum([1,2,3])
3
source

Base.maximumMethod

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
 4
source

Base.maximum!Function

maximum!(r, A)

Compute the maximum value of A over the singleton dimensions of r, and write results to r.

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  4
source

Base.minimumMethod

minimum(itr)

Returns the smallest element in a collection.

julia> minimum(-20.5:10)
-20.5

julia> minimum([1,2,3])
1
source

Base.minimumMethod

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).

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
 3
source

Base.minimum!Function

minimum!(r, A)

Compute the minimum value of A over the singleton dimensions of r, and write results to r.

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  2
source

Base.extremaMethod

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.extremaMethod

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.indmaxFunction

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.

julia> indmax([8,0.1,-9,pi])
1

julia> indmax([1,7,7,6])
2

julia> indmax([1,7,7,NaN])
2
source

Base.indminFunction

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.

julia> indmin([8,0.1,-9,pi])
3

julia> indmin([7,1,1,6])
2

julia> indmin([7,1,1,NaN])
2
source

Base.findmaxMethod

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.

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.findmaxMethod

findmax(A, region) -> (maxval, index)

For an array input, returns the value and index of the maximum over the given region.

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.findminMethod

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.

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.findminMethod

findmin(A, region) -> (minval, index)

For an array input, returns the value and index of the minimum over the given region.

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.

source

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.

source

Base.sumFunction

sum(f, itr)

Sum the results of calling function f on each element of itr.

julia> sum(abs2, [2; 3; 4])
29
source
sum(itr)

Returns the sum of all elements in a collection.

julia> sum(1:20)
210
source
sum(A, dims)

Sum elements of an array over the given dimensions.

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
 7
source

Base.sum!Function

sum!(r, A)

Sum elements of A over the singleton dimensions of r, and write results to r.

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  6
source

Base.prodFunction

prod(f, itr)

Returns the product of f applied to each element of itr.

julia> prod(abs2, [2; 3; 4])
576
source
prod(itr)

Returns the product of all elements of a collection.

julia> prod(1:20)
2432902008176640000
source
prod(A, dims)

Multiply elements of an array over the given dimensions.

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
 12
source

Base.prod!Function

prod!(r, A)

Multiply elements of A over the singleton dimensions of r, and write results to r.

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  8
source

Base.anyMethod

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
true
source

Base.anyMethod

any(A, dims)

Test whether any values along the given dimensions of an array are true.

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
 true
source

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.

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  0
source

Base.allMethod

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
false
source

Base.allMethod

all(A, dims)

Test whether all values along the given dimensions of an array are true.

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
  true
source

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.

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  0
source

Base.countFunction

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])
3
source

Base.anyMethod

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
true
source

Base.allMethod

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
false
source

Base.foreachFunction

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).

julia> a = 1:3:7;

julia> foreach(x -> println(x^2), a)
1
16
49
source

Base.mapFunction

map(f, c...) -> collection

Transform collection c by applying f to each element. For multiple collection arguments, apply f elementwise.

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
 33
source
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))}.

source

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.

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.0
source

Base.mapreduceMethod

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.

source

Base.mapreduceMethod

mapreduce(f, op, itr)

Like mapreduce(f, op, v0, itr). In general, this cannot be used with empty collections (see reduce(op, itr)).

source

Base.mapfoldlMethod

mapfoldl(f, op, v0, itr)

Like mapreduce, but with guaranteed left associativity, as in foldl. v0 will be used exactly once.

source

Base.mapfoldlMethod

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)).

source

Base.mapfoldrMethod

mapfoldr(f, op, v0, itr)

Like mapreduce, but with guaranteed right associativity, as in foldr. v0 will be used exactly once.

source

Base.mapfoldrMethod

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)).

source

Base.firstFunction

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])
1
source

Base.lastFunction

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])
4
source

Base.stepFunction

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.1
source

Base.collectMethod

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.

julia> collect(1:2:13)
7-element Array{Int64,1}:
  1
  3
  5
  7
  9
 11
 13
source

Base.collectMethod

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.0
source

Base.issubsetMethod

issubset(a, b)
⊆(a,b) -> Bool
⊈(a,b) -> Bool
⊊(a,b) -> Bool

Determine whether every element of a is also in b, using in.

source

Base.filterFunction

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).

julia> a = 1:10
1:10

julia> filter(isodd, a)
5-element Array{Int64,1}:
 1
 3
 5
 7
 9
source
filter(p, x::Nullable)

Return null if either x is null or p(get(x)) is false, and x otherwise.

source

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).

julia> filter!(isodd, collect(1:10))
5-element Array{Int64,1}:
 1
 3
 5
 7
 9
source

Indexable Collections

Base.getindexMethod

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, ...).

julia> A = Dict("a" => 1, "b" => 2)
Dict{String,Int64} with 2 entries:
  "b" => 2
  "a" => 1

julia> getindex(A, "a")
1
source

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).

source

Fully implemented by:

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.

Dicts 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.DictType

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" => 1
source

Base.ObjectIdDictType

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.

source

Base.WeakKeyDictType

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.

source

Base.haskeyFunction

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')
false
source

Base.getMethod

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.

source

Base.getFunction

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()
end
source

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.

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
source

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()
end
source

Base.getkeyFunction

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.

source

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.

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)
4
source

Base.keysFunction

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.valuesFunction

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
 2
source

Base.mergeFunction

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.0
source
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.0
source

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 => 4
source
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 => 0
source

Merge changes into current head

source

Internal implementation of merge. Returns true if merge was successful, otherwise false

source
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) in committish.

  • branch::AbstractString="": Merge the branch branch and all its commits since it diverged from the current branch.

  • fastforward::Bool=false: If fastforward is true, 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 return false. 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>].

Note

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").

source

Base.sizehint!Function

sizehint!(s, n)

Suggest that collection s reserve capacity for at least n elements. This can improve performance.

source

Base.keytypeFunction

keytype(type)

Get the key type of an associative collection type. Behaves similarly to eltype.

julia> keytype(Dict(Int32(1) => "foo"))
Int32
source

Base.valtypeFunction

valtype(type)

Get the value type of an associative collection type. Behaves similarly to eltype.

julia> valtype(Dict(Int32(1) => "foo"))
String
source

Fully implemented by:

Partially implemented by:

Set-Like Collections

Base.SetType

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.

source

Base.IntSetType

IntSet([itr])

Construct a sorted set of positive Ints generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only Ints greater than 0 can be stored. If the set will be sparse (for example holding a few very large integers), use Set instead.

source

Base.unionFunction

union(s1,s2...)
∪(s1,s2...)

Construct the union of two or more sets. Maintains order with arrays.

source

Base.union!Function

union!(s, iterable)

Union each element of iterable into set s in-place.

source

Base.intersectFunction

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.setdiffFunction

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.

julia> setdiff([1,2,3],[3,4,5])
2-element Array{Int64,1}:
 1
 2
source

Base.setdiff!Function

setdiff!(s, iterable)

Remove each element of iterable from set s in-place.

source

Base.symdiffFunction

symdiff(a, b, rest...)

Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays.

julia> symdiff([1,2,3],[3,4,5],[4,5,6])
3-element Array{Int64,1}:
 1
 2
 6
source

Base.symdiff!Method

symdiff!(s, n)

The set s is destructively modified to toggle the inclusion of integer n.

source

Base.symdiff!Method

symdiff!(s, itr)

For each element in itr, destructively toggle its inclusion in set s.

source

Base.symdiff!Method

symdiff!(s, itr)

For each element in itr, destructively toggle its inclusion in set s.

source

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.

source

Base.issubsetFunction

issubset(A, S) -> Bool
⊆(A,S) -> Bool

Return true if A is a subset of or equal to S.

source

Fully implemented by:

Partially implemented by:

Dequeues

Base.push!Function

push!(collection, items...) -> collection

Insert one or more items at the end of collection.

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]).

source

Base.pop!Method

pop!(collection) -> item

Remove the last item in collection and return it.

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
 5
source

Base.unshift!Function

unshift!(collection, items...) -> collection

Insert one or more items at the beginning of collection.

julia> unshift!([1, 2, 3, 4], 5, 6)
6-element Array{Int64,1}:
 5
 6
 1
 2
 3
 4
source

Base.shift!Function

shift!(collection) -> item

Remove the first item from collection.

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
 6
source

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.

julia> insert!([6, 5, 4, 2, 1], 4, 3)
6-element Array{Int64,1}:
 6
 5
 4
 3
 2
 1
source

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.

julia> deleteat!([6, 5, 4, 3, 2, 1], 2)
5-element Array{Int64,1}:
 6
 4
 3
 2
 1
source
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.

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:885
 [2] deleteat!(::Array{Int64,1}, ::Tuple{Int64,Int64}) at ./array.jl:872
source

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.

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).

source
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).

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
 -1
source

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.

julia> resize!([6, 5, 4, 3, 2, 1], 3)
3-element Array{Int64,1}:
 6
 5
 4
julia> resize!([6, 5, 4, 3, 2, 1], 8)
8-element Array{Int64,1}:
 6
 5
 4
 3
 2
 1
 0
 0
source

Base.append!Function

append!(collection, collection2) -> collection.

Add the elements of collection2 to the end of collection.

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).

source

Base.prepend!Function

prepend!(a::Vector, items) -> collection

Insert the elements of items to the beginning of a.

julia> prepend!([3],[1,2])
3-element Array{Int64,1}:
 1
 2
 3
source

Fully implemented by:

  • Vector (a.k.a. 1-dimensional Array)

  • BitVector (a.k.a. 1-dimensional BitArray)

© 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/