Arrays¶
Basic functions¶

ndims
(A::AbstractArray) → Integer¶ Returns the number of dimensions of
A
.julia> A = ones(3,4,5); julia> ndims(A) 3

size
(A::AbstractArray[, dim...])¶ Returns a tuple containing the dimensions of
A
. Optionally you can specify the dimension(s) you want the length of, and get the length of that dimension, or a tuple of the lengths of dimensions you asked for.julia> A = ones(2,3,4); julia> size(A, 2) 3 julia> size(A,3,2) (4,3)

indices
(A)¶ Returns the tuple of valid indices for array
A
.

indices
(A, d) Returns the valid range of indices for array
A
along dimensiond
.

length
(A::AbstractArray) → Integer¶ Returns the number of elements in
A
.julia> A = ones(3,4,5); julia> length(A) 60

eachindex
(A...)¶ Creates an iterable object for visiting each index of an AbstractArray
A
in an efficient manner. For array types that have opted into fast linear indexing (likeArray
), this is simply the range1:length(A)
. For other array types, this returns a specialized Cartesian range to efficiently index into the array with indices specified for every dimension. For other iterables, including strings and dictionaries, this returns an iterator object supporting arbitrary index types (e.g. unevenly spaced or noninteger indices).Example for a sparse 2d array:
julia> A = sparse([1, 1, 2], [1, 3, 1], [1, 2, 5]) 2×3 sparse matrix with 3 Int64 nonzero entries: [1, 1] = 1 [2, 1] = 5 [1, 3] = 2 julia> for iter in eachindex(A) @show iter.I[1], iter.I[2] @show A[iter] end (iter.I[1],iter.I[2]) = (1,1) A[iter] = 1 (iter.I[1],iter.I[2]) = (2,1) A[iter] = 5 (iter.I[1],iter.I[2]) = (1,2) A[iter] = 0 (iter.I[1],iter.I[2]) = (2,2) A[iter] = 0 (iter.I[1],iter.I[2]) = (1,3) A[iter] = 2 (iter.I[1],iter.I[2]) = (2,3) A[iter] = 0
If you supply more than one
AbstractArray
argument,eachindex
will create an iterable object that is fast for all arguments (aUnitRange
if all inputs have fast linear indexing, a CartesianRange otherwise). If the arrays have different sizes and/or dimensionalities,eachindex
returns an iterable that spans the largest range along each dimension.

linearindices
(A)¶ Returns a
UnitRange
specifying the valid range of indices forA[i]
wherei
is anInt
. For arrays with conventional indexing (indices start at 1), or any multidimensional array, this is1:length(A)
; however, for onedimensional arrays with unconventional indices, this isindices(A, 1)
.Calling this function is the “safe” way to write algorithms that exploit linear indexing.

Base.
linearindexing
(A)¶ linearindexing
defines how an AbstractArray most efficiently accesses its elements. IfBase.linearindexing(A)
returnsBase.LinearFast()
, this means that linear indexing with only one index is an efficient operation. If it instead returnsBase.LinearSlow()
(by default), this means that the array intrinsically accesses its elements with indices specified for every dimension. Since converting a linear index to multiple indexing subscripts is typically very expensive, this provides a traitsbased mechanism to enable efficient generic code for all array types.An abstract array subtype
MyArray
that wishes to opt into fast linear indexing behaviors should definelinearindexing
in the typedomain:Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast()

countnz
(A)¶ Counts the number of nonzero values in array
A
(dense or sparse). Note that this is not a constanttime operation. For sparse matrices, one should usually usennz
, which returns the number of stored values.

conj!
(A)¶ Convert an array to its complex conjugate inplace.

stride
(A, k::Integer)¶ Returns the distance in memory (in number of elements) between adjacent elements in dimension
k
.julia> A = ones(3,4,5); julia> stride(A,2) 3 julia> stride(A,3) 12

strides
(A)¶ Returns a tuple of the memory strides in each dimension.
julia> A = ones(3,4,5); julia> strides(A) (1,3,12)

ind2sub
(dims, index) → subscripts¶ Returns a tuple of subscripts into an array with dimensions
dims
, corresponding to the linear indexindex
.Example:
i, j, ... = ind2sub(size(A), indmax(A))
provides the indices of the maximum element.

ind2sub
(a, index) → subscripts Returns a tuple of subscripts into array
a
corresponding to the linear indexindex
.

sub2ind
(dims, i, j, k...) → index¶ The inverse of
ind2sub
, returns the linear index corresponding to the provided subscripts.

LinAlg.
checksquare
(A)¶ Check that a matrix is square, then return its common dimension. For multiple arguments, return a vector.
Constructors¶

Array
(dims)¶ Array{T}(dims)
constructs an uninitialized dense array with element typeT
.dims
may be a tuple or a series of integer arguments. The syntaxArray(T, dims)
is also available, but deprecated.

getindex
(type[, elements...])¶ Construct a 1d array of the specified type. This is usually called with the syntax
Type[]
. Element values can be specified usingType[a,b,c,...]
.

zeros
(type, dims)¶ Create an array of all zeros of specified type. The type defaults to Float64 if not specified.

zeros
(A) Create an array of all zeros with the same element type and shape as
A
.

ones
(type, dims)¶ Create an array of all ones of specified type. The type defaults to
Float64
if not specified.

ones
(A) Create an array of all ones with the same element type and shape as
A
.

trues
(dims)¶ Create a
BitArray
with all values set totrue
.

trues
(A) Create a
BitArray
with all values set totrue
of the same shape asA
.

falses
(dims)¶ Create a
BitArray
with all values set tofalse
.

falses
(A) Create a
BitArray
with all values set tofalse
of the same shape asA
.

fill
(x, dims)¶ Create an array filled with the value
x
. For example,fill(1.0, (10,10))
returns a 10×10 array of floats, with each element initialized to1.0
.If
x
is an object reference, all elements will refer to the same object.fill(Foo(), dims)
will return an array filled with the result of evaluatingFoo()
once.

fill!
(A, x)¶ Fill array
A
with the valuex
. Ifx
is an object reference, all elements will refer to the same object.fill!(A, Foo())
will returnA
filled with the result of evaluatingFoo()
once.

reshape
(A, dims)¶ Create an array with the same data as the given array, but with different dimensions.

similar
(array[, element_type=eltype(array)][, dims=size(array)])¶ Create an uninitialized mutable array with the given element type and size, based upon the given source array. The second and third arguments are both optional, defaulting to the given array’s
eltype
andsize
. The dimensions may be specified either as a single tuple argument or as a series of integer arguments.Custom AbstractArray subtypes may choose which specific array type is bestsuited to return for the given element type and dimensionality. If they do not specialize this method, the default is an
Array{element_type}(dims...)
.For example,
similar(1:10, 1, 4)
returns an uninitializedArray{Int,2}
since ranges are neither mutable nor support 2 dimensions:julia> similar(1:10, 1, 4) 1×4 Array{Int64,2}: 4419743872 4374413872 4419743888 0
Conversely,
similar(trues(10,10), 2)
returns an uninitializedBitVector
with two elements sinceBitArray
s are both mutable and can support 1dimensional arrays:julia> similar(trues(10,10), 2) 2element BitArray{1}: false false
Since
BitArray
s can only store elements of typeBool
, however, if you request a different element type it will create a regularArray
instead:julia> similar(falses(10), Float64, 2, 4) 2×4 Array{Float64,2}: 2.18425e314 2.18425e314 2.18425e314 2.18425e314 2.18425e314 2.18425e314 2.18425e314 2.18425e314

similar
(storagetype, indices) Create an uninitialized mutable array analogous to that specified by
storagetype
, but withindices
specified by the last argument.storagetype
might be a type or a function.Examples:
similar(Array{Int}, indices(A))
creates an array that “acts like” an
Array{Int}
(and might indeed be backed by one), but which is indexed identically toA
. IfA
has conventional indexing, this will be identical toArray{Int}(size(A))
, but ifA
has unconventional indexing then the indices of the result will matchA
.similar(BitArray, (indices(A, 2),))
would create a 1dimensional logical array whose indices match those of the columns of
A
.similar(dims>zeros(Int, dims), indices(A))
would create an array of
Int
, initialized to zero, matching the indices ofA
.

reinterpret
(type, A)¶ Change the typeinterpretation of a block of memory. For example,
reinterpret(Float32, UInt32(7))
interprets the 4 bytes corresponding toUInt32(7)
as aFloat32
. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type.

eye
([T::Type=Float64, ]n::Integer)¶ n
byn
identity matrix. The default element type isFloat64
.

eye
([T::Type=Float64, ]m::Integer, n::Integer) m
byn
identity matrix. The default element type isFloat64
.

eye
(A) Constructs an identity matrix of the same dimensions and type as
A
.julia> A = [1 2 3; 4 5 6; 7 8 9] 3×3 Array{Int64,2}: 1 2 3 4 5 6 7 8 9 julia> eye(A) 3×3 Array{Int64,2}: 1 0 0 0 1 0 0 0 1
Note the difference from
ones()
.

linspace
(start, stop, n=50)¶ Construct a range of
n
linearly spaced elements fromstart
tostop
.

logspace
(start, stop, n=50)¶ Construct a vector of
n
logarithmically spaced numbers from10^start
to10^stop
.
Mathematical operators and functions¶
All mathematical operations and functions are supported for arrays

broadcast
(f, As...)¶ Broadcasts the arrays
As
to a common size by expanding singleton dimensions, and returns an array of the resultsf(as...)
for each position.

broadcast!
(f, dest, As...)¶ Like
broadcast
, but store the result ofbroadcast(f, As...)
in thedest
array. Note thatdest
is only used to store the result, and does not supply arguments tof
unless it is also listed in theAs
, as inbroadcast!(f, A, A, B)
to performA[:] = broadcast(f, A, B)
.

bitbroadcast
(f, As...)¶ Like
broadcast
, but allocates aBitArray
to store the result, rather then anArray
.
Indexing, Assignment, and Concatenation¶

getindex
(A, inds...) Returns a subset of array
A
as specified byinds
, where eachind
may be anInt
, aRange
, or aVector
. See the manual section on array indexing for details.

view
(A, inds...)¶ Like
getindex()
, but returns a view into the parent arrayA
with the given indices instead of making a copy. Callinggetindex()
orsetindex!()
on the returnedSubArray
computes the indices to the parent array on the fly without checking bounds.

@view A[inds...]
Creates a
SubArray
from an indexing expression. This can only be applied directly to a reference expression (e.g.@view A[1,2:end]
), and should not be used as the target of an assignment (e.g.@view(A[1,2:end]) = ...
).

parent
(A)¶ Returns the “parent array” of an array view type (e.g.,
SubArray
), or the array itself if it is not a view.

parentindexes
(A)¶ From an array view
A
, returns the corresponding indexes in the parent.

slicedim
(A, d, i)¶ Return all the data of
A
where the index for dimensiond
equalsi
. Equivalent toA[:,:,...,i,:,:,...]
wherei
is in positiond
.

setindex!
(A, X, inds...)¶ Store values from array
X
within some subset ofA
as specified byinds
.

broadcast_getindex
(A, inds...)¶ Broadcasts the
inds
arrays to a common size likebroadcast
, and returns an array of the resultsA[ks...]
, whereks
goes over the positions in the broadcast.

broadcast_setindex!
(A, X, inds...)¶ Broadcasts the
X
andinds
arrays to a common size and stores the value from each position inX
at the indices given by the same positions ininds
.

isassigned
(array, i) → Bool¶ Tests whether the given array has a value associated with index
i
. Returnsfalse
if the index is out of bounds, or has an undefined reference.

cat
(dims, A...)¶ Concatenate the input arrays along the specified dimensions in the iterable
dims
. For dimensions not indims
, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions indims
, the size of the output array is the sum of the sizes of the input arrays along that dimension. Ifdims
is a single number, the different arrays are tightly stacked along that dimension. Ifdims
is an iterable containing several dimensions, this allows one to construct block diagonal matrices and their higherdimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example,cat([1,2], matrices...)
builds a block diagonal matrix, i.e. a block matrix withmatrices[1]
,matrices[2]
, ... as diagonal blocks and matching zero blocks away from the diagonal.

vcat
(A...)¶ Concatenate along dimension 1.
julia> a = [1 2 3 4 5] 1×5 Array{Int64,2}: 1 2 3 4 5 julia> b = [6 7 8 9 10; 11 12 13 14 15] 2×5 Array{Int64,2}: 6 7 8 9 10 11 12 13 14 15 julia> vcat(a,b) 3×5 Array{Int64,2}: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 julia> c = ([1 2 3], [4 5 6]) ( [1 2 3], [4 5 6]) julia> vcat(c...) 2×3 Array{Int64,2}: 1 2 3 4 5 6

hcat
(A...)¶ Concatenate along dimension 2.
julia> a = [1; 2; 3; 4; 5] 5element Array{Int64,1}: 1 2 3 4 5 julia> b = [6 7; 8 9; 10 11; 12 13; 14 15] 5×2 Array{Int64,2}: 6 7 8 9 10 11 12 13 14 15 julia> hcat(a,b) 5×3 Array{Int64,2}: 1 6 7 2 8 9 3 10 11 4 12 13 5 14 15 julia> c = ([1; 2; 3], [4; 5; 6]) ([1,2,3],[4,5,6]) julia> hcat(c...) 3×2 Array{Int64,2}: 1 4 2 5 3 6

hvcat
(rows::Tuple{Vararg{Int}}, values...)¶ Horizontal and vertical concatenation in one call. This function is called for block matrix syntax. The first argument specifies the number of arguments to concatenate in each block row.
julia> a, b, c, d, e, f = 1, 2, 3, 4, 5, 6 (1,2,3,4,5,6) julia> [a b c; d e f] 2×3 Array{Int64,2}: 1 2 3 4 5 6 julia> hvcat((3,3), a,b,c,d,e,f) 2×3 Array{Int64,2}: 1 2 3 4 5 6 julia> [a b;c d; e f] 3×2 Array{Int64,2}: 1 2 3 4 5 6 julia> hvcat((2,2,2), a,b,c,d,e,f) 3×2 Array{Int64,2}: 1 2 3 4 5 6
If the first argument is a single integer
n
, then all block rows are assumed to haven
block columns.

flipdim
(A, d)¶ Reverse
A
in dimensiond
.julia> b = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> flipdim(b,2) 2×2 Array{Int64,2}: 2 1 4 3

circshift
(A, shifts)¶ Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension.
julia> b = reshape(collect(1:16), (4,4)) 4×4 Array{Int64,2}: 1 5 9 13 2 6 10 14 3 7 11 15 4 8 12 16 julia> circshift(b, (0,2)) 4×4 Array{Int64,2}: 9 13 1 5 10 14 2 6 11 15 3 7 12 16 4 8 julia> circshift(b, (1,0)) 4×4 Array{Int64,2}: 2 6 10 14 3 7 11 15 4 8 12 16 1 5 9 13

find
(A)¶ Return a vector of the linear indexes of the nonzeros in
A
(determined byA[i]!=0
). A common use of this is to convert a boolean array to an array of indexes of thetrue
elements. If there are no nonzero elements ofA
,find
returns an empty array.julia> A = [true false; false true] 2×2 Array{Bool,2}: true false false true julia> find(A) 2element Array{Int64,1}: 1 4

find
(f::Function, A) Return a vector
I
of the linear indexes ofA
wheref(A[I])
returnstrue
. If there are no such elements ofA
, find returns an empty array.julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> find(isodd,A) 2element Array{Int64,1}: 1 2

findn
(A)¶ Return a vector of indexes for each dimension giving the locations of the nonzeros in
A
(determined byA[i]!=0
). If there are no nonzero elements ofA
,findn
returns a 2tuple of empty arrays.julia> A = [1 2 0; 0 0 3; 0 4 0] 3×3 Array{Int64,2}: 1 2 0 0 0 3 0 4 0 julia> findn(A) ([1,1,3,2],[1,2,2,3]) julia> A = zeros(2,2) 2×2 Array{Float64,2}: 0.0 0.0 0.0 0.0 julia> findn(A) (Int64[],Int64[])

findnz
(A)¶ Return a tuple
(I, J, V)
whereI
andJ
are the row and column indexes of the nonzero values in matrixA
, andV
is a vector of the nonzero values.julia> A = [1 2 0; 0 0 3; 0 4 0] 3×3 Array{Int64,2}: 1 2 0 0 0 3 0 4 0 julia> findnz(A) ([1,1,3,2],[1,2,2,3],[1,2,4,3])

findfirst
(A)¶ Return the linear index of the first nonzero value in
A
(determined byA[i]!=0
). Returns0
if no such value is found.julia> A = [0 0; 1 0] 2×2 Array{Int64,2}: 0 0 1 0 julia> findfirst(A) 2

findfirst
(A, v) Return the linear index of the first element equal to
v
inA
. Returns0
ifv
is not found.julia> A = [4 6; 2 2] 2×2 Array{Int64,2}: 4 6 2 2 julia> findfirst(A,2) 2 julia> findfirst(A,3) 0

findfirst
(predicate::Function, A) Return the linear index of the first element of
A
for whichpredicate
returnstrue
. Returns0
if there is no such element.julia> A = [1 4; 2 2] 2×2 Array{Int64,2}: 1 4 2 2 julia> findfirst(iseven, A) 2 julia> findfirst(x > x>10, A) 0

findlast
(A)¶ Return the linear index of the last nonzero value in
A
(determined byA[i]!=0
). Returns0
if there is no nonzero value inA
.julia> A = [1 0; 1 0] 2×2 Array{Int64,2}: 1 0 1 0 julia> findlast(A) 2 julia> A = zeros(2,2) 2×2 Array{Float64,2}: 0.0 0.0 0.0 0.0 julia> findlast(A) 0

findlast
(A, v) Return the linear index of the last element equal to
v
inA
. Returns0
if there is no element ofA
equal tov
.julia> A = [1 2; 2 1] 2×2 Array{Int64,2}: 1 2 2 1 julia> findlast(A,1) 4 julia> findlast(A,2) 3 julia> findlast(A,3) 0

findlast
(predicate::Function, A) Return the linear index of the last element of
A
for whichpredicate
returnstrue
. Returns0
if there is no such element.julia> A = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> findlast(isodd, A) 2 julia> findlast(x > x > 5, A) 0

findnext
(A, i::Integer)¶ Find the next linear index >=
i
of a nonzero element ofA
, or0
if not found.julia> A = [0 0; 1 0] 2×2 Array{Int64,2}: 0 0 1 0 julia> findnext(A,1) 2 julia> findnext(A,3) 0

findnext
(predicate::Function, A, i::Integer) Find the next linear index >=
i
of an element ofA
for whichpredicate
returnstrue
, or0
if not found.julia> A = [1 4; 2 2] 2×2 Array{Int64,2}: 1 4 2 2 julia> findnext(isodd, A, 1) 1 julia> findnext(isodd, A, 2) 0

findnext
(A, v, i::Integer) Find the next linear index >=
i
of an element ofA
equal tov
(using==
), or0
if not found.julia> A = [1 4; 2 2] 2×2 Array{Int64,2}: 1 4 2 2 julia> findnext(A,4,4) 0 julia> findnext(A,4,3) 3

findprev
(A, i::Integer)¶ Find the previous linear index <=
i
of a nonzero element ofA
, or0
if not found.julia> A = [0 0; 1 2] 2×2 Array{Int64,2}: 0 0 1 2 julia> findprev(A,2) 2 julia> findprev(A,1) 0

findprev
(predicate::Function, A, i::Integer) Find the previous linear index <=
i
of an element ofA
for whichpredicate
returnstrue
, or0
if not found.julia> A = [4 6; 1 2] 2×2 Array{Int64,2}: 4 6 1 2 julia> findprev(isodd, A, 1) 0 julia> findprev(isodd, A, 3) 2

findprev
(A, v, i::Integer) Find the previous linear index <=
i
of an element ofA
equal tov
(using==
), or0
if not found.julia> A = [0 0; 1 2] 2×2 Array{Int64,2}: 0 0 1 2 julia> findprev(A, 1, 4) 2 julia> findprev(A, 1, 1) 0

permutedims
(A, perm)¶ Permute the dimensions of array
A
.perm
is a vector specifying a permutation of lengthndims(A)
. This is a generalization of transpose for multidimensional arrays. Transpose is equivalent topermutedims(A, [2,1])
.

ipermutedims
(A, perm)¶ Like
permutedims()
, except the inverse of the given permutation is applied.

permutedims!
(dest, src, perm)¶ Permute the dimensions of array
src
and store the result in the arraydest
.perm
is a vector specifying a permutation of lengthndims(src)
. The preallocated arraydest
should havesize(dest) == size(src)[perm]
and is completely overwritten. No inplace permutation is supported and unexpected results will happen ifsrc
anddest
have overlapping memory regions.

squeeze
(A, dims)¶ Remove the dimensions specified by
dims
from arrayA
. Elements ofdims
must be unique and within the range1:ndims(A)
.size(A,i)
must equal 1 for alli
indims
.julia> a = reshape(collect(1:4),(2,2,1,1)) 2×2×1×1 Array{Int64,4}: [:, :, 1, 1] = 1 3 2 4 julia> squeeze(a,3) 2×2×1 Array{Int64,3}: [:, :, 1] = 1 3 2 4

vec
(a::AbstractArray) → Vector¶ Reshape array
a
as a onedimensional column vector.julia> a = [1 2 3; 4 5 6] 2×3 Array{Int64,2}: 1 2 3 4 5 6 julia> vec(a) 6element Array{Int64,1}: 1 4 2 5 3 6

promote_shape
(s1, s2)¶ Check two array shapes for compatibility, allowing trailing singleton dimensions, and return whichever shape has more dimensions.

checkbounds
(A, I...)¶ Throw an error if the specified indices
I
are not in bounds for the given arrayA
.

checkbounds
(Bool, A, I...) Return
true
if the specified indicesI
are in bounds for the given arrayA
. Subtypes ofAbstractArray
should specialize this method if they need to provide custom bounds checking behaviors; however, in many cases one can rely onA
‘s indices andcheckindex
.See also
checkindex
.

checkindex
(Bool, inds::AbstractUnitRange, index)¶ Return
true
if the givenindex
is within the bounds ofinds
. Custom types that would like to behave as indices for all arrays can extend this method in order to provide a specialized bounds checking implementation.

randsubseq
(A, p) → Vector¶ Return a vector consisting of a random subsequence of the given array
A
, where each element ofA
is included (in order) with independent probabilityp
. (Complexity is linear inp*length(A)
, so this function is efficient even ifp
is small andA
is large.) Technically, this process is known as “Bernoulli sampling” ofA
.

randsubseq!
(S, A, p)¶ Like
randsubseq
, but the results are stored inS
(which is resized as needed).
Array functions¶

cumprod
(A, dim=1)¶ Cumulative product along a dimension
dim
(defaults to 1). See alsocumprod!()
to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow).julia> a = [1 2 3; 4 5 6] 2×3 Array{Int64,2}: 1 2 3 4 5 6 julia> cumprod(a,1) 2×3 Array{Int64,2}: 1 2 3 4 10 18 julia> cumprod(a,2) 2×3 Array{Int64,2}: 1 2 6 4 20 120

cumprod!
(B, A[, dim])¶ Cumulative product of
A
along a dimension, storing the result inB
. The dimension defaults to 1.

cumsum
(A, dim=1)¶ Cumulative sum along a dimension
dim
(defaults to 1). See alsocumsum!()
to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow).julia> a = [1 2 3; 4 5 6] 2×3 Array{Int64,2}: 1 2 3 4 5 6 julia> cumsum(a,1) 2×3 Array{Int64,2}: 1 2 3 5 7 9 julia> cumsum(a,2) 2×3 Array{Int64,2}: 1 3 6 4 9 15

cumsum!
(B, A[, dim])¶ Cumulative sum of
A
along a dimension, storing the result inB
. The dimension defaults to 1.

cumsum_kbn
(A[, dim])¶ Cumulative sum along a dimension, using the KahanBabuskaNeumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1.

cummin
(A[, dim])¶ Cumulative minimum along a dimension. The dimension defaults to 1.

cummax
(A[, dim])¶ Cumulative maximum along a dimension. The dimension defaults to 1.

diff
(A[, dim])¶ Finite difference operator of matrix or vector.

gradient
(F[, h])¶ Compute differences along vector
F
, usingh
as the spacing between points. The default spacing is one.

rot180
(A)¶ Rotate matrix
A
180 degrees.julia> a = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> rot180(a) 2×2 Array{Int64,2}: 4 3 2 1

rot180
(A, k) Rotate matrix
A
180 degrees an integerk
number of times. Ifk
is even, this is equivalent to acopy
.julia> a = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> rot180(a,1) 2×2 Array{Int64,2}: 4 3 2 1 julia> rot180(a,2) 2×2 Array{Int64,2}: 1 2 3 4

rotl90
(A)¶ Rotate matrix
A
left 90 degrees.julia> a = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> rotl90(a) 2×2 Array{Int64,2}: 2 4 1 3

rotl90
(A, k) Rotate matrix
A
left 90 degrees an integerk
number of times. Ifk
is zero or a multiple of four, this is equivalent to acopy
.julia> a = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> rotl90(a,1) 2×2 Array{Int64,2}: 2 4 1 3 julia> rotl90(a,2) 2×2 Array{Int64,2}: 4 3 2 1 julia> rotl90(a,3) 2×2 Array{Int64,2}: 3 1 4 2 julia> rotl90(a,4) 2×2 Array{Int64,2}: 1 2 3 4

rotr90
(A)¶ Rotate matrix
A
right 90 degrees.julia> a = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> rotr90(a) 2×2 Array{Int64,2}: 3 1 4 2

rotr90
(A, k) Rotate matrix
A
right 90 degrees an integerk
number of times. Ifk
is zero or a multiple of four, this is equivalent to acopy
.julia> a = [1 2; 3 4] 2×2 Array{Int64,2}: 1 2 3 4 julia> rotr90(a,1) 2×2 Array{Int64,2}: 3 1 4 2 julia> rotr90(a,2) 2×2 Array{Int64,2}: 4 3 2 1 julia> rotr90(a,3) 2×2 Array{Int64,2}: 2 4 1 3 julia> rotr90(a,4) 2×2 Array{Int64,2}: 1 2 3 4

reducedim
(f, A, region[, v0])¶ Reduce 2argument function
f
along dimensions ofA
.region
is a vector specifying the dimensions to reduce, andv0
is the initial value to use in the reductions. For+
,*
,max
andmin
thev0
argument is optional.The associativity of the reduction is implementationdependent; if you need a particular associativity, e.g. lefttoright, you should write your own loop. See documentation for
reduce()
.julia> a = reshape(collect(1:16), (4,4)) 4×4 Array{Int64,2}: 1 5 9 13 2 6 10 14 3 7 11 15 4 8 12 16 julia> reducedim(max, a, 2) 4×1 Array{Int64,2}: 13 14 15 16 julia> reducedim(max, a, 1) 1×4 Array{Int64,2}: 4 8 12 16

mapreducedim
(f, op, A, region[, v0])¶ Evaluates to the same as
reducedim(op, map(f, A), region, f(v0))
, but is generally faster because the intermediate array is avoided.julia> a = reshape(collect(1:16), (4,4)) 4×4 Array{Int64,2}: 1 5 9 13 2 6 10 14 3 7 11 15 4 8 12 16 julia> mapreducedim(isodd, *, a, 1) 1×4 Array{Bool,2}: false false false false julia> mapreducedim(isodd, , a, 1, true) 1×4 Array{Bool,2}: true true true true

mapslices
(f, A, dims)¶ Transform the given dimensions of array
A
using functionf
.f
is called on each slice ofA
of the formA[...,:,...,:,...]
.dims
is an integer vector specifying where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, ifdims
is[1,2]
andA
is 4dimensional,f
is called onA[:,:,i,j]
for alli
andj
.julia> a = reshape(collect(1:16),(2,2,2,2)) 2×2×2×2 Array{Int64,4}: [:, :, 1, 1] = 1 3 2 4 [:, :, 2, 1] = 5 7 6 8 [:, :, 1, 2] = 9 11 10 12 [:, :, 2, 2] = 13 15 14 16 julia> mapslices(sum, a, [1,2]) 1×1×2×2 Array{Int64,4}: [:, :, 1, 1] = 10 [:, :, 2, 1] = 26 [:, :, 1, 2] = 42 [:, :, 2, 2] = 58

sum_kbn
(A)¶ Returns the sum of all array elements, using the KahanBabuskaNeumaier compensated summation algorithm for additional accuracy.
Combinatorics¶

randperm
([rng, ]n)¶ Construct a random permutation of length
n
. The optionalrng
argument specifies a random number generator (see Random Numbers). To randomly permute a arbitrary vector, seeshuffle()
orshuffle!()
.

invperm
(v)¶ Return the inverse permutation of
v

isperm
(v) → Bool¶ Returns
true
ifv
is a valid permutation.

permute!
(v, p)¶ Permute vector
v
inplace, according to permutationp
. No checking is done to verify thatp
is a permutation.To return a new permutation, use
v[p]
. Note that this is generally faster thanpermute!(v,p)
for large vectors.

ipermute!
(v, p)¶ Like
permute!
, but the inverse of the given permutation is applied.

randcycle
([rng, ]n)¶ Construct a random cyclic permutation of length
n
. The optionalrng
argument specifies a random number generator, see Random Numbers.

shuffle
([rng, ]v)¶ Return a randomly permuted copy of
v
. The optionalrng
argument specifies a random number generator (see Random Numbers). To permutev
inplace, seeshuffle!()
. To obtain randomly permuted indices, seerandperm()
.

shuffle!
([rng, ]v)¶ Inplace version of
shuffle()
: randomly permute the arrayv
inplace, optionally supplying the randomnumber generatorrng
.

reverse
(v[, start=1[, stop=length(v)]])¶ Return a copy of
v
reversed from start to stop.

reverseind
(v, i)¶ Given an index
i
inreverse(v)
, return the corresponding index inv
so thatv[reverseind(v,i)] == reverse(v)[i]
. (This can be nontrivial in the case wherev
is a Unicode string.)
BitArrays¶
BitArrays are spaceefficient “packed” boolean arrays, which store
one bit per boolean value. They can be used similarly to Array{Bool}
arrays (which store one byte per boolean value), and can be converted
to/from the latter via Array(bitarray)
and BitArray(array)
, respectively.

flipbits!
(B::BitArray{N}) → BitArray{N}¶ Performs a bitwise not operation on
B
. See ~ operator.julia> A = trues(2,2) 2×2 BitArray{2}: true true true true julia> flipbits!(A) 2×2 BitArray{2}: false false false false

rol!
(dest::BitVector, src::BitVector, i::Integer) → BitVector¶ Performs a left rotation operation on
src
and puts the result intodest
.i
controls how far to rotate the bits.

rol!
(B::BitVector, i::Integer) → BitVector Performs a left rotation operation inplace on
B
.i
controls how far to rotate the bits.

rol
(B::BitVector, i::Integer) → BitVector¶ Performs a left rotation operation, returning a new
BitVector
.i
controls how far to rotate the bits. See alsorol!()
.julia> A = BitArray([true, true, false, false, true]) 5element BitArray{1}: true true false false true julia> rol(A,1) 5element BitArray{1}: true false false true true julia> rol(A,2) 5element BitArray{1}: false false true true true julia> rol(A,5) 5element BitArray{1}: true true false false true

ror!
(dest::BitVector, src::BitVector, i::Integer) → BitVector¶ Performs a right rotation operation on
src
and puts the result intodest
.i
controls how far to rotate the bits.

ror!
(B::BitVector, i::Integer) → BitVector Performs a right rotation operation inplace on
B
.i
controls how far to rotate the bits.

ror
(B::BitVector, i::Integer) → BitVector¶ Performs a right rotation operation on
B
, returning a newBitVector
.i
controls how far to rotate the bits. See alsoror!()
.julia> A = BitArray([true, true, false, false, true]) 5element BitArray{1}: true true false false true julia> ror(A,1) 5element BitArray{1}: true true true false false julia> ror(A,2) 5element BitArray{1}: false true true true false julia> ror(A,5) 5element BitArray{1}: true true false false true
Sparse Vectors and Matrices¶
Sparse vectors and matrices largely support the same set of operations as their dense counterparts. The following functions are specific to sparse arrays.

sparse
(I, J, V[, m, n, combine])¶ Create a sparse matrix
S
of dimensionsm x n
such thatS[I[k], J[k]] = V[k]
. Thecombine
function is used to combine duplicates. Ifm
andn
are not specified, they are set tomaximum(I)
andmaximum(J)
respectively. If thecombine
function is not supplied,combine
defaults to+
unless the elements ofV
are Booleans in which casecombine
defaults to
. All elements ofI
must satisfy1 <= I[k] <= m
, and all elements ofJ
must satisfy1 <= J[k] <= n
. Numerical zeros in (I
,J
,V
) are retained as structural nonzeros; to drop numerical zeros, usedropzeros!()
.For additional documentation and an expert driver, see
Base.SparseArrays.sparse!
.

sparsevec
(I, V[, m, combine])¶ Create a sparse vector
S
of lengthm
such thatS[I[k]] = V[k]
. Duplicates are combined using thecombine
function, which defaults to+
if nocombine
argument is provided, unless the elements ofV
are Booleans in which casecombine
defaults to
.

sparsevec
(D::Dict[, m]) Create a sparse vector of length
m
where the nonzero indices are keys from the dictionary, and the nonzero values are the values from the dictionary.

issparse
(S)¶ Returns
true
ifS
is sparse, andfalse
otherwise.

sparse
(A) Convert an AbstractMatrix
A
into a sparse matrix.

sparsevec
(A) Convert a vector
A
into a sparse vector of lengthm
.

full
(S)¶ Convert a sparse matrix or vector
S
into a dense matrix or vector.

nnz
(A)¶ Returns the number of stored (filled) elements in a sparse array.

spzeros
([type, ]m[, n])¶ Create a sparse vector of length
m
or sparse matrix of sizem x n
. This sparse array will not contain any nonzero values. No storage will be allocated for nonzero values during construction. The type defaults toFloat64
if not specified.

spones
(S)¶ Create a sparse array with the same structure as that of
S
, but with every nonzero element having the value1.0
.julia> A = sparse([1,2,3,4],[2,4,3,1],[5.,4.,3.,2.]) 4×4 sparse matrix with 4 Float64 nonzero entries: [4, 1] = 2.0 [1, 2] = 5.0 [3, 3] = 3.0 [2, 4] = 4.0 julia> spones(A) 4×4 sparse matrix with 4 Float64 nonzero entries: [4, 1] = 1.0 [1, 2] = 1.0 [3, 3] = 1.0 [2, 4] = 1.0
Note the difference from
speye()
.

speye
([type, ]m[, n])¶ Create a sparse identity matrix of size
m x m
. Whenn
is supplied, create a sparse identity matrix of sizem x n
. The type defaults toFloat64
if not specified.

speye
(S) Create a sparse identity matrix with the same size as
S
.julia> A = sparse([1,2,3,4],[2,4,3,1],[5.,4.,3.,2.]) 4×4 sparse matrix with 4 Float64 nonzero entries: [4, 1] = 2.0 [1, 2] = 5.0 [3, 3] = 3.0 [2, 4] = 4.0 julia> speye(A) 4×4 sparse matrix with 4 Float64 nonzero entries: [1, 1] = 1.0 [2, 2] = 1.0 [3, 3] = 1.0 [4, 4] = 1.0
Note the difference from
spones()
.

spdiagm
(B, d[, m, n])¶ Construct a sparse diagonal matrix.
B
is a tuple of vectors containing the diagonals andd
is a tuple containing the positions of the diagonals. In the case the input contains only one diagonal,B
can be a vector (instead of a tuple) andd
can be the diagonal position (instead of a tuple), defaulting to 0 (diagonal). Optionally,m
andn
specify the size of the resulting sparse matrix.julia> spdiagm(([1,2,3,4],[4,3,2,1]),(1,1)) 5×5 sparse matrix with 8 Int64 nonzero entries: [2, 1] = 1 [1, 2] = 4 [3, 2] = 2 [2, 3] = 3 [4, 3] = 3 [3, 4] = 2 [5, 4] = 4 [4, 5] = 1

sprand
([rng, ][type, ]m, [n, ]p::AbstractFloat[, rfn])¶ Create a random length
m
sparse vector orm
byn
sparse matrix, in which the probability of any element being nonzero is independently given byp
(and hence the mean density of nonzeros is also exactlyp
). Nonzero values are sampled from the distribution specified byrfn
and have the typetype
. The uniform distribution is used in caserfn
is not specified. The optionalrng
argument specifies a random number generator, see Random Numbers.

sprandn
([rng, ]m, [n, ]p::AbstractFloat)¶ Create a random sparse vector of length
m
or sparse matrix of sizem
byn
with the specified (independent) probabilityp
of any entry being nonzero, where nonzero values are sampled from the normal distribution. The optionalrng
argument specifies a random number generator, see Random Numbers.

nonzeros
(A)¶ Return a vector of the structural nonzero values in sparse array
A
. This includes zeros that are explicitly stored in the sparse array. The returned vector points directly to the internal nonzero storage ofA
, and any modifications to the returned vector will mutateA
as well. Seerowvals()
andnzrange()
.

rowvals
(A::SparseMatrixCSC)¶ Return a vector of the row indices of
A
. Any modifications to the returned vector will mutateA
as well. Providing access to how the row indices are stored internally can be useful in conjunction with iterating over structural nonzero values. See alsononzeros()
andnzrange()
.

nzrange
(A::SparseMatrixCSC, col)¶ Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with
nonzeros()
androwvals()
, this allows for convenient iterating over a sparse matrix :A = sparse(I,J,V) rows = rowvals(A) vals = nonzeros(A) m, n = size(A) for i = 1:n for j in nzrange(A, i) row = rows[j] val = vals[j] # perform sparse wizardry... end end

dropzeros!
(A::SparseMatrixCSC, trim::Bool = true)¶ Removes stored numerical zeros from
A
, optionally trimming resulting excess space fromA.rowval
andA.nzval
whentrim
istrue
.For an outofplace version, see
dropzeros()
. For algorithmic information, seeBase.SparseArrays.fkeep!()
.

dropzeros
(A::SparseMatrixCSC, trim::Bool = true)¶ Generates a copy of
A
and removes stored numerical zeros from that copy, optionally trimming excess space from the result’srowval
andnzval
arrays whentrim
istrue
.For an inplace version and algorithmic information, see
dropzeros!()
.

dropzeros!
(x::SparseVector, trim::Bool = true) Removes stored numerical zeros from
x
, optionally trimming resulting excess space fromx.nzind
andx.nzval
whentrim
istrue
.For an outofplace version, see
Base.SparseArrays.dropzeros()
. For algorithmic information, seeBase.SparseArrays.fkeep!()
.

dropzeros
(x::SparseVector, trim::Bool = true) Generates a copy of
x
and removes numerical zeros from that copy, optionally trimming excess space from the result’snzind
andnzval
arrays whentrim
istrue
.For an inplace version and algorithmic information, see
Base.SparseArrays.dropzeros!()
.

permute{Tv,Ti,Tp<:Integer,Tq<:Integer}(A::SparseMatrixCSC{Tv,Ti}, p::AbstractVector{Tp},

q::AbstractVector{Tq})
()¶ Bilaterally permute
A
, returningPAQ
(A[p,q]
). Columnpermutationq
‘s length must matchA
‘s column count (length(q) == A.n
). Rowpermutationp
‘s length must matchA
‘s row count (length(p) == A.m
).For expert drivers and additional information, see
Base.SparseArrays.permute!()
.

permute!{Tv,Ti,Tp<:Integer,Tq<:Integer}(X::SparseMatrixCSC{Tv,Ti}, A::SparseMatrixCSC{Tv,Ti},

p::AbstractVector{Tp}, q::AbstractVector{Tq}[, C::SparseMatrixCSC{Tv,Ti}])
Bilaterally permute
A
, storing resultPAQ
(A[p,q]
) inX
. Stores intermediate result(AQ)^T
(transpose(A[:,q])
) in optional argumentC
if present. Requires that none ofX
,A
, and, if present,C
alias each other; to store resultPAQ
back intoA
, use the following method lackingX
:permute!{Tv,Ti,Tp<:Integer,Tq<:Integer}(A::SparseMatrixCSC{Tv,Ti}, p::AbstractVector{Tp}, q::AbstractVector{Tq}[, C::SparseMatrixCSC{Tv,Ti}[, workcolptr::Vector{Ti}]])
X
‘s dimensions must match those ofA
(X.m == A.m
andX.n == A.n
), andX
must have enough storage to accommodate all allocated entries inA
(length(X.rowval) >= nnz(A)
andlength(X.nzval) >= nnz(A)
). Columnpermutationq
‘s length must matchA
‘s column count (length(q) == A.n
). Rowpermutationp
‘s length must matchA
‘s row count (length(p) == A.m
).C
‘s dimensions must match those oftranspose(A)
(C.m == A.n
andC.n == A.m
), andC
must have enough storage to accommodate all allocated entries inA
(length(C.rowval)
>= nnz(A)``and``length(C.nzval) >= nnz(A)`).For additional (algorithmic) information, and for versions of these methods that forgo argument checking, see (unexported) parent methods
Base.SparseArrays.unchecked_noalias_permute!()
andBase.SparseArrays.unchecked_aliasing_permute!()
.See also:
Base.SparseArrays.permute()