From b2663f115e552e68134b31a208e76e840474adf8 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Tue, 23 Jun 2015 00:48:49 -0400 Subject: [PATCH 01/27] helpdb conversion --- base/docs/helpdb.jl | 16114 ++++++++++++++++++++++++++++++++++++++++++ base/sysimg.jl | 1 + doc/newdoc.jl | 21 + 3 files changed, 16136 insertions(+) create mode 100644 base/docs/helpdb.jl create mode 100644 doc/newdoc.jl diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl new file mode 100644 index 0000000000000..bf022f5357224 --- /dev/null +++ b/base/docs/helpdb.jl @@ -0,0 +1,16114 @@ + @doc doc""" + ```rst + ndims(A) -> Integer + + Returns the number of dimensions of A + ``` + """ Base.ndims + + @doc doc""" + ```rst + size(A[, 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 = rand(2,3,4); + + julia> size(A, 2) + 3 + + julia> size(A,3,2) + (4,3) + ``` + """ Base.size + + @doc doc""" + ```rst + iseltype(A, T) + + Tests whether A or its elements are of type T + ``` + """ Base.iseltype + + @doc doc""" + ```rst + length(A) -> Integer + + Returns the number of elements in A + ``` + """ Base.length + + @doc doc""" + ```rst + 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 (like "Array"), this is + simply the range "1:length(A)". For other array types, this + returns a specialized Cartesian range to efficiently index into the + array with indices specified for every dimension. Example for a + sparse 2-d array: + + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 + ``` + """ Base.eachindex + + @doc doc""" + ```rst + Base.linearindexing(A) + + "linearindexing" defines how an AbstractArray most efficiently + accesses its elements. If "Base.linearindexing(A)" returns + "Base.LinearFast()", this means that linear indexing with only + one index is an efficient operation. If it instead returns + "Base.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 + traits-based 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 define "linearindexing" in the + type-domain: + + Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() + ``` + """ Base.Base + + @doc doc""" + ```rst + countnz(A) + + Counts the number of nonzero values in array A (dense or sparse). + Note that this is not a constant-time operation. For sparse + matrices, one should usually use "nnz", which returns the number + of stored values. + ``` + """ Base.countnz + + @doc doc""" + ```rst + conj!(A) + + Convert an array to its complex conjugate in-place + ``` + """ Base.conj! + + @doc doc""" + ```rst + stride(A, k) + + Returns the distance in memory (in number of elements) between + adjacent elements in dimension k + ``` + """ Base.stride + + @doc doc""" + ```rst + strides(A) + + Returns a tuple of the memory strides in each dimension + ``` + """ Base.strides + + @doc doc""" + ```rst + ind2sub(dims, index) -> subscripts + + Returns a tuple of subscripts into an array with dimensions + "dims", corresponding to the linear index "index" + + **Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides + the indices of the maximum element + ``` + """ Base.ind2sub + + @doc doc""" + ```rst + ind2sub(a, index) -> subscripts + + Returns a tuple of subscripts into array "a" corresponding to the + linear index "index" + ``` + """ Base.ind2sub + + @doc doc""" + ```rst + sub2ind(dims, i, j, k...) -> index + + The inverse of "ind2sub", returns the linear index corresponding + to the provided subscripts + ``` + """ Base.sub2ind + + @doc doc""" + ```rst + Array(dims) + + "Array{T}(dims)" constructs an uninitialized dense array with + element type "T". "dims" may be a tuple or a series of integer + arguments. The syntax "Array(T, dims)" is also available, but + deprecated. + ``` + """ Base.Array + + @doc doc""" + ```rst + getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called + with the syntax "Type[]". Element values can be specified using + "Type[a,b,c,...]". + ``` + """ Base.getindex + + @doc doc""" + ```rst + cell(dims) + + Construct an uninitialized cell array (heterogeneous array). + "dims" can be either a tuple or a series of integer arguments. + ``` + """ Base.cell + + @doc doc""" + ```rst + zeros(type, dims) + + Create an array of all zeros of specified type. The type defaults + to Float64 if not specified. + ``` + """ Base.zeros + + @doc doc""" + ```rst + zeros(A) + + Create an array of all zeros with the same element type and shape + as A. + ``` + """ Base.zeros + + @doc doc""" + ```rst + ones(type, dims) + + Create an array of all ones of specified type. The type defaults to + Float64 if not specified. + ``` + """ Base.ones + + @doc doc""" + ```rst + ones(A) + + Create an array of all ones with the same element type and shape as + A. + ``` + """ Base.ones + + @doc doc""" + ```rst + trues(dims) + + Create a "BitArray" with all values set to true + ``` + """ Base.trues + + @doc doc""" + ```rst + falses(dims) + + Create a "BitArray" with all values set to false + ``` + """ Base.falses + + @doc doc""" + ```rst + fill(x, dims) + + Create an array filled with the value "x". For example, + "fill(1.0, (10,10))" returns a 10x10 array of floats, with each + element initialized to 1.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 evaluating "Foo()" once. + ``` + """ Base.fill + + @doc doc""" + ```rst + fill!(A, x) + + Fill array "A" with the value "x". If "x" is an object + reference, all elements will refer to the same object. "fill!(A, + Foo())" will return "A" filled with the result of evaluating + "Foo()" once. + ``` + """ Base.fill! + + @doc doc""" + ```rst + reshape(A, dims) + + Create an array with the same data as the given array, but with + different dimensions. An implementation for a particular type of + array may choose whether the data is copied or shared. + ``` + """ Base.reshape + + @doc doc""" + ```rst + similar(array, element_type, dims) + + Create an uninitialized array of the same type as the given array, + but with the specified element type and dimensions. The second and + third arguments are both optional. The "dims" argument may be a + tuple or a series of integer arguments. For some special + "AbstractArray" objects which are not real containers (like + ranges), this function returns a standard "Array" to allow + operating on elements. + ``` + """ Base.similar + + @doc doc""" + ```rst + reinterpret(type, A) + + Change the type-interpretation of a block of memory. For example, + "reinterpret(Float32, UInt32(7))" interprets the 4 bytes + corresponding to "UInt32(7)" as a "Float32". For arrays, this + constructs an array with the same binary data as the given array, + but with the specified element type. + ``` + """ Base.reinterpret + + @doc doc""" + ```rst + eye(n) + + n-by-n identity matrix + ``` + """ Base.eye + + @doc doc""" + ```rst + eye(m, n) + + m-by-n identity matrix + ``` + """ Base.eye + + @doc doc""" + ```rst + eye(A) + + Constructs an identity matrix of the same dimensions and type as + "A". + ``` + """ Base.eye + + @doc doc""" + ```rst + linspace(start, stop, n=100) + + Construct a range of "n" linearly spaced elements from "start" + to "stop". + ``` + """ Base.linspace + + @doc doc""" + ```rst + logspace(start, stop, n=50) + + Construct a vector of "n" logarithmically spaced numbers from + "10^start" to "10^stop". + ``` + """ Base.logspace + + @doc doc""" + ```rst + broadcast(f, As...) + + Broadcasts the arrays "As" to a common size by expanding + singleton dimensions, and returns an array of the results + "f(as...)" for each position. + ``` + """ Base.broadcast + + @doc doc""" + ```rst + broadcast!(f, dest, As...) + + Like "broadcast", but store the result of "broadcast(f, As...)" + in the "dest" array. Note that "dest" is only used to store the + result, and does not supply arguments to "f" unless it is also + listed in the "As", as in "broadcast!(f, A, A, B)" to perform + "A[:] = broadcast(f, A, B)". + ``` + """ Base.broadcast! + + @doc doc""" + ```rst + bitbroadcast(f, As...) + + Like "broadcast", but allocates a "BitArray" to store the + result, rather then an "Array". + ``` + """ Base.bitbroadcast + + @doc doc""" + ```rst + broadcast_function(f) + + Returns a function "broadcast_f" such that + "broadcast_function(f)(As...) === broadcast(f, As...)". Most + useful in the form "const broadcast_f = broadcast_function(f)". + ``` + """ Base.broadcast_function + + @doc doc""" + ```rst + broadcast!_function(f) + + Like "broadcast_function", but for "broadcast!". + ``` + """ Base.broadcast!_function + + @doc doc""" + ```rst + getindex(A, inds...) + + Returns a subset of array "A" as specified by "inds", where + each "ind" may be an "Int", a "Range", or a "Vector". See + the manual section on *array indexing* for details. + ``` + """ Base.getindex + + @doc doc""" + ```rst + sub(A, inds...) + + Like "getindex()", but returns a view into the parent array "A" + with the given indices instead of making a copy. Calling + "getindex()" or "setindex!()" on the returned "SubArray" + computes the indices to the parent array on the fly without + checking bounds. + ``` + """ Base.sub + + @doc doc""" + ```rst + parent(A) + + Returns the "parent array" of an array view type (e.g., + SubArray), or the array itself if it is not a view + ``` + """ Base.parent + + @doc doc""" + ```rst + parentindexes(A) + + From an array view "A", returns the corresponding indexes in the + parent + ``` + """ Base.parentindexes + + @doc doc""" + ```rst + slicedim(A, d, i) + + Return all the data of "A" where the index for dimension "d" + equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is + in position "d". + ``` + """ Base.slicedim + + @doc doc""" + ```rst + slice(A, inds...) + + Returns a view of array "A" with the given indices like + "sub()", but drops all dimensions indexed with scalars. + ``` + """ Base.slice + + @doc doc""" + ```rst + setindex!(A, X, inds...) + + Store values from array "X" within some subset of "A" as + specified by "inds". + ``` + """ Base.setindex! + + @doc doc""" + ```rst + broadcast_getindex(A, inds...) + + Broadcasts the "inds" arrays to a common size like "broadcast", + and returns an array of the results "A[ks...]", where "ks" goes + over the positions in the broadcast. + ``` + """ Base.broadcast_getindex + + @doc doc""" + ```rst + broadcast_setindex!(A, X, inds...) + + Broadcasts the "X" and "inds" arrays to a common size and + stores the value from each position in "X" at the indices given + by the same positions in "inds". + ``` + """ Base.broadcast_setindex! + + @doc doc""" + ```rst + cat(dims, A...) + + Concatenate the input arrays along the specified dimensions in the + iterable "dims". For dimensions not in "dims", all input arrays + should have the same size, which will also be the size of the + output array along that dimension. For dimensions in "dims", the + size of the output array is the sum of the sizes of the input + arrays along that dimension. If "dims" is a single number, the + different arrays are tightly stacked along that dimension. If + "dims" is an iterable containing several dimensions, this allows + to construct block diagonal matrices and their higher-dimensional + 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 with *matrices[1]*, *matrices[2]*, ... as diagonal + blocks and matching zero blocks away from the diagonal. + ``` + """ Base.cat + + @doc doc""" + ```rst + vcat(A...) + + Concatenate along dimension 1 + ``` + """ Base.vcat + + @doc doc""" + ```rst + hcat(A...) + + Concatenate along dimension 2 + ``` + """ Base.hcat + + @doc doc""" + ```rst + 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. For example, + "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". + + If the first argument is a single integer "n", then all block + rows are assumed to have "n" block columns. + ``` + """ Base.hvcat + + @doc doc""" + ```rst + flipdim(A, d) + + Reverse "A" in dimension "d". + ``` + """ Base.flipdim + + @doc doc""" + ```rst + circshift(A, shifts) + + Circularly shift the data in an array. The second argument is a + vector giving the amount to shift in each dimension. + ``` + """ Base.circshift + + @doc doc""" + ```rst + find(A) + + Return a vector of the linear indexes of the non-zeros in "A" + (determined by "A[i]!=0"). A common use of this is to convert a + boolean array to an array of indexes of the "true" elements. + ``` + """ Base.find + + @doc doc""" + ```rst + find(f, A) + + Return a vector of the linear indexes of "A" where "f" returns + true. + ``` + """ Base.find + + @doc doc""" + ```rst + findn(A) + + Return a vector of indexes for each dimension giving the locations + of the non-zeros in "A" (determined by "A[i]!=0"). + ``` + """ Base.findn + + @doc doc""" + ```rst + findnz(A) + + Return a tuple "(I, J, V)" where "I" and "J" are the row and + column indexes of the non-zero values in matrix "A", and "V" is + a vector of the non-zero values. + ``` + """ Base.findnz + + @doc doc""" + ```rst + findfirst(A) + + Return the index of the first non-zero value in "A" (determined + by "A[i]!=0"). + ``` + """ Base.findfirst + + @doc doc""" + ```rst + findfirst(A, v) + + Return the index of the first element equal to "v" in "A". + ``` + """ Base.findfirst + + @doc doc""" + ```rst + findfirst(predicate, A) + + Return the index of the first element of "A" for which + "predicate" returns true. + ``` + """ Base.findfirst + + @doc doc""" + ```rst + findlast(A) + + Return the index of the last non-zero value in "A" (determined by + "A[i]!=0"). + ``` + """ Base.findlast + + @doc doc""" + ```rst + findlast(A, v) + + Return the index of the last element equal to "v" in "A". + ``` + """ Base.findlast + + @doc doc""" + ```rst + findlast(predicate, A) + + Return the index of the last element of "A" for which + "predicate" returns true. + ``` + """ Base.findlast + + @doc doc""" + ```rst + findnext(A, i) + + Find the next index >= "i" of a non-zero element of "A", or + "0" if not found. + ``` + """ Base.findnext + + @doc doc""" + ```rst + findnext(predicate, A, i) + + Find the next index >= "i" of an element of "A" for which + "predicate" returns true, or "0" if not found. + ``` + """ Base.findnext + + @doc doc""" + ```rst + findnext(A, v, i) + + Find the next index >= "i" of an element of "A" equal to "v" + (using "=="), or "0" if not found. + ``` + """ Base.findnext + + @doc doc""" + ```rst + findprev(A, i) + + Find the previous index <= "i" of a non-zero element of "A", or + 0 if not found. + ``` + """ Base.findprev + + @doc doc""" + ```rst + findprev(predicate, A, i) + + Find the previous index <= "i" of an element of "A" for which + "predicate" returns true, or "0" if not found. + ``` + """ Base.findprev + + @doc doc""" + ```rst + findprev(A, v, i) + + Find the previous index <= "i" of an element of "A" equal to + "v" (using "=="), or "0" if not found. + ``` + """ Base.findprev + + @doc doc""" + ```rst + permutedims(A, perm) + + Permute the dimensions of array "A". "perm" is a vector + specifying a permutation of length "ndims(A)". This is a + generalization of transpose for multi-dimensional arrays. Transpose + is equivalent to "permutedims(A, [2,1])". + ``` + """ Base.permutedims + + @doc doc""" + ```rst + ipermutedims(A, perm) + + Like "permutedims()", except the inverse of the given permutation + is applied. + ``` + """ Base.ipermutedims + + @doc doc""" + ```rst + permutedims!(dest, src, perm) + + Permute the dimensions of array "src" and store the result in the + array "dest". "perm" is a vector specifying a permutation of + length "ndims(src)". The preallocated array "dest" should have + "size(dest) == size(src)[perm]" and is completely overwritten. No + in-place permutation is supported and unexpected results will + happen if *src* and *dest* have overlapping memory regions. + ``` + """ Base.permutedims! + + @doc doc""" + ```rst + squeeze(A, dims) + + Remove the dimensions specified by "dims" from array "A". + Elements of "dims" must be unique and within the range + "1:ndims(A)". + ``` + """ Base.squeeze + + @doc doc""" + ```rst + vec(Array) -> Vector + + Vectorize an array using column-major convention. + ``` + """ Base.vec + + @doc doc""" + ```rst + promote_shape(s1, s2) + + Check two array shapes for compatibility, allowing trailing + singleton dimensions, and return whichever shape has more + dimensions. + ``` + """ Base.promote_shape + + @doc doc""" + ```rst + checkbounds(array, indexes...) + + Throw an error if the specified indexes are not in bounds for the + given array. + ``` + """ Base.checkbounds + + @doc doc""" + ```rst + randsubseq(A, p) -> Vector + + Return a vector consisting of a random subsequence of the given + array "A", where each element of "A" is included (in order) + with independent probability "p". (Complexity is linear in + "p*length(A)", so this function is efficient even if "p" is + small and "A" is large.) Technically, this process is known as + "Bernoulli sampling" of "A". + ``` + """ Base.randsubseq + + @doc doc""" + ```rst + randsubseq!(S, A, p) + + Like "randsubseq", but the results are stored in "S" (which is + resized as needed). + ``` + """ Base.randsubseq! + + @doc doc""" + ```rst + cumprod(A[, dim]) + + Cumulative product along a dimension "dim" (defaults to 1). See + also "cumprod!()" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). + ``` + """ Base.cumprod + + @doc doc""" + ```rst + cumprod!(B, A[, dim]) + + Cumulative product of "A" along a dimension, storing the result + in "B". The dimension defaults to 1. + ``` + """ Base.cumprod! + + @doc doc""" + ```rst + cumsum(A[, dim]) + + Cumulative sum along a dimension "dim" (defaults to 1). See also + "cumsum!()" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). + ``` + """ Base.cumsum + + @doc doc""" + ```rst + cumsum!(B, A[, dim]) + + Cumulative sum of "A" along a dimension, storing the result in + "B". The dimension defaults to 1. + ``` + """ Base.cumsum! + + @doc doc""" + ```rst + cumsum_kbn(A[, dim]) + + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier + compensated summation algorithm for additional accuracy. The + dimension defaults to 1. + ``` + """ Base.cumsum_kbn + + @doc doc""" + ```rst + cummin(A[, dim]) + + Cumulative minimum along a dimension. The dimension defaults to 1. + ``` + """ Base.cummin + + @doc doc""" + ```rst + cummax(A[, dim]) + + Cumulative maximum along a dimension. The dimension defaults to 1. + ``` + """ Base.cummax + + @doc doc""" + ```rst + diff(A[, dim]) + + Finite difference operator of matrix or vector. + ``` + """ Base.diff + + @doc doc""" + ```rst + gradient(F[, h]) + + Compute differences along vector "F", using "h" as the spacing + between points. The default spacing is one. + ``` + """ Base.gradient + + @doc doc""" + ```rst + rot180(A) + + Rotate matrix "A" 180 degrees. + ``` + """ Base.rot180 + + @doc doc""" + ```rst + rot180(A, k) + + Rotate matrix "A" 180 degrees an integer "k" number of times. + If "k" is even, this is equivalent to a "copy". + ``` + """ Base.rot180 + + @doc doc""" + ```rst + rotl90(A) + + Rotate matrix "A" left 90 degrees. + ``` + """ Base.rotl90 + + @doc doc""" + ```rst + rotl90(A, k) + + Rotate matrix "A" left 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". + ``` + """ Base.rotl90 + + @doc doc""" + ```rst + rotr90(A) + + Rotate matrix "A" right 90 degrees. + ``` + """ Base.rotr90 + + @doc doc""" + ```rst + rotr90(A, k) + + Rotate matrix "A" right 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". + ``` + """ Base.rotr90 + + @doc doc""" + ```rst + reducedim(f, A, dims[, initial]) + + Reduce 2-argument function "f" along dimensions of "A". + "dims" is a vector specifying the dimensions to reduce, and + "initial" is the initial value to use in the reductions. For *+*, + ***, *max* and *min* the *initial* argument is optional. + + The associativity of the reduction is implementation-dependent; if + you need a particular associativity, e.g. left-to-right, you should + write your own loop. See documentation for "reduce". + ``` + """ Base.reducedim + + @doc doc""" + ```rst + mapreducedim(f, op, A, dims[, initial]) + + Evaluates to the same as *reducedim(op, map(f, A), dims, + f(initial))*, but is generally faster because the intermediate + array is avoided. + ``` + """ Base.mapreducedim + + @doc doc""" + ```rst + mapslices(f, A, dims) + + Transform the given dimensions of array "A" using function "f". + "f" is called on each slice of "A" of the form + "A[...,:,...,:,...]". "dims" is an integer vector specifying + where the colons go in this expression. The results are + concatenated along the remaining dimensions. For example, if + "dims" is "[1,2]" and A is 4-dimensional, "f" is called on + "A[:,:,i,j]" for all "i" and "j". + ``` + """ Base.mapslices + + @doc doc""" + ```rst + sum_kbn(A) + + Returns the sum of all array elements, using the Kahan-Babuska- + Neumaier compensated summation algorithm for additional accuracy. + ``` + """ Base.sum_kbn + + @doc doc""" + ```rst + cartesianmap(f, dims) + + Given a "dims" tuple of integers "(m, n, ...)", call "f" on + all combinations of integers in the ranges "1:m", "1:n", etc. + + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 + ``` + """ Base.cartesianmap + + @doc doc""" + ```rst + nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + ``` + """ Base.nthperm + + @doc doc""" + ```rst + nthperm(p) + + Return the "k" that generated permutation "p". Note that + "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". + ``` + """ Base.nthperm + + @doc doc""" + ```rst + nthperm!(v, k) + + In-place version of "nthperm()". + ``` + """ Base.nthperm! + + @doc doc""" + ```rst + randperm([rng], n) + + Construct a random permutation of length "n". The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. + ``` + """ Base.randperm + + @doc doc""" + ```rst + invperm(v) + + Return the inverse permutation of v. + ``` + """ Base.invperm + + @doc doc""" + ```rst + isperm(v) -> Bool + + Returns true if v is a valid permutation. + ``` + """ Base.isperm + + @doc doc""" + ```rst + permute!(v, p) + + Permute vector "v" in-place, according to permutation "p". No + checking is done to verify that "p" is a permutation. + + To return a new permutation, use "v[p]". Note that this is + generally faster than "permute!(v,p)" for large vectors. + ``` + """ Base.permute! + + @doc doc""" + ```rst + ipermute!(v, p) + + Like permute!, but the inverse of the given permutation is applied. + ``` + """ Base.ipermute! + + @doc doc""" + ```rst + randcycle([rng], n) + + Construct a random cyclic permutation of length "n". The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. + ``` + """ Base.randcycle + + @doc doc""" + ```rst + shuffle([rng], v) + + Return a randomly permuted copy of "v". The optional "rng" + argument specifies a random number generator, see *Random Numbers*. + ``` + """ Base.shuffle + + @doc doc""" + ```rst + shuffle!([rng], v) + + In-place version of "shuffle()". + ``` + """ Base.shuffle! + + @doc doc""" + ```rst + reverse(v[, start=1[, stop=length(v)]]) + + Return a copy of "v" reversed from start to stop. + ``` + """ Base.reverse + + @doc doc""" + ```rst + reverseind(v, i) + + Given an index "i" in "reverse(v)", return the corresponding + index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". + (This can be nontrivial in the case where "v" is a Unicode + string.) + ``` + """ Base.reverseind + + @doc doc""" + ```rst + reverse!(v[, start=1[, stop=length(v)]]) -> v + + In-place version of "reverse()". + ``` + """ Base.reverse! + + @doc doc""" + ```rst + combinations(array, n) + + Generate all combinations of "n" elements from an indexable + object. Because the number of combinations can be very large, this + function returns an iterator object. Use + "collect(combinations(array,n))" to get an array of all + combinations. + ``` + """ Base.combinations + + @doc doc""" + ```rst + permutations(array) + + Generate all permutations of an indexable object. Because the + number of permutations can be very large, this function returns an + iterator object. Use "collect(permutations(array))" to get an + array of all permutations. + ``` + """ Base.permutations + + @doc doc""" + ```rst + partitions(n) + + Generate all integer arrays that sum to "n". Because the number + of partitions can be very large, this function returns an iterator + object. Use "collect(partitions(n))" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using "length(partitions(n))". + ``` + """ Base.partitions + + @doc doc""" + ```rst + partitions(n, m) + + Generate all arrays of "m" integers that sum to "n". Because + the number of partitions can be very large, this function returns + an iterator object. Use "collect(partitions(n,m))" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using "length(partitions(n,m))". + ``` + """ Base.partitions + + @doc doc""" + ```rst + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + "collect(partitions(array))" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using "length(partitions(array))". + ``` + """ Base.partitions + + @doc doc""" + ```rst + partitions(array, m) + + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use "collect(partitions(array,m))" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using "length(partitions(array,m))". + ``` + """ Base.partitions + + @doc doc""" + ```rst + bitpack(A::AbstractArray{T, N}) -> BitArray + + Converts a numeric array to a packed boolean array + ``` + """ Base.bitpack + + @doc doc""" + ```rst + bitunpack(B::BitArray{N}) -> Array{Bool,N} + + Converts a packed boolean array to an array of booleans + ``` + """ Base.bitunpack + + @doc doc""" + ```rst + flipbits!(B::BitArray{N}) -> BitArray{N} + + Performs a bitwise not operation on B. See *~ operator*. + ``` + """ Base.flipbits! + + @doc doc""" + ```rst + rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on "src" and put the result + into "dest". + ``` + """ Base.rol! + + @doc doc""" + ```rst + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on B. + ``` + """ Base.rol! + + @doc doc""" + ```rst + rol(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation. + ``` + """ Base.rol + + @doc doc""" + ```rst + ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on "src" and put the result + into "dest". + ``` + """ Base.ror! + + @doc doc""" + ```rst + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on B. + ``` + """ Base.ror! + + @doc doc""" + ```rst + ror(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation. + ``` + """ Base.ror + + @doc doc""" + ```rst + sparse(I, J, V[, m, n, combine]) + + Create a sparse matrix "S" of dimensions "m x n" such that + "S[I[k], J[k]] = V[k]". The "combine" function is used to + combine duplicates. If "m" and "n" are not specified, they are + set to "max(I)" and "max(J)" respectively. If the "combine" + function is not supplied, duplicates are added by default. + ``` + """ Base.sparse + + @doc doc""" + ```rst + sparsevec(I, V[, m, combine]) + + Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] + = V[k]". Duplicates are combined using the "combine" function, + which defaults to "+" if it is not provided. In julia, sparse + vectors are really just sparse matrices with one column. Given + Julia's Compressed Sparse Columns (CSC) storage format, a sparse + column matrix with one column is sparse, whereas a sparse row + matrix with one row ends up being dense. + ``` + """ Base.sparsevec + + @doc doc""" + ```rst + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size "m x 1" where the row values are + keys from the dictionary, and the nonzero values are the values + from the dictionary. + ``` + """ Base.sparsevec + + @doc doc""" + ```rst + issparse(S) + + Returns "true" if "S" is sparse, and "false" otherwise. + ``` + """ Base.issparse + + @doc doc""" + ```rst + sparse(A) + + Convert an AbstractMatrix "A" into a sparse matrix. + ``` + """ Base.sparse + + @doc doc""" + ```rst + sparsevec(A) + + Convert a dense vector "A" into a sparse matrix of size "m x + 1". In julia, sparse vectors are really just sparse matrices with + one column. + ``` + """ Base.sparsevec + + @doc doc""" + ```rst + full(S) + + Convert a sparse matrix "S" into a dense matrix. + ``` + """ Base.full + + @doc doc""" + ```rst + nnz(A) + + Returns the number of stored (filled) elements in a sparse matrix. + ``` + """ Base.nnz + + @doc doc""" + ```rst + spzeros(m, n) + + Create a sparse matrix of size "m x n". This sparse matrix will + not contain any nonzero values. No storage will be allocated for + nonzero values during construction. + ``` + """ Base.spzeros + + @doc doc""" + ```rst + spones(S) + + Create a sparse matrix with the same structure as that of "S", + but with every nonzero element having the value "1.0". + ``` + """ Base.spones + + @doc doc""" + ```rst + speye(type, m[, n]) + + Create a sparse identity matrix of specified type of size "m x + m". In case "n" is supplied, create a sparse identity matrix of + size "m x n". + ``` + """ Base.speye + + @doc doc""" + ```rst + spdiagm(B, d[, m, n]) + + Construct a sparse diagonal matrix. "B" is a tuple of vectors + containing the diagonals and "d" is a tuple containing the + positions of the diagonals. In the case the input contains only one + diagonaly, "B" can be a vector (instead of a tuple) and "d" can + be the diagonal position (instead of a tuple), defaulting to 0 + (diagonal). Optionally, "m" and "n" specify the size of the + resulting sparse matrix. + ``` + """ Base.spdiagm + + @doc doc""" + ```rst + sprand([rng], m, n, p[, rfn]) + + Create a random "m" by "n" sparse matrix, in which the + probability of any element being nonzero is independently given by + "p" (and hence the mean density of nonzeros is also exactly + "p"). Nonzero values are sampled from the distribution specified + by "rfn". The uniform distribution is used in case "rfn" is not + specified. The optional "rng" argument specifies a random number + generator, see *Random Numbers*. + ``` + """ Base.sprand + + @doc doc""" + ```rst + sprandn(m, n, p) + + Create a random "m" by "n" sparse matrix with the specified + (independent) probability "p" of any entry being nonzero, where + nonzero values are sampled from the normal distribution. + ``` + """ Base.sprandn + + @doc doc""" + ```rst + sprandbool(m, n, p) + + Create a random "m" by "n" sparse boolean matrix with the + specified (independent) probability "p" of any entry being + "true". + ``` + """ Base.sprandbool + + @doc doc""" + ```rst + etree(A[, post]) + + Compute the elimination tree of a symmetric sparse matrix "A" + from "triu(A)" and, optionally, its post-ordering permutation. + ``` + """ Base.etree + + @doc doc""" + ```rst + symperm(A, p) + + Return the symmetric permutation of A, which is "A[p,p]". A + should be symmetric and sparse, where only the upper triangular + part of the matrix is stored. This algorithm ignores the lower + triangular part of the matrix. Only the upper triangular part of + the result is returned as well. + ``` + """ Base.symperm + + @doc doc""" + ```rst + nonzeros(A) + + Return a vector of the structural nonzero values in sparse matrix + "A". This includes zeros that are explicitly stored in the sparse + matrix. The returned vector points directly to the internal nonzero + storage of "A", and any modifications to the returned vector will + mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". + ``` + """ Base.nonzeros + + @doc doc""" + ```rst + rowvals(A) + + Return a vector of the row indices of "A", and any modifications + to the returned vector will mutate "A" as well. Given the + internal storage format of sparse matrices, providing access to how + the row indices are stored internally can be useful in conjuction + with iterating over structural nonzero values. See "nonzeros(A)" + and "nzrange(A, col)". + ``` + """ Base.rowvals + + @doc doc""" + ```rst + nzrange(A, col) + + Return the range of indices to the structural nonzero values of a + sparse matrix column. In conjunction with "nonzeros(A)" and + "rowvals(A)", 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 + ``` + """ Base.nzrange + + @doc doc""" + ```rst + exit([code]) + + Quit (or control-D at the prompt). The default exit code is zero, + indicating that the processes completed successfully. + ``` + """ Base.exit + + @doc doc""" + ```rst + quit() + + Quit the program indicating that the processes completed + successfully. This function calls "exit(0)" (see "exit()"). + ``` + """ Base.quit + + @doc doc""" + ```rst + atexit(f) + + Register a zero-argument function to be called at exit. + ``` + """ Base.atexit + + @doc doc""" + ```rst + atreplinit(f) + + Register a one-argument function to be called before the REPL + interface is initialized in interactive sessions; this is useful to + customize the interface. The argument of "f" is the REPL object. + This function should be called from within the ".juliarc.jl" + initialization file. + ``` + """ Base.atreplinit + + @doc doc""" + ```rst + isinteractive() -> Bool + + Determine whether Julia is running an interactive session. + ``` + """ Base.isinteractive + + @doc doc""" + ```rst + whos([Module,] [pattern::Regex]) + + Print information about exported global variables in a module, + optionally restricted to those matching "pattern". + ``` + """ Base.whos + + @doc doc""" + ```rst + edit(file::AbstractString[, line]) + + Edit a file optionally providing a line number to edit at. Returns + to the julia prompt when you quit the editor. + ``` + """ Base.edit + + @doc doc""" + ```rst + edit(function[, types]) + + Edit the definition of a function, optionally specifying a tuple of + types to indicate which method to edit. + ``` + """ Base.edit + + @doc doc""" + ```rst + @edit() + + Evaluates the arguments to the function call, determines their + types, and calls the "edit" function on the resulting expression + ``` + """ Base.@edit + + @doc doc""" + ```rst + less(file::AbstractString[, line]) + + Show a file using the default pager, optionally providing a + starting line number. Returns to the julia prompt when you quit the + pager. + ``` + """ Base.less + + @doc doc""" + ```rst + less(function[, types]) + + Show the definition of a function using the default pager, + optionally specifying a tuple of types to indicate which method to + see. + ``` + """ Base.less + + @doc doc""" + ```rst + @less() + + Evaluates the arguments to the function call, determines their + types, and calls the "less" function on the resulting expression + ``` + """ Base.@less + + @doc doc""" + ```rst + clipboard(x) + + Send a printed form of "x" to the operating system clipboard + ("copy"). + ``` + """ Base.clipboard + + @doc doc""" + ```rst + clipboard() -> AbstractString + + Return a string with the contents of the operating system clipboard + ("paste"). + ``` + """ Base.clipboard + + @doc doc""" + ```rst + require(file::AbstractString...) + + Load source files once, in the context of the "Main" module, on + every active node, searching standard locations for files. + "require" is considered a top-level operation, so it sets the + current "include" path but does not use it to search for files + (see help for "include"). This function is typically used to load + library code, and is implicitly called by "using" to load + packages. + + When searching for files, "require" first looks in the current + working directory, then looks for package code under "Pkg.dir()", + then tries paths in the global array "LOAD_PATH". + ``` + """ Base.require + + @doc doc""" + ```rst + reload(file::AbstractString) + + Like "require", except forces loading of files regardless of + whether they have been loaded before. Typically used when + interactively developing libraries. + ``` + """ Base.reload + + @doc doc""" + ```rst + include(path::AbstractString) + + Evaluate the contents of a source file in the current context. + During including, a task-local include path is set to the directory + containing the file. Nested calls to "include" will search + relative to that path. All paths refer to files on node 1 when + running in parallel, and files will be fetched from node 1. This + function is typically used to load source interactively, or to + combine files in packages that are broken into multiple source + files. + ``` + """ Base.include + + @doc doc""" + ```rst + include_string(code::AbstractString) + + Like "include", except reads code from the given string rather + than from a file. Since there is no file path involved, no path + processing or fetching from node 1 is done. + ``` + """ Base.include_string + + @doc doc""" + ```rst + help(name) + + Get help for a function. "name" can be an object or a string. + ``` + """ Base.help + + @doc doc""" + ```rst + apropos(string) + + Search documentation for functions related to "string". + ``` + """ Base.apropos + + @doc doc""" + ```rst + which(f, types) + + Returns the method of "f" (a "Method" object) that would be + called for arguments of the given types. + + If "types" is an abstract type, then the method that would be + called by "invoke" is returned. + ``` + """ Base.which + + @doc doc""" + ```rst + which(symbol) + + Return the module in which the binding for the variable referenced + by "symbol" was created. + ``` + """ Base.which + + @doc doc""" + ```rst + @which() + + Applied to a function call, it evaluates the arguments to the + specified function call, and returns the "Method" object for the + method that would be called for those arguments. Applied to a + variable, it returns the module in which the variable was bound. It + calls out to the "which" function. + ``` + """ Base.@which + + @doc doc""" + ```rst + methods(f[, types]) + + Returns the method table for "f". + + If "types" is specified, returns an array of methods whose types + match. + ``` + """ Base.methods + + @doc doc""" + ```rst + methodswith(typ[, module or function][, showparents]) + + Return an array of methods with an argument of type "typ". If + optional "showparents" is "true", also return arguments with a + parent type of "typ", excluding type "Any". + + The optional second argument restricts the search to a particular + module or function. + ``` + """ Base.methodswith + + @doc doc""" + ```rst + @show() + + Show an expression and result, returning the result + ``` + """ Base.@show + + @doc doc""" + ```rst + versioninfo([verbose::Bool]) + + Print information about the version of Julia in use. If the + "verbose" argument is true, detailed system information is shown + as well. + ``` + """ Base.versioninfo + + @doc doc""" + ```rst + workspace() + + Replace the top-level module ("Main") with a new one, providing a + clean workspace. The previous "Main" module is made available as + "LastMain". A previously-loaded package can be accessed using a + statement such as "using LastMain.Package". + + This function should only be used interactively. + ``` + """ Base.workspace + + @doc doc""" + ```rst + is(x, y) -> Bool +===(x, y) -> Bool +≡(x, y) -> Bool + + Determine whether "x" and "y" are identical, in the sense that + no program could distinguish them. Compares mutable objects by + address in memory, and compares immutable objects (such as numbers) + by contents at the bit level. This function is sometimes called + "egal". + ``` + """ Base.is + + @doc doc""" + ```rst + isa(x, type) -> Bool + + Determine whether "x" is of the given "type". + ``` + """ Base.isa + + @doc doc""" + ```rst + isequal(x, y) + + Similar to "==", except treats all floating-point "NaN" values + as equal to each other, and treats "-0.0" as unequal to "0.0". + The default implementation of "isequal" calls "==", so if you + have a type that doesn't have these floating-point subtleties then + you probably only need to define "==". + + "isequal" is the comparison function used by hash tables + ("Dict"). "isequal(x,y)" must imply that "hash(x) == + hash(y)". + + This typically means that if you define your own "==" function + then you must define a corresponding "hash" (and vice versa). + Collections typically implement "isequal" by calling "isequal" + recursively on all contents. + + Scalar types generally do not need to implement "isequal" + separate from "==", unless they represent floating-point numbers + amenable to a more efficient implementation than that provided as a + generic fallback (based on "isnan", "signbit", and "=="). + ``` + """ Base.isequal + + @doc doc""" + ```rst + isless(x, y) + + Test whether "x" is less than "y", according to a canonical + total order. Values that are normally unordered, such as "NaN", + are ordered in an arbitrary but consistent fashion. This is the + default comparison used by "sort". Non-numeric types with a + canonical total order should implement this function. Numeric types + only need to implement it if they have special values such as + "NaN". + ``` + """ Base.isless + + @doc doc""" + ```rst + ifelse(condition::Bool, x, y) + + Return "x" if "condition" is true, otherwise return "y". This + differs from "?" or "if" in that it is an ordinary function, so + all the arguments are evaluated first. In some cases, using + "ifelse" instead of an "if" statement can eliminate the branch + in generated code and provide higher performance in tight loops. + ``` + """ Base.ifelse + + @doc doc""" + ```rst + lexcmp(x, y) + + Compare "x" and "y" lexicographically and return -1, 0, or 1 + depending on whether "x" is less than, equal to, or greater than + "y", respectively. This function should be defined for + lexicographically comparable types, and "lexless" will call + "lexcmp" by default. + ``` + """ Base.lexcmp + + @doc doc""" + ```rst + lexless(x, y) + + Determine whether "x" is lexicographically less than "y". + ``` + """ Base.lexless + + @doc doc""" + ```rst + typeof(x) + + Get the concrete type of "x". + ``` + """ Base.typeof + + @doc doc""" + ```rst + tuple(xs...) + + Construct a tuple of the given objects. + ``` + """ Base.tuple + + @doc doc""" + ```rst + ntuple(f::Function, n) + + Create a tuple of length "n", computing each element as "f(i)", + where "i" is the index of the element. + ``` + """ Base.ntuple + + @doc doc""" + ```rst + object_id(x) + + Get a unique integer id for "x". "object_id(x)==object_id(y)" + if and only if "is(x,y)". + ``` + """ Base.object_id + + @doc doc""" + ```rst + hash(x[, h]) + + Compute an integer hash code such that "isequal(x,y)" implies + "hash(x)==hash(y)". The optional second argument "h" is a hash + code to be mixed with the result. + + New types should implement the 2-argument form, typically by + calling the 2-argument "hash" method recursively in order to mix + hashes of the contents with each other (and with "h"). + Typically, any type that implements "hash" should also implement + its own "==" (hence "isequal") to guarantee the property + mentioned above. + ``` + """ Base.hash + + @doc doc""" + ```rst + finalizer(x, function) + + Register a function "f(x)" to be called when there are no + program-accessible references to "x". The behavior of this + function is unpredictable if "x" is of a bits type. + ``` + """ Base.finalizer + + @doc doc""" + ```rst + finalize(x) + + Immediately run finalizers registered for object "x". + ``` + """ Base.finalize + + @doc doc""" + ```rst + copy(x) + + Create a shallow copy of "x": the outer structure is copied, but + not all internal values. For example, copying an array produces a + new array with identically-same elements as the original. + ``` + """ Base.copy + + @doc doc""" + ```rst + deepcopy(x) + + Create a deep copy of "x": everything is copied recursively, + resulting in a fully independent object. For example, deep-copying + an array produces a new array whose elements are deep copies of the + original elements. Calling *deepcopy* on an object should generally + have the same effect as serializing and then deserializing it. + + As a special case, functions can only be actually deep-copied if + they are anonymous, otherwise they are just copied. The difference + is only relevant in the case of closures, i.e. functions which may + contain hidden internal references. + + While it isn't normally necessary, user-defined types can override + the default "deepcopy" behavior by defining a specialized version + of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" + (which shouldn't otherwise be used), where "T" is the type to be + specialized for, and "dict" keeps track of objects copied so far + within the recursion. Within the definition, "deepcopy_internal" + should be used in place of "deepcopy", and the "dict" variable + should be updated as appropriate before returning. + ``` + """ Base.deepcopy + + @doc doc""" + ```rst + isdefined([object], index | symbol) + + Tests whether an assignable location is defined. The arguments can + be an array and index, a composite object and field name (as a + symbol), or a module and a symbol. With a single symbol argument, + tests whether a global variable with that name is defined in + "current_module()". + ``` + """ Base.isdefined + + @doc doc""" + ```rst + convert(T, x) + + Convert "x" to a value of type "T". + + If "T" is an "Integer" type, an "InexactError" will be raised + if "x" is not representable by "T", for example if "x" is not + integer-valued, or is outside the range supported by "T". + + julia> convert(Int, 3.0) + 3 + + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 + + If "T" is a "FloatingPoint" or "Rational" type, then it will + return the closest value to "x" representable by "T". + + julia> x = 1/3 + 0.3333333333333333 + + julia> convert(Float32, x) + 0.33333334f0 + + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 + ``` + """ Base.convert + + @doc doc""" + ```rst + promote(xs...) + + Convert all arguments to their common promotion type (if any), and + return them all (as a tuple). + ``` + """ Base.promote + + @doc doc""" + ```rst + oftype(x, y) + + Convert "y" to the type of "x" ("convert(typeof(x), y)"). + ``` + """ Base.oftype + + @doc doc""" + ```rst + widen(type | x) + + If the argument is a type, return a "larger" type (for numeric + types, this will be a type with at least as much range and + precision as the argument, and usually more). Otherwise the + argument "x" is converted to "widen(typeof(x))". + + julia> widen(Int32) + Int64 + + julia> widen(1.5f0) + 1.5 + ``` + """ Base.widen + + @doc doc""" + ```rst + identity(x) + + The identity function. Returns its argument. + ``` + """ Base.identity + + @doc doc""" + ```rst + super(T::DataType) + + Return the supertype of DataType T + ``` + """ Base.super + + @doc doc""" + ```rst + issubtype(type1, type2) + + True if and only if all values of "type1" are also of "type2". + Can also be written using the "<:" infix operator as "type1 <: + type2". + ``` + """ Base.issubtype + + @doc doc""" + ```rst + <:(T1, T2) + + Subtype operator, equivalent to "issubtype(T1,T2)". + ``` + """ Base.(:(<:)) + + @doc doc""" + ```rst + subtypes(T::DataType) + + Return a list of immediate subtypes of DataType T. Note that all + currently loaded subtypes are included, including those not visible + in the current module. + ``` + """ Base.subtypes + + @doc doc""" + ```rst + typemin(type) + + The lowest value representable by the given (real) numeric type. + ``` + """ Base.typemin + + @doc doc""" + ```rst + typemax(type) + + The highest value representable by the given (real) numeric type. + ``` + """ Base.typemax + + @doc doc""" + ```rst + realmin(type) + + The smallest in absolute value non-subnormal value representable by + the given floating-point type + ``` + """ Base.realmin + + @doc doc""" + ```rst + realmax(type) + + The highest finite value representable by the given floating-point + type + ``` + """ Base.realmax + + @doc doc""" + ```rst + maxintfloat(type) + + The largest integer losslessly representable by the given floating- + point type + ``` + """ Base.maxintfloat + + @doc doc""" + ```rst + sizeof(type) + + Size, in bytes, of the canonical binary representation of the given + type, if any. + ``` + """ Base.sizeof + + @doc doc""" + ```rst + eps([type]) + + The distance between 1.0 and the next larger representable + floating-point value of "type". Only floating-point types are + sensible arguments. If "type" is omitted, then "eps(Float64)" + is returned. + ``` + """ Base.eps + + @doc doc""" + ```rst + eps(x) + + The distance between "x" and the next larger representable + floating-point value of the same type as "x". + ``` + """ Base.eps + + @doc doc""" + ```rst + promote_type(type1, type2) + + Determine a type big enough to hold values of each argument type + without loss, whenever possible. In some cases, where no type + exists to which both types can be promoted losslessly, some loss is + tolerated; for example, "promote_type(Int64,Float64)" returns + "Float64" even though strictly, not all "Int64" values can be + represented exactly as "Float64" values. + ``` + """ Base.promote_type + + @doc doc""" + ```rst + promote_rule(type1, type2) + + Specifies what type should be used by "promote" when given values + of types "type1" and "type2". This function should not be + called directly, but should have definitions added to it for new + types as appropriate. + ``` + """ Base.promote_rule + + @doc doc""" + ```rst + getfield(value, name::Symbol) + + Extract a named field from a value of composite type. The syntax + "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls + "getfield(a, b)". + ``` + """ Base.getfield + + @doc doc""" + ```rst + setfield!(value, name::Symbol, x) + + Assign "x" to a named field in "value" of composite type. The + syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax + "a.(b) = c" calls "setfield!(a, b, c)". + ``` + """ Base.setfield! + + @doc doc""" + ```rst + fieldoffsets(type) + + The byte offset of each field of a type relative to the data start. + For example, we could use it in the following manner to summarize + information about a struct type: + + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; + + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) + ``` + """ Base.fieldoffsets + + @doc doc""" + ```rst + fieldtype(type, name::Symbol | index::Int) + + Determine the declared type of a field (specified by name or index) + in a composite type. + ``` + """ Base.fieldtype + + @doc doc""" + ```rst + isimmutable(v) + + True if value "v" is immutable. See *Immutable Composite Types* + for a discussion of immutability. Note that this function works on + values, so if you give it a type, it will tell you that a value of + "DataType" is mutable. + ``` + """ Base.isimmutable + + @doc doc""" + ```rst + isbits(T) + + True if "T" is a "plain data" type, meaning it is immutable and + contains no references to other values. Typical examples are + numeric types such as "UInt8", "Float64", and + "Complex{Float64}". + + julia> isbits(Complex{Float64}) + true + + julia> isbits(Complex) + false + ``` + """ Base.isbits + + @doc doc""" + ```rst + isleaftype(T) + + Determine whether "T" is a concrete type that can have instances, + meaning its only subtypes are itself and "None" (but "T" itself + is not "None"). + ``` + """ Base.isleaftype + + @doc doc""" + ```rst + typejoin(T, S) + + Compute a type that contains both "T" and "S". + ``` + """ Base.typejoin + + @doc doc""" + ```rst + typeintersect(T, S) + + Compute a type that contains the intersection of "T" and "S". + Usually this will be the smallest such type or one close to it. + ``` + """ Base.typeintersect + + @doc doc""" + ```rst + instances(T::Type) + + Return a collection of all instances of the given type, if + applicable. Mostly used for enumerated types (see "@enum"). + ``` + """ Base.instances + + @doc doc""" + ```rst + method_exists(f, Tuple type) -> Bool + + Determine whether the given generic function has a method matching + the given "Tuple" of argument types. + + julia> method_exists(length, Tuple{Array}) + true + ``` + """ Base.method_exists + + @doc doc""" + ```rst + applicable(f, args...) -> Bool + + Determine whether the given generic function has a method + applicable to the given arguments. + + julia> function f(x, y) + x + y + end; + + julia> applicable(f, 1) + false + + julia> applicable(f, 1, 2) + true + ``` + """ Base.applicable + + @doc doc""" + ```rst + invoke(f, (types...), args...) + + Invoke a method for the given generic function matching the + specified types (as a tuple), on the specified arguments. The + arguments must be compatible with the specified types. This allows + invoking a method other than the most specific matching method, + which is useful when the behavior of a more general definition is + explicitly needed (often as part of the implementation of a more + specific method of the same function). + ``` + """ Base.invoke + + @doc doc""" + ```rst + |>(x, f) + + Applies a function to the preceding argument. This allows for easy + function chaining. + + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 + ``` + """ Base.(:(|>)) + + @doc doc""" + ```rst + call(x, args...) + + If "x" is not a "Function", then "x(args...)" is equivalent + to "call(x, args...)". This means that function-like behavior + can be added to any type by defining new "call" methods. + ``` + """ Base.call + + @doc doc""" + ```rst + eval([m::Module], expr::Expr) + + Evaluate an expression in the given module and return the result. + Every module (except those defined with "baremodule") has its own + 1-argument definition of "eval", which evaluates expressions in + that module. + ``` + """ Base.eval + + @doc doc""" + ```rst + @eval() + + Evaluate an expression and return the value. + ``` + """ Base.@eval + + @doc doc""" + ```rst + evalfile(path::AbstractString) + + Load the file using "include", evaluate all expressions, and + return the value of the last one. + ``` + """ Base.evalfile + + @doc doc""" + ```rst + esc(e::ANY) + + Only valid in the context of an Expr returned from a macro. + Prevents the macro hygiene pass from turning embedded variables + into gensym variables. See the *Macros* section of the + Metaprogramming chapter of the manual for more details and + examples. + ``` + """ Base.esc + + @doc doc""" + ```rst + gensym([tag]) + + Generates a symbol which will not conflict with other variable + names. + ``` + """ Base.gensym + + @doc doc""" + ```rst + @gensym() + + Generates a gensym symbol for a variable. For example, "@gensym x + y" is transformed into "x = gensym("x"); y = gensym("y")". + ``` + """ Base.@gensym + + @doc doc""" + ```rst + parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could + later be passed to eval for execution). Start is the index of the + first character to start parsing. If "greedy" is true (default), + "parse" will try to consume as much input as it can; otherwise, + it will stop as soon as it has parsed a valid expression. + Incomplete but otherwise syntactically valid expressions will + return "Expr(:incomplete, "(error message)")". If "raise" is + true (default), syntax errors other than incomplete expressions + will raise an error. If "raise" is false, "parse" will return + an expression that will raise an error upon evaluation. + ``` + """ Base.parse + + @doc doc""" + ```rst + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An + error is thrown if there are additional characters after the first + expression. If "raise" is true (default), syntax errors will + raise an error; otherwise, "parse" will return an expression that + will raise an error upon evaluation. + ``` + """ Base.parse + + @doc doc""" + ```rst + Nullable(x) + + Wrap value "x" in an object of type "Nullable", which indicates + whether a value is present. "Nullable(x)" yields a non-empty + wrapper, and "Nullable{T}()" yields an empty instance of a + wrapper that might contain a value of type "T". + ``` + """ Base.Nullable + + @doc doc""" + ```rst + get(x) + + Attempt to access the value of the "Nullable" object, "x". + Returns the value if it is present; otherwise, throws a + "NullException". + ``` + """ Base.get + + @doc doc""" + ```rst + get(x, y) + + Attempt to access the value of the "Nullable{T}" object, "x". + Returns the value if it is present; otherwise, returns "convert(T, + y)". + ``` + """ Base.get + + @doc doc""" + ```rst + isnull(x) + + Is the "Nullable" object "x" null, i.e. missing a value? + ``` + """ Base.isnull + + @doc doc""" + ```rst + run(command) + + Run a command object, constructed with backticks. Throws an error + if anything goes wrong, including the process exiting with a non- + zero status. + ``` + """ Base.run + + @doc doc""" + ```rst + spawn(command) + + Run a command object asynchronously, returning the resulting + "Process" object. + ``` + """ Base.spawn + + @doc doc""" + ```rst + DevNull + + Used in a stream redirect to discard all data written to it. + Essentially equivalent to /dev/null on Unix or NUL on Windows. + Usage: "run(`cat test.txt` |> DevNull)" + ``` + """ Base.DevNull + + @doc doc""" + ```rst + success(command) + + Run a command object, constructed with backticks, and tell whether + it was successful (exited with a code of 0). An exception is raised + if the process cannot be started. + ``` + """ Base.success + + @doc doc""" + ```rst + process_running(p::Process) + + Determine whether a process is currently running. + ``` + """ Base.process_running + + @doc doc""" + ```rst + process_exited(p::Process) + + Determine whether a process has exited. + ``` + """ Base.process_exited + + @doc doc""" + ```rst + kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the + process. + ``` + """ Base.kill + + @doc doc""" + ```rst + open(command, mode::AbstractString="r", stdio=DevNull) + + Start running "command" asynchronously, and return a tuple + "(stream,process)". If "mode" is ""r"", then "stream" + reads from the process's standard output and "stdio" optionally + specifies the process's standard input stream. If "mode" is + ""w"", then "stream" writes to the process's standard input + and "stdio" optionally specifies the process's standard output + stream. + ``` + """ Base.open + + @doc doc""" + ```rst + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to "open(command, mode, stdio)", but calls "f(stream)" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + "f". + ``` + """ Base.open + + @doc doc""" + ```rst + Sys.set_process_title(title::AbstractString) + + Set the process title. No-op on some operating systems. (not + exported) + ``` + """ Base.Sys + + @doc doc""" + ```rst + Sys.get_process_title() + + Get the process title. On some systems, will always return empty + string. (not exported) + ``` + """ Base.Sys + + @doc doc""" + ```rst + readandwrite(command) + + Starts running a command asynchronously, and returns a tuple + (stdout,stdin,process) of the output stream and input stream of the + process, and the process object itself. + ``` + """ Base.readandwrite + + @doc doc""" + ```rst + ignorestatus(command) + + Mark a command object so that running it will not throw an error if + the result code is non-zero. + ``` + """ Base.ignorestatus + + @doc doc""" + ```rst + detach(command) + + Mark a command object so that it will be run in a new process + group, allowing it to outlive the julia process, and not have + Ctrl-C interrupts passed to it. + ``` + """ Base.detach + + @doc doc""" + ```rst + setenv(command, env; dir=working_dir) + + Set environment variables to use when running the given command. + "env" is either a dictionary mapping strings to strings, an array + of strings of the form ""var=val"", or zero or more + ""var"=>val" pair arguments. In order to modify (rather than + replace) the existing environment, create "env" by "copy(ENV)" + and then setting "env["var"]=val" as desired, or use + "withenv". + + The "dir" keyword argument can be used to specify a working + directory for the command. + ``` + """ Base.setenv + + @doc doc""" + ```rst + withenv(f::Function, kv::Pair...) + + Execute "f()" in an environment that is temporarily modified (not + replaced as in "setenv") by zero or more ""var"=>val" + arguments "kv". "withenv" is generally used via the + "withenv(kv...) do ... end" syntax. A value of "nothing" can + be used to temporarily unset an environment variable (if it is + set). When "withenv" returns, the original environment has been + restored. + ``` + """ Base.withenv + + @doc doc""" + ```rst + pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source + and destination can be commands, I/O streams, strings, or results + of other "pipe" calls. At least one argument must be a command. + Strings refer to filenames. When called with more than two + arguments, they are chained together from left to right. For + example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". + This provides a more concise way to specify multi-stage pipelines. + + **Examples**: + * "run(pipe(`ls`, `grep xyz`))" + + * "run(pipe(`ls`, "out.txt"))" + + * "run(pipe("out.txt", `grep xyz`))" + ``` + """ Base.pipe + + @doc doc""" + ```rst + pipe(command; stdin, stdout, stderr, append=false) + + Redirect I/O to or from the given "command". Keyword arguments + specify which of the command's streams should be redirected. + "append" controls whether file output appends to the file. This + is a more general version of the 2-argument "pipe" function. + "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when + "from" is a command, and to "pipe(to, stdin=from)" when + "from" is another kind of data source. + + **Examples**: + * "run(pipe(`dothings`, stdout="out.txt", + stderr="errs.txt"))" + + * "run(pipe(`update`, stdout="log.txt", append=true))" + ``` + """ Base.pipe + + @doc doc""" + ```rst + gethostname() -> AbstractString + + Get the local machine's host name. + ``` + """ Base.gethostname + + @doc doc""" + ```rst + getipaddr() -> AbstractString + + Get the IP address of the local machine, as a string of the form + "x.x.x.x". + ``` + """ Base.getipaddr + + @doc doc""" + ```rst + getpid() -> Int32 + + Get julia's process ID. + ``` + """ Base.getpid + + @doc doc""" + ```rst + time() + + Get the system time in seconds since the epoch, with fairly high + (typically, microsecond) resolution. + ``` + """ Base.time + + @doc doc""" + ```rst + time_ns() + + Get the time in nanoseconds. The time corresponding to 0 is + undefined, and wraps every 5.8 years. + ``` + """ Base.time_ns + + @doc doc""" + ```rst + tic() + + Set a timer to be read by the next call to "toc()" or "toq()". + The macro call "@time expr" can also be used to time evaluation. + ``` + """ Base.tic + + @doc doc""" + ```rst + toc() + + Print and return the time elapsed since the last "tic()". + ``` + """ Base.toc + + @doc doc""" + ```rst + toq() + + Return, but do not print, the time elapsed since the last + "tic()". + ``` + """ Base.toq + + @doc doc""" + ```rst + @time() + + A macro to execute an expression, printing the time it took to + execute, the number of allocations, and the total number of bytes + its execution caused to be allocated, before returning the value of + the expression. + ``` + """ Base.@time + + @doc doc""" + ```rst + @timev() + + This is a verbose version of the "@time" macro, it first prints + the same information as "@time", then any non-zero memory + allocation counters, and then returns the value of the expression. + ``` + """ Base.@timev + + @doc doc""" + ```rst + @timed() + + A macro to execute an expression, and return the value of the + expression, elapsed time, total bytes allocated, garbage collection + time, and an object with various memory allocation counters. + ``` + """ Base.@timed + + @doc doc""" + ```rst + @elapsed() + + A macro to evaluate an expression, discarding the resulting value, + instead returning the number of seconds it took to execute as a + floating-point number. + ``` + """ Base.@elapsed + + @doc doc""" + ```rst + @allocated() + + A macro to evaluate an expression, discarding the resulting value, + instead returning the total number of bytes allocated during + evaluation of the expression. Note: the expression is evaluated + inside a local function, instead of the current context, in order + to eliminate the effects of compilation, however, there still may + be some allocations due to JIT compilation. This also makes the + results inconsistent with the "@time" macros, which do not try to + adjust for the effects of compilation. + ``` + """ Base.@allocated + + @doc doc""" + ```rst + EnvHash() -> EnvHash + + A singleton of this type provides a hash table interface to + environment variables. + ``` + """ Base.EnvHash + + @doc doc""" + ```rst + ENV + + Reference to the singleton "EnvHash", providing a dictionary + interface to system environment variables. + ``` + """ Base.ENV + + @doc doc""" + ```rst + @unix() + + Given "@unix? a : b", do "a" on Unix systems (including Linux + and OS X) and "b" elsewhere. See documentation for Handling + Platform Variations in the Calling C and Fortran Code section of + the manual. + ``` + """ Base.@unix + + @doc doc""" + ```rst + @osx() + + Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. + ``` + """ Base.@osx + + @doc doc""" + ```rst + @linux() + + Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. + ``` + """ Base.@linux + + @doc doc""" + ```rst + @windows() + + Given "@windows? a : b", do "a" on Windows and "b" elsewhere. + See documentation for Handling Platform Variations in the Calling C + and Fortran Code section of the manual. + ``` + """ Base.@windows + + @doc doc""" + ```rst + error(message::AbstractString) + + Raise an "ErrorException" with the given message + ``` + """ Base.error + + @doc doc""" + ```rst + throw(e) + + Throw an object as an exception + ``` + """ Base.throw + + @doc doc""" + ```rst + rethrow([e]) + + Throw an object without changing the current exception backtrace. + The default argument is the current exception (if called within a + "catch" block). + ``` + """ Base.rethrow + + @doc doc""" + ```rst + backtrace() + + Get a backtrace object for the current program point. + ``` + """ Base.backtrace + + @doc doc""" + ```rst + catch_backtrace() + + Get the backtrace of the current exception, for use within + "catch" blocks. + ``` + """ Base.catch_backtrace + + @doc doc""" + ```rst + assert(cond) + + Throw an "AssertionError" if "cond" is false. Also available as + the macro "@assert expr". + ``` + """ Base.assert + + @doc doc""" + ```rst + ArgumentError(msg) + + The parameters to a function call do not match a valid signature. + ``` + """ Base.ArgumentError + + @doc doc""" + ```rst + AssertionError([msg]) + + The asserted condition did not evalutate to "true". + ``` + """ Base.AssertionError + + @doc doc""" + ```rst + BoundsError([a][, i]) + + An indexing operation into an array, "a", tried to access an out- + of-bounds element, "i". + ``` + """ Base.BoundsError + + @doc doc""" + ```rst + DimensionMismatch([msg]) + + The objects called do not have matching dimensionality. + ``` + """ Base.DimensionMismatch + + @doc doc""" + ```rst + DivideError() + + Integer division was attempted with a denominator value of 0. + ``` + """ Base.DivideError + + @doc doc""" + ```rst + DomainError() + + The arguments to a function or constructor are outside the valid + domain. + ``` + """ Base.DomainError + + @doc doc""" + ```rst + EOFError() + + No more data was available to read from a file or stream. + ``` + """ Base.EOFError + + @doc doc""" + ```rst + ErrorException(msg) + + Generic error type. The error message, in the *.msg* field, may + provide more specific details. + ``` + """ Base.ErrorException + + @doc doc""" + ```rst + InexactError() + + Type conversion cannot be done exactly. + ``` + """ Base.InexactError + + @doc doc""" + ```rst + InterruptException() + + The process was stopped by a terminal interrupt (CTRL+C). + ``` + """ Base.InterruptException + + @doc doc""" + ```rst + KeyError(key) + + An indexing operation into an "Associative" ("Dict") or "Set" + like object tried to access or delete a non-existent element. + ``` + """ Base.KeyError + + @doc doc""" + ```rst + LoadError(file::AbstractString, line::Int, error) + + An error occurred while *including*, *requiring*, or *using* a + file. The error specifics should be available in the *.error* + field. + ``` + """ Base.LoadError + + @doc doc""" + ```rst + MethodError(f, args) + + A method with the required type signature does not exist in the + given generic function. + ``` + """ Base.MethodError + + @doc doc""" + ```rst + NullException() + + An attempted access to a "Nullable" with no defined value. + ``` + """ Base.NullException + + @doc doc""" + ```rst + OutOfMemoryError() + + An operation allocated too much memory for either the system or the + garbage collector to handle properly. + ``` + """ Base.OutOfMemoryError + + @doc doc""" + ```rst + ReadOnlyMemoryError() + + An operation tried to write to memory that is read-only. + ``` + """ Base.ReadOnlyMemoryError + + @doc doc""" + ```rst + OverflowError() + + The result of an expression is too large for the specified type and + will cause a wraparound. + ``` + """ Base.OverflowError + + @doc doc""" + ```rst + ParseError(msg) + + The expression passed to the *parse* function could not be + interpreted as a valid Julia expression. + ``` + """ Base.ParseError + + @doc doc""" + ```rst + ProcessExitedException() + + After a client Julia process has exited, further attempts to + reference the dead child will throw this exception. + ``` + """ Base.ProcessExitedException + + @doc doc""" + ```rst + StackOverflowError() + + The function call grew beyond the size of the call stack. This + usually happens when a call recurses infinitely. + ``` + """ Base.StackOverflowError + + @doc doc""" + ```rst + SystemError(prefix::AbstractString[, errnum::Int32]) + + A system call failed with an error code (in the "errno" global + variable). + ``` + """ Base.SystemError + + @doc doc""" + ```rst + TypeError(func::Symbol, context::AbstractString, expected::Type, got) + + A type assertion failure, or calling an intrinsic function with an + incorrect argument type. + ``` + """ Base.TypeError + + @doc doc""" + ```rst + UndefRefError() + + The item or field is not defined for the given object. + ``` + """ Base.UndefRefError + + @doc doc""" + ```rst + UndefVarError(var::Symbol) + + A symbol in the current scope is not defined. + ``` + """ Base.UndefVarError + + @doc doc""" + ```rst + Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. The callback is + passed one argument, the timer object itself. The callback will be + invoked after the specified initial delay, and then repeating with + the given "repeat" interval. If "repeat" is "0", the timer is + only triggered once. Times are in seconds. A timer is stopped and + has its resources freed by calling "close" on it. + ``` + """ Base.Timer + + @doc doc""" + ```rst + Timer(delay, repeat=0) + + Create a timer that wakes up tasks waiting for it (by calling + "wait" on the timer object) at a specified interval. + ``` + """ Base.Timer + + @doc doc""" + ```rst + module_name(m::Module) -> Symbol + + Get the name of a module as a symbol. + ``` + """ Base.module_name + + @doc doc""" + ```rst + module_parent(m::Module) -> Module + + Get a module's enclosing module. "Main" is its own parent. + ``` + """ Base.module_parent + + @doc doc""" + ```rst + current_module() -> Module + + Get the *dynamically* current module, which is the module code is + currently being read from. In general, this is not the same as the + module containing the call to this function. + ``` + """ Base.current_module + + @doc doc""" + ```rst + fullname(m::Module) + + Get the fully-qualified name of a module as a tuple of symbols. For + example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and + "fullname(Main)" gives "()". + ``` + """ Base.fullname + + @doc doc""" + ```rst + names(x::Module[, all=false[, imported=false]]) + + Get an array of the names exported by a module, with optionally + more module globals according to the additional parameters. + ``` + """ Base.names + + @doc doc""" + ```rst + nfields(x::DataType) -> Int + + Get the number of fields of a data type. + ``` + """ Base.nfields + + @doc doc""" + ```rst + fieldnames(x::DataType) + + Get an array of the fields of a data type. + ``` + """ Base.fieldnames + + @doc doc""" + ```rst + isconst([m::Module], s::Symbol) -> Bool + + Determine whether a global is declared "const" in a given module. + The default module argument is "current_module()". + ``` + """ Base.isconst + + @doc doc""" + ```rst + isgeneric(f::Function) -> Bool + + Determine whether a function is generic. + ``` + """ Base.isgeneric + + @doc doc""" + ```rst + function_name(f::Function) -> Symbol + + Get the name of a generic function as a symbol, or ":anonymous". + ``` + """ Base.function_name + + @doc doc""" + ```rst + function_module(f::Function, types) -> Module + + Determine the module containing a given definition of a generic + function. + ``` + """ Base.function_module + + @doc doc""" + ```rst + functionloc(f::Function, types) + + Returns a tuple "(filename,line)" giving the location of a method + definition. + ``` + """ Base.functionloc + + @doc doc""" + ```rst + functionloc(m::Method) + + Returns a tuple "(filename,line)" giving the location of a method + definition. + ``` + """ Base.functionloc + + @doc doc""" + ```rst + gc() + + Perform garbage collection. This should not generally be used. + ``` + """ Base.gc + + @doc doc""" + ```rst + gc_enable(on::Bool) + + Control whether garbage collection is enabled using a boolean + argument (true for enabled, false for disabled). Returns previous + GC state. Disabling garbage collection should be used only with + extreme caution, as it can cause memory use to grow without bound. + ``` + """ Base.gc_enable + + @doc doc""" + ```rst + macroexpand(x) + + Takes the expression x and returns an equivalent expression with + all macros removed (expanded). + ``` + """ Base.macroexpand + + @doc doc""" + ```rst + expand(x) + + Takes the expression x and returns an equivalent expression in + lowered form + ``` + """ Base.expand + + @doc doc""" + ```rst + code_lowered(f, types) + + Returns an array of lowered ASTs for the methods matching the given + generic function and type signature. + ``` + """ Base.code_lowered + + @doc doc""" + ```rst + @code_lowered() + + Evaluates the arguments to the function call, determines their + types, and calls "code_lowered()" on the resulting expression + ``` + """ Base.@code_lowered + + @doc doc""" + ```rst + code_typed(f, types; optimize=true) + + Returns an array of lowered and type-inferred ASTs for the methods + matching the given generic function and type signature. The keyword + argument "optimize" controls whether additional optimizations, + such as inlining, are also applied. + ``` + """ Base.code_typed + + @doc doc""" + ```rst + @code_typed() + + Evaluates the arguments to the function call, determines their + types, and calls "code_typed()" on the resulting expression + ``` + """ Base.@code_typed + + @doc doc""" + ```rst + code_warntype(f, types) + + Displays lowered and type-inferred ASTs for the methods matching + the given generic function and type signature. The ASTs are + annotated in such a way as to cause "non-leaf" types to be + emphasized (if color is available, displayed in red). This serves + as a warning of potential type instability. Not all non-leaf types + are particularly problematic for performance, so the results need + to be used judiciously. See *@code_warntype* for more information. + ``` + """ Base.code_warntype + + @doc doc""" + ```rst + @code_warntype() + + Evaluates the arguments to the function call, determines their + types, and calls "code_warntype()" on the resulting expression + ``` + """ Base.@code_warntype + + @doc doc""" + ```rst + code_llvm(f, types) + + Prints the LLVM bitcodes generated for running the method matching + the given generic function and type signature to "STDOUT". + + All metadata and dbg.* calls are removed from the printed bitcode. + Use code_llvm_raw for the full IR. + ``` + """ Base.code_llvm + + @doc doc""" + ```rst + @code_llvm() + + Evaluates the arguments to the function call, determines their + types, and calls "code_llvm()" on the resulting expression + ``` + """ Base.@code_llvm + + @doc doc""" + ```rst + code_native(f, types) + + Prints the native assembly instructions generated for running the + method matching the given generic function and type signature to + STDOUT. + ``` + """ Base.code_native + + @doc doc""" + ```rst + @code_native() + + Evaluates the arguments to the function call, determines their + types, and calls "code_native()" on the resulting expression + ``` + """ Base.@code_native + + @doc doc""" + ```rst + precompile(f, args::Tuple{Vararg{Any}}) + + Compile the given function "f" for the argument tuple (of types) + "args", but do not execute it. + ``` + """ Base.precompile + + @doc doc""" + ```rst + ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) + + Call function in C-exported shared library, specified by + "(function name, library)" tuple, where each component is an + AbstractString or :Symbol. + + Note that the argument type tuple must be a literal tuple, and not + a tuple-valued variable or expression. Alternatively, ccall may + also be used to call a function pointer, such as one returned by + dlsym. + + Each "ArgumentValue" to the "ccall" will be converted to the + corresponding "ArgumentType", by automatic insertion of calls to + "unsafe_convert(ArgumentType, cconvert(ArgumentType, + ArgumentValue))". (see also the documentation for each of these + functions for further details). In most cases, this simply results + in a call to "convert(ArgumentType, ArgumentValue)" + ``` + """ Base.ccall + + @doc doc""" + ```rst + cglobal((symbol, library)[, type=Void]) + + Obtain a pointer to a global variable in a C-exported shared + library, specified exactly as in "ccall". Returns a + "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is + supplied. The values can be read or written by "unsafe_load" or + "unsafe_store!", respectively. + ``` + """ Base.cglobal + + @doc doc""" + ```rst + cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + + Generate C-callable function pointer from Julia function. Type + annotation of the return value in the callback function is a must + for situations where Julia cannot infer the return type + automatically. + + For example: + + function foo() + # body + + retval::Float64 + end + + bar = cfunction(foo, Float64, ()) + ``` + """ Base.cfunction + + @doc doc""" + ```rst + unsafe_convert(T, x) + + Convert "x" to a value of type "T" + + In cases where "convert" would need to take a Julia object and + turn it into a "Ptr", this function should be used to define and + perform that conversion. + + Be careful to ensure that a julia reference to "x" exists as long + as the result of this function will be used. Accordingly, the + argument "x" to this function should never be an expression, only + a variable name or field reference. For example, "x=a.b.c" is + acceptable, but "x=[a,b,c]" is not. + + The "unsafe" prefix on this function indicates that using the + result of this function after the "x" argument to this function + is no longer accessible to the program may cause undefined + behavior, including program corruption or segfaults, at any later + time. + ``` + """ Base.unsafe_convert + + @doc doc""" + ```rst + cconvert(T, x) + + Convert "x" to a value of type "T", typically by calling + "convert(T,x)" + + In cases where "x" cannot be safely converted to "T", unlike + "convert", "cconvert" may return an object of a type different + from "T", which however is suitable for "unsafe_convert" to + handle. + + Neither "convert" nor "cconvert" should take a Julia object and + turn it into a "Ptr". + ``` + """ Base.cconvert + + @doc doc""" + ```rst + unsafe_load(p::Ptr{T}, i::Integer) + + Load a value of type "T" from the address of the ith element + (1-indexed) starting at "p". This is equivalent to the C + expression "p[i-1]". + + The "unsafe" prefix on this function indicates that no validation + is performed on the pointer "p" to ensure that it is valid. + Incorrect usage may segfault your program or return garbage + answers, in the same manner as C. + ``` + """ Base.unsafe_load + + @doc doc""" + ```rst + unsafe_store!(p::Ptr{T}, x, i::Integer) + + Store a value of type "T" to the address of the ith element + (1-indexed) starting at "p". This is equivalent to the C + expression "p[i-1] = x". + + The "unsafe" prefix on this function indicates that no validation + is performed on the pointer "p" to ensure that it is valid. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. + ``` + """ Base.unsafe_store! + + @doc doc""" + ```rst + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy "N" elements from a source pointer to a destination, with no + checking. The size of an element is determined by the type of the + pointers. + + The "unsafe" prefix on this function indicates that no validation + is performed on the pointers "dest" and "src" to ensure that + they are valid. Incorrect usage may corrupt or segfault your + program, in the same manner as C. + ``` + """ Base.unsafe_copy! + + @doc doc""" + ```rst + unsafe_copy!(dest::Array, do, src::Array, so, N) + + Copy "N" elements from a source array to a destination, starting + at offset "so" in the source and "do" in the destination + (1-indexed). + + The "unsafe" prefix on this function indicates that no validation + is performed to ensure that N is inbounds on either array. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. + ``` + """ Base.unsafe_copy! + + @doc doc""" + ```rst + copy!(dest, src) + + Copy all elements from collection "src" to array "dest". + Returns "dest". + ``` + """ Base.copy! + + @doc doc""" + ```rst + copy!(dest, do, src, so, N) + + Copy "N" elements from collection "src" starting at offset + "so", to array "dest" starting at offset "do". Returns + "dest". + ``` + """ Base.copy! + + @doc doc""" + ```rst + pointer(array[, index]) + + Get the native address of an array or string element. Be careful to + ensure that a julia reference to "a" exists as long as this + pointer will be used. This function is "unsafe" like + "unsafe_convert". + + Calling "Ref(array[, index])" is generally preferable to this + function. + ``` + """ Base.pointer + + @doc doc""" + ```rst + pointer_to_array(pointer, dims[, take_ownership::Bool]) + + Wrap a native pointer as a Julia Array object. The pointer element + type determines the array element type. "own" optionally + specifies whether Julia should take ownership of the memory, + calling "free" on the pointer when the array is no longer + referenced. + ``` + """ Base.pointer_to_array + + @doc doc""" + ```rst + pointer_from_objref(object_instance) + + Get the memory address of a Julia object as a "Ptr". The + existence of the resulting "Ptr" will not protect the object from + garbage collection, so you must ensure that the object remains + referenced for the whole time that the "Ptr" will be used. + ``` + """ Base.pointer_from_objref + + @doc doc""" + ```rst + unsafe_pointer_to_objref(p::Ptr) + + Convert a "Ptr" to an object reference. Assumes the pointer + refers to a valid heap-allocated Julia object. If this is not the + case, undefined behavior results, hence this function is considered + "unsafe" and should be used with care. + ``` + """ Base.unsafe_pointer_to_objref + + @doc doc""" + ```rst + disable_sigint(f::Function) + + Disable Ctrl-C handler during execution of a function, for calling + external code that is not interrupt safe. Intended to be called + using "do" block syntax as follows: + + disable_sigint() do + # interrupt-unsafe code + ... + end + ``` + """ Base.disable_sigint + + @doc doc""" + ```rst + reenable_sigint(f::Function) + + Re-enable Ctrl-C handler during execution of a function. + Temporarily reverses the effect of "disable_sigint". + ``` + """ Base.reenable_sigint + + @doc doc""" + ```rst + systemerror(sysfunc, iftrue) + + Raises a "SystemError" for "errno" with the descriptive string + "sysfunc" if "bool" is true + ``` + """ Base.systemerror + + @doc doc""" + ```rst + Cchar + + Equivalent to the native "char" c-type + ``` + """ Base.Cchar + + @doc doc""" + ```rst + Cuchar + + Equivalent to the native "unsigned char" c-type (UInt8) + ``` + """ Base.Cuchar + + @doc doc""" + ```rst + Cshort + + Equivalent to the native "signed short" c-type (Int16) + ``` + """ Base.Cshort + + @doc doc""" + ```rst + Cushort + + Equivalent to the native "unsigned short" c-type (UInt16) + ``` + """ Base.Cushort + + @doc doc""" + ```rst + Cint + + Equivalent to the native "signed int" c-type (Int32) + ``` + """ Base.Cint + + @doc doc""" + ```rst + Cuint + + Equivalent to the native "unsigned int" c-type (UInt32) + ``` + """ Base.Cuint + + @doc doc""" + ```rst + Clong + + Equivalent to the native "signed long" c-type + ``` + """ Base.Clong + + @doc doc""" + ```rst + Culong + + Equivalent to the native "unsigned long" c-type + ``` + """ Base.Culong + + @doc doc""" + ```rst + Clonglong + + Equivalent to the native "signed long long" c-type (Int64) + ``` + """ Base.Clonglong + + @doc doc""" + ```rst + Culonglong + + Equivalent to the native "unsigned long long" c-type (UInt64) + ``` + """ Base.Culonglong + + @doc doc""" + ```rst + Cintmax_t + + Equivalent to the native "intmax_t" c-type (Int64) + ``` + """ Base.Cintmax_t + + @doc doc""" + ```rst + Cuintmax_t + + Equivalent to the native "uintmax_t" c-type (UInt64) + ``` + """ Base.Cuintmax_t + + @doc doc""" + ```rst + Csize_t + + Equivalent to the native "size_t" c-type (UInt) + ``` + """ Base.Csize_t + + @doc doc""" + ```rst + Cssize_t + + Equivalent to the native "ssize_t" c-type + ``` + """ Base.Cssize_t + + @doc doc""" + ```rst + Cptrdiff_t + + Equivalent to the native "ptrdiff_t" c-type (Int) + ``` + """ Base.Cptrdiff_t + + @doc doc""" + ```rst + Coff_t + + Equivalent to the native "off_t" c-type + ``` + """ Base.Coff_t + + @doc doc""" + ```rst + Cwchar_t + + Equivalent to the native "wchar_t" c-type (Int32) + ``` + """ Base.Cwchar_t + + @doc doc""" + ```rst + Cfloat + + Equivalent to the native "float" c-type (Float32) + ``` + """ Base.Cfloat + + @doc doc""" + ```rst + Cdouble + + Equivalent to the native "double" c-type (Float64) + ``` + """ Base.Cdouble + + @doc doc""" + ```rst + start(iter) -> state + + Get initial iteration state for an iterable object + ``` + """ Base.start + + @doc doc""" + ```rst + done(iter, state) -> Bool + + Test whether we are done iterating + ``` + """ Base.done + + @doc doc""" + ```rst + next(iter, state) -> item, state + + For a given iterable object and iteration state, return the current + item and the next iteration state + ``` + """ Base.next + + @doc doc""" + ```rst + zip(iters...) + + For a set of iterable objects, returns an iterable of tuples, where + the "i"th tuple contains the "i"th component of each input + iterable. + + Note that "zip()" is its own inverse: + "collect(zip(zip(a...)...)) == collect(a)". + ``` + """ Base.zip + + @doc doc""" + ```rst + enumerate(iter) + + An iterator that yields "(i, x)" where "i" is an index starting + at 1, and "x" is the "i"th value from the given iterator. It's + useful when you need not only the values "x" over which you are + iterating, but also the index "i" of the iterations. + + julia> a = ["a", "b", "c"]; + + julia> for (index, value) in enumerate(a) + println("\$index \$value") + end + 1 a + 2 b + 3 c + ``` + """ Base.enumerate + + @doc doc""" + ```rst + rest(iter, state) + + An iterator that yields the same elements as "iter", but starting + at the given "state". + ``` + """ Base.rest + + @doc doc""" + ```rst + countfrom(start=1, step=1) + + An iterator that counts forever, starting at "start" and + incrementing by "step". + ``` + """ Base.countfrom + + @doc doc""" + ```rst + take(iter, n) + + An iterator that generates at most the first "n" elements of + "iter". + ``` + """ Base.take + + @doc doc""" + ```rst + drop(iter, n) + + An iterator that generates all but the first "n" elements of + "iter". + ``` + """ Base.drop + + @doc doc""" + ```rst + cycle(iter) + + An iterator that cycles through "iter" forever. + ``` + """ Base.cycle + + @doc doc""" + ```rst + repeated(x[, n::Int]) + + An iterator that generates the value "x" forever. If "n" is + specified, generates "x" that many times (equivalent to + "take(repeated(x), n)"). + ``` + """ Base.repeated + + @doc doc""" + ```rst + isempty(collection) -> Bool + + Determine whether a collection is empty (has no elements). + + julia> isempty([]) + true + + julia> isempty([1 2 3]) + false + ``` + """ Base.isempty + + @doc doc""" + ```rst + empty!(collection) -> collection + + Remove all elements from a "collection". + ``` + """ Base.empty! + + @doc doc""" + ```rst + length(collection) -> Integer + + For ordered, indexable collections, the maximum index "i" for + which "getindex(collection, i)" is valid. For unordered + collections, the number of elements. + ``` + """ Base.length + + @doc doc""" + ```rst + endof(collection) -> Integer + + Returns the last index of the collection. + + julia> endof([1,2,4]) + 3 + ``` + """ Base.endof + + @doc doc""" + ```rst + 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)". + ``` + """ Base.in + + @doc doc""" + ```rst + 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 "(key,value)" tuple type. 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. + ``` + """ Base.eltype + + @doc doc""" + ```rst + 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". + ``` + """ Base.indexin + + @doc doc""" + ```rst + findin(a, b) + + Returns the indices of elements in collection "a" that appear in + collection "b" + ``` + """ Base.findin + + @doc doc""" + ```rst + 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". + ``` + """ Base.unique + + @doc doc""" + ```rst + 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. + ``` + """ Base.reduce + + @doc doc""" + ```rst + 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". + ``` + """ Base.reduce + + @doc doc""" + ```rst + foldl(op, v0, itr) + + Like "reduce()", but with guaranteed left associativity. "v0" + will be used exactly once. + ``` + """ Base.foldl + + @doc doc""" + ```rst + 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)"). + ``` + """ Base.foldl + + @doc doc""" + ```rst + foldr(op, v0, itr) + + Like "reduce()", but with guaranteed right associativity. "v0" + will be used exactly once. + ``` + """ Base.foldr + + @doc doc""" + ```rst + 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)"). + ``` + """ Base.foldr + + @doc doc""" + ```rst + maximum(itr) + + Returns the largest element in a collection. + ``` + """ Base.maximum + + @doc doc""" + ```rst + maximum(A, dims) + + Compute the maximum value of an array over the given dimensions. + ``` + """ Base.maximum + + @doc doc""" + ```rst + maximum!(r, A) + + Compute the maximum value of "A" over the singleton dimensions of + "r", and write results to "r". + ``` + """ Base.maximum! + + @doc doc""" + ```rst + minimum(itr) + + Returns the smallest element in a collection. + ``` + """ Base.minimum + + @doc doc""" + ```rst + minimum(A, dims) + + Compute the minimum value of an array over the given dimensions. + ``` + """ Base.minimum + + @doc doc""" + ```rst + minimum!(r, A) + + Compute the minimum value of "A" over the singleton dimensions of + "r", and write results to "r". + ``` + """ Base.minimum! + + @doc doc""" + ```rst + extrema(itr) + + Compute both the minimum and maximum element in a single pass, and + return them as a 2-tuple. + ``` + """ Base.extrema + + @doc doc""" + ```rst + indmax(itr) -> Integer + + Returns the index of the maximum element in a collection. + ``` + """ Base.indmax + + @doc doc""" + ```rst + indmin(itr) -> Integer + + Returns the index of the minimum element in a collection. + ``` + """ Base.indmin + + @doc doc""" + ```rst + findmax(itr) -> (x, index) + + Returns the maximum element and its index. + ``` + """ Base.findmax + + @doc doc""" + ```rst + findmax(A, dims) -> (maxval, index) + + For an array input, returns the value and index of the maximum over + the given dimensions. + ``` + """ Base.findmax + + @doc doc""" + ```rst + findmin(itr) -> (x, index) + + Returns the minimum element and its index. + ``` + """ Base.findmin + + @doc doc""" + ```rst + findmin(A, dims) -> (minval, index) + + For an array input, returns the value and index of the minimum over + the given dimensions. + ``` + """ Base.findmin + + @doc doc""" + ```rst + maxabs(itr) + + Compute the maximum absolute value of a collection of values. + ``` + """ Base.maxabs + + @doc doc""" + ```rst + maxabs(A, dims) + + Compute the maximum absolute values over given dimensions. + ``` + """ Base.maxabs + + @doc doc""" + ```rst + maxabs!(r, A) + + Compute the maximum absolute values over the singleton dimensions + of "r", and write values to "r". + ``` + """ Base.maxabs! + + @doc doc""" + ```rst + minabs(itr) + + Compute the minimum absolute value of a collection of values. + ``` + """ Base.minabs + + @doc doc""" + ```rst + minabs(A, dims) + + Compute the minimum absolute values over given dimensions. + ``` + """ Base.minabs + + @doc doc""" + ```rst + minabs!(r, A) + + Compute the minimum absolute values over the singleton dimensions + of "r", and write values to "r". + ``` + """ Base.minabs! + + @doc doc""" + ```rst + sum(itr) + + Returns the sum of all elements in a collection. + ``` + """ Base.sum + + @doc doc""" + ```rst + sum(A, dims) + + Sum elements of an array over the given dimensions. + ``` + """ Base.sum + + @doc doc""" + ```rst + sum!(r, A) + + Sum elements of "A" over the singleton dimensions of "r", and + write results to "r". + ``` + """ Base.sum! + + @doc doc""" + ```rst + sum(f, itr) + + Sum the results of calling function "f" on each element of + "itr". + ``` + """ Base.sum + + @doc doc""" + ```rst + sumabs(itr) + + Sum absolute values of all elements in a collection. This is + equivalent to *sum(abs(itr))* but faster. + ``` + """ Base.sumabs + + @doc doc""" + ```rst + sumabs(A, dims) + + Sum absolute values of elements of an array over the given + dimensions. + ``` + """ Base.sumabs + + @doc doc""" + ```rst + sumabs!(r, A) + + Sum absolute values of elements of "A" over the singleton + dimensions of "r", and write results to "r". + ``` + """ Base.sumabs! + + @doc doc""" + ```rst + sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This + is equivalent to *sum(abs2(itr))* but faster. + ``` + """ Base.sumabs2 + + @doc doc""" + ```rst + sumabs2(A, dims) + + Sum squared absolute values of elements of an array over the given + dimensions. + ``` + """ Base.sumabs2 + + @doc doc""" + ```rst + sumabs2!(r, A) + + Sum squared absolute values of elements of "A" over the singleton + dimensions of "r", and write results to "r". + ``` + """ Base.sumabs2! + + @doc doc""" + ```rst + prod(itr) + + Returns the product of all elements of a collection. + ``` + """ Base.prod + + @doc doc""" + ```rst + prod(A, dims) + + Multiply elements of an array over the given dimensions. + ``` + """ Base.prod + + @doc doc""" + ```rst + prod!(r, A) + + Multiply elements of "A" over the singleton dimensions of "r", + and write results to "r". + ``` + """ Base.prod! + + @doc doc""" + ```rst + any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + ``` + """ Base.any + + @doc doc""" + ```rst + any(A, dims) + + Test whether any values along the given dimensions of an array are + true. + ``` + """ Base.any + + @doc doc""" + ```rst + any!(r, A) + + Test whether any values in "A" along the singleton dimensions of + "r" are true, and write results to "r". + ``` + """ Base.any! + + @doc doc""" + ```rst + all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + ``` + """ Base.all + + @doc doc""" + ```rst + all(A, dims) + + Test whether all values along the given dimensions of an array are + true. + ``` + """ Base.all + + @doc doc""" + ```rst + all!(r, A) + + Test whether all values in "A" along the singleton dimensions of + "r" are true, and write results to "r". + ``` + """ Base.all! + + @doc doc""" + ```rst + count(p, itr) -> Integer + + Count the number of elements in "itr" for which predicate "p" + returns true. + ``` + """ Base.count + + @doc doc""" + ```rst + any(p, itr) -> Bool + + Determine whether predicate "p" returns true for any elements of + "itr". + ``` + """ Base.any + + @doc doc""" + ```rst + all(p, itr) -> Bool + + Determine whether predicate "p" returns true for all elements of + "itr". + + julia> all(i->(4<=i<=6), [4,5,6]) + true + ``` + """ Base.all + + @doc doc""" + ```rst + 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 + ``` + """ Base.map + + @doc doc""" + ```rst + map!(function, collection) + + In-place version of "map()". + ``` + """ Base.map! + + @doc doc""" + ```rst + 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. + ``` + """ Base.map! + + @doc doc""" + ```rst + 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 + + @doc doc""" + ```rst + mapreduce(f, op, itr) + + Like "mapreduce(f, op, v0, itr)". In general, this cannot be used + with empty collections (see "reduce(op, itr)"). + ``` + """ Base.mapreduce + + @doc doc""" + ```rst + mapfoldl(f, op, v0, itr) + + Like "mapreduce()", but with guaranteed left associativity. + "v0" will be used exactly once. + ``` + """ Base.mapfoldl + + @doc doc""" + ```rst + 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.mapfoldl + + @doc doc""" + ```rst + mapfoldr(f, op, v0, itr) + + Like "mapreduce()", but with guaranteed right associativity. + "v0" will be used exactly once. + ``` + """ Base.mapfoldr + + @doc doc""" + ```rst + 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.mapfoldr + + @doc doc""" + ```rst + first(coll) + + Get the first element of an iterable collection. Returns the start + point of a "Range" even if it is empty. + ``` + """ Base.first + + @doc doc""" + ```rst + 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. + ``` + """ Base.last + + @doc doc""" + ```rst + step(r) + + Get the step size of a "Range" object. + ``` + """ Base.step + + @doc doc""" + ```rst + collect(collection) + + Return an array of all items in a collection. For associative + collections, returns (key, value) tuples. + ``` + """ Base.collect + + @doc doc""" + ```rst + collect(element_type, collection) + + Return an array of type "Array{element_type,1}" of all items in a + collection. + ``` + """ Base.collect + + @doc doc""" + ```rst + issubset(a, b) +⊆(A, S) -> Bool +⊈(A, S) -> Bool +⊊(A, S) -> Bool + + Determine whether every element of "a" is also in "b", using + "in()". + ``` + """ Base.issubset + + @doc doc""" + ```rst + 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). + ``` + """ Base.filter + + @doc doc""" + ```rst + filter!(function, collection) + + Update "collection", removing elements for which "function" is + false. For associative collections, the function is passed two + arguments (key and value). + ``` + """ Base.filter! + + @doc doc""" + ```rst + 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, ...)". + ``` + """ Base.getindex + + @doc doc""" + ```rst + 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, ...)". + ``` + """ Base.setindex! + + @doc doc""" + ```rst + 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{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 + + Alternatively, a sequence of pair arguments may be passed. + + julia> Dict("A"=>1, "B"=>2) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 + ``` + """ Base.Dict + + @doc doc""" + ```rst + haskey(collection, key) -> Bool + + Determine whether a collection has a mapping for a given key. + ``` + """ Base.haskey + + @doc doc""" + ```rst + 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. + ``` + """ Base.get + + @doc doc""" + ```rst + 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 + ``` + """ Base.get + + @doc doc""" + ```rst + 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". + ``` + """ Base.get! + + @doc doc""" + ```rst + 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 + ``` + """ Base.get! + + @doc doc""" + ```rst + getkey(collection, key, default) + + Return the key matching argument "key" if one exists in + "collection", otherwise return "default". + ``` + """ Base.getkey + + @doc doc""" + ```rst + delete!(collection, key) + + Delete the mapping for the given key in a collection, and return + the collection. + ``` + """ Base.delete! + + @doc doc""" + ```rst + 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. + ``` + """ Base.pop! + + @doc doc""" + ```rst + keys(collection) + + Return an iterator over all keys in a collection. + "collect(keys(d))" returns an array of keys. + ``` + """ Base.keys + + @doc doc""" + ```rst + values(collection) + + Return an iterator over all values in a collection. + "collect(values(d))" returns an array of values. + ``` + """ Base.values + + @doc doc""" + ```rst + merge(collection, others...) + + 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. + + julia> a = Dict("foo" => 0.0, "bar" => 42.0) + Dict{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 + + julia> b = Dict(utf8("baz") => 17, utf8("qux") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "baz" => 17 + "qux" => 4711 + + julia> merge(a, b) + Dict{UTF8String,Float64} with 4 entries: + "qux" => 4711.0 + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 + ``` + """ Base.merge + + @doc doc""" + ```rst + merge!(collection, others...) + + Update collection with pairs from the other collections + ``` + """ Base.merge! + + @doc doc""" + ```rst + sizehint!(s, n) + + Suggest that collection "s" reserve capacity for at least "n" + elements. This can improve performance. + ``` + """ Base.sizehint! + + @doc doc""" + ```rst + 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.Set + + @doc doc""" + ```rst + IntSet([itr]) + + Construct a sorted set of the integers generated by the given + iterable object, or an empty set. Implemented as a bit string, and + therefore designed for dense integer sets. Only non-negative + integers can be stored. If the set will be sparse (for example + holding a single very large integer), use "Set" instead. + ``` + """ Base.IntSet + + @doc doc""" + ```rst + union(s1, s2...) +∪(s1, s2) + + Construct the union of two or more sets. Maintains order with + arrays. + ``` + """ Base.union + + @doc doc""" + ```rst + union!(s, iterable) + + Union each element of "iterable" into set "s" in-place. + ``` + """ Base.union! + + @doc doc""" + ```rst + 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. + ``` + """ Base.intersect + + @doc doc""" + ```rst + setdiff(s1, s2) + + Construct the set of elements in "s1" but not "s2". 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. + ``` + """ Base.setdiff + + @doc doc""" + ```rst + setdiff!(s, iterable) + + Remove each element of "iterable" from set "s" in-place. + ``` + """ Base.setdiff! + + @doc doc""" + ```rst + symdiff(s1, s2...) + + Construct the symmetric difference of elements in the passed in + sets or arrays. Maintains order with arrays. + ``` + """ Base.symdiff + + @doc doc""" + ```rst + symdiff!(s, n) + + The set "s" is destructively modified to toggle the inclusion of + integer "n". + ``` + """ Base.symdiff! + + @doc doc""" + ```rst + symdiff!(s, itr) + + For each element in "itr", destructively toggle its inclusion in + set "s". + ``` + """ Base.symdiff! + + @doc doc""" + ```rst + symdiff!(s1, s2) + + Construct the symmetric difference of sets "s1" and "s2", + storing the result in "s1". + ``` + """ Base.symdiff! + + @doc doc""" + ```rst + complement(s) + + Returns the set-complement of "IntSet" "s". + ``` + """ Base.complement + + @doc doc""" + ```rst + complement!(s) + + Mutates "IntSet" "s" into its set-complement. + ``` + """ Base.complement! + + @doc doc""" + ```rst + intersect!(s1, s2) + + 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.intersect! + + @doc doc""" + ```rst + issubset(A, S) -> Bool +⊆(A, S) -> Bool + + True if A is a subset of or equal to S. + ``` + """ Base.issubset + + @doc doc""" + ```rst + 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])". + ``` + """ Base.push! + + @doc doc""" + ```rst + 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 + ``` + """ Base.pop! + + @doc doc""" + ```rst + 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 + ``` + """ Base.unshift! + + @doc doc""" + ```rst + 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 + ``` + """ Base.shift! + + @doc doc""" + ```rst + insert!(collection, index, item) + + Insert an "item" into "collection" at the given "index". + "index" is the index of "item" in the resulting "collection". + + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 + ``` + """ Base.insert! + + @doc doc""" + ```rst + deleteat!(collection, index) + + Remove the item at the given "index" and return the modified + "collection". 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 + ``` + """ Base.deleteat! + + @doc doc""" + ```rst + deleteat!(collection, itr) + + Remove the items at the indices given by "itr", and return the + modified "collection". Subsequent items are shifted to fill the + resulting gap. "itr" must be sorted and unique. + + 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], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 + ``` + """ Base.deleteat! + + @doc doc""" + ```rst + splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. + Subsequent items are shifted down 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)". + ``` + """ Base.splice! + + @doc doc""" + ```rst + splice!(collection, range[, replacement]) -> items + + Remove items in the specified index range, and return a collection + containing the removed items. Subsequent items are shifted down 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 + ``` + """ Base.splice! + + @doc doc""" + ```rst + resize!(collection, n) -> collection + + Resize "collection" 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 + ``` + """ Base.resize! + + @doc doc""" + ```rst + 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)". + ``` + """ Base.append! + + @doc doc""" + ```rst + prepend!(collection, items) -> collection + + Insert the elements of "items" to the beginning of + "collection". + + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 + ``` + """ Base.prepend! + + @doc doc""" + ```rst + PriorityQueue(K, V[, ord]) + + Construct a new "PriorityQueue", with keys of type "K" and + values/priorites of type "V". If an order is not given, the + priority queue is min-ordered using the default comparison for + "V". + ``` + """ Base.Collections.PriorityQueue + + @doc doc""" + ```rst + enqueue!(pq, k, v) + + Insert the a key "k" into a priority queue "pq" with priority + "v". + ``` + """ Base.Collections.enqueue! + + @doc doc""" + ```rst + dequeue!(pq) + + Remove and return the lowest priority key from a priority queue. + ``` + """ Base.Collections.dequeue! + + @doc doc""" + ```rst + peek(pq) + + Return the lowest priority key from a priority queue without + removing that key from the queue. + ``` + """ Base.Collections.peek + + @doc doc""" + ```rst + heapify(v[, ord]) + + Return a new vector in binary heap order, optionally using the + given ordering. + ``` + """ Base.Collections.heapify + + @doc doc""" + ```rst + heapify!(v[, ord]) + + In-place "heapify()". + ``` + """ Base.Collections.heapify! + + @doc doc""" + ```rst + isheap(v[, ord]) + + Return true iff an array is heap-ordered according to the given + order. + ``` + """ Base.Collections.isheap + + @doc doc""" + ```rst + heappush!(v, x[, ord]) + + Given a binary heap-ordered array, push a new element "x", + preserving the heap property. For efficiency, this function does + not check that the array is indeed heap-ordered. + ``` + """ Base.Collections.heappush! + + @doc doc""" + ```rst + heappop!(v[, ord]) + + Given a binary heap-ordered array, remove and return the lowest + ordered element. For efficiency, this function does not check that + the array is indeed heap-ordered. + ``` + """ Base.Collections.heappop! + + @doc doc""" + ```rst + nothing + + The singleton instance of type "Void", used by convention when + there is no value to return (as in a C "void" function). Can be + converted to an empty "Nullable" value. + ``` + """ Base.nothing + + @doc doc""" + ```rst + OS_NAME + + A symbol representing the name of the operating system. Possible + values are ":Linux", ":Darwin" (OS X), or ":Windows". + ``` + """ Base.OS_NAME + + @doc doc""" + ```rst + ARGS + + An array of the command line arguments passed to Julia, as strings. + ``` + """ Base.ARGS + + @doc doc""" + ```rst + C_NULL + + The C null pointer constant, sometimes used when calling external + code. + ``` + """ Base.C_NULL + + @doc doc""" + ```rst + WORD_SIZE + + Standard word size on the current machine, in bits. + ``` + """ Base.WORD_SIZE + + @doc doc""" + ```rst + VERSION + + An object describing which version of Julia is in use. + ``` + """ Base.VERSION + + @doc doc""" + ```rst + LOAD_PATH + + An array of paths (as strings) where the "require" function looks + for code. + ``` + """ Base.LOAD_PATH + + @doc doc""" + ```rst + ANY + + Equivalent to "Any" for dispatch purposes, but signals the + compiler to skip code generation specialization for that field + ``` + """ Base.ANY + + @doc doc""" + ```rst + Period + ``` + """ Dates.Period + + @doc doc""" + ```rst + Year + ``` + """ Dates.Year + + @doc doc""" + ```rst + Month + ``` + """ Dates.Month + + @doc doc""" + ```rst + Week + ``` + """ Dates.Week + + @doc doc""" + ```rst + Day + ``` + """ Dates.Day + + @doc doc""" + ```rst + Hour + ``` + """ Dates.Hour + + @doc doc""" + ```rst + Minute + ``` + """ Dates.Minute + + @doc doc""" + ```rst + Second + ``` + """ Dates.Second + + @doc doc""" + ```rst + Millisecond + + "Period" types represent discrete, human representations of time. + ``` + """ Dates.Millisecond + + @doc doc""" + ```rst + Instant + + "Instant" types represent integer-based, machine representations + of time as continuous timelines starting from an epoch. + ``` + """ Dates.Instant + + @doc doc""" + ```rst + TimeType + + "TimeType" types wrap "Instant" machine instances to provide + human representations of the machine instant. + ``` + """ Dates.TimeType + + @doc doc""" + ```rst + DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it + according to the proleptic Gregorian calendar. + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to + the proleptic Gregorian calendar. + ``` + """ Dates.Date + + @doc doc""" + ```rst + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to "Int64". + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of "Dates.default(period)". + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided "y, m, d..." arguments, and will + be adjusted until "f::Function" returns true. The step size in + adjusting can be provided manually through the "step" keyword. If + "negate=true", then the adjusting will stop when "f::Function" + returns false instead of true. "limit" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that "f::Function" is never + satisfied). + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, + second, and millisecond parts of the new "DateTime" are assumed + to be zero. + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string + following the pattern given in the "format" string. The following + codes can be used for constructing format strings: + + +-----------------+-----------+-----------------------------------------------------------------+ + | Code | Matches | Comment | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"y\" | 1996, 96 | Returns year of 1996, 0096 | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"m\" | 1, 01 | Matches 1 or 2-digit months | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"U\" | January | Matches full month names according to the \"locale\" keyword | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"d\" | 1, 01 | Matches 1 or 2-digit days | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"H\" | 00 | Matches hours | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"M\" | 00 | Matches minutes | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"S\" | 00 | Matches seconds | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"s\" | .500 | Matches milliseconds | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"e\" | Mon, Tues | Matches abbreviated days of the week | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"E\" | Monday | Matches full name days of the week | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | + +-----------------+-----------+-----------------------------------------------------------------+ + + All characters not listed above are treated as delimiters between + date and time slots. So a "dt" string of + "1996-01-15T00:00:00.0" would have a "format" string like + "y-m-dTH:M:S.s". + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + Dates.DateFormat(format::AbstractString) -> DateFormat + + Construct a date formatting object that can be passed repeatedly + for parsing similarly formatted date strings. "format" is a + format string in the form described above (e.g. ""yyyy-mm- + dd""). + ``` + """ Dates.Dates + + @doc doc""" + ```rst + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. + ``` + """ Dates.DateTime + + @doc doc""" + ```rst + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible + to "Int64". + ``` + """ Dates.Date + + @doc doc""" + ```rst + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + "Dates.default(period)". + ``` + """ Dates.Date + + @doc doc""" + ```rst + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided "y, m" arguments, and will be + adjusted until "f::Function" returns true. The step size in + adjusting can be provided manually through the "step" keyword. If + "negate=true", then the adjusting will stop when "f::Function" + returns false instead of true. "limit" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that "f::Function" is never satisfied). + ``` + """ Dates.Date + + @doc doc""" + ```rst + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, + second, and millisecond parts of the "DateTime" are truncated, so + only the year, month and day parts are used in construction. + ``` + """ Dates.Date + + @doc doc""" + ```rst + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the + pattern given in the "format" string. Follows the same + conventions as "DateTime" above. + ``` + """ Dates.Date + + @doc doc""" + ```rst + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string "dt" using a "DateFormat" + object "df". + ``` + """ Dates.Date + + @doc doc""" + ```rst + now() -> DateTime + + Returns a DateTime corresponding to the user's system time + including the system timezone locale. + ``` + """ Dates.now + + @doc doc""" + ```rst + now(::Type{UTC}) -> DateTime + + Returns a DateTime corresponding to the user's system time as + UTC/GMT. + ``` + """ Dates.now + + @doc doc""" + ```rst + eps(::DateTime) -> Millisecond +eps(::Date) -> Day + + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" + for "Date" values. + ``` + """ Dates.eps + + @doc doc""" + ```rst + year(dt::TimeType) -> Int64 +month(dt::TimeType) -> Int64 +week(dt::TimeType) -> Int64 +day(dt::TimeType) -> Int64 +hour(dt::TimeType) -> Int64 +minute(dt::TimeType) -> Int64 +second(dt::TimeType) -> Int64 +millisecond(dt::TimeType) -> Int64 + + Return the field part of a Date or DateTime as an "Int64". + ``` + """ Dates.year + + @doc doc""" + ```rst + Year(dt::TimeType) -> Year +Month(dt::TimeType) -> Month +Week(dt::TimeType) -> Week +Day(dt::TimeType) -> Day +Hour(dt::TimeType) -> Hour +Minute(dt::TimeType) -> Minute +Second(dt::TimeType) -> Second +Millisecond(dt::TimeType) -> Millisecond + + Return the field part of a Date or DateTime as a "Period" type. + ``` + """ Dates.Year + + @doc doc""" + ```rst + yearmonth(dt::TimeType) -> (Int64, Int64) + + Simultaneously return the year and month parts of a Date or + DateTime. + ``` + """ Dates.yearmonth + + @doc doc""" + ```rst + monthday(dt::TimeType) -> (Int64, Int64) + + Simultaneously return the month and day parts of a Date or + DateTime. + ``` + """ Dates.monthday + + @doc doc""" + ```rst + yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + + Simultaneously return the year, month, and day parts of a Date or + DateTime. + ``` + """ Dates.yearmonthday + + @doc doc""" + ```rst + dayname(dt::TimeType; locale="english") -> AbstractString + + Return the full day name corresponding to the day of the week of + the Date or DateTime in the given "locale". + ``` + """ Dates.dayname + + @doc doc""" + ```rst + dayabbr(dt::TimeType; locale="english") -> AbstractString + + Return the abbreviated name corresponding to the day of the week of + the Date or DateTime in the given "locale". + ``` + """ Dates.dayabbr + + @doc doc""" + ```rst + dayofweek(dt::TimeType) -> Int64 + + Returns the day of the week as an "Int64" with "1 = Monday, 2 = + Tuesday, etc.". + ``` + """ Dates.dayofweek + + @doc doc""" + ```rst + dayofweekofmonth(dt::TimeType) -> Int + + For the day of week of "dt", returns which number it is in + "dt"'s month. So if the day of the week of "dt" is Monday, then + "1 = First Monday of the month, 2 = Second Monday of the month, + etc." In the range 1:5. + ``` + """ Dates.dayofweekofmonth + + @doc doc""" + ```rst + daysofweekinmonth(dt::TimeType) -> Int + + For the day of week of "dt", returns the total number of that day + of the week in "dt"'s month. Returns 4 or 5. Useful in temporal + expressions for specifying the last day of a week in a month by + including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the + adjuster function. + ``` + """ Dates.daysofweekinmonth + + @doc doc""" + ```rst + monthname(dt::TimeType; locale="english") -> AbstractString + + Return the full name of the month of the Date or DateTime in the + given "locale". + ``` + """ Dates.monthname + + @doc doc""" + ```rst + monthabbr(dt::TimeType; locale="english") -> AbstractString + + Return the abbreviated month name of the Date or DateTime in the + given "locale". + ``` + """ Dates.monthabbr + + @doc doc""" + ```rst + daysinmonth(dt::TimeType) -> Int + + Returns the number of days in the month of "dt". Value will be + 28, 29, 30, or 31. + ``` + """ Dates.daysinmonth + + @doc doc""" + ```rst + isleapyear(dt::TimeType) -> Bool + + Returns true if the year of "dt" is a leap year. + ``` + """ Dates.isleapyear + + @doc doc""" + ```rst + dayofyear(dt::TimeType) -> Int + + Returns the day of the year for "dt" with January 1st being day + 1. + ``` + """ Dates.dayofyear + + @doc doc""" + ```rst + daysinyear(dt::TimeType) -> Int + + Returns 366 if the year of "dt" is a leap year, otherwise returns + 365. + ``` + """ Dates.daysinyear + + @doc doc""" + ```rst + quarterofyear(dt::TimeType) -> Int + + Returns the quarter that "dt" resides in. Range of value is 1:4. + ``` + """ Dates.quarterofyear + + @doc doc""" + ```rst + dayofquarter(dt::TimeType) -> Int + + Returns the day of the current quarter of "dt". Range of value is + 1:92. + ``` + """ Dates.dayofquarter + + @doc doc""" + ```rst + trunc(dt::TimeType, ::Type{Period}) -> TimeType + + Truncates the value of "dt" according to the provided "Period" + type. E.g. if "dt" is "1996-01-01T12:30:00", then + "trunc(dt,Day) == 1996-01-01T00:00:00". + ``` + """ Dates.trunc + + @doc doc""" + ```rst + firstdayofweek(dt::TimeType) -> TimeType + + Adjusts "dt" to the Monday of its week. + ``` + """ Dates.firstdayofweek + + @doc doc""" + ```rst + lastdayofweek(dt::TimeType) -> TimeType + + Adjusts "dt" to the Sunday of its week. + ``` + """ Dates.lastdayofweek + + @doc doc""" + ```rst + firstdayofmonth(dt::TimeType) -> TimeType + + Adjusts "dt" to the first day of its month. + ``` + """ Dates.firstdayofmonth + + @doc doc""" + ```rst + lastdayofmonth(dt::TimeType) -> TimeType + + Adjusts "dt" to the last day of its month. + ``` + """ Dates.lastdayofmonth + + @doc doc""" + ```rst + firstdayofyear(dt::TimeType) -> TimeType + + Adjusts "dt" to the first day of its year. + ``` + """ Dates.firstdayofyear + + @doc doc""" + ```rst + lastdayofyear(dt::TimeType) -> TimeType + + Adjusts "dt" to the last day of its year. + ``` + """ Dates.lastdayofyear + + @doc doc""" + ```rst + firstdayofquarter(dt::TimeType) -> TimeType + + Adjusts "dt" to the first day of its quarter. + ``` + """ Dates.firstdayofquarter + + @doc doc""" + ```rst + lastdayofquarter(dt::TimeType) -> TimeType + + Adjusts "dt" to the last day of its quarter. + ``` + """ Dates.lastdayofquarter + + @doc doc""" + ```rst + tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts "dt" to the next day of week corresponding to "dow" + with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows + the current "dt" to be considered as the next "dow", allowing + for no adjustment to occur. + ``` + """ Dates.tonext + + @doc doc""" + ```rst + toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts "dt" to the previous day of week corresponding to "dow" + with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows + the current "dt" to be considered as the previous "dow", + allowing for no adjustment to occur. + ``` + """ Dates.toprev + + @doc doc""" + ```rst + tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + + Adjusts "dt" to the first "dow" of its month. Alternatively, + "of=Year" will adjust to the first "dow" of the year. + ``` + """ Dates.tofirst + + @doc doc""" + ```rst + tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + + Adjusts "dt" to the last "dow" of its month. Alternatively, + "of=Year" will adjust to the last "dow" of the year. + ``` + """ Dates.tolast + + @doc doc""" + ```rst + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. + ``` + """ Dates.tonext + + @doc doc""" + ```rst + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. + ``` + """ Dates.toprev + + @doc doc""" + ```rst + Year(v) +Month(v) +Week(v) +Day(v) +Hour(v) +Minute(v) +Second(v) +Millisecond(v) + + Construct a "Period" type with the given "v" value. Input must + be losslessly convertible to an "Int64". + ``` + """ Dates.Year + + @doc doc""" + ```rst + default(p::Period) -> Period + + Returns a sensible "default" value for the input Period by + returning "one(p)" for Year, Month, and Day, and "zero(p)" for + Hour, Minute, Second, and Millisecond. + ``` + """ Dates.default + + @doc doc""" + ```rst + today() -> Date + + Returns the date portion of "now()". + ``` + """ Dates.today + + @doc doc""" + ```rst + unix2datetime(x) -> DateTime + + Takes the number of seconds since unix epoch + "1970-01-01T00:00:00" and converts to the corresponding DateTime. + ``` + """ Dates.unix2datetime + + @doc doc""" + ```rst + datetime2unix(dt::DateTime) -> Float64 + + Takes the given DateTime and returns the number of seconds since + the unix epoch as a "Float64". + ``` + """ Dates.datetime2unix + + @doc doc""" + ```rst + julian2datetime(julian_days) -> DateTime + + Takes the number of Julian calendar days since epoch + "-4713-11-24T12:00:00" and returns the corresponding DateTime. + ``` + """ Dates.julian2datetime + + @doc doc""" + ```rst + datetime2julian(dt::DateTime) -> Float64 + + Takes the given DateTime and returns the number of Julian calendar + days since the julian epoch as a "Float64". + ``` + """ Dates.datetime2julian + + @doc doc""" + ```rst + rata2datetime(days) -> DateTime + + Takes the number of Rata Die days since epoch + "0000-12-31T00:00:00" and returns the corresponding DateTime. + ``` + """ Dates.rata2datetime + + @doc doc""" + ```rst + datetime2rata(dt::TimeType) -> Int64 + + Returns the number of Rata Die days since epoch from the given Date + or DateTime. + ``` + """ Dates.datetime2rata + + @doc doc""" + ```rst + pwd() -> AbstractString + + Get the current working directory. + ``` + """ Base.pwd + + @doc doc""" + ```rst + cd(dir::AbstractString) + + Set the current working directory. + ``` + """ Base.cd + + @doc doc""" + ```rst + cd(f[, dir]) + + Temporarily changes the current working directory (HOME if not + specified) and applies function f before returning. + ``` + """ Base.cd + + @doc doc""" + ```rst + readdir([dir]) -> Vector{ByteString} + + Returns the files and directories in the directory *dir* (or the + current working directory if not given). + ``` + """ Base.readdir + + @doc doc""" + ```rst + mkdir(path[, mode]) + + Make a new directory with name "path" and permissions "mode". + "mode" defaults to 0o777, modified by the current file creation + mask. + ``` + """ Base.mkdir + + @doc doc""" + ```rst + mkpath(path[, mode]) + + Create all directories in the given "path", with permissions + "mode". "mode" defaults to 0o777, modified by the current file + creation mask. + ``` + """ Base.mkpath + + @doc doc""" + ```rst + symlink(target, link) + + Creates a symbolic link to "target" with the name "link". + + Note: This function raises an error under operating systems that + do not support soft symbolic links, such as Windows XP. + ``` + """ Base.symlink + + @doc doc""" + ```rst + readlink(path) -> AbstractString + + Returns the value of a symbolic link "path". + ``` + """ Base.readlink + + @doc doc""" + ```rst + chmod(path, mode) + + Change the permissions mode of "path" to "mode". Only integer + "mode"s (e.g. 0o777) are currently supported. + ``` + """ Base.chmod + + @doc doc""" + ```rst + stat(file) + + Returns a structure whose fields contain information about the + file. The fields of the structure are: + + +-----------+------------------------------------------------------------------------+ + | size | The size (in bytes) of the file | + +-----------+------------------------------------------------------------------------+ + | device | ID of the device that contains the file | + +-----------+------------------------------------------------------------------------+ + | inode | The inode number of the file | + +-----------+------------------------------------------------------------------------+ + | mode | The protection mode of the file | + +-----------+------------------------------------------------------------------------+ + | nlink | The number of hard links to the file | + +-----------+------------------------------------------------------------------------+ + | uid | The user id of the owner of the file | + +-----------+------------------------------------------------------------------------+ + | gid | The group id of the file owner | + +-----------+------------------------------------------------------------------------+ + | rdev | If this file refers to a device, the ID of the device it refers to | + +-----------+------------------------------------------------------------------------+ + | blksize | The file-system preferred block size for the file | + +-----------+------------------------------------------------------------------------+ + | blocks | The number of such blocks allocated | + +-----------+------------------------------------------------------------------------+ + | mtime | Unix timestamp of when the file was last modified | + +-----------+------------------------------------------------------------------------+ + | ctime | Unix timestamp of when the file was created | + +-----------+------------------------------------------------------------------------+ + ``` + """ Base.stat + + @doc doc""" + ```rst + lstat(file) + + Like stat, but for symbolic links gets the info for the link itself + rather than the file it refers to. This function must be called on + a file path rather than a file object or a file descriptor. + ``` + """ Base.lstat + + @doc doc""" + ```rst + ctime(file) + + Equivalent to stat(file).ctime + ``` + """ Base.ctime + + @doc doc""" + ```rst + mtime(file) + + Equivalent to stat(file).mtime + ``` + """ Base.mtime + + @doc doc""" + ```rst + filemode(file) + + Equivalent to stat(file).mode + ``` + """ Base.filemode + + @doc doc""" + ```rst + filesize(path...) + + Equivalent to stat(file).size + ``` + """ Base.filesize + + @doc doc""" + ```rst + uperm(file) + + Gets the permissions of the owner of the file as a bitfield of + + +------+-----------------------+ + | 01 | Execute Permission | + +------+-----------------------+ + | 02 | Write Permission | + +------+-----------------------+ + | 04 | Read Permission | + +------+-----------------------+ + + For allowed arguments, see "stat". + ``` + """ Base.uperm + + @doc doc""" + ```rst + gperm(file) + + Like uperm but gets the permissions of the group owning the file + ``` + """ Base.gperm + + @doc doc""" + ```rst + operm(file) + + Like uperm but gets the permissions for people who neither own the + file nor are a member of the group owning the file + ``` + """ Base.operm + + @doc doc""" + ```rst + cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + + Copy the file, link, or directory from *src* to *dest*. + "remove_destination=true" will first remove an existing *dst*. + + If *follow_symlinks=false*, and src is a symbolic link, dst will be + created as a symbolic link. If *follow_symlinks=true* and src is a + symbolic link, dst will be a copy of the file or directory *src* + refers to. + ``` + """ Base.cp + + @doc doc""" + ```rst + download(url[, localfile]) + + Download a file from the given url, optionally renaming it to the + given local file name. Note that this function relies on the + availability of external tools such as "curl", "wget" or + "fetch" to download the file and is provided for convenience. For + production use or situations in which more options are need, please + use a package that provides the desired functionality instead. + ``` + """ Base.download + + @doc doc""" + ```rst + mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + + Move the file, link, or directory from *src* to *dest*. + "remove_destination=true" will first remove an existing *dst*. + ``` + """ Base.mv + + @doc doc""" + ```rst + rm(path::AbstractString; recursive=false) + + Delete the file, link, or empty directory at the given path. If + "recursive=true" is passed and the path is a directory, then all + contents are removed recursively. + ``` + """ Base.rm + + @doc doc""" + ```rst + touch(path::AbstractString) + + Update the last-modified timestamp on a file to the current time. + ``` + """ Base.touch + + @doc doc""" + ```rst + tempname() + + Generate a unique temporary file path. + ``` + """ Base.tempname + + @doc doc""" + ```rst + tempdir() + + Obtain the path of a temporary directory (possibly shared with + other processes). + ``` + """ Base.tempdir + + @doc doc""" + ```rst + mktemp([parent=tempdir()]) + + Returns "(path, io)", where "path" is the path of a new + temporary file in "parent" and "io" is an open file object for + this path. + ``` + """ Base.mktemp + + @doc doc""" + ```rst + mktempdir([parent=tempdir()]) + + Create a temporary directory in the "parent" directory and return + its path. + ``` + """ Base.mktempdir + + @doc doc""" + ```rst + isblockdev(path) -> Bool + + Returns "true" if "path" is a block device, "false" + otherwise. + ``` + """ Base.isblockdev + + @doc doc""" + ```rst + ischardev(path) -> Bool + + Returns "true" if "path" is a character device, "false" + otherwise. + ``` + """ Base.ischardev + + @doc doc""" + ```rst + isdir(path) -> Bool + + Returns "true" if "path" is a directory, "false" otherwise. + ``` + """ Base.isdir + + @doc doc""" + ```rst + isexecutable(path) -> Bool + + Returns "true" if the current user has permission to execute + "path", "false" otherwise. + ``` + """ Base.isexecutable + + @doc doc""" + ```rst + isfifo(path) -> Bool + + Returns "true" if "path" is a FIFO, "false" otherwise. + ``` + """ Base.isfifo + + @doc doc""" + ```rst + isfile(path) -> Bool + + Returns "true" if "path" is a regular file, "false" + otherwise. + ``` + """ Base.isfile + + @doc doc""" + ```rst + islink(path) -> Bool + + Returns "true" if "path" is a symbolic link, "false" + otherwise. + ``` + """ Base.islink + + @doc doc""" + ```rst + ismount(path) -> Bool + + Returns "true" if "path" is a mount point, "false" otherwise. + ``` + """ Base.ismount + + @doc doc""" + ```rst + ispath(path) -> Bool + + Returns "true" if "path" is a valid filesystem path, "false" + otherwise. + ``` + """ Base.ispath + + @doc doc""" + ```rst + isreadable(path) -> Bool + + Returns "true" if the current user has permission to read + "path", "false" otherwise. + ``` + """ Base.isreadable + + @doc doc""" + ```rst + issetgid(path) -> Bool + + Returns "true" if "path" has the setgid flag set, "false" + otherwise. + ``` + """ Base.issetgid + + @doc doc""" + ```rst + issetuid(path) -> Bool + + Returns "true" if "path" has the setuid flag set, "false" + otherwise. + ``` + """ Base.issetuid + + @doc doc""" + ```rst + issocket(path) -> Bool + + Returns "true" if "path" is a socket, "false" otherwise. + ``` + """ Base.issocket + + @doc doc""" + ```rst + issticky(path) -> Bool + + Returns "true" if "path" has the sticky bit set, "false" + otherwise. + ``` + """ Base.issticky + + @doc doc""" + ```rst + iswritable(path) -> Bool + + Returns "true" if the current user has permission to write to + "path", "false" otherwise. + ``` + """ Base.iswritable + + @doc doc""" + ```rst + homedir() -> AbstractString + + Return the current user's home directory. + ``` + """ Base.homedir + + @doc doc""" + ```rst + dirname(path::AbstractString) -> AbstractString + + Get the directory part of a path. + ``` + """ Base.dirname + + @doc doc""" + ```rst + basename(path::AbstractString) -> AbstractString + + Get the file name part of a path. + ``` + """ Base.basename + + @doc doc""" + ```rst + @__FILE__() -> AbstractString + + "@__FILE__" expands to a string with the absolute path and file + name of the script being run. Returns "nothing" if run from a + REPL or an empty string if evaluated by "julia -e ". + ``` + """ Base.@__FILE__ + + @doc doc""" + ```rst + isabspath(path::AbstractString) -> Bool + + Determines whether a path is absolute (begins at the root + directory). + ``` + """ Base.isabspath + + @doc doc""" + ```rst + isdirpath(path::AbstractString) -> Bool + + Determines whether a path refers to a directory (for example, ends + with a path separator). + ``` + """ Base.isdirpath + + @doc doc""" + ```rst + joinpath(parts...) -> AbstractString + + Join path components into a full path. If some argument is an + absolute path, then prior components are dropped. + ``` + """ Base.joinpath + + @doc doc""" + ```rst + abspath(path::AbstractString) -> AbstractString + + Convert a path to an absolute path by adding the current directory + if necessary. + ``` + """ Base.abspath + + @doc doc""" + ```rst + normpath(path::AbstractString) -> AbstractString + + Normalize a path, removing "." and ".." entries. + ``` + """ Base.normpath + + @doc doc""" + ```rst + realpath(path::AbstractString) -> AbstractString + + Canonicalize a path by expanding symbolic links and removing "." + and ".." entries. + ``` + """ Base.realpath + + @doc doc""" + ```rst + relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString + + Return a relative filepath to path either from the current + directory or from an optional start directory. This is a path + computation: the filesystem is not accessed to confirm the + existence or nature of path or startpath. + ``` + """ Base.relpath + + @doc doc""" + ```rst + expanduser(path::AbstractString) -> AbstractString + + On Unix systems, replace a tilde character at the start of a path + with the current user's home directory. + ``` + """ Base.expanduser + + @doc doc""" + ```rst + splitdir(path::AbstractString) -> (AbstractString, AbstractString) + + Split a path into a tuple of the directory name and file name. + ``` + """ Base.splitdir + + @doc doc""" + ```rst + splitdrive(path::AbstractString) -> (AbstractString, AbstractString) + + On Windows, split a path into the drive letter part and the path + part. On Unix systems, the first component is always the empty + string. + ``` + """ Base.splitdrive + + @doc doc""" + ```rst + splitext(path::AbstractString) -> (AbstractString, AbstractString) + + If the last component of a path contains a dot, split the path into + everything before the dot and everything including and after the + dot. Otherwise, return a tuple of the argument unmodified and the + empty string. + ``` + """ Base.splitext + + @doc doc""" + ```rst + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + ``` + """ Base.open + + @doc doc""" + ```rst + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of "mode" + correspond to those from "fopen(3)" or Perl "open", and are + equivalent to setting the following boolean groups: + + +------+-----------------------------------+ + | r | read | + +------+-----------------------------------+ + | r+ | read, write | + +------+-----------------------------------+ + | w | write, create, truncate | + +------+-----------------------------------+ + | w+ | read, write, create, truncate | + +------+-----------------------------------+ + | a | write, create, append | + +------+-----------------------------------+ + | a+ | read, write, create, append | + +------+-----------------------------------+ + ``` + """ Base.open + + @doc doc""" + ```rst + open(f::function, args...) + + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. + + **Example**: "open(readall, "file.txt")" + ``` + """ Base.open + + @doc doc""" + ```rst + IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + ``` + """ Base.IOBuffer + + @doc doc""" + ```rst + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + ``` + """ Base.IOBuffer + + @doc doc""" + ```rst + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + ``` + """ Base.IOBuffer + + @doc doc""" + ```rst + IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. + ``` + """ Base.IOBuffer + + @doc doc""" + ```rst + takebuf_array(b::IOBuffer) + + Obtain the contents of an "IOBuffer" as an array, without + copying. Afterwards, the IOBuffer is reset to its initial state. + ``` + """ Base.takebuf_array + + @doc doc""" + ```rst + takebuf_string(b::IOBuffer) + + Obtain the contents of an "IOBuffer" as a string, without + copying. Afterwards, the IOBuffer is reset to its initial state. + ``` + """ Base.takebuf_string + + @doc doc""" + ```rst + fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + + Create an "IOStream" object from an integer file descriptor. If + "own" is true, closing this object will close the underlying + descriptor. By default, an "IOStream" is closed when it is + garbage collected. "name" allows you to associate the descriptor + with a named file. + ``` + """ Base.fdio + + @doc doc""" + ```rst + flush(stream) + + Commit all currently buffered writes to the given stream. + ``` + """ Base.flush + + @doc doc""" + ```rst + close(stream) + + Close an I/O stream. Performs a "flush" first. + ``` + """ Base.close + + @doc doc""" + ```rst + write(stream, x) + + Write the canonical binary representation of a value to the given + stream. + ``` + """ Base.write + + @doc doc""" + ```rst + read(stream, type) + + Read a value of the given type from a stream, in canonical binary + representation. + ``` + """ Base.read + + @doc doc""" + ```rst + read(stream, type, dims) + + Read a series of values of the given type from a stream, in + canonical binary representation. "dims" is either a tuple or a + series of integer arguments specifying the size of "Array" to + return. + ``` + """ Base.read + + @doc doc""" + ```rst + read!(stream, array::Array) + + Read binary data from a stream, filling in the argument "array". + ``` + """ Base.read! + + @doc doc""" + ```rst + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + + Read at most "nb" bytes from the stream into "b", returning the + number of bytes read (increasing the size of "b" as needed). + ``` + """ Base.readbytes! + + @doc doc""" + ```rst + readbytes(stream, nb=typemax(Int)) + + Read at most "nb" bytes from the stream, returning a + "Vector{UInt8}" of the bytes read. + ``` + """ Base.readbytes + + @doc doc""" + ```rst + position(s) + + Get the current position of a stream. + ``` + """ Base.position + + @doc doc""" + ```rst + seek(s, pos) + + Seek a stream to the given position. + ``` + """ Base.seek + + @doc doc""" + ```rst + seekstart(s) + + Seek a stream to its beginning. + ``` + """ Base.seekstart + + @doc doc""" + ```rst + seekend(s) + + Seek a stream to its end. + ``` + """ Base.seekend + + @doc doc""" + ```rst + skip(s, offset) + + Seek a stream relative to the current position. + ``` + """ Base.skip + + @doc doc""" + ```rst + mark(s) + + Add a mark at the current position of stream "s". Returns the + marked position. + + See also "unmark()", "reset()", "ismarked()" + ``` + """ Base.mark + + @doc doc""" + ```rst + unmark(s) + + Remove a mark from stream "s". Returns "true" if the stream was + marked, "false" otherwise. + + See also "mark()", "reset()", "ismarked()" + ``` + """ Base.unmark + + @doc doc""" + ```rst + reset(s) + + Reset a stream "s" to a previously marked position, and remove + the mark. Returns the previously marked position. Throws an error + if the stream is not marked. + + See also "mark()", "unmark()", "ismarked()" + ``` + """ Base.reset + + @doc doc""" + ```rst + ismarked(s) + + Returns true if stream "s" is marked. + + See also "mark()", "unmark()", "reset()" + ``` + """ Base.ismarked + + @doc doc""" + ```rst + eof(stream) -> Bool + + Tests whether an I/O stream is at end-of-file. If the stream is not + yet exhausted, this function will block to wait for more data if + necessary, and then return "false". Therefore it is always safe + to read one byte after seeing "eof" return "false". "eof" + will return "false" as long as buffered data is still available, + even if the remote end of a connection is closed. + ``` + """ Base.eof + + @doc doc""" + ```rst + isreadonly(stream) -> Bool + + Determine whether a stream is read-only. + ``` + """ Base.isreadonly + + @doc doc""" + ```rst + isopen(stream) -> Bool + + Determine whether a stream is open (i.e. has not been closed yet). + If the connection has been closed remotely (in case of e.g. a + socket), "isopen" will return "false" even though buffered data + may still be available. Use "eof" to check if necessary. + ``` + """ Base.isopen + + @doc doc""" + ```rst + serialize(stream, value) + + Write an arbitrary value to a stream in an opaque format, such that + it can be read back by "deserialize". The read-back value will be + as identical as possible to the original. In general, this process + will not work if the reading and writing are done by different + versions of Julia, or an instance of Julia with a different system + image. + ``` + """ Base.serialize + + @doc doc""" + ```rst + deserialize(stream) + + Read a value written by "serialize". + ``` + """ Base.deserialize + + @doc doc""" + ```rst + print_escaped(io, str::AbstractString, esc::AbstractString) + + General escaping of traditional C and Unicode escape sequences, + plus any characters in esc are also escaped (with a backslash). + ``` + """ Base.print_escaped + + @doc doc""" + ```rst + print_unescaped(io, s::AbstractString) + + General unescaping of traditional C and Unicode escape sequences. + Reverse of "print_escaped()". + ``` + """ Base.print_unescaped + + @doc doc""" + ```rst + print_joined(io, items, delim[, last]) + + Print elements of "items" to "io" with "delim" between them. + If "last" is specified, it is used as the final delimiter instead + of "delim". + ``` + """ Base.print_joined + + @doc doc""" + ```rst + print_shortest(io, x) + + Print the shortest possible representation, with the minimum number + of consecutive non-zero digits, of number "x", ensuring that it + would parse to the exact same number. + ``` + """ Base.print_shortest + + @doc doc""" + ```rst + fd(stream) + + Returns the file descriptor backing the stream or file. Note that + this function only applies to synchronous *File*'s and *IOStream*'s + not to any of the asynchronous streams. + ``` + """ Base.fd + + @doc doc""" + ```rst + redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be + redirected. Returns a tuple (rd,wr) representing the pipe ends. + Data written to STDOUT may now be read from the rd end of the pipe. + The wr end is given for convenience in case the old STDOUT object + was cached by the user and needs to be replaced elsewhere. + ``` + """ Base.redirect_stdout + + @doc doc""" + ```rst + redirect_stdout(stream) + + Replace STDOUT by stream for all C and julia level output to + STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + ``` + """ Base.redirect_stdout + + @doc doc""" + ```rst + redirect_stderr([stream]) + + Like redirect_stdout, but for STDERR + ``` + """ Base.redirect_stderr + + @doc doc""" + ```rst + redirect_stdin([stream]) + + Like redirect_stdout, but for STDIN. Note that the order of the + return tuple is still (rd,wr), i.e. data to be read from STDIN, may + be written to wr. + ``` + """ Base.redirect_stdin + + @doc doc""" + ```rst + readchomp(x) + + Read the entirety of x as a string but remove trailing newlines. + Equivalent to chomp(readall(x)). + ``` + """ Base.readchomp + + @doc doc""" + ```rst + truncate(file, n) + + Resize the file or buffer given by the first argument to exactly + *n* bytes, filling previously unallocated space with '\0' if the + file or buffer is grown + ``` + """ Base.truncate + + @doc doc""" + ```rst + skipchars(stream, predicate; linecomment::Char) + + Advance the stream until before the first character for which + "predicate" returns false. For example "skipchars(stream, + isspace)" will skip all whitespace. If keyword argument + "linecomment" is specified, characters from that character + through the end of a line will also be skipped. + ``` + """ Base.skipchars + + @doc doc""" + ```rst + countlines(io[, eol::Char]) + + Read io until the end of the stream/file and count the number of + non-empty lines. To specify a file pass the filename as the first + argument. EOL markers other than '\n' are supported by passing + them as the second argument. + ``` + """ Base.countlines + + @doc doc""" + ```rst + PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. + Seeking and truncating are not supported. See IOBuffer for the + available constructors. + ``` + """ Base.PipeBuffer + + @doc doc""" + ```rst + PipeBuffer(data::Vector{UInt8}[, maxsize]) + + Create a PipeBuffer to operate on a data vector, optionally + specifying a size beyond which the underlying Array may not be + grown. + ``` + """ Base.PipeBuffer + + @doc doc""" + ```rst + readavailable(stream) + + Read all available data on the stream, blocking the task only if no + data is available. The result is a "Vector{UInt8,1}". + ``` + """ Base.readavailable + + @doc doc""" + ```rst + show(x) + + Write an informative text representation of a value to the current + output stream. New types should overload "show(io, x)" where the + first argument is a stream. The representation used by "show" + generally includes Julia-specific formatting and type information. + ``` + """ Base.show + + @doc doc""" + ```rst + showcompact(x) + + Show a more compact representation of a value. This is used for + printing array elements. If a new type has a different compact + representation, it should overload "showcompact(io, x)" where the + first argument is a stream. + ``` + """ Base.showcompact + + @doc doc""" + ```rst + showall(x) + + Similar to "show", except shows all elements of arrays. + ``` + """ Base.showall + + @doc doc""" + ```rst + summary(x) + + Return a string giving a brief description of a value. By default + returns "string(typeof(x))". For arrays, returns strings like + "2x2 Float64 Array". + ``` + """ Base.summary + + @doc doc""" + ```rst + print(x) + + Write (to the default output stream) a canonical (un-decorated) + text representation of a value if there is one, otherwise call + "show". The representation used by "print" includes minimal + formatting and tries to avoid Julia-specific details. + ``` + """ Base.print + + @doc doc""" + ```rst + println(x) + + Print (using "print()") "x" followed by a newline. + ``` + """ Base.println + + @doc doc""" + ```rst + print_with_color(color::Symbol[, io], strings...) + + Print strings in a color specified as a symbol, for example + ":red" or ":blue". + ``` + """ Base.print_with_color + + @doc doc""" + ```rst + info(msg) + + Display an informational message. + ``` + """ Base.info + + @doc doc""" + ```rst + warn(msg) + + Display a warning. + ``` + """ Base.warn + + @doc doc""" + ```rst + @printf([io::IOStream], "%Fmt", args...) + + Print arg(s) using C "printf()" style format specification + string. Optionally, an IOStream may be passed as the first argument + to redirect output. + ``` + """ Base.@printf + + @doc doc""" + ```rst + @sprintf("%Fmt", args...) + + Return "@printf" formatted output as string. + ``` + """ Base.@sprintf + + @doc doc""" + ```rst + sprint(f::Function, args...) + + Call the given function with an I/O stream and the supplied extra + arguments. Everything written to this I/O stream is returned as a + string. + ``` + """ Base.sprint + + @doc doc""" + ```rst + showerror(io, e) + + Show a descriptive representation of an exception object. + ``` + """ Base.showerror + + @doc doc""" + ```rst + dump(x) + + Show all user-visible structure of a value. + ``` + """ Base.dump + + @doc doc""" + ```rst + xdump(x) + + Show all structure of a value, including all fields of objects. + ``` + """ Base.xdump + + @doc doc""" + ```rst + readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + ``` + """ Base.readall + + @doc doc""" + ```rst + readall(filename::AbstractString) + + Open "filename", read the entire contents as a string, then close + the file. Equivalent to "open(readall, filename)". + ``` + """ Base.readall + + @doc doc""" + ```rst + readline(stream=STDIN) + + Read a single line of text, including a trailing newline character + (if one is reached before the end of the input), from the given + "stream" (defaults to "STDIN"), + ``` + """ Base.readline + + @doc doc""" + ```rst + readuntil(stream, delim) + + Read a string, up to and including the given delimiter byte. + ``` + """ Base.readuntil + + @doc doc""" + ```rst + readlines(stream) + + Read all lines as an array. + ``` + """ Base.readlines + + @doc doc""" + ```rst + eachline(stream) + + Create an iterable object that will yield each line from a stream. + ``` + """ Base.eachline + + @doc doc""" + ```rst + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + "eol") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, + with any non-numeric elements as "NaN" for floating-point types, + or zero. Other useful values of "T" include "ASCIIString", + "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as + header and the tuple "(data_cells, header_cells)" is returned + instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of + initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be + ignored. + + If "use_mmap" is "true", the file specified by "source" is + memory mapped for potential speedups. Default is "true" except on + Windows. On Windows, you may want to specify "true" if the file + is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" + and text following "comment_char" in any line are ignored. + ``` + """ Base.readdlm + + @doc doc""" + ```rst + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + ``` + """ Base.readdlm + + @doc doc""" + ```rst + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + ``` + """ Base.readdlm + + @doc doc""" + ```rst + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + ``` + """ Base.readdlm + + @doc doc""" + ```rst + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". + ``` + """ Base.readdlm + + @doc doc""" + ```rst + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + ``` + """ Base.readdlm + + @doc doc""" + ```rst + writedlm(f, A, delim='\t') + + Write "A" (a vector, matrix or an iterable collection of iterable + rows) as text to "f" (either a filename string or an "IO" + stream) using the given delimeter "delim" (which defaults to tab, + but can be any printable Julia object, typically a "Char" or + "AbstractString"). + + For example, two vectors "x" and "y" of the same length can be + written as two columns of tab-delimited text to "f" by either + "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". + ``` + """ Base.writedlm + + @doc doc""" + ```rst + readcsv(source, [T::Type]; options...) + + Equivalent to "readdlm" with "delim" set to comma. + ``` + """ Base.readcsv + + @doc doc""" + ```rst + writecsv(filename, A) + + Equivalent to "writedlm" with "delim" set to comma. + ``` + """ Base.writecsv + + @doc doc""" + ```rst + Base64EncodePipe(ostream) + + Returns a new write-only I/O stream, which converts any bytes + written to it into base64-encoded ASCII bytes written to + "ostream". Calling "close" on the "Base64Pipe" stream is + necessary to complete the encoding (but does not close + "ostream"). + ``` + """ Base.Base64EncodePipe + + @doc doc""" + ```rst + Base64DecodePipe(istream) + + Returns a new read-only I/O stream, which decodes base64-encoded + data read from "istream". + ``` + """ Base.Base64DecodePipe + + @doc doc""" + ```rst + base64encode(writefunc, args...) +base64encode(args...) + + Given a "write"-like function "writefunc", which takes an I/O + stream as its first argument, "base64(writefunc, args...)" calls + "writefunc" to write "args..." to a base64-encoded string, and + returns the string. "base64(args...)" is equivalent to + "base64(write, args...)": it converts its arguments into bytes + using the standard "write" functions and returns the + base64-encoded string. + ``` + """ Base.base64encode + + @doc doc""" + ```rst + base64decode(string) + + Decodes the base64-encoded "string" and returns a + "Vector{UInt8}" of the decoded bytes. + ``` + """ Base.base64decode + + @doc doc""" + ```rst + display(x) +display(d::Display, x) +display(mime, x) +display(d::Display, mime, x) + + Display "x" using the topmost applicable display in the display + stack, typically using the richest supported multimedia output for + "x", with plain-text "STDOUT" output as a fallback. The + "display(d, x)" variant attempts to display "x" on the given + display "d" only, throwing a "MethodError" if "d" cannot + display objects of this type. + + There are also two variants with a "mime" argument (a MIME type + string, such as ""image/png""), which attempt to display "x" + using the requested MIME type *only*, throwing a "MethodError" if + this type is not supported by either the display(s) or by "x". + With these variants, one can also supply the "raw" data in the + requested MIME type by passing "x::AbstractString" (for MIME + types with text-based storage, such as text/html or + application/postscript) or "x::Vector{UInt8}" (for binary MIME + types). + ``` + """ Base.display + + @doc doc""" + ```rst + redisplay(x) +redisplay(d::Display, x) +redisplay(mime, x) +redisplay(d::Display, mime, x) + + By default, the "redisplay" functions simply call "display". + However, some display backends may override "redisplay" to modify + an existing display of "x" (if any). Using "redisplay" is + also a hint to the backend that "x" may be redisplayed several + times, and the backend may choose to defer the display until (for + example) the next interactive prompt. + ``` + """ Base.redisplay + + @doc doc""" + ```rst + displayable(mime) -> Bool +displayable(d::Display, mime) -> Bool + + Returns a boolean value indicating whether the given "mime" type + (string) is displayable by any of the displays in the current + display stack, or specifically by the display "d" in the second + variant. + ``` + """ Base.displayable + + @doc doc""" + ```rst + writemime(stream, mime, x) + + The "display" functions ultimately call "writemime" in order to + write an object "x" as a given "mime" type to a given I/O + "stream" (usually a memory buffer), if possible. In order to + provide a rich multimedia representation of a user-defined type + "T", it is only necessary to define a new "writemime" method + for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", + where "mime" is a MIME-type string and the function body calls + "write" (or similar) to write that representation of "x" to + "stream". (Note that the "MIME\""" notation only supports + literal strings; to construct "MIME" types in a more flexible + manner use "MIME{symbol("")}".) + + For example, if you define a "MyImage" type and know how to write + it to a PNG file, you could define a function "writemime(stream, + ::MIME"image/png", x::MyImage) = ...`" to allow your images to + be displayed on any PNG-capable "Display" (such as IJulia). As + usual, be sure to "import Base.writemime" in order to add new + methods to the built-in Julia function "writemime". + + Technically, the "MIME"mime"" macro defines a singleton type + for the given "mime" string, which allows us to exploit Julia's + dispatch mechanisms in determining how to display objects of any + given type. + ``` + """ Base.writemime + + @doc doc""" + ```rst + mimewritable(mime, x) + + Returns a boolean value indicating whether or not the object "x" + can be written as the given "mime" type. (By default, this is + determined automatically by the existence of the corresponding + "writemime" function for "typeof(x)".) + ``` + """ Base.mimewritable + + @doc doc""" + ```rst + reprmime(mime, x) + + Returns an "AbstractString" or "Vector{UInt8}" containing the + representation of "x" in the requested "mime" type, as written + by "writemime" (throwing a "MethodError" if no appropriate + "writemime" is available). An "AbstractString" is returned for + MIME types with textual representations (such as ""text/html"" + or ""application/postscript""), whereas binary data is returned + as "Vector{UInt8}". (The function "istext(mime)" returns + whether or not Julia treats a given "mime" type as text.) + + As a special case, if "x" is an "AbstractString" (for textual + MIME types) or a "Vector{UInt8}" (for binary MIME types), the + "reprmime" function assumes that "x" is already in the + requested "mime" format and simply returns "x". + ``` + """ Base.reprmime + + @doc doc""" + ```rst + stringmime(mime, x) + + Returns an "AbstractString" containing the representation of + "x" in the requested "mime" type. This is similar to + "reprmime" except that binary data is base64-encoded as an ASCII + string. + ``` + """ Base.stringmime + + @doc doc""" + ```rst + pushdisplay(d::Display) + + Pushes a new display "d" on top of the global display-backend + stack. Calling "display(x)" or "display(mime, x)" will display + "x" on the topmost compatible backend in the stack (i.e., the + topmost backend that does not throw a "MethodError"). + ``` + """ Base.pushdisplay + + @doc doc""" + ```rst + popdisplay() +popdisplay(d::Display) + + Pop the topmost backend off of the display-backend stack, or the + topmost copy of "d" in the second variant. + ``` + """ Base.popdisplay + + @doc doc""" + ```rst + TextDisplay(stream) + + Returns a "TextDisplay <: Display", which can display any object + as the text/plain MIME type (only), writing the text representation + to the given I/O stream. (The text representation is the same as + the way an object is printed in the Julia REPL.) + ``` + """ Base.TextDisplay + + @doc doc""" + ```rst + istext(m::MIME) + + Determine whether a MIME type is text data. + ``` + """ Base.istext + + @doc doc""" + ```rst + mmap_array(type, dims, stream[, offset]) + + Create an "Array" whose values are linked to a file, using + memory-mapping. This provides a convenient way of working with data + too large to fit in the computer's memory. + + The type determines how the bytes of the array are interpreted. + Note that the file must be stored in binary format, and no format + conversions are possible (this is a limitation of operating + systems, not Julia). + + "dims" is a tuple specifying the size of the array. + + The file is passed via the stream argument. When you initialize + the stream, use ""r"" for a "read-only" array, and ""w+"" + to create a new array used to write values to disk. + + Optionally, you can specify an offset (in bytes) if, for example, + you want to skip over a header in the file. The default value for + the offset is the current stream position. + + For example, the following code: + + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) + + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) + + creates a "m"-by-"n" "Matrix{Int}", linked to the file + associated with stream "s". + + A more portable file would need to encode the word size---32 bit or + 64 bit---and endianness information in the header. In practice, + consider encoding binary data using standard formats like HDF5 + (which can be used with memory-mapping). + ``` + """ Base.mmap_array + + @doc doc""" + ```rst + mmap_bitarray([type], dims, stream[, offset]) + + Create a "BitArray" whose values are linked to a file, using + memory-mapping; it has the same purpose, works in the same way, and + has the same arguments, as "mmap_array()", but the byte + representation is different. The "type" parameter is optional, + and must be "Bool" if given. + + **Example**: "B = mmap_bitarray((25,30000), s)" + + This would create a 25-by-30000 "BitArray", linked to the file + associated with stream "s". + ``` + """ Base.mmap_bitarray + + @doc doc""" + ```rst + msync(array) + + Forces synchronization between the in-memory version of a memory- + mapped "Array" or "BitArray" and the on-disk version. + ``` + """ Base.msync + + @doc doc""" + ```rst + connect([host], port) -> TcpSocket + + Connect to the host "host" on port "port" + ``` + """ Base.connect + + @doc doc""" + ```rst + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at "path" + ``` + """ Base.connect + + @doc doc""" + ```rst + listen([addr], port) -> TcpServer + + Listen on port on the address specified by "addr". By default + this listens on localhost only. To listen on all interfaces pass, + "IPv4(0)" or "IPv6(0)" as appropriate. + ``` + """ Base.listen + + @doc doc""" + ```rst + listen(path) -> PipeServer + + Listens on/Creates a Named Pipe/Domain Socket + ``` + """ Base.listen + + @doc doc""" + ```rst + getaddrinfo(host) + + Gets the IP address of the "host" (may have to do a DNS lookup) + ``` + """ Base.getaddrinfo + + @doc doc""" + ```rst + parseip(addr) + + Parse a string specifying an IPv4 or IPv6 ip address. + ``` + """ Base.parseip + + @doc doc""" + ```rst + IPv4(host::Integer) -> IPv4 + + Returns IPv4 object from ip address formatted as Integer + ``` + """ Base.IPv4 + + @doc doc""" + ```rst + IPv6(host::Integer) -> IPv6 + + Returns IPv6 object from ip address formatted as Integer + ``` + """ Base.IPv6 + + @doc doc""" + ```rst + nb_available(stream) + + Returns the number of bytes available for reading before a read + from this stream or buffer will block. + ``` + """ Base.nb_available + + @doc doc""" + ```rst + accept(server[, client]) + + Accepts a connection on the given server and returns a connection + to the client. An uninitialized client stream may be provided, in + which case it will be used instead of creating a new stream. + ``` + """ Base.accept + + @doc doc""" + ```rst + listenany(port_hint) -> (UInt16, TcpServer) + + Create a TcpServer on any port, using hint as a starting point. + Returns a tuple of the actual port that the server was created on + and the server itself. + ``` + """ Base.listenany + + @doc doc""" + ```rst + watch_file(cb=false, s; poll=false) + + Watch file or directory "s" and run callback "cb" when "s" is + modified. The "poll" parameter specifies whether to use file + system event monitoring or polling. The callback function "cb" + should accept 3 arguments: "(filename, events, status)" where + "filename" is the name of file that was modified, "events" is + an object with boolean fields "changed" and "renamed" when + using file system event monitoring, or "readable" and + "writable" when using polling, and "status" is always 0. Pass + "false" for "cb" to not use a callback function. + ``` + """ Base.watch_file + + @doc doc""" + ```rst + poll_fd(fd, seconds::Real; readable=false, writable=false) + + Poll a file descriptor fd for changes in the read or write + availability and with a timeout given by the second argument. If + the timeout is not needed, use "wait(fd)" instead. The keyword + arguments determine which of read and/or write status should be + monitored and at least one of them needs to be set to true. The + returned value is an object with boolean fields "readable", + "writable", and "timedout", giving the result of the polling. + ``` + """ Base.poll_fd + + @doc doc""" + ```rst + poll_file(s, interval_seconds::Real, seconds::Real) + + Monitor a file for changes by polling every *interval_seconds* + seconds for *seconds* seconds. A return value of true indicates the + file changed, a return value of false indicates a timeout. + ``` + """ Base.poll_file + + @doc doc""" + ```rst + bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + + Bind "socket" to the given "host:port". Note that *0.0.0.0* + will listen on all devices. + ``` + """ Base.bind + + @doc doc""" + ```rst + send(socket::UDPSocket, host::IPv4, port::Integer, msg) + + Send "msg" over "socket to ``host:port". + ``` + """ Base.send + + @doc doc""" + ```rst + recv(socket::UDPSocket) + + Read a UDP packet from the specified socket, and return the bytes + received. This call blocks. + ``` + """ Base.recv + + @doc doc""" + ```rst + recvfrom(socket::UDPSocket) -> (address, data) + + Read a UDP packet from the specified socket, returning a tuple of + (address, data), where address will be either IPv4 or IPv6 as + appropriate. + ``` + """ Base.recvfrom + + @doc doc""" + ```rst + setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + + Set UDP socket options. "multicast_loop": loopback for multicast + packets (default: true). "multicast_ttl": TTL for multicast + packets. "enable_broadcast": flag must be set to true if socket + will be used for broadcast messages, or else the UDP system will + return an access error (default: false). "ttl": Time-to-live of + packets sent on the socket. + ``` + """ Base.setopt + + @doc doc""" + ```rst + ntoh(x) + + Converts the endianness of a value from Network byte order (big- + endian) to that used by the Host. + ``` + """ Base.ntoh + + @doc doc""" + ```rst + hton(x) + + Converts the endianness of a value from that used by the Host to + Network byte order (big-endian). + ``` + """ Base.hton + + @doc doc""" + ```rst + ltoh(x) + + Converts the endianness of a value from Little-endian to that used + by the Host. + ``` + """ Base.ltoh + + @doc doc""" + ```rst + htol(x) + + Converts the endianness of a value from that used by the Host to + Little-endian. + ``` + """ Base.htol + + @doc doc""" + ```rst + ENDIAN_BOM + + The 32-bit byte-order-mark indicates the native byte order of the + host machine. Little-endian machines will contain the value + 0x04030201. Big-endian machines will contain the value 0x01020304. + ``` + """ Base.ENDIAN_BOM + + @doc doc""" + ```rst + malloc(size::Integer) -> Ptr{Void} + + Call "malloc" from the C standard library. + ``` + """ Libc.malloc + + @doc doc""" + ```rst + calloc(num::Integer, size::Integer) -> Ptr{Void} + + Call "calloc" from the C standard library. + ``` + """ Libc.calloc + + @doc doc""" + ```rst + realloc(addr::Ptr, size::Integer) -> Ptr{Void} + + Call "realloc" from the C standard library. + + See warning in the documentation for "free" regarding only using + this on memory originally obtained from "malloc". + ``` + """ Libc.realloc + + @doc doc""" + ```rst + free(addr::Ptr) + + Call "free" from the C standard library. Only use this on memory + obtained from "malloc", not on pointers retrieved from other C + libraries. "Ptr" objects obtained from C libraries should be + freed by the free functions defined in that library, to avoid + assertion failures if multiple "libc" libraries exist on the + system. + ``` + """ Libc.free + + @doc doc""" + ```rst + errno([code]) + + Get the value of the C library's "errno". If an argument is + specified, it is used to set the value of "errno". + + The value of "errno" is only valid immediately after a "ccall" + to a C library routine that sets it. Specifically, you cannot call + "errno" at the next prompt in a REPL, because lots of code is + executed between prompts. + ``` + """ Libc.errno + + @doc doc""" + ```rst + strerror(n) + + Convert a system call error code to a descriptive string + ``` + """ Libc.strerror + + @doc doc""" + ```rst + time(t::TmStruct) + + Converts a "TmStruct" struct to a number of seconds since the + epoch. + ``` + """ Libc.time + + @doc doc""" + ```rst + strftime([format], time) + + Convert time, given as a number of seconds since the epoch or a + "TmStruct", to a formatted string using the given format. + Supported formats are the same as those in the standard C library. + ``` + """ Libc.strftime + + @doc doc""" + ```rst + strptime([format], timestr) + + Parse a formatted time string into a "TmStruct" giving the + seconds, minute, hour, date, etc. Supported formats are the same as + those in the standard C library. On some platforms, timezones will + not be parsed correctly. If the result of this function will be + passed to "time" to convert it to seconds since the epoch, the + "isdst" field should be filled in manually. Setting it to "-1" + will tell the C library to use the current system settings to + determine the timezone. + ``` + """ Libc.strptime + + @doc doc""" + ```rst + TmStruct([seconds]) + + Convert a number of seconds since the epoch to broken-down format, + with fields "sec", "min", "hour", "mday", "month", + "year", "wday", "yday", and "isdst". + ``` + """ Libc.TmStruct + + @doc doc""" + ```rst + flush_cstdio() + + Flushes the C "stdout" and "stderr" streams (which may have + been written to by external C code). + ``` + """ Libc.flush_cstdio + + @doc doc""" + ```rst + msync(ptr, len[, flags]) + + Forces synchronization of the "mmap()"ped memory region from + "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a + combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See + your platform man page for specifics. The flags argument is not + valid on Windows. + + You may not need to call "msync", because synchronization is + performed at intervals automatically by the operating system. + However, you can call this directly if, for example, you are + concerned about losing the result of a long-running calculation. + ``` + """ Libc.msync + + @doc doc""" + ```rst + MS_ASYNC + + Enum constant for "msync()". See your platform man page for + details. (not available on Windows). + ``` + """ Libc.MS_ASYNC + + @doc doc""" + ```rst + MS_SYNC + + Enum constant for "msync()". See your platform man page for + details. (not available on Windows). + ``` + """ Libc.MS_SYNC + + @doc doc""" + ```rst + MS_INVALIDATE + + Enum constant for "msync()". See your platform man page for + details. (not available on Windows). + ``` + """ Libc.MS_INVALIDATE + + @doc doc""" + ```rst + mmap(len, prot, flags, fd, offset) + + Low-level interface to the "mmap" system call. See the man page. + ``` + """ Libc.mmap + + @doc doc""" + ```rst + munmap(pointer, len) + + Low-level interface for unmapping memory (see the man page). With + "mmap_array()" you do not need to call this directly; the memory + is unmapped for you when the array goes out of scope. + ``` + """ Libc.munmap + + @doc doc""" + ```rst + dlopen(libfile::AbstractString[, flags::Integer]) + + Load a shared library, returning an opaque handle. + + The optional flags argument is a bitwise-or of zero or more of + "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", + "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and + "RTLD_FIRST". These are converted to the corresponding flags of + the POSIX (and/or GNU libc and/or MacOS) dlopen command, if + possible, or are ignored if the specified functionality is not + available on the current platform. The default is + "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of + these flags, on POSIX platforms, is to specify + "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's + symbols to be available for usage in other shared libraries, in + situations where there are dependencies between shared libraries. + ``` + """ Libdl.dlopen + + @doc doc""" + ```rst + dlopen_e(libfile::AbstractString[, flags::Integer]) + + Similar to "dlopen()", except returns a "NULL" pointer instead + of raising errors. + ``` + """ Libdl.dlopen_e + + @doc doc""" + ```rst + RTLD_DEEPBIND + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_DEEPBIND + + @doc doc""" + ```rst + RTLD_FIRST + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_FIRST + + @doc doc""" + ```rst + RTLD_GLOBAL + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_GLOBAL + + @doc doc""" + ```rst + RTLD_LAZY + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_LAZY + + @doc doc""" + ```rst + RTLD_LOCAL + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_LOCAL + + @doc doc""" + ```rst + RTLD_NODELETE + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_NODELETE + + @doc doc""" + ```rst + RTLD_NOLOAD + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_NOLOAD + + @doc doc""" + ```rst + RTLD_NOW + + Enum constant for "dlopen()". See your platform man page for + details, if applicable. + ``` + """ Libdl.RTLD_NOW + + @doc doc""" + ```rst + dlsym(handle, sym) + + Look up a symbol from a shared library handle, return callable + function pointer on success. + ``` + """ Libdl.dlsym + + @doc doc""" + ```rst + dlsym_e(handle, sym) + + Look up a symbol from a shared library handle, silently return NULL + pointer on lookup failure. + ``` + """ Libdl.dlsym_e + + @doc doc""" + ```rst + dlclose(handle) + + Close shared library referenced by handle. + ``` + """ Libdl.dlclose + + @doc doc""" + ```rst + find_library(names, locations) + + Searches for the first library in "names" in the paths in the + "locations" list, "DL_LOAD_PATH", or system library paths (in + that order) which can successfully be dlopen'd. On success, the + return value will be one of the names (potentially prefixed by one + of the paths in locations). This string can be assigned to a + "global const" and used as the library name in future + "ccall"'s. On failure, it returns the empty string. + ``` + """ Libdl.find_library + + @doc doc""" + ```rst + DL_LOAD_PATH + + When calling "dlopen", the paths in this list will be searched + first, in order, before searching the system locations for a valid + library handle. + ``` + """ Libdl.DL_LOAD_PATH + + @doc doc""" + ```rst + *(A, B) + + Matrix multiplication + ``` + """ Base.(:(*)) + + @doc doc""" + ```rst + \(A, B) + + Matrix division using a polyalgorithm. For input matrices "A" and + "B", the result "X" is such that "A*X == B" when "A" is + square. The solver that is used depends upon the structure of + "A". A direct solver is used for upper- or lower triangular + "A". For Hermitian "A" (equivalent to symmetric "A" for non- + complex "A") the "BunchKaufman" factorization is used. + Otherwise an LU factorization is used. For rectangular "A" the + result is the minimum-norm least squares solution computed by a + pivoted QR factorization of "A" and a rank estimate of A based on + the R factor. + + When "A" is sparse, a similar polyalgorithm is used. For + indefinite matrices, the LDLt factorization does not use pivoting + during the numerical factorization and therefore the procedure can + fail even for invertible matrices. + ``` + """ Base.(:(\)) + + @doc doc""" + ```rst + dot(x, y) +⋅(x, y) + + Compute the dot product. For complex vectors, the first vector is + conjugated. + ``` + """ Base.dot + + @doc doc""" + ```rst + vecdot(x, y) + + For any iterable containers "x" and "y" (including arrays of + any dimension) of numbers (or any element type for which "dot" is + defined), compute the Euclidean dot product (the sum of + "dot(x[i],y[i])") as if they were vectors. + ``` + """ Base.vecdot + + @doc doc""" + ```rst + cross(x, y) +×(x, y) + + Compute the cross product of two 3-vectors. + ``` + """ Base.cross + + @doc doc""" + ```rst + factorize(A) + + Compute a convenient factorization (including LU, Cholesky, Bunch- + Kaufman, LowerTriangular, UpperTriangular) of A, based upon the + type of the input matrix. The return value can then be reused for + efficient solving of multiple systems. For example: + "A=factorize(A); x=A\\b; y=A\\C". + ``` + """ Base.factorize + + @doc doc""" + ```rst + full(F) + + Reconstruct the matrix "A" from the factorization + "F=factorize(A)". + ``` + """ Base.full + + @doc doc""" + ```rst + lu(A) -> L, U, p + + Compute the LU factorization of "A", such that "A[p,:] = L*U". + ``` + """ Base.lu + + @doc doc""" + ```rst + lufact(A[, pivot=Val{true}]) -> F + + Compute the LU factorization of "A". The return type of "F" + depends on the type of "A". In most cases, if "A" is a subtype + "S" of AbstractMatrix with an element type "T`" supporting + "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If + pivoting is chosen (default) the element type should also support + "abs" and "<". When "A" is sparse and have element of type + "Float32", "Float64", "Complex{Float32}", or + "Complex{Float64}" the return type is "UmfpackLU". Some + examples are shown in the table below. + + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | + +-------------------------+---------------------------+----------------------------------------------+ + + The individual components of the factorization "F" can be + accessed by indexing: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +--------------------+--------+--------------------------+---------------+ + | \"/\" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | \"\\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"cond\" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"det\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"size\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + ``` + """ Base.lufact + + @doc doc""" + ```rst + lufact!(A) -> LU + + "lufact!" is the same as "lufact()", but saves space by + overwriting the input A, instead of creating a copy. For sparse + "A" the "nzval" field is not overwritten but the index fields, + "colptr" and "rowval" are decremented in place, converting from + 1-based indices to 0-based indices. + ``` + """ Base.lufact! + + @doc doc""" + ```rst + chol(A[, LU]) -> F + + Compute the Cholesky factorization of a symmetric positive definite + matrix "A" and return the matrix "F". If "LU" is "Val{:U}" + (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If + "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" + and "A = F*F'". "LU" defaults to "Val{:U}". + ``` + """ Base.chol + + @doc doc""" + ```rst + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive + (semi)definite matrix "A" and return either a "Cholesky" if + "pivot==Val{false}" or "CholeskyPivoted" if + "pivot==Val{true}". "LU" may be ":L" for using the lower part + or ":U" for the upper part. The default is to use ":U". The + triangular matrix can be obtained from the factorization "F" + with: "F[:L]" and "F[:U]". The following functions are + available for "Cholesky" objects: "size", "\", "inv", + "det". For "CholeskyPivoted" there is also defined a "rank". + If "pivot==Val{false}" a "PosDefException" exception is thrown + in case the matrix is not positive definite. The argument "tol" + determines the tolerance for determining the rank. For negative + values, the tolerance is the machine precision. + ``` + """ Base.cholfact + + @doc doc""" + ```rst + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite + matrix "A". A fill-reducing permutation is used. "F = + cholfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors + from "F", using "F[:L]". However, since pivoting is on by + default, the factorization is internally represented as "A == + P'*L*L'*P" with a permutation matrix "P"; using just "L" + without accounting for "P" will give incorrect answers. To + include the effects of permutation, it's typically preferable to + extact "combined" factors like "PtL = F[:PtL]" (the equivalent + of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. + ``` + """ Base.cholfact + + @doc doc""" + ```rst + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + "cholfact!" is the same as "cholfact()", but saves space by + overwriting the input "A", instead of creating a copy. + "cholfact!" can also reuse the symbolic factorization from a + different matrix "F" with the same structure when used as: + "cholfact!(F::CholmodFactor, A)". + ``` + """ Base.cholfact! + + @doc doc""" + ```rst + ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix "A" such + that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular + matrix and "d" is a vector with non-negative elements. + ``` + """ Base.ldltfact + + @doc doc""" + ```rst + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix "A". A fill-reducing permutation is used. "F = + ldltfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors from + "F", using "F[:L]". However, since pivoting is on by default, + the factorization is internally represented as "A == P'*L*D*L'*P" + with a permutation matrix "P"; using just "L" without + accounting for "P" will give incorrect answers. To include the + effects of permutation, it's typically preferable to extact + "combined" factors like "PtL = F[:PtL]" (the equivalent of + "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The + complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, + :DU, :PtLD, :DUP". + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. + ``` + """ Base.ldltfact + + @doc doc""" + ```rst + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + + Compute the (pivoted) QR factorization of "A" such that either + "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default + is to compute a thin factorization. Note that "R" is not extended + with zeros when the full "Q" is requested. + ``` + """ Base.qr + + @doc doc""" + ```rst + qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of "A". The return type of "F" + depends on the element type of "A" and whether pivoting is + specified (with "pivot==Val{true}"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + + "BlasFloat" refers to any of: "Float32", "Float64", + "Complex64" or "Complex128". + + The individual components of the factorization "F" can be + accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:p]\" | pivot \"Vector\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the "QR" objects: + "size", "\". When "A" is rectangular, "\" will return a + least squares solution and if the solution is not unique, the one + with smallest norm is returned. + + Multiplication with respect to either thin or full "Q" is + allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A + "Q" matrix can be converted into a regular matrix with "full()" + which has a named argument "thin". + + Note: "qrfact" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the "Q" and "R" matrices can be stored compactly rather + as two separate dense matrices.The data contained in "QR" or + "QRPivoted" can be used to construct the "QRPackedQ" type, + which is a compact representation of the rotation matrix: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where \tau_i is the scale factor and v_i is the projection + vector associated with the i^{th} Householder elementary + reflector.The data contained in "QRCompactWY" can be used to + construct the "QRCompactWYQ" type, which is a compact + representation of the rotation matrix + + Q = I + Y T Y^T + + where "Y" is m \times r lower trapezoidal and "T" is r + \times r upper triangular. The *compact WY* representation + [Schreiber1989] is not to be confused with the older, *WY* + representation [Bischof1987]. (The LAPACK documentation uses + "V" in lieu of "Y".) + + [Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 + ``` + """ Base.qrfact + + @doc doc""" + ```rst + qrfact(A) -> SPQR.Factorization + + Compute the QR factorization of a sparse matrix "A". A fill- + reducing permutation is used. The main application of this type is + to solve least squares problems with "\". The function calls the + C library SPQR and a few additional functions from the library are + wrapped but not exported. + ``` + """ Base.qrfact + + @doc doc""" + ```rst + qrfact!(A[, pivot=Val{false}]) + + "qrfact!" is the same as "qrfact()" when A is a subtype of + "StridedMatrix", but saves space by overwriting the input "A", + instead of creating a copy. + ``` + """ Base.qrfact! + + @doc doc""" + ```rst + full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a + "QRCompactWYQ" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. + + Optionally takes a "thin" Boolean argument, which if "true" + omits the columns that span the rows of "R" in the QR + factorization that are zero. The resulting matrix is the "Q" in a + thin QR factorization (sometimes called the reduced QR + factorization). If "false", returns a "Q" that spans all rows + of "R" in its corresponding QR factorization. + ``` + """ Base.full + + @doc doc""" + ```rst + bkfact(A) -> BunchKaufman + + Compute the Bunch-Kaufman [Bunch1977] factorization of a real + symmetric or complex Hermitian matrix "A" and return a + "BunchKaufman" object. The following functions are available for + "BunchKaufman" objects: "size", "\", "inv", "issym", + "ishermitian". + ``` + """ Base.bkfact + + @doc doc""" + ```rst + bkfact!(A) -> BunchKaufman + + "bkfact!" is the same as "bkfact()", but saves space by + overwriting the input "A", instead of creating a copy. + ``` + """ Base.bkfact! + + @doc doc""" + ```rst + sqrtm(A) + + Compute the matrix square root of "A". If "B = sqrtm(A)", then + "B*B == A" within roundoff error. + + "sqrtm" uses a polyalgorithm, computing the matrix square root + using Schur factorizations ("schurfact()") unless it detects the + matrix to be Hermitian or real symmetric, in which case it computes + the matrix square root from an eigendecomposition ("eigfact()"). + In the latter situation for positive definite matrices, the matrix + square root has "Real" elements, otherwise it has "Complex" + elements. + ``` + """ Base.sqrtm + + @doc doc""" + ```rst + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of "A". See "eigfact()" + for details on the "balance" keyword argument. + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + "eig" is a wrapper around "eigfact()", extracting all parts of + the factorization to a tuple; where possible, using "eigfact()" + is recommended. + ``` + """ Base.eig + + @doc doc""" + ```rst + eig(A, B) -> D, V + + Computes generalized eigenvalues and vectors of "A" with respect + to "B". + + "eig" is a wrapper around "eigfact()", extracting all parts of + the factorization to a tuple; where possible, using "eigfact()" + is recommended. + ``` + """ Base.eig + + @doc doc""" + ```rst + eigvals(A,[irange,][vl,][vu]) + + Returns the eigenvalues of "A". If "A" is "Symmetric", + "Hermitian" or "SymTridiagonal", it is possible to calculate + only a subset of the eigenvalues by specifying either a + "UnitRange" "irange" covering indices of the sorted + eigenvalues, or a pair "vl" and "vu" for the lower and upper + boundaries of the eigenvalues. + + For general non-symmetric matrices it is possible to specify how + the matrix is balanced before the eigenvector calculation. The + option "permute=true" permutes the matrix to become closer to + upper triangular, and "scale=true" scales the matrix by its + diagonal elements to make rows and columns more equal in norm. The + default is "true" for both options. + ``` + """ Base.eigvals + + @doc doc""" + ```rst + eigmax(A) + + Returns the largest eigenvalue of "A". + ``` + """ Base.eigmax + + @doc doc""" + ```rst + eigmin(A) + + Returns the smallest eigenvalue of "A". + ``` + """ Base.eigmin + + @doc doc""" + ```rst + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + + Returns a matrix "M" whose columns are the eigenvectors of "A". + (The "k"th eigenvector can be obtained from the slice "M[:, + k]".) The "permute" and "scale" keywords are the same as for + "eigfact()". + + For "SymTridiagonal" matrices, if the optional vector of + eigenvalues "eigvals" is specified, returns the specific + corresponding eigenvectors. + ``` + """ Base.eigvecs + + @doc doc""" + ```rst + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of "A", returning an + "Eigen" factorization object "F" which contains the eigenvalues + in "F[:values]" and the eigenvectors in the columns of the matrix + "F[:vectors]". (The "k"th eigenvector can be obtained from the + slice "F[:vectors][:, k]".) + + The following functions are available for "Eigen" objects: + "inv", "det". + + If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it + is possible to calculate only a subset of the eigenvalues by + specifying either a "UnitRange" "irange" covering indices of + the sorted eigenvalues or a pair "vl" and "vu" for the lower + and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the + matrix is balanced before the eigenvector calculation. The option + "permute=true" permutes the matrix to become closer to upper + triangular, and "scale=true" scales the matrix by its diagonal + elements to make rows and columns more equal in norm. The default + is "true" for both options. + ``` + """ Base.eigfact + + @doc doc""" + ```rst + eigfact(A, B) -> GeneralizedEigen + + Computes the generalized eigenvalue decomposition of "A" and + "B", returning a "GeneralizedEigen" factorization object "F" + which contains the generalized eigenvalues in "F[:values]" and + the generalized eigenvectors in the columns of the matrix + "F[:vectors]". (The "k"th generalized eigenvector can be + obtained from the slice "F[:vectors][:, k]".) + ``` + """ Base.eigfact + + @doc doc""" + ```rst + eigfact!(A[, B]) + + Same as "eigfact()", but saves space by overwriting the input + "A" (and "B"), instead of creating a copy. + ``` + """ Base.eigfact! + + @doc doc""" + ```rst + hessfact(A) + + Compute the Hessenberg decomposition of "A" and return a + "Hessenberg" object. If "F" is the factorization object, the + unitary matrix can be accessed with "F[:Q]" and the Hessenberg + matrix with "F[:H]". When "Q" is extracted, the resulting type + is the "HessenbergQ" object, and may be converted to a regular + matrix with "full()". + ``` + """ Base.hessfact + + @doc doc""" + ```rst + hessfact!(A) + + "hessfact!" is the same as "hessfact()", but saves space by + overwriting the input A, instead of creating a copy. + ``` + """ Base.hessfact! + + @doc doc""" + ```rst + schurfact(A) -> Schur + + Computes the Schur factorization of the matrix "A". The (quasi) + triangular Schur factor can be obtained from the "Schur" object + "F" with either "F[:Schur]" or "F[:T]" and the + unitary/orthogonal Schur vectors can be obtained with + "F[:vectors]" or "F[:Z]" such that + "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" + can be obtained with "F[:values]". + ``` + """ Base.schurfact + + @doc doc""" + ```rst + schurfact!(A) + + Computes the Schur factorization of "A", overwriting "A" in the + process. See "schurfact()" + ``` + """ Base.schurfact! + + @doc doc""" + ```rst + schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + + See "schurfact()" + ``` + """ Base.schur + + @doc doc""" + ```rst + ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'" + according to the logical array "select" returning a Schur object + "F". The selected eigenvalues appear in the leading diagonal of + "F[:Schur]" and the the corresponding leading columns of + "F[:vectors]" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via "select". + ``` + """ Base.ordschur + + @doc doc""" + ```rst + ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'", + overwriting "Q" and "T" in the process. See "ordschur()" + ``` + """ Base.ordschur! + + @doc doc""" + ```rst + ordschur(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur". + ``` + """ Base.ordschur + + @doc doc""" + ```rst + ordschur!(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur", + overwriting "S" in the process. See "ordschur()" + ``` + """ Base.ordschur! + + @doc doc""" + ```rst + schurfact(A, B) -> GeneralizedSchur + + Computes the Generalized Schur (or QZ) factorization of the + matrices "A" and "B". The (quasi) triangular Schur factors can + be obtained from the "Schur" object "F" with "F[:S]" and + "F[:T]", the left unitary/orthogonal Schur vectors can be + obtained with "F[:left]" or "F[:Q]" and the right + unitary/orthogonal Schur vectors can be obtained with "F[:right]" + or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and + "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of + "A" and "B" can be obtained with "F[:alpha]./F[:beta]". + ``` + """ Base.schurfact + + @doc doc""" + ```rst + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + + See "schurfact()" + ``` + """ Base.schur + + @doc doc""" + ```rst + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix "(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" + and returns a GeneralizedSchur object "GS". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that "(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of + "A" and "B" can still be obtained with + "GS[:alpha]./GS[:beta]". + ``` + """ Base.ordschur + + @doc doc""" + ```rst + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices "(S, T, Q, Z)" in the process. See + "ordschur()". + ``` + """ Base.ordschur! + + @doc doc""" + ```rst + ordschur(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur + object. See "ordschur()". + ``` + """ Base.ordschur + + @doc doc""" + ```rst + ordschur!(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + "ordschur()". + ``` + """ Base.ordschur! + + @doc doc""" + ```rst + svdfact(A[, thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of "A" and return + an "SVD" object. "U", "S", "V" and "Vt" can be obtained + from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" + and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is + "true", an economy mode decomposition is returned. The algorithm + produces "Vt" and hence "Vt" is more efficient to extract than + "V". The default is to produce a thin decomposition. + ``` + """ Base.svdfact + + @doc doc""" + ```rst + svdfact!(A[, thin=true]) -> SVD + + "svdfact!" is the same as "svdfact()", but saves space by + overwriting the input A, instead of creating a copy. If "thin" is + "true", an economy mode decomposition is returned. The default is + to produce a thin decomposition. + ``` + """ Base.svdfact! + + @doc doc""" + ```rst + svd(A[, thin=true]) -> U, S, V + + Wrapper around "svdfact" extracting all parts the factorization + to a tuple. Direct use of "svdfact" is therefore generally more + efficient. Computes the SVD of A, returning "U", vector "S", + and "V" such that "A == U*diagm(S)*V'". If "thin" is + "true", an economy mode decomposition is returned. The default is + to produce a thin decomposition. + ``` + """ Base.svd + + @doc doc""" + ```rst + svdvals(A) + + Returns the singular values of "A". + ``` + """ Base.svdvals + + @doc doc""" + ```rst + svdvals!(A) + + Returns the singular values of "A", while saving space by + overwriting the input. + ``` + """ Base.svdvals! + + @doc doc""" + ```rst + svdfact(A, B) -> GeneralizedSVD + + Compute the generalized SVD of "A" and "B", returning a + "GeneralizedSVD" Factorization object "F", such that "A = + F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = + F[:V]*F[:D2]*F[:R0]*F[:Q]'". + ``` + """ Base.svdfact + + @doc doc""" + ```rst + svd(A, B) -> U, V, Q, D1, D2, R0 + + Wrapper around "svdfact" extracting all parts the factorization + to a tuple. Direct use of "svdfact" is therefore generally more + efficient. The function returns the generalized SVD of "A" and + "B", returning "U", "V", "Q", "D1", "D2", and "R0" + such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". + ``` + """ Base.svd + + @doc doc""" + ```rst + svdvals(A, B) + + Return only the singular values from the generalized singular value + decomposition of "A" and "B". + ``` + """ Base.svdvals + + @doc doc""" + ```rst + triu(M) + + Upper triangle of a matrix. + ``` + """ Base.triu + + @doc doc""" + ```rst + triu(M, k) + + Returns the upper triangle of "M" starting from the "k"th + superdiagonal. + ``` + """ Base.triu + + @doc doc""" + ```rst + triu!(M) + + Upper triangle of a matrix, overwriting "M" in the process. + ``` + """ Base.triu! + + @doc doc""" + ```rst + triu!(M, k) + + Returns the upper triangle of "M" starting from the "k"th + superdiagonal, overwriting "M" in the process. + ``` + """ Base.triu! + + @doc doc""" + ```rst + tril(M) + + Lower triangle of a matrix. + ``` + """ Base.tril + + @doc doc""" + ```rst + tril(M, k) + + Returns the lower triangle of "M" starting from the "k"th + subdiagonal. + ``` + """ Base.tril + + @doc doc""" + ```rst + tril!(M) + + Lower triangle of a matrix, overwriting "M" in the process. + ``` + """ Base.tril! + + @doc doc""" + ```rst + tril!(M, k) + + Returns the lower triangle of "M" starting from the "k"th + subdiagonal, overwriting "M" in the process. + ``` + """ Base.tril! + + @doc doc""" + ```rst + diagind(M[, k]) + + A "Range" giving the indices of the "k"th diagonal of the + matrix "M". + ``` + """ Base.diagind + + @doc doc""" + ```rst + diag(M[, k]) + + The "k"th diagonal of a matrix, as a vector. Use "diagm" to + construct a diagonal matrix. + ``` + """ Base.diag + + @doc doc""" + ```rst + diagm(v[, k]) + + Construct a diagonal matrix and place "v" on the "k"th + diagonal. + ``` + """ Base.diagm + + @doc doc""" + ```rst + scale(A, b) + ``` + """ Base.scale + + @doc doc""" + ```rst + scale(b, A) + + Scale an array "A" by a scalar "b", returning a new array. + + If "A" is a matrix and "b" is a vector, then "scale(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), returning a new + array. + + Note: for large "A", "scale" can be much faster than "A .* b" + or "b .* A", due to the use of BLAS. + ``` + """ Base.scale + + @doc doc""" + ```rst + scale!(A, b) + ``` + """ Base.scale! + + @doc doc""" + ```rst + scale!(b, A) + + Scale an array "A" by a scalar "b", similar to "scale()" but + overwriting "A" in-place. + + If "A" is a matrix and "b" is a vector, then "scale!(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- + place on "A". + ``` + """ Base.scale! + + @doc doc""" + ```rst + Tridiagonal(dl, d, du) + + Construct a tridiagonal matrix from the lower diagonal, diagonal, + and upper diagonal, respectively. The result is of type + "Tridiagonal" and provides efficient specialized linear solvers, + but may be converted into a regular matrix with "full()". + ``` + """ Base.Tridiagonal + + @doc doc""" + ```rst + Bidiagonal(dv, ev, isupper) + + Constructs an upper ("isupper=true") or lower ("isupper=false") + bidiagonal matrix using the given diagonal ("dv") and off- + diagonal ("ev") vectors. The result is of type "Bidiagonal" + and provides efficient specialized linear solvers, but may be + converted into a regular matrix with "full()". + ``` + """ Base.Bidiagonal + + @doc doc""" + ```rst + SymTridiagonal(d, du) + + Construct a real symmetric tridiagonal matrix from the diagonal and + upper diagonal, respectively. The result is of type + "SymTridiagonal" and provides efficient specialized eigensolvers, + but may be converted into a regular matrix with "full()". + ``` + """ Base.SymTridiagonal + + @doc doc""" + ```rst + rank(M) + + Compute the rank of a matrix. + ``` + """ Base.rank + + @doc doc""" + ```rst + norm(A[, p]) + + Compute the "p"-norm of a vector or the operator norm of a matrix + "A", defaulting to the "p=2"-norm. + + For vectors, "p" can assume any numeric value (even though not + all values produce a mathematically valid vector norm). In + particular, "norm(A, Inf)" returns the largest value in + "abs(A)", whereas "norm(A, -Inf)" returns the smallest. + + For matrices, valid values of "p" are "1", "2", or "Inf". + (Note that for sparse matrices, "p=2" is currently not + implemented.) Use "vecnorm()" to compute the Frobenius norm. + ``` + """ Base.norm + + @doc doc""" + ```rst + vecnorm(A[, p]) + + For any iterable container "A" (including arrays of any + dimension) of numbers (or any element type for which "norm" is + defined), compute the "p"-norm (defaulting to "p=2") as if + "A" were a vector of the corresponding length. + + For example, if "A" is a matrix and "p=2", then this is + equivalent to the Frobenius norm. + ``` + """ Base.vecnorm + + @doc doc""" + ```rst + cond(M[, p]) + + Condition number of the matrix "M", computed using the operator + "p"-norm. Valid values for "p" are "1", "2" (default), or + "Inf". + ``` + """ Base.cond + + @doc doc""" + ```rst + condskeel(M[, x, p]) + + \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \right\Vert_p \\ + \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \left\vert x \right\vert + \right\Vert_p + + Skeel condition number \kappa_S of the matrix "M", optionally + with respect to the vector "x", as computed using the operator + "p"-norm. "p" is "Inf" by default, if not provided. Valid + values for "p" are "1", "2", or "Inf". + + This quantity is also known in the literature as the Bauer + condition number, relative condition number, or componentwise + relative condition number. + ``` + """ Base.condskeel + + @doc doc""" + ```rst + trace(M) + + Matrix trace + ``` + """ Base.trace + + @doc doc""" + ```rst + det(M) + + Matrix determinant + ``` + """ Base.det + + @doc doc""" + ```rst + logdet(M) + + Log of matrix determinant. Equivalent to "log(det(M))", but may + provide increased accuracy and/or speed. + ``` + """ Base.logdet + + @doc doc""" + ```rst + inv(M) + + Matrix inverse + ``` + """ Base.inv + + @doc doc""" + ```rst + pinv(M[, tol]) + + Computes the Moore-Penrose pseudoinverse. + + For matrices "M" with floating point elements, it is convenient + to compute the pseudoinverse by inverting only singular values + above a given threshold, "tol". + + The optimal choice of "tol" varies both with the value of "M" + and the intended application of the pseudoinverse. The default + value of "tol" is + "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is + essentially machine epsilon for the real part of a matrix element + multiplied by the larger matrix dimension. For inverting dense ill- + conditioned matrices in a least-squares sense, "tol = + sqrt(eps(real(float(one(eltype(M))))))" is recommended. + + For more information, see [8859], [B96], [S84], [KY88]. + + [8859] Issue 8859, "Fix least squares", + https://github.com/JuliaLang/julia/pull/8859 + + [B96] Åke Björck, "Numerical Methods for Least Squares + Problems", SIAM Press, Philadelphia, 1996, "Other Titles in + Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 + + [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 + + [KY88] Konstantinos Konstantinides and Kung Yao, + "Statistical analysis of effective singular values in + matrix rank determination", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 + ``` + """ Base.pinv + + @doc doc""" + ```rst + nullspace(M) + + Basis for nullspace of "M". + ``` + """ Base.nullspace + + @doc doc""" + ```rst + repmat(A, n, m) + + Construct a matrix by repeating the given matrix "n" times in + dimension 1 and "m" times in dimension 2. + ``` + """ Base.repmat + + @doc doc""" + ```rst + repeat(A, inner = Int[], outer = Int[]) + + Construct an array by repeating the entries of "A". The i-th + element of "inner" specifies the number of times that the + individual entries of the i-th dimension of "A" should be + repeated. The i-th element of "outer" specifies the number of + times that a slice along the i-th dimension of "A" should be + repeated. + ``` + """ Base.repeat + + @doc doc""" + ```rst + kron(A, B) + + Kronecker tensor product of two vectors or two matrices. + ``` + """ Base.kron + + @doc doc""" + ```rst + blkdiag(A...) + + Concatenate matrices block-diagonally. Currently only implemented + for sparse matrices. + ``` + """ Base.blkdiag + + @doc doc""" + ```rst + linreg(x, y) -> [a; b] + + Linear Regression. Returns "a" and "b" such that "a+b*x" is + the closest line to the given points "(x,y)". In other words, + this function determines parameters "[a, b]" that minimize the + squared error between "y" and "a+b*x". + + **Example**: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + ``` + """ Base.linreg + + @doc doc""" + ```rst + linreg(x, y, w) + + Weighted least-squares linear regression. + ``` + """ Base.linreg + + @doc doc""" + ```rst + expm(A) + + Matrix exponential. + ``` + """ Base.expm + + @doc doc""" + ```rst + lyap(A, C) + + Computes the solution "X" to the continuous Lyapunov equation + "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real + part and no two eigenvalues are negative complex conjugates of each + other. + ``` + """ Base.lyap + + @doc doc""" + ```rst + sylvester(A, B, C) + + Computes the solution "X" to the Sylvester equation "AX + XB + C + = 0", where "A", "B" and "C" have compatible dimensions and + "A" and "-B" have no eigenvalues with equal real part. + ``` + """ Base.sylvester + + @doc doc""" + ```rst + issym(A) -> Bool + + Test whether a matrix is symmetric. + ``` + """ Base.issym + + @doc doc""" + ```rst + isposdef(A) -> Bool + + Test whether a matrix is positive definite. + ``` + """ Base.isposdef + + @doc doc""" + ```rst + isposdef!(A) -> Bool + + Test whether a matrix is positive definite, overwriting "A" in + the processes. + ``` + """ Base.isposdef! + + @doc doc""" + ```rst + istril(A) -> Bool + + Test whether a matrix is lower triangular. + ``` + """ Base.istril + + @doc doc""" + ```rst + istriu(A) -> Bool + + Test whether a matrix is upper triangular. + ``` + """ Base.istriu + + @doc doc""" + ```rst + isdiag(A) -> Bool + + Test whether a matrix is diagonal. + ``` + """ Base.isdiag + + @doc doc""" + ```rst + ishermitian(A) -> Bool + + Test whether a matrix is Hermitian. + ``` + """ Base.ishermitian + + @doc doc""" + ```rst + transpose(A) + + The transposition operator (".'"). + ``` + """ Base.transpose + + @doc doc""" + ```rst + transpose!(dest, src) + + Transpose array "src" and store the result in the preallocated + array "dest", which should have a size corresponding to + "(size(src,2),size(src,1))". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. + ``` + """ Base.transpose! + + @doc doc""" + ```rst + ctranspose(A) + + The conjugate transposition operator ("'"). + ``` + """ Base.ctranspose + + @doc doc""" + ```rst + ctranspose!(dest, src) + + Conjugate transpose array "src" and store the result in the + preallocated array "dest", which should have a size corresponding + to "(size(src,2),size(src,1))". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. + ``` + """ Base.ctranspose! + + @doc doc""" + ```rst + eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) + + Computes eigenvalues "d" of "A" using Lanczos or Arnoldi + iterations for real symmetric or general nonsymmetric matrices + respectively. If "B" is provided, the generalized eigenproblem is + solved. + + The following keyword arguments are supported: + * "nev": Number of eigenvalues + + * "ncv": Number of Krylov vectors used in the computation; + should satisfy + + "nev+1 <= ncv <= n" for real symmetric problems and + "nev+2 <= ncv <= n" for other problems, where "n" is + the size of the input matrix "A". The default is "ncv = + max(20,2*nev+1)". Note that these restrictions limit the + input matrix "A" to be of dimension at least 2. + + * "which": type of eigenvalues to compute. See the note + below. + + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \"which\" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LM\" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SM\" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LR\" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SR\" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + + * "tol": tolerance (tol \le 0.0 defaults to + "DLAMCH('EPS')") + + * "maxiter": Maximum number of iterations (default = 300) + + * "sigma": Specifies the level shift used in inverse + iteration. If "nothing" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + "sigma" using shift and invert iterations. + + * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) + if "true" + + * "v0": starting vector from which to start the iterations + + "eigs" returns the "nev" requested eigenvalues in "d", the + corresponding Ritz vectors "v" (only if "ritzvec=true"), the + number of converged eigenvalues "nconv", the number of iterations + "niter" and the number of matrix vector multiplications + "nmult", as well as the final residual vector "resid". + + Note: The "sigma" and "which" keywords interact: the + description of eigenvalues searched for by "which" do _not_ + necessarily refer to the eigenvalues of "A", but rather the + linear operator constructed by the specification of the iteration + mode implied by "sigma". + + +-----------------+------------------------------------+------------------------------------+ + | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | + +-----------------+------------------------------------+------------------------------------+ + | \"nothing\" | ordinary (forward) | A | + +-----------------+------------------------------------+------------------------------------+ + | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | + +-----------------+------------------------------------+------------------------------------+ + ``` + """ Base.eigs + + @doc doc""" + ```rst + svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + + "svds" computes largest singular values "s" of "A" using + Lanczos or Arnoldi iterations. Uses "eigs()" underneath. + + Inputs are: + * "A": Linear operator. It can either subtype of + "AbstractArray" (e.g., sparse matrix) or duck typed. For + duck typing "A" has to support "size(A)", "eltype(A)", + "A * vector" and "A' * vector". + + * "nsv": Number of singular values. + + * "ritzvec": Whether to return the left and right singular + vectors "left_sv" and "right_sv", default is "true". If + "false" the singular vectors are omitted from the output. + + * "tol": tolerance, see "eigs()". + + * "maxiter": Maximum number of iterations, see "eigs()". + + **Example**: + + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) + ``` + """ Base.svds + + @doc doc""" + ```rst + peakflops(n; parallel=false) + + "peakflops" computes the peak flop rate of the computer by using + double precision "Base.LinAlg.BLAS.gemm!()". By default, if no + arguments are specified, it multiplies a matrix of size "n x n", + where "n = 2000". If the underlying BLAS is using multiple + threads, higher flop rates are realized. The number of BLAS threads + can be set with "blas_set_num_threads(n)". + + If the keyword argument "parallel" is set to "true", + "peakflops" is run in parallel on all the worker processors. The + flop rate of the entire parallel computer is returned. When running + in parallel, only 1 BLAS thread is used. The argument "n" still + refers to the size of the problem that is solved on each processor. + ``` + """ Base.peakflops + + @doc doc""" + ```rst + dot(n, X, incx, Y, incy) + + Dot product of two vectors consisting of "n" elements of array + "X" with stride "incx" and "n" elements of array "Y" with + stride "incy". + ``` + """ Base.LinAlg.BLAS.dot + + @doc doc""" + ```rst + dotu(n, X, incx, Y, incy) + + Dot function for two complex vectors. + ``` + """ Base.LinAlg.BLAS.dotu + + @doc doc""" + ```rst + dotc(n, X, incx, U, incy) + + Dot function for two complex vectors conjugating the first vector. + ``` + """ Base.LinAlg.BLAS.dotc + + @doc doc""" + ```rst + blascopy!(n, X, incx, Y, incy) + + Copy "n" elements of array "X" with stride "incx" to array + "Y" with stride "incy". Returns "Y". + ``` + """ Base.LinAlg.BLAS.blascopy! + + @doc doc""" + ```rst + nrm2(n, X, incx) + + 2-norm of a vector consisting of "n" elements of array "X" with + stride "incx". + ``` + """ Base.LinAlg.BLAS.nrm2 + + @doc doc""" + ```rst + asum(n, X, incx) + + sum of the absolute values of the first "n" elements of array + "X" with stride "incx". + ``` + """ Base.LinAlg.BLAS.asum + + @doc doc""" + ```rst + axpy!(a, X, Y) + + Overwrite "Y" with "a*X + Y". Returns "Y". + ``` + """ Base.LinAlg.BLAS.axpy! + + @doc doc""" + ```rst + scal!(n, a, X, incx) + + Overwrite "X" with "a*X". Returns "X". + ``` + """ Base.LinAlg.BLAS.scal! + + @doc doc""" + ```rst + scal(n, a, X, incx) + + Returns "a*X". + ``` + """ Base.LinAlg.BLAS.scal + + @doc doc""" + ```rst + ger!(alpha, x, y, A) + + Rank-1 update of the matrix "A" with vectors "x" and "y" as + "alpha*x*y' + A". + ``` + """ Base.LinAlg.BLAS.ger! + + @doc doc""" + ```rst + syr!(uplo, alpha, x, A) + + Rank-1 update of the symmetric matrix "A" with vector "x" as + "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of + "A" is updated ('L' for lower triangle). Returns "A". + ``` + """ Base.LinAlg.BLAS.syr! + + @doc doc""" + ```rst + syrk!(uplo, trans, alpha, A, beta, C) + + Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + + beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" + is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is + updated ('L' for lower triangle). Returns "C". + ``` + """ Base.LinAlg.BLAS.syrk! + + @doc doc""" + ```rst + syrk(uplo, trans, alpha, A) + + Returns either the upper triangle or the lower triangle, according + to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", + according to "trans" ('N' or 'T'). + ``` + """ Base.LinAlg.BLAS.syrk + + @doc doc""" + ```rst + her!(uplo, alpha, x, A) + + Methods for complex arrays only. Rank-1 update of the Hermitian + matrix "A" with vector "x" as "alpha*x*x' + A". When + "uplo" is 'U' the upper triangle of "A" is updated ('L' for + lower triangle). Returns "A". + ``` + """ Base.LinAlg.BLAS.her! + + @doc doc""" + ```rst + herk!(uplo, trans, alpha, A, beta, C) + + Methods for complex arrays only. Rank-k update of the Hermitian + matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" + according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' + the upper triangle of "C" is updated ('L' for lower triangle). + Returns "C". + ``` + """ Base.LinAlg.BLAS.herk! + + @doc doc""" + ```rst + herk(uplo, trans, alpha, A) + + Methods for complex arrays only. Returns either the upper triangle + or the lower triangle, according to "uplo" ('U' or 'L'), of + "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or + 'T'). + ``` + """ Base.LinAlg.BLAS.herk + + @doc doc""" + ```rst + gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) + + Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + + beta*y" according to "trans" ('N' or 'T'). The matrix "A" is + a general band matrix of dimension "m" by "size(A,2)" with + "kl" sub-diagonals and "ku" super-diagonals. Returns the + updated "y". + ``` + """ Base.LinAlg.BLAS.gbmv! + + @doc doc""" + ```rst + gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + + Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' + or 'T'). The matrix "A" is a general band matrix of dimension + "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- + diagonals. + ``` + """ Base.LinAlg.BLAS.gbmv + + @doc doc""" + ```rst + sbmv!(uplo, k, alpha, A, x, beta, y) + + Update vector "y" as "alpha*A*x + beta*y" where "A" is a a + symmetric band matrix of order "size(A,2)" with "k" super- + diagonals stored in the argument "A". The storage layout for + "A" is described the reference BLAS module, level-2 BLAS at + http://www.netlib.org/lapack/explore-html/. + + Returns the updated "y". + ``` + """ Base.LinAlg.BLAS.sbmv! + + @doc doc""" + ```rst + sbmv(uplo, k, alpha, A, x) + + Returns "alpha*A*x" where "A" is a symmetric band matrix of + order "size(A,2)" with "k" super-diagonals stored in the + argument "A". + ``` + """ Base.LinAlg.BLAS.sbmv + + @doc doc""" + ```rst + sbmv(uplo, k, A, x) + + Returns "A*x" where "A" is a symmetric band matrix of order + "size(A,2)" with "k" super-diagonals stored in the argument + "A". + ``` + """ Base.LinAlg.BLAS.sbmv + + @doc doc""" + ```rst + gemm!(tA, tB, alpha, A, B, beta, C) + + Update "C" as "alpha*A*B + beta*C" or the other three variants + according to "tA" (transpose "A") and "tB". Returns the + updated "C". + ``` + """ Base.LinAlg.BLAS.gemm! + + @doc doc""" + ```rst + gemm(tA, tB, alpha, A, B) + + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". + ``` + """ Base.LinAlg.BLAS.gemm + + @doc doc""" + ```rst + gemm(tA, tB, A, B) + + Returns "A*B" or the other three variants according to "tA" + (transpose "A") and "tB". + ``` + """ Base.LinAlg.BLAS.gemm + + @doc doc""" + ```rst + gemv!(tA, alpha, A, x, beta, y) + + Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + + beta*y" according to "tA" (transpose "A"). Returns the updated + "y". + ``` + """ Base.LinAlg.BLAS.gemv! + + @doc doc""" + ```rst + gemv(tA, alpha, A, x) + + Returns "alpha*A*x" or "alpha*A'x" according to "tA" + (transpose "A"). + ``` + """ Base.LinAlg.BLAS.gemv + + @doc doc""" + ```rst + gemv(tA, A, x) + + Returns "A*x" or "A'x" according to "tA" (transpose "A"). + ``` + """ Base.LinAlg.BLAS.gemv + + @doc doc""" + ```rst + symm!(side, ul, alpha, A, B, beta, C) + + Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" + according to "side". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. Returns the updated "C". + ``` + """ Base.LinAlg.BLAS.symm! + + @doc doc""" + ```rst + symm(side, ul, alpha, A, B) + + Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" + is assumed to be symmetric. Only the "ul" triangle of "A" is + used. + ``` + """ Base.LinAlg.BLAS.symm + + @doc doc""" + ```rst + symm(side, ul, A, B) + + Returns "A*B" or "B*A" according to "side". "A" is assumed + to be symmetric. Only the "ul" triangle of "A" is used. + ``` + """ Base.LinAlg.BLAS.symm + + @doc doc""" + ```rst + symm(tA, tB, alpha, A, B) + + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". + ``` + """ Base.LinAlg.BLAS.symm + + @doc doc""" + ```rst + symv!(ul, alpha, A, x, beta, y) + + Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed + to be symmetric. Only the "ul" triangle of "A" is used. + Returns the updated "y". + ``` + """ Base.LinAlg.BLAS.symv! + + @doc doc""" + ```rst + symv(ul, alpha, A, x) + + Returns "alpha*A*x". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. + ``` + """ Base.LinAlg.BLAS.symv + + @doc doc""" + ```rst + symv(ul, A, x) + + Returns "A*x". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. + ``` + """ Base.LinAlg.BLAS.symv + + @doc doc""" + ```rst + trmm!(side, ul, tA, dA, alpha, A, B) + + Update "B" as "alpha*A*B" or one of the other three variants + determined by "side" (A on left or right) and "tA" (transpose + A). Only the "ul" triangle of "A" is used. "dA" indicates if + "A" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated "B". + ``` + """ Base.LinAlg.BLAS.trmm! + + @doc doc""" + ```rst + trmm(side, ul, tA, dA, alpha, A, B) + + Returns "alpha*A*B" or one of the other three variants determined + by "side" (A on left or right) and "tA" (transpose A). Only the + "ul" triangle of "A" is used. "dA" indicates if "A" is + unit-triangular (the diagonal is assumed to be all ones). + ``` + """ Base.LinAlg.BLAS.trmm + + @doc doc""" + ```rst + trsm!(side, ul, tA, dA, alpha, A, B) + + Overwrite "B" with the solution to "A*X = alpha*B" or one of + the other three variants determined by "side" (A on left or right + of "X") and "tA" (transpose A). Only the "ul" triangle of + "A" is used. "dA" indicates if "A" is unit-triangular (the + diagonal is assumed to be all ones). Returns the updated "B". + ``` + """ Base.LinAlg.BLAS.trsm! + + @doc doc""" + ```rst + trsm(side, ul, tA, dA, alpha, A, B) + + Returns the solution to "A*X = alpha*B" or one of the other three + variants determined by "side" (A on left or right of "X") and + "tA" (transpose A). Only the "ul" triangle of "A" is used. + "dA" indicates if "A" is unit-triangular (the diagonal is + assumed to be all ones). + ``` + """ Base.LinAlg.BLAS.trsm + + @doc doc""" + ```rst + trmv!(side, ul, tA, dA, alpha, A, b) + + Update "b" as "alpha*A*b" or one of the other three variants + determined by "side" (A on left or right) and "tA" (transpose + A). Only the "ul" triangle of "A" is used. "dA" indicates if + "A" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated "b". + ``` + """ Base.LinAlg.BLAS.trmv! + + @doc doc""" + ```rst + trmv(side, ul, tA, dA, alpha, A, b) + + Returns "alpha*A*b" or one of the other three variants determined + by "side" (A on left or right) and "tA" (transpose A). Only the + "ul" triangle of "A" is used. "dA" indicates if "A" is + unit-triangular (the diagonal is assumed to be all ones). + ``` + """ Base.LinAlg.BLAS.trmv + + @doc doc""" + ```rst + trsv!(ul, tA, dA, A, b) + + Overwrite "b" with the solution to "A*x = b" or one of the + other two variants determined by "tA" (transpose A) and "ul" + (triangle of "A" used). "dA" indicates if "A" is unit- + triangular (the diagonal is assumed to be all ones). Returns the + updated "b". + ``` + """ Base.LinAlg.BLAS.trsv! + + @doc doc""" + ```rst + trsv(ul, tA, dA, A, b) + + Returns the solution to "A*x = b" or one of the other two + variants determined by "tA" (transpose A) and "ul" (triangle of + "A" is used.) "dA" indicates if "A" is unit-triangular (the + diagonal is assumed to be all ones). + ``` + """ Base.LinAlg.BLAS.trsv + + @doc doc""" + ```rst + blas_set_num_threads(n) + + Set the number of threads the BLAS library should use. + ``` + """ Base.LinAlg.BLAS.blas_set_num_threads + + @doc doc""" + ```rst + I + + An object of type "UniformScaling", representing an identity + matrix of any size. + ``` + """ Base.LinAlg.BLAS.I + + @doc doc""" + ```rst + -(x) + + Unary minus operator. + ``` + """ Base.(:(-)) + + @doc doc""" + ```rst + +(x, y...) + + Addition operator. "x+y+z+..." calls this function with all + arguments, i.e. "+(x, y, z, ...)". + ``` + """ Base.(:(+)) + + @doc doc""" + ```rst + -(x, y) + + Subtraction operator. + ``` + """ Base.(:(-)) + + @doc doc""" + ```rst + *(x, y...) + + Multiplication operator. "x*y*z*..." calls this function with all + arguments, i.e. "*(x, y, z, ...)". + ``` + """ Base.(:(*)) + + @doc doc""" + ```rst + /(x, y) + + Right division operator: multiplication of "x" by the inverse of + "y" on the right. Gives floating-point results for integer + arguments. + ``` + """ Base.(:(/)) + + @doc doc""" + ```rst + \(x, y) + + Left division operator: multiplication of "y" by the inverse of + "x" on the left. Gives floating-point results for integer + arguments. + ``` + """ Base.(:(\)) + + @doc doc""" + ```rst + ^(x, y) + + Exponentiation operator. + ``` + """ Base.(:(^)) + + @doc doc""" + ```rst + .+(x, y) + + Element-wise addition operator. + ``` + """ Base.(:(.+)) + + @doc doc""" + ```rst + .-(x, y) + + Element-wise subtraction operator. + ``` + """ Base.(:(.-)) + + @doc doc""" + ```rst + .*(x, y) + + Element-wise multiplication operator. + ``` + """ Base.(:(.*)) + + @doc doc""" + ```rst + ./(x, y) + + Element-wise right division operator. + ``` + """ Base.(:(./)) + + @doc doc""" + ```rst + .\(x, y) + + Element-wise left division operator. + ``` + """ Base.(:(.\)) + + @doc doc""" + ```rst + .^(x, y) + + Element-wise exponentiation operator. + ``` + """ Base.(:(.^)) + + @doc doc""" + ```rst + fma(x, y, z) + + Computes "x*y+z" without rounding the intermediate result + "x*y". On some systems this is significantly more expensive than + "x*y+z". "fma" is used to improve accuracy in certain + algorithms. See "muladd". + ``` + """ Base.fma + + @doc doc""" + ```rst + muladd(x, y, z) + + Combined multiply-add, computes "x*y+z" in an efficient manner. + This may on some systems be equivalent to "x*y+z", or to + "fma(x,y,z)". "muladd" is used to improve performance. See + "fma". + ``` + """ Base.muladd + + @doc doc""" + ```rst + div(x, y) +÷(x, y) + + The quotient from Euclidean division. Computes "x/y", truncated + to an integer. + ``` + """ Base.div + + @doc doc""" + ```rst + fld(x, y) + + Largest integer less than or equal to "x/y". + ``` + """ Base.fld + + @doc doc""" + ```rst + cld(x, y) + + Smallest integer larger than or equal to "x/y". + ``` + """ Base.cld + + @doc doc""" + ```rst + mod(x, y) + + Modulus after division, returning in the range [0,``y``), if "y" + is positive, or ("y",0] if "y" is negative. + ``` + """ Base.mod + + @doc doc""" + ```rst + mod2pi(x) + + Modulus after division by 2pi, returning in the range [0,2pi). + + This function computes a floating point representation of the + modulus after division by numerically exact 2pi, and is therefore + not exactly the same as mod(x,2pi), which would compute the modulus + of x relative to division by the floating-point number 2pi. + ``` + """ Base.mod2pi + + @doc doc""" + ```rst + rem(x, y) +%(x, y) + + Remainder from Euclidean division, returning a value of the same + sign as``x``, and smaller in magnitude than "y". This value is + always exact. + ``` + """ Base.rem + + @doc doc""" + ```rst + divrem(x, y) + + The quotient and remainder from Euclidean division. Equivalent to + "(x÷y, x%y)". + ``` + """ Base.divrem + + @doc doc""" + ```rst + fldmod(x, y) + + The floored quotient and modulus after division. Equivalent to + "(fld(x,y), mod(x,y))". + ``` + """ Base.fldmod + + @doc doc""" + ```rst + mod1(x, m) + + Modulus after division, returning in the range (0,m] + ``` + """ Base.mod1 + + @doc doc""" + ```rst + rem1(x, m) + + Remainder after division, returning in the range (0,m] + ``` + """ Base.rem1 + + @doc doc""" + ```rst + //(num, den) + + Divide two integers or rational numbers, giving a "Rational" + result. + ``` + """ Base.(:(//)) + + @doc doc""" + ```rst + rationalize([Type=Int], x; tol=eps(x)) + + Approximate floating point number "x" as a Rational number with + components of the given integer type. The result will differ from + "x" by no more than "tol". + ``` + """ Base.rationalize + + @doc doc""" + ```rst + num(x) + + Numerator of the rational representation of "x" + ``` + """ Base.num + + @doc doc""" + ```rst + den(x) + + Denominator of the rational representation of "x" + ``` + """ Base.den + + @doc doc""" + ```rst + <<(x, n) + + Left bit shift operator. + ``` + """ Base.(:(<<)) + + @doc doc""" + ```rst + >>(x, n) + + Right bit shift operator, preserving the sign of "x". + ``` + """ Base.(:(>>)) + + @doc doc""" + ```rst + >>>(x, n) + + Unsigned right bit shift operator. + ``` + """ Base.(:(>>>)) + + @doc doc""" + ```rst + :(start[, step], stop) + + Range operator. "a:b" constructs a range from "a" to "b" with + a step size of 1, and "a:s:b" is similar but uses a step size of + "s". These syntaxes call the function "colon". The colon is + also used in indexing to select whole dimensions. + ``` + """ Base.(:(:)) + + @doc doc""" + ```rst + colon(start[, step], stop) + + Called by ":" syntax for constructing ranges. + ``` + """ Base.colon + + @doc doc""" + ```rst + range(start[, step], length) + + Construct a range by length, given a starting value and optional + step (defaults to 1). + ``` + """ Base.range + + @doc doc""" + ```rst + ==(x, y) + + Generic equality operator, giving a single "Bool" result. Falls + back to "===". Should be implemented for all types with a notion + of equality, based on the abstract value that an instance + represents. For example, all numeric types are compared by numeric + value, ignoring type. Strings are compared as sequences of + characters, ignoring encoding. + + Follows IEEE semantics for floating-point numbers. + + Collections should generally implement "==" by calling "==" + recursively on all contents. + + New numeric types should implement this function for two arguments + of the new type, and handle comparison to other types via promotion + rules where possible. + ``` + """ Base.(:(==)) + + @doc doc""" + ```rst + !=(x, y) +≠(x, y) + + Not-equals comparison operator. Always gives the opposite answer as + "==". New types should generally not implement this, and rely on + the fallback definition "!=(x,y) = !(x==y)" instead. + ``` + """ Base.(:(!=)) + + @doc doc""" + ```rst + ===(x, y) +≡(x, y) + + See the "is()" operator + ``` + """ Base.(:(===)) + + @doc doc""" + ```rst + !==(x, y) +≢(x, y) + + Equivalent to "!is(x, y)" + ``` + """ Base.(:(!==)) + + @doc doc""" + ```rst + <(x, y) + + Less-than comparison operator. New numeric types should implement + this function for two arguments of the new type. Because of the + behavior of floating-point NaN values, "<" implements a partial + order. Types with a canonical partial order should implement "<", + and types with a canonical total order should implement "isless". + ``` + """ Base.(:(<)) + + @doc doc""" + ```rst + <=(x, y) +≤(x, y) + + Less-than-or-equals comparison operator. + ``` + """ Base.(:(<=)) + + @doc doc""" + ```rst + >(x, y) + + Greater-than comparison operator. Generally, new types should + implement "<" instead of this function, and rely on the fallback + definition ">(x,y) = y)) + + @doc doc""" + ```rst + >=(x, y) +≥(x, y) + + Greater-than-or-equals comparison operator. + ``` + """ Base.(:(>=)) + + @doc doc""" + ```rst + .==(x, y) + + Element-wise equality comparison operator. + ``` + """ Base.(:(.==)) + + @doc doc""" + ```rst + .!=(x, y) +.≠(x, y) + + Element-wise not-equals comparison operator. + ``` + """ Base.(:(.!=)) + + @doc doc""" + ```rst + .<(x, y) + + Element-wise less-than comparison operator. + ``` + """ Base.(:(.<)) + + @doc doc""" + ```rst + .<=(x, y) +.≤(x, y) + + Element-wise less-than-or-equals comparison operator. + ``` + """ Base.(:(.<=)) + + @doc doc""" + ```rst + .>(x, y) + + Element-wise greater-than comparison operator. + ``` + """ Base.(:(.>)) + + @doc doc""" + ```rst + .>=(x, y) +.≥(x, y) + + Element-wise greater-than-or-equals comparison operator. + ``` + """ Base.(:(.>=)) + + @doc doc""" + ```rst + cmp(x, y) + + Return -1, 0, or 1 depending on whether "x" is less than, equal + to, or greater than "y", respectively. Uses the total order + implemented by "isless". For floating-point numbers, uses "<" + but throws an error for unordered arguments. + ``` + """ Base.cmp + + @doc doc""" + ```rst + ~(x) + + Bitwise not + ``` + """ Base.(:(~)) + + @doc doc""" + ```rst + &(x, y) + + Bitwise and + ``` + """ Base.(:(&)) + + @doc doc""" + ```rst + |(x, y) + + Bitwise or + ``` + """ Base.(:(|)) + + @doc doc""" + ```rst + \$(x, y) + + Bitwise exclusive or + ``` + """ Base.(:($)) + + @doc doc""" + ```rst + !(x) + + Boolean not + ``` + """ Base.(:(!)) + + @doc doc""" + ```rst + A_ldiv_Bc(a, b) + + Matrix operator A \ B^H + ``` + """ Base.A_ldiv_Bc + + @doc doc""" + ```rst + A_ldiv_Bt(a, b) + + Matrix operator A \ B^T + ``` + """ Base.A_ldiv_Bt + + @doc doc""" + ```rst + A_mul_B!(Y, A, B) -> Y + + Calculates the matrix-matrix or matrix-vector product *A B* and + stores the result in *Y*, overwriting the existing value of *Y*. + + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); + + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 + ``` + """ Base.A_mul_B! + + @doc doc""" + ```rst + A_mul_Bc(...) + + Matrix operator A B^H + ``` + """ Base.A_mul_Bc + + @doc doc""" + ```rst + A_mul_Bt(...) + + Matrix operator A B^T + ``` + """ Base.A_mul_Bt + + @doc doc""" + ```rst + A_rdiv_Bc(...) + + Matrix operator A / B^H + ``` + """ Base.A_rdiv_Bc + + @doc doc""" + ```rst + A_rdiv_Bt(a, b) + + Matrix operator A / B^T + ``` + """ Base.A_rdiv_Bt + + @doc doc""" + ```rst + Ac_ldiv_B(...) + + Matrix operator A^H \ B + ``` + """ Base.Ac_ldiv_B + + @doc doc""" + ```rst + Ac_ldiv_Bc(...) + + Matrix operator A^H \ B^H + ``` + """ Base.Ac_ldiv_Bc + + @doc doc""" + ```rst + Ac_mul_B(...) + + Matrix operator A^H B + ``` + """ Base.Ac_mul_B + + @doc doc""" + ```rst + Ac_mul_Bc(...) + + Matrix operator A^H B^H + ``` + """ Base.Ac_mul_Bc + + @doc doc""" + ```rst + Ac_rdiv_B(a, b) + + Matrix operator A^H / B + ``` + """ Base.Ac_rdiv_B + + @doc doc""" + ```rst + Ac_rdiv_Bc(a, b) + + Matrix operator A^H / B^H + ``` + """ Base.Ac_rdiv_Bc + + @doc doc""" + ```rst + At_ldiv_B(...) + + Matrix operator A^T \ B + ``` + """ Base.At_ldiv_B + + @doc doc""" + ```rst + At_ldiv_Bt(...) + + Matrix operator A^T \ B^T + ``` + """ Base.At_ldiv_Bt + + @doc doc""" + ```rst + At_mul_B(...) + + Matrix operator A^T B + ``` + """ Base.At_mul_B + + @doc doc""" + ```rst + At_mul_Bt(...) + + Matrix operator A^T B^T + ``` + """ Base.At_mul_Bt + + @doc doc""" + ```rst + At_rdiv_B(a, b) + + Matrix operator A^T / B + ``` + """ Base.At_rdiv_B + + @doc doc""" + ```rst + At_rdiv_Bt(a, b) + + Matrix operator A^T / B^T + ``` + """ Base.At_rdiv_Bt + + @doc doc""" + ```rst + isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + + Inexact equality comparison - behaves slightly different depending + on types of input args: + + * For "FloatingPoint" numbers, "isapprox" returns "true" if + "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". + + * For "Integer" and "Rational" numbers, "isapprox" returns + "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. + If one of "x" and "y" is "FloatingPoint", the other is + promoted, and the method above is called instead. + + * For "Complex" numbers, the distance in the complex plane is + compared, using the same criterion as above. + + For default tolerance arguments, "maxeps = max(eps(abs(x)), + eps(abs(y)))". + ``` + """ Base.isapprox + + @doc doc""" + ```rst + sin(x) + + Compute sine of "x", where "x" is in radians + ``` + """ Base.sin + + @doc doc""" + ```rst + cos(x) + + Compute cosine of "x", where "x" is in radians + ``` + """ Base.cos + + @doc doc""" + ```rst + tan(x) + + Compute tangent of "x", where "x" is in radians + ``` + """ Base.tan + + @doc doc""" + ```rst + sind(x) + + Compute sine of "x", where "x" is in degrees + ``` + """ Base.sind + + @doc doc""" + ```rst + cosd(x) + + Compute cosine of "x", where "x" is in degrees + ``` + """ Base.cosd + + @doc doc""" + ```rst + tand(x) + + Compute tangent of "x", where "x" is in degrees + ``` + """ Base.tand + + @doc doc""" + ```rst + sinpi(x) + + Compute \sin(\pi x) more accurately than "sin(pi*x)", + especially for large "x". + ``` + """ Base.sinpi + + @doc doc""" + ```rst + cospi(x) + + Compute \cos(\pi x) more accurately than "cos(pi*x)", + especially for large "x". + ``` + """ Base.cospi + + @doc doc""" + ```rst + sinh(x) + + Compute hyperbolic sine of "x" + ``` + """ Base.sinh + + @doc doc""" + ```rst + cosh(x) + + Compute hyperbolic cosine of "x" + ``` + """ Base.cosh + + @doc doc""" + ```rst + tanh(x) + + Compute hyperbolic tangent of "x" + ``` + """ Base.tanh + + @doc doc""" + ```rst + asin(x) + + Compute the inverse sine of "x", where the output is in radians + ``` + """ Base.asin + + @doc doc""" + ```rst + acos(x) + + Compute the inverse cosine of "x", where the output is in radians + ``` + """ Base.acos + + @doc doc""" + ```rst + atan(x) + + Compute the inverse tangent of "x", where the output is in + radians + ``` + """ Base.atan + + @doc doc""" + ```rst + atan2(y, x) + + Compute the inverse tangent of "y/x", using the signs of both + "x" and "y" to determine the quadrant of the return value. + ``` + """ Base.atan2 + + @doc doc""" + ```rst + asind(x) + + Compute the inverse sine of "x", where the output is in degrees + ``` + """ Base.asind + + @doc doc""" + ```rst + acosd(x) + + Compute the inverse cosine of "x", where the output is in degrees + ``` + """ Base.acosd + + @doc doc""" + ```rst + atand(x) + + Compute the inverse tangent of "x", where the output is in + degrees + ``` + """ Base.atand + + @doc doc""" + ```rst + sec(x) + + Compute the secant of "x", where "x" is in radians + ``` + """ Base.sec + + @doc doc""" + ```rst + csc(x) + + Compute the cosecant of "x", where "x" is in radians + ``` + """ Base.csc + + @doc doc""" + ```rst + cot(x) + + Compute the cotangent of "x", where "x" is in radians + ``` + """ Base.cot + + @doc doc""" + ```rst + secd(x) + + Compute the secant of "x", where "x" is in degrees + ``` + """ Base.secd + + @doc doc""" + ```rst + cscd(x) + + Compute the cosecant of "x", where "x" is in degrees + ``` + """ Base.cscd + + @doc doc""" + ```rst + cotd(x) + + Compute the cotangent of "x", where "x" is in degrees + ``` + """ Base.cotd + + @doc doc""" + ```rst + asec(x) + + Compute the inverse secant of "x", where the output is in radians + ``` + """ Base.asec + + @doc doc""" + ```rst + acsc(x) + + Compute the inverse cosecant of "x", where the output is in + radians + ``` + """ Base.acsc + + @doc doc""" + ```rst + acot(x) + + Compute the inverse cotangent of "x", where the output is in + radians + ``` + """ Base.acot + + @doc doc""" + ```rst + asecd(x) + + Compute the inverse secant of "x", where the output is in degrees + ``` + """ Base.asecd + + @doc doc""" + ```rst + acscd(x) + + Compute the inverse cosecant of "x", where the output is in + degrees + ``` + """ Base.acscd + + @doc doc""" + ```rst + acotd(x) + + Compute the inverse cotangent of "x", where the output is in + degrees + ``` + """ Base.acotd + + @doc doc""" + ```rst + sech(x) + + Compute the hyperbolic secant of "x" + ``` + """ Base.sech + + @doc doc""" + ```rst + csch(x) + + Compute the hyperbolic cosecant of "x" + ``` + """ Base.csch + + @doc doc""" + ```rst + coth(x) + + Compute the hyperbolic cotangent of "x" + ``` + """ Base.coth + + @doc doc""" + ```rst + asinh(x) + + Compute the inverse hyperbolic sine of "x" + ``` + """ Base.asinh + + @doc doc""" + ```rst + acosh(x) + + Compute the inverse hyperbolic cosine of "x" + ``` + """ Base.acosh + + @doc doc""" + ```rst + atanh(x) + + Compute the inverse hyperbolic tangent of "x" + ``` + """ Base.atanh + + @doc doc""" + ```rst + asech(x) + + Compute the inverse hyperbolic secant of "x" + ``` + """ Base.asech + + @doc doc""" + ```rst + acsch(x) + + Compute the inverse hyperbolic cosecant of "x" + ``` + """ Base.acsch + + @doc doc""" + ```rst + acoth(x) + + Compute the inverse hyperbolic cotangent of "x" + ``` + """ Base.acoth + + @doc doc""" + ```rst + sinc(x) + + Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. + ``` + """ Base.sinc + + @doc doc""" + ```rst + cosc(x) + + Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq + 0, and 0 if x = 0. This is the derivative of "sinc(x)". + ``` + """ Base.cosc + + @doc doc""" + ```rst + deg2rad(x) + + Convert "x" from degrees to radians + ``` + """ Base.deg2rad + + @doc doc""" + ```rst + rad2deg(x) + + Convert "x" from radians to degrees + ``` + """ Base.rad2deg + + @doc doc""" + ```rst + hypot(x, y) + + Compute the \sqrt{x^2+y^2} avoiding overflow and underflow + ``` + """ Base.hypot + + @doc doc""" + ```rst + log(x) + + Compute the natural logarithm of "x". Throws "DomainError" for + negative "Real" arguments. Use complex negative arguments to + obtain complex results. + + There is an experimental variant in the "Base.Math.JuliaLibm" + module, which is typically faster and more accurate. + ``` + """ Base.log + + @doc doc""" + ```rst + log(b, x) + + Compute the base "b" logarithm of "x". Throws "DomainError" + for negative "Real" arguments. + ``` + """ Base.log + + @doc doc""" + ```rst + log2(x) + + Compute the logarithm of "x" to base 2. Throws "DomainError" + for negative "Real" arguments. + ``` + """ Base.log2 + + @doc doc""" + ```rst + log10(x) + + Compute the logarithm of "x" to base 10. Throws "DomainError" + for negative "Real" arguments. + ``` + """ Base.log10 + + @doc doc""" + ```rst + log1p(x) + + Accurate natural logarithm of "1+x". Throws "DomainError" for + "Real" arguments less than -1. + + There is an experimental variant in the "Base.Math.JuliaLibm" + module, which is typically faster and more accurate. + ``` + """ Base.log1p + + @doc doc""" + ```rst + frexp(val) + + Return "(x,exp)" such that "x" has a magnitude in the interval + "[1/2, 1)" or 0, and val = x \times 2^{exp}. + ``` + """ Base.frexp + + @doc doc""" + ```rst + exp(x) + + Compute e^x + ``` + """ Base.exp + + @doc doc""" + ```rst + exp2(x) + + Compute 2^x + ``` + """ Base.exp2 + + @doc doc""" + ```rst + exp10(x) + + Compute 10^x + ``` + """ Base.exp10 + + @doc doc""" + ```rst + ldexp(x, n) + + Compute x \times 2^n + ``` + """ Base.ldexp + + @doc doc""" + ```rst + modf(x) + + Return a tuple (fpart,ipart) of the fractional and integral parts + of a number. Both parts have the same sign as the argument. + ``` + """ Base.modf + + @doc doc""" + ```rst + expm1(x) + + Accurately compute e^x-1 + ``` + """ Base.expm1 + + @doc doc""" + ```rst + round([T], x[, digits[, base]][, r::RoundingMode]) + + "round(x)" rounds "x" to an integer value according to the + default rounding mode (see "get_rounding()"), returning a value + of the same type as "x". By default ("RoundNearest"), this will + round to the nearest integer, with ties (fractional values of 0.5) + being rounded to the even integer. + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional "RoundingMode" argument will change how the number + gets rounded. + + "round(T, x, [r::RoundingMode])" converts the result to type + "T", throwing an "InexactError" if the value is not + representable. + + "round(x, digits)" rounds to the specified number of digits after + the decimal place (or before if negative). "round(x, digits, + base)" rounds using a base other than 10. + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the "Float64" value represented by "1.15" is + actually *less* than 1.15, yet will be rounded to 1.2. + + julia> x = 1.15 + 1.15 + + julia> @sprintf "%.20f" x + "1.14999999999999991118" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + ``` + """ Base.round + + @doc doc""" + ```rst + RoundingMode + + A type which controls rounding behavior. Currently supported + rounding modes are: + + * "RoundNearest" (default) + + * "RoundNearestTiesAway" + + * "RoundNearestTiesUp" + + * "RoundToZero" + + * "RoundUp" + + * "RoundDown" + ``` + """ Base.RoundingMode + + @doc doc""" + ```rst + RoundNearest + + The default rounding mode. Rounds to the nearest integer, with ties + (fractional values of 0.5) being rounded to the nearest even + integer. + ``` + """ Base.RoundNearest + + @doc doc""" + ```rst + RoundNearestTiesAway + + Rounds to nearest integer, with ties rounded away from zero (C/C++ + "round()" behaviour). + ``` + """ Base.RoundNearestTiesAway + + @doc doc""" + ```rst + RoundNearestTiesUp + + Rounds to nearest integer, with ties rounded toward positive + infinity (Java/JavaScript "round()" behaviour). + ``` + """ Base.RoundNearestTiesUp + + @doc doc""" + ```rst + RoundToZero + + "round()" using this rounding mode is an alias for "trunc()". + ``` + """ Base.RoundToZero + + @doc doc""" + ```rst + RoundUp + + "round()" using this rounding mode is an alias for "ceil()". + ``` + """ Base.RoundUp + + @doc doc""" + ```rst + RoundDown + + "round()" using this rounding mode is an alias for "floor()". + ``` + """ Base.RoundDown + + @doc doc""" + ```rst + round(z, RoundingModeReal, RoundingModeImaginary) + + Returns the nearest integral value of the same type as the complex- + valued "z" to "z", breaking ties using the specified + "RoundingMode"s. The first "RoundingMode" is used for rounding + the real components while the second is used for rounding the + imaginary components. + ``` + """ Base.round + + @doc doc""" + ```rst + ceil([T], x[, digits[, base]]) + + "ceil(x)" returns the nearest integral value of the same type as + "x" that is greater than or equal to "x". + + "ceil(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". + ``` + """ Base.ceil + + @doc doc""" + ```rst + floor([T], x[, digits[, base]]) + + "floor(x)" returns the nearest integral value of the same type as + "x" that is less than or equal to "x". + + "floor(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". + ``` + """ Base.floor + + @doc doc""" + ```rst + trunc([T], x[, digits[, base]]) + + "trunc(x)" returns the nearest integral value of the same type as + "x" whose absolute value is less than or equal to "x". + + "trunc(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". + ``` + """ Base.trunc + + @doc doc""" + ```rst + unsafe_trunc(T, x) + + "unsafe_trunc(T, x)" returns the nearest integral value of type + "T" whose absolute value is less than or equal to "x". If the + value is not representable by "T", an arbitrary value will be + returned. + ``` + """ Base.unsafe_trunc + + @doc doc""" + ```rst + signif(x, digits[, base]) + + Rounds (in the sense of "round") "x" so that there are + "digits" significant digits, under a base "base" + representation, default 10. E.g., "signif(123.456, 2)" is + "120.0", and "signif(357.913, 4, 2)" is "352.0". + ``` + """ Base.signif + + @doc doc""" + ```rst + min(x, y, ...) + + Return the minimum of the arguments. Operates elementwise over + arrays. + ``` + """ Base.min + + @doc doc""" + ```rst + max(x, y, ...) + + Return the maximum of the arguments. Operates elementwise over + arrays. + ``` + """ Base.max + + @doc doc""" + ```rst + minmax(x, y) + + Return "(min(x,y), max(x,y))". See also: "extrema()" that + returns "(minimum(x), maximum(x))" + ``` + """ Base.minmax + + @doc doc""" + ```rst + clamp(x, lo, hi) + + Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x + > hi", return "hi". Arguments are promoted to a common type. + Operates elementwise over "x" if it is an array. + ``` + """ Base.clamp + + @doc doc""" + ```rst + abs(x) + + Absolute value of "x" + ``` + """ Base.abs + + @doc doc""" + ```rst + abs2(x) + + Squared absolute value of "x" + ``` + """ Base.abs2 + + @doc doc""" + ```rst + copysign(x, y) + + Return "x" such that it has the same sign as "y" + ``` + """ Base.copysign + + @doc doc""" + ```rst + sign(x) + + Return "+1" if "x" is positive, "0" if "x == 0", and "-1" + if "x" is negative. + ``` + """ Base.sign + + @doc doc""" + ```rst + signbit(x) + + Returns "true" if the value of the sign of "x" is negative, + otherwise "false". + ``` + """ Base.signbit + + @doc doc""" + ```rst + flipsign(x, y) + + Return "x" with its sign flipped if "y" is negative. For + example "abs(x) = flipsign(x,x)". + ``` + """ Base.flipsign + + @doc doc""" + ```rst + sqrt(x) + + Return \sqrt{x}. Throws "DomainError" for negative "Real" + arguments. Use complex negative arguments instead. The prefix + operator "√" is equivalent to "sqrt". + ``` + """ Base.sqrt + + @doc doc""" + ```rst + isqrt(n) + + Integer square root: the largest integer "m" such that "m*m <= + n". + ``` + """ Base.isqrt + + @doc doc""" + ```rst + cbrt(x) + + Return x^{1/3}. The prefix operator "∛" is equivalent to + "cbrt". + ``` + """ Base.cbrt + + @doc doc""" + ```rst + erf(x) + + Compute the error function of "x", defined by + \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex + "x". + ``` + """ Base.erf + + @doc doc""" + ```rst + erfc(x) + + Compute the complementary error function of "x", defined by 1 - + \operatorname{erf}(x). + ``` + """ Base.erfc + + @doc doc""" + ```rst + erfcx(x) + + Compute the scaled complementary error function of "x", defined + by e^{x^2} \operatorname{erfc}(x). Note also that + \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). + ``` + """ Base.erfcx + + @doc doc""" + ```rst + erfi(x) + + Compute the imaginary error function of "x", defined by -i + \operatorname{erf}(ix). + ``` + """ Base.erfi + + @doc doc""" + ```rst + dawson(x) + + Compute the Dawson function (scaled imaginary error function) of + "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} + \operatorname{erfi}(x). + ``` + """ Base.dawson + + @doc doc""" + ```rst + erfinv(x) + + Compute the inverse error function of a real "x", defined by + \operatorname{erf}(\operatorname{erfinv}(x)) = x. + ``` + """ Base.erfinv + + @doc doc""" + ```rst + erfcinv(x) + + Compute the inverse error complementary function of a real "x", + defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. + ``` + """ Base.erfcinv + + @doc doc""" + ```rst + real(z) + + Return the real part of the complex number "z" + ``` + """ Base.real + + @doc doc""" + ```rst + imag(z) + + Return the imaginary part of the complex number "z" + ``` + """ Base.imag + + @doc doc""" + ```rst + reim(z) + + Return both the real and imaginary parts of the complex number + "z" + ``` + """ Base.reim + + @doc doc""" + ```rst + conj(z) + + Compute the complex conjugate of a complex number "z" + ``` + """ Base.conj + + @doc doc""" + ```rst + angle(z) + + Compute the phase angle in radians of a complex number "z" + ``` + """ Base.angle + + @doc doc""" + ```rst + cis(z) + + Return \exp(iz). + ``` + """ Base.cis + + @doc doc""" + ```rst + binomial(n, k) + + Number of ways to choose "k" out of "n" items + ``` + """ Base.binomial + + @doc doc""" + ```rst + factorial(n) + + Factorial of "n". If "n" is an "Integer", the factorial is + computed as an integer (promoted to at least 64 bits). Note that + this may overflow if "n" is not small, but you can use + "factorial(big(n))" to compute the result exactly in arbitrary + precision. If "n" is not an "Integer", "factorial(n)" is + equivalent to "gamma(n+1)". + ``` + """ Base.factorial + + @doc doc""" + ```rst + factorial(n, k) + + Compute "factorial(n)/factorial(k)" + ``` + """ Base.factorial + + @doc doc""" + ```rst + factor(n) -> Dict + + Compute the prime factorization of an integer "n". Returns a + dictionary. The keys of the dictionary correspond to the factors, + and hence are of the same type as "n". The value associated with + each key indicates the number of times the factor appears in the + factorization. + + julia> factor(100) # == 2*2*5*5 + Dict{Int64,Int64} with 2 entries: + 2 => 2 + 5 => 2 + ``` + """ Base.factor + + @doc doc""" + ```rst + gcd(x, y) + + Greatest common (positive) divisor (or zero if x and y are both + zero). + ``` + """ Base.gcd + + @doc doc""" + ```rst + lcm(x, y) + + Least common (non-negative) multiple. + ``` + """ Base.lcm + + @doc doc""" + ```rst + gcdx(x, y) + + Computes the greatest common (positive) divisor of "x" and "y" + and their Bézout coefficients, i.e. the integer coefficients "u" + and "v" that satisfy ux+vy = d = gcd(x,y). + + julia> gcdx(12, 42) + (6,-3,1) + + julia> gcdx(240, 46) + (2,-9,47) + + Note: Bézout coefficients are *not* uniquely defined. "gcdx" + returns the minimal Bézout coefficients that are computed by the + extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, + Algorithm X.) These coefficients "u" and "v" are minimal in + the sense that |u| < |\frac y d and |v| < |\frac x d. + Furthermore, the signs of "u" and "v" are chosen so that + "d" is positive. + ``` + """ Base.gcdx + + @doc doc""" + ```rst + ispow2(n) -> Bool + + Test whether "n" is a power of two + ``` + """ Base.ispow2 + + @doc doc""" + ```rst + nextpow2(n) + + The smallest power of two not less than "n". Returns 0 for + "n==0", and returns "-nextpow2(-n)" for negative arguments. + ``` + """ Base.nextpow2 + + @doc doc""" + ```rst + prevpow2(n) + + The largest power of two not greater than "n". Returns 0 for + "n==0", and returns "-prevpow2(-n)" for negative arguments. + ``` + """ Base.prevpow2 + + @doc doc""" + ```rst + nextpow(a, x) + + The smallest "a^n" not less than "x", where "n" is a non- + negative integer. "a" must be greater than 1, and "x" must be + greater than 0. + ``` + """ Base.nextpow + + @doc doc""" + ```rst + prevpow(a, x) + + The largest "a^n" not greater than "x", where "n" is a non- + negative integer. "a" must be greater than 1, and "x" must not + be less than 1. + ``` + """ Base.prevpow + + @doc doc""" + ```rst + nextprod([k_1, k_2, ...], n) + + Next integer not less than "n" that can be written as \prod + k_i^{p_i} for integers p_1, p_2, etc. + ``` + """ Base.nextprod + + @doc doc""" + ```rst + prevprod([k_1, k_2, ...], n) + + Previous integer not greater than "n" that can be written as + \prod k_i^{p_i} for integers p_1, p_2, etc. + ``` + """ Base.prevprod + + @doc doc""" + ```rst + invmod(x, m) + + Take the inverse of "x" modulo "m": "y" such that xy = 1 + \pmod m + ``` + """ Base.invmod + + @doc doc""" + ```rst + powermod(x, p, m) + + Compute x^p \pmod m + ``` + """ Base.powermod + + @doc doc""" + ```rst + gamma(x) + + Compute the gamma function of "x" + ``` + """ Base.gamma + + @doc doc""" + ```rst + lgamma(x) + + Compute the logarithm of the absolute value of "gamma()" for + "Real" "x", while for "Complex" "x" it computes the + logarithm of "gamma(x)". + ``` + """ Base.lgamma + + @doc doc""" + ```rst + lfact(x) + + Compute the logarithmic factorial of "x" + ``` + """ Base.lfact + + @doc doc""" + ```rst + digamma(x) + + Compute the digamma function of "x" (the logarithmic derivative + of "gamma(x)") + ``` + """ Base.digamma + + @doc doc""" + ```rst + invdigamma(x) + + Compute the inverse digamma function of "x". + ``` + """ Base.invdigamma + + @doc doc""" + ```rst + trigamma(x) + + Compute the trigamma function of "x" (the logarithmic second + derivative of "gamma(x)") + ``` + """ Base.trigamma + + @doc doc""" + ```rst + polygamma(m, x) + + Compute the polygamma function of order "m" of argument "x" + (the "(m+1)th" derivative of the logarithm of "gamma(x)") + ``` + """ Base.polygamma + + @doc doc""" + ```rst + airy(k, x) + + kth derivative of the Airy function \operatorname{Ai}(x). + ``` + """ Base.airy + + @doc doc""" + ```rst + airyai(x) + + Airy function \operatorname{Ai}(x). + ``` + """ Base.airyai + + @doc doc""" + ```rst + airyprime(x) + + Airy function derivative \operatorname{Ai}'(x). + ``` + """ Base.airyprime + + @doc doc""" + ```rst + airyaiprime(x) + + Airy function derivative \operatorname{Ai}'(x). + ``` + """ Base.airyaiprime + + @doc doc""" + ```rst + airybi(x) + + Airy function \operatorname{Bi}(x). + ``` + """ Base.airybi + + @doc doc""" + ```rst + airybiprime(x) + + Airy function derivative \operatorname{Bi}'(x). + ``` + """ Base.airybiprime + + @doc doc""" + ```rst + airyx(k, x) + + scaled kth derivative of the Airy function, return + \operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || + k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} + \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || + k == 3". + ``` + """ Base.airyx + + @doc doc""" + ```rst + besselj0(x) + + Bessel function of the first kind of order 0, J_0(x). + ``` + """ Base.besselj0 + + @doc doc""" + ```rst + besselj1(x) + + Bessel function of the first kind of order 1, J_1(x). + ``` + """ Base.besselj1 + + @doc doc""" + ```rst + besselj(nu, x) + + Bessel function of the first kind of order "nu", J_\nu(x). + ``` + """ Base.besselj + + @doc doc""" + ```rst + besseljx(nu, x) + + Scaled Bessel function of the first kind of order "nu", J_\nu(x) + e^{- | \operatorname{Im}(x) |}. + ``` + """ Base.besseljx + + @doc doc""" + ```rst + bessely0(x) + + Bessel function of the second kind of order 0, Y_0(x). + ``` + """ Base.bessely0 + + @doc doc""" + ```rst + bessely1(x) + + Bessel function of the second kind of order 1, Y_1(x). + ``` + """ Base.bessely1 + + @doc doc""" + ```rst + bessely(nu, x) + + Bessel function of the second kind of order "nu", Y_\nu(x). + ``` + """ Base.bessely + + @doc doc""" + ```rst + besselyx(nu, x) + + Scaled Bessel function of the second kind of order "nu", + Y_\nu(x) e^{- | \operatorname{Im}(x) |}. + ``` + """ Base.besselyx + + @doc doc""" + ```rst + hankelh1(nu, x) + + Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). + ``` + """ Base.hankelh1 + + @doc doc""" + ```rst + hankelh1x(nu, x) + + Scaled Bessel function of the third kind of order "nu", + H^{(1)}_\nu(x) e^{-x i}. + ``` + """ Base.hankelh1x + + @doc doc""" + ```rst + hankelh2(nu, x) + + Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). + ``` + """ Base.hankelh2 + + @doc doc""" + ```rst + hankelh2x(nu, x) + + Scaled Bessel function of the third kind of order "nu", + H^{(2)}_\nu(x) e^{x i}. + ``` + """ Base.hankelh2x + + @doc doc""" + ```rst + besselh(nu, k, x) + + Bessel function of the third kind of order "nu" (Hankel + function). "k" is either 1 or 2, selecting "hankelh1" or + "hankelh2", respectively. + ``` + """ Base.besselh + + @doc doc""" + ```rst + besseli(nu, x) + + Modified Bessel function of the first kind of order "nu", + I_\nu(x). + ``` + """ Base.besseli + + @doc doc""" + ```rst + besselix(nu, x) + + Scaled modified Bessel function of the first kind of order "nu", + I_\nu(x) e^{- | \operatorname{Re}(x) |}. + ``` + """ Base.besselix + + @doc doc""" + ```rst + besselk(nu, x) + + Modified Bessel function of the second kind of order "nu", + K_\nu(x). + ``` + """ Base.besselk + + @doc doc""" + ```rst + besselkx(nu, x) + + Scaled modified Bessel function of the second kind of order "nu", + K_\nu(x) e^x. + ``` + """ Base.besselkx + + @doc doc""" + ```rst + beta(x, y) + + Euler integral of the first kind \operatorname{B}(x,y) = + \Gamma(x)\Gamma(y)/\Gamma(x+y). + ``` + """ Base.beta + + @doc doc""" + ```rst + lbeta(x, y) + + Natural logarithm of the absolute value of the beta function + \log(|\operatorname{B}(x,y)|). + ``` + """ Base.lbeta + + @doc doc""" + ```rst + eta(x) + + Dirichlet eta function \eta(s) = + \sum^\infty_{n=1}(-)^{n-1}/n^{s}. + ``` + """ Base.eta + + @doc doc""" + ```rst + zeta(s) + + Riemann zeta function \zeta(s). + ``` + """ Base.zeta + + @doc doc""" + ```rst + zeta(s, z) + + Hurwitz zeta function \zeta(s, z). (This is equivalent to the + Riemann zeta function \zeta(s) for the case of "z=1".) + ``` + """ Base.zeta + + @doc doc""" + ```rst + ndigits(n, b) + + Compute the number of digits in number "n" written in base "b". + ``` + """ Base.ndigits + + @doc doc""" + ```rst + widemul(x, y) + + Multiply "x" and "y", giving the result as a larger type. + ``` + """ Base.widemul + + @doc doc""" + ```rst + @evalpoly(z, c...) + + Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients + "c[1]", "c[2]", ...; that is, the coefficients are given in + ascending order by power of "z". This macro expands to efficient + inline code that uses either Horner's method or, for complex "z", + a more efficient Goertzel-like algorithm. + ``` + """ Base.@evalpoly + + @doc doc""" + ```rst + mean(v[, region]) + + Compute the mean of whole array "v", or optionally along the + dimensions in "region". Note: Julia does not ignore "NaN" + values in the computation. For applications requiring the handling + of missing data, the "DataArray" package is recommended. + ``` + """ Base.mean + + @doc doc""" + ```rst + mean!(r, v) + + Compute the mean of "v" over the singleton dimensions of "r", + and write results to "r". + ``` + """ Base.mean! + + @doc doc""" + ```rst + std(v[, region]) + + Compute the sample standard deviation of a vector or array "v", + optionally along dimensions in "region". The algorithm returns an + estimator of the generative distribution's standard deviation under + the assumption that each entry of "v" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". + Note: Julia does not ignore "NaN" values in the computation. For + applications requiring the handling of missing data, the + "DataArray" package is recommended. + ``` + """ Base.std + + @doc doc""" + ```rst + stdm(v, m) + + Compute the sample standard deviation of a vector "v" with known + mean "m". Note: Julia does not ignore "NaN" values in the + computation. + ``` + """ Base.stdm + + @doc doc""" + ```rst + var(v[, region]) + + Compute the sample variance of a vector or array "v", optionally + along dimensions in "region". The algorithm will return an + estimator of the generative distribution's variance under the + assumption that each entry of "v" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: + Julia does not ignore "NaN" values in the computation. For + applications requiring the handling of missing data, the + "DataArray" package is recommended. + ``` + """ Base.var + + @doc doc""" + ```rst + varm(v, m) + + Compute the sample variance of a vector "v" with known mean + "m". Note: Julia does not ignore "NaN" values in the + computation. + ``` + """ Base.varm + + @doc doc""" + ```rst + middle(x) + + Compute the middle of a scalar value, which is equivalent to "x" + itself, but of the type of "middle(x, x)" for consistency. + ``` + """ Base.middle + + @doc doc""" + ```rst + middle(x, y) + + Compute the middle of two reals "x" and "y", which is + equivalent in both value and type to computing their mean ("(x + + y) / 2"). + ``` + """ Base.middle + + @doc doc""" + ```rst + middle(range) + + Compute the middle of a range, which consists in computing the mean + of its extrema. Since a range is sorted, the mean is performed with + the first and last element. + ``` + """ Base.middle + + @doc doc""" + ```rst + middle(array) + + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. + ``` + """ Base.middle + + @doc doc""" + ```rst + median(v) + + Compute the median of a vector "v". "NaN" is returned if the + data contains any "NaN" values. For applications requiring the + handling of missing data, the "DataArrays" package is + recommended. + ``` + """ Base.median + + @doc doc""" + ```rst + median!(v) + + Like "median", but may overwrite the input vector. + ``` + """ Base.median! + + @doc doc""" + ```rst + hist(v[, n]) -> e, counts + + Compute the histogram of "v", optionally using approximately + "n" bins. The return values are a range "e", which correspond + to the edges of the bins, and "counts" containing the number of + elements of "v" in each bin. Note: Julia does not ignore "NaN" + values in the computation. + ``` + """ Base.hist + + @doc doc""" + ```rst + hist(v, e) -> e, counts + + Compute the histogram of "v" using a vector/range "e" as the + edges for the bins. The result will be a vector of length + "length(e) - 1", such that the element at location "i" + satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not + ignore "NaN" values in the computation. + ``` + """ Base.hist + + @doc doc""" + ```rst + hist!(counts, v, e) -> e, counts + + Compute the histogram of "v", using a vector/range "e" as the + edges for the bins. This function writes the resultant counts to a + pre-allocated array "counts". + ``` + """ Base.hist! + + @doc doc""" + ```rst + hist2d(M, e1, e2) -> (edge1, edge2, counts) + + Compute a "2d histogram" of a set of N points specified by N-by-2 + matrix "M". Arguments "e1" and "e2" are bins for each + dimension, specified either as integer bin counts or vectors of bin + edges. The result is a tuple of "edge1" (the bin edges used in + the first dimension), "edge2" (the bin edges used in the second + dimension), and "counts", a histogram matrix of size + "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore + "NaN" values in the computation. + ``` + """ Base.hist2d + + @doc doc""" + ```rst + hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + + Compute a "2d histogram" with respect to the bins delimited by + the edges given in "e1" and "e2". This function writes the + results to a pre-allocated array "counts". + ``` + """ Base.hist2d! + + @doc doc""" + ```rst + histrange(v, n) + + Compute *nice* bin ranges for the edges of a histogram of "v", + using approximately "n" bins. The resulting step sizes will be 1, + 2 or 5 multiplied by a power of 10. Note: Julia does not ignore + "NaN" values in the computation. + ``` + """ Base.histrange + + @doc doc""" + ```rst + midpoints(e) + + Compute the midpoints of the bins with edges "e". The result is a + vector/range of length "length(e) - 1". Note: Julia does not + ignore "NaN" values in the computation. + ``` + """ Base.midpoints + + @doc doc""" + ```rst + quantile(v, p) + + Compute the quantiles of a vector "v" at a specified set of + probability values "p". Note: Julia does not ignore "NaN" + values in the computation. + ``` + """ Base.quantile + + @doc doc""" + ```rst + quantile(v, p) + + Compute the quantile of a vector "v" at the probability "p". + Note: Julia does not ignore "NaN" values in the computation. + ``` + """ Base.quantile + + @doc doc""" + ```rst + quantile!(v, p) + + Like "quantile", but overwrites the input vector. + ``` + """ Base.quantile! + + @doc doc""" + ```rst + cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + + Compute the Pearson covariance between the vector(s) in "v1" and + "v2". Here, "v1" and "v2" can be either vectors or matrices. + + This function accepts three keyword arguments: + + * "vardim": the dimension of variables. When "vardim = 1", + variables are considered in columns while observations in rows; + when "vardim = 2", variables are in rows while observations in + columns. By default, it is set to "1". + + * "corrected": whether to apply Bessel's correction (divide by + "n-1" instead of "n"). By default, it is set to "true". + + * "mean": allow users to supply mean values that are known. By + default, it is set to "nothing", which indicates that the + mean(s) are unknown, and the function will compute the mean. + Users can use "mean=0" to indicate that the input data are + centered, and hence there's no need to subtract the mean. + + The size of the result depends on the size of "v1" and "v2". + When both "v1" and "v2" are vectors, it returns the covariance + between them as a scalar. When either one is a matrix, it returns a + covariance matrix of size "(n1, n2)", where "n1" and "n2" are + the numbers of slices in "v1" and "v2", which depend on the + setting of "vardim". + + Note: "v2" can be omitted, which indicates "v2 = v1". + ``` + """ Base.cov + + @doc doc""" + ```rst + cor(v1[, v2][, vardim=1, mean=nothing]) + + Compute the Pearson correlation between the vector(s) in "v1" and + "v2". + + Users can use the keyword argument "vardim" to specify the + variable dimension, and "mean" to supply pre-computed mean + values. + ``` + """ Base.cor + + @doc doc""" + ```rst + fft(A[, dims]) + + Performs a multidimensional FFT of the array "A". The optional + "dims" argument specifies an iterable subset of dimensions (e.g. + an integer, range, tuple, or array) to transform along. Most + efficient if the size of "A" along the transformed dimensions is + a product of small primes; see "nextprod()". See also + "plan_fft()" for even greater efficiency. + + A one-dimensional FFT computes the one-dimensional discrete Fourier + transform (DFT) as defined by + + \operatorname{DFT}(A)[k] = + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(-i\frac{2\pi + (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. + + A multidimensional FFT simply performs this operation along each + transformed dimension of "A". + + Higher performance is usually possible with multi-threading. Use + *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* + processors. + ``` + """ Base.fft + + @doc doc""" + ```rst + fft!(A[, dims]) + + Same as "fft()", but operates in-place on "A", which must be an + array of complex floating-point numbers. + ``` + """ Base.fft! + + @doc doc""" + ```rst + ifft(A[, dims]) + + Multidimensional inverse FFT. + + A one-dimensional inverse FFT computes + + \operatorname{IDFT}(A)[k] = + \frac{1}{\operatorname{length}(A)} + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(+i\frac{2\pi (n-1)(k-1)} + {\operatorname{length}(A)} \right) A[n]. + + A multidimensional inverse FFT simply performs this operation along + each transformed dimension of "A". + ``` + """ Base.ifft + + @doc doc""" + ```rst + ifft!(A[, dims]) + + Same as "ifft()", but operates in-place on "A". + ``` + """ Base.ifft! + + @doc doc""" + ```rst + bfft(A[, dims]) + + Similar to "ifft()", but computes an unnormalized inverse + (backward) transform, which must be divided by the product of the + sizes of the transformed dimensions in order to obtain the inverse. + (This is slightly more efficient than "ifft()" because it omits a + scaling step, which in some applications can be combined with other + computational steps elsewhere.) + + \operatorname{BDFT}(A)[k] = \operatorname{length}(A) + \operatorname{IDFT}(A)[k] + ``` + """ Base.bfft + + @doc doc""" + ```rst + bfft!(A[, dims]) + + Same as "bfft()", but operates in-place on "A". + ``` + """ Base.bfft! + + @doc doc""" + ```rst + plan_fft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized FFT along given dimensions ("dims") of + arrays matching the shape and type of "A". (The first two + arguments have the same meaning as for "fft()".) Returns a + function "plan(A)" that computes "fft(A, dims)" quickly. + + The "flags" argument is a bitwise-or of FFTW planner flags, + defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or + "FFTW.PATIENT" will instead spend several seconds (or more) + benchmarking different possible FFT algorithms and picking the + fastest one; see the FFTW manual for more information on planner + flags. The optional "timelimit" argument specifies a rough upper + bound on the allowed planning time, in seconds. Passing + "FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array + "A" to be overwritten with zeros during plan creation. + + "plan_fft!()" is the same as "plan_fft()" but creates a plan + that operates in-place on its argument (which must be an array of + complex floating-point numbers). "plan_ifft()" and so on are + similar but produce plans that perform the equivalent of the + inverse transforms "ifft()" and so on. + ``` + """ Base.plan_fft + + @doc doc""" + ```rst + plan_ifft(A[, dims[, flags[, timelimit]]]) + + Same as "plan_fft()", but produces a plan that performs inverse + transforms "ifft()". + ``` + """ Base.plan_ifft + + @doc doc""" + ```rst + plan_bfft(A[, dims[, flags[, timelimit]]]) + + Same as "plan_fft()", but produces a plan that performs an + unnormalized backwards transform "bfft()". + ``` + """ Base.plan_bfft + + @doc doc""" + ```rst + plan_fft!(A[, dims[, flags[, timelimit]]]) + + Same as "plan_fft()", but operates in-place on "A". + ``` + """ Base.plan_fft! + + @doc doc""" + ```rst + plan_ifft!(A[, dims[, flags[, timelimit]]]) + + Same as "plan_ifft()", but operates in-place on "A". + ``` + """ Base.plan_ifft! + + @doc doc""" + ```rst + plan_bfft!(A[, dims[, flags[, timelimit]]]) + + Same as "plan_bfft()", but operates in-place on "A". + ``` + """ Base.plan_bfft! + + @doc doc""" + ```rst + rfft(A[, dims]) + + Multidimensional FFT of a real array A, exploiting the fact that + the transform has conjugate symmetry in order to save roughly half + the computational time and storage costs compared with "fft()". + If "A" has size "(n_1, ..., n_d)", the result has size + "(floor(n_1/2)+1, ..., n_d)". + + The optional "dims" argument specifies an iterable subset of one + or more dimensions of "A" to transform, similar to "fft()". + Instead of (roughly) halving the first dimension of "A" in the + result, the "dims[1]" dimension is (roughly) halved in the same + way. + ``` + """ Base.rfft + + @doc doc""" + ```rst + irfft(A, d[, dims]) + + Inverse of "rfft()": for a complex array "A", gives the + corresponding real array whose FFT yields "A" in the first half. + As for "rfft()", "dims" is an optional subset of dimensions to + transform, defaulting to "1:ndims(A)". + + "d" is the length of the transformed real array along the + "dims[1]" dimension, which must satisfy "d == + floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred + from "size(A)" due to the possibility of rounding by the + "floor" function here.) + ``` + """ Base.irfft + + @doc doc""" + ```rst + brfft(A, d[, dims]) + + Similar to "irfft()" but computes an unnormalized inverse + transform (similar to "bfft()"), which must be divided by the + product of the sizes of the transformed dimensions (of the real + output array) in order to obtain the inverse transform. + ``` + """ Base.brfft + + @doc doc""" + ```rst + plan_rfft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized real-input FFT, similar to "plan_fft()" + except for "rfft()" instead of "fft()". The first two + arguments, and the size of the transformed result, are the same as + for "rfft()". + ``` + """ Base.plan_rfft + + @doc doc""" + ```rst + plan_brfft(A, d[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized real-input unnormalized transform, similar to + "plan_rfft()" except for "brfft()" instead of "rfft()". The + first two arguments and the size of the transformed result, are the + same as for "brfft()". + ``` + """ Base.plan_brfft + + @doc doc""" + ```rst + plan_irfft(A, d[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized inverse real-input FFT, similar to + "plan_rfft()" except for "irfft()" and "brfft()", + respectively. The first three arguments have the same meaning as + for "irfft()". + ``` + """ Base.plan_irfft + + @doc doc""" + ```rst + dct(A[, dims]) + + Performs a multidimensional type-II discrete cosine transform (DCT) + of the array "A", using the unitary normalization of the DCT. The + optional "dims" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. Most efficient if the size of "A" along the transformed + dimensions is a product of small primes; see "nextprod()". See + also "plan_dct()" for even greater efficiency. + ``` + """ Base.dct + + @doc doc""" + ```rst + dct!(A[, dims]) + + Same as "dct!()", except that it operates in-place on "A", + which must be an array of real or complex floating-point values. + ``` + """ Base.dct! + + @doc doc""" + ```rst + idct(A[, dims]) + + Computes the multidimensional inverse discrete cosine transform + (DCT) of the array "A" (technically, a type-III DCT with the + unitary normalization). The optional "dims" argument specifies an + iterable subset of dimensions (e.g. an integer, range, tuple, or + array) to transform along. Most efficient if the size of "A" + along the transformed dimensions is a product of small primes; see + "nextprod()". See also "plan_idct()" for even greater + efficiency. + ``` + """ Base.idct + + @doc doc""" + ```rst + idct!(A[, dims]) + + Same as "idct!()", but operates in-place on "A". + ``` + """ Base.idct! + + @doc doc""" + ```rst + plan_dct(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized discrete cosine transform (DCT), similar to + "plan_fft()" except producing a function that computes "dct()". + The first two arguments have the same meaning as for "dct()". + ``` + """ Base.plan_dct + + @doc doc""" + ```rst + plan_dct!(A[, dims[, flags[, timelimit]]]) + + Same as "plan_dct()", but operates in-place on "A". + ``` + """ Base.plan_dct! + + @doc doc""" + ```rst + plan_idct(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized inverse discrete cosine transform (DCT), + similar to "plan_fft()" except producing a function that computes + "idct()". The first two arguments have the same meaning as for + "idct()". + ``` + """ Base.plan_idct + + @doc doc""" + ```rst + plan_idct!(A[, dims[, flags[, timelimit]]]) + + Same as "plan_idct()", but operates in-place on "A". + ``` + """ Base.plan_idct! + + @doc doc""" + ```rst + fftshift(x) + + Swap the first and second halves of each dimension of "x". + ``` + """ Base.fftshift + + @doc doc""" + ```rst + fftshift(x, dim) + + Swap the first and second halves of the given dimension of array + "x". + ``` + """ Base.fftshift + + @doc doc""" + ```rst + ifftshift(x[, dim]) + + Undoes the effect of "fftshift". + ``` + """ Base.ifftshift + + @doc doc""" + ```rst + filt(b, a, x[, si]) + + Apply filter described by vectors "a" and "b" to vector "x", + with an optional initial filter state vector "si" (defaults to + zeros). + ``` + """ Base.filt + + @doc doc""" + ```rst + filt!(out, b, a, x[, si]) + + Same as "filt()" but writes the result into the "out" argument, + which may alias the input "x" to modify it in-place. + ``` + """ Base.filt! + + @doc doc""" + ```rst + deconv(b, a) + + Construct vector "c" such that "b = conv(a,c) + r". Equivalent + to polynomial division. + ``` + """ Base.deconv + + @doc doc""" + ```rst + conv(u, v) + + Convolution of two vectors. Uses FFT algorithm. + ``` + """ Base.conv + + @doc doc""" + ```rst + conv2(u, v, A) + + 2-D convolution of the matrix "A" with the 2-D separable kernel + generated by the vectors "u" and "v". Uses 2-D FFT algorithm + ``` + """ Base.conv2 + + @doc doc""" + ```rst + conv2(B, A) + + 2-D convolution of the matrix "B" with the matrix "A". Uses + 2-D FFT algorithm + ``` + """ Base.conv2 + + @doc doc""" + ```rst + xcorr(u, v) + + Compute the cross-correlation of two vectors. + ``` + """ Base.xcorr + + @doc doc""" + ```rst + r2r(A, kind[, dims]) + + Performs a multidimensional real-input/real-output (r2r) transform + of type "kind" of the array "A", as defined in the FFTW manual. + "kind" specifies either a discrete cosine transform of various + types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or + "FFTW.REDFT11"), a discrete sine transform of various types + ("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or + "FFTW.RODFT11"), a real-input DFT with halfcomplex-format output + ("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete + Hartley transform ("FFTW.DHT"). The "kind" argument may be an + array or tuple in order to specify different transform types along + the different dimensions of "A"; "kind[end]" is used for any + unspecified dimensions. See the FFTW manual for precise + definitions of these transform types, at http://www.fftw.org/doc. + + The optional "dims" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. "kind[i]" is then the transform type for "dims[i]", with + "kind[end]" being used for "i > length(kind)". + + See also "plan_r2r()" to pre-plan optimized r2r transforms. + ``` + """ Base.FFTW.r2r + + @doc doc""" + ```rst + r2r!(A, kind[, dims]) + + Same as "r2r()", but operates in-place on "A", which must be an + array of real or complex floating-point numbers. + ``` + """ Base.FFTW.r2r! + + @doc doc""" + ```rst + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" + except that the transforms (and the first three arguments) + correspond to "r2r()" and "r2r!()", respectively. + ``` + """ Base.FFTW.plan_r2r + + @doc doc""" + ```rst + plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + + Similar to "Base.plan_fft()", but corresponds to "r2r!()". + ``` + """ Base.FFTW.plan_r2r! + + @doc doc""" + ```rst + quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + + Numerically integrate the function "f(x)" from "a" to "b", + and optionally over additional intervals "b" to "c" and so on. + Keyword options include a relative error tolerance "reltol" + (defaults to "sqrt(eps)" in the precision of the endpoints), an + absolute error tolerance "abstol" (defaults to 0), a maximum + number of function evaluations "maxevals" (defaults to "10^7"), + and the "order" of the integration rule (defaults to 7). + + Returns a pair "(I,E)" of the estimated integral "I" and an + estimated upper bound on the absolute error "E". If "maxevals" + is not exceeded then "E <= max(abstol, reltol*norm(I))" will + hold. (Note that it is useful to specify a positive "abstol" in + cases where "norm(I)" may be zero.) + + The endpoints "a" etcetera can also be complex (in which case the + integral is performed over straight-line segments in the complex + plane). If the endpoints are "BigFloat", then the integration + will be performed in "BigFloat" precision as well (note: it is + advisable to increase the integration "order" in rough proportion + to the precision, for smooth integrands). More generally, the + precision is set by the precision of the integration endpoints + (promoted to floating-point types). + + The integrand "f(x)" can return any numeric scalar, vector, or + matrix type, or in fact any type supporting "+", "-", + multiplication by real values, and a "norm" (i.e., any normed + vector space). Alternatively, a different norm can be specified by + passing a *norm*-like function as the *norm* keyword argument + (which defaults to *vecnorm*). + + [Only one-dimensional integrals are provided by this function. For + multi-dimensional integration (cubature), there are many different + algorithms (often much better than simple nested 1d integrals) and + the optimal choice tends to be very problem-dependent. See the + Julia external-package listing for available algorithms for + multidimensional integration or other specialized tasks (such as + integrals of highly oscillatory or singular functions).] + + The algorithm is an adaptive Gauss-Kronrod integration technique: + the integral in each interval is estimated using a Kronrod rule + ("2*order+1" points) and the error is estimated using an embedded + Gauss rule ("order" points). The interval with the largest + error is then subdivided into two intervals and the process is + repeated until the desired error tolerance is achieved. + + These quadrature rules work best for smooth functions within each + interval, so if your function has a known discontinuity or other + singularity, it is best to subdivide your interval to put the + singularity at an endpoint. For example, if "f" has a + discontinuity at "x=0.7" and you want to integrate from 0 to 1, + you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at + the point of discontinuity. The integrand is never evaluated + exactly at the endpoints of the intervals, so it is possible to + integrate functions that diverge at the endpoints as long as the + singularity is integrable (for example, a "log(x)" or + "1/sqrt(x)" singularity). + + For real-valued endpoints, the starting and/or ending points may be + infinite. (A coordinate transformation is performed internally to + map the infinite interval to a finite one.) + ``` + """ Base.quadgk + + @doc doc""" + ```rst + bin(n[, pad]) + + Convert an integer to a binary string, optionally specifying a + number of digits to pad to. + ``` + """ Base.bin + + @doc doc""" + ```rst + hex(n[, pad]) + + Convert an integer to a hexadecimal string, optionally specifying a + number of digits to pad to. + ``` + """ Base.hex + + @doc doc""" + ```rst + dec(n[, pad]) + + Convert an integer to a decimal string, optionally specifying a + number of digits to pad to. + ``` + """ Base.dec + + @doc doc""" + ```rst + oct(n[, pad]) + + Convert an integer to an octal string, optionally specifying a + number of digits to pad to. + ``` + """ Base.oct + + @doc doc""" + ```rst + base(base, n[, pad]) + + Convert an integer to a string in the given base, optionally + specifying a number of digits to pad to. The base can be specified + as either an integer, or as a "UInt8" array of character values + to use as digit symbols. + ``` + """ Base.base + + @doc doc""" + ```rst + digits(n[, base][, pad]) + + Returns an array of the digits of "n" in the given base, + optionally padded with zeros to a specified size. More significant + digits are at higher indexes, such that "n == + sum([digits[k]*base^(k-1) for k=1:length(digits)])". + ``` + """ Base.digits + + @doc doc""" + ```rst + digits!(array, n[, base]) + + Fills an array of the digits of "n" in the given base. More + significant digits are at higher indexes. If the array length is + insufficient, the least significant digits are filled up to the + array length. If the array length is excessive, the excess portion + is filled with zeros. + ``` + """ Base.digits! + + @doc doc""" + ```rst + bits(n) + + A string giving the literal bit representation of a number. + ``` + """ Base.bits + + @doc doc""" + ```rst + parse(type, str[, base]) + + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. + ``` + """ Base.parse + + @doc doc""" + ```rst + tryparse(type, str[, base]) + + Like "parse", but returns a "Nullable" of the requested type. + The result will be null if the string does not contain a valid + number. + ``` + """ Base.tryparse + + @doc doc""" + ```rst + big(x) + + Convert a number to a maximum precision representation (typically + "BigInt" or "BigFloat"). See "BigFloat" for information about + some pitfalls with floating-point numbers. + ``` + """ Base.big + + @doc doc""" + ```rst + signed(x) + + Convert a number to a signed integer. If the argument is unsigned, + it is reinterpreted as signed without checking for overflow. + ``` + """ Base.signed + + @doc doc""" + ```rst + unsigned(x) -> Unsigned + + Convert a number to an unsigned integer. If the argument is signed, + it is reinterpreted as unsigned without checking for negative + values. + ``` + """ Base.unsigned + + @doc doc""" + ```rst + float(x) + + Convert a number, array, or string to a "FloatingPoint" data + type. For numeric data, the smallest suitable "FloatingPoint" + type is used. Converts strings to "Float64". + ``` + """ Base.float + + @doc doc""" + ```rst + significand(x) + + Extract the significand(s) (a.k.a. mantissa), in binary + representation, of a floating-point number or array. If "x" is a + non-zero finite number, than the result will be a number of the + same type on the interval [1,2). Otherwise "x" is returned. + + julia> significand(15.2)/15.2 + 0.125 + + julia> significand(15.2)*8 + 15.2 + ``` + """ Base.significand + + @doc doc""" + ```rst + exponent(x) -> Int + + Get the exponent of a normalized floating-point number. + ``` + """ Base.exponent + + @doc doc""" + ```rst + complex(r[, i]) + + Convert real numbers or arrays to complex. "i" defaults to zero. + ``` + """ Base.complex + + @doc doc""" + ```rst + bswap(n) + + Byte-swap an integer + ``` + """ Base.bswap + + @doc doc""" + ```rst + num2hex(f) + + Get a hexadecimal string of the binary representation of a floating + point number + ``` + """ Base.num2hex + + @doc doc""" + ```rst + hex2num(str) + + Convert a hexadecimal string to the floating point number it + represents + ``` + """ Base.hex2num + + @doc doc""" + ```rst + hex2bytes(s::ASCIIString) + + Convert an arbitrarily long hexadecimal string to its binary + representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. + ``` + """ Base.hex2bytes + + @doc doc""" + ```rst + bytes2hex(bin_arr::Array{UInt8, 1}) + + Convert an array of bytes to its hexadecimal representation. All + characters are in lower-case. Returns an ASCIIString. + ``` + """ Base.bytes2hex + + @doc doc""" + ```rst + one(x) + + Get the multiplicative identity element for the type of x (x can + also specify the type itself). For matrices, returns an identity + matrix of the appropriate size and type. + ``` + """ Base.one + + @doc doc""" + ```rst + zero(x) + + Get the additive identity element for the type of x (x can also + specify the type itself). + ``` + """ Base.zero + + @doc doc""" + ```rst + pi +π + + The constant pi + ``` + """ Base.pi + + @doc doc""" + ```rst + im + + The imaginary unit + ``` + """ Base.im + + @doc doc""" + ```rst + e +eu + + The constant e + ``` + """ Base.e + + @doc doc""" + ```rst + catalan + + Catalan's constant + ``` + """ Base.catalan + + @doc doc""" + ```rst + γ +eulergamma + + Euler's constant + ``` + """ Base.(:(γ)) + + @doc doc""" + ```rst + φ +golden + + The golden ratio + ``` + """ Base.(:(φ)) + + @doc doc""" + ```rst + Inf + + Positive infinity of type Float64 + ``` + """ Base.Inf + + @doc doc""" + ```rst + Inf32 + + Positive infinity of type Float32 + ``` + """ Base.Inf32 + + @doc doc""" + ```rst + Inf16 + + Positive infinity of type Float16 + ``` + """ Base.Inf16 + + @doc doc""" + ```rst + NaN + + A not-a-number value of type Float64 + ``` + """ Base.NaN + + @doc doc""" + ```rst + NaN32 + + A not-a-number value of type Float32 + ``` + """ Base.NaN32 + + @doc doc""" + ```rst + NaN16 + + A not-a-number value of type Float16 + ``` + """ Base.NaN16 + + @doc doc""" + ```rst + issubnormal(f) -> Bool + + Test whether a floating point number is subnormal + ``` + """ Base.issubnormal + + @doc doc""" + ```rst + isfinite(f) -> Bool + + Test whether a number is finite + ``` + """ Base.isfinite + + @doc doc""" + ```rst + isinf(f) -> Bool + + Test whether a number is infinite + ``` + """ Base.isinf + + @doc doc""" + ```rst + isnan(f) -> Bool + + Test whether a floating point number is not a number (NaN) + ``` + """ Base.isnan + + @doc doc""" + ```rst + inf(f) + + Returns positive infinity of the floating point type "f" or of + the same floating point type as "f" + ``` + """ Base.inf + + @doc doc""" + ```rst + nan(f) + + Returns NaN (not-a-number) of the floating point type "f" or of + the same floating point type as "f" + ``` + """ Base.nan + + @doc doc""" + ```rst + nextfloat(f) + + Get the next floating point number in lexicographic order + ``` + """ Base.nextfloat + + @doc doc""" + ```rst + prevfloat(f) -> FloatingPoint + + Get the previous floating point number in lexicographic order + ``` + """ Base.prevfloat + + @doc doc""" + ```rst + isinteger(x) -> Bool + + Test whether "x" or all its elements are numerically equal to + some integer + ``` + """ Base.isinteger + + @doc doc""" + ```rst + isreal(x) -> Bool + + Test whether "x" or all its elements are numerically equal to + some real number + ``` + """ Base.isreal + + @doc doc""" + ```rst + Float32(x[, mode::RoundingMode]) + + Create a Float32 from "x". If "x" is not exactly representable + then "mode" determines how "x" is rounded. + + julia> Float32(1/3, RoundDown) + 0.3333333f0 + + julia> Float32(1/3, RoundUp) + 0.33333334f0 + + See "get_rounding" for available rounding modes. + ``` + """ Base.Float32 + + @doc doc""" + ```rst + Float64(x[, mode::RoundingMode]) + + Create a Float64 from "x". If "x" is not exactly representable + then "mode" determines how "x" is rounded. + + julia> Float64(pi, RoundDown) + 3.141592653589793 + + julia> Float64(pi, RoundUp) + 3.1415926535897936 + + See "get_rounding" for available rounding modes. + ``` + """ Base.Float64 + + @doc doc""" + ```rst + BigInt(x) + + Create an arbitrary precision integer. "x" may be an "Int" (or + anything that can be converted to an "Int"). The usual + mathematical operators are defined for this type, and results are + promoted to a "BigInt". + + Instances can be constructed from strings via "parse()", or using + the "big" string literal. + ``` + """ Base.BigInt + + @doc doc""" + ```rst + BigFloat(x) + + Create an arbitrary precision floating point number. "x" may be + an "Integer", a "Float64" or a "BigInt". The usual + mathematical operators are defined for this type, and results are + promoted to a "BigFloat". + + Note that because decimal literals are converted to floating point + numbers when parsed, "BigFloat(2.1)" may not yield what you + expect. You may instead prefer to initialize constants from strings + via "parse()", or using the "big" string literal. + + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision + ``` + """ Base.BigFloat + + @doc doc""" + ```rst + get_rounding(T) + + Get the current floating point rounding mode for type "T", + controlling the rounding of basic arithmetic functions ("+()", + "-()", "*()", "/()" and "sqrt()") and type conversion. + + Valid modes are "RoundNearest", "RoundToZero", "RoundUp", + "RoundDown", and "RoundFromZero" ("BigFloat" only). + ``` + """ Base.get_rounding + + @doc doc""" + ```rst + set_rounding(T, mode) + + Set the rounding mode of floating point type "T", controlling the + rounding of basic arithmetic functions ("+()", "-()", "*()", + "/()" and "sqrt()") and type conversion. + + Note that this may affect other types, for instance changing the + rounding mode of "Float64" will change the rounding mode of + "Float32". See "get_rounding" for available modes + ``` + """ Base.set_rounding + + @doc doc""" + ```rst + with_rounding(f::Function, T, mode) + + Change the rounding mode of floating point type "T" for the + duration of "f". It is logically equivalent to: + + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) + + See "get_rounding" for available rounding modes. + ``` + """ Base.with_rounding + + @doc doc""" + ```rst + count_ones(x::Integer) -> Integer + + Number of ones in the binary representation of "x". + + julia> count_ones(7) + 3 + ``` + """ Base.count_ones + + @doc doc""" + ```rst + count_zeros(x::Integer) -> Integer + + Number of zeros in the binary representation of "x". + + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 + ``` + """ Base.count_zeros + + @doc doc""" + ```rst + leading_zeros(x::Integer) -> Integer + + Number of zeros leading the binary representation of "x". + + julia> leading_zeros(Int32(1)) + 31 + ``` + """ Base.leading_zeros + + @doc doc""" + ```rst + leading_ones(x::Integer) -> Integer + + Number of ones leading the binary representation of "x". + + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 + ``` + """ Base.leading_ones + + @doc doc""" + ```rst + trailing_zeros(x::Integer) -> Integer + + Number of zeros trailing the binary representation of "x". + + julia> trailing_zeros(2) + 1 + ``` + """ Base.trailing_zeros + + @doc doc""" + ```rst + trailing_ones(x::Integer) -> Integer + + Number of ones trailing the binary representation of "x". + + julia> trailing_ones(3) + 2 + ``` + """ Base.trailing_ones + + @doc doc""" + ```rst + isprime(x::Integer) -> Bool + + Returns "true" if "x" is prime, and "false" otherwise. + + julia> isprime(3) + true + ``` + """ Base.isprime + + @doc doc""" + ```rst + isprime(x::BigInt[, reps = 25]) -> Bool + + Probabilistic primality test. Returns "true" if "x" is prime; + and "false" if "x" is not prime with high probability. The + false positive rate is about "0.25^reps". "reps = 25" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). + + julia> isprime(big(3)) + true + ``` + """ Base.isprime + + @doc doc""" + ```rst + primes(n) + + Returns a collection of the prime numbers <= "n". + ``` + """ Base.primes + + @doc doc""" + ```rst + isodd(x::Integer) -> Bool + + Returns "true" if "x" is odd (that is, not divisible by 2), and + "false" otherwise. + + julia> isodd(9) + true + + julia> isodd(10) + false + ``` + """ Base.isodd + + @doc doc""" + ```rst + iseven(x::Integer) -> Bool + + Returns "true" is "x" is even (that is, divisible by 2), and + "false" otherwise. + + julia> iseven(9) + false + + julia> iseven(10) + true + ``` + """ Base.iseven + + @doc doc""" + ```rst + precision(num::FloatingPoint) + + Get the precision of a floating point number, as defined by the + effective number of bits in the mantissa. + ``` + """ Base.precision + + @doc doc""" + ```rst + get_bigfloat_precision() + + Get the precision (in bits) currently used for BigFloat arithmetic. + ``` + """ Base.get_bigfloat_precision + + @doc doc""" + ```rst + set_bigfloat_precision(x::Int64) + + Set the precision (in bits) to be used to BigFloat arithmetic. + ``` + """ Base.set_bigfloat_precision + + @doc doc""" + ```rst + with_bigfloat_precision(f::Function, precision::Integer) + + Change the BigFloat arithmetic precision (in bits) for the duration + of "f". It is logically equivalent to: + + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) + ``` + """ Base.with_bigfloat_precision + + @doc doc""" + ```rst + srand([rng][, seed]) + + Reseed the random number generator. If a "seed" is provided, the + RNG will give a reproducible sequence of numbers, otherwise Julia + will get entropy from the system. For "MersenneTwister", the + "seed" may be a non-negative integer, a vector of "UInt32" + integers or a filename, in which case the seed is read from a file. + "RandomDevice" does not support seeding. + ``` + """ Base.srand + + @doc doc""" + ```rst + MersenneTwister([seed]) + + Create a "MersenneTwister" RNG object. Different RNG objects can + have their own seeds, which may be useful for generating different + streams of random numbers. + ``` + """ Base.MersenneTwister + + @doc doc""" + ```rst + RandomDevice() + + Create a "RandomDevice" RNG object. Two such objects will always + generate different streams of random numbers. + ``` + """ Base.RandomDevice + + @doc doc""" + ```rst + rand([rng][, S][, dims...]) + + Pick a random element or array of random elements from the set of + values specified by "S"; "S" can be + + * an indexable collection (for example "1:n" or + "['x','y','z']"), or + + * a type: the set of values to pick from is then equivalent to + "typemin(S):typemax(S)" for integers (this is not applicable to + "BigInt"), and to [0,1) for floating point numbers; + + "S" defaults to "Float64". + ``` + """ Base.rand + + @doc doc""" + ```rst + rand!([rng], A[, coll]) + + Populate the array A with random values. If the indexable + collection "coll" is specified, the values are picked randomly + from "coll". This is equivalent to "copy!(A, rand(rng, coll, + size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but + without allocating a new array. + ``` + """ Base.rand! + + @doc doc""" + ```rst + bitrand([rng][, dims...]) + + Generate a "BitArray" of random boolean values. + ``` + """ Base.bitrand + + @doc doc""" + ```rst + randn([rng][, dims...]) + + Generate a normally-distributed random number with mean 0 and + standard deviation 1. Optionally generate an array of normally- + distributed random numbers. + ``` + """ Base.randn + + @doc doc""" + ```rst + randn!([rng], A::Array{Float64, N}) + + Fill the array A with normally-distributed (mean 0, standard + deviation 1) random numbers. Also see the rand function. + ``` + """ Base.randn! + + @doc doc""" + ```rst + randexp([rng][, dims...]) + + Generate a random number according to the exponential distribution + with scale 1. Optionally generate an array of such random numbers. + ``` + """ Base.randexp + + @doc doc""" + ```rst + randexp!([rng], A::Array{Float64, N}) + + Fill the array A with random numbers following the exponential + distribution (with scale 1). + ``` + """ Base.randexp! + + @doc doc""" + ```rst + Task(func) + + Create a "Task" (i.e. thread, or coroutine) to execute the given + function (which must be callable with no arguments). The task exits + when this function returns. + ``` + """ Base.Task + + @doc doc""" + ```rst + yieldto(task, arg = nothing) + + Switch to the given task. The first time a task is switched to, the + task's function is called with no arguments. On subsequent + switches, "arg" is returned from the task's last call to + "yieldto". This is a low-level call that only switches tasks, not + considering states or scheduling in any way. Its use is + discouraged. + ``` + """ Base.yieldto + + @doc doc""" + ```rst + current_task() + + Get the currently running Task. + ``` + """ Base.current_task + + @doc doc""" + ```rst + istaskdone(task) -> Bool + + Tell whether a task has exited. + ``` + """ Base.istaskdone + + @doc doc""" + ```rst + istaskstarted(task) -> Bool + + Tell whether a task has started executing. + ``` + """ Base.istaskstarted + + @doc doc""" + ```rst + consume(task, values...) + + Receive the next value passed to "produce" by the specified task. + Additional arguments may be passed, to be returned from the last + "produce" call in the producer. + ``` + """ Base.consume + + @doc doc""" + ```rst + produce(value) + + Send the given value to the last "consume" call, switching to the + consumer task. If the next "consume" call passes any values, they + are returned by "produce". + ``` + """ Base.produce + + @doc doc""" + ```rst + yield() + + Switch to the scheduler to allow another scheduled task to run. A + task that calls this function is still runnable, and will be + restarted immediately if there are no other runnable tasks. + ``` + """ Base.yield + + @doc doc""" + ```rst + task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local + storage. + ``` + """ Base.task_local_storage + + @doc doc""" + ```rst + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local + storage. + ``` + """ Base.task_local_storage + + @doc doc""" + ```rst + task_local_storage(body, symbol, value) + + Call the function "body" with a modified task-local storage, in + which "value" is assigned to "symbol"; the previous value of + "symbol", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. + ``` + """ Base.task_local_storage + + @doc doc""" + ```rst + Condition() + + Create an edge-triggered event source that tasks can wait for. + Tasks that call "wait" on a "Condition" are suspended and + queued. Tasks are woken up when "notify" is later called on the + "Condition". Edge triggering means that only tasks waiting at the + time "notify" is called can be woken up. For level-triggered + notifications, you must keep extra state to keep track of whether a + notification has happened. The "RemoteRef" type does this, and so + can be used for level-triggered events. + ``` + """ Base.Condition + + @doc doc""" + ```rst + notify(condition, val=nothing; all=true, error=false) + + Wake up tasks waiting for a condition, passing them "val". If + "all" is true (the default), all waiting tasks are woken, + otherwise only one is. If "error" is true, the passed value is + raised as an exception in the woken tasks. + ``` + """ Base.notify + + @doc doc""" + ```rst + schedule(t::Task, [val]; error=false) + + Add a task to the scheduler's queue. This causes the task to run + constantly when the system is otherwise idle, unless the task + performs a blocking operation such as "wait". + + If a second argument is provided, it will be passed to the task + (via the return value of "yieldto") when it runs again. If + "error" is true, the value is raised as an exception in the woken + task. + ``` + """ Base.schedule + + @doc doc""" + ```rst + @schedule() + + Wrap an expression in a Task and add it to the scheduler's queue. + ``` + """ Base.@schedule + + @doc doc""" + ```rst + @task() + + Wrap an expression in a Task without executing it, and return the + Task. This only creates a task, and does not run it. + ``` + """ Base.@task + + @doc doc""" + ```rst + sleep(seconds) + + Block the current task for a specified number of seconds. The + minimum sleep time is 1 millisecond or input of "0.001". + ``` + """ Base.sleep + + @doc doc""" + ```rst + ReentrantLock() + + Creates a reentrant lock. The same task can acquire the lock as + many times as required. Each lock must be matched with an unlock. + ``` + """ Base.ReentrantLock + + @doc doc""" + ```rst + lock(l::ReentrantLock) + + Associates "l" with the current task. If "l" is already locked + by a different task, waits for it to become available. The same + task can acquire the lock multiple times. Each "lock" must be + matched by an "unlock" + ``` + """ Base.lock + + @doc doc""" + ```rst + unlock(l::ReentrantLock) + + Releases ownership of the lock by the current task. If the lock had + been acquired before, it just decrements an internal counter and + returns immediately. + ``` + """ Base.unlock + + @doc doc""" + ```rst + addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built "LocalManager" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. "addprocs(4)" will add 4 processes + on the local machine. + ``` + """ Base.addprocs + + @doc doc""" + ```rst + addprocs() -> List of process identifiers + + Equivalent to "addprocs(CPU_CORES)" + ``` + """ Base.addprocs + + @doc doc""" + ```rst + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + "machines" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string "machine_spec" or a + tuple - "(machine_spec, count)" + + "machine_spec" is a string of the form "[user@]host[:port] + [bind_addr[:port]]". "user" defaults to current user, "port" + to the standard ssh port. If "[bind_addr[:port]]" is specified, + other workers will connect to this worker at the specified + "bind_addr" and "port". + + "count" is the number of workers to be launched on the specified + host. If specified as ":auto" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + "tunnel" : if "true" then SSH tunneling will be used to connect + to the worker from the master process. + + "sshflags" : specifies additional ssh options, e.g. + "sshflags=`-i /home/foo/bar.pem`" . + + "max_parallel" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + "dir" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + "exename" : name of the julia executable. Defaults to + "\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case + may be. + + "exeflags" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable "JULIA_WORKER_TIMEOUT". The value of + "JULIA_WORKER_TIMEOUT" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. + ``` + """ Base.addprocs + + @doc doc""" + ```rst + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster + manager implemented in package "ClusterManagers". + + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + "JULIA_WORKER_TIMEOUT" in the worker process's environment. + Relevant only when using TCP/IP as transport. + ``` + """ Base.addprocs + + @doc doc""" + ```rst + nprocs() + + Get the number of available processes. + ``` + """ Base.nprocs + + @doc doc""" + ```rst + nworkers() + + Get the number of available worker processes. This is one less than + nprocs(). Equal to nprocs() if nprocs() == 1. + ``` + """ Base.nworkers + + @doc doc""" + ```rst + procs() + + Returns a list of all process identifiers. + ``` + """ Base.procs + + @doc doc""" + ```rst + workers() + + Returns a list of all worker process identifiers. + ``` + """ Base.workers + + @doc doc""" + ```rst + rmprocs(pids...) + + Removes the specified workers. + ``` + """ Base.rmprocs + + @doc doc""" + ```rst + interrupt([pids...]) + + Interrupt the current executing task on the specified workers. This + is equivalent to pressing Ctrl-C on the local machine. If no + arguments are given, all workers are interrupted. + ``` + """ Base.interrupt + + @doc doc""" + ```rst + myid() + + Get the id of the current process. + ``` + """ Base.myid + + @doc doc""" + ```rst + pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + + Transform collections "lsts" by applying "f" to each element in + parallel. If "nprocs() > 1", the calling process will be + dedicated to assigning tasks. All other available processes will be + used as parallel workers, or on the processes specified by + "pids". + + If "err_retry" is true, it retries a failed application of "f" + on a different worker. If "err_stop" is true, it takes precedence + over the value of "err_retry" and "pmap" stops execution on the + first error. + ``` + """ Base.pmap + + @doc doc""" + ```rst + remotecall(id, func, args...) + + Call a function asynchronously on the given arguments on the + specified process. Returns a "RemoteRef". + ``` + """ Base.remotecall + + @doc doc""" + ```rst + wait([x]) + + Block the current task until some event occurs, depending on the + type of the argument: + + * "RemoteRef": Wait for a value to become available for the + specified remote reference. + + * "Condition": Wait for "notify" on a condition. + + * "Process": Wait for a process or process chain to exit. The + "exitcode" field of a process can be used to determine success + or failure. + + * "Task": Wait for a "Task" to finish, returning its result + value. If the task fails with an exception, the exception is + propagated (re-thrown in the task that called "wait"). + + * "RawFD": Wait for changes on a file descriptor (see *poll_fd* + for keyword arguments and return code) + + If no argument is passed, the task blocks for an undefined period. + If the task's state is set to ":waiting", it can only be + restarted by an explicit call to "schedule" or "yieldto". If + the task's state is ":runnable", it might be restarted + unpredictably. + + Often "wait" is called within a "while" loop to ensure a + waited-for condition is met before proceeding. + ``` + """ Base.wait + + @doc doc""" + ```rst + fetch(RemoteRef) + + Wait for and get the value of a remote reference. + ``` + """ Base.fetch + + @doc doc""" + ```rst + remotecall_wait(id, func, args...) + + Perform "wait(remotecall(...))" in one message. + ``` + """ Base.remotecall_wait + + @doc doc""" + ```rst + remotecall_fetch(id, func, args...) + + Perform "fetch(remotecall(...))" in one message. + ``` + """ Base.remotecall_fetch + + @doc doc""" + ```rst + put!(RemoteRef, value) + + Store a value to a remote reference. Implements "shared queue of + length 1" semantics: if a value is already present, blocks until + the value is removed with "take!". Returns its first argument. + ``` + """ Base.put! + + @doc doc""" + ```rst + take!(RemoteRef) + + Fetch the value of a remote reference, removing it so that the + reference is empty again. + ``` + """ Base.take! + + @doc doc""" + ```rst + isready(r::RemoteRef) + + Determine whether a "RemoteRef" has a value stored to it. Note + that this function can cause race conditions, since by the time you + receive its result it may no longer be true. It is recommended that + this function only be used on a "RemoteRef" that is assigned + once. + + If the argument "RemoteRef" is owned by a different node, this + call will block to wait for the answer. It is recommended to wait + for "r" in a separate task instead, or to use a local + "RemoteRef" as a proxy: + + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block + ``` + """ Base.isready + + @doc doc""" + ```rst + RemoteRef() + + Make an uninitialized remote reference on the local machine. + ``` + """ Base.RemoteRef + + @doc doc""" + ```rst + RemoteRef(n) + + Make an uninitialized remote reference on process "n". + ``` + """ Base.RemoteRef + + @doc doc""" + ```rst + timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + + Waits till "testcb" returns "true" or for "secs`" seconds, + whichever is earlier. "testcb" is polled every "pollint" + seconds. + ``` + """ Base.timedwait + + @doc doc""" + ```rst + @spawn() + + Execute an expression on an automatically-chosen process, returning + a "RemoteRef" to the result. + ``` + """ Base.@spawn + + @doc doc""" + ```rst + @spawnat() + + Accepts two arguments, "p" and an expression, and runs the + expression asynchronously on process "p", returning a + "RemoteRef" to the result. + ``` + """ Base.@spawnat + + @doc doc""" + ```rst + @fetch() + + Equivalent to "fetch(@spawn expr)". + ``` + """ Base.@fetch + + @doc doc""" + ```rst + @fetchfrom() + + Equivalent to "fetch(@spawnat p expr)". + ``` + """ Base.@fetchfrom + + @doc doc""" + ```rst + @async() + + Schedule an expression to run on the local machine, also adding it + to the set of items that the nearest enclosing "@sync" waits for. + ``` + """ Base.@async + + @doc doc""" + ```rst + @sync() + + Wait until all dynamically-enclosed uses of "@async", "@spawn", + "@spawnat" and "@parallel" are complete. + ``` + """ Base.@sync + + @doc doc""" + ```rst + @parallel() + + A parallel for loop of the form + + @parallel [reducer] for var = range + body + end + + The specified range is partitioned and locally executed across all + workers. In case an optional reducer function is specified, + @parallel performs local reductions on each worker with a final + reduction on the calling process. + + Note that without a reducer function, @parallel executes + asynchronously, i.e. it spawns independent tasks on all available + workers and returns immediately without waiting for completion. To + wait for completion, prefix the call with "@sync", like + + @sync @parallel for var = range + body + end + ``` + """ Base.@parallel + + @doc doc""" + ```rst + SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + + Construct a SharedArray of a bitstype "T" and size "dims" + across the processes specified by "pids" - all of which have to + be on the same host. + + If "pids" is left unspecified, the shared array will be mapped + across all processes on the current host, including the master. + But, "localindexes" and "indexpids" will only refer to worker + processes. This facilitates work distribution code to use workers + for actual computation with the master process acting as a driver. + + If an "init" function of the type "initfn(S::SharedArray)" is + specified, it is called on all the participating workers. + ``` + """ Base.SharedArray + + @doc doc""" + ```rst + procs(S::SharedArray) + + Get the vector of processes that have mapped the shared array + ``` + """ Base.procs + + @doc doc""" + ```rst + sdata(S::SharedArray) + + Returns the actual "Array" object backing "S" + ``` + """ Base.sdata + + @doc doc""" + ```rst + indexpids(S::SharedArray) + + Returns the index of the current worker into the "pids" vector, + i.e., the list of workers mapping the SharedArray + ``` + """ Base.indexpids + + @doc doc""" + ```rst + launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + + Implemented by cluster managers. For every Julia worker launched by + this function, it should append a "WorkerConfig" entry to + "launched" and notify "launch_ntfy". The function MUST exit + once all workers, requested by "manager" have been launched. + "params" is a dictionary of all keyword arguments "addprocs" + was called with. + ``` + """ Base.launch + + @doc doc""" + ```rst + manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + + Implemented by cluster managers. It is called on the master + process, during a worker's lifetime, with appropriate "op" + values: + + * with ":register"/":deregister" when a worker is added / + removed from the Julia worker pool. + + * with ":interrupt" when "interrupt(workers)" is called. + The "ClusterManager" should signal the appropriate worker + with an interrupt signal. + + * with ":finalize" for cleanup purposes. + ``` + """ Base.manage + + @doc doc""" + ```rst + kill(manager::FooManager, pid::Int, config::WorkerConfig) + + Implemented by cluster managers. It is called on the master + process, by "rmprocs". It should cause the remote worker + specified by "pid" to exit. + "Base.kill(manager::ClusterManager.....)" executes a remote + "exit()" on "pid" + ``` + """ Base.kill + + @doc doc""" + ```rst + init_worker(manager::FooManager) + + Called by cluster managers implementing custom transports. It + initializes a newly launched process as a worker. Command line + argument "--worker" has the effect of initializing a process as a + worker using TCP/IP sockets for transport. + ``` + """ Base.init_worker + + @doc doc""" + ```rst + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id "pid", specified + by "config" and return a pair of "AsyncStream" objects. + Messages from "pid" to current process will be read off + "instrm", while messages to be sent to "pid" will be written to + "outstrm". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + "Base.connect(manager::ClusterManager.....)" sets up TCP/IP + socket connections in-between workers. + ``` + """ Base.connect + + @doc doc""" + ```rst + Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + + Called by cluster managers using custom transports. It should be + called when the custom transport implementation receives the first + message from a remote worker. The custom transport must manage a + logical connection to the remote worker and provide two AsyncStream + objects, one for incoming messages and the other for messages + addressed to the remote worker. + ``` + """ Base.Base + + @doc doc""" + ```rst + dir() -> AbstractString + + Returns the absolute path of the package directory. This defaults + to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION + .minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell + syntax). If the "JULIA_PKGDIR" environment variable is set, then + that path is used in the returned value as "joinpath(ENV["JULIA_ + PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If + "JULIA_PKGDIR" is a relative path, it is interpreted relative to + whatever the current working directory is. + ``` + """ Base.Pkg.dir + + @doc doc""" + ```rst + dir(names...) -> AbstractString + + Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends + path components to the package directory and normalizes the + resulting path. In particular, "Pkg.dir(pkg)" returns the path to + the package "pkg". + ``` + """ Base.Pkg.dir + + @doc doc""" + ```rst + init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) + + Initialize "Pkg.dir()" as a package directory. This will be done + automatically when the "JULIA_PKGDIR" is not set and + "Pkg.dir()" uses its default value. As part of this process, + clones a local METADATA git repository from the site and branch + specified by its arguments, which are typically not provided. + Explicit (non-default) arguments can be used to support a custom + METADATA setup. + ``` + """ Base.Pkg.init + + @doc doc""" + ```rst + resolve() + + Determines an optimal, consistent set of package versions to + install or upgrade to. The optimal set of package versions is based + on the contents of "Pkg.dir("REQUIRE")" and the state of + installed packages in "Pkg.dir()", Packages that are no longer + required are moved into "Pkg.dir(".trash")". + ``` + """ Base.Pkg.resolve + + @doc doc""" + ```rst + edit() + + Opens "Pkg.dir("REQUIRE")" in the editor specified by the + "VISUAL" or "EDITOR" environment variables; when the editor + command returns, it runs "Pkg.resolve()" to determine and install + a new optimal set of installed package versions. + ``` + """ Base.Pkg.edit + + @doc doc""" + ```rst + add(pkg, vers...) + + Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and + call "Pkg.resolve()". If "vers" are given, they must be + "VersionNumber" objects and they specify acceptable version + intervals for "pkg". + ``` + """ Base.Pkg.add + + @doc doc""" + ```rst + rm(pkg) + + Remove all requirement entries for "pkg" from + "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". + ``` + """ Base.Pkg.rm + + @doc doc""" + ```rst + clone(url[, pkg]) + + Clone a package directly from the git URL "url". The package does + not need to be a registered in "Pkg.dir("METADATA")". The + package repo is cloned by the name "pkg" if provided; if not + provided, "pkg" is determined automatically from "url". + ``` + """ Base.Pkg.clone + + @doc doc""" + ```rst + clone(pkg) + + If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone + it from that URL on the default branch. The package does not need + to have any registered versions. + ``` + """ Base.Pkg.clone + + @doc doc""" + ```rst + available() -> Vector{ASCIIString} + + Returns the names of available packages. + ``` + """ Base.Pkg.available + + @doc doc""" + ```rst + available(pkg) -> Vector{VersionNumber} + + Returns the version numbers available for package "pkg". + ``` + """ Base.Pkg.available + + @doc doc""" + ```rst + installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the + installed version number of each package. + ``` + """ Base.Pkg.installed + + @doc doc""" + ```rst + installed(pkg) -> Void | VersionNumber + + If "pkg" is installed, return the installed version number, + otherwise return "nothing". + ``` + """ Base.Pkg.installed + + @doc doc""" + ```rst + status() + + Prints out a summary of what packages are installed and what + version and state they're in. + ``` + """ Base.Pkg.status + + @doc doc""" + ```rst + update() + + Update package the metadata repo – kept in + "Pkg.dir("METADATA")" – then update any fixed packages that can + safely be pulled from their origin; then call "Pkg.resolve()" to + determine a new optimal set of packages versions. + ``` + """ Base.Pkg.update + + @doc doc""" + ```rst + checkout(pkg[, branch="master"]) + + Checkout the "Pkg.dir(pkg)" repo to the branch "branch". + Defaults to checking out the "master" branch. To go back to using + the newest compatible released version, use "Pkg.free(pkg)" + ``` + """ Base.Pkg.checkout + + @doc doc""" + ```rst + pin(pkg) + + Pin "pkg" at the current version. To go back to using the newest + compatible released version, use "Pkg.free(pkg)" + ``` + """ Base.Pkg.pin + + @doc doc""" + ```rst + pin(pkg, version) + + Pin "pkg" at registered version "version". + ``` + """ Base.Pkg.pin + + @doc doc""" + ```rst + free(pkg) + + Free the package "pkg" to be managed by the package manager + again. It calls "Pkg.resolve()" to determine optimal package + versions after. This is an inverse for both "Pkg.checkout" and + "Pkg.pin". + + You can also supply an iterable collection of package names, e.g., + "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at + once. + ``` + """ Base.Pkg.free + + @doc doc""" + ```rst + build() + + Run the build scripts for all installed packages in depth-first + recursive order. + ``` + """ Base.Pkg.build + + @doc doc""" + ```rst + build(pkgs...) + + Run the build script in "deps/build.jl" for each package in + "pkgs" and all of their dependencies in depth-first recursive + order. This is called automatically by "Pkg.resolve()" on all + installed or updated packages. + ``` + """ Base.Pkg.build + + @doc doc""" + ```rst + generate(pkg, license) + + Generate a new package named "pkg" with one of these license + keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make + a package with a different license, you can edit it afterwards. + Generate creates a git repo at "Pkg.dir(pkg)" for the package and + inside it "LICENSE.md", "README.md", the julia entrypoint + "\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". + ``` + """ Base.Pkg.generate + + @doc doc""" + ```rst + register(pkg[, url]) + + Register "pkg" at the git URL "url", defaulting to the + configured origin URL of the git repo "Pkg.dir(pkg)". + ``` + """ Base.Pkg.register + + @doc doc""" + ```rst + tag(pkg[, ver[, commit]]) + + Tag "commit" as version "ver" of package "pkg" and create a + version entry in "METADATA". If not provided, "commit" defaults + to the current commit of the "pkg" repo. If "ver" is one of the + symbols ":patch", ":minor", ":major" the next patch, minor or + major version is used. If "ver" is not provided, it defaults to + ":patch". + ``` + """ Base.Pkg.tag + + @doc doc""" + ```rst + publish() + + For each new package version tagged in "METADATA" not already + published, make sure that the tagged package commits have been + pushed to the repo at the registered URL for the package and if + they all have, open a pull request to "METADATA". + ``` + """ Base.Pkg.publish + + @doc doc""" + ```rst + test() + + Run the tests for all installed packages ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its "test/runtests.jl" file + and test dependencies are specified in "test/REQUIRE". + ``` + """ Base.Pkg.test + + @doc doc""" + ```rst + test(pkgs...) + + Run the tests for each package in "pkgs" ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its "test/runtests.jl" file + and test dependencies are specified in "test/REQUIRE". + ``` + """ Base.Pkg.test + + @doc doc""" + ```rst + @profile() + + "@profile " runs your expression while taking + periodic backtraces. These are appended to an internal buffer of + backtraces. + ``` + """ Base.@profile + + @doc doc""" + ```rst + clear() + + Clear any existing backtraces from the internal buffer. + ``` + """ Base.Profile.clear + + @doc doc""" + ```rst + print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to "io" (by default, "STDOUT"). If you + do not supply a "data" vector, the internal buffer of accumulated + backtraces will be used. "format" can be ":tree" or ":flat". + If "C==true", backtraces from C and Fortran code are shown. + "combine==true" merges instruction pointers that correspond to + the same line of code. "cols" controls the width of the display. + ``` + """ Base.Profile.print + + @doc doc""" + ```rst + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + + Prints profiling results to "io". This variant is used to examine + results exported by a previous call to "retrieve()". Supply the + vector "data" of backtraces and a dictionary "lidict" of line + information. + ``` + """ Base.Profile.print + + @doc doc""" + ```rst + init(; n::Integer, delay::Float64) + + Configure the "delay" between backtraces (measured in seconds), + and the number "n" of instruction pointers that may be stored. + Each instruction pointer corresponds to a single line of code; + backtraces generally consist of a long list of instruction + pointers. Default settings can be obtained by calling this function + with no arguments, and each can be set independently using keywords + or in the order "(n, delay)". + ``` + """ Base.Profile.init + + @doc doc""" + ```rst + fetch() -> data + + Returns a reference to the internal buffer of backtraces. Note that + subsequent operations, like "clear()", can affect "data" unless + you first make a copy. Note that the values in "data" have + meaning only on this machine in the current session, because it + depends on the exact memory addresses used in JIT-compiling. This + function is primarily for internal use; "retrieve()" may be a + better choice for most users. + ``` + """ Base.Profile.fetch + + @doc doc""" + ```rst + retrieve() -> data, lidict + + "Exports" profiling results in a portable format, returning the + set of all backtraces ("data") and a dictionary that maps the + (session-specific) instruction pointers in "data" to "LineInfo" + values that store the file name, function name, and line number. + This function allows you to save profiling results for future + analysis. + ``` + """ Base.Profile.retrieve + + @doc doc""" + ```rst + callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} + + Given a previous profiling run, determine who called a particular + function. Supplying the filename (and optionally, range of line + numbers over which the function is defined) allows you to + disambiguate an overloaded method. The returned value is a vector + containing a count of the number of calls and line information + about the caller. One can optionally supply backtrace data + obtained from "retrieve()"; otherwise, the current internal + profile buffer is used. + ``` + """ Base.Profile.callers + + @doc doc""" + ```rst + clear_malloc_data() + + Clears any stored memory allocation data when running julia with " + --track-allocation". Execute the command(s) you want to test (to + force JIT-compilation), then call "clear_malloc_data()". Then + execute your command(s) again, quit Julia, and examine the + resulting "*.mem" files. + ``` + """ Base.Profile.clear_malloc_data + + @doc doc""" + ```rst + sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the vector "v" in place. "QuickSort" is used by default + for numeric arrays while "MergeSort" is used for other arrays. + You can specify an algorithm to use via the "alg" keyword (see + Sorting Algorithms for available algorithms). The "by" keyword + lets you provide a function that will be applied to each element + before comparison; the "lt" keyword allows providing a custom + "less than" function; use "rev=true" to reverse the sorting + order. These options are independent and can be used together in + all possible combinations: if both "by" and "lt" are specified, + the "lt" function is applied to the result of the "by" + function; "rev=true" reverses whatever ordering specified via the + "by" and "lt" keywords. + ``` + """ Base.sort! + + @doc doc""" + ```rst + sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of "sort!" that returns a sorted copy of "v" leaving + "v" itself unmodified. + ``` + """ Base.sort + + @doc doc""" + ```rst + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort a multidimensional array "A" along the given dimension. + ``` + """ Base.sort + + @doc doc""" + ```rst + sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Return a permutation vector of indices of "v" that puts it in + sorted order. Specify "alg" to choose a particular sorting + algorithm (see Sorting Algorithms). "MergeSort" is used by + default, and since it is stable, the resulting permutation will be + the lexicographically first one that puts the input array into + sorted order – i.e. indices of equal elements appear in ascending + order. If you choose a non-stable sorting algorithm such as + "QuickSort", a different permutation that puts the array into + order may be returned. The order is specified using the same + keywords as "sort!". + + See also "sortperm!()" + ``` + """ Base.sortperm + + @doc doc""" + ```rst + sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + + Like "sortperm", but accepts a preallocated index vector "ix". + If "initialized" is "false" (the default), ix is initialized to + contain the values "1:length(v)". + + See also "sortperm()" + ``` + """ Base.sortperm! + + @doc doc""" + ```rst + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the rows of matrix "A" lexicographically. + ``` + """ Base.sortrows + + @doc doc""" + ```rst + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the columns of matrix "A" lexicographically. + ``` + """ Base.sortcols + + @doc doc""" + ```rst + issorted(v, [by=,] [lt=,] [rev=false]) + + Test whether a vector is in sorted order. The "by", "lt" and + "rev" keywords modify what order is considered to be sorted just + as they do for "sort". + ``` + """ Base.issorted + + @doc doc""" + ```rst + searchsorted(a, x, [by=,] [lt=,] [rev=false]) + + Returns the range of indices of "a" which compare as equal to + "x" according to the order specified by the "by", "lt" and + "rev" keywords, assuming that "a" is already sorted in that + order. Returns an empty range located at the insertion point if + "a" does not contain values equal to "x". + ``` + """ Base.searchsorted + + @doc doc""" + ```rst + searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + + Returns the index of the first value in "a" greater than or equal + to "x", according to the specified order. Returns "length(a)+1" + if "x" is greater than all values in "a". + ``` + """ Base.searchsortedfirst + + @doc doc""" + ```rst + searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + + Returns the index of the last value in "a" less than or equal to + "x", according to the specified order. Returns "0" if "x" is + less than all values in "a". + ``` + """ Base.searchsortedlast + + @doc doc""" + ```rst + select!(v, k, [by=,] [lt=,] [rev=false]) + + Partially sort the vector "v" in place, according to the order + specified by "by", "lt" and "rev" so that the value at index + "k" (or range of adjacent values if "k" is a range) occurs at + the position where it would appear if the array were fully sorted + via a non-stable algorithm. If "k" is a single index, that value + is returned; if "k" is a range, an array of values at those + indices is returned. Note that "select!" does not fully sort the + input array. + ``` + """ Base.select! + + @doc doc""" + ```rst + select(v, k, [by=,] [lt=,] [rev=false]) + + Variant of "select!" which copies "v" before partially sorting + it, thereby returning the same thing as "select!" but leaving + "v" unmodified. + ``` + """ Base.select + + @doc doc""" + ```rst + length(s) + + The number of characters in string "s". + ``` + """ Base.length + + @doc doc""" + ```rst + sizeof(s::AbstractString) + + The number of bytes in string "s". + ``` + """ Base.sizeof + + @doc doc""" + ```rst + *(s, t) + + Concatenate strings. The "*" operator is an alias to this + function. + + julia> "Hello " * "world" + "Hello world" + ``` + """ Base.(:(*)) + + @doc doc""" + ```rst + ^(s, n) + + Repeat "n" times the string "s". The "^" operator is an alias + to this function. + + julia> "Test "^3 + "Test Test Test " + ``` + """ Base.(:(^)) + + @doc doc""" + ```rst + string(xs...) + + Create a string from any values using the "print" function. + ``` + """ Base.string + + @doc doc""" + ```rst + repr(x) + + Create a string from any value using the "showall" function. + ``` + """ Base.repr + + @doc doc""" + ```rst + bytestring(::Ptr{UInt8}[, length]) + + Create a string from the address of a C (0-terminated) string + encoded in ASCII or UTF-8. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. + ``` + """ Base.bytestring + + @doc doc""" + ```rst + bytestring(s) + + Convert a string to a contiguous byte array representation + appropriate for passing it to C functions. The string will be + encoded as either ASCII or UTF-8. + ``` + """ Base.bytestring + + @doc doc""" + ```rst + ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + ``` + """ Base.ascii + + @doc doc""" + ```rst + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must + be valid ASCII characters). + ``` + """ Base.ascii + + @doc doc""" + ```rst + ascii(::Ptr{UInt8}[, length]) + + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. + ``` + """ Base.ascii + + @doc doc""" + ```rst + utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + ``` + """ Base.utf8 + + @doc doc""" + ```rst + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string + encoded in UTF-8. A copy is made; the ptr can be safely freed. If + "length" is specified, the string does not have to be + 0-terminated. + ``` + """ Base.utf8 + + @doc doc""" + ```rst + utf8(s) + + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). + ``` + """ Base.utf8 + + @doc doc""" + ```rst + normalize_string(s, normalform::Symbol) + + Normalize the string "s" according to one of the four "normal + forms" of the Unicode standard: "normalform" can be ":NFC", + ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical + composition) and D (canonical decomposition) convert different + visually identical representations of the same abstract string into + a single canonical form, with form C being more compact. Normal + forms KC and KD additionally canonicalize "compatibility + equivalents": they convert characters that are abstractly similar + but visually distinct into a single canonical choice (e.g. they + expand ligatures into the individual characters), with form KC + being more compact. + + Alternatively, finer control and additional transformations may be + be obtained by calling *normalize_string(s; keywords...)*, where + any number of the following boolean keywords options (which all + default to "false" except for "compose") are specified: + + * "compose=false": do not perform canonical composition + + * "decompose=true": do canonical decomposition instead of + canonical composition ("compose=true" is ignored if present) + + * "compat=true": compatibility equivalents are canonicalized + + * "casefold=true": perform Unicode case folding, e.g. for case- + insensitive string comparison + + * "newline2lf=true", "newline2ls=true", or + "newline2ps=true": convert various newline sequences (LF, CRLF, + CR, NEL) into a linefeed (LF), line-separation (LS), or + paragraph-separation (PS) character, respectively + + * "stripmark=true": strip diacritical marks (e.g. accents) + + * "stripignore=true": strip Unicode's "default ignorable" + characters (e.g. the soft hyphen or the left-to-right marker) + + * "stripcc=true": strip control characters; horizontal tabs and + form feeds are converted to spaces; newlines are also converted + to spaces unless a newline-conversion flag was specified + + * "rejectna=true": throw an error if unassigned code points are + found + + * "stable=true": enforce Unicode Versioning Stability + + For example, NFKC corresponds to the options "compose=true, + compat=true, stable=true". + ``` + """ Base.normalize_string + + @doc doc""" + ```rst + graphemes(s) -> iterator over substrings of s + + Returns an iterator over substrings of "s" that correspond to the + extended graphemes in the string, as defined by Unicode UAX #29. + (Roughly, these are what users would perceive as single characters, + even though they may contain more than one codepoint; for example a + letter combined with an accent mark is a single grapheme.) + ``` + """ Base.graphemes + + @doc doc""" + ```rst + isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which + currently can be one of "Char", "ASCIIString", "UTF8String", + "UTF16String", or "UTF32String" + ``` + """ Base.isvalid + + @doc doc""" + ```rst + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types + currently can be "Char", "ASCIIString", "UTF8String", + "UTF16String", or "UTF32String" Values for "Char" can be of + type "Char" or "UInt32" Values for "ASCIIString" and + "UTF8String" can be of that type, or "Vector{UInt8}" Values for + "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values + for "UTF32String" can be "UTF32String", "Vector{Char}" or + "Vector{UInt32}" + ``` + """ Base.isvalid + + @doc doc""" + ```rst + is_assigned_char(c) -> Bool + + Returns true if the given char or integer is an assigned Unicode + code point. + ``` + """ Base.is_assigned_char + + @doc doc""" + ```rst + ismatch(r::Regex, s::AbstractString) -> Bool + + Test whether a string contains a match of the given regular + expression. + ``` + """ Base.ismatch + + @doc doc""" + ```rst + match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + + Search for the first match of the regular expression "r" in "s" + and return a RegexMatch object containing the match, or nothing if + the match failed. The matching substring can be retrieved by + accessing "m.match" and the captured sequences can be retrieved + by accessing "m.captures" The optional "idx" argument specifies + an index at which to start the search. + ``` + """ Base.match + + @doc doc""" + ```rst + eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + + Search for all matches of a the regular expression "r" in "s" + and return a iterator over the matches. If overlap is true, the + matching sequences are allowed to overlap indices in the original + string, otherwise they must be from distinct character ranges. + ``` + """ Base.eachmatch + + @doc doc""" + ```rst + matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + + Return a vector of the matching substrings from eachmatch. + ``` + """ Base.matchall + + @doc doc""" + ```rst + lpad(string, n, p) + + Make a string at least "n" columns wide when printed, by padding + on the left with copies of "p". + ``` + """ Base.lpad + + @doc doc""" + ```rst + rpad(string, n, p) + + Make a string at least "n" columns wide when printed, by padding + on the right with copies of "p". + ``` + """ Base.rpad + + @doc doc""" + ```rst + search(string, chars[, start]) + + Search for the first occurrence of the given characters within the + given string. The second argument may be a single character, a + vector or a set of characters, a string, or a regular expression + (though regular expressions are only allowed on contiguous strings, + such as ASCII or UTF-8 strings). The third argument optionally + specifies a starting index. The return value is a range of indexes + where the matching sequence is found, such that "s[search(s,x)] == + x": + + "search(string, "substring")" = "start:end" such that + "string[start:end] == "substring"", or "0:-1" if unmatched. + + "search(string, 'c')" = "index" such that + "string[index] == 'c'", or "0" if unmatched. + ``` + """ Base.search + + @doc doc""" + ```rst + rsearch(string, chars[, start]) + + Similar to "search", but returning the last occurrence of the + given characters within the given string, searching in reverse from + "start". + ``` + """ Base.rsearch + + @doc doc""" + ```rst + searchindex(string, substring[, start]) + + Similar to "search", but return only the start index at which the + substring is found, or 0 if it is not. + ``` + """ Base.searchindex + + @doc doc""" + ```rst + rsearchindex(string, substring[, start]) + + Similar to "rsearch", but return only the start index at which + the substring is found, or 0 if it is not. + ``` + """ Base.rsearchindex + + @doc doc""" + ```rst + contains(haystack, needle) + + Determine whether the second argument is a substring of the first. + ``` + """ Base.contains + + @doc doc""" + ```rst + replace(string, pat, r[, n]) + + Search for the given pattern "pat", and replace each occurrence + with "r". If "n" is provided, replace at most "n" + occurrences. As with search, the second argument may be a single + character, a vector or a set of characters, a string, or a regular + expression. If "r" is a function, each occurrence is replaced + with "r(s)" where "s" is the matched substring. + ``` + """ Base.replace + + @doc doc""" + ```rst + split(string, [chars]; limit=0, keep=true) + + Return an array of substrings by splitting the given string on + occurrences of the given character delimiters, which may be + specified in any of the formats allowed by "search"'s second + argument (i.e. a single character, collection of characters, + string, or regular expression). If "chars" is omitted, it + defaults to the set of all space characters, and "keep" is taken + to be false. The two keyword arguments are optional: they are are a + maximum size for the result and a flag determining whether empty + fields should be kept in the result. + ``` + """ Base.split + + @doc doc""" + ```rst + rsplit(string, [chars]; limit=0, keep=true) + + Similar to "split", but starting from the end of the string. + ``` + """ Base.rsplit + + @doc doc""" + ```rst + strip(string[, chars]) + + Return "string" with any leading and trailing whitespace removed. + If "chars" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. + ``` + """ Base.strip + + @doc doc""" + ```rst + lstrip(string[, chars]) + + Return "string" with any leading whitespace removed. If "chars" + (a character, or vector or set of characters) is provided, instead + remove characters contained in it. + ``` + """ Base.lstrip + + @doc doc""" + ```rst + rstrip(string[, chars]) + + Return "string" with any trailing whitespace removed. If + "chars" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. + ``` + """ Base.rstrip + + @doc doc""" + ```rst + startswith(string, prefix | chars) + + Returns "true" if "string" starts with "prefix". If the + second argument is a vector or set of characters, tests whether the + first character of "string" belongs to that set. + ``` + """ Base.startswith + + @doc doc""" + ```rst + endswith(string, suffix | chars) + + Returns "true" if "string" ends with "suffix". If the second + argument is a vector or set of characters, tests whether the last + character of "string" belongs to that set. + ``` + """ Base.endswith + + @doc doc""" + ```rst + uppercase(string) + + Returns "string" with all characters converted to uppercase. + ``` + """ Base.uppercase + + @doc doc""" + ```rst + lowercase(string) + + Returns "string" with all characters converted to lowercase. + ``` + """ Base.lowercase + + @doc doc""" + ```rst + ucfirst(string) + + Returns "string" with the first character converted to uppercase. + ``` + """ Base.ucfirst + + @doc doc""" + ```rst + lcfirst(string) + + Returns "string" with the first character converted to lowercase. + ``` + """ Base.lcfirst + + @doc doc""" + ```rst + join(strings, delim[, last]) + + Join an array of "strings" into a single string, inserting the + given delimiter between adjacent strings. If "last" is given, it + will be used instead of "delim" between the last two strings. For + example, "join(["apples", "bananas", "pineapples"], ", ", + " and ") == "apples, bananas and pineapples"". + + "strings" can be any iterable over elements "x" which are + convertible to strings via "print(io::IOBuffer, x)". + ``` + """ Base.join + + @doc doc""" + ```rst + chop(string) + + Remove the last character from a string + ``` + """ Base.chop + + @doc doc""" + ```rst + chomp(string) + + Remove a trailing newline from a string + ``` + """ Base.chomp + + @doc doc""" + ```rst + ind2chr(string, i) + + Convert a byte index to a character index + ``` + """ Base.ind2chr + + @doc doc""" + ```rst + chr2ind(string, i) + + Convert a character index to a byte index + ``` + """ Base.chr2ind + + @doc doc""" + ```rst + isvalid(str, i) + + Tells whether index "i" is valid for the given string + ``` + """ Base.isvalid + + @doc doc""" + ```rst + nextind(str, i) + + Get the next valid string index after "i". Returns a value + greater than "endof(str)" at or after the end of the string. + ``` + """ Base.nextind + + @doc doc""" + ```rst + prevind(str, i) + + Get the previous valid string index before "i". Returns a value + less than "1" at the beginning of the string. + ``` + """ Base.prevind + + @doc doc""" + ```rst + randstring([rng], len=8) + + Create a random ASCII string of length "len", consisting of + upper- and lower-case letters and the digits 0-9. The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. + ``` + """ Base.randstring + + @doc doc""" + ```rst + charwidth(c) + + Gives the number of columns needed to print a character. + ``` + """ Base.charwidth + + @doc doc""" + ```rst + strwidth(s) + + Gives the number of columns needed to print a string. + ``` + """ Base.strwidth + + @doc doc""" + ```rst + isalnum(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is alphanumeric, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter or + Number, i.e. a character whose category code begins with 'L' or + 'N'. + ``` + """ Base.isalnum + + @doc doc""" + ```rst + isalpha(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is alphabetic, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter, + i.e. a character whose category code begins with 'L'. + ``` + """ Base.isalpha + + @doc doc""" + ```rst + isascii(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character belongs to the ASCII character set, or + whether this is true for all elements of a string. + ``` + """ Base.isascii + + @doc doc""" + ```rst + iscntrl(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a control character, or whether this + is true for all elements of a string. Control characters are the + non-printing characters of the Latin-1 subset of Unicode. + ``` + """ Base.iscntrl + + @doc doc""" + ```rst + isdigit(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a numeric digit (0-9), or whether this + is true for all elements of a string. + ``` + """ Base.isdigit + + @doc doc""" + ```rst + isgraph(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is printable, and not a space, or whether + this is true for all elements of a string. Any character that + would cause a printer to use ink should be classified with + isgraph(c)==true. + ``` + """ Base.isgraph + + @doc doc""" + ```rst + islower(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a lowercase letter, or whether this is + true for all elements of a string. A character is classified as + lowercase if it belongs to Unicode category Ll, Letter: Lowercase. + ``` + """ Base.islower + + @doc doc""" + ```rst + isnumber(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is numeric, or whether this is true for + all elements of a string. A character is classified as numeric if + it belongs to the Unicode general category Number, i.e. a character + whose category code begins with 'N'. + ``` + """ Base.isnumber + + @doc doc""" + ```rst + isprint(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is printable, including spaces, but not a + control character. For strings, tests whether this is true for all + elements of the string. + ``` + """ Base.isprint + + @doc doc""" + ```rst + ispunct(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character belongs to the Unicode general category + Punctuation, i.e. a character whose category code begins with 'P'. + For strings, tests whether this is true for all elements of the + string. + ``` + """ Base.ispunct + + @doc doc""" + ```rst + isspace(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is any whitespace character. Includes + ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', + Latin-1 character U+0085, and characters in Unicode category Zs. + For strings, tests whether this is true for all elements of the + string. + ``` + """ Base.isspace + + @doc doc""" + ```rst + isupper(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is an uppercase letter, or whether this + is true for all elements of a string. A character is classified + as uppercase if it belongs to Unicode category Lu, Letter: + Uppercase, or Lt, Letter: Titlecase. + ``` + """ Base.isupper + + @doc doc""" + ```rst + isxdigit(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a valid hexadecimal digit, or whether + this is true for all elements of a string. + ``` + """ Base.isxdigit + + @doc doc""" + ```rst + symbol(x...) -> Symbol + + Create a "Symbol" by concatenating the string representations of + the arguments together. + ``` + """ Base.symbol + + @doc doc""" + ```rst + escape_string(str::AbstractString) -> AbstractString + + General escaping of traditional C and Unicode escape sequences. See + "print_escaped()" for more general escaping. + ``` + """ Base.escape_string + + @doc doc""" + ```rst + unescape_string(s::AbstractString) -> AbstractString + + General unescaping of traditional C and Unicode escape sequences. + Reverse of "escape_string()". See also "print_unescaped()". + ``` + """ Base.unescape_string + + @doc doc""" + ```rst + utf16(s) + + Create a UTF-16 string from a byte array, array of "UInt16", or + any other string type. (Data must be valid UTF-16. Conversions of + byte arrays check for a byte-order marker in the first two bytes, + and do not include it in the resulting string.) + + Note that the resulting "UTF16String" data is terminated by the + NUL codepoint (16-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf16(s)* conversion function. If you have a "UInt16" array + "A" that is already NUL-terminated valid UTF-16 data, then you + can instead use *UTF16String(A)`* to construct the string without + making a copy of the data and treating the NUL as a terminator + rather than as part of the string. + ``` + """ Base.utf16 + + @doc doc""" + ```rst + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + + Create a string from the address of a NUL-terminated UTF-16 string. + A copy is made; the pointer can be safely freed. If "length" is + specified, the string does not have to be NUL-terminated. + ``` + """ Base.utf16 + + @doc doc""" + ```rst + utf32(s) + + Create a UTF-32 string from a byte array, array of "Char" or + "UInt32", or any other string type. (Conversions of byte arrays + check for a byte-order marker in the first four bytes, and do not + include it in the resulting string.) + + Note that the resulting "UTF32String" data is terminated by the + NUL codepoint (32-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf32(s)* conversion function. If you have a "Char" or + "UInt32" array "A" that is already NUL-terminated UTF-32 data, + then you can instead use *UTF32String(A)`* to construct the string + without making a copy of the data and treating the NUL as a + terminator rather than as part of the string. + ``` + """ Base.utf32 + + @doc doc""" + ```rst + utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) + + Create a string from the address of a NUL-terminated UTF-32 string. + A copy is made; the pointer can be safely freed. If "length" is + specified, the string does not have to be NUL-terminated. + ``` + """ Base.utf32 + + @doc doc""" + ```rst + wstring(s) + + This is a synonym for either "utf32(s)" or "utf16(s)", + depending on whether "Cwchar_t" is 32 or 16 bits, respectively. + The synonym "WString" for "UTF32String" or "UTF16String" is + also provided. + ``` + """ Base.wstring + + @doc doc""" + ```rst + runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) + + Run the Julia unit tests listed in "tests", which can be either a + string or an array of strings, using "numcores" processors. (not + exported) + ``` + """ Base.runtests + + @doc doc""" + ```rst + @test(ex) + + Test the expression "ex" and calls the current handler to handle + the result. + ``` + """ Base.Test.@test + + @doc doc""" + ```rst + @test_throws(extype, ex) + + Test that the expression "ex" throws an exception of type + "extype" and calls the current handler to handle the result. + ``` + """ Base.Test.@test_throws + + @doc doc""" + ```rst + @test_approx_eq(a, b) + + Test two floating point numbers "a" and "b" for equality taking + in account small numerical errors. + ``` + """ Base.Test.@test_approx_eq + + @doc doc""" + ```rst + @test_approx_eq_eps(a, b, tol) + + Test two floating point numbers "a" and "b" for equality taking + in account a margin of tolerance given by "tol". + ``` + """ Base.Test.@test_approx_eq_eps + + @doc doc""" + ```rst + with_handler(f, handler) + + Run the function "f" using the "handler" as the handler. + ``` + """ Base.Test.with_handler + diff --git a/base/sysimg.jl b/base/sysimg.jl index 48d05edc2af56..7fe3aeb6b2719 100644 --- a/base/sysimg.jl +++ b/base/sysimg.jl @@ -307,6 +307,7 @@ include("deprecated.jl") # Some basic documentation include("docs/basedocs.jl") +include("docs/helpdb.jl") function __init__() # Base library init diff --git a/doc/newdoc.jl b/doc/newdoc.jl new file mode 100644 index 0000000000000..c41fd1453fd95 --- /dev/null +++ b/doc/newdoc.jl @@ -0,0 +1,21 @@ +exceptions = ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] + +cd(joinpath(dirname(@__FILE__), "..", "base", "docs")) do + open("helpdb.jl", "w") do io + for (mod, func, desc) in evalfile(Base.Help.helpdb_filename()) + (func in exceptions || ismatch(r"[\{\} ]", func)) && continue + + ismatch(r"[^\w@!]|^!$", func) && (func = "(:($func))") + desc = replace(rstrip(desc), "\$", "\\\$") + desc = replace(desc, "\"\"\"", "\\\"\"\"") + + println(io, """ + @doc doc\""" + ```rst + $desc + ``` + \""" $mod.$func + """) + end + end +end From cd639a56e7892a9bb3596026c8e13c0aba816eb8 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Tue, 23 Jun 2015 13:00:14 -0400 Subject: [PATCH 02/27] remove redundant qualifiers --- base/docs/helpdb.jl | 2536 +++++++++++++++++++++---------------------- doc/newdoc.jl | 13 +- 2 files changed, 1279 insertions(+), 1270 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index bf022f5357224..465e00c29505b 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -4,7 +4,7 @@ Returns the number of dimensions of A ``` - """ Base.ndims + """ ndims @doc doc""" ```rst @@ -23,7 +23,7 @@ julia> size(A,3,2) (4,3) ``` - """ Base.size + """ size @doc doc""" ```rst @@ -31,7 +31,7 @@ Tests whether A or its elements are of type T ``` - """ Base.iseltype + """ iseltype @doc doc""" ```rst @@ -39,7 +39,7 @@ Returns the number of elements in A ``` - """ Base.length + """ length @doc doc""" ```rst @@ -77,7 +77,7 @@ (iter.I_1,iter.I_2) = (2,3) A[iter] = 0.8090413606455655 ``` - """ Base.eachindex + """ eachindex @doc doc""" ```rst @@ -100,7 +100,7 @@ Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() ``` - """ Base.Base + """ Base @doc doc""" ```rst @@ -111,7 +111,7 @@ matrices, one should usually use "nnz", which returns the number of stored values. ``` - """ Base.countnz + """ countnz @doc doc""" ```rst @@ -119,7 +119,7 @@ Convert an array to its complex conjugate in-place ``` - """ Base.conj! + """ conj! @doc doc""" ```rst @@ -128,7 +128,7 @@ Returns the distance in memory (in number of elements) between adjacent elements in dimension k ``` - """ Base.stride + """ stride @doc doc""" ```rst @@ -136,7 +136,7 @@ Returns a tuple of the memory strides in each dimension ``` - """ Base.strides + """ strides @doc doc""" ```rst @@ -148,7 +148,7 @@ **Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides the indices of the maximum element ``` - """ Base.ind2sub + """ ind2sub @doc doc""" ```rst @@ -157,7 +157,7 @@ Returns a tuple of subscripts into array "a" corresponding to the linear index "index" ``` - """ Base.ind2sub + """ ind2sub @doc doc""" ```rst @@ -166,7 +166,7 @@ The inverse of "ind2sub", returns the linear index corresponding to the provided subscripts ``` - """ Base.sub2ind + """ sub2ind @doc doc""" ```rst @@ -177,7 +177,7 @@ arguments. The syntax "Array(T, dims)" is also available, but deprecated. ``` - """ Base.Array + """ Array @doc doc""" ```rst @@ -187,7 +187,7 @@ with the syntax "Type[]". Element values can be specified using "Type[a,b,c,...]". ``` - """ Base.getindex + """ getindex @doc doc""" ```rst @@ -196,7 +196,7 @@ Construct an uninitialized cell array (heterogeneous array). "dims" can be either a tuple or a series of integer arguments. ``` - """ Base.cell + """ cell @doc doc""" ```rst @@ -205,7 +205,7 @@ Create an array of all zeros of specified type. The type defaults to Float64 if not specified. ``` - """ Base.zeros + """ zeros @doc doc""" ```rst @@ -214,7 +214,7 @@ Create an array of all zeros with the same element type and shape as A. ``` - """ Base.zeros + """ zeros @doc doc""" ```rst @@ -223,7 +223,7 @@ Create an array of all ones of specified type. The type defaults to Float64 if not specified. ``` - """ Base.ones + """ ones @doc doc""" ```rst @@ -232,7 +232,7 @@ Create an array of all ones with the same element type and shape as A. ``` - """ Base.ones + """ ones @doc doc""" ```rst @@ -240,7 +240,7 @@ Create a "BitArray" with all values set to true ``` - """ Base.trues + """ trues @doc doc""" ```rst @@ -248,7 +248,7 @@ Create a "BitArray" with all values set to false ``` - """ Base.falses + """ falses @doc doc""" ```rst @@ -262,7 +262,7 @@ same object. "fill(Foo(), dims)" will return an array filled with the result of evaluating "Foo()" once. ``` - """ Base.fill + """ fill @doc doc""" ```rst @@ -273,7 +273,7 @@ Foo())" will return "A" filled with the result of evaluating "Foo()" once. ``` - """ Base.fill! + """ fill! @doc doc""" ```rst @@ -283,7 +283,7 @@ different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. ``` - """ Base.reshape + """ reshape @doc doc""" ```rst @@ -297,7 +297,7 @@ ranges), this function returns a standard "Array" to allow operating on elements. ``` - """ Base.similar + """ similar @doc doc""" ```rst @@ -309,7 +309,7 @@ constructs an array with the same binary data as the given array, but with the specified element type. ``` - """ Base.reinterpret + """ reinterpret @doc doc""" ```rst @@ -317,7 +317,7 @@ n-by-n identity matrix ``` - """ Base.eye + """ eye @doc doc""" ```rst @@ -325,7 +325,7 @@ m-by-n identity matrix ``` - """ Base.eye + """ eye @doc doc""" ```rst @@ -334,7 +334,7 @@ Constructs an identity matrix of the same dimensions and type as "A". ``` - """ Base.eye + """ eye @doc doc""" ```rst @@ -343,7 +343,7 @@ Construct a range of "n" linearly spaced elements from "start" to "stop". ``` - """ Base.linspace + """ linspace @doc doc""" ```rst @@ -352,7 +352,7 @@ Construct a vector of "n" logarithmically spaced numbers from "10^start" to "10^stop". ``` - """ Base.logspace + """ logspace @doc doc""" ```rst @@ -362,7 +362,7 @@ singleton dimensions, and returns an array of the results "f(as...)" for each position. ``` - """ Base.broadcast + """ broadcast @doc doc""" ```rst @@ -374,7 +374,7 @@ listed in the "As", as in "broadcast!(f, A, A, B)" to perform "A[:] = broadcast(f, A, B)". ``` - """ Base.broadcast! + """ broadcast! @doc doc""" ```rst @@ -383,7 +383,7 @@ Like "broadcast", but allocates a "BitArray" to store the result, rather then an "Array". ``` - """ Base.bitbroadcast + """ bitbroadcast @doc doc""" ```rst @@ -393,7 +393,7 @@ "broadcast_function(f)(As...) === broadcast(f, As...)". Most useful in the form "const broadcast_f = broadcast_function(f)". ``` - """ Base.broadcast_function + """ broadcast_function @doc doc""" ```rst @@ -401,7 +401,7 @@ Like "broadcast_function", but for "broadcast!". ``` - """ Base.broadcast!_function + """ broadcast!_function @doc doc""" ```rst @@ -411,7 +411,7 @@ each "ind" may be an "Int", a "Range", or a "Vector". See the manual section on *array indexing* for details. ``` - """ Base.getindex + """ getindex @doc doc""" ```rst @@ -423,7 +423,7 @@ computes the indices to the parent array on the fly without checking bounds. ``` - """ Base.sub + """ sub @doc doc""" ```rst @@ -432,7 +432,7 @@ Returns the "parent array" of an array view type (e.g., SubArray), or the array itself if it is not a view ``` - """ Base.parent + """ parent @doc doc""" ```rst @@ -441,7 +441,7 @@ From an array view "A", returns the corresponding indexes in the parent ``` - """ Base.parentindexes + """ parentindexes @doc doc""" ```rst @@ -451,7 +451,7 @@ equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is in position "d". ``` - """ Base.slicedim + """ slicedim @doc doc""" ```rst @@ -460,7 +460,7 @@ Returns a view of array "A" with the given indices like "sub()", but drops all dimensions indexed with scalars. ``` - """ Base.slice + """ slice @doc doc""" ```rst @@ -469,7 +469,7 @@ Store values from array "X" within some subset of "A" as specified by "inds". ``` - """ Base.setindex! + """ setindex! @doc doc""" ```rst @@ -479,7 +479,7 @@ and returns an array of the results "A[ks...]", where "ks" goes over the positions in the broadcast. ``` - """ Base.broadcast_getindex + """ broadcast_getindex @doc doc""" ```rst @@ -489,7 +489,7 @@ stores the value from each position in "X" at the indices given by the same positions in "inds". ``` - """ Base.broadcast_setindex! + """ broadcast_setindex! @doc doc""" ```rst @@ -510,7 +510,7 @@ block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. ``` - """ Base.cat + """ cat @doc doc""" ```rst @@ -518,7 +518,7 @@ Concatenate along dimension 1 ``` - """ Base.vcat + """ vcat @doc doc""" ```rst @@ -526,7 +526,7 @@ Concatenate along dimension 2 ``` - """ Base.hcat + """ hcat @doc doc""" ```rst @@ -540,7 +540,7 @@ If the first argument is a single integer "n", then all block rows are assumed to have "n" block columns. ``` - """ Base.hvcat + """ hvcat @doc doc""" ```rst @@ -548,7 +548,7 @@ Reverse "A" in dimension "d". ``` - """ Base.flipdim + """ flipdim @doc doc""" ```rst @@ -557,7 +557,7 @@ Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. ``` - """ Base.circshift + """ circshift @doc doc""" ```rst @@ -567,7 +567,7 @@ (determined by "A[i]!=0"). A common use of this is to convert a boolean array to an array of indexes of the "true" elements. ``` - """ Base.find + """ find @doc doc""" ```rst @@ -576,7 +576,7 @@ Return a vector of the linear indexes of "A" where "f" returns true. ``` - """ Base.find + """ find @doc doc""" ```rst @@ -585,7 +585,7 @@ Return a vector of indexes for each dimension giving the locations of the non-zeros in "A" (determined by "A[i]!=0"). ``` - """ Base.findn + """ findn @doc doc""" ```rst @@ -595,7 +595,7 @@ column indexes of the non-zero values in matrix "A", and "V" is a vector of the non-zero values. ``` - """ Base.findnz + """ findnz @doc doc""" ```rst @@ -604,7 +604,7 @@ Return the index of the first non-zero value in "A" (determined by "A[i]!=0"). ``` - """ Base.findfirst + """ findfirst @doc doc""" ```rst @@ -612,7 +612,7 @@ Return the index of the first element equal to "v" in "A". ``` - """ Base.findfirst + """ findfirst @doc doc""" ```rst @@ -621,7 +621,7 @@ Return the index of the first element of "A" for which "predicate" returns true. ``` - """ Base.findfirst + """ findfirst @doc doc""" ```rst @@ -630,7 +630,7 @@ Return the index of the last non-zero value in "A" (determined by "A[i]!=0"). ``` - """ Base.findlast + """ findlast @doc doc""" ```rst @@ -638,7 +638,7 @@ Return the index of the last element equal to "v" in "A". ``` - """ Base.findlast + """ findlast @doc doc""" ```rst @@ -647,7 +647,7 @@ Return the index of the last element of "A" for which "predicate" returns true. ``` - """ Base.findlast + """ findlast @doc doc""" ```rst @@ -656,7 +656,7 @@ Find the next index >= "i" of a non-zero element of "A", or "0" if not found. ``` - """ Base.findnext + """ findnext @doc doc""" ```rst @@ -665,7 +665,7 @@ Find the next index >= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. ``` - """ Base.findnext + """ findnext @doc doc""" ```rst @@ -674,7 +674,7 @@ Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. ``` - """ Base.findnext + """ findnext @doc doc""" ```rst @@ -683,7 +683,7 @@ Find the previous index <= "i" of a non-zero element of "A", or 0 if not found. ``` - """ Base.findprev + """ findprev @doc doc""" ```rst @@ -692,7 +692,7 @@ Find the previous index <= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. ``` - """ Base.findprev + """ findprev @doc doc""" ```rst @@ -701,7 +701,7 @@ Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. ``` - """ Base.findprev + """ findprev @doc doc""" ```rst @@ -712,7 +712,7 @@ generalization of transpose for multi-dimensional arrays. Transpose is equivalent to "permutedims(A, [2,1])". ``` - """ Base.permutedims + """ permutedims @doc doc""" ```rst @@ -721,7 +721,7 @@ Like "permutedims()", except the inverse of the given permutation is applied. ``` - """ Base.ipermutedims + """ ipermutedims @doc doc""" ```rst @@ -734,7 +734,7 @@ in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. ``` - """ Base.permutedims! + """ permutedims! @doc doc""" ```rst @@ -744,7 +744,7 @@ Elements of "dims" must be unique and within the range "1:ndims(A)". ``` - """ Base.squeeze + """ squeeze @doc doc""" ```rst @@ -752,7 +752,7 @@ Vectorize an array using column-major convention. ``` - """ Base.vec + """ vec @doc doc""" ```rst @@ -762,7 +762,7 @@ singleton dimensions, and return whichever shape has more dimensions. ``` - """ Base.promote_shape + """ promote_shape @doc doc""" ```rst @@ -771,7 +771,7 @@ Throw an error if the specified indexes are not in bounds for the given array. ``` - """ Base.checkbounds + """ checkbounds @doc doc""" ```rst @@ -784,7 +784,7 @@ small and "A" is large.) Technically, this process is known as "Bernoulli sampling" of "A". ``` - """ Base.randsubseq + """ randsubseq @doc doc""" ```rst @@ -793,7 +793,7 @@ Like "randsubseq", but the results are stored in "S" (which is resized as needed). ``` - """ Base.randsubseq! + """ randsubseq! @doc doc""" ```rst @@ -804,7 +804,7 @@ performance and to control the precision of the output (e.g. to avoid overflow). ``` - """ Base.cumprod + """ cumprod @doc doc""" ```rst @@ -813,7 +813,7 @@ Cumulative product of "A" along a dimension, storing the result in "B". The dimension defaults to 1. ``` - """ Base.cumprod! + """ cumprod! @doc doc""" ```rst @@ -824,7 +824,7 @@ performance and to control the precision of the output (e.g. to avoid overflow). ``` - """ Base.cumsum + """ cumsum @doc doc""" ```rst @@ -833,7 +833,7 @@ Cumulative sum of "A" along a dimension, storing the result in "B". The dimension defaults to 1. ``` - """ Base.cumsum! + """ cumsum! @doc doc""" ```rst @@ -843,7 +843,7 @@ compensated summation algorithm for additional accuracy. The dimension defaults to 1. ``` - """ Base.cumsum_kbn + """ cumsum_kbn @doc doc""" ```rst @@ -851,7 +851,7 @@ Cumulative minimum along a dimension. The dimension defaults to 1. ``` - """ Base.cummin + """ cummin @doc doc""" ```rst @@ -859,7 +859,7 @@ Cumulative maximum along a dimension. The dimension defaults to 1. ``` - """ Base.cummax + """ cummax @doc doc""" ```rst @@ -867,7 +867,7 @@ Finite difference operator of matrix or vector. ``` - """ Base.diff + """ diff @doc doc""" ```rst @@ -876,7 +876,7 @@ Compute differences along vector "F", using "h" as the spacing between points. The default spacing is one. ``` - """ Base.gradient + """ gradient @doc doc""" ```rst @@ -884,7 +884,7 @@ Rotate matrix "A" 180 degrees. ``` - """ Base.rot180 + """ rot180 @doc doc""" ```rst @@ -893,7 +893,7 @@ Rotate matrix "A" 180 degrees an integer "k" number of times. If "k" is even, this is equivalent to a "copy". ``` - """ Base.rot180 + """ rot180 @doc doc""" ```rst @@ -901,7 +901,7 @@ Rotate matrix "A" left 90 degrees. ``` - """ Base.rotl90 + """ rotl90 @doc doc""" ```rst @@ -911,7 +911,7 @@ times. If "k" is zero or a multiple of four, this is equivalent to a "copy". ``` - """ Base.rotl90 + """ rotl90 @doc doc""" ```rst @@ -919,7 +919,7 @@ Rotate matrix "A" right 90 degrees. ``` - """ Base.rotr90 + """ rotr90 @doc doc""" ```rst @@ -929,7 +929,7 @@ times. If "k" is zero or a multiple of four, this is equivalent to a "copy". ``` - """ Base.rotr90 + """ rotr90 @doc doc""" ```rst @@ -944,7 +944,7 @@ you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for "reduce". ``` - """ Base.reducedim + """ reducedim @doc doc""" ```rst @@ -954,7 +954,7 @@ f(initial))*, but is generally faster because the intermediate array is avoided. ``` - """ Base.mapreducedim + """ mapreducedim @doc doc""" ```rst @@ -968,7 +968,7 @@ "dims" is "[1,2]" and A is 4-dimensional, "f" is called on "A[:,:,i,j]" for all "i" and "j". ``` - """ Base.mapslices + """ mapslices @doc doc""" ```rst @@ -977,7 +977,7 @@ Returns the sum of all array elements, using the Kahan-Babuska- Neumaier compensated summation algorithm for additional accuracy. ``` - """ Base.sum_kbn + """ sum_kbn @doc doc""" ```rst @@ -992,7 +992,7 @@ 12 22 ``` - """ Base.cartesianmap + """ cartesianmap @doc doc""" ```rst @@ -1000,7 +1000,7 @@ Compute the kth lexicographic permutation of a vector. ``` - """ Base.nthperm + """ nthperm @doc doc""" ```rst @@ -1009,7 +1009,7 @@ Return the "k" that generated permutation "p". Note that "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". ``` - """ Base.nthperm + """ nthperm @doc doc""" ```rst @@ -1017,7 +1017,7 @@ In-place version of "nthperm()". ``` - """ Base.nthperm! + """ nthperm! @doc doc""" ```rst @@ -1027,7 +1027,7 @@ "rng" argument specifies a random number generator, see *Random Numbers*. ``` - """ Base.randperm + """ randperm @doc doc""" ```rst @@ -1035,7 +1035,7 @@ Return the inverse permutation of v. ``` - """ Base.invperm + """ invperm @doc doc""" ```rst @@ -1043,7 +1043,7 @@ Returns true if v is a valid permutation. ``` - """ Base.isperm + """ isperm @doc doc""" ```rst @@ -1055,7 +1055,7 @@ To return a new permutation, use "v[p]". Note that this is generally faster than "permute!(v,p)" for large vectors. ``` - """ Base.permute! + """ permute! @doc doc""" ```rst @@ -1063,7 +1063,7 @@ Like permute!, but the inverse of the given permutation is applied. ``` - """ Base.ipermute! + """ ipermute! @doc doc""" ```rst @@ -1073,7 +1073,7 @@ "rng" argument specifies a random number generator, see *Random Numbers*. ``` - """ Base.randcycle + """ randcycle @doc doc""" ```rst @@ -1082,7 +1082,7 @@ Return a randomly permuted copy of "v". The optional "rng" argument specifies a random number generator, see *Random Numbers*. ``` - """ Base.shuffle + """ shuffle @doc doc""" ```rst @@ -1090,7 +1090,7 @@ In-place version of "shuffle()". ``` - """ Base.shuffle! + """ shuffle! @doc doc""" ```rst @@ -1098,7 +1098,7 @@ Return a copy of "v" reversed from start to stop. ``` - """ Base.reverse + """ reverse @doc doc""" ```rst @@ -1109,7 +1109,7 @@ (This can be nontrivial in the case where "v" is a Unicode string.) ``` - """ Base.reverseind + """ reverseind @doc doc""" ```rst @@ -1117,7 +1117,7 @@ In-place version of "reverse()". ``` - """ Base.reverse! + """ reverse! @doc doc""" ```rst @@ -1129,7 +1129,7 @@ "collect(combinations(array,n))" to get an array of all combinations. ``` - """ Base.combinations + """ combinations @doc doc""" ```rst @@ -1140,7 +1140,7 @@ iterator object. Use "collect(permutations(array))" to get an array of all permutations. ``` - """ Base.permutations + """ permutations @doc doc""" ```rst @@ -1152,7 +1152,7 @@ partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n))". ``` - """ Base.partitions + """ partitions @doc doc""" ```rst @@ -1164,7 +1164,7 @@ array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n,m))". ``` - """ Base.partitions + """ partitions @doc doc""" ```rst @@ -1177,7 +1177,7 @@ The number of partitions to generate can be efficiently computed using "length(partitions(array))". ``` - """ Base.partitions + """ partitions @doc doc""" ```rst @@ -1191,7 +1191,7 @@ equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". ``` - """ Base.partitions + """ partitions @doc doc""" ```rst @@ -1199,7 +1199,7 @@ Converts a numeric array to a packed boolean array ``` - """ Base.bitpack + """ bitpack @doc doc""" ```rst @@ -1207,7 +1207,7 @@ Converts a packed boolean array to an array of booleans ``` - """ Base.bitunpack + """ bitunpack @doc doc""" ```rst @@ -1215,7 +1215,7 @@ Performs a bitwise not operation on B. See *~ operator*. ``` - """ Base.flipbits! + """ flipbits! @doc doc""" ```rst @@ -1224,7 +1224,7 @@ Performs a left rotation operation on "src" and put the result into "dest". ``` - """ Base.rol! + """ rol! @doc doc""" ```rst @@ -1232,7 +1232,7 @@ Performs a left rotation operation on B. ``` - """ Base.rol! + """ rol! @doc doc""" ```rst @@ -1240,7 +1240,7 @@ Performs a left rotation operation. ``` - """ Base.rol + """ rol @doc doc""" ```rst @@ -1249,7 +1249,7 @@ Performs a right rotation operation on "src" and put the result into "dest". ``` - """ Base.ror! + """ ror! @doc doc""" ```rst @@ -1257,7 +1257,7 @@ Performs a right rotation operation on B. ``` - """ Base.ror! + """ ror! @doc doc""" ```rst @@ -1265,7 +1265,7 @@ Performs a right rotation operation. ``` - """ Base.ror + """ ror @doc doc""" ```rst @@ -1277,7 +1277,7 @@ set to "max(I)" and "max(J)" respectively. If the "combine" function is not supplied, duplicates are added by default. ``` - """ Base.sparse + """ sparse @doc doc""" ```rst @@ -1291,7 +1291,7 @@ column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. ``` - """ Base.sparsevec + """ sparsevec @doc doc""" ```rst @@ -1301,7 +1301,7 @@ keys from the dictionary, and the nonzero values are the values from the dictionary. ``` - """ Base.sparsevec + """ sparsevec @doc doc""" ```rst @@ -1309,7 +1309,7 @@ Returns "true" if "S" is sparse, and "false" otherwise. ``` - """ Base.issparse + """ issparse @doc doc""" ```rst @@ -1317,7 +1317,7 @@ Convert an AbstractMatrix "A" into a sparse matrix. ``` - """ Base.sparse + """ sparse @doc doc""" ```rst @@ -1327,7 +1327,7 @@ 1". In julia, sparse vectors are really just sparse matrices with one column. ``` - """ Base.sparsevec + """ sparsevec @doc doc""" ```rst @@ -1335,7 +1335,7 @@ Convert a sparse matrix "S" into a dense matrix. ``` - """ Base.full + """ full @doc doc""" ```rst @@ -1343,7 +1343,7 @@ Returns the number of stored (filled) elements in a sparse matrix. ``` - """ Base.nnz + """ nnz @doc doc""" ```rst @@ -1353,7 +1353,7 @@ not contain any nonzero values. No storage will be allocated for nonzero values during construction. ``` - """ Base.spzeros + """ spzeros @doc doc""" ```rst @@ -1362,7 +1362,7 @@ Create a sparse matrix with the same structure as that of "S", but with every nonzero element having the value "1.0". ``` - """ Base.spones + """ spones @doc doc""" ```rst @@ -1372,7 +1372,7 @@ m". In case "n" is supplied, create a sparse identity matrix of size "m x n". ``` - """ Base.speye + """ speye @doc doc""" ```rst @@ -1386,7 +1386,7 @@ (diagonal). Optionally, "m" and "n" specify the size of the resulting sparse matrix. ``` - """ Base.spdiagm + """ spdiagm @doc doc""" ```rst @@ -1400,7 +1400,7 @@ specified. The optional "rng" argument specifies a random number generator, see *Random Numbers*. ``` - """ Base.sprand + """ sprand @doc doc""" ```rst @@ -1410,7 +1410,7 @@ (independent) probability "p" of any entry being nonzero, where nonzero values are sampled from the normal distribution. ``` - """ Base.sprandn + """ sprandn @doc doc""" ```rst @@ -1420,7 +1420,7 @@ specified (independent) probability "p" of any entry being "true". ``` - """ Base.sprandbool + """ sprandbool @doc doc""" ```rst @@ -1429,7 +1429,7 @@ Compute the elimination tree of a symmetric sparse matrix "A" from "triu(A)" and, optionally, its post-ordering permutation. ``` - """ Base.etree + """ etree @doc doc""" ```rst @@ -1441,7 +1441,7 @@ triangular part of the matrix. Only the upper triangular part of the result is returned as well. ``` - """ Base.symperm + """ symperm @doc doc""" ```rst @@ -1453,7 +1453,7 @@ storage of "A", and any modifications to the returned vector will mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". ``` - """ Base.nonzeros + """ nonzeros @doc doc""" ```rst @@ -1466,7 +1466,7 @@ with iterating over structural nonzero values. See "nonzeros(A)" and "nzrange(A, col)". ``` - """ Base.rowvals + """ rowvals @doc doc""" ```rst @@ -1489,7 +1489,7 @@ end end ``` - """ Base.nzrange + """ nzrange @doc doc""" ```rst @@ -1498,7 +1498,7 @@ Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. ``` - """ Base.exit + """ exit @doc doc""" ```rst @@ -1507,7 +1507,7 @@ Quit the program indicating that the processes completed successfully. This function calls "exit(0)" (see "exit()"). ``` - """ Base.quit + """ quit @doc doc""" ```rst @@ -1515,7 +1515,7 @@ Register a zero-argument function to be called at exit. ``` - """ Base.atexit + """ atexit @doc doc""" ```rst @@ -1527,7 +1527,7 @@ This function should be called from within the ".juliarc.jl" initialization file. ``` - """ Base.atreplinit + """ atreplinit @doc doc""" ```rst @@ -1535,7 +1535,7 @@ Determine whether Julia is running an interactive session. ``` - """ Base.isinteractive + """ isinteractive @doc doc""" ```rst @@ -1544,7 +1544,7 @@ Print information about exported global variables in a module, optionally restricted to those matching "pattern". ``` - """ Base.whos + """ whos @doc doc""" ```rst @@ -1553,7 +1553,7 @@ Edit a file optionally providing a line number to edit at. Returns to the julia prompt when you quit the editor. ``` - """ Base.edit + """ edit @doc doc""" ```rst @@ -1562,7 +1562,7 @@ Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. ``` - """ Base.edit + """ edit @doc doc""" ```rst @@ -1571,7 +1571,7 @@ Evaluates the arguments to the function call, determines their types, and calls the "edit" function on the resulting expression ``` - """ Base.@edit + """ @edit @doc doc""" ```rst @@ -1581,7 +1581,7 @@ starting line number. Returns to the julia prompt when you quit the pager. ``` - """ Base.less + """ less @doc doc""" ```rst @@ -1591,7 +1591,7 @@ optionally specifying a tuple of types to indicate which method to see. ``` - """ Base.less + """ less @doc doc""" ```rst @@ -1600,7 +1600,7 @@ Evaluates the arguments to the function call, determines their types, and calls the "less" function on the resulting expression ``` - """ Base.@less + """ @less @doc doc""" ```rst @@ -1609,7 +1609,7 @@ Send a printed form of "x" to the operating system clipboard ("copy"). ``` - """ Base.clipboard + """ clipboard @doc doc""" ```rst @@ -1618,7 +1618,7 @@ Return a string with the contents of the operating system clipboard ("paste"). ``` - """ Base.clipboard + """ clipboard @doc doc""" ```rst @@ -1636,7 +1636,7 @@ working directory, then looks for package code under "Pkg.dir()", then tries paths in the global array "LOAD_PATH". ``` - """ Base.require + """ require @doc doc""" ```rst @@ -1646,7 +1646,7 @@ whether they have been loaded before. Typically used when interactively developing libraries. ``` - """ Base.reload + """ reload @doc doc""" ```rst @@ -1661,7 +1661,7 @@ combine files in packages that are broken into multiple source files. ``` - """ Base.include + """ include @doc doc""" ```rst @@ -1671,7 +1671,7 @@ than from a file. Since there is no file path involved, no path processing or fetching from node 1 is done. ``` - """ Base.include_string + """ include_string @doc doc""" ```rst @@ -1679,7 +1679,7 @@ Get help for a function. "name" can be an object or a string. ``` - """ Base.help + """ help @doc doc""" ```rst @@ -1687,7 +1687,7 @@ Search documentation for functions related to "string". ``` - """ Base.apropos + """ apropos @doc doc""" ```rst @@ -1699,7 +1699,7 @@ If "types" is an abstract type, then the method that would be called by "invoke" is returned. ``` - """ Base.which + """ which @doc doc""" ```rst @@ -1708,7 +1708,7 @@ Return the module in which the binding for the variable referenced by "symbol" was created. ``` - """ Base.which + """ which @doc doc""" ```rst @@ -1720,7 +1720,7 @@ variable, it returns the module in which the variable was bound. It calls out to the "which" function. ``` - """ Base.@which + """ @which @doc doc""" ```rst @@ -1731,7 +1731,7 @@ If "types" is specified, returns an array of methods whose types match. ``` - """ Base.methods + """ methods @doc doc""" ```rst @@ -1744,7 +1744,7 @@ The optional second argument restricts the search to a particular module or function. ``` - """ Base.methodswith + """ methodswith @doc doc""" ```rst @@ -1752,7 +1752,7 @@ Show an expression and result, returning the result ``` - """ Base.@show + """ @show @doc doc""" ```rst @@ -1762,7 +1762,7 @@ "verbose" argument is true, detailed system information is shown as well. ``` - """ Base.versioninfo + """ versioninfo @doc doc""" ```rst @@ -1775,7 +1775,7 @@ This function should only be used interactively. ``` - """ Base.workspace + """ workspace @doc doc""" ```rst @@ -1789,7 +1789,7 @@ by contents at the bit level. This function is sometimes called "egal". ``` - """ Base.is + """ is @doc doc""" ```rst @@ -1797,7 +1797,7 @@ Determine whether "x" is of the given "type". ``` - """ Base.isa + """ isa @doc doc""" ```rst @@ -1823,7 +1823,7 @@ amenable to a more efficient implementation than that provided as a generic fallback (based on "isnan", "signbit", and "=="). ``` - """ Base.isequal + """ isequal @doc doc""" ```rst @@ -1837,7 +1837,7 @@ only need to implement it if they have special values such as "NaN". ``` - """ Base.isless + """ isless @doc doc""" ```rst @@ -1849,7 +1849,7 @@ "ifelse" instead of an "if" statement can eliminate the branch in generated code and provide higher performance in tight loops. ``` - """ Base.ifelse + """ ifelse @doc doc""" ```rst @@ -1861,7 +1861,7 @@ lexicographically comparable types, and "lexless" will call "lexcmp" by default. ``` - """ Base.lexcmp + """ lexcmp @doc doc""" ```rst @@ -1869,7 +1869,7 @@ Determine whether "x" is lexicographically less than "y". ``` - """ Base.lexless + """ lexless @doc doc""" ```rst @@ -1877,7 +1877,7 @@ Get the concrete type of "x". ``` - """ Base.typeof + """ typeof @doc doc""" ```rst @@ -1885,7 +1885,7 @@ Construct a tuple of the given objects. ``` - """ Base.tuple + """ tuple @doc doc""" ```rst @@ -1894,7 +1894,7 @@ Create a tuple of length "n", computing each element as "f(i)", where "i" is the index of the element. ``` - """ Base.ntuple + """ ntuple @doc doc""" ```rst @@ -1903,7 +1903,7 @@ Get a unique integer id for "x". "object_id(x)==object_id(y)" if and only if "is(x,y)". ``` - """ Base.object_id + """ object_id @doc doc""" ```rst @@ -1920,7 +1920,7 @@ its own "==" (hence "isequal") to guarantee the property mentioned above. ``` - """ Base.hash + """ hash @doc doc""" ```rst @@ -1930,7 +1930,7 @@ program-accessible references to "x". The behavior of this function is unpredictable if "x" is of a bits type. ``` - """ Base.finalizer + """ finalizer @doc doc""" ```rst @@ -1938,7 +1938,7 @@ Immediately run finalizers registered for object "x". ``` - """ Base.finalize + """ finalize @doc doc""" ```rst @@ -1948,7 +1948,7 @@ not all internal values. For example, copying an array produces a new array with identically-same elements as the original. ``` - """ Base.copy + """ copy @doc doc""" ```rst @@ -1974,7 +1974,7 @@ should be used in place of "deepcopy", and the "dict" variable should be updated as appropriate before returning. ``` - """ Base.deepcopy + """ deepcopy @doc doc""" ```rst @@ -1986,7 +1986,7 @@ tests whether a global variable with that name is defined in "current_module()". ``` - """ Base.isdefined + """ isdefined @doc doc""" ```rst @@ -2020,7 +2020,7 @@ julia> convert(Rational{Int64}, x) 6004799503160661//18014398509481984 ``` - """ Base.convert + """ convert @doc doc""" ```rst @@ -2029,7 +2029,7 @@ Convert all arguments to their common promotion type (if any), and return them all (as a tuple). ``` - """ Base.promote + """ promote @doc doc""" ```rst @@ -2037,7 +2037,7 @@ Convert "y" to the type of "x" ("convert(typeof(x), y)"). ``` - """ Base.oftype + """ oftype @doc doc""" ```rst @@ -2054,7 +2054,7 @@ julia> widen(1.5f0) 1.5 ``` - """ Base.widen + """ widen @doc doc""" ```rst @@ -2062,7 +2062,7 @@ The identity function. Returns its argument. ``` - """ Base.identity + """ identity @doc doc""" ```rst @@ -2070,7 +2070,7 @@ Return the supertype of DataType T ``` - """ Base.super + """ super @doc doc""" ```rst @@ -2080,7 +2080,7 @@ Can also be written using the "<:" infix operator as "type1 <: type2". ``` - """ Base.issubtype + """ issubtype @doc doc""" ```rst @@ -2098,7 +2098,7 @@ currently loaded subtypes are included, including those not visible in the current module. ``` - """ Base.subtypes + """ subtypes @doc doc""" ```rst @@ -2106,7 +2106,7 @@ The lowest value representable by the given (real) numeric type. ``` - """ Base.typemin + """ typemin @doc doc""" ```rst @@ -2114,7 +2114,7 @@ The highest value representable by the given (real) numeric type. ``` - """ Base.typemax + """ typemax @doc doc""" ```rst @@ -2123,7 +2123,7 @@ The smallest in absolute value non-subnormal value representable by the given floating-point type ``` - """ Base.realmin + """ realmin @doc doc""" ```rst @@ -2132,7 +2132,7 @@ The highest finite value representable by the given floating-point type ``` - """ Base.realmax + """ realmax @doc doc""" ```rst @@ -2141,7 +2141,7 @@ The largest integer losslessly representable by the given floating- point type ``` - """ Base.maxintfloat + """ maxintfloat @doc doc""" ```rst @@ -2150,7 +2150,7 @@ Size, in bytes, of the canonical binary representation of the given type, if any. ``` - """ Base.sizeof + """ sizeof @doc doc""" ```rst @@ -2161,7 +2161,7 @@ sensible arguments. If "type" is omitted, then "eps(Float64)" is returned. ``` - """ Base.eps + """ eps @doc doc""" ```rst @@ -2170,7 +2170,7 @@ The distance between "x" and the next larger representable floating-point value of the same type as "x". ``` - """ Base.eps + """ eps @doc doc""" ```rst @@ -2183,7 +2183,7 @@ "Float64" even though strictly, not all "Int64" values can be represented exactly as "Float64" values. ``` - """ Base.promote_type + """ promote_type @doc doc""" ```rst @@ -2194,7 +2194,7 @@ called directly, but should have definitions added to it for new types as appropriate. ``` - """ Base.promote_rule + """ promote_rule @doc doc""" ```rst @@ -2204,7 +2204,7 @@ "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls "getfield(a, b)". ``` - """ Base.getfield + """ getfield @doc doc""" ```rst @@ -2214,7 +2214,7 @@ syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax "a.(b) = c" calls "setfield!(a, b, c)". ``` - """ Base.setfield! + """ setfield! @doc doc""" ```rst @@ -2241,7 +2241,7 @@ (80,:mtime,Float64) (88,:ctime,Float64) ``` - """ Base.fieldoffsets + """ fieldoffsets @doc doc""" ```rst @@ -2250,7 +2250,7 @@ Determine the declared type of a field (specified by name or index) in a composite type. ``` - """ Base.fieldtype + """ fieldtype @doc doc""" ```rst @@ -2261,7 +2261,7 @@ values, so if you give it a type, it will tell you that a value of "DataType" is mutable. ``` - """ Base.isimmutable + """ isimmutable @doc doc""" ```rst @@ -2278,7 +2278,7 @@ julia> isbits(Complex) false ``` - """ Base.isbits + """ isbits @doc doc""" ```rst @@ -2288,7 +2288,7 @@ meaning its only subtypes are itself and "None" (but "T" itself is not "None"). ``` - """ Base.isleaftype + """ isleaftype @doc doc""" ```rst @@ -2296,7 +2296,7 @@ Compute a type that contains both "T" and "S". ``` - """ Base.typejoin + """ typejoin @doc doc""" ```rst @@ -2305,7 +2305,7 @@ Compute a type that contains the intersection of "T" and "S". Usually this will be the smallest such type or one close to it. ``` - """ Base.typeintersect + """ typeintersect @doc doc""" ```rst @@ -2314,7 +2314,7 @@ Return a collection of all instances of the given type, if applicable. Mostly used for enumerated types (see "@enum"). ``` - """ Base.instances + """ instances @doc doc""" ```rst @@ -2326,7 +2326,7 @@ julia> method_exists(length, Tuple{Array}) true ``` - """ Base.method_exists + """ method_exists @doc doc""" ```rst @@ -2345,7 +2345,7 @@ julia> applicable(f, 1, 2) true ``` - """ Base.applicable + """ applicable @doc doc""" ```rst @@ -2359,7 +2359,7 @@ explicitly needed (often as part of the implementation of a more specific method of the same function). ``` - """ Base.invoke + """ invoke @doc doc""" ```rst @@ -2381,7 +2381,7 @@ to "call(x, args...)". This means that function-like behavior can be added to any type by defining new "call" methods. ``` - """ Base.call + """ call @doc doc""" ```rst @@ -2392,7 +2392,7 @@ 1-argument definition of "eval", which evaluates expressions in that module. ``` - """ Base.eval + """ eval @doc doc""" ```rst @@ -2400,7 +2400,7 @@ Evaluate an expression and return the value. ``` - """ Base.@eval + """ @eval @doc doc""" ```rst @@ -2409,7 +2409,7 @@ Load the file using "include", evaluate all expressions, and return the value of the last one. ``` - """ Base.evalfile + """ evalfile @doc doc""" ```rst @@ -2421,7 +2421,7 @@ Metaprogramming chapter of the manual for more details and examples. ``` - """ Base.esc + """ esc @doc doc""" ```rst @@ -2430,7 +2430,7 @@ Generates a symbol which will not conflict with other variable names. ``` - """ Base.gensym + """ gensym @doc doc""" ```rst @@ -2439,7 +2439,7 @@ Generates a gensym symbol for a variable. For example, "@gensym x y" is transformed into "x = gensym("x"); y = gensym("y")". ``` - """ Base.@gensym + """ @gensym @doc doc""" ```rst @@ -2456,7 +2456,7 @@ will raise an error. If "raise" is false, "parse" will return an expression that will raise an error upon evaluation. ``` - """ Base.parse + """ parse @doc doc""" ```rst @@ -2468,7 +2468,7 @@ raise an error; otherwise, "parse" will return an expression that will raise an error upon evaluation. ``` - """ Base.parse + """ parse @doc doc""" ```rst @@ -2479,7 +2479,7 @@ wrapper, and "Nullable{T}()" yields an empty instance of a wrapper that might contain a value of type "T". ``` - """ Base.Nullable + """ Nullable @doc doc""" ```rst @@ -2489,7 +2489,7 @@ Returns the value if it is present; otherwise, throws a "NullException". ``` - """ Base.get + """ get @doc doc""" ```rst @@ -2499,7 +2499,7 @@ Returns the value if it is present; otherwise, returns "convert(T, y)". ``` - """ Base.get + """ get @doc doc""" ```rst @@ -2507,7 +2507,7 @@ Is the "Nullable" object "x" null, i.e. missing a value? ``` - """ Base.isnull + """ isnull @doc doc""" ```rst @@ -2517,7 +2517,7 @@ if anything goes wrong, including the process exiting with a non- zero status. ``` - """ Base.run + """ run @doc doc""" ```rst @@ -2526,7 +2526,7 @@ Run a command object asynchronously, returning the resulting "Process" object. ``` - """ Base.spawn + """ spawn @doc doc""" ```rst @@ -2536,7 +2536,7 @@ Essentially equivalent to /dev/null on Unix or NUL on Windows. Usage: "run(`cat test.txt` |> DevNull)" ``` - """ Base.DevNull + """ DevNull @doc doc""" ```rst @@ -2546,7 +2546,7 @@ it was successful (exited with a code of 0). An exception is raised if the process cannot be started. ``` - """ Base.success + """ success @doc doc""" ```rst @@ -2554,7 +2554,7 @@ Determine whether a process is currently running. ``` - """ Base.process_running + """ process_running @doc doc""" ```rst @@ -2562,7 +2562,7 @@ Determine whether a process has exited. ``` - """ Base.process_exited + """ process_exited @doc doc""" ```rst @@ -2571,7 +2571,7 @@ Send a signal to a process. The default is to terminate the process. ``` - """ Base.kill + """ kill @doc doc""" ```rst @@ -2585,7 +2585,7 @@ and "stdio" optionally specifies the process's standard output stream. ``` - """ Base.open + """ open @doc doc""" ```rst @@ -2596,7 +2596,7 @@ waits for the process to complete. Returns the value returned by "f". ``` - """ Base.open + """ open @doc doc""" ```rst @@ -2605,7 +2605,7 @@ Set the process title. No-op on some operating systems. (not exported) ``` - """ Base.Sys + """ Sys @doc doc""" ```rst @@ -2614,7 +2614,7 @@ Get the process title. On some systems, will always return empty string. (not exported) ``` - """ Base.Sys + """ Sys @doc doc""" ```rst @@ -2624,7 +2624,7 @@ (stdout,stdin,process) of the output stream and input stream of the process, and the process object itself. ``` - """ Base.readandwrite + """ readandwrite @doc doc""" ```rst @@ -2633,7 +2633,7 @@ Mark a command object so that running it will not throw an error if the result code is non-zero. ``` - """ Base.ignorestatus + """ ignorestatus @doc doc""" ```rst @@ -2643,7 +2643,7 @@ group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. ``` - """ Base.detach + """ detach @doc doc""" ```rst @@ -2660,7 +2660,7 @@ The "dir" keyword argument can be used to specify a working directory for the command. ``` - """ Base.setenv + """ setenv @doc doc""" ```rst @@ -2674,7 +2674,7 @@ set). When "withenv" returns, the original environment has been restored. ``` - """ Base.withenv + """ withenv @doc doc""" ```rst @@ -2695,7 +2695,7 @@ * "run(pipe("out.txt", `grep xyz`))" ``` - """ Base.pipe + """ pipe @doc doc""" ```rst @@ -2715,7 +2715,7 @@ * "run(pipe(`update`, stdout="log.txt", append=true))" ``` - """ Base.pipe + """ pipe @doc doc""" ```rst @@ -2723,7 +2723,7 @@ Get the local machine's host name. ``` - """ Base.gethostname + """ gethostname @doc doc""" ```rst @@ -2732,7 +2732,7 @@ Get the IP address of the local machine, as a string of the form "x.x.x.x". ``` - """ Base.getipaddr + """ getipaddr @doc doc""" ```rst @@ -2740,7 +2740,7 @@ Get julia's process ID. ``` - """ Base.getpid + """ getpid @doc doc""" ```rst @@ -2749,7 +2749,7 @@ Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. ``` - """ Base.time + """ time @doc doc""" ```rst @@ -2758,7 +2758,7 @@ Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. ``` - """ Base.time_ns + """ time_ns @doc doc""" ```rst @@ -2767,7 +2767,7 @@ Set a timer to be read by the next call to "toc()" or "toq()". The macro call "@time expr" can also be used to time evaluation. ``` - """ Base.tic + """ tic @doc doc""" ```rst @@ -2775,7 +2775,7 @@ Print and return the time elapsed since the last "tic()". ``` - """ Base.toc + """ toc @doc doc""" ```rst @@ -2784,7 +2784,7 @@ Return, but do not print, the time elapsed since the last "tic()". ``` - """ Base.toq + """ toq @doc doc""" ```rst @@ -2795,7 +2795,7 @@ its execution caused to be allocated, before returning the value of the expression. ``` - """ Base.@time + """ @time @doc doc""" ```rst @@ -2805,7 +2805,7 @@ the same information as "@time", then any non-zero memory allocation counters, and then returns the value of the expression. ``` - """ Base.@timev + """ @timev @doc doc""" ```rst @@ -2815,7 +2815,7 @@ expression, elapsed time, total bytes allocated, garbage collection time, and an object with various memory allocation counters. ``` - """ Base.@timed + """ @timed @doc doc""" ```rst @@ -2825,7 +2825,7 @@ instead returning the number of seconds it took to execute as a floating-point number. ``` - """ Base.@elapsed + """ @elapsed @doc doc""" ```rst @@ -2840,7 +2840,7 @@ results inconsistent with the "@time" macros, which do not try to adjust for the effects of compilation. ``` - """ Base.@allocated + """ @allocated @doc doc""" ```rst @@ -2849,7 +2849,7 @@ A singleton of this type provides a hash table interface to environment variables. ``` - """ Base.EnvHash + """ EnvHash @doc doc""" ```rst @@ -2858,7 +2858,7 @@ Reference to the singleton "EnvHash", providing a dictionary interface to system environment variables. ``` - """ Base.ENV + """ ENV @doc doc""" ```rst @@ -2869,7 +2869,7 @@ Platform Variations in the Calling C and Fortran Code section of the manual. ``` - """ Base.@unix + """ @unix @doc doc""" ```rst @@ -2879,7 +2879,7 @@ documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. ``` - """ Base.@osx + """ @osx @doc doc""" ```rst @@ -2889,7 +2889,7 @@ documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. ``` - """ Base.@linux + """ @linux @doc doc""" ```rst @@ -2899,7 +2899,7 @@ See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. ``` - """ Base.@windows + """ @windows @doc doc""" ```rst @@ -2907,7 +2907,7 @@ Raise an "ErrorException" with the given message ``` - """ Base.error + """ error @doc doc""" ```rst @@ -2915,7 +2915,7 @@ Throw an object as an exception ``` - """ Base.throw + """ throw @doc doc""" ```rst @@ -2925,7 +2925,7 @@ The default argument is the current exception (if called within a "catch" block). ``` - """ Base.rethrow + """ rethrow @doc doc""" ```rst @@ -2933,7 +2933,7 @@ Get a backtrace object for the current program point. ``` - """ Base.backtrace + """ backtrace @doc doc""" ```rst @@ -2942,7 +2942,7 @@ Get the backtrace of the current exception, for use within "catch" blocks. ``` - """ Base.catch_backtrace + """ catch_backtrace @doc doc""" ```rst @@ -2951,7 +2951,7 @@ Throw an "AssertionError" if "cond" is false. Also available as the macro "@assert expr". ``` - """ Base.assert + """ assert @doc doc""" ```rst @@ -2959,7 +2959,7 @@ The parameters to a function call do not match a valid signature. ``` - """ Base.ArgumentError + """ ArgumentError @doc doc""" ```rst @@ -2967,7 +2967,7 @@ The asserted condition did not evalutate to "true". ``` - """ Base.AssertionError + """ AssertionError @doc doc""" ```rst @@ -2976,7 +2976,7 @@ An indexing operation into an array, "a", tried to access an out- of-bounds element, "i". ``` - """ Base.BoundsError + """ BoundsError @doc doc""" ```rst @@ -2984,7 +2984,7 @@ The objects called do not have matching dimensionality. ``` - """ Base.DimensionMismatch + """ DimensionMismatch @doc doc""" ```rst @@ -2992,7 +2992,7 @@ Integer division was attempted with a denominator value of 0. ``` - """ Base.DivideError + """ DivideError @doc doc""" ```rst @@ -3001,7 +3001,7 @@ The arguments to a function or constructor are outside the valid domain. ``` - """ Base.DomainError + """ DomainError @doc doc""" ```rst @@ -3009,7 +3009,7 @@ No more data was available to read from a file or stream. ``` - """ Base.EOFError + """ EOFError @doc doc""" ```rst @@ -3018,7 +3018,7 @@ Generic error type. The error message, in the *.msg* field, may provide more specific details. ``` - """ Base.ErrorException + """ ErrorException @doc doc""" ```rst @@ -3026,7 +3026,7 @@ Type conversion cannot be done exactly. ``` - """ Base.InexactError + """ InexactError @doc doc""" ```rst @@ -3034,7 +3034,7 @@ The process was stopped by a terminal interrupt (CTRL+C). ``` - """ Base.InterruptException + """ InterruptException @doc doc""" ```rst @@ -3043,7 +3043,7 @@ An indexing operation into an "Associative" ("Dict") or "Set" like object tried to access or delete a non-existent element. ``` - """ Base.KeyError + """ KeyError @doc doc""" ```rst @@ -3053,7 +3053,7 @@ file. The error specifics should be available in the *.error* field. ``` - """ Base.LoadError + """ LoadError @doc doc""" ```rst @@ -3062,7 +3062,7 @@ A method with the required type signature does not exist in the given generic function. ``` - """ Base.MethodError + """ MethodError @doc doc""" ```rst @@ -3070,7 +3070,7 @@ An attempted access to a "Nullable" with no defined value. ``` - """ Base.NullException + """ NullException @doc doc""" ```rst @@ -3079,7 +3079,7 @@ An operation allocated too much memory for either the system or the garbage collector to handle properly. ``` - """ Base.OutOfMemoryError + """ OutOfMemoryError @doc doc""" ```rst @@ -3087,7 +3087,7 @@ An operation tried to write to memory that is read-only. ``` - """ Base.ReadOnlyMemoryError + """ ReadOnlyMemoryError @doc doc""" ```rst @@ -3096,7 +3096,7 @@ The result of an expression is too large for the specified type and will cause a wraparound. ``` - """ Base.OverflowError + """ OverflowError @doc doc""" ```rst @@ -3105,7 +3105,7 @@ The expression passed to the *parse* function could not be interpreted as a valid Julia expression. ``` - """ Base.ParseError + """ ParseError @doc doc""" ```rst @@ -3114,7 +3114,7 @@ After a client Julia process has exited, further attempts to reference the dead child will throw this exception. ``` - """ Base.ProcessExitedException + """ ProcessExitedException @doc doc""" ```rst @@ -3123,7 +3123,7 @@ The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. ``` - """ Base.StackOverflowError + """ StackOverflowError @doc doc""" ```rst @@ -3132,7 +3132,7 @@ A system call failed with an error code (in the "errno" global variable). ``` - """ Base.SystemError + """ SystemError @doc doc""" ```rst @@ -3141,7 +3141,7 @@ A type assertion failure, or calling an intrinsic function with an incorrect argument type. ``` - """ Base.TypeError + """ TypeError @doc doc""" ```rst @@ -3149,7 +3149,7 @@ The item or field is not defined for the given object. ``` - """ Base.UndefRefError + """ UndefRefError @doc doc""" ```rst @@ -3157,7 +3157,7 @@ A symbol in the current scope is not defined. ``` - """ Base.UndefVarError + """ UndefVarError @doc doc""" ```rst @@ -3170,7 +3170,7 @@ only triggered once. Times are in seconds. A timer is stopped and has its resources freed by calling "close" on it. ``` - """ Base.Timer + """ Timer @doc doc""" ```rst @@ -3179,7 +3179,7 @@ Create a timer that wakes up tasks waiting for it (by calling "wait" on the timer object) at a specified interval. ``` - """ Base.Timer + """ Timer @doc doc""" ```rst @@ -3187,7 +3187,7 @@ Get the name of a module as a symbol. ``` - """ Base.module_name + """ module_name @doc doc""" ```rst @@ -3195,7 +3195,7 @@ Get a module's enclosing module. "Main" is its own parent. ``` - """ Base.module_parent + """ module_parent @doc doc""" ```rst @@ -3205,7 +3205,7 @@ currently being read from. In general, this is not the same as the module containing the call to this function. ``` - """ Base.current_module + """ current_module @doc doc""" ```rst @@ -3215,7 +3215,7 @@ example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and "fullname(Main)" gives "()". ``` - """ Base.fullname + """ fullname @doc doc""" ```rst @@ -3224,7 +3224,7 @@ Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. ``` - """ Base.names + """ names @doc doc""" ```rst @@ -3232,7 +3232,7 @@ Get the number of fields of a data type. ``` - """ Base.nfields + """ nfields @doc doc""" ```rst @@ -3240,7 +3240,7 @@ Get an array of the fields of a data type. ``` - """ Base.fieldnames + """ fieldnames @doc doc""" ```rst @@ -3249,7 +3249,7 @@ Determine whether a global is declared "const" in a given module. The default module argument is "current_module()". ``` - """ Base.isconst + """ isconst @doc doc""" ```rst @@ -3257,7 +3257,7 @@ Determine whether a function is generic. ``` - """ Base.isgeneric + """ isgeneric @doc doc""" ```rst @@ -3265,7 +3265,7 @@ Get the name of a generic function as a symbol, or ":anonymous". ``` - """ Base.function_name + """ function_name @doc doc""" ```rst @@ -3274,7 +3274,7 @@ Determine the module containing a given definition of a generic function. ``` - """ Base.function_module + """ function_module @doc doc""" ```rst @@ -3283,7 +3283,7 @@ Returns a tuple "(filename,line)" giving the location of a method definition. ``` - """ Base.functionloc + """ functionloc @doc doc""" ```rst @@ -3292,7 +3292,7 @@ Returns a tuple "(filename,line)" giving the location of a method definition. ``` - """ Base.functionloc + """ functionloc @doc doc""" ```rst @@ -3300,7 +3300,7 @@ Perform garbage collection. This should not generally be used. ``` - """ Base.gc + """ gc @doc doc""" ```rst @@ -3311,7 +3311,7 @@ GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. ``` - """ Base.gc_enable + """ gc_enable @doc doc""" ```rst @@ -3320,7 +3320,7 @@ Takes the expression x and returns an equivalent expression with all macros removed (expanded). ``` - """ Base.macroexpand + """ macroexpand @doc doc""" ```rst @@ -3329,7 +3329,7 @@ Takes the expression x and returns an equivalent expression in lowered form ``` - """ Base.expand + """ expand @doc doc""" ```rst @@ -3338,7 +3338,7 @@ Returns an array of lowered ASTs for the methods matching the given generic function and type signature. ``` - """ Base.code_lowered + """ code_lowered @doc doc""" ```rst @@ -3347,7 +3347,7 @@ Evaluates the arguments to the function call, determines their types, and calls "code_lowered()" on the resulting expression ``` - """ Base.@code_lowered + """ @code_lowered @doc doc""" ```rst @@ -3358,7 +3358,7 @@ argument "optimize" controls whether additional optimizations, such as inlining, are also applied. ``` - """ Base.code_typed + """ code_typed @doc doc""" ```rst @@ -3367,7 +3367,7 @@ Evaluates the arguments to the function call, determines their types, and calls "code_typed()" on the resulting expression ``` - """ Base.@code_typed + """ @code_typed @doc doc""" ```rst @@ -3381,7 +3381,7 @@ are particularly problematic for performance, so the results need to be used judiciously. See *@code_warntype* for more information. ``` - """ Base.code_warntype + """ code_warntype @doc doc""" ```rst @@ -3390,7 +3390,7 @@ Evaluates the arguments to the function call, determines their types, and calls "code_warntype()" on the resulting expression ``` - """ Base.@code_warntype + """ @code_warntype @doc doc""" ```rst @@ -3402,7 +3402,7 @@ All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. ``` - """ Base.code_llvm + """ code_llvm @doc doc""" ```rst @@ -3411,7 +3411,7 @@ Evaluates the arguments to the function call, determines their types, and calls "code_llvm()" on the resulting expression ``` - """ Base.@code_llvm + """ @code_llvm @doc doc""" ```rst @@ -3421,7 +3421,7 @@ method matching the given generic function and type signature to STDOUT. ``` - """ Base.code_native + """ code_native @doc doc""" ```rst @@ -3430,7 +3430,7 @@ Evaluates the arguments to the function call, determines their types, and calls "code_native()" on the resulting expression ``` - """ Base.@code_native + """ @code_native @doc doc""" ```rst @@ -3439,7 +3439,7 @@ Compile the given function "f" for the argument tuple (of types) "args", but do not execute it. ``` - """ Base.precompile + """ precompile @doc doc""" ```rst @@ -3473,7 +3473,7 @@ supplied. The values can be read or written by "unsafe_load" or "unsafe_store!", respectively. ``` - """ Base.cglobal + """ cglobal @doc doc""" ```rst @@ -3494,7 +3494,7 @@ bar = cfunction(foo, Float64, ()) ``` - """ Base.cfunction + """ cfunction @doc doc""" ```rst @@ -3518,7 +3518,7 @@ behavior, including program corruption or segfaults, at any later time. ``` - """ Base.unsafe_convert + """ unsafe_convert @doc doc""" ```rst @@ -3535,7 +3535,7 @@ Neither "convert" nor "cconvert" should take a Julia object and turn it into a "Ptr". ``` - """ Base.cconvert + """ cconvert @doc doc""" ```rst @@ -3550,7 +3550,7 @@ Incorrect usage may segfault your program or return garbage answers, in the same manner as C. ``` - """ Base.unsafe_load + """ unsafe_load @doc doc""" ```rst @@ -3565,7 +3565,7 @@ Incorrect usage may corrupt or segfault your program, in the same manner as C. ``` - """ Base.unsafe_store! + """ unsafe_store! @doc doc""" ```rst @@ -3580,7 +3580,7 @@ they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. ``` - """ Base.unsafe_copy! + """ unsafe_copy! @doc doc""" ```rst @@ -3595,7 +3595,7 @@ Incorrect usage may corrupt or segfault your program, in the same manner as C. ``` - """ Base.unsafe_copy! + """ unsafe_copy! @doc doc""" ```rst @@ -3604,7 +3604,7 @@ Copy all elements from collection "src" to array "dest". Returns "dest". ``` - """ Base.copy! + """ copy! @doc doc""" ```rst @@ -3614,7 +3614,7 @@ "so", to array "dest" starting at offset "do". Returns "dest". ``` - """ Base.copy! + """ copy! @doc doc""" ```rst @@ -3628,7 +3628,7 @@ Calling "Ref(array[, index])" is generally preferable to this function. ``` - """ Base.pointer + """ pointer @doc doc""" ```rst @@ -3640,7 +3640,7 @@ calling "free" on the pointer when the array is no longer referenced. ``` - """ Base.pointer_to_array + """ pointer_to_array @doc doc""" ```rst @@ -3651,7 +3651,7 @@ garbage collection, so you must ensure that the object remains referenced for the whole time that the "Ptr" will be used. ``` - """ Base.pointer_from_objref + """ pointer_from_objref @doc doc""" ```rst @@ -3662,7 +3662,7 @@ case, undefined behavior results, hence this function is considered "unsafe" and should be used with care. ``` - """ Base.unsafe_pointer_to_objref + """ unsafe_pointer_to_objref @doc doc""" ```rst @@ -3677,7 +3677,7 @@ ... end ``` - """ Base.disable_sigint + """ disable_sigint @doc doc""" ```rst @@ -3686,7 +3686,7 @@ Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of "disable_sigint". ``` - """ Base.reenable_sigint + """ reenable_sigint @doc doc""" ```rst @@ -3695,7 +3695,7 @@ Raises a "SystemError" for "errno" with the descriptive string "sysfunc" if "bool" is true ``` - """ Base.systemerror + """ systemerror @doc doc""" ```rst @@ -3703,7 +3703,7 @@ Equivalent to the native "char" c-type ``` - """ Base.Cchar + """ Cchar @doc doc""" ```rst @@ -3711,7 +3711,7 @@ Equivalent to the native "unsigned char" c-type (UInt8) ``` - """ Base.Cuchar + """ Cuchar @doc doc""" ```rst @@ -3719,7 +3719,7 @@ Equivalent to the native "signed short" c-type (Int16) ``` - """ Base.Cshort + """ Cshort @doc doc""" ```rst @@ -3727,7 +3727,7 @@ Equivalent to the native "unsigned short" c-type (UInt16) ``` - """ Base.Cushort + """ Cushort @doc doc""" ```rst @@ -3735,7 +3735,7 @@ Equivalent to the native "signed int" c-type (Int32) ``` - """ Base.Cint + """ Cint @doc doc""" ```rst @@ -3743,7 +3743,7 @@ Equivalent to the native "unsigned int" c-type (UInt32) ``` - """ Base.Cuint + """ Cuint @doc doc""" ```rst @@ -3751,7 +3751,7 @@ Equivalent to the native "signed long" c-type ``` - """ Base.Clong + """ Clong @doc doc""" ```rst @@ -3759,7 +3759,7 @@ Equivalent to the native "unsigned long" c-type ``` - """ Base.Culong + """ Culong @doc doc""" ```rst @@ -3767,7 +3767,7 @@ Equivalent to the native "signed long long" c-type (Int64) ``` - """ Base.Clonglong + """ Clonglong @doc doc""" ```rst @@ -3775,7 +3775,7 @@ Equivalent to the native "unsigned long long" c-type (UInt64) ``` - """ Base.Culonglong + """ Culonglong @doc doc""" ```rst @@ -3783,7 +3783,7 @@ Equivalent to the native "intmax_t" c-type (Int64) ``` - """ Base.Cintmax_t + """ Cintmax_t @doc doc""" ```rst @@ -3791,7 +3791,7 @@ Equivalent to the native "uintmax_t" c-type (UInt64) ``` - """ Base.Cuintmax_t + """ Cuintmax_t @doc doc""" ```rst @@ -3799,7 +3799,7 @@ Equivalent to the native "size_t" c-type (UInt) ``` - """ Base.Csize_t + """ Csize_t @doc doc""" ```rst @@ -3807,7 +3807,7 @@ Equivalent to the native "ssize_t" c-type ``` - """ Base.Cssize_t + """ Cssize_t @doc doc""" ```rst @@ -3815,7 +3815,7 @@ Equivalent to the native "ptrdiff_t" c-type (Int) ``` - """ Base.Cptrdiff_t + """ Cptrdiff_t @doc doc""" ```rst @@ -3823,7 +3823,7 @@ Equivalent to the native "off_t" c-type ``` - """ Base.Coff_t + """ Coff_t @doc doc""" ```rst @@ -3831,7 +3831,7 @@ Equivalent to the native "wchar_t" c-type (Int32) ``` - """ Base.Cwchar_t + """ Cwchar_t @doc doc""" ```rst @@ -3839,7 +3839,7 @@ Equivalent to the native "float" c-type (Float32) ``` - """ Base.Cfloat + """ Cfloat @doc doc""" ```rst @@ -3847,7 +3847,7 @@ Equivalent to the native "double" c-type (Float64) ``` - """ Base.Cdouble + """ Cdouble @doc doc""" ```rst @@ -3855,7 +3855,7 @@ Get initial iteration state for an iterable object ``` - """ Base.start + """ start @doc doc""" ```rst @@ -3863,7 +3863,7 @@ Test whether we are done iterating ``` - """ Base.done + """ done @doc doc""" ```rst @@ -3872,7 +3872,7 @@ For a given iterable object and iteration state, return the current item and the next iteration state ``` - """ Base.next + """ next @doc doc""" ```rst @@ -3885,7 +3885,7 @@ Note that "zip()" is its own inverse: "collect(zip(zip(a...)...)) == collect(a)". ``` - """ Base.zip + """ zip @doc doc""" ```rst @@ -3905,7 +3905,7 @@ 2 b 3 c ``` - """ Base.enumerate + """ enumerate @doc doc""" ```rst @@ -3914,7 +3914,7 @@ An iterator that yields the same elements as "iter", but starting at the given "state". ``` - """ Base.rest + """ rest @doc doc""" ```rst @@ -3923,7 +3923,7 @@ An iterator that counts forever, starting at "start" and incrementing by "step". ``` - """ Base.countfrom + """ countfrom @doc doc""" ```rst @@ -3932,7 +3932,7 @@ An iterator that generates at most the first "n" elements of "iter". ``` - """ Base.take + """ take @doc doc""" ```rst @@ -3941,7 +3941,7 @@ An iterator that generates all but the first "n" elements of "iter". ``` - """ Base.drop + """ drop @doc doc""" ```rst @@ -3949,7 +3949,7 @@ An iterator that cycles through "iter" forever. ``` - """ Base.cycle + """ cycle @doc doc""" ```rst @@ -3959,7 +3959,7 @@ specified, generates "x" that many times (equivalent to "take(repeated(x), n)"). ``` - """ Base.repeated + """ repeated @doc doc""" ```rst @@ -3973,7 +3973,7 @@ julia> isempty([1 2 3]) false ``` - """ Base.isempty + """ isempty @doc doc""" ```rst @@ -3981,7 +3981,7 @@ Remove all elements from a "collection". ``` - """ Base.empty! + """ empty! @doc doc""" ```rst @@ -3991,7 +3991,7 @@ which "getindex(collection, i)" is valid. For unordered collections, the number of elements. ``` - """ Base.length + """ length @doc doc""" ```rst @@ -4002,7 +4002,7 @@ julia> endof([1,2,4]) 3 ``` - """ Base.endof + """ endof @doc doc""" ```rst @@ -4034,7 +4034,7 @@ that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types. ``` - """ Base.eltype + """ eltype @doc doc""" ```rst @@ -4044,7 +4044,7 @@ value in "a" that is a member of "b" . The output vector contains 0 wherever "a" is not a member of "b". ``` - """ Base.indexin + """ indexin @doc doc""" ```rst @@ -4053,7 +4053,7 @@ Returns the indices of elements in collection "a" that appear in collection "b" ``` - """ Base.findin + """ findin @doc doc""" ```rst @@ -4064,7 +4064,7 @@ equivalent elements originally appears. If "dim" is specified, returns unique regions of the array "itr" along "dim". ``` - """ Base.unique + """ unique @doc doc""" ```rst @@ -4091,7 +4091,7 @@ of Julia might change the algorithm. Note that the elements are not reordered if you use an ordered collection. ``` - """ Base.reduce + """ reduce @doc doc""" ```rst @@ -4102,7 +4102,7 @@ of "+", "*", "max", "min", "&", "|") when Julia can determine the neutral element of "op". ``` - """ Base.reduce + """ reduce @doc doc""" ```rst @@ -4111,7 +4111,7 @@ Like "reduce()", but with guaranteed left associativity. "v0" will be used exactly once. ``` - """ Base.foldl + """ foldl @doc doc""" ```rst @@ -4121,7 +4121,7 @@ as "v0". In general, this cannot be used with empty collections (see "reduce(op, itr)"). ``` - """ Base.foldl + """ foldl @doc doc""" ```rst @@ -4130,7 +4130,7 @@ Like "reduce()", but with guaranteed right associativity. "v0" will be used exactly once. ``` - """ Base.foldr + """ foldr @doc doc""" ```rst @@ -4140,7 +4140,7 @@ as "v0". In general, this cannot be used with empty collections (see "reduce(op, itr)"). ``` - """ Base.foldr + """ foldr @doc doc""" ```rst @@ -4148,7 +4148,7 @@ Returns the largest element in a collection. ``` - """ Base.maximum + """ maximum @doc doc""" ```rst @@ -4156,7 +4156,7 @@ Compute the maximum value of an array over the given dimensions. ``` - """ Base.maximum + """ maximum @doc doc""" ```rst @@ -4165,7 +4165,7 @@ Compute the maximum value of "A" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.maximum! + """ maximum! @doc doc""" ```rst @@ -4173,7 +4173,7 @@ Returns the smallest element in a collection. ``` - """ Base.minimum + """ minimum @doc doc""" ```rst @@ -4181,7 +4181,7 @@ Compute the minimum value of an array over the given dimensions. ``` - """ Base.minimum + """ minimum @doc doc""" ```rst @@ -4190,7 +4190,7 @@ Compute the minimum value of "A" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.minimum! + """ minimum! @doc doc""" ```rst @@ -4199,7 +4199,7 @@ Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. ``` - """ Base.extrema + """ extrema @doc doc""" ```rst @@ -4207,7 +4207,7 @@ Returns the index of the maximum element in a collection. ``` - """ Base.indmax + """ indmax @doc doc""" ```rst @@ -4215,7 +4215,7 @@ Returns the index of the minimum element in a collection. ``` - """ Base.indmin + """ indmin @doc doc""" ```rst @@ -4223,7 +4223,7 @@ Returns the maximum element and its index. ``` - """ Base.findmax + """ findmax @doc doc""" ```rst @@ -4232,7 +4232,7 @@ For an array input, returns the value and index of the maximum over the given dimensions. ``` - """ Base.findmax + """ findmax @doc doc""" ```rst @@ -4240,7 +4240,7 @@ Returns the minimum element and its index. ``` - """ Base.findmin + """ findmin @doc doc""" ```rst @@ -4249,7 +4249,7 @@ For an array input, returns the value and index of the minimum over the given dimensions. ``` - """ Base.findmin + """ findmin @doc doc""" ```rst @@ -4257,7 +4257,7 @@ Compute the maximum absolute value of a collection of values. ``` - """ Base.maxabs + """ maxabs @doc doc""" ```rst @@ -4265,7 +4265,7 @@ Compute the maximum absolute values over given dimensions. ``` - """ Base.maxabs + """ maxabs @doc doc""" ```rst @@ -4274,7 +4274,7 @@ Compute the maximum absolute values over the singleton dimensions of "r", and write values to "r". ``` - """ Base.maxabs! + """ maxabs! @doc doc""" ```rst @@ -4282,7 +4282,7 @@ Compute the minimum absolute value of a collection of values. ``` - """ Base.minabs + """ minabs @doc doc""" ```rst @@ -4290,7 +4290,7 @@ Compute the minimum absolute values over given dimensions. ``` - """ Base.minabs + """ minabs @doc doc""" ```rst @@ -4299,7 +4299,7 @@ Compute the minimum absolute values over the singleton dimensions of "r", and write values to "r". ``` - """ Base.minabs! + """ minabs! @doc doc""" ```rst @@ -4307,7 +4307,7 @@ Returns the sum of all elements in a collection. ``` - """ Base.sum + """ sum @doc doc""" ```rst @@ -4315,7 +4315,7 @@ Sum elements of an array over the given dimensions. ``` - """ Base.sum + """ sum @doc doc""" ```rst @@ -4324,7 +4324,7 @@ Sum elements of "A" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.sum! + """ sum! @doc doc""" ```rst @@ -4333,7 +4333,7 @@ Sum the results of calling function "f" on each element of "itr". ``` - """ Base.sum + """ sum @doc doc""" ```rst @@ -4342,7 +4342,7 @@ Sum absolute values of all elements in a collection. This is equivalent to *sum(abs(itr))* but faster. ``` - """ Base.sumabs + """ sumabs @doc doc""" ```rst @@ -4351,7 +4351,7 @@ Sum absolute values of elements of an array over the given dimensions. ``` - """ Base.sumabs + """ sumabs @doc doc""" ```rst @@ -4360,7 +4360,7 @@ Sum absolute values of elements of "A" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.sumabs! + """ sumabs! @doc doc""" ```rst @@ -4369,7 +4369,7 @@ Sum squared absolute values of all elements in a collection. This is equivalent to *sum(abs2(itr))* but faster. ``` - """ Base.sumabs2 + """ sumabs2 @doc doc""" ```rst @@ -4378,7 +4378,7 @@ Sum squared absolute values of elements of an array over the given dimensions. ``` - """ Base.sumabs2 + """ sumabs2 @doc doc""" ```rst @@ -4387,7 +4387,7 @@ Sum squared absolute values of elements of "A" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.sumabs2! + """ sumabs2! @doc doc""" ```rst @@ -4395,7 +4395,7 @@ Returns the product of all elements of a collection. ``` - """ Base.prod + """ prod @doc doc""" ```rst @@ -4403,7 +4403,7 @@ Multiply elements of an array over the given dimensions. ``` - """ Base.prod + """ prod @doc doc""" ```rst @@ -4412,7 +4412,7 @@ Multiply elements of "A" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.prod! + """ prod! @doc doc""" ```rst @@ -4420,7 +4420,7 @@ Test whether any elements of a boolean collection are true. ``` - """ Base.any + """ any @doc doc""" ```rst @@ -4429,7 +4429,7 @@ Test whether any values along the given dimensions of an array are true. ``` - """ Base.any + """ any @doc doc""" ```rst @@ -4438,7 +4438,7 @@ Test whether any values in "A" along the singleton dimensions of "r" are true, and write results to "r". ``` - """ Base.any! + """ any! @doc doc""" ```rst @@ -4446,7 +4446,7 @@ Test whether all elements of a boolean collection are true. ``` - """ Base.all + """ all @doc doc""" ```rst @@ -4455,7 +4455,7 @@ Test whether all values along the given dimensions of an array are true. ``` - """ Base.all + """ all @doc doc""" ```rst @@ -4464,7 +4464,7 @@ Test whether all values in "A" along the singleton dimensions of "r" are true, and write results to "r". ``` - """ Base.all! + """ all! @doc doc""" ```rst @@ -4473,7 +4473,7 @@ Count the number of elements in "itr" for which predicate "p" returns true. ``` - """ Base.count + """ count @doc doc""" ```rst @@ -4482,7 +4482,7 @@ Determine whether predicate "p" returns true for any elements of "itr". ``` - """ Base.any + """ any @doc doc""" ```rst @@ -4494,7 +4494,7 @@ julia> all(i->(4<=i<=6), [4,5,6]) true ``` - """ Base.all + """ all @doc doc""" ```rst @@ -4515,7 +4515,7 @@ 22 33 ``` - """ Base.map + """ map @doc doc""" ```rst @@ -4523,7 +4523,7 @@ In-place version of "map()". ``` - """ Base.map! + """ map! @doc doc""" ```rst @@ -4533,7 +4533,7 @@ than a new collection. "destination" must be at least as large as the first collection. ``` - """ Base.map! + """ map! @doc doc""" ```rst @@ -4559,7 +4559,7 @@ "mapfoldl()" or "mapfoldr()" instead for guaranteed left or right associativity and invocation of "f" for every value. ``` - """ Base.mapreduce + """ mapreduce @doc doc""" ```rst @@ -4568,7 +4568,7 @@ Like "mapreduce(f, op, v0, itr)". In general, this cannot be used with empty collections (see "reduce(op, itr)"). ``` - """ Base.mapreduce + """ mapreduce @doc doc""" ```rst @@ -4577,7 +4577,7 @@ Like "mapreduce()", but with guaranteed left associativity. "v0" will be used exactly once. ``` - """ Base.mapfoldl + """ mapfoldl @doc doc""" ```rst @@ -4587,7 +4587,7 @@ "itr" as "v0". In general, this cannot be used with empty collections (see "reduce(op, itr)"). ``` - """ Base.mapfoldl + """ mapfoldl @doc doc""" ```rst @@ -4596,7 +4596,7 @@ Like "mapreduce()", but with guaranteed right associativity. "v0" will be used exactly once. ``` - """ Base.mapfoldr + """ mapfoldr @doc doc""" ```rst @@ -4606,7 +4606,7 @@ "itr" as "v0". In general, this cannot be used with empty collections (see "reduce(op, itr)"). ``` - """ Base.mapfoldr + """ mapfoldr @doc doc""" ```rst @@ -4615,7 +4615,7 @@ Get the first element of an iterable collection. Returns the start point of a "Range" even if it is empty. ``` - """ Base.first + """ first @doc doc""" ```rst @@ -4626,7 +4626,7 @@ to get the last index. Returns the end point of a "Range" even if it is empty. ``` - """ Base.last + """ last @doc doc""" ```rst @@ -4634,7 +4634,7 @@ Get the step size of a "Range" object. ``` - """ Base.step + """ step @doc doc""" ```rst @@ -4643,7 +4643,7 @@ Return an array of all items in a collection. For associative collections, returns (key, value) tuples. ``` - """ Base.collect + """ collect @doc doc""" ```rst @@ -4652,7 +4652,7 @@ Return an array of type "Array{element_type,1}" of all items in a collection. ``` - """ Base.collect + """ collect @doc doc""" ```rst @@ -4664,7 +4664,7 @@ Determine whether every element of "a" is also in "b", using "in()". ``` - """ Base.issubset + """ issubset @doc doc""" ```rst @@ -4674,7 +4674,7 @@ "function" is false. For associative collections, the function is passed two arguments (key and value). ``` - """ Base.filter + """ filter @doc doc""" ```rst @@ -4684,7 +4684,7 @@ false. For associative collections, the function is passed two arguments (key and value). ``` - """ Base.filter! + """ filter! @doc doc""" ```rst @@ -4694,7 +4694,7 @@ collection. The syntax "a[i,j,...]" is converted by the compiler to "getindex(a, i, j, ...)". ``` - """ Base.getindex + """ getindex @doc doc""" ```rst @@ -4704,7 +4704,7 @@ collection. The syntax "a[i,j,...] = x" is converted by the compiler to "setindex!(a, x, i, j, ...)". ``` - """ Base.setindex! + """ setindex! @doc doc""" ```rst @@ -4729,7 +4729,7 @@ "B" => 2 "A" => 1 ``` - """ Base.Dict + """ Dict @doc doc""" ```rst @@ -4737,7 +4737,7 @@ Determine whether a collection has a mapping for a given key. ``` - """ Base.haskey + """ haskey @doc doc""" ```rst @@ -4746,7 +4746,7 @@ Return the value stored for the given key, or the given default value if no mapping for the key is present. ``` - """ Base.get + """ get @doc doc""" ```rst @@ -4763,7 +4763,7 @@ time() end ``` - """ Base.get + """ get @doc doc""" ```rst @@ -4772,7 +4772,7 @@ Return the value stored for the given key, or if no mapping for the key is present, store "key => default", and return "default". ``` - """ Base.get! + """ get! @doc doc""" ```rst @@ -4788,7 +4788,7 @@ time() end ``` - """ Base.get! + """ get! @doc doc""" ```rst @@ -4797,7 +4797,7 @@ Return the key matching argument "key" if one exists in "collection", otherwise return "default". ``` - """ Base.getkey + """ getkey @doc doc""" ```rst @@ -4806,7 +4806,7 @@ Delete the mapping for the given key in a collection, and return the collection. ``` - """ Base.delete! + """ delete! @doc doc""" ```rst @@ -4816,7 +4816,7 @@ "collection", otherwise return "default", or throw an error if default is not specified. ``` - """ Base.pop! + """ pop! @doc doc""" ```rst @@ -4825,7 +4825,7 @@ Return an iterator over all keys in a collection. "collect(keys(d))" returns an array of keys. ``` - """ Base.keys + """ keys @doc doc""" ```rst @@ -4834,7 +4834,7 @@ Return an iterator over all values in a collection. "collect(values(d))" returns an array of values. ``` - """ Base.values + """ values @doc doc""" ```rst @@ -4861,7 +4861,7 @@ "baz" => 17.0 "foo" => 0.0 ``` - """ Base.merge + """ merge @doc doc""" ```rst @@ -4869,7 +4869,7 @@ Update collection with pairs from the other collections ``` - """ Base.merge! + """ merge! @doc doc""" ```rst @@ -4878,7 +4878,7 @@ Suggest that collection "s" reserve capacity for at least "n" elements. This can improve performance. ``` - """ Base.sizehint! + """ sizehint! @doc doc""" ```rst @@ -4888,7 +4888,7 @@ object, or an empty set. Should be used instead of "IntSet" for sparse integer sets, or for sets of arbitrary objects. ``` - """ Base.Set + """ Set @doc doc""" ```rst @@ -4900,7 +4900,7 @@ integers can be stored. If the set will be sparse (for example holding a single very large integer), use "Set" instead. ``` - """ Base.IntSet + """ IntSet @doc doc""" ```rst @@ -4910,7 +4910,7 @@ Construct the union of two or more sets. Maintains order with arrays. ``` - """ Base.union + """ union @doc doc""" ```rst @@ -4918,7 +4918,7 @@ Union each element of "iterable" into set "s" in-place. ``` - """ Base.union! + """ union! @doc doc""" ```rst @@ -4928,7 +4928,7 @@ Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. ``` - """ Base.intersect + """ intersect @doc doc""" ```rst @@ -4940,7 +4940,7 @@ "setdiff(set,element)" where "element" is a potential member of "set", will not work in general. ``` - """ Base.setdiff + """ setdiff @doc doc""" ```rst @@ -4948,7 +4948,7 @@ Remove each element of "iterable" from set "s" in-place. ``` - """ Base.setdiff! + """ setdiff! @doc doc""" ```rst @@ -4957,7 +4957,7 @@ Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. ``` - """ Base.symdiff + """ symdiff @doc doc""" ```rst @@ -4966,7 +4966,7 @@ The set "s" is destructively modified to toggle the inclusion of integer "n". ``` - """ Base.symdiff! + """ symdiff! @doc doc""" ```rst @@ -4975,7 +4975,7 @@ For each element in "itr", destructively toggle its inclusion in set "s". ``` - """ Base.symdiff! + """ symdiff! @doc doc""" ```rst @@ -4984,7 +4984,7 @@ Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". ``` - """ Base.symdiff! + """ symdiff! @doc doc""" ```rst @@ -4992,7 +4992,7 @@ Returns the set-complement of "IntSet" "s". ``` - """ Base.complement + """ complement @doc doc""" ```rst @@ -5000,7 +5000,7 @@ Mutates "IntSet" "s" into its set-complement. ``` - """ Base.complement! + """ complement! @doc doc""" ```rst @@ -5010,7 +5010,7 @@ with the result. If needed, "s1" will be expanded to the size of "s2". ``` - """ Base.intersect! + """ intersect! @doc doc""" ```rst @@ -5019,7 +5019,7 @@ True if A is a subset of or equal to S. ``` - """ Base.issubset + """ issubset @doc doc""" ```rst @@ -5040,7 +5040,7 @@ "collection". The result of the preceding example is equivalent to "append!([1, 2, 3], [4, 5, 6])". ``` - """ Base.push! + """ push! @doc doc""" ```rst @@ -5068,7 +5068,7 @@ 4 5 ``` - """ Base.pop! + """ pop! @doc doc""" ```rst @@ -5085,7 +5085,7 @@ 3 4 ``` - """ Base.unshift! + """ unshift! @doc doc""" ```rst @@ -5113,7 +5113,7 @@ 5 6 ``` - """ Base.shift! + """ shift! @doc doc""" ```rst @@ -5131,7 +5131,7 @@ 2 1 ``` - """ Base.insert! + """ insert! @doc doc""" ```rst @@ -5149,7 +5149,7 @@ 2 1 ``` - """ Base.deleteat! + """ deleteat! @doc doc""" ```rst @@ -5169,7 +5169,7 @@ ERROR: ArgumentError: indices must be unique and sorted in deleteat! at array.jl:631 ``` - """ Base.deleteat! + """ deleteat! @doc doc""" ```rst @@ -5218,7 +5218,7 @@ To insert "replacement" before an index "n" without removing any items, use "splice!(collection, n:n-1, replacement)". ``` - """ Base.splice! + """ splice! @doc doc""" ```rst @@ -5246,7 +5246,7 @@ 3 -1 ``` - """ Base.splice! + """ splice! @doc doc""" ```rst @@ -5274,7 +5274,7 @@ 0 0 ``` - """ Base.resize! + """ resize! @doc doc""" ```rst @@ -5301,7 +5301,7 @@ not already themselves in another collection. The result is of the preceding example is equivalent to "push!([1, 2, 3], 4, 5, 6)". ``` - """ Base.append! + """ append! @doc doc""" ```rst @@ -5316,7 +5316,7 @@ 2 3 ``` - """ Base.prepend! + """ prepend! @doc doc""" ```rst @@ -5409,7 +5409,7 @@ there is no value to return (as in a C "void" function). Can be converted to an empty "Nullable" value. ``` - """ Base.nothing + """ nothing @doc doc""" ```rst @@ -5418,7 +5418,7 @@ A symbol representing the name of the operating system. Possible values are ":Linux", ":Darwin" (OS X), or ":Windows". ``` - """ Base.OS_NAME + """ OS_NAME @doc doc""" ```rst @@ -5426,7 +5426,7 @@ An array of the command line arguments passed to Julia, as strings. ``` - """ Base.ARGS + """ ARGS @doc doc""" ```rst @@ -5435,7 +5435,7 @@ The C null pointer constant, sometimes used when calling external code. ``` - """ Base.C_NULL + """ C_NULL @doc doc""" ```rst @@ -5443,7 +5443,7 @@ Standard word size on the current machine, in bits. ``` - """ Base.WORD_SIZE + """ WORD_SIZE @doc doc""" ```rst @@ -5451,7 +5451,7 @@ An object describing which version of Julia is in use. ``` - """ Base.VERSION + """ VERSION @doc doc""" ```rst @@ -5460,7 +5460,7 @@ An array of paths (as strings) where the "require" function looks for code. ``` - """ Base.LOAD_PATH + """ LOAD_PATH @doc doc""" ```rst @@ -5469,7 +5469,7 @@ Equivalent to "Any" for dispatch purposes, but signals the compiler to skip code generation specialization for that field ``` - """ Base.ANY + """ ANY @doc doc""" ```rst @@ -6176,7 +6176,7 @@ Millisecond(v) Get the current working directory. ``` - """ Base.pwd + """ pwd @doc doc""" ```rst @@ -6184,7 +6184,7 @@ Millisecond(v) Set the current working directory. ``` - """ Base.cd + """ cd @doc doc""" ```rst @@ -6193,7 +6193,7 @@ Millisecond(v) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. ``` - """ Base.cd + """ cd @doc doc""" ```rst @@ -6202,7 +6202,7 @@ Millisecond(v) Returns the files and directories in the directory *dir* (or the current working directory if not given). ``` - """ Base.readdir + """ readdir @doc doc""" ```rst @@ -6212,7 +6212,7 @@ Millisecond(v) "mode" defaults to 0o777, modified by the current file creation mask. ``` - """ Base.mkdir + """ mkdir @doc doc""" ```rst @@ -6222,7 +6222,7 @@ Millisecond(v) "mode". "mode" defaults to 0o777, modified by the current file creation mask. ``` - """ Base.mkpath + """ mkpath @doc doc""" ```rst @@ -6233,7 +6233,7 @@ Millisecond(v) Note: This function raises an error under operating systems that do not support soft symbolic links, such as Windows XP. ``` - """ Base.symlink + """ symlink @doc doc""" ```rst @@ -6241,7 +6241,7 @@ Millisecond(v) Returns the value of a symbolic link "path". ``` - """ Base.readlink + """ readlink @doc doc""" ```rst @@ -6250,7 +6250,7 @@ Millisecond(v) Change the permissions mode of "path" to "mode". Only integer "mode"s (e.g. 0o777) are currently supported. ``` - """ Base.chmod + """ chmod @doc doc""" ```rst @@ -6285,7 +6285,7 @@ Millisecond(v) | ctime | Unix timestamp of when the file was created | +-----------+------------------------------------------------------------------------+ ``` - """ Base.stat + """ stat @doc doc""" ```rst @@ -6295,7 +6295,7 @@ Millisecond(v) rather than the file it refers to. This function must be called on a file path rather than a file object or a file descriptor. ``` - """ Base.lstat + """ lstat @doc doc""" ```rst @@ -6303,7 +6303,7 @@ Millisecond(v) Equivalent to stat(file).ctime ``` - """ Base.ctime + """ ctime @doc doc""" ```rst @@ -6311,7 +6311,7 @@ Millisecond(v) Equivalent to stat(file).mtime ``` - """ Base.mtime + """ mtime @doc doc""" ```rst @@ -6319,7 +6319,7 @@ Millisecond(v) Equivalent to stat(file).mode ``` - """ Base.filemode + """ filemode @doc doc""" ```rst @@ -6327,7 +6327,7 @@ Millisecond(v) Equivalent to stat(file).size ``` - """ Base.filesize + """ filesize @doc doc""" ```rst @@ -6345,7 +6345,7 @@ Millisecond(v) For allowed arguments, see "stat". ``` - """ Base.uperm + """ uperm @doc doc""" ```rst @@ -6353,7 +6353,7 @@ Millisecond(v) Like uperm but gets the permissions of the group owning the file ``` - """ Base.gperm + """ gperm @doc doc""" ```rst @@ -6362,7 +6362,7 @@ Millisecond(v) Like uperm but gets the permissions for people who neither own the file nor are a member of the group owning the file ``` - """ Base.operm + """ operm @doc doc""" ```rst @@ -6376,7 +6376,7 @@ Millisecond(v) symbolic link, dst will be a copy of the file or directory *src* refers to. ``` - """ Base.cp + """ cp @doc doc""" ```rst @@ -6389,7 +6389,7 @@ Millisecond(v) production use or situations in which more options are need, please use a package that provides the desired functionality instead. ``` - """ Base.download + """ download @doc doc""" ```rst @@ -6398,7 +6398,7 @@ Millisecond(v) Move the file, link, or directory from *src* to *dest*. "remove_destination=true" will first remove an existing *dst*. ``` - """ Base.mv + """ mv @doc doc""" ```rst @@ -6408,7 +6408,7 @@ Millisecond(v) "recursive=true" is passed and the path is a directory, then all contents are removed recursively. ``` - """ Base.rm + """ rm @doc doc""" ```rst @@ -6416,7 +6416,7 @@ Millisecond(v) Update the last-modified timestamp on a file to the current time. ``` - """ Base.touch + """ touch @doc doc""" ```rst @@ -6424,7 +6424,7 @@ Millisecond(v) Generate a unique temporary file path. ``` - """ Base.tempname + """ tempname @doc doc""" ```rst @@ -6433,7 +6433,7 @@ Millisecond(v) Obtain the path of a temporary directory (possibly shared with other processes). ``` - """ Base.tempdir + """ tempdir @doc doc""" ```rst @@ -6443,7 +6443,7 @@ Millisecond(v) temporary file in "parent" and "io" is an open file object for this path. ``` - """ Base.mktemp + """ mktemp @doc doc""" ```rst @@ -6452,7 +6452,7 @@ Millisecond(v) Create a temporary directory in the "parent" directory and return its path. ``` - """ Base.mktempdir + """ mktempdir @doc doc""" ```rst @@ -6461,7 +6461,7 @@ Millisecond(v) Returns "true" if "path" is a block device, "false" otherwise. ``` - """ Base.isblockdev + """ isblockdev @doc doc""" ```rst @@ -6470,7 +6470,7 @@ Millisecond(v) Returns "true" if "path" is a character device, "false" otherwise. ``` - """ Base.ischardev + """ ischardev @doc doc""" ```rst @@ -6478,7 +6478,7 @@ Millisecond(v) Returns "true" if "path" is a directory, "false" otherwise. ``` - """ Base.isdir + """ isdir @doc doc""" ```rst @@ -6487,7 +6487,7 @@ Millisecond(v) Returns "true" if the current user has permission to execute "path", "false" otherwise. ``` - """ Base.isexecutable + """ isexecutable @doc doc""" ```rst @@ -6495,7 +6495,7 @@ Millisecond(v) Returns "true" if "path" is a FIFO, "false" otherwise. ``` - """ Base.isfifo + """ isfifo @doc doc""" ```rst @@ -6504,7 +6504,7 @@ Millisecond(v) Returns "true" if "path" is a regular file, "false" otherwise. ``` - """ Base.isfile + """ isfile @doc doc""" ```rst @@ -6513,7 +6513,7 @@ Millisecond(v) Returns "true" if "path" is a symbolic link, "false" otherwise. ``` - """ Base.islink + """ islink @doc doc""" ```rst @@ -6521,7 +6521,7 @@ Millisecond(v) Returns "true" if "path" is a mount point, "false" otherwise. ``` - """ Base.ismount + """ ismount @doc doc""" ```rst @@ -6530,7 +6530,7 @@ Millisecond(v) Returns "true" if "path" is a valid filesystem path, "false" otherwise. ``` - """ Base.ispath + """ ispath @doc doc""" ```rst @@ -6539,7 +6539,7 @@ Millisecond(v) Returns "true" if the current user has permission to read "path", "false" otherwise. ``` - """ Base.isreadable + """ isreadable @doc doc""" ```rst @@ -6548,7 +6548,7 @@ Millisecond(v) Returns "true" if "path" has the setgid flag set, "false" otherwise. ``` - """ Base.issetgid + """ issetgid @doc doc""" ```rst @@ -6557,7 +6557,7 @@ Millisecond(v) Returns "true" if "path" has the setuid flag set, "false" otherwise. ``` - """ Base.issetuid + """ issetuid @doc doc""" ```rst @@ -6565,7 +6565,7 @@ Millisecond(v) Returns "true" if "path" is a socket, "false" otherwise. ``` - """ Base.issocket + """ issocket @doc doc""" ```rst @@ -6574,7 +6574,7 @@ Millisecond(v) Returns "true" if "path" has the sticky bit set, "false" otherwise. ``` - """ Base.issticky + """ issticky @doc doc""" ```rst @@ -6583,7 +6583,7 @@ Millisecond(v) Returns "true" if the current user has permission to write to "path", "false" otherwise. ``` - """ Base.iswritable + """ iswritable @doc doc""" ```rst @@ -6591,7 +6591,7 @@ Millisecond(v) Return the current user's home directory. ``` - """ Base.homedir + """ homedir @doc doc""" ```rst @@ -6599,7 +6599,7 @@ Millisecond(v) Get the directory part of a path. ``` - """ Base.dirname + """ dirname @doc doc""" ```rst @@ -6607,7 +6607,7 @@ Millisecond(v) Get the file name part of a path. ``` - """ Base.basename + """ basename @doc doc""" ```rst @@ -6617,7 +6617,7 @@ Millisecond(v) name of the script being run. Returns "nothing" if run from a REPL or an empty string if evaluated by "julia -e ". ``` - """ Base.@__FILE__ + """ @__FILE__ @doc doc""" ```rst @@ -6626,7 +6626,7 @@ Millisecond(v) Determines whether a path is absolute (begins at the root directory). ``` - """ Base.isabspath + """ isabspath @doc doc""" ```rst @@ -6635,7 +6635,7 @@ Millisecond(v) Determines whether a path refers to a directory (for example, ends with a path separator). ``` - """ Base.isdirpath + """ isdirpath @doc doc""" ```rst @@ -6644,7 +6644,7 @@ Millisecond(v) Join path components into a full path. If some argument is an absolute path, then prior components are dropped. ``` - """ Base.joinpath + """ joinpath @doc doc""" ```rst @@ -6653,7 +6653,7 @@ Millisecond(v) Convert a path to an absolute path by adding the current directory if necessary. ``` - """ Base.abspath + """ abspath @doc doc""" ```rst @@ -6661,7 +6661,7 @@ Millisecond(v) Normalize a path, removing "." and ".." entries. ``` - """ Base.normpath + """ normpath @doc doc""" ```rst @@ -6670,7 +6670,7 @@ Millisecond(v) Canonicalize a path by expanding symbolic links and removing "." and ".." entries. ``` - """ Base.realpath + """ realpath @doc doc""" ```rst @@ -6681,7 +6681,7 @@ Millisecond(v) computation: the filesystem is not accessed to confirm the existence or nature of path or startpath. ``` - """ Base.relpath + """ relpath @doc doc""" ```rst @@ -6690,7 +6690,7 @@ Millisecond(v) On Unix systems, replace a tilde character at the start of a path with the current user's home directory. ``` - """ Base.expanduser + """ expanduser @doc doc""" ```rst @@ -6698,7 +6698,7 @@ Millisecond(v) Split a path into a tuple of the directory name and file name. ``` - """ Base.splitdir + """ splitdir @doc doc""" ```rst @@ -6708,7 +6708,7 @@ Millisecond(v) part. On Unix systems, the first component is always the empty string. ``` - """ Base.splitdrive + """ splitdrive @doc doc""" ```rst @@ -6719,7 +6719,7 @@ Millisecond(v) dot. Otherwise, return a tuple of the argument unmodified and the empty string. ``` - """ Base.splitext + """ splitext @doc doc""" ```rst @@ -6729,7 +6729,7 @@ Millisecond(v) default is to open files for reading only. Returns a stream for accessing the file. ``` - """ Base.open + """ open @doc doc""" ```rst @@ -6754,7 +6754,7 @@ Millisecond(v) | a+ | read, write, create, append | +------+-----------------------------------+ ``` - """ Base.open + """ open @doc doc""" ```rst @@ -6765,7 +6765,7 @@ Millisecond(v) **Example**: "open(readall, "file.txt")" ``` - """ Base.open + """ open @doc doc""" ```rst @@ -6773,7 +6773,7 @@ Millisecond(v) Create an in-memory I/O stream. ``` - """ Base.IOBuffer + """ IOBuffer @doc doc""" ```rst @@ -6781,7 +6781,7 @@ Millisecond(v) Create a fixed size IOBuffer. The buffer will not grow dynamically. ``` - """ Base.IOBuffer + """ IOBuffer @doc doc""" ```rst @@ -6789,7 +6789,7 @@ Millisecond(v) Create a read-only IOBuffer on the data underlying the given string ``` - """ Base.IOBuffer + """ IOBuffer @doc doc""" ```rst @@ -6802,7 +6802,7 @@ Millisecond(v) The last argument optionally specifies a size beyond which the buffer may not be grown. ``` - """ Base.IOBuffer + """ IOBuffer @doc doc""" ```rst @@ -6811,7 +6811,7 @@ Millisecond(v) Obtain the contents of an "IOBuffer" as an array, without copying. Afterwards, the IOBuffer is reset to its initial state. ``` - """ Base.takebuf_array + """ takebuf_array @doc doc""" ```rst @@ -6820,7 +6820,7 @@ Millisecond(v) Obtain the contents of an "IOBuffer" as a string, without copying. Afterwards, the IOBuffer is reset to its initial state. ``` - """ Base.takebuf_string + """ takebuf_string @doc doc""" ```rst @@ -6832,7 +6832,7 @@ Millisecond(v) garbage collected. "name" allows you to associate the descriptor with a named file. ``` - """ Base.fdio + """ fdio @doc doc""" ```rst @@ -6840,7 +6840,7 @@ Millisecond(v) Commit all currently buffered writes to the given stream. ``` - """ Base.flush + """ flush @doc doc""" ```rst @@ -6848,7 +6848,7 @@ Millisecond(v) Close an I/O stream. Performs a "flush" first. ``` - """ Base.close + """ close @doc doc""" ```rst @@ -6857,7 +6857,7 @@ Millisecond(v) Write the canonical binary representation of a value to the given stream. ``` - """ Base.write + """ write @doc doc""" ```rst @@ -6866,7 +6866,7 @@ Millisecond(v) Read a value of the given type from a stream, in canonical binary representation. ``` - """ Base.read + """ read @doc doc""" ```rst @@ -6877,7 +6877,7 @@ Millisecond(v) series of integer arguments specifying the size of "Array" to return. ``` - """ Base.read + """ read @doc doc""" ```rst @@ -6885,7 +6885,7 @@ Millisecond(v) Read binary data from a stream, filling in the argument "array". ``` - """ Base.read! + """ read! @doc doc""" ```rst @@ -6894,7 +6894,7 @@ Millisecond(v) Read at most "nb" bytes from the stream into "b", returning the number of bytes read (increasing the size of "b" as needed). ``` - """ Base.readbytes! + """ readbytes! @doc doc""" ```rst @@ -6903,7 +6903,7 @@ Millisecond(v) Read at most "nb" bytes from the stream, returning a "Vector{UInt8}" of the bytes read. ``` - """ Base.readbytes + """ readbytes @doc doc""" ```rst @@ -6911,7 +6911,7 @@ Millisecond(v) Get the current position of a stream. ``` - """ Base.position + """ position @doc doc""" ```rst @@ -6919,7 +6919,7 @@ Millisecond(v) Seek a stream to the given position. ``` - """ Base.seek + """ seek @doc doc""" ```rst @@ -6927,7 +6927,7 @@ Millisecond(v) Seek a stream to its beginning. ``` - """ Base.seekstart + """ seekstart @doc doc""" ```rst @@ -6935,7 +6935,7 @@ Millisecond(v) Seek a stream to its end. ``` - """ Base.seekend + """ seekend @doc doc""" ```rst @@ -6943,7 +6943,7 @@ Millisecond(v) Seek a stream relative to the current position. ``` - """ Base.skip + """ skip @doc doc""" ```rst @@ -6954,7 +6954,7 @@ Millisecond(v) See also "unmark()", "reset()", "ismarked()" ``` - """ Base.mark + """ mark @doc doc""" ```rst @@ -6965,7 +6965,7 @@ Millisecond(v) See also "mark()", "reset()", "ismarked()" ``` - """ Base.unmark + """ unmark @doc doc""" ```rst @@ -6977,7 +6977,7 @@ Millisecond(v) See also "mark()", "unmark()", "ismarked()" ``` - """ Base.reset + """ reset @doc doc""" ```rst @@ -6987,7 +6987,7 @@ Millisecond(v) See also "mark()", "unmark()", "reset()" ``` - """ Base.ismarked + """ ismarked @doc doc""" ```rst @@ -7000,7 +7000,7 @@ Millisecond(v) will return "false" as long as buffered data is still available, even if the remote end of a connection is closed. ``` - """ Base.eof + """ eof @doc doc""" ```rst @@ -7008,7 +7008,7 @@ Millisecond(v) Determine whether a stream is read-only. ``` - """ Base.isreadonly + """ isreadonly @doc doc""" ```rst @@ -7019,7 +7019,7 @@ Millisecond(v) socket), "isopen" will return "false" even though buffered data may still be available. Use "eof" to check if necessary. ``` - """ Base.isopen + """ isopen @doc doc""" ```rst @@ -7032,7 +7032,7 @@ Millisecond(v) versions of Julia, or an instance of Julia with a different system image. ``` - """ Base.serialize + """ serialize @doc doc""" ```rst @@ -7040,7 +7040,7 @@ Millisecond(v) Read a value written by "serialize". ``` - """ Base.deserialize + """ deserialize @doc doc""" ```rst @@ -7049,7 +7049,7 @@ Millisecond(v) General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). ``` - """ Base.print_escaped + """ print_escaped @doc doc""" ```rst @@ -7058,7 +7058,7 @@ Millisecond(v) General unescaping of traditional C and Unicode escape sequences. Reverse of "print_escaped()". ``` - """ Base.print_unescaped + """ print_unescaped @doc doc""" ```rst @@ -7068,7 +7068,7 @@ Millisecond(v) If "last" is specified, it is used as the final delimiter instead of "delim". ``` - """ Base.print_joined + """ print_joined @doc doc""" ```rst @@ -7078,7 +7078,7 @@ Millisecond(v) of consecutive non-zero digits, of number "x", ensuring that it would parse to the exact same number. ``` - """ Base.print_shortest + """ print_shortest @doc doc""" ```rst @@ -7088,7 +7088,7 @@ Millisecond(v) this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. ``` - """ Base.fd + """ fd @doc doc""" ```rst @@ -7100,7 +7100,7 @@ Millisecond(v) The wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be replaced elsewhere. ``` - """ Base.redirect_stdout + """ redirect_stdout @doc doc""" ```rst @@ -7109,7 +7109,7 @@ Millisecond(v) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. ``` - """ Base.redirect_stdout + """ redirect_stdout @doc doc""" ```rst @@ -7117,7 +7117,7 @@ Millisecond(v) Like redirect_stdout, but for STDERR ``` - """ Base.redirect_stderr + """ redirect_stderr @doc doc""" ```rst @@ -7127,7 +7127,7 @@ Millisecond(v) return tuple is still (rd,wr), i.e. data to be read from STDIN, may be written to wr. ``` - """ Base.redirect_stdin + """ redirect_stdin @doc doc""" ```rst @@ -7136,7 +7136,7 @@ Millisecond(v) Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). ``` - """ Base.readchomp + """ readchomp @doc doc""" ```rst @@ -7146,7 +7146,7 @@ Millisecond(v) *n* bytes, filling previously unallocated space with '\0' if the file or buffer is grown ``` - """ Base.truncate + """ truncate @doc doc""" ```rst @@ -7158,7 +7158,7 @@ Millisecond(v) "linecomment" is specified, characters from that character through the end of a line will also be skipped. ``` - """ Base.skipchars + """ skipchars @doc doc""" ```rst @@ -7169,7 +7169,7 @@ Millisecond(v) argument. EOL markers other than '\n' are supported by passing them as the second argument. ``` - """ Base.countlines + """ countlines @doc doc""" ```rst @@ -7179,7 +7179,7 @@ Millisecond(v) Seeking and truncating are not supported. See IOBuffer for the available constructors. ``` - """ Base.PipeBuffer + """ PipeBuffer @doc doc""" ```rst @@ -7189,7 +7189,7 @@ Millisecond(v) specifying a size beyond which the underlying Array may not be grown. ``` - """ Base.PipeBuffer + """ PipeBuffer @doc doc""" ```rst @@ -7198,7 +7198,7 @@ Millisecond(v) Read all available data on the stream, blocking the task only if no data is available. The result is a "Vector{UInt8,1}". ``` - """ Base.readavailable + """ readavailable @doc doc""" ```rst @@ -7209,7 +7209,7 @@ Millisecond(v) first argument is a stream. The representation used by "show" generally includes Julia-specific formatting and type information. ``` - """ Base.show + """ show @doc doc""" ```rst @@ -7220,7 +7220,7 @@ Millisecond(v) representation, it should overload "showcompact(io, x)" where the first argument is a stream. ``` - """ Base.showcompact + """ showcompact @doc doc""" ```rst @@ -7228,7 +7228,7 @@ Millisecond(v) Similar to "show", except shows all elements of arrays. ``` - """ Base.showall + """ showall @doc doc""" ```rst @@ -7238,7 +7238,7 @@ Millisecond(v) returns "string(typeof(x))". For arrays, returns strings like "2x2 Float64 Array". ``` - """ Base.summary + """ summary @doc doc""" ```rst @@ -7249,7 +7249,7 @@ Millisecond(v) "show". The representation used by "print" includes minimal formatting and tries to avoid Julia-specific details. ``` - """ Base.print + """ print @doc doc""" ```rst @@ -7257,7 +7257,7 @@ Millisecond(v) Print (using "print()") "x" followed by a newline. ``` - """ Base.println + """ println @doc doc""" ```rst @@ -7266,7 +7266,7 @@ Millisecond(v) Print strings in a color specified as a symbol, for example ":red" or ":blue". ``` - """ Base.print_with_color + """ print_with_color @doc doc""" ```rst @@ -7274,7 +7274,7 @@ Millisecond(v) Display an informational message. ``` - """ Base.info + """ info @doc doc""" ```rst @@ -7282,7 +7282,7 @@ Millisecond(v) Display a warning. ``` - """ Base.warn + """ warn @doc doc""" ```rst @@ -7292,7 +7292,7 @@ Millisecond(v) string. Optionally, an IOStream may be passed as the first argument to redirect output. ``` - """ Base.@printf + """ @printf @doc doc""" ```rst @@ -7300,7 +7300,7 @@ Millisecond(v) Return "@printf" formatted output as string. ``` - """ Base.@sprintf + """ @sprintf @doc doc""" ```rst @@ -7310,7 +7310,7 @@ Millisecond(v) arguments. Everything written to this I/O stream is returned as a string. ``` - """ Base.sprint + """ sprint @doc doc""" ```rst @@ -7318,7 +7318,7 @@ Millisecond(v) Show a descriptive representation of an exception object. ``` - """ Base.showerror + """ showerror @doc doc""" ```rst @@ -7326,7 +7326,7 @@ Millisecond(v) Show all user-visible structure of a value. ``` - """ Base.dump + """ dump @doc doc""" ```rst @@ -7334,7 +7334,7 @@ Millisecond(v) Show all structure of a value, including all fields of objects. ``` - """ Base.xdump + """ xdump @doc doc""" ```rst @@ -7342,7 +7342,7 @@ Millisecond(v) Read the entire contents of an I/O stream as a string. ``` - """ Base.readall + """ readall @doc doc""" ```rst @@ -7351,7 +7351,7 @@ Millisecond(v) Open "filename", read the entire contents as a string, then close the file. Equivalent to "open(readall, filename)". ``` - """ Base.readall + """ readall @doc doc""" ```rst @@ -7361,7 +7361,7 @@ Millisecond(v) (if one is reached before the end of the input), from the given "stream" (defaults to "STDIN"), ``` - """ Base.readline + """ readline @doc doc""" ```rst @@ -7369,7 +7369,7 @@ Millisecond(v) Read a string, up to and including the given delimiter byte. ``` - """ Base.readuntil + """ readuntil @doc doc""" ```rst @@ -7377,7 +7377,7 @@ Millisecond(v) Read all lines as an array. ``` - """ Base.readlines + """ readlines @doc doc""" ```rst @@ -7385,7 +7385,7 @@ Millisecond(v) Create an iterable object that will yield each line from a stream. ``` - """ Base.eachline + """ eachline @doc doc""" ```rst @@ -7432,7 +7432,7 @@ Millisecond(v) If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. ``` - """ Base.readdlm + """ readdlm @doc doc""" ```rst @@ -7442,7 +7442,7 @@ Millisecond(v) elements cannot be parsed as numbers, a cell array of numbers and strings is returned. ``` - """ Base.readdlm + """ readdlm @doc doc""" ```rst @@ -7450,7 +7450,7 @@ Millisecond(v) The end of line delimiter is taken as "\n". ``` - """ Base.readdlm + """ readdlm @doc doc""" ```rst @@ -7461,7 +7461,7 @@ Millisecond(v) cannot be parsed as numbers, a cell array of numbers and strings is returned. ``` - """ Base.readdlm + """ readdlm @doc doc""" ```rst @@ -7470,7 +7470,7 @@ Millisecond(v) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". ``` - """ Base.readdlm + """ readdlm @doc doc""" ```rst @@ -7482,7 +7482,7 @@ Millisecond(v) cannot be parsed as numbers, a cell array of numbers and strings is returned. ``` - """ Base.readdlm + """ readdlm @doc doc""" ```rst @@ -7498,7 +7498,7 @@ Millisecond(v) written as two columns of tab-delimited text to "f" by either "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". ``` - """ Base.writedlm + """ writedlm @doc doc""" ```rst @@ -7506,7 +7506,7 @@ Millisecond(v) Equivalent to "readdlm" with "delim" set to comma. ``` - """ Base.readcsv + """ readcsv @doc doc""" ```rst @@ -7514,7 +7514,7 @@ Millisecond(v) Equivalent to "writedlm" with "delim" set to comma. ``` - """ Base.writecsv + """ writecsv @doc doc""" ```rst @@ -7526,7 +7526,7 @@ Millisecond(v) necessary to complete the encoding (but does not close "ostream"). ``` - """ Base.Base64EncodePipe + """ Base64EncodePipe @doc doc""" ```rst @@ -7535,7 +7535,7 @@ Millisecond(v) Returns a new read-only I/O stream, which decodes base64-encoded data read from "istream". ``` - """ Base.Base64DecodePipe + """ Base64DecodePipe @doc doc""" ```rst @@ -7550,7 +7550,7 @@ base64encode(args...) using the standard "write" functions and returns the base64-encoded string. ``` - """ Base.base64encode + """ base64encode @doc doc""" ```rst @@ -7559,7 +7559,7 @@ base64encode(args...) Decodes the base64-encoded "string" and returns a "Vector{UInt8}" of the decoded bytes. ``` - """ Base.base64decode + """ base64decode @doc doc""" ```rst @@ -7585,7 +7585,7 @@ display(d::Display, mime, x) application/postscript) or "x::Vector{UInt8}" (for binary MIME types). ``` - """ Base.display + """ display @doc doc""" ```rst @@ -7601,7 +7601,7 @@ redisplay(d::Display, mime, x) times, and the backend may choose to defer the display until (for example) the next interactive prompt. ``` - """ Base.redisplay + """ redisplay @doc doc""" ```rst @@ -7613,7 +7613,7 @@ displayable(d::Display, mime) -> Bool display stack, or specifically by the display "d" in the second variant. ``` - """ Base.displayable + """ displayable @doc doc""" ```rst @@ -7643,7 +7643,7 @@ displayable(d::Display, mime) -> Bool dispatch mechanisms in determining how to display objects of any given type. ``` - """ Base.writemime + """ writemime @doc doc""" ```rst @@ -7654,7 +7654,7 @@ displayable(d::Display, mime) -> Bool determined automatically by the existence of the corresponding "writemime" function for "typeof(x)".) ``` - """ Base.mimewritable + """ mimewritable @doc doc""" ```rst @@ -7674,7 +7674,7 @@ displayable(d::Display, mime) -> Bool "reprmime" function assumes that "x" is already in the requested "mime" format and simply returns "x". ``` - """ Base.reprmime + """ reprmime @doc doc""" ```rst @@ -7685,7 +7685,7 @@ displayable(d::Display, mime) -> Bool "reprmime" except that binary data is base64-encoded as an ASCII string. ``` - """ Base.stringmime + """ stringmime @doc doc""" ```rst @@ -7696,7 +7696,7 @@ displayable(d::Display, mime) -> Bool "x" on the topmost compatible backend in the stack (i.e., the topmost backend that does not throw a "MethodError"). ``` - """ Base.pushdisplay + """ pushdisplay @doc doc""" ```rst @@ -7706,7 +7706,7 @@ popdisplay(d::Display) Pop the topmost backend off of the display-backend stack, or the topmost copy of "d" in the second variant. ``` - """ Base.popdisplay + """ popdisplay @doc doc""" ```rst @@ -7717,7 +7717,7 @@ popdisplay(d::Display) to the given I/O stream. (The text representation is the same as the way an object is printed in the Julia REPL.) ``` - """ Base.TextDisplay + """ TextDisplay @doc doc""" ```rst @@ -7725,7 +7725,7 @@ popdisplay(d::Display) Determine whether a MIME type is text data. ``` - """ Base.istext + """ istext @doc doc""" ```rst @@ -7777,7 +7777,7 @@ popdisplay(d::Display) consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). ``` - """ Base.mmap_array + """ mmap_array @doc doc""" ```rst @@ -7794,7 +7794,7 @@ popdisplay(d::Display) This would create a 25-by-30000 "BitArray", linked to the file associated with stream "s". ``` - """ Base.mmap_bitarray + """ mmap_bitarray @doc doc""" ```rst @@ -7803,7 +7803,7 @@ popdisplay(d::Display) Forces synchronization between the in-memory version of a memory- mapped "Array" or "BitArray" and the on-disk version. ``` - """ Base.msync + """ msync @doc doc""" ```rst @@ -7811,7 +7811,7 @@ popdisplay(d::Display) Connect to the host "host" on port "port" ``` - """ Base.connect + """ connect @doc doc""" ```rst @@ -7819,7 +7819,7 @@ popdisplay(d::Display) Connect to the Named Pipe/Domain Socket at "path" ``` - """ Base.connect + """ connect @doc doc""" ```rst @@ -7829,7 +7829,7 @@ popdisplay(d::Display) this listens on localhost only. To listen on all interfaces pass, "IPv4(0)" or "IPv6(0)" as appropriate. ``` - """ Base.listen + """ listen @doc doc""" ```rst @@ -7837,7 +7837,7 @@ popdisplay(d::Display) Listens on/Creates a Named Pipe/Domain Socket ``` - """ Base.listen + """ listen @doc doc""" ```rst @@ -7845,7 +7845,7 @@ popdisplay(d::Display) Gets the IP address of the "host" (may have to do a DNS lookup) ``` - """ Base.getaddrinfo + """ getaddrinfo @doc doc""" ```rst @@ -7853,7 +7853,7 @@ popdisplay(d::Display) Parse a string specifying an IPv4 or IPv6 ip address. ``` - """ Base.parseip + """ parseip @doc doc""" ```rst @@ -7861,7 +7861,7 @@ popdisplay(d::Display) Returns IPv4 object from ip address formatted as Integer ``` - """ Base.IPv4 + """ IPv4 @doc doc""" ```rst @@ -7869,7 +7869,7 @@ popdisplay(d::Display) Returns IPv6 object from ip address formatted as Integer ``` - """ Base.IPv6 + """ IPv6 @doc doc""" ```rst @@ -7878,7 +7878,7 @@ popdisplay(d::Display) Returns the number of bytes available for reading before a read from this stream or buffer will block. ``` - """ Base.nb_available + """ nb_available @doc doc""" ```rst @@ -7888,7 +7888,7 @@ popdisplay(d::Display) to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. ``` - """ Base.accept + """ accept @doc doc""" ```rst @@ -7898,7 +7898,7 @@ popdisplay(d::Display) Returns a tuple of the actual port that the server was created on and the server itself. ``` - """ Base.listenany + """ listenany @doc doc""" ```rst @@ -7914,7 +7914,7 @@ popdisplay(d::Display) "writable" when using polling, and "status" is always 0. Pass "false" for "cb" to not use a callback function. ``` - """ Base.watch_file + """ watch_file @doc doc""" ```rst @@ -7928,7 +7928,7 @@ popdisplay(d::Display) returned value is an object with boolean fields "readable", "writable", and "timedout", giving the result of the polling. ``` - """ Base.poll_fd + """ poll_fd @doc doc""" ```rst @@ -7938,7 +7938,7 @@ popdisplay(d::Display) seconds for *seconds* seconds. A return value of true indicates the file changed, a return value of false indicates a timeout. ``` - """ Base.poll_file + """ poll_file @doc doc""" ```rst @@ -7947,7 +7947,7 @@ popdisplay(d::Display) Bind "socket" to the given "host:port". Note that *0.0.0.0* will listen on all devices. ``` - """ Base.bind + """ bind @doc doc""" ```rst @@ -7955,7 +7955,7 @@ popdisplay(d::Display) Send "msg" over "socket to ``host:port". ``` - """ Base.send + """ send @doc doc""" ```rst @@ -7964,7 +7964,7 @@ popdisplay(d::Display) Read a UDP packet from the specified socket, and return the bytes received. This call blocks. ``` - """ Base.recv + """ recv @doc doc""" ```rst @@ -7974,7 +7974,7 @@ popdisplay(d::Display) (address, data), where address will be either IPv4 or IPv6 as appropriate. ``` - """ Base.recvfrom + """ recvfrom @doc doc""" ```rst @@ -7987,7 +7987,7 @@ popdisplay(d::Display) return an access error (default: false). "ttl": Time-to-live of packets sent on the socket. ``` - """ Base.setopt + """ setopt @doc doc""" ```rst @@ -7996,7 +7996,7 @@ popdisplay(d::Display) Converts the endianness of a value from Network byte order (big- endian) to that used by the Host. ``` - """ Base.ntoh + """ ntoh @doc doc""" ```rst @@ -8005,7 +8005,7 @@ popdisplay(d::Display) Converts the endianness of a value from that used by the Host to Network byte order (big-endian). ``` - """ Base.hton + """ hton @doc doc""" ```rst @@ -8014,7 +8014,7 @@ popdisplay(d::Display) Converts the endianness of a value from Little-endian to that used by the Host. ``` - """ Base.ltoh + """ ltoh @doc doc""" ```rst @@ -8023,7 +8023,7 @@ popdisplay(d::Display) Converts the endianness of a value from that used by the Host to Little-endian. ``` - """ Base.htol + """ htol @doc doc""" ```rst @@ -8033,7 +8033,7 @@ popdisplay(d::Display) host machine. Little-endian machines will contain the value 0x04030201. Big-endian machines will contain the value 0x01020304. ``` - """ Base.ENDIAN_BOM + """ ENDIAN_BOM @doc doc""" ```rst @@ -8402,7 +8402,7 @@ popdisplay(d::Display) Compute the dot product. For complex vectors, the first vector is conjugated. ``` - """ Base.dot + """ dot @doc doc""" ```rst @@ -8413,7 +8413,7 @@ popdisplay(d::Display) defined), compute the Euclidean dot product (the sum of "dot(x[i],y[i])") as if they were vectors. ``` - """ Base.vecdot + """ vecdot @doc doc""" ```rst @@ -8422,7 +8422,7 @@ popdisplay(d::Display) Compute the cross product of two 3-vectors. ``` - """ Base.cross + """ cross @doc doc""" ```rst @@ -8434,7 +8434,7 @@ popdisplay(d::Display) efficient solving of multiple systems. For example: "A=factorize(A); x=A\\b; y=A\\C". ``` - """ Base.factorize + """ factorize @doc doc""" ```rst @@ -8443,7 +8443,7 @@ popdisplay(d::Display) Reconstruct the matrix "A" from the factorization "F=factorize(A)". ``` - """ Base.full + """ full @doc doc""" ```rst @@ -8451,7 +8451,7 @@ popdisplay(d::Display) Compute the LU factorization of "A", such that "A[p,:] = L*U". ``` - """ Base.lu + """ lu @doc doc""" ```rst @@ -8512,7 +8512,7 @@ popdisplay(d::Display) | \"size\" | ✓ | ✓ | | +--------------------+--------+--------------------------+---------------+ ``` - """ Base.lufact + """ lufact @doc doc""" ```rst @@ -8524,7 +8524,7 @@ popdisplay(d::Display) "colptr" and "rowval" are decremented in place, converting from 1-based indices to 0-based indices. ``` - """ Base.lufact! + """ lufact! @doc doc""" ```rst @@ -8536,7 +8536,7 @@ popdisplay(d::Display) "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" and "A = F*F'". "LU" defaults to "Val{:U}". ``` - """ Base.chol + """ chol @doc doc""" ```rst @@ -8556,7 +8556,7 @@ popdisplay(d::Display) determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. ``` - """ Base.cholfact + """ cholfact @doc doc""" ```rst @@ -8584,7 +8584,7 @@ popdisplay(d::Display) The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. ``` - """ Base.cholfact + """ cholfact @doc doc""" ```rst @@ -8596,7 +8596,7 @@ popdisplay(d::Display) different matrix "F" with the same structure when used as: "cholfact!(F::CholmodFactor, A)". ``` - """ Base.cholfact! + """ cholfact! @doc doc""" ```rst @@ -8606,7 +8606,7 @@ popdisplay(d::Display) that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular matrix and "d" is a vector with non-negative elements. ``` - """ Base.ldltfact + """ ldltfact @doc doc""" ```rst @@ -8636,7 +8636,7 @@ popdisplay(d::Display) The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. ``` - """ Base.ldltfact + """ ldltfact @doc doc""" ```rst @@ -8647,7 +8647,7 @@ popdisplay(d::Display) is to compute a thin factorization. Note that "R" is not extended with zeros when the full "Q" is requested. ``` - """ Base.qr + """ qr @doc doc""" ```rst @@ -8729,7 +8729,7 @@ popdisplay(d::Display) Householder transformations, SIAM J Sci Stat Comput 10 (1989), 53-57. doi:10.1137/0910005 ``` - """ Base.qrfact + """ qrfact @doc doc""" ```rst @@ -8741,7 +8741,7 @@ popdisplay(d::Display) C library SPQR and a few additional functions from the library are wrapped but not exported. ``` - """ Base.qrfact + """ qrfact @doc doc""" ```rst @@ -8751,7 +8751,7 @@ popdisplay(d::Display) "StridedMatrix", but saves space by overwriting the input "A", instead of creating a copy. ``` - """ Base.qrfact! + """ qrfact! @doc doc""" ```rst @@ -8768,7 +8768,7 @@ popdisplay(d::Display) factorization). If "false", returns a "Q" that spans all rows of "R" in its corresponding QR factorization. ``` - """ Base.full + """ full @doc doc""" ```rst @@ -8780,7 +8780,7 @@ popdisplay(d::Display) "BunchKaufman" objects: "size", "\", "inv", "issym", "ishermitian". ``` - """ Base.bkfact + """ bkfact @doc doc""" ```rst @@ -8789,7 +8789,7 @@ popdisplay(d::Display) "bkfact!" is the same as "bkfact()", but saves space by overwriting the input "A", instead of creating a copy. ``` - """ Base.bkfact! + """ bkfact! @doc doc""" ```rst @@ -8806,7 +8806,7 @@ popdisplay(d::Display) square root has "Real" elements, otherwise it has "Complex" elements. ``` - """ Base.sqrtm + """ sqrtm @doc doc""" ```rst @@ -8826,7 +8826,7 @@ popdisplay(d::Display) the factorization to a tuple; where possible, using "eigfact()" is recommended. ``` - """ Base.eig + """ eig @doc doc""" ```rst @@ -8839,7 +8839,7 @@ popdisplay(d::Display) the factorization to a tuple; where possible, using "eigfact()" is recommended. ``` - """ Base.eig + """ eig @doc doc""" ```rst @@ -8859,7 +8859,7 @@ popdisplay(d::Display) diagonal elements to make rows and columns more equal in norm. The default is "true" for both options. ``` - """ Base.eigvals + """ eigvals @doc doc""" ```rst @@ -8867,7 +8867,7 @@ popdisplay(d::Display) Returns the largest eigenvalue of "A". ``` - """ Base.eigmax + """ eigmax @doc doc""" ```rst @@ -8875,7 +8875,7 @@ popdisplay(d::Display) Returns the smallest eigenvalue of "A". ``` - """ Base.eigmin + """ eigmin @doc doc""" ```rst @@ -8890,7 +8890,7 @@ popdisplay(d::Display) eigenvalues "eigvals" is specified, returns the specific corresponding eigenvectors. ``` - """ Base.eigvecs + """ eigvecs @doc doc""" ```rst @@ -8918,7 +8918,7 @@ popdisplay(d::Display) elements to make rows and columns more equal in norm. The default is "true" for both options. ``` - """ Base.eigfact + """ eigfact @doc doc""" ```rst @@ -8931,7 +8931,7 @@ popdisplay(d::Display) "F[:vectors]". (The "k"th generalized eigenvector can be obtained from the slice "F[:vectors][:, k]".) ``` - """ Base.eigfact + """ eigfact @doc doc""" ```rst @@ -8940,7 +8940,7 @@ popdisplay(d::Display) Same as "eigfact()", but saves space by overwriting the input "A" (and "B"), instead of creating a copy. ``` - """ Base.eigfact! + """ eigfact! @doc doc""" ```rst @@ -8953,7 +8953,7 @@ popdisplay(d::Display) is the "HessenbergQ" object, and may be converted to a regular matrix with "full()". ``` - """ Base.hessfact + """ hessfact @doc doc""" ```rst @@ -8962,7 +8962,7 @@ popdisplay(d::Display) "hessfact!" is the same as "hessfact()", but saves space by overwriting the input A, instead of creating a copy. ``` - """ Base.hessfact! + """ hessfact! @doc doc""" ```rst @@ -8976,7 +8976,7 @@ popdisplay(d::Display) "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" can be obtained with "F[:values]". ``` - """ Base.schurfact + """ schurfact @doc doc""" ```rst @@ -8985,7 +8985,7 @@ popdisplay(d::Display) Computes the Schur factorization of "A", overwriting "A" in the process. See "schurfact()" ``` - """ Base.schurfact! + """ schurfact! @doc doc""" ```rst @@ -8993,7 +8993,7 @@ popdisplay(d::Display) See "schurfact()" ``` - """ Base.schur + """ schur @doc doc""" ```rst @@ -9007,7 +9007,7 @@ popdisplay(d::Display) right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via "select". ``` - """ Base.ordschur + """ ordschur @doc doc""" ```rst @@ -9016,7 +9016,7 @@ popdisplay(d::Display) Reorders the Schur factorization of a real matrix "A=Q*T*Q'", overwriting "Q" and "T" in the process. See "ordschur()" ``` - """ Base.ordschur! + """ ordschur! @doc doc""" ```rst @@ -9024,7 +9024,7 @@ popdisplay(d::Display) Reorders the Schur factorization "S" of type "Schur". ``` - """ Base.ordschur + """ ordschur @doc doc""" ```rst @@ -9033,7 +9033,7 @@ popdisplay(d::Display) Reorders the Schur factorization "S" of type "Schur", overwriting "S" in the process. See "ordschur()" ``` - """ Base.ordschur! + """ ordschur! @doc doc""" ```rst @@ -9049,7 +9049,7 @@ popdisplay(d::Display) "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of "A" and "B" can be obtained with "F[:alpha]./F[:beta]". ``` - """ Base.schurfact + """ schurfact @doc doc""" ```rst @@ -9057,7 +9057,7 @@ popdisplay(d::Display) See "schurfact()" ``` - """ Base.schur + """ schur @doc doc""" ```rst @@ -9073,7 +9073,7 @@ popdisplay(d::Display) "A" and "B" can still be obtained with "GS[:alpha]./GS[:beta]". ``` - """ Base.ordschur + """ ordschur @doc doc""" ```rst @@ -9083,7 +9083,7 @@ popdisplay(d::Display) overwriting the matrices "(S, T, Q, Z)" in the process. See "ordschur()". ``` - """ Base.ordschur! + """ ordschur! @doc doc""" ```rst @@ -9092,7 +9092,7 @@ popdisplay(d::Display) Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". ``` - """ Base.ordschur + """ ordschur @doc doc""" ```rst @@ -9102,7 +9102,7 @@ popdisplay(d::Display) object by overwriting the object with the new factorization. See "ordschur()". ``` - """ Base.ordschur! + """ ordschur! @doc doc""" ```rst @@ -9116,7 +9116,7 @@ popdisplay(d::Display) produces "Vt" and hence "Vt" is more efficient to extract than "V". The default is to produce a thin decomposition. ``` - """ Base.svdfact + """ svdfact @doc doc""" ```rst @@ -9127,7 +9127,7 @@ popdisplay(d::Display) "true", an economy mode decomposition is returned. The default is to produce a thin decomposition. ``` - """ Base.svdfact! + """ svdfact! @doc doc""" ```rst @@ -9140,7 +9140,7 @@ popdisplay(d::Display) "true", an economy mode decomposition is returned. The default is to produce a thin decomposition. ``` - """ Base.svd + """ svd @doc doc""" ```rst @@ -9148,7 +9148,7 @@ popdisplay(d::Display) Returns the singular values of "A". ``` - """ Base.svdvals + """ svdvals @doc doc""" ```rst @@ -9157,7 +9157,7 @@ popdisplay(d::Display) Returns the singular values of "A", while saving space by overwriting the input. ``` - """ Base.svdvals! + """ svdvals! @doc doc""" ```rst @@ -9168,7 +9168,7 @@ popdisplay(d::Display) F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = F[:V]*F[:D2]*F[:R0]*F[:Q]'". ``` - """ Base.svdfact + """ svdfact @doc doc""" ```rst @@ -9180,7 +9180,7 @@ popdisplay(d::Display) "B", returning "U", "V", "Q", "D1", "D2", and "R0" such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". ``` - """ Base.svd + """ svd @doc doc""" ```rst @@ -9189,7 +9189,7 @@ popdisplay(d::Display) Return only the singular values from the generalized singular value decomposition of "A" and "B". ``` - """ Base.svdvals + """ svdvals @doc doc""" ```rst @@ -9197,7 +9197,7 @@ popdisplay(d::Display) Upper triangle of a matrix. ``` - """ Base.triu + """ triu @doc doc""" ```rst @@ -9206,7 +9206,7 @@ popdisplay(d::Display) Returns the upper triangle of "M" starting from the "k"th superdiagonal. ``` - """ Base.triu + """ triu @doc doc""" ```rst @@ -9214,7 +9214,7 @@ popdisplay(d::Display) Upper triangle of a matrix, overwriting "M" in the process. ``` - """ Base.triu! + """ triu! @doc doc""" ```rst @@ -9223,7 +9223,7 @@ popdisplay(d::Display) Returns the upper triangle of "M" starting from the "k"th superdiagonal, overwriting "M" in the process. ``` - """ Base.triu! + """ triu! @doc doc""" ```rst @@ -9231,7 +9231,7 @@ popdisplay(d::Display) Lower triangle of a matrix. ``` - """ Base.tril + """ tril @doc doc""" ```rst @@ -9240,7 +9240,7 @@ popdisplay(d::Display) Returns the lower triangle of "M" starting from the "k"th subdiagonal. ``` - """ Base.tril + """ tril @doc doc""" ```rst @@ -9248,7 +9248,7 @@ popdisplay(d::Display) Lower triangle of a matrix, overwriting "M" in the process. ``` - """ Base.tril! + """ tril! @doc doc""" ```rst @@ -9257,7 +9257,7 @@ popdisplay(d::Display) Returns the lower triangle of "M" starting from the "k"th subdiagonal, overwriting "M" in the process. ``` - """ Base.tril! + """ tril! @doc doc""" ```rst @@ -9266,7 +9266,7 @@ popdisplay(d::Display) A "Range" giving the indices of the "k"th diagonal of the matrix "M". ``` - """ Base.diagind + """ diagind @doc doc""" ```rst @@ -9275,7 +9275,7 @@ popdisplay(d::Display) The "k"th diagonal of a matrix, as a vector. Use "diagm" to construct a diagonal matrix. ``` - """ Base.diag + """ diag @doc doc""" ```rst @@ -9284,13 +9284,13 @@ popdisplay(d::Display) Construct a diagonal matrix and place "v" on the "k"th diagonal. ``` - """ Base.diagm + """ diagm @doc doc""" ```rst scale(A, b) ``` - """ Base.scale + """ scale @doc doc""" ```rst @@ -9307,13 +9307,13 @@ popdisplay(d::Display) Note: for large "A", "scale" can be much faster than "A .* b" or "b .* A", due to the use of BLAS. ``` - """ Base.scale + """ scale @doc doc""" ```rst scale!(A, b) ``` - """ Base.scale! + """ scale! @doc doc""" ```rst @@ -9328,7 +9328,7 @@ popdisplay(d::Display) "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- place on "A". ``` - """ Base.scale! + """ scale! @doc doc""" ```rst @@ -9339,7 +9339,7 @@ popdisplay(d::Display) "Tridiagonal" and provides efficient specialized linear solvers, but may be converted into a regular matrix with "full()". ``` - """ Base.Tridiagonal + """ Tridiagonal @doc doc""" ```rst @@ -9351,7 +9351,7 @@ popdisplay(d::Display) and provides efficient specialized linear solvers, but may be converted into a regular matrix with "full()". ``` - """ Base.Bidiagonal + """ Bidiagonal @doc doc""" ```rst @@ -9362,7 +9362,7 @@ popdisplay(d::Display) "SymTridiagonal" and provides efficient specialized eigensolvers, but may be converted into a regular matrix with "full()". ``` - """ Base.SymTridiagonal + """ SymTridiagonal @doc doc""" ```rst @@ -9370,7 +9370,7 @@ popdisplay(d::Display) Compute the rank of a matrix. ``` - """ Base.rank + """ rank @doc doc""" ```rst @@ -9388,7 +9388,7 @@ popdisplay(d::Display) (Note that for sparse matrices, "p=2" is currently not implemented.) Use "vecnorm()" to compute the Frobenius norm. ``` - """ Base.norm + """ norm @doc doc""" ```rst @@ -9402,7 +9402,7 @@ popdisplay(d::Display) For example, if "A" is a matrix and "p=2", then this is equivalent to the Frobenius norm. ``` - """ Base.vecnorm + """ vecnorm @doc doc""" ```rst @@ -9412,7 +9412,7 @@ popdisplay(d::Display) "p"-norm. Valid values for "p" are "1", "2" (default), or "Inf". ``` - """ Base.cond + """ cond @doc doc""" ```rst @@ -9433,7 +9433,7 @@ popdisplay(d::Display) condition number, relative condition number, or componentwise relative condition number. ``` - """ Base.condskeel + """ condskeel @doc doc""" ```rst @@ -9441,7 +9441,7 @@ popdisplay(d::Display) Matrix trace ``` - """ Base.trace + """ trace @doc doc""" ```rst @@ -9449,7 +9449,7 @@ popdisplay(d::Display) Matrix determinant ``` - """ Base.det + """ det @doc doc""" ```rst @@ -9458,7 +9458,7 @@ popdisplay(d::Display) Log of matrix determinant. Equivalent to "log(det(M))", but may provide increased accuracy and/or speed. ``` - """ Base.logdet + """ logdet @doc doc""" ```rst @@ -9466,7 +9466,7 @@ popdisplay(d::Display) Matrix inverse ``` - """ Base.inv + """ inv @doc doc""" ```rst @@ -9506,7 +9506,7 @@ popdisplay(d::Display) Speech and Signal Processing, 36(5), 1988, 757-763. doi:10.1109/29.1585 ``` - """ Base.pinv + """ pinv @doc doc""" ```rst @@ -9514,7 +9514,7 @@ popdisplay(d::Display) Basis for nullspace of "M". ``` - """ Base.nullspace + """ nullspace @doc doc""" ```rst @@ -9523,7 +9523,7 @@ popdisplay(d::Display) Construct a matrix by repeating the given matrix "n" times in dimension 1 and "m" times in dimension 2. ``` - """ Base.repmat + """ repmat @doc doc""" ```rst @@ -9536,7 +9536,7 @@ popdisplay(d::Display) times that a slice along the i-th dimension of "A" should be repeated. ``` - """ Base.repeat + """ repeat @doc doc""" ```rst @@ -9544,7 +9544,7 @@ popdisplay(d::Display) Kronecker tensor product of two vectors or two matrices. ``` - """ Base.kron + """ kron @doc doc""" ```rst @@ -9553,7 +9553,7 @@ popdisplay(d::Display) Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. ``` - """ Base.blkdiag + """ blkdiag @doc doc""" ```rst @@ -9573,7 +9573,7 @@ popdisplay(d::Display) plot(x, y, "o") # Plot (x,y) points plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression ``` - """ Base.linreg + """ linreg @doc doc""" ```rst @@ -9581,7 +9581,7 @@ popdisplay(d::Display) Weighted least-squares linear regression. ``` - """ Base.linreg + """ linreg @doc doc""" ```rst @@ -9589,7 +9589,7 @@ popdisplay(d::Display) Matrix exponential. ``` - """ Base.expm + """ expm @doc doc""" ```rst @@ -9600,7 +9600,7 @@ popdisplay(d::Display) part and no two eigenvalues are negative complex conjugates of each other. ``` - """ Base.lyap + """ lyap @doc doc""" ```rst @@ -9610,7 +9610,7 @@ popdisplay(d::Display) = 0", where "A", "B" and "C" have compatible dimensions and "A" and "-B" have no eigenvalues with equal real part. ``` - """ Base.sylvester + """ sylvester @doc doc""" ```rst @@ -9618,7 +9618,7 @@ popdisplay(d::Display) Test whether a matrix is symmetric. ``` - """ Base.issym + """ issym @doc doc""" ```rst @@ -9626,7 +9626,7 @@ popdisplay(d::Display) Test whether a matrix is positive definite. ``` - """ Base.isposdef + """ isposdef @doc doc""" ```rst @@ -9635,7 +9635,7 @@ popdisplay(d::Display) Test whether a matrix is positive definite, overwriting "A" in the processes. ``` - """ Base.isposdef! + """ isposdef! @doc doc""" ```rst @@ -9643,7 +9643,7 @@ popdisplay(d::Display) Test whether a matrix is lower triangular. ``` - """ Base.istril + """ istril @doc doc""" ```rst @@ -9651,7 +9651,7 @@ popdisplay(d::Display) Test whether a matrix is upper triangular. ``` - """ Base.istriu + """ istriu @doc doc""" ```rst @@ -9659,7 +9659,7 @@ popdisplay(d::Display) Test whether a matrix is diagonal. ``` - """ Base.isdiag + """ isdiag @doc doc""" ```rst @@ -9667,7 +9667,7 @@ popdisplay(d::Display) Test whether a matrix is Hermitian. ``` - """ Base.ishermitian + """ ishermitian @doc doc""" ```rst @@ -9675,7 +9675,7 @@ popdisplay(d::Display) The transposition operator (".'"). ``` - """ Base.transpose + """ transpose @doc doc""" ```rst @@ -9687,7 +9687,7 @@ popdisplay(d::Display) supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. ``` - """ Base.transpose! + """ transpose! @doc doc""" ```rst @@ -9695,7 +9695,7 @@ popdisplay(d::Display) The conjugate transposition operator ("'"). ``` - """ Base.ctranspose + """ ctranspose @doc doc""" ```rst @@ -9707,7 +9707,7 @@ popdisplay(d::Display) supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. ``` - """ Base.ctranspose! + """ ctranspose! @doc doc""" ```rst @@ -9786,7 +9786,7 @@ popdisplay(d::Display) | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | +-----------------+------------------------------------+------------------------------------+ ``` - """ Base.eigs + """ eigs @doc doc""" ```rst @@ -9816,7 +9816,7 @@ popdisplay(d::Display) X = sprand(10, 5, 0.2) svds(X, nsv = 2) ``` - """ Base.svds + """ svds @doc doc""" ```rst @@ -9835,7 +9835,7 @@ popdisplay(d::Display) in parallel, only 1 BLAS thread is used. The argument "n" still refers to the size of the problem that is solved on each processor. ``` - """ Base.peakflops + """ peakflops @doc doc""" ```rst @@ -10282,7 +10282,7 @@ popdisplay(d::Display) Unary minus operator. ``` - """ Base.(:(-)) + """ - @doc doc""" ```rst @@ -10291,7 +10291,7 @@ popdisplay(d::Display) Addition operator. "x+y+z+..." calls this function with all arguments, i.e. "+(x, y, z, ...)". ``` - """ Base.(:(+)) + """ + @doc doc""" ```rst @@ -10299,7 +10299,7 @@ popdisplay(d::Display) Subtraction operator. ``` - """ Base.(:(-)) + """ - @doc doc""" ```rst @@ -10395,7 +10395,7 @@ popdisplay(d::Display) "x*y+z". "fma" is used to improve accuracy in certain algorithms. See "muladd". ``` - """ Base.fma + """ fma @doc doc""" ```rst @@ -10406,7 +10406,7 @@ popdisplay(d::Display) "fma(x,y,z)". "muladd" is used to improve performance. See "fma". ``` - """ Base.muladd + """ muladd @doc doc""" ```rst @@ -10416,7 +10416,7 @@ popdisplay(d::Display) The quotient from Euclidean division. Computes "x/y", truncated to an integer. ``` - """ Base.div + """ div @doc doc""" ```rst @@ -10424,7 +10424,7 @@ popdisplay(d::Display) Largest integer less than or equal to "x/y". ``` - """ Base.fld + """ fld @doc doc""" ```rst @@ -10432,7 +10432,7 @@ popdisplay(d::Display) Smallest integer larger than or equal to "x/y". ``` - """ Base.cld + """ cld @doc doc""" ```rst @@ -10441,7 +10441,7 @@ popdisplay(d::Display) Modulus after division, returning in the range [0,``y``), if "y" is positive, or ("y",0] if "y" is negative. ``` - """ Base.mod + """ mod @doc doc""" ```rst @@ -10454,7 +10454,7 @@ popdisplay(d::Display) not exactly the same as mod(x,2pi), which would compute the modulus of x relative to division by the floating-point number 2pi. ``` - """ Base.mod2pi + """ mod2pi @doc doc""" ```rst @@ -10465,7 +10465,7 @@ popdisplay(d::Display) sign as``x``, and smaller in magnitude than "y". This value is always exact. ``` - """ Base.rem + """ rem @doc doc""" ```rst @@ -10474,7 +10474,7 @@ popdisplay(d::Display) The quotient and remainder from Euclidean division. Equivalent to "(x÷y, x%y)". ``` - """ Base.divrem + """ divrem @doc doc""" ```rst @@ -10483,7 +10483,7 @@ popdisplay(d::Display) The floored quotient and modulus after division. Equivalent to "(fld(x,y), mod(x,y))". ``` - """ Base.fldmod + """ fldmod @doc doc""" ```rst @@ -10491,7 +10491,7 @@ popdisplay(d::Display) Modulus after division, returning in the range (0,m] ``` - """ Base.mod1 + """ mod1 @doc doc""" ```rst @@ -10499,7 +10499,7 @@ popdisplay(d::Display) Remainder after division, returning in the range (0,m] ``` - """ Base.rem1 + """ rem1 @doc doc""" ```rst @@ -10518,7 +10518,7 @@ popdisplay(d::Display) components of the given integer type. The result will differ from "x" by no more than "tol". ``` - """ Base.rationalize + """ rationalize @doc doc""" ```rst @@ -10526,7 +10526,7 @@ popdisplay(d::Display) Numerator of the rational representation of "x" ``` - """ Base.num + """ num @doc doc""" ```rst @@ -10534,7 +10534,7 @@ popdisplay(d::Display) Denominator of the rational representation of "x" ``` - """ Base.den + """ den @doc doc""" ```rst @@ -10569,7 +10569,7 @@ popdisplay(d::Display) "s". These syntaxes call the function "colon". The colon is also used in indexing to select whole dimensions. ``` - """ Base.(:(:)) + """ : @doc doc""" ```rst @@ -10577,7 +10577,7 @@ popdisplay(d::Display) Called by ":" syntax for constructing ranges. ``` - """ Base.colon + """ colon @doc doc""" ```rst @@ -10586,7 +10586,7 @@ popdisplay(d::Display) Construct a range by length, given a starting value and optional step (defaults to 1). ``` - """ Base.range + """ range @doc doc""" ```rst @@ -10739,7 +10739,7 @@ popdisplay(d::Display) implemented by "isless". For floating-point numbers, uses "<" but throws an error for unordered arguments. ``` - """ Base.cmp + """ cmp @doc doc""" ```rst @@ -10747,7 +10747,7 @@ popdisplay(d::Display) Bitwise not ``` - """ Base.(:(~)) + """ ~ @doc doc""" ```rst @@ -10755,7 +10755,7 @@ popdisplay(d::Display) Bitwise and ``` - """ Base.(:(&)) + """ & @doc doc""" ```rst @@ -10771,7 +10771,7 @@ popdisplay(d::Display) Bitwise exclusive or ``` - """ Base.(:($)) + """ $ @doc doc""" ```rst @@ -10779,7 +10779,7 @@ popdisplay(d::Display) Boolean not ``` - """ Base.(:(!)) + """ ! @doc doc""" ```rst @@ -10787,7 +10787,7 @@ popdisplay(d::Display) Matrix operator A \ B^H ``` - """ Base.A_ldiv_Bc + """ A_ldiv_Bc @doc doc""" ```rst @@ -10795,7 +10795,7 @@ popdisplay(d::Display) Matrix operator A \ B^T ``` - """ Base.A_ldiv_Bt + """ A_ldiv_Bt @doc doc""" ```rst @@ -10811,7 +10811,7 @@ popdisplay(d::Display) 3.0 3.0 7.0 7.0 ``` - """ Base.A_mul_B! + """ A_mul_B! @doc doc""" ```rst @@ -10819,7 +10819,7 @@ popdisplay(d::Display) Matrix operator A B^H ``` - """ Base.A_mul_Bc + """ A_mul_Bc @doc doc""" ```rst @@ -10827,7 +10827,7 @@ popdisplay(d::Display) Matrix operator A B^T ``` - """ Base.A_mul_Bt + """ A_mul_Bt @doc doc""" ```rst @@ -10835,7 +10835,7 @@ popdisplay(d::Display) Matrix operator A / B^H ``` - """ Base.A_rdiv_Bc + """ A_rdiv_Bc @doc doc""" ```rst @@ -10843,7 +10843,7 @@ popdisplay(d::Display) Matrix operator A / B^T ``` - """ Base.A_rdiv_Bt + """ A_rdiv_Bt @doc doc""" ```rst @@ -10851,7 +10851,7 @@ popdisplay(d::Display) Matrix operator A^H \ B ``` - """ Base.Ac_ldiv_B + """ Ac_ldiv_B @doc doc""" ```rst @@ -10859,7 +10859,7 @@ popdisplay(d::Display) Matrix operator A^H \ B^H ``` - """ Base.Ac_ldiv_Bc + """ Ac_ldiv_Bc @doc doc""" ```rst @@ -10867,7 +10867,7 @@ popdisplay(d::Display) Matrix operator A^H B ``` - """ Base.Ac_mul_B + """ Ac_mul_B @doc doc""" ```rst @@ -10875,7 +10875,7 @@ popdisplay(d::Display) Matrix operator A^H B^H ``` - """ Base.Ac_mul_Bc + """ Ac_mul_Bc @doc doc""" ```rst @@ -10883,7 +10883,7 @@ popdisplay(d::Display) Matrix operator A^H / B ``` - """ Base.Ac_rdiv_B + """ Ac_rdiv_B @doc doc""" ```rst @@ -10891,7 +10891,7 @@ popdisplay(d::Display) Matrix operator A^H / B^H ``` - """ Base.Ac_rdiv_Bc + """ Ac_rdiv_Bc @doc doc""" ```rst @@ -10899,7 +10899,7 @@ popdisplay(d::Display) Matrix operator A^T \ B ``` - """ Base.At_ldiv_B + """ At_ldiv_B @doc doc""" ```rst @@ -10907,7 +10907,7 @@ popdisplay(d::Display) Matrix operator A^T \ B^T ``` - """ Base.At_ldiv_Bt + """ At_ldiv_Bt @doc doc""" ```rst @@ -10915,7 +10915,7 @@ popdisplay(d::Display) Matrix operator A^T B ``` - """ Base.At_mul_B + """ At_mul_B @doc doc""" ```rst @@ -10923,7 +10923,7 @@ popdisplay(d::Display) Matrix operator A^T B^T ``` - """ Base.At_mul_Bt + """ At_mul_Bt @doc doc""" ```rst @@ -10931,7 +10931,7 @@ popdisplay(d::Display) Matrix operator A^T / B ``` - """ Base.At_rdiv_B + """ At_rdiv_B @doc doc""" ```rst @@ -10939,7 +10939,7 @@ popdisplay(d::Display) Matrix operator A^T / B^T ``` - """ Base.At_rdiv_Bt + """ At_rdiv_Bt @doc doc""" ```rst @@ -10962,7 +10962,7 @@ popdisplay(d::Display) For default tolerance arguments, "maxeps = max(eps(abs(x)), eps(abs(y)))". ``` - """ Base.isapprox + """ isapprox @doc doc""" ```rst @@ -10970,7 +10970,7 @@ popdisplay(d::Display) Compute sine of "x", where "x" is in radians ``` - """ Base.sin + """ sin @doc doc""" ```rst @@ -10978,7 +10978,7 @@ popdisplay(d::Display) Compute cosine of "x", where "x" is in radians ``` - """ Base.cos + """ cos @doc doc""" ```rst @@ -10986,7 +10986,7 @@ popdisplay(d::Display) Compute tangent of "x", where "x" is in radians ``` - """ Base.tan + """ tan @doc doc""" ```rst @@ -10994,7 +10994,7 @@ popdisplay(d::Display) Compute sine of "x", where "x" is in degrees ``` - """ Base.sind + """ sind @doc doc""" ```rst @@ -11002,7 +11002,7 @@ popdisplay(d::Display) Compute cosine of "x", where "x" is in degrees ``` - """ Base.cosd + """ cosd @doc doc""" ```rst @@ -11010,7 +11010,7 @@ popdisplay(d::Display) Compute tangent of "x", where "x" is in degrees ``` - """ Base.tand + """ tand @doc doc""" ```rst @@ -11019,7 +11019,7 @@ popdisplay(d::Display) Compute \sin(\pi x) more accurately than "sin(pi*x)", especially for large "x". ``` - """ Base.sinpi + """ sinpi @doc doc""" ```rst @@ -11028,7 +11028,7 @@ popdisplay(d::Display) Compute \cos(\pi x) more accurately than "cos(pi*x)", especially for large "x". ``` - """ Base.cospi + """ cospi @doc doc""" ```rst @@ -11036,7 +11036,7 @@ popdisplay(d::Display) Compute hyperbolic sine of "x" ``` - """ Base.sinh + """ sinh @doc doc""" ```rst @@ -11044,7 +11044,7 @@ popdisplay(d::Display) Compute hyperbolic cosine of "x" ``` - """ Base.cosh + """ cosh @doc doc""" ```rst @@ -11052,7 +11052,7 @@ popdisplay(d::Display) Compute hyperbolic tangent of "x" ``` - """ Base.tanh + """ tanh @doc doc""" ```rst @@ -11060,7 +11060,7 @@ popdisplay(d::Display) Compute the inverse sine of "x", where the output is in radians ``` - """ Base.asin + """ asin @doc doc""" ```rst @@ -11068,7 +11068,7 @@ popdisplay(d::Display) Compute the inverse cosine of "x", where the output is in radians ``` - """ Base.acos + """ acos @doc doc""" ```rst @@ -11077,7 +11077,7 @@ popdisplay(d::Display) Compute the inverse tangent of "x", where the output is in radians ``` - """ Base.atan + """ atan @doc doc""" ```rst @@ -11086,7 +11086,7 @@ popdisplay(d::Display) Compute the inverse tangent of "y/x", using the signs of both "x" and "y" to determine the quadrant of the return value. ``` - """ Base.atan2 + """ atan2 @doc doc""" ```rst @@ -11094,7 +11094,7 @@ popdisplay(d::Display) Compute the inverse sine of "x", where the output is in degrees ``` - """ Base.asind + """ asind @doc doc""" ```rst @@ -11102,7 +11102,7 @@ popdisplay(d::Display) Compute the inverse cosine of "x", where the output is in degrees ``` - """ Base.acosd + """ acosd @doc doc""" ```rst @@ -11111,7 +11111,7 @@ popdisplay(d::Display) Compute the inverse tangent of "x", where the output is in degrees ``` - """ Base.atand + """ atand @doc doc""" ```rst @@ -11119,7 +11119,7 @@ popdisplay(d::Display) Compute the secant of "x", where "x" is in radians ``` - """ Base.sec + """ sec @doc doc""" ```rst @@ -11127,7 +11127,7 @@ popdisplay(d::Display) Compute the cosecant of "x", where "x" is in radians ``` - """ Base.csc + """ csc @doc doc""" ```rst @@ -11135,7 +11135,7 @@ popdisplay(d::Display) Compute the cotangent of "x", where "x" is in radians ``` - """ Base.cot + """ cot @doc doc""" ```rst @@ -11143,7 +11143,7 @@ popdisplay(d::Display) Compute the secant of "x", where "x" is in degrees ``` - """ Base.secd + """ secd @doc doc""" ```rst @@ -11151,7 +11151,7 @@ popdisplay(d::Display) Compute the cosecant of "x", where "x" is in degrees ``` - """ Base.cscd + """ cscd @doc doc""" ```rst @@ -11159,7 +11159,7 @@ popdisplay(d::Display) Compute the cotangent of "x", where "x" is in degrees ``` - """ Base.cotd + """ cotd @doc doc""" ```rst @@ -11167,7 +11167,7 @@ popdisplay(d::Display) Compute the inverse secant of "x", where the output is in radians ``` - """ Base.asec + """ asec @doc doc""" ```rst @@ -11176,7 +11176,7 @@ popdisplay(d::Display) Compute the inverse cosecant of "x", where the output is in radians ``` - """ Base.acsc + """ acsc @doc doc""" ```rst @@ -11185,7 +11185,7 @@ popdisplay(d::Display) Compute the inverse cotangent of "x", where the output is in radians ``` - """ Base.acot + """ acot @doc doc""" ```rst @@ -11193,7 +11193,7 @@ popdisplay(d::Display) Compute the inverse secant of "x", where the output is in degrees ``` - """ Base.asecd + """ asecd @doc doc""" ```rst @@ -11202,7 +11202,7 @@ popdisplay(d::Display) Compute the inverse cosecant of "x", where the output is in degrees ``` - """ Base.acscd + """ acscd @doc doc""" ```rst @@ -11211,7 +11211,7 @@ popdisplay(d::Display) Compute the inverse cotangent of "x", where the output is in degrees ``` - """ Base.acotd + """ acotd @doc doc""" ```rst @@ -11219,7 +11219,7 @@ popdisplay(d::Display) Compute the hyperbolic secant of "x" ``` - """ Base.sech + """ sech @doc doc""" ```rst @@ -11227,7 +11227,7 @@ popdisplay(d::Display) Compute the hyperbolic cosecant of "x" ``` - """ Base.csch + """ csch @doc doc""" ```rst @@ -11235,7 +11235,7 @@ popdisplay(d::Display) Compute the hyperbolic cotangent of "x" ``` - """ Base.coth + """ coth @doc doc""" ```rst @@ -11243,7 +11243,7 @@ popdisplay(d::Display) Compute the inverse hyperbolic sine of "x" ``` - """ Base.asinh + """ asinh @doc doc""" ```rst @@ -11251,7 +11251,7 @@ popdisplay(d::Display) Compute the inverse hyperbolic cosine of "x" ``` - """ Base.acosh + """ acosh @doc doc""" ```rst @@ -11259,7 +11259,7 @@ popdisplay(d::Display) Compute the inverse hyperbolic tangent of "x" ``` - """ Base.atanh + """ atanh @doc doc""" ```rst @@ -11267,7 +11267,7 @@ popdisplay(d::Display) Compute the inverse hyperbolic secant of "x" ``` - """ Base.asech + """ asech @doc doc""" ```rst @@ -11275,7 +11275,7 @@ popdisplay(d::Display) Compute the inverse hyperbolic cosecant of "x" ``` - """ Base.acsch + """ acsch @doc doc""" ```rst @@ -11283,7 +11283,7 @@ popdisplay(d::Display) Compute the inverse hyperbolic cotangent of "x" ``` - """ Base.acoth + """ acoth @doc doc""" ```rst @@ -11291,7 +11291,7 @@ popdisplay(d::Display) Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. ``` - """ Base.sinc + """ sinc @doc doc""" ```rst @@ -11300,7 +11300,7 @@ popdisplay(d::Display) Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq 0, and 0 if x = 0. This is the derivative of "sinc(x)". ``` - """ Base.cosc + """ cosc @doc doc""" ```rst @@ -11308,7 +11308,7 @@ popdisplay(d::Display) Convert "x" from degrees to radians ``` - """ Base.deg2rad + """ deg2rad @doc doc""" ```rst @@ -11316,7 +11316,7 @@ popdisplay(d::Display) Convert "x" from radians to degrees ``` - """ Base.rad2deg + """ rad2deg @doc doc""" ```rst @@ -11324,7 +11324,7 @@ popdisplay(d::Display) Compute the \sqrt{x^2+y^2} avoiding overflow and underflow ``` - """ Base.hypot + """ hypot @doc doc""" ```rst @@ -11337,7 +11337,7 @@ popdisplay(d::Display) There is an experimental variant in the "Base.Math.JuliaLibm" module, which is typically faster and more accurate. ``` - """ Base.log + """ log @doc doc""" ```rst @@ -11346,7 +11346,7 @@ popdisplay(d::Display) Compute the base "b" logarithm of "x". Throws "DomainError" for negative "Real" arguments. ``` - """ Base.log + """ log @doc doc""" ```rst @@ -11355,7 +11355,7 @@ popdisplay(d::Display) Compute the logarithm of "x" to base 2. Throws "DomainError" for negative "Real" arguments. ``` - """ Base.log2 + """ log2 @doc doc""" ```rst @@ -11364,7 +11364,7 @@ popdisplay(d::Display) Compute the logarithm of "x" to base 10. Throws "DomainError" for negative "Real" arguments. ``` - """ Base.log10 + """ log10 @doc doc""" ```rst @@ -11376,7 +11376,7 @@ popdisplay(d::Display) There is an experimental variant in the "Base.Math.JuliaLibm" module, which is typically faster and more accurate. ``` - """ Base.log1p + """ log1p @doc doc""" ```rst @@ -11385,7 +11385,7 @@ popdisplay(d::Display) Return "(x,exp)" such that "x" has a magnitude in the interval "[1/2, 1)" or 0, and val = x \times 2^{exp}. ``` - """ Base.frexp + """ frexp @doc doc""" ```rst @@ -11393,7 +11393,7 @@ popdisplay(d::Display) Compute e^x ``` - """ Base.exp + """ exp @doc doc""" ```rst @@ -11401,7 +11401,7 @@ popdisplay(d::Display) Compute 2^x ``` - """ Base.exp2 + """ exp2 @doc doc""" ```rst @@ -11409,7 +11409,7 @@ popdisplay(d::Display) Compute 10^x ``` - """ Base.exp10 + """ exp10 @doc doc""" ```rst @@ -11417,7 +11417,7 @@ popdisplay(d::Display) Compute x \times 2^n ``` - """ Base.ldexp + """ ldexp @doc doc""" ```rst @@ -11426,7 +11426,7 @@ popdisplay(d::Display) Return a tuple (fpart,ipart) of the fractional and integral parts of a number. Both parts have the same sign as the argument. ``` - """ Base.modf + """ modf @doc doc""" ```rst @@ -11434,7 +11434,7 @@ popdisplay(d::Display) Accurately compute e^x-1 ``` - """ Base.expm1 + """ expm1 @doc doc""" ```rst @@ -11489,7 +11489,7 @@ popdisplay(d::Display) julia> round(x, 1) 1.2 ``` - """ Base.round + """ round @doc doc""" ```rst @@ -11510,7 +11510,7 @@ popdisplay(d::Display) * "RoundDown" ``` - """ Base.RoundingMode + """ RoundingMode @doc doc""" ```rst @@ -11520,7 +11520,7 @@ popdisplay(d::Display) (fractional values of 0.5) being rounded to the nearest even integer. ``` - """ Base.RoundNearest + """ RoundNearest @doc doc""" ```rst @@ -11529,7 +11529,7 @@ popdisplay(d::Display) Rounds to nearest integer, with ties rounded away from zero (C/C++ "round()" behaviour). ``` - """ Base.RoundNearestTiesAway + """ RoundNearestTiesAway @doc doc""" ```rst @@ -11538,7 +11538,7 @@ popdisplay(d::Display) Rounds to nearest integer, with ties rounded toward positive infinity (Java/JavaScript "round()" behaviour). ``` - """ Base.RoundNearestTiesUp + """ RoundNearestTiesUp @doc doc""" ```rst @@ -11546,7 +11546,7 @@ popdisplay(d::Display) "round()" using this rounding mode is an alias for "trunc()". ``` - """ Base.RoundToZero + """ RoundToZero @doc doc""" ```rst @@ -11554,7 +11554,7 @@ popdisplay(d::Display) "round()" using this rounding mode is an alias for "ceil()". ``` - """ Base.RoundUp + """ RoundUp @doc doc""" ```rst @@ -11562,7 +11562,7 @@ popdisplay(d::Display) "round()" using this rounding mode is an alias for "floor()". ``` - """ Base.RoundDown + """ RoundDown @doc doc""" ```rst @@ -11574,7 +11574,7 @@ popdisplay(d::Display) the real components while the second is used for rounding the imaginary components. ``` - """ Base.round + """ round @doc doc""" ```rst @@ -11588,7 +11588,7 @@ popdisplay(d::Display) "digits" and "base" work as for "round()". ``` - """ Base.ceil + """ ceil @doc doc""" ```rst @@ -11602,7 +11602,7 @@ popdisplay(d::Display) "digits" and "base" work as for "round()". ``` - """ Base.floor + """ floor @doc doc""" ```rst @@ -11616,7 +11616,7 @@ popdisplay(d::Display) "digits" and "base" work as for "round()". ``` - """ Base.trunc + """ trunc @doc doc""" ```rst @@ -11627,7 +11627,7 @@ popdisplay(d::Display) value is not representable by "T", an arbitrary value will be returned. ``` - """ Base.unsafe_trunc + """ unsafe_trunc @doc doc""" ```rst @@ -11638,7 +11638,7 @@ popdisplay(d::Display) representation, default 10. E.g., "signif(123.456, 2)" is "120.0", and "signif(357.913, 4, 2)" is "352.0". ``` - """ Base.signif + """ signif @doc doc""" ```rst @@ -11647,7 +11647,7 @@ popdisplay(d::Display) Return the minimum of the arguments. Operates elementwise over arrays. ``` - """ Base.min + """ min @doc doc""" ```rst @@ -11656,7 +11656,7 @@ popdisplay(d::Display) Return the maximum of the arguments. Operates elementwise over arrays. ``` - """ Base.max + """ max @doc doc""" ```rst @@ -11665,7 +11665,7 @@ popdisplay(d::Display) Return "(min(x,y), max(x,y))". See also: "extrema()" that returns "(minimum(x), maximum(x))" ``` - """ Base.minmax + """ minmax @doc doc""" ```rst @@ -11675,7 +11675,7 @@ popdisplay(d::Display) > hi", return "hi". Arguments are promoted to a common type. Operates elementwise over "x" if it is an array. ``` - """ Base.clamp + """ clamp @doc doc""" ```rst @@ -11683,7 +11683,7 @@ popdisplay(d::Display) Absolute value of "x" ``` - """ Base.abs + """ abs @doc doc""" ```rst @@ -11691,7 +11691,7 @@ popdisplay(d::Display) Squared absolute value of "x" ``` - """ Base.abs2 + """ abs2 @doc doc""" ```rst @@ -11699,7 +11699,7 @@ popdisplay(d::Display) Return "x" such that it has the same sign as "y" ``` - """ Base.copysign + """ copysign @doc doc""" ```rst @@ -11708,7 +11708,7 @@ popdisplay(d::Display) Return "+1" if "x" is positive, "0" if "x == 0", and "-1" if "x" is negative. ``` - """ Base.sign + """ sign @doc doc""" ```rst @@ -11717,7 +11717,7 @@ popdisplay(d::Display) Returns "true" if the value of the sign of "x" is negative, otherwise "false". ``` - """ Base.signbit + """ signbit @doc doc""" ```rst @@ -11726,7 +11726,7 @@ popdisplay(d::Display) Return "x" with its sign flipped if "y" is negative. For example "abs(x) = flipsign(x,x)". ``` - """ Base.flipsign + """ flipsign @doc doc""" ```rst @@ -11736,7 +11736,7 @@ popdisplay(d::Display) arguments. Use complex negative arguments instead. The prefix operator "√" is equivalent to "sqrt". ``` - """ Base.sqrt + """ sqrt @doc doc""" ```rst @@ -11745,7 +11745,7 @@ popdisplay(d::Display) Integer square root: the largest integer "m" such that "m*m <= n". ``` - """ Base.isqrt + """ isqrt @doc doc""" ```rst @@ -11754,7 +11754,7 @@ popdisplay(d::Display) Return x^{1/3}. The prefix operator "∛" is equivalent to "cbrt". ``` - """ Base.cbrt + """ cbrt @doc doc""" ```rst @@ -11764,7 +11764,7 @@ popdisplay(d::Display) \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex "x". ``` - """ Base.erf + """ erf @doc doc""" ```rst @@ -11773,7 +11773,7 @@ popdisplay(d::Display) Compute the complementary error function of "x", defined by 1 - \operatorname{erf}(x). ``` - """ Base.erfc + """ erfc @doc doc""" ```rst @@ -11783,7 +11783,7 @@ popdisplay(d::Display) by e^{x^2} \operatorname{erfc}(x). Note also that \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). ``` - """ Base.erfcx + """ erfcx @doc doc""" ```rst @@ -11792,7 +11792,7 @@ popdisplay(d::Display) Compute the imaginary error function of "x", defined by -i \operatorname{erf}(ix). ``` - """ Base.erfi + """ erfi @doc doc""" ```rst @@ -11802,7 +11802,7 @@ popdisplay(d::Display) "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} \operatorname{erfi}(x). ``` - """ Base.dawson + """ dawson @doc doc""" ```rst @@ -11811,7 +11811,7 @@ popdisplay(d::Display) Compute the inverse error function of a real "x", defined by \operatorname{erf}(\operatorname{erfinv}(x)) = x. ``` - """ Base.erfinv + """ erfinv @doc doc""" ```rst @@ -11820,7 +11820,7 @@ popdisplay(d::Display) Compute the inverse error complementary function of a real "x", defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. ``` - """ Base.erfcinv + """ erfcinv @doc doc""" ```rst @@ -11828,7 +11828,7 @@ popdisplay(d::Display) Return the real part of the complex number "z" ``` - """ Base.real + """ real @doc doc""" ```rst @@ -11836,7 +11836,7 @@ popdisplay(d::Display) Return the imaginary part of the complex number "z" ``` - """ Base.imag + """ imag @doc doc""" ```rst @@ -11845,7 +11845,7 @@ popdisplay(d::Display) Return both the real and imaginary parts of the complex number "z" ``` - """ Base.reim + """ reim @doc doc""" ```rst @@ -11853,7 +11853,7 @@ popdisplay(d::Display) Compute the complex conjugate of a complex number "z" ``` - """ Base.conj + """ conj @doc doc""" ```rst @@ -11861,7 +11861,7 @@ popdisplay(d::Display) Compute the phase angle in radians of a complex number "z" ``` - """ Base.angle + """ angle @doc doc""" ```rst @@ -11869,7 +11869,7 @@ popdisplay(d::Display) Return \exp(iz). ``` - """ Base.cis + """ cis @doc doc""" ```rst @@ -11877,7 +11877,7 @@ popdisplay(d::Display) Number of ways to choose "k" out of "n" items ``` - """ Base.binomial + """ binomial @doc doc""" ```rst @@ -11890,7 +11890,7 @@ popdisplay(d::Display) precision. If "n" is not an "Integer", "factorial(n)" is equivalent to "gamma(n+1)". ``` - """ Base.factorial + """ factorial @doc doc""" ```rst @@ -11898,7 +11898,7 @@ popdisplay(d::Display) Compute "factorial(n)/factorial(k)" ``` - """ Base.factorial + """ factorial @doc doc""" ```rst @@ -11915,7 +11915,7 @@ popdisplay(d::Display) 2 => 2 5 => 2 ``` - """ Base.factor + """ factor @doc doc""" ```rst @@ -11924,7 +11924,7 @@ popdisplay(d::Display) Greatest common (positive) divisor (or zero if x and y are both zero). ``` - """ Base.gcd + """ gcd @doc doc""" ```rst @@ -11932,7 +11932,7 @@ popdisplay(d::Display) Least common (non-negative) multiple. ``` - """ Base.lcm + """ lcm @doc doc""" ```rst @@ -11956,7 +11956,7 @@ popdisplay(d::Display) Furthermore, the signs of "u" and "v" are chosen so that "d" is positive. ``` - """ Base.gcdx + """ gcdx @doc doc""" ```rst @@ -11964,7 +11964,7 @@ popdisplay(d::Display) Test whether "n" is a power of two ``` - """ Base.ispow2 + """ ispow2 @doc doc""" ```rst @@ -11973,7 +11973,7 @@ popdisplay(d::Display) The smallest power of two not less than "n". Returns 0 for "n==0", and returns "-nextpow2(-n)" for negative arguments. ``` - """ Base.nextpow2 + """ nextpow2 @doc doc""" ```rst @@ -11982,7 +11982,7 @@ popdisplay(d::Display) The largest power of two not greater than "n". Returns 0 for "n==0", and returns "-prevpow2(-n)" for negative arguments. ``` - """ Base.prevpow2 + """ prevpow2 @doc doc""" ```rst @@ -11992,7 +11992,7 @@ popdisplay(d::Display) negative integer. "a" must be greater than 1, and "x" must be greater than 0. ``` - """ Base.nextpow + """ nextpow @doc doc""" ```rst @@ -12002,7 +12002,7 @@ popdisplay(d::Display) negative integer. "a" must be greater than 1, and "x" must not be less than 1. ``` - """ Base.prevpow + """ prevpow @doc doc""" ```rst @@ -12011,7 +12011,7 @@ popdisplay(d::Display) Next integer not less than "n" that can be written as \prod k_i^{p_i} for integers p_1, p_2, etc. ``` - """ Base.nextprod + """ nextprod @doc doc""" ```rst @@ -12020,7 +12020,7 @@ popdisplay(d::Display) Previous integer not greater than "n" that can be written as \prod k_i^{p_i} for integers p_1, p_2, etc. ``` - """ Base.prevprod + """ prevprod @doc doc""" ```rst @@ -12029,7 +12029,7 @@ popdisplay(d::Display) Take the inverse of "x" modulo "m": "y" such that xy = 1 \pmod m ``` - """ Base.invmod + """ invmod @doc doc""" ```rst @@ -12037,7 +12037,7 @@ popdisplay(d::Display) Compute x^p \pmod m ``` - """ Base.powermod + """ powermod @doc doc""" ```rst @@ -12045,7 +12045,7 @@ popdisplay(d::Display) Compute the gamma function of "x" ``` - """ Base.gamma + """ gamma @doc doc""" ```rst @@ -12055,7 +12055,7 @@ popdisplay(d::Display) "Real" "x", while for "Complex" "x" it computes the logarithm of "gamma(x)". ``` - """ Base.lgamma + """ lgamma @doc doc""" ```rst @@ -12063,7 +12063,7 @@ popdisplay(d::Display) Compute the logarithmic factorial of "x" ``` - """ Base.lfact + """ lfact @doc doc""" ```rst @@ -12072,7 +12072,7 @@ popdisplay(d::Display) Compute the digamma function of "x" (the logarithmic derivative of "gamma(x)") ``` - """ Base.digamma + """ digamma @doc doc""" ```rst @@ -12080,7 +12080,7 @@ popdisplay(d::Display) Compute the inverse digamma function of "x". ``` - """ Base.invdigamma + """ invdigamma @doc doc""" ```rst @@ -12089,7 +12089,7 @@ popdisplay(d::Display) Compute the trigamma function of "x" (the logarithmic second derivative of "gamma(x)") ``` - """ Base.trigamma + """ trigamma @doc doc""" ```rst @@ -12098,7 +12098,7 @@ popdisplay(d::Display) Compute the polygamma function of order "m" of argument "x" (the "(m+1)th" derivative of the logarithm of "gamma(x)") ``` - """ Base.polygamma + """ polygamma @doc doc""" ```rst @@ -12106,7 +12106,7 @@ popdisplay(d::Display) kth derivative of the Airy function \operatorname{Ai}(x). ``` - """ Base.airy + """ airy @doc doc""" ```rst @@ -12114,7 +12114,7 @@ popdisplay(d::Display) Airy function \operatorname{Ai}(x). ``` - """ Base.airyai + """ airyai @doc doc""" ```rst @@ -12122,7 +12122,7 @@ popdisplay(d::Display) Airy function derivative \operatorname{Ai}'(x). ``` - """ Base.airyprime + """ airyprime @doc doc""" ```rst @@ -12130,7 +12130,7 @@ popdisplay(d::Display) Airy function derivative \operatorname{Ai}'(x). ``` - """ Base.airyaiprime + """ airyaiprime @doc doc""" ```rst @@ -12138,7 +12138,7 @@ popdisplay(d::Display) Airy function \operatorname{Bi}(x). ``` - """ Base.airybi + """ airybi @doc doc""" ```rst @@ -12146,7 +12146,7 @@ popdisplay(d::Display) Airy function derivative \operatorname{Bi}'(x). ``` - """ Base.airybiprime + """ airybiprime @doc doc""" ```rst @@ -12158,7 +12158,7 @@ popdisplay(d::Display) \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || k == 3". ``` - """ Base.airyx + """ airyx @doc doc""" ```rst @@ -12166,7 +12166,7 @@ popdisplay(d::Display) Bessel function of the first kind of order 0, J_0(x). ``` - """ Base.besselj0 + """ besselj0 @doc doc""" ```rst @@ -12174,7 +12174,7 @@ popdisplay(d::Display) Bessel function of the first kind of order 1, J_1(x). ``` - """ Base.besselj1 + """ besselj1 @doc doc""" ```rst @@ -12182,7 +12182,7 @@ popdisplay(d::Display) Bessel function of the first kind of order "nu", J_\nu(x). ``` - """ Base.besselj + """ besselj @doc doc""" ```rst @@ -12191,7 +12191,7 @@ popdisplay(d::Display) Scaled Bessel function of the first kind of order "nu", J_\nu(x) e^{- | \operatorname{Im}(x) |}. ``` - """ Base.besseljx + """ besseljx @doc doc""" ```rst @@ -12199,7 +12199,7 @@ popdisplay(d::Display) Bessel function of the second kind of order 0, Y_0(x). ``` - """ Base.bessely0 + """ bessely0 @doc doc""" ```rst @@ -12207,7 +12207,7 @@ popdisplay(d::Display) Bessel function of the second kind of order 1, Y_1(x). ``` - """ Base.bessely1 + """ bessely1 @doc doc""" ```rst @@ -12215,7 +12215,7 @@ popdisplay(d::Display) Bessel function of the second kind of order "nu", Y_\nu(x). ``` - """ Base.bessely + """ bessely @doc doc""" ```rst @@ -12224,7 +12224,7 @@ popdisplay(d::Display) Scaled Bessel function of the second kind of order "nu", Y_\nu(x) e^{- | \operatorname{Im}(x) |}. ``` - """ Base.besselyx + """ besselyx @doc doc""" ```rst @@ -12232,7 +12232,7 @@ popdisplay(d::Display) Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). ``` - """ Base.hankelh1 + """ hankelh1 @doc doc""" ```rst @@ -12241,7 +12241,7 @@ popdisplay(d::Display) Scaled Bessel function of the third kind of order "nu", H^{(1)}_\nu(x) e^{-x i}. ``` - """ Base.hankelh1x + """ hankelh1x @doc doc""" ```rst @@ -12249,7 +12249,7 @@ popdisplay(d::Display) Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). ``` - """ Base.hankelh2 + """ hankelh2 @doc doc""" ```rst @@ -12258,7 +12258,7 @@ popdisplay(d::Display) Scaled Bessel function of the third kind of order "nu", H^{(2)}_\nu(x) e^{x i}. ``` - """ Base.hankelh2x + """ hankelh2x @doc doc""" ```rst @@ -12268,7 +12268,7 @@ popdisplay(d::Display) function). "k" is either 1 or 2, selecting "hankelh1" or "hankelh2", respectively. ``` - """ Base.besselh + """ besselh @doc doc""" ```rst @@ -12277,7 +12277,7 @@ popdisplay(d::Display) Modified Bessel function of the first kind of order "nu", I_\nu(x). ``` - """ Base.besseli + """ besseli @doc doc""" ```rst @@ -12286,7 +12286,7 @@ popdisplay(d::Display) Scaled modified Bessel function of the first kind of order "nu", I_\nu(x) e^{- | \operatorname{Re}(x) |}. ``` - """ Base.besselix + """ besselix @doc doc""" ```rst @@ -12295,7 +12295,7 @@ popdisplay(d::Display) Modified Bessel function of the second kind of order "nu", K_\nu(x). ``` - """ Base.besselk + """ besselk @doc doc""" ```rst @@ -12304,7 +12304,7 @@ popdisplay(d::Display) Scaled modified Bessel function of the second kind of order "nu", K_\nu(x) e^x. ``` - """ Base.besselkx + """ besselkx @doc doc""" ```rst @@ -12313,7 +12313,7 @@ popdisplay(d::Display) Euler integral of the first kind \operatorname{B}(x,y) = \Gamma(x)\Gamma(y)/\Gamma(x+y). ``` - """ Base.beta + """ beta @doc doc""" ```rst @@ -12322,7 +12322,7 @@ popdisplay(d::Display) Natural logarithm of the absolute value of the beta function \log(|\operatorname{B}(x,y)|). ``` - """ Base.lbeta + """ lbeta @doc doc""" ```rst @@ -12331,7 +12331,7 @@ popdisplay(d::Display) Dirichlet eta function \eta(s) = \sum^\infty_{n=1}(-)^{n-1}/n^{s}. ``` - """ Base.eta + """ eta @doc doc""" ```rst @@ -12339,7 +12339,7 @@ popdisplay(d::Display) Riemann zeta function \zeta(s). ``` - """ Base.zeta + """ zeta @doc doc""" ```rst @@ -12348,7 +12348,7 @@ popdisplay(d::Display) Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of "z=1".) ``` - """ Base.zeta + """ zeta @doc doc""" ```rst @@ -12356,7 +12356,7 @@ popdisplay(d::Display) Compute the number of digits in number "n" written in base "b". ``` - """ Base.ndigits + """ ndigits @doc doc""" ```rst @@ -12364,7 +12364,7 @@ popdisplay(d::Display) Multiply "x" and "y", giving the result as a larger type. ``` - """ Base.widemul + """ widemul @doc doc""" ```rst @@ -12376,7 +12376,7 @@ popdisplay(d::Display) inline code that uses either Horner's method or, for complex "z", a more efficient Goertzel-like algorithm. ``` - """ Base.@evalpoly + """ @evalpoly @doc doc""" ```rst @@ -12387,7 +12387,7 @@ popdisplay(d::Display) values in the computation. For applications requiring the handling of missing data, the "DataArray" package is recommended. ``` - """ Base.mean + """ mean @doc doc""" ```rst @@ -12396,7 +12396,7 @@ popdisplay(d::Display) Compute the mean of "v" over the singleton dimensions of "r", and write results to "r". ``` - """ Base.mean! + """ mean! @doc doc""" ```rst @@ -12412,7 +12412,7 @@ popdisplay(d::Display) applications requiring the handling of missing data, the "DataArray" package is recommended. ``` - """ Base.std + """ std @doc doc""" ```rst @@ -12422,7 +12422,7 @@ popdisplay(d::Display) mean "m". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.stdm + """ stdm @doc doc""" ```rst @@ -12438,7 +12438,7 @@ popdisplay(d::Display) applications requiring the handling of missing data, the "DataArray" package is recommended. ``` - """ Base.var + """ var @doc doc""" ```rst @@ -12448,7 +12448,7 @@ popdisplay(d::Display) "m". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.varm + """ varm @doc doc""" ```rst @@ -12457,7 +12457,7 @@ popdisplay(d::Display) Compute the middle of a scalar value, which is equivalent to "x" itself, but of the type of "middle(x, x)" for consistency. ``` - """ Base.middle + """ middle @doc doc""" ```rst @@ -12467,7 +12467,7 @@ popdisplay(d::Display) equivalent in both value and type to computing their mean ("(x + y) / 2"). ``` - """ Base.middle + """ middle @doc doc""" ```rst @@ -12477,7 +12477,7 @@ popdisplay(d::Display) of its extrema. Since a range is sorted, the mean is performed with the first and last element. ``` - """ Base.middle + """ middle @doc doc""" ```rst @@ -12486,7 +12486,7 @@ popdisplay(d::Display) Compute the middle of an array, which consists in finding its extrema and then computing their mean. ``` - """ Base.middle + """ middle @doc doc""" ```rst @@ -12497,7 +12497,7 @@ popdisplay(d::Display) handling of missing data, the "DataArrays" package is recommended. ``` - """ Base.median + """ median @doc doc""" ```rst @@ -12505,7 +12505,7 @@ popdisplay(d::Display) Like "median", but may overwrite the input vector. ``` - """ Base.median! + """ median! @doc doc""" ```rst @@ -12517,7 +12517,7 @@ popdisplay(d::Display) elements of "v" in each bin. Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.hist + """ hist @doc doc""" ```rst @@ -12529,7 +12529,7 @@ popdisplay(d::Display) satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.hist + """ hist @doc doc""" ```rst @@ -12539,7 +12539,7 @@ popdisplay(d::Display) edges for the bins. This function writes the resultant counts to a pre-allocated array "counts". ``` - """ Base.hist! + """ hist! @doc doc""" ```rst @@ -12554,7 +12554,7 @@ popdisplay(d::Display) "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.hist2d + """ hist2d @doc doc""" ```rst @@ -12564,7 +12564,7 @@ popdisplay(d::Display) the edges given in "e1" and "e2". This function writes the results to a pre-allocated array "counts". ``` - """ Base.hist2d! + """ hist2d! @doc doc""" ```rst @@ -12575,7 +12575,7 @@ popdisplay(d::Display) 2 or 5 multiplied by a power of 10. Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.histrange + """ histrange @doc doc""" ```rst @@ -12585,7 +12585,7 @@ popdisplay(d::Display) vector/range of length "length(e) - 1". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.midpoints + """ midpoints @doc doc""" ```rst @@ -12595,7 +12595,7 @@ popdisplay(d::Display) probability values "p". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.quantile + """ quantile @doc doc""" ```rst @@ -12604,7 +12604,7 @@ popdisplay(d::Display) Compute the quantile of a vector "v" at the probability "p". Note: Julia does not ignore "NaN" values in the computation. ``` - """ Base.quantile + """ quantile @doc doc""" ```rst @@ -12612,7 +12612,7 @@ popdisplay(d::Display) Like "quantile", but overwrites the input vector. ``` - """ Base.quantile! + """ quantile! @doc doc""" ```rst @@ -12646,7 +12646,7 @@ popdisplay(d::Display) Note: "v2" can be omitted, which indicates "v2 = v1". ``` - """ Base.cov + """ cov @doc doc""" ```rst @@ -12659,7 +12659,7 @@ popdisplay(d::Display) variable dimension, and "mean" to supply pre-computed mean values. ``` - """ Base.cor + """ cor @doc doc""" ```rst @@ -12687,7 +12687,7 @@ popdisplay(d::Display) *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* processors. ``` - """ Base.fft + """ fft @doc doc""" ```rst @@ -12696,7 +12696,7 @@ popdisplay(d::Display) Same as "fft()", but operates in-place on "A", which must be an array of complex floating-point numbers. ``` - """ Base.fft! + """ fft! @doc doc""" ```rst @@ -12715,7 +12715,7 @@ popdisplay(d::Display) A multidimensional inverse FFT simply performs this operation along each transformed dimension of "A". ``` - """ Base.ifft + """ ifft @doc doc""" ```rst @@ -12723,7 +12723,7 @@ popdisplay(d::Display) Same as "ifft()", but operates in-place on "A". ``` - """ Base.ifft! + """ ifft! @doc doc""" ```rst @@ -12739,7 +12739,7 @@ popdisplay(d::Display) \operatorname{BDFT}(A)[k] = \operatorname{length}(A) \operatorname{IDFT}(A)[k] ``` - """ Base.bfft + """ bfft @doc doc""" ```rst @@ -12747,7 +12747,7 @@ popdisplay(d::Display) Same as "bfft()", but operates in-place on "A". ``` - """ Base.bfft! + """ bfft! @doc doc""" ```rst @@ -12774,7 +12774,7 @@ popdisplay(d::Display) similar but produce plans that perform the equivalent of the inverse transforms "ifft()" and so on. ``` - """ Base.plan_fft + """ plan_fft @doc doc""" ```rst @@ -12783,7 +12783,7 @@ popdisplay(d::Display) Same as "plan_fft()", but produces a plan that performs inverse transforms "ifft()". ``` - """ Base.plan_ifft + """ plan_ifft @doc doc""" ```rst @@ -12792,7 +12792,7 @@ popdisplay(d::Display) Same as "plan_fft()", but produces a plan that performs an unnormalized backwards transform "bfft()". ``` - """ Base.plan_bfft + """ plan_bfft @doc doc""" ```rst @@ -12800,7 +12800,7 @@ popdisplay(d::Display) Same as "plan_fft()", but operates in-place on "A". ``` - """ Base.plan_fft! + """ plan_fft! @doc doc""" ```rst @@ -12808,7 +12808,7 @@ popdisplay(d::Display) Same as "plan_ifft()", but operates in-place on "A". ``` - """ Base.plan_ifft! + """ plan_ifft! @doc doc""" ```rst @@ -12816,7 +12816,7 @@ popdisplay(d::Display) Same as "plan_bfft()", but operates in-place on "A". ``` - """ Base.plan_bfft! + """ plan_bfft! @doc doc""" ```rst @@ -12834,7 +12834,7 @@ popdisplay(d::Display) result, the "dims[1]" dimension is (roughly) halved in the same way. ``` - """ Base.rfft + """ rfft @doc doc""" ```rst @@ -12851,7 +12851,7 @@ popdisplay(d::Display) from "size(A)" due to the possibility of rounding by the "floor" function here.) ``` - """ Base.irfft + """ irfft @doc doc""" ```rst @@ -12862,7 +12862,7 @@ popdisplay(d::Display) product of the sizes of the transformed dimensions (of the real output array) in order to obtain the inverse transform. ``` - """ Base.brfft + """ brfft @doc doc""" ```rst @@ -12873,7 +12873,7 @@ popdisplay(d::Display) arguments, and the size of the transformed result, are the same as for "rfft()". ``` - """ Base.plan_rfft + """ plan_rfft @doc doc""" ```rst @@ -12884,7 +12884,7 @@ popdisplay(d::Display) first two arguments and the size of the transformed result, are the same as for "brfft()". ``` - """ Base.plan_brfft + """ plan_brfft @doc doc""" ```rst @@ -12895,7 +12895,7 @@ popdisplay(d::Display) respectively. The first three arguments have the same meaning as for "irfft()". ``` - """ Base.plan_irfft + """ plan_irfft @doc doc""" ```rst @@ -12909,7 +12909,7 @@ popdisplay(d::Display) dimensions is a product of small primes; see "nextprod()". See also "plan_dct()" for even greater efficiency. ``` - """ Base.dct + """ dct @doc doc""" ```rst @@ -12918,7 +12918,7 @@ popdisplay(d::Display) Same as "dct!()", except that it operates in-place on "A", which must be an array of real or complex floating-point values. ``` - """ Base.dct! + """ dct! @doc doc""" ```rst @@ -12933,7 +12933,7 @@ popdisplay(d::Display) "nextprod()". See also "plan_idct()" for even greater efficiency. ``` - """ Base.idct + """ idct @doc doc""" ```rst @@ -12941,7 +12941,7 @@ popdisplay(d::Display) Same as "idct!()", but operates in-place on "A". ``` - """ Base.idct! + """ idct! @doc doc""" ```rst @@ -12951,7 +12951,7 @@ popdisplay(d::Display) "plan_fft()" except producing a function that computes "dct()". The first two arguments have the same meaning as for "dct()". ``` - """ Base.plan_dct + """ plan_dct @doc doc""" ```rst @@ -12959,7 +12959,7 @@ popdisplay(d::Display) Same as "plan_dct()", but operates in-place on "A". ``` - """ Base.plan_dct! + """ plan_dct! @doc doc""" ```rst @@ -12970,7 +12970,7 @@ popdisplay(d::Display) "idct()". The first two arguments have the same meaning as for "idct()". ``` - """ Base.plan_idct + """ plan_idct @doc doc""" ```rst @@ -12978,7 +12978,7 @@ popdisplay(d::Display) Same as "plan_idct()", but operates in-place on "A". ``` - """ Base.plan_idct! + """ plan_idct! @doc doc""" ```rst @@ -12986,7 +12986,7 @@ popdisplay(d::Display) Swap the first and second halves of each dimension of "x". ``` - """ Base.fftshift + """ fftshift @doc doc""" ```rst @@ -12995,7 +12995,7 @@ popdisplay(d::Display) Swap the first and second halves of the given dimension of array "x". ``` - """ Base.fftshift + """ fftshift @doc doc""" ```rst @@ -13003,7 +13003,7 @@ popdisplay(d::Display) Undoes the effect of "fftshift". ``` - """ Base.ifftshift + """ ifftshift @doc doc""" ```rst @@ -13013,7 +13013,7 @@ popdisplay(d::Display) with an optional initial filter state vector "si" (defaults to zeros). ``` - """ Base.filt + """ filt @doc doc""" ```rst @@ -13022,7 +13022,7 @@ popdisplay(d::Display) Same as "filt()" but writes the result into the "out" argument, which may alias the input "x" to modify it in-place. ``` - """ Base.filt! + """ filt! @doc doc""" ```rst @@ -13031,7 +13031,7 @@ popdisplay(d::Display) Construct vector "c" such that "b = conv(a,c) + r". Equivalent to polynomial division. ``` - """ Base.deconv + """ deconv @doc doc""" ```rst @@ -13039,7 +13039,7 @@ popdisplay(d::Display) Convolution of two vectors. Uses FFT algorithm. ``` - """ Base.conv + """ conv @doc doc""" ```rst @@ -13048,7 +13048,7 @@ popdisplay(d::Display) 2-D convolution of the matrix "A" with the 2-D separable kernel generated by the vectors "u" and "v". Uses 2-D FFT algorithm ``` - """ Base.conv2 + """ conv2 @doc doc""" ```rst @@ -13057,7 +13057,7 @@ popdisplay(d::Display) 2-D convolution of the matrix "B" with the matrix "A". Uses 2-D FFT algorithm ``` - """ Base.conv2 + """ conv2 @doc doc""" ```rst @@ -13065,7 +13065,7 @@ popdisplay(d::Display) Compute the cross-correlation of two vectors. ``` - """ Base.xcorr + """ xcorr @doc doc""" ```rst @@ -13186,7 +13186,7 @@ popdisplay(d::Display) infinite. (A coordinate transformation is performed internally to map the infinite interval to a finite one.) ``` - """ Base.quadgk + """ quadgk @doc doc""" ```rst @@ -13195,7 +13195,7 @@ popdisplay(d::Display) Convert an integer to a binary string, optionally specifying a number of digits to pad to. ``` - """ Base.bin + """ bin @doc doc""" ```rst @@ -13204,7 +13204,7 @@ popdisplay(d::Display) Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. ``` - """ Base.hex + """ hex @doc doc""" ```rst @@ -13213,7 +13213,7 @@ popdisplay(d::Display) Convert an integer to a decimal string, optionally specifying a number of digits to pad to. ``` - """ Base.dec + """ dec @doc doc""" ```rst @@ -13222,7 +13222,7 @@ popdisplay(d::Display) Convert an integer to an octal string, optionally specifying a number of digits to pad to. ``` - """ Base.oct + """ oct @doc doc""" ```rst @@ -13233,7 +13233,7 @@ popdisplay(d::Display) as either an integer, or as a "UInt8" array of character values to use as digit symbols. ``` - """ Base.base + """ base @doc doc""" ```rst @@ -13244,7 +13244,7 @@ popdisplay(d::Display) digits are at higher indexes, such that "n == sum([digits[k]*base^(k-1) for k=1:length(digits)])". ``` - """ Base.digits + """ digits @doc doc""" ```rst @@ -13256,7 +13256,7 @@ popdisplay(d::Display) array length. If the array length is excessive, the excess portion is filled with zeros. ``` - """ Base.digits! + """ digits! @doc doc""" ```rst @@ -13264,7 +13264,7 @@ popdisplay(d::Display) A string giving the literal bit representation of a number. ``` - """ Base.bits + """ bits @doc doc""" ```rst @@ -13276,7 +13276,7 @@ popdisplay(d::Display) point number. If the string does not contain a valid number, an error is raised. ``` - """ Base.parse + """ parse @doc doc""" ```rst @@ -13286,7 +13286,7 @@ popdisplay(d::Display) The result will be null if the string does not contain a valid number. ``` - """ Base.tryparse + """ tryparse @doc doc""" ```rst @@ -13296,7 +13296,7 @@ popdisplay(d::Display) "BigInt" or "BigFloat"). See "BigFloat" for information about some pitfalls with floating-point numbers. ``` - """ Base.big + """ big @doc doc""" ```rst @@ -13305,7 +13305,7 @@ popdisplay(d::Display) Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. ``` - """ Base.signed + """ signed @doc doc""" ```rst @@ -13315,7 +13315,7 @@ popdisplay(d::Display) it is reinterpreted as unsigned without checking for negative values. ``` - """ Base.unsigned + """ unsigned @doc doc""" ```rst @@ -13325,7 +13325,7 @@ popdisplay(d::Display) type. For numeric data, the smallest suitable "FloatingPoint" type is used. Converts strings to "Float64". ``` - """ Base.float + """ float @doc doc""" ```rst @@ -13342,7 +13342,7 @@ popdisplay(d::Display) julia> significand(15.2)*8 15.2 ``` - """ Base.significand + """ significand @doc doc""" ```rst @@ -13350,7 +13350,7 @@ popdisplay(d::Display) Get the exponent of a normalized floating-point number. ``` - """ Base.exponent + """ exponent @doc doc""" ```rst @@ -13358,7 +13358,7 @@ popdisplay(d::Display) Convert real numbers or arrays to complex. "i" defaults to zero. ``` - """ Base.complex + """ complex @doc doc""" ```rst @@ -13366,7 +13366,7 @@ popdisplay(d::Display) Byte-swap an integer ``` - """ Base.bswap + """ bswap @doc doc""" ```rst @@ -13375,7 +13375,7 @@ popdisplay(d::Display) Get a hexadecimal string of the binary representation of a floating point number ``` - """ Base.num2hex + """ num2hex @doc doc""" ```rst @@ -13384,7 +13384,7 @@ popdisplay(d::Display) Convert a hexadecimal string to the floating point number it represents ``` - """ Base.hex2num + """ hex2num @doc doc""" ```rst @@ -13393,7 +13393,7 @@ popdisplay(d::Display) Convert an arbitrarily long hexadecimal string to its binary representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. ``` - """ Base.hex2bytes + """ hex2bytes @doc doc""" ```rst @@ -13402,7 +13402,7 @@ popdisplay(d::Display) Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. ``` - """ Base.bytes2hex + """ bytes2hex @doc doc""" ```rst @@ -13412,7 +13412,7 @@ popdisplay(d::Display) also specify the type itself). For matrices, returns an identity matrix of the appropriate size and type. ``` - """ Base.one + """ one @doc doc""" ```rst @@ -13421,7 +13421,7 @@ popdisplay(d::Display) Get the additive identity element for the type of x (x can also specify the type itself). ``` - """ Base.zero + """ zero @doc doc""" ```rst @@ -13430,7 +13430,7 @@ popdisplay(d::Display) The constant pi ``` - """ Base.pi + """ pi @doc doc""" ```rst @@ -13438,7 +13438,7 @@ popdisplay(d::Display) The imaginary unit ``` - """ Base.im + """ im @doc doc""" ```rst @@ -13447,7 +13447,7 @@ eu The constant e ``` - """ Base.e + """ e @doc doc""" ```rst @@ -13455,7 +13455,7 @@ eu Catalan's constant ``` - """ Base.catalan + """ catalan @doc doc""" ```rst @@ -13464,7 +13464,7 @@ eulergamma Euler's constant ``` - """ Base.(:(γ)) + """ γ @doc doc""" ```rst @@ -13473,7 +13473,7 @@ golden The golden ratio ``` - """ Base.(:(φ)) + """ φ @doc doc""" ```rst @@ -13481,7 +13481,7 @@ golden Positive infinity of type Float64 ``` - """ Base.Inf + """ Inf @doc doc""" ```rst @@ -13489,7 +13489,7 @@ golden Positive infinity of type Float32 ``` - """ Base.Inf32 + """ Inf32 @doc doc""" ```rst @@ -13497,7 +13497,7 @@ golden Positive infinity of type Float16 ``` - """ Base.Inf16 + """ Inf16 @doc doc""" ```rst @@ -13505,7 +13505,7 @@ golden A not-a-number value of type Float64 ``` - """ Base.NaN + """ NaN @doc doc""" ```rst @@ -13513,7 +13513,7 @@ golden A not-a-number value of type Float32 ``` - """ Base.NaN32 + """ NaN32 @doc doc""" ```rst @@ -13521,7 +13521,7 @@ golden A not-a-number value of type Float16 ``` - """ Base.NaN16 + """ NaN16 @doc doc""" ```rst @@ -13529,7 +13529,7 @@ golden Test whether a floating point number is subnormal ``` - """ Base.issubnormal + """ issubnormal @doc doc""" ```rst @@ -13537,7 +13537,7 @@ golden Test whether a number is finite ``` - """ Base.isfinite + """ isfinite @doc doc""" ```rst @@ -13545,7 +13545,7 @@ golden Test whether a number is infinite ``` - """ Base.isinf + """ isinf @doc doc""" ```rst @@ -13553,7 +13553,7 @@ golden Test whether a floating point number is not a number (NaN) ``` - """ Base.isnan + """ isnan @doc doc""" ```rst @@ -13562,7 +13562,7 @@ golden Returns positive infinity of the floating point type "f" or of the same floating point type as "f" ``` - """ Base.inf + """ inf @doc doc""" ```rst @@ -13571,7 +13571,7 @@ golden Returns NaN (not-a-number) of the floating point type "f" or of the same floating point type as "f" ``` - """ Base.nan + """ nan @doc doc""" ```rst @@ -13579,7 +13579,7 @@ golden Get the next floating point number in lexicographic order ``` - """ Base.nextfloat + """ nextfloat @doc doc""" ```rst @@ -13587,7 +13587,7 @@ golden Get the previous floating point number in lexicographic order ``` - """ Base.prevfloat + """ prevfloat @doc doc""" ```rst @@ -13596,7 +13596,7 @@ golden Test whether "x" or all its elements are numerically equal to some integer ``` - """ Base.isinteger + """ isinteger @doc doc""" ```rst @@ -13605,7 +13605,7 @@ golden Test whether "x" or all its elements are numerically equal to some real number ``` - """ Base.isreal + """ isreal @doc doc""" ```rst @@ -13622,7 +13622,7 @@ golden See "get_rounding" for available rounding modes. ``` - """ Base.Float32 + """ Float32 @doc doc""" ```rst @@ -13639,7 +13639,7 @@ golden See "get_rounding" for available rounding modes. ``` - """ Base.Float64 + """ Float64 @doc doc""" ```rst @@ -13653,7 +13653,7 @@ golden Instances can be constructed from strings via "parse()", or using the "big" string literal. ``` - """ Base.BigInt + """ BigInt @doc doc""" ```rst @@ -13672,7 +13672,7 @@ golden julia> big"2.1" 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision ``` - """ Base.BigFloat + """ BigFloat @doc doc""" ```rst @@ -13685,7 +13685,7 @@ golden Valid modes are "RoundNearest", "RoundToZero", "RoundUp", "RoundDown", and "RoundFromZero" ("BigFloat" only). ``` - """ Base.get_rounding + """ get_rounding @doc doc""" ```rst @@ -13699,7 +13699,7 @@ golden rounding mode of "Float64" will change the rounding mode of "Float32". See "get_rounding" for available modes ``` - """ Base.set_rounding + """ set_rounding @doc doc""" ```rst @@ -13715,7 +13715,7 @@ golden See "get_rounding" for available rounding modes. ``` - """ Base.with_rounding + """ with_rounding @doc doc""" ```rst @@ -13726,7 +13726,7 @@ golden julia> count_ones(7) 3 ``` - """ Base.count_ones + """ count_ones @doc doc""" ```rst @@ -13737,7 +13737,7 @@ golden julia> count_zeros(Int32(2 ^ 16 - 1)) 16 ``` - """ Base.count_zeros + """ count_zeros @doc doc""" ```rst @@ -13748,7 +13748,7 @@ golden julia> leading_zeros(Int32(1)) 31 ``` - """ Base.leading_zeros + """ leading_zeros @doc doc""" ```rst @@ -13759,7 +13759,7 @@ golden julia> leading_ones(UInt32(2 ^ 32 - 2)) 31 ``` - """ Base.leading_ones + """ leading_ones @doc doc""" ```rst @@ -13770,7 +13770,7 @@ golden julia> trailing_zeros(2) 1 ``` - """ Base.trailing_zeros + """ trailing_zeros @doc doc""" ```rst @@ -13781,7 +13781,7 @@ golden julia> trailing_ones(3) 2 ``` - """ Base.trailing_ones + """ trailing_ones @doc doc""" ```rst @@ -13792,7 +13792,7 @@ golden julia> isprime(3) true ``` - """ Base.isprime + """ isprime @doc doc""" ```rst @@ -13807,7 +13807,7 @@ golden julia> isprime(big(3)) true ``` - """ Base.isprime + """ isprime @doc doc""" ```rst @@ -13815,7 +13815,7 @@ golden Returns a collection of the prime numbers <= "n". ``` - """ Base.primes + """ primes @doc doc""" ```rst @@ -13830,7 +13830,7 @@ golden julia> isodd(10) false ``` - """ Base.isodd + """ isodd @doc doc""" ```rst @@ -13845,7 +13845,7 @@ golden julia> iseven(10) true ``` - """ Base.iseven + """ iseven @doc doc""" ```rst @@ -13854,7 +13854,7 @@ golden Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. ``` - """ Base.precision + """ precision @doc doc""" ```rst @@ -13862,7 +13862,7 @@ golden Get the precision (in bits) currently used for BigFloat arithmetic. ``` - """ Base.get_bigfloat_precision + """ get_bigfloat_precision @doc doc""" ```rst @@ -13870,7 +13870,7 @@ golden Set the precision (in bits) to be used to BigFloat arithmetic. ``` - """ Base.set_bigfloat_precision + """ set_bigfloat_precision @doc doc""" ```rst @@ -13884,7 +13884,7 @@ golden f() set_bigfloat_precision(old) ``` - """ Base.with_bigfloat_precision + """ with_bigfloat_precision @doc doc""" ```rst @@ -13897,7 +13897,7 @@ golden integers or a filename, in which case the seed is read from a file. "RandomDevice" does not support seeding. ``` - """ Base.srand + """ srand @doc doc""" ```rst @@ -13907,7 +13907,7 @@ golden have their own seeds, which may be useful for generating different streams of random numbers. ``` - """ Base.MersenneTwister + """ MersenneTwister @doc doc""" ```rst @@ -13916,7 +13916,7 @@ golden Create a "RandomDevice" RNG object. Two such objects will always generate different streams of random numbers. ``` - """ Base.RandomDevice + """ RandomDevice @doc doc""" ```rst @@ -13934,7 +13934,7 @@ golden "S" defaults to "Float64". ``` - """ Base.rand + """ rand @doc doc""" ```rst @@ -13946,7 +13946,7 @@ golden size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but without allocating a new array. ``` - """ Base.rand! + """ rand! @doc doc""" ```rst @@ -13954,7 +13954,7 @@ golden Generate a "BitArray" of random boolean values. ``` - """ Base.bitrand + """ bitrand @doc doc""" ```rst @@ -13964,7 +13964,7 @@ golden standard deviation 1. Optionally generate an array of normally- distributed random numbers. ``` - """ Base.randn + """ randn @doc doc""" ```rst @@ -13973,7 +13973,7 @@ golden Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand function. ``` - """ Base.randn! + """ randn! @doc doc""" ```rst @@ -13982,7 +13982,7 @@ golden Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. ``` - """ Base.randexp + """ randexp @doc doc""" ```rst @@ -13991,7 +13991,7 @@ golden Fill the array A with random numbers following the exponential distribution (with scale 1). ``` - """ Base.randexp! + """ randexp! @doc doc""" ```rst @@ -14001,7 +14001,7 @@ golden function (which must be callable with no arguments). The task exits when this function returns. ``` - """ Base.Task + """ Task @doc doc""" ```rst @@ -14014,7 +14014,7 @@ golden considering states or scheduling in any way. Its use is discouraged. ``` - """ Base.yieldto + """ yieldto @doc doc""" ```rst @@ -14022,7 +14022,7 @@ golden Get the currently running Task. ``` - """ Base.current_task + """ current_task @doc doc""" ```rst @@ -14030,7 +14030,7 @@ golden Tell whether a task has exited. ``` - """ Base.istaskdone + """ istaskdone @doc doc""" ```rst @@ -14038,7 +14038,7 @@ golden Tell whether a task has started executing. ``` - """ Base.istaskstarted + """ istaskstarted @doc doc""" ```rst @@ -14048,7 +14048,7 @@ golden Additional arguments may be passed, to be returned from the last "produce" call in the producer. ``` - """ Base.consume + """ consume @doc doc""" ```rst @@ -14058,7 +14058,7 @@ golden consumer task. If the next "consume" call passes any values, they are returned by "produce". ``` - """ Base.produce + """ produce @doc doc""" ```rst @@ -14068,7 +14068,7 @@ golden task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. ``` - """ Base.yield + """ yield @doc doc""" ```rst @@ -14077,7 +14077,7 @@ golden Look up the value of a symbol in the current task's task-local storage. ``` - """ Base.task_local_storage + """ task_local_storage @doc doc""" ```rst @@ -14086,7 +14086,7 @@ golden Assign a value to a symbol in the current task's task-local storage. ``` - """ Base.task_local_storage + """ task_local_storage @doc doc""" ```rst @@ -14097,7 +14097,7 @@ golden "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. ``` - """ Base.task_local_storage + """ task_local_storage @doc doc""" ```rst @@ -14112,7 +14112,7 @@ golden notification has happened. The "RemoteRef" type does this, and so can be used for level-triggered events. ``` - """ Base.Condition + """ Condition @doc doc""" ```rst @@ -14123,7 +14123,7 @@ golden otherwise only one is. If "error" is true, the passed value is raised as an exception in the woken tasks. ``` - """ Base.notify + """ notify @doc doc""" ```rst @@ -14138,7 +14138,7 @@ golden "error" is true, the value is raised as an exception in the woken task. ``` - """ Base.schedule + """ schedule @doc doc""" ```rst @@ -14146,7 +14146,7 @@ golden Wrap an expression in a Task and add it to the scheduler's queue. ``` - """ Base.@schedule + """ @schedule @doc doc""" ```rst @@ -14155,7 +14155,7 @@ golden Wrap an expression in a Task without executing it, and return the Task. This only creates a task, and does not run it. ``` - """ Base.@task + """ @task @doc doc""" ```rst @@ -14164,7 +14164,7 @@ golden Block the current task for a specified number of seconds. The minimum sleep time is 1 millisecond or input of "0.001". ``` - """ Base.sleep + """ sleep @doc doc""" ```rst @@ -14173,7 +14173,7 @@ golden Creates a reentrant lock. The same task can acquire the lock as many times as required. Each lock must be matched with an unlock. ``` - """ Base.ReentrantLock + """ ReentrantLock @doc doc""" ```rst @@ -14184,7 +14184,7 @@ golden task can acquire the lock multiple times. Each "lock" must be matched by an "unlock" ``` - """ Base.lock + """ lock @doc doc""" ```rst @@ -14194,7 +14194,7 @@ golden been acquired before, it just decrements an internal counter and returns immediately. ``` - """ Base.unlock + """ unlock @doc doc""" ```rst @@ -14205,7 +14205,7 @@ golden advantage of multiple cores. "addprocs(4)" will add 4 processes on the local machine. ``` - """ Base.addprocs + """ addprocs @doc doc""" ```rst @@ -14213,7 +14213,7 @@ golden Equivalent to "addprocs(CPU_CORES)" ``` - """ Base.addprocs + """ addprocs @doc doc""" ```rst @@ -14269,7 +14269,7 @@ golden number of seconds a newly launched worker waits for connection establishment. ``` - """ Base.addprocs + """ addprocs @doc doc""" ```rst @@ -14285,7 +14285,7 @@ golden "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. ``` - """ Base.addprocs + """ addprocs @doc doc""" ```rst @@ -14293,7 +14293,7 @@ golden Get the number of available processes. ``` - """ Base.nprocs + """ nprocs @doc doc""" ```rst @@ -14302,7 +14302,7 @@ golden Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. ``` - """ Base.nworkers + """ nworkers @doc doc""" ```rst @@ -14310,7 +14310,7 @@ golden Returns a list of all process identifiers. ``` - """ Base.procs + """ procs @doc doc""" ```rst @@ -14318,7 +14318,7 @@ golden Returns a list of all worker process identifiers. ``` - """ Base.workers + """ workers @doc doc""" ```rst @@ -14326,7 +14326,7 @@ golden Removes the specified workers. ``` - """ Base.rmprocs + """ rmprocs @doc doc""" ```rst @@ -14336,7 +14336,7 @@ golden is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted. ``` - """ Base.interrupt + """ interrupt @doc doc""" ```rst @@ -14344,7 +14344,7 @@ golden Get the id of the current process. ``` - """ Base.myid + """ myid @doc doc""" ```rst @@ -14361,7 +14361,7 @@ golden over the value of "err_retry" and "pmap" stops execution on the first error. ``` - """ Base.pmap + """ pmap @doc doc""" ```rst @@ -14370,7 +14370,7 @@ golden Call a function asynchronously on the given arguments on the specified process. Returns a "RemoteRef". ``` - """ Base.remotecall + """ remotecall @doc doc""" ```rst @@ -14404,7 +14404,7 @@ golden Often "wait" is called within a "while" loop to ensure a waited-for condition is met before proceeding. ``` - """ Base.wait + """ wait @doc doc""" ```rst @@ -14412,7 +14412,7 @@ golden Wait for and get the value of a remote reference. ``` - """ Base.fetch + """ fetch @doc doc""" ```rst @@ -14420,7 +14420,7 @@ golden Perform "wait(remotecall(...))" in one message. ``` - """ Base.remotecall_wait + """ remotecall_wait @doc doc""" ```rst @@ -14428,7 +14428,7 @@ golden Perform "fetch(remotecall(...))" in one message. ``` - """ Base.remotecall_fetch + """ remotecall_fetch @doc doc""" ```rst @@ -14438,7 +14438,7 @@ golden length 1" semantics: if a value is already present, blocks until the value is removed with "take!". Returns its first argument. ``` - """ Base.put! + """ put! @doc doc""" ```rst @@ -14447,7 +14447,7 @@ golden Fetch the value of a remote reference, removing it so that the reference is empty again. ``` - """ Base.take! + """ take! @doc doc""" ```rst @@ -14468,7 +14468,7 @@ golden @async put!(rr, remotecall_fetch(p, long_computation)) isready(rr) # will not block ``` - """ Base.isready + """ isready @doc doc""" ```rst @@ -14476,7 +14476,7 @@ golden Make an uninitialized remote reference on the local machine. ``` - """ Base.RemoteRef + """ RemoteRef @doc doc""" ```rst @@ -14484,7 +14484,7 @@ golden Make an uninitialized remote reference on process "n". ``` - """ Base.RemoteRef + """ RemoteRef @doc doc""" ```rst @@ -14494,7 +14494,7 @@ golden whichever is earlier. "testcb" is polled every "pollint" seconds. ``` - """ Base.timedwait + """ timedwait @doc doc""" ```rst @@ -14503,7 +14503,7 @@ golden Execute an expression on an automatically-chosen process, returning a "RemoteRef" to the result. ``` - """ Base.@spawn + """ @spawn @doc doc""" ```rst @@ -14513,7 +14513,7 @@ golden expression asynchronously on process "p", returning a "RemoteRef" to the result. ``` - """ Base.@spawnat + """ @spawnat @doc doc""" ```rst @@ -14521,7 +14521,7 @@ golden Equivalent to "fetch(@spawn expr)". ``` - """ Base.@fetch + """ @fetch @doc doc""" ```rst @@ -14529,7 +14529,7 @@ golden Equivalent to "fetch(@spawnat p expr)". ``` - """ Base.@fetchfrom + """ @fetchfrom @doc doc""" ```rst @@ -14538,7 +14538,7 @@ golden Schedule an expression to run on the local machine, also adding it to the set of items that the nearest enclosing "@sync" waits for. ``` - """ Base.@async + """ @async @doc doc""" ```rst @@ -14547,7 +14547,7 @@ golden Wait until all dynamically-enclosed uses of "@async", "@spawn", "@spawnat" and "@parallel" are complete. ``` - """ Base.@sync + """ @sync @doc doc""" ```rst @@ -14573,7 +14573,7 @@ golden body end ``` - """ Base.@parallel + """ @parallel @doc doc""" ```rst @@ -14592,7 +14592,7 @@ golden If an "init" function of the type "initfn(S::SharedArray)" is specified, it is called on all the participating workers. ``` - """ Base.SharedArray + """ SharedArray @doc doc""" ```rst @@ -14600,7 +14600,7 @@ golden Get the vector of processes that have mapped the shared array ``` - """ Base.procs + """ procs @doc doc""" ```rst @@ -14608,7 +14608,7 @@ golden Returns the actual "Array" object backing "S" ``` - """ Base.sdata + """ sdata @doc doc""" ```rst @@ -14617,7 +14617,7 @@ golden Returns the index of the current worker into the "pids" vector, i.e., the list of workers mapping the SharedArray ``` - """ Base.indexpids + """ indexpids @doc doc""" ```rst @@ -14630,7 +14630,7 @@ golden "params" is a dictionary of all keyword arguments "addprocs" was called with. ``` - """ Base.launch + """ launch @doc doc""" ```rst @@ -14649,7 +14649,7 @@ golden * with ":finalize" for cleanup purposes. ``` - """ Base.manage + """ manage @doc doc""" ```rst @@ -14661,7 +14661,7 @@ golden "Base.kill(manager::ClusterManager.....)" executes a remote "exit()" on "pid" ``` - """ Base.kill + """ kill @doc doc""" ```rst @@ -14672,7 +14672,7 @@ golden argument "--worker" has the effect of initializing a process as a worker using TCP/IP sockets for transport. ``` - """ Base.init_worker + """ init_worker @doc doc""" ```rst @@ -14688,7 +14688,7 @@ golden "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. ``` - """ Base.connect + """ connect @doc doc""" ```rst @@ -14701,7 +14701,7 @@ golden objects, one for incoming messages and the other for messages addressed to the remote worker. ``` - """ Base.Base + """ Base @doc doc""" ```rst @@ -14999,7 +14999,7 @@ golden periodic backtraces. These are appended to an internal buffer of backtraces. ``` - """ Base.@profile + """ @profile @doc doc""" ```rst @@ -15118,7 +15118,7 @@ golden function; "rev=true" reverses whatever ordering specified via the "by" and "lt" keywords. ``` - """ Base.sort! + """ sort! @doc doc""" ```rst @@ -15127,7 +15127,7 @@ golden Variant of "sort!" that returns a sorted copy of "v" leaving "v" itself unmodified. ``` - """ Base.sort + """ sort @doc doc""" ```rst @@ -15135,7 +15135,7 @@ golden Sort a multidimensional array "A" along the given dimension. ``` - """ Base.sort + """ sort @doc doc""" ```rst @@ -15154,7 +15154,7 @@ golden See also "sortperm!()" ``` - """ Base.sortperm + """ sortperm @doc doc""" ```rst @@ -15166,7 +15166,7 @@ golden See also "sortperm()" ``` - """ Base.sortperm! + """ sortperm! @doc doc""" ```rst @@ -15174,7 +15174,7 @@ golden Sort the rows of matrix "A" lexicographically. ``` - """ Base.sortrows + """ sortrows @doc doc""" ```rst @@ -15182,7 +15182,7 @@ golden Sort the columns of matrix "A" lexicographically. ``` - """ Base.sortcols + """ sortcols @doc doc""" ```rst @@ -15192,7 +15192,7 @@ golden "rev" keywords modify what order is considered to be sorted just as they do for "sort". ``` - """ Base.issorted + """ issorted @doc doc""" ```rst @@ -15204,7 +15204,7 @@ golden order. Returns an empty range located at the insertion point if "a" does not contain values equal to "x". ``` - """ Base.searchsorted + """ searchsorted @doc doc""" ```rst @@ -15214,7 +15214,7 @@ golden to "x", according to the specified order. Returns "length(a)+1" if "x" is greater than all values in "a". ``` - """ Base.searchsortedfirst + """ searchsortedfirst @doc doc""" ```rst @@ -15224,7 +15224,7 @@ golden "x", according to the specified order. Returns "0" if "x" is less than all values in "a". ``` - """ Base.searchsortedlast + """ searchsortedlast @doc doc""" ```rst @@ -15239,7 +15239,7 @@ golden indices is returned. Note that "select!" does not fully sort the input array. ``` - """ Base.select! + """ select! @doc doc""" ```rst @@ -15249,7 +15249,7 @@ golden it, thereby returning the same thing as "select!" but leaving "v" unmodified. ``` - """ Base.select + """ select @doc doc""" ```rst @@ -15257,7 +15257,7 @@ golden The number of characters in string "s". ``` - """ Base.length + """ length @doc doc""" ```rst @@ -15265,7 +15265,7 @@ golden The number of bytes in string "s". ``` - """ Base.sizeof + """ sizeof @doc doc""" ```rst @@ -15297,7 +15297,7 @@ golden Create a string from any values using the "print" function. ``` - """ Base.string + """ string @doc doc""" ```rst @@ -15305,7 +15305,7 @@ golden Create a string from any value using the "showall" function. ``` - """ Base.repr + """ repr @doc doc""" ```rst @@ -15316,7 +15316,7 @@ golden freed. If "length" is specified, the string does not have to be 0-terminated. ``` - """ Base.bytestring + """ bytestring @doc doc""" ```rst @@ -15326,7 +15326,7 @@ golden appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. ``` - """ Base.bytestring + """ bytestring @doc doc""" ```rst @@ -15334,7 +15334,7 @@ golden Create an ASCII string from a byte array. ``` - """ Base.ascii + """ ascii @doc doc""" ```rst @@ -15343,7 +15343,7 @@ golden Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). ``` - """ Base.ascii + """ ascii @doc doc""" ```rst @@ -15354,7 +15354,7 @@ golden freed. If "length" is specified, the string does not have to be 0-terminated. ``` - """ Base.ascii + """ ascii @doc doc""" ```rst @@ -15362,7 +15362,7 @@ golden Create a UTF-8 string from a byte array. ``` - """ Base.utf8 + """ utf8 @doc doc""" ```rst @@ -15373,7 +15373,7 @@ golden "length" is specified, the string does not have to be 0-terminated. ``` - """ Base.utf8 + """ utf8 @doc doc""" ```rst @@ -15382,7 +15382,7 @@ golden Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). ``` - """ Base.utf8 + """ utf8 @doc doc""" ```rst @@ -15437,7 +15437,7 @@ golden For example, NFKC corresponds to the options "compose=true, compat=true, stable=true". ``` - """ Base.normalize_string + """ normalize_string @doc doc""" ```rst @@ -15449,7 +15449,7 @@ golden even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) ``` - """ Base.graphemes + """ graphemes @doc doc""" ```rst @@ -15459,7 +15459,7 @@ golden currently can be one of "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" ``` - """ Base.isvalid + """ isvalid @doc doc""" ```rst @@ -15474,7 +15474,7 @@ golden for "UTF32String" can be "UTF32String", "Vector{Char}" or "Vector{UInt32}" ``` - """ Base.isvalid + """ isvalid @doc doc""" ```rst @@ -15483,7 +15483,7 @@ golden Returns true if the given char or integer is an assigned Unicode code point. ``` - """ Base.is_assigned_char + """ is_assigned_char @doc doc""" ```rst @@ -15492,7 +15492,7 @@ golden Test whether a string contains a match of the given regular expression. ``` - """ Base.ismatch + """ ismatch @doc doc""" ```rst @@ -15505,7 +15505,7 @@ golden by accessing "m.captures" The optional "idx" argument specifies an index at which to start the search. ``` - """ Base.match + """ match @doc doc""" ```rst @@ -15516,7 +15516,7 @@ golden matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges. ``` - """ Base.eachmatch + """ eachmatch @doc doc""" ```rst @@ -15524,7 +15524,7 @@ golden Return a vector of the matching substrings from eachmatch. ``` - """ Base.matchall + """ matchall @doc doc""" ```rst @@ -15533,7 +15533,7 @@ golden Make a string at least "n" columns wide when printed, by padding on the left with copies of "p". ``` - """ Base.lpad + """ lpad @doc doc""" ```rst @@ -15542,7 +15542,7 @@ golden Make a string at least "n" columns wide when printed, by padding on the right with copies of "p". ``` - """ Base.rpad + """ rpad @doc doc""" ```rst @@ -15563,7 +15563,7 @@ golden "search(string, 'c')" = "index" such that "string[index] == 'c'", or "0" if unmatched. ``` - """ Base.search + """ search @doc doc""" ```rst @@ -15573,7 +15573,7 @@ golden given characters within the given string, searching in reverse from "start". ``` - """ Base.rsearch + """ rsearch @doc doc""" ```rst @@ -15582,7 +15582,7 @@ golden Similar to "search", but return only the start index at which the substring is found, or 0 if it is not. ``` - """ Base.searchindex + """ searchindex @doc doc""" ```rst @@ -15591,7 +15591,7 @@ golden Similar to "rsearch", but return only the start index at which the substring is found, or 0 if it is not. ``` - """ Base.rsearchindex + """ rsearchindex @doc doc""" ```rst @@ -15599,7 +15599,7 @@ golden Determine whether the second argument is a substring of the first. ``` - """ Base.contains + """ contains @doc doc""" ```rst @@ -15612,7 +15612,7 @@ golden expression. If "r" is a function, each occurrence is replaced with "r(s)" where "s" is the matched substring. ``` - """ Base.replace + """ replace @doc doc""" ```rst @@ -15628,7 +15628,7 @@ golden maximum size for the result and a flag determining whether empty fields should be kept in the result. ``` - """ Base.split + """ split @doc doc""" ```rst @@ -15636,7 +15636,7 @@ golden Similar to "split", but starting from the end of the string. ``` - """ Base.rsplit + """ rsplit @doc doc""" ```rst @@ -15646,7 +15646,7 @@ golden If "chars" (a character, or vector or set of characters) is provided, instead remove characters contained in it. ``` - """ Base.strip + """ strip @doc doc""" ```rst @@ -15656,7 +15656,7 @@ golden (a character, or vector or set of characters) is provided, instead remove characters contained in it. ``` - """ Base.lstrip + """ lstrip @doc doc""" ```rst @@ -15666,7 +15666,7 @@ golden "chars" (a character, or vector or set of characters) is provided, instead remove characters contained in it. ``` - """ Base.rstrip + """ rstrip @doc doc""" ```rst @@ -15676,7 +15676,7 @@ golden second argument is a vector or set of characters, tests whether the first character of "string" belongs to that set. ``` - """ Base.startswith + """ startswith @doc doc""" ```rst @@ -15686,7 +15686,7 @@ golden argument is a vector or set of characters, tests whether the last character of "string" belongs to that set. ``` - """ Base.endswith + """ endswith @doc doc""" ```rst @@ -15694,7 +15694,7 @@ golden Returns "string" with all characters converted to uppercase. ``` - """ Base.uppercase + """ uppercase @doc doc""" ```rst @@ -15702,7 +15702,7 @@ golden Returns "string" with all characters converted to lowercase. ``` - """ Base.lowercase + """ lowercase @doc doc""" ```rst @@ -15710,7 +15710,7 @@ golden Returns "string" with the first character converted to uppercase. ``` - """ Base.ucfirst + """ ucfirst @doc doc""" ```rst @@ -15718,7 +15718,7 @@ golden Returns "string" with the first character converted to lowercase. ``` - """ Base.lcfirst + """ lcfirst @doc doc""" ```rst @@ -15733,7 +15733,7 @@ golden "strings" can be any iterable over elements "x" which are convertible to strings via "print(io::IOBuffer, x)". ``` - """ Base.join + """ join @doc doc""" ```rst @@ -15741,7 +15741,7 @@ golden Remove the last character from a string ``` - """ Base.chop + """ chop @doc doc""" ```rst @@ -15749,7 +15749,7 @@ golden Remove a trailing newline from a string ``` - """ Base.chomp + """ chomp @doc doc""" ```rst @@ -15757,7 +15757,7 @@ golden Convert a byte index to a character index ``` - """ Base.ind2chr + """ ind2chr @doc doc""" ```rst @@ -15765,7 +15765,7 @@ golden Convert a character index to a byte index ``` - """ Base.chr2ind + """ chr2ind @doc doc""" ```rst @@ -15773,7 +15773,7 @@ golden Tells whether index "i" is valid for the given string ``` - """ Base.isvalid + """ isvalid @doc doc""" ```rst @@ -15782,7 +15782,7 @@ golden Get the next valid string index after "i". Returns a value greater than "endof(str)" at or after the end of the string. ``` - """ Base.nextind + """ nextind @doc doc""" ```rst @@ -15791,7 +15791,7 @@ golden Get the previous valid string index before "i". Returns a value less than "1" at the beginning of the string. ``` - """ Base.prevind + """ prevind @doc doc""" ```rst @@ -15802,7 +15802,7 @@ golden "rng" argument specifies a random number generator, see *Random Numbers*. ``` - """ Base.randstring + """ randstring @doc doc""" ```rst @@ -15810,7 +15810,7 @@ golden Gives the number of columns needed to print a character. ``` - """ Base.charwidth + """ charwidth @doc doc""" ```rst @@ -15818,7 +15818,7 @@ golden Gives the number of columns needed to print a string. ``` - """ Base.strwidth + """ strwidth @doc doc""" ```rst @@ -15830,7 +15830,7 @@ golden Number, i.e. a character whose category code begins with 'L' or 'N'. ``` - """ Base.isalnum + """ isalnum @doc doc""" ```rst @@ -15841,7 +15841,7 @@ golden alphabetic if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'. ``` - """ Base.isalpha + """ isalpha @doc doc""" ```rst @@ -15850,7 +15850,7 @@ golden Tests whether a character belongs to the ASCII character set, or whether this is true for all elements of a string. ``` - """ Base.isascii + """ isascii @doc doc""" ```rst @@ -15860,7 +15860,7 @@ golden is true for all elements of a string. Control characters are the non-printing characters of the Latin-1 subset of Unicode. ``` - """ Base.iscntrl + """ iscntrl @doc doc""" ```rst @@ -15869,7 +15869,7 @@ golden Tests whether a character is a numeric digit (0-9), or whether this is true for all elements of a string. ``` - """ Base.isdigit + """ isdigit @doc doc""" ```rst @@ -15880,7 +15880,7 @@ golden would cause a printer to use ink should be classified with isgraph(c)==true. ``` - """ Base.isgraph + """ isgraph @doc doc""" ```rst @@ -15890,7 +15890,7 @@ golden true for all elements of a string. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase. ``` - """ Base.islower + """ islower @doc doc""" ```rst @@ -15901,7 +15901,7 @@ golden it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'. ``` - """ Base.isnumber + """ isnumber @doc doc""" ```rst @@ -15911,7 +15911,7 @@ golden control character. For strings, tests whether this is true for all elements of the string. ``` - """ Base.isprint + """ isprint @doc doc""" ```rst @@ -15922,7 +15922,7 @@ golden For strings, tests whether this is true for all elements of the string. ``` - """ Base.ispunct + """ ispunct @doc doc""" ```rst @@ -15934,7 +15934,7 @@ golden For strings, tests whether this is true for all elements of the string. ``` - """ Base.isspace + """ isspace @doc doc""" ```rst @@ -15945,7 +15945,7 @@ golden as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. ``` - """ Base.isupper + """ isupper @doc doc""" ```rst @@ -15954,7 +15954,7 @@ golden Tests whether a character is a valid hexadecimal digit, or whether this is true for all elements of a string. ``` - """ Base.isxdigit + """ isxdigit @doc doc""" ```rst @@ -15963,7 +15963,7 @@ golden Create a "Symbol" by concatenating the string representations of the arguments together. ``` - """ Base.symbol + """ symbol @doc doc""" ```rst @@ -15972,7 +15972,7 @@ golden General escaping of traditional C and Unicode escape sequences. See "print_escaped()" for more general escaping. ``` - """ Base.escape_string + """ escape_string @doc doc""" ```rst @@ -15981,7 +15981,7 @@ golden General unescaping of traditional C and Unicode escape sequences. Reverse of "escape_string()". See also "print_unescaped()". ``` - """ Base.unescape_string + """ unescape_string @doc doc""" ```rst @@ -16003,7 +16003,7 @@ golden making a copy of the data and treating the NUL as a terminator rather than as part of the string. ``` - """ Base.utf16 + """ utf16 @doc doc""" ```rst @@ -16013,7 +16013,7 @@ golden A copy is made; the pointer can be safely freed. If "length" is specified, the string does not have to be NUL-terminated. ``` - """ Base.utf16 + """ utf16 @doc doc""" ```rst @@ -16035,7 +16035,7 @@ golden without making a copy of the data and treating the NUL as a terminator rather than as part of the string. ``` - """ Base.utf32 + """ utf32 @doc doc""" ```rst @@ -16045,7 +16045,7 @@ golden A copy is made; the pointer can be safely freed. If "length" is specified, the string does not have to be NUL-terminated. ``` - """ Base.utf32 + """ utf32 @doc doc""" ```rst @@ -16056,7 +16056,7 @@ golden The synonym "WString" for "UTF32String" or "UTF16String" is also provided. ``` - """ Base.wstring + """ wstring @doc doc""" ```rst @@ -16066,7 +16066,7 @@ golden string or an array of strings, using "numcores" processors. (not exported) ``` - """ Base.runtests + """ runtests @doc doc""" ```rst diff --git a/doc/newdoc.jl b/doc/newdoc.jl index c41fd1453fd95..5d0857894d78d 100644 --- a/doc/newdoc.jl +++ b/doc/newdoc.jl @@ -1,11 +1,20 @@ +using Base.Meta + exceptions = ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] +qualify = ["ccall", "in", "<:", "|>", "*", "\\", "*", "/", "^", ".+", ".-", ".*", + "./", ".\\", ".^", "//", "<<", ">>", ">>>", "==", "!=", "===", "!==", + "<", "<=", ">", ">=", ".==", ".!=", ".<", ".<=", ".>", ".>=", "|", "*", + "^"] + cd(joinpath(dirname(@__FILE__), "..", "base", "docs")) do open("helpdb.jl", "w") do io for (mod, func, desc) in evalfile(Base.Help.helpdb_filename()) (func in exceptions || ismatch(r"[\{\} ]", func)) && continue + isop = ismatch(r"[^\w@!]|^!$", func) + isbase = mod == "Base" && !(func in qualify) - ismatch(r"[^\w@!]|^!$", func) && (func = "(:($func))") + isop && !isbase && (func = "(:($func))") desc = replace(rstrip(desc), "\$", "\\\$") desc = replace(desc, "\"\"\"", "\\\"\"\"") @@ -14,7 +23,7 @@ cd(joinpath(dirname(@__FILE__), "..", "base", "docs")) do ```rst $desc ``` - \""" $mod.$func + \""" $(isbase ? func : "$mod.$func") """) end end From fc43d630facb9d774f4b18781917d50e854f6644 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 14:14:52 -0400 Subject: [PATCH 03/27] basic rst rendering --- base/markdown/Markdown.jl | 1 + base/markdown/render/rst.jl | 80 +++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 base/markdown/render/rst.jl diff --git a/base/markdown/Markdown.jl b/base/markdown/Markdown.jl index 62559a9068a3f..401fb13dd41c7 100644 --- a/base/markdown/Markdown.jl +++ b/base/markdown/Markdown.jl @@ -18,6 +18,7 @@ include("Julia/Julia.jl") include("render/plain.jl") include("render/html.jl") include("render/latex.jl") +include("render/rst.jl") include("render/terminal/render.jl") diff --git a/base/markdown/render/rst.jl b/base/markdown/render/rst.jl new file mode 100644 index 0000000000000..cfd3c977c37ff --- /dev/null +++ b/base/markdown/render/rst.jl @@ -0,0 +1,80 @@ +# This file is a part of Julia. License is MIT: http://julialang.org/license + +rst(x) = sprint(rst, x) + +function rst(io::IO, content::Vector) + isempty(content) && return + for md in content[1:end-1] + rst(io, md) + println(io) + end + rst(io, content[end]) +end + +rst(io::IO, md::MD) = rst(io, md.content) + +function rst{l}(io::IO, header::Header{l}) + s = rstinline(header.text) + println(io, s) + println(io, string("*=-~:.^"[l])^length(s)) + println(io) +end + +function rst(io::IO, code::Code) + println(io, "::") + println(io) + for l in lines(code.code) + println(io, " ", l) + end +end + +function rst(io::IO, p::Paragraph) + rstinline(io, p.content) + println(io) +end + +function rst(io::IO, list::List) + for (i, item) in enumerate(list.items) + print(io, list.ordered ? "$i. " : " * ") + rstinline(io, item) + println(io) + end +end + +function rst(io::IO, md::HorizontalRule) + println(io, "–" ^ 5) +end + +rst(io::IO, md) = writemime(io, "text/rst", md) + +# Inline elements + +rstinline(x) = sprint(rstinline, x) + +function rstinline(io::IO, md...) + for el in md + rstinline(io, el) + end +end + +rstinline(io::IO, md::Vector) = !isempty(md) && rstinline(io, md...) + +# rstinline(io::IO, md::Image) = rstinline(io, ".. image:: ", md.url) + +rstinline(io::IO, md::Link) = rstinline(io, "`", md.text, " <", md.url, ">`_") + +rstinline(io::IO, s::AbstractString) = print(io, s) + +rstinline(io::IO, md::Bold) = rstinline(io, "**", md.text, "**") + +rstinline(io::IO, md::Italic) = rstinline(io, "*", md.text, "*") + +rstinline(io::IO, md::Code) = print(io, "``", md.code, "``") + +rstinline(io::IO, br::LineBreak) = println(io) + +rstinline(io::IO, x) = writemime(io, MIME"text/rst"(), x) + +# writemime + +Base.writemime(io::IO, ::MIME"text/rst", md::MD) = rst(io, md) From 19840a349d6020420fdca0c96f802eac9cb89cb0 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sat, 27 Jun 2015 15:16:16 -0400 Subject: [PATCH 04/27] new doc city: delete old helpdb.jl and things that depends on it --- CONTRIBUTING.md | 2 +- Makefile | 6 +- base/docs/Docs.jl | 5 +- base/docs/helpdb.jl | 16 - base/help.jl | 226 - base/sysimg.jl | 3 - doc/Makefile | 7 +- doc/README.md | 2 - doc/helpdb.jl | 13240 ------------------------------------------ test/docs.jl | 67 - 10 files changed, 4 insertions(+), 13570 deletions(-) delete mode 100644 base/help.jl delete mode 100644 doc/helpdb.jl diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b13f5e738148e..4f9e82ab46ade 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -146,7 +146,7 @@ Make sure that [Travis](http://www.travis-ci.org) greenlights the pull request w - Try to [squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) together small commits that make repeated changes to the same section of code so your pull request is easier to review, and Julia's history won't have any broken intermediate commits. A reasonable number of separate well-factored commits is fine, especially for larger changes. - If any conflicts arise due to changes in Julia's `master`, prefer updating your pull request branch with `git rebase` versus `git merge` or `git pull`, since the latter will introduce merge commits that clutter the git history with noise that makes your changes more difficult to review. - If you see any unrelated changes to submodules like `deps/libuv`, `deps/openlibm`, etc., try running `git submodule update` first. - - Avoid committing changes to auto-generated files such as `doc/helpdb.jl`, which is a frequent source of conflicts and can be re-generated later. + - Avoid committing changes to auto-generated files such as `doc/stdlib/*.rst`, which is a frequent source of conflicts and can be re-generated later. - Descriptive commit messages are good. - Using `git add -p` or `git add -i` can be useful to avoid accidentally committing unrelated changes. - GitHub does not send notifications when you push a new commit to a pull request, so please add a comment to the pull request thread to let reviewers know when you've made changes. diff --git a/Makefile b/Makefile index 81c8857ddb3b0..7131a9089a72e 100644 --- a/Makefile +++ b/Makefile @@ -89,7 +89,6 @@ release-candidate: release test @$(MAKE) -C doc latex SPHINXOPTS="-n" #Rebuild Julia PDF docs pedantically @$(MAKE) -C doc doctest #Run Julia doctests @$(MAKE) -C doc linkcheck #Check all links - @$(MAKE) -C doc helpdb.jl #Rebuild Julia online documentation for help(), apropos(), etc... @# Check to see if the above make invocations changed anything important @if [ -n "$$(git status --porcelain)" ]; then \ @@ -117,9 +116,6 @@ release-candidate: release test @echo 10. Change master to release-0.X in base/version.jl and base/version_git.sh as in 4cb1e20 @echo -$(build_docdir)/helpdb.jl: doc/helpdb.jl | $(build_docdir) - @cp $< $@ - $(build_man1dir)/julia.1: doc/man/julia.1 | $(build_man1dir) @mkdir -p $(build_man1dir) @cp $< $@ @@ -188,7 +184,7 @@ JULIA_SYSIMG_BUILD_FLAGS += --output-ji $(call cygpath_w,$(build_private_libdir) endif COMMA:=, -$(build_private_libdir)/sys.o: VERSION $(BASE_SRCS) $(build_docdir)/helpdb.jl $(build_private_libdir)/inference.$(SHLIB_EXT) +$(build_private_libdir)/sys.o: VERSION $(BASE_SRCS) $(build_private_libdir)/inference.$(SHLIB_EXT) @$(call PRINT_JULIA, cd base && \ $(call spawn,$(JULIA_EXECUTABLE)) -C $(JULIA_CPU_TARGET) --output-o $(call cygpath_w,$(build_private_libdir)/sys.o) $(JULIA_SYSIMG_BUILD_FLAGS) -f \ -J $(call cygpath_w,$(build_private_libdir)/inference.$(SHLIB_EXT)) sysimg.jl \ diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index e10d434312c04..ce76e31b9bf78 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -493,10 +493,7 @@ macro repl (ex) if $(isfield(ex) ? :(isa($(esc(ex.args[1])), DataType)) : false) $(isfield(ex) ? :(fielddoc($(esc(ex.args[1])), $(ex.args[2]))) : nothing) else - # Backwards-compatible with the previous help system, for now - let doc = @doc $(esc(ex)) - doc ≠ nothing ? doc : Base.Help.@help_ $(esc(ex)) - end + @doc $(esc(ex)) end end end diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index 465e00c29505b..b3d6398567e8c 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -1673,22 +1673,6 @@ ``` """ include_string - @doc doc""" - ```rst - help(name) - - Get help for a function. "name" can be an object or a string. - ``` - """ help - - @doc doc""" - ```rst - apropos(string) - - Search documentation for functions related to "string". - ``` - """ apropos - @doc doc""" ```rst which(f, types) diff --git a/base/help.jl b/base/help.jl deleted file mode 100644 index f0d6e8cca7039..0000000000000 --- a/base/help.jl +++ /dev/null @@ -1,226 +0,0 @@ -# This file is a part of Julia. License is MIT: http://julialang.org/license - -module Help - -export help, apropos, @help - -MODULE_DICT = nothing -FUNCTION_DICT = nothing - -function clear_cache() - global MODULE_DICT = nothing - global FUNCTION_DICT = nothing -end - -function decor_help_desc(func::AbstractString, mfunc::AbstractString, desc::AbstractString) - sd = convert(Array{ByteString,1}, split(desc, '\n')) - for i = 1:length(sd) - if startswith(sd[i], func) - sd[i] = mfunc * sd[i][length(func)+1:end] - else - break - end - end - return join(sd, '\n') -end - -function helpdb_filename() - file = "helpdb.jl" - for loc in [Base.locale()] - fn = joinpath(JULIA_HOME, Base.DOCDIR, loc, file) - if isfile(fn) - return fn - end - end - joinpath(JULIA_HOME, Base.DOCDIR, file) -end - -function init_help() - global MODULE_DICT, FUNCTION_DICT - if FUNCTION_DICT == nothing - helpdb = evalfile(helpdb_filename()) - MODULE_DICT = Dict() - FUNCTION_DICT = Dict() - for (mod,func,desc) in helpdb - if !isempty(mod) - mfunc = mod * "." * func - desc = decor_help_desc(func, mfunc, desc) - else - mfunc = func - end - if !haskey(FUNCTION_DICT, mfunc) - FUNCTION_DICT[mfunc] = [] - end - push!(FUNCTION_DICT[mfunc], desc) - if !haskey(MODULE_DICT, func) - MODULE_DICT[func] = [] - end - if !in(mod, MODULE_DICT[func]) - push!(MODULE_DICT[func], mod) - end - end - end -end - -function help(io::IO) - print(io, """ - - Welcome to Julia. The full manual is available at - - http://docs.julialang.org - - To get help, try help(function), help("@macro"), or help("variable"). - To search all help text, try apropos("string"). - """) -end - -function print_help_entries(io::IO, entries) - first = true - for desc in entries - if !first - println(io) - end - println(io, strip(desc)) - first = false - end -end - -func_expr_from_symbols(s::Vector{Symbol}) = length(s) == 1 ? s[1] : Expr(:., func_expr_from_symbols(s[1:end-1]), Expr(:quote, s[end])) - -module_defined(x::Symbol) = isdefined(x) -module_defined(x::Expr) = - x.head == :. && - module_defined(x.args[1]) && - isdefined(eval(x.args[1]), x.args[2].value) - -function is_defined_in_module(name::AbstractString, obj::DataType, mod::AbstractString) - module_defined(parse(mod)) && - isdefined(eval(parse(mod)), symbol(name)) && - eval(parse("$mod.$name")) == obj -end - -function help(io::IO, fname::AbstractString, obj=0) - init_help() - found = false - if haskey(FUNCTION_DICT, fname) - print_help_entries(io, FUNCTION_DICT[fname]) - found = true - elseif haskey(MODULE_DICT, fname) - allmods = MODULE_DICT[fname] - alldesc = [] - for mod in allmods - mfname = isempty(mod) ? fname : mod * "." * fname - if isgeneric(obj) - mf = eval(func_expr_from_symbols(map(symbol, split(mfname, r"(? 0 - print(io, " subtypes : ") - showcompact(io, st) - println(io) - end - end - fields = fieldnames(obj) - if !isempty(fields) - println(io, " fields : ", fields) - end - elseif isgeneric(obj) - writemime(io, "text/plain", obj); println() - else - println(io, "Symbol not found. Falling back on apropos search ...") - apropos(io, fname) - end - end -end - -apropos() = help() - -apropos(s::AbstractString) = apropos(STDOUT, s) -function apropos(io::IO, txt::AbstractString) - init_help() - n = 0 - r = Regex("\\Q$txt", "i") - for (func, entries) in FUNCTION_DICT - if ismatch(r, func) || any(e->ismatch(r,e), entries) - for desc in entries - nl = search(desc,'\n') - if nl != 0 - println(io, desc[1:(nl-1)]) - else - println(io, desc) - end - end - n+=1 - end - end - if n == 0 - println(io, "No help information found.") - end -end - -typename(t::DataType) = t.name.name - -help(io::IO, f::Function) = help(io, string(f), f) -help(io::IO, t::DataType) = help(io, string(typename(t)), t) -help(io::IO, t::Module) = help(io, string(t)) - -function help(io::IO, x) - show(io, x) - t = typeof(x) - if isa(t,DataType) - println(io, " is of type") - help(io, t) - else - println(io, " is of type $t") - end -end - -help(args...) = help(STDOUT, args...) -help(::IO, args...) = throw(ArgumentError("too many arguments to help()")) - -# check whether an expression is a qualified name, e.g. Base.FFTW.FORWARD -isname(n::Symbol) = true -isname(ex::Expr) = ((ex.head == :. && isname(ex.args[1]) && isname(ex.args[2])) - || (ex.head == :quote && isname(ex.args[1]))) - -macro help_(ex) - if ex === :? || ex === :help - return Expr(:call, :help) - elseif !isa(ex, Expr) || isname(ex) - return Expr(:call, :help, esc(ex)) - elseif ex.head == :macrocall && length(ex.args) == 1 - # e.g., "julia> @help @printf" - return Expr(:call, :help, string(ex.args[1])) - else - return Expr(:macrocall, symbol("@which"), esc(ex)) - end -end - -end # module diff --git a/base/sysimg.jl b/base/sysimg.jl index 7fe3aeb6b2719..38a83674dc8ea 100644 --- a/base/sysimg.jl +++ b/base/sysimg.jl @@ -231,10 +231,7 @@ include("interactiveutil.jl") include("replutil.jl") include("test.jl") include("i18n.jl") -include("help.jl") using .I18n -using .Help -push!(I18n.CALLBACKS, Help.clear_cache) # frontend include("Terminals.jl") diff --git a/doc/Makefile b/doc/Makefile index dc803abc94b90..de445e7d6a910 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,6 @@ # Makefile for Sphinx documentation -default: helpdb.jl html +default: html # You can set these variables from the command line. SPHINXOPTS = @@ -34,7 +34,6 @@ SPHINXBUILD = . $(ACTIVATE) && sphinx-build help: @echo "Please use 'make ' where is one of" - @echo " helpdb.jl to make the REPL help db" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @@ -171,10 +170,6 @@ doctest: $(SPHINX_BUILD) @echo "Testing of doctests in the sources finished, look at the " \ "results in _build/doctest/output.txt." -helpdb.jl: stdlib/*.rst $(SPHINX_BUILD) - $(SPHINXBUILD) -b jlhelp $(ALLSPHINXOPTS) _build/jlhelp - mv _build/jlhelp/jlhelp.jl helpdb.jl - manual/unicode-input-table.rst: $(JULIAHOME)/base/latex_symbols.jl $(JULIAHOME)/julia tabcomplete.jl > manual/unicode-input-table.rst diff --git a/doc/README.md b/doc/README.md index a6e1e4085e902..627feb73b262b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -25,7 +25,6 @@ Building the documentation Build the documentation by running - $ make helpdb.jl $ make html $ make latexpdf @@ -34,7 +33,6 @@ File layout ----------- conf.py Sphinx configuration - helpdb.jl REPL help database stdlib/ Julia standard library documentation UNDOCUMENTED.rst Undocumented functions (to be filled in and copied to the correct location in stdlib/) diff --git a/doc/helpdb.jl b/doc/helpdb.jl deleted file mode 100644 index 189a3ed7c8fd8..0000000000000 --- a/doc/helpdb.jl +++ /dev/null @@ -1,13240 +0,0 @@ -# automatically generated from files in doc/stdlib/ -- do not edit here - -Any[ - -("Base","ndims","ndims(A) -> Integer - - Returns the number of dimensions of A - -"), - -("Base","size","size(A[, 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 = rand(2,3,4); - - julia> size(A, 2) - 3 - - julia> size(A,3,2) - (4,3) - -"), - -("Base","iseltype","iseltype(A, T) - - Tests whether A or its elements are of type T - -"), - -("Base","length","length(A) -> Integer - - Returns the number of elements in A - -"), - -("Base","eachindex","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 (like \"Array\"), this is - simply the range \"1:length(A)\". For other array types, this - returns a specialized Cartesian range to efficiently index into the - array with indices specified for every dimension. Example for a - sparse 2-d array: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 - -"), - -("Base","Base","Base.linearindexing(A) - - \"linearindexing\" defines how an AbstractArray most efficiently - accesses its elements. If \"Base.linearindexing(A)\" returns - \"Base.LinearFast()\", this means that linear indexing with only - one index is an efficient operation. If it instead returns - \"Base.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 - traits-based 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 define \"linearindexing\" in the - type-domain: - - Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() - -"), - -("Base","countnz","countnz(A) - - Counts the number of nonzero values in array A (dense or sparse). - Note that this is not a constant-time operation. For sparse - matrices, one should usually use \"nnz\", which returns the number - of stored values. - -"), - -("Base","conj!","conj!(A) - - Convert an array to its complex conjugate in-place - -"), - -("Base","stride","stride(A, k) - - Returns the distance in memory (in number of elements) between - adjacent elements in dimension k - -"), - -("Base","strides","strides(A) - - Returns a tuple of the memory strides in each dimension - -"), - -("Base","ind2sub","ind2sub(dims, index) -> subscripts - - Returns a tuple of subscripts into an array with dimensions - \"dims\", corresponding to the linear index \"index\" - - **Example** \"i, j, ... = ind2sub(size(A), indmax(A))\" provides - the indices of the maximum element - -"), - -("Base","ind2sub","ind2sub(a, index) -> subscripts - - Returns a tuple of subscripts into array \"a\" corresponding to the - linear index \"index\" - -"), - -("Base","sub2ind","sub2ind(dims, i, j, k...) -> index - - The inverse of \"ind2sub\", returns the linear index corresponding - to the provided subscripts - -"), - -("Base","Array","Array(dims) - - \"Array{T}(dims)\" constructs an uninitialized dense array with - element type \"T\". \"dims\" may be a tuple or a series of integer - arguments. The syntax \"Array(T, dims)\" is also available, but - deprecated. - -"), - -("Base","getindex","getindex(type[, elements...]) - - Construct a 1-d array of the specified type. This is usually called - with the syntax \"Type[]\". Element values can be specified using - \"Type[a,b,c,...]\". - -"), - -("Base","cell","cell(dims) - - Construct an uninitialized cell array (heterogeneous array). - \"dims\" can be either a tuple or a series of integer arguments. - -"), - -("Base","zeros","zeros(type, dims) - - Create an array of all zeros of specified type. The type defaults - to Float64 if not specified. - -"), - -("Base","zeros","zeros(A) - - Create an array of all zeros with the same element type and shape - as A. - -"), - -("Base","ones","ones(type, dims) - - Create an array of all ones of specified type. The type defaults to - Float64 if not specified. - -"), - -("Base","ones","ones(A) - - Create an array of all ones with the same element type and shape as - A. - -"), - -("Base","trues","trues(dims) - - Create a \"BitArray\" with all values set to true - -"), - -("Base","falses","falses(dims) - - Create a \"BitArray\" with all values set to false - -"), - -("Base","fill","fill(x, dims) - - Create an array filled with the value \"x\". For example, - \"fill(1.0, (10,10))\" returns a 10x10 array of floats, with each - element initialized to 1.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 evaluating \"Foo()\" once. - -"), - -("Base","fill!","fill!(A, x) - - Fill array \"A\" with the value \"x\". If \"x\" is an object - reference, all elements will refer to the same object. \"fill!(A, - Foo())\" will return \"A\" filled with the result of evaluating - \"Foo()\" once. - -"), - -("Base","reshape","reshape(A, dims) - - Create an array with the same data as the given array, but with - different dimensions. An implementation for a particular type of - array may choose whether the data is copied or shared. - -"), - -("Base","similar","similar(array, element_type, dims) - - Create an uninitialized array of the same type as the given array, - but with the specified element type and dimensions. The second and - third arguments are both optional. The \"dims\" argument may be a - tuple or a series of integer arguments. For some special - \"AbstractArray\" objects which are not real containers (like - ranges), this function returns a standard \"Array\" to allow - operating on elements. - -"), - -("Base","reinterpret","reinterpret(type, A) - - Change the type-interpretation of a block of memory. For example, - \"reinterpret(Float32, UInt32(7))\" interprets the 4 bytes - corresponding to \"UInt32(7)\" as a \"Float32\". For arrays, this - constructs an array with the same binary data as the given array, - but with the specified element type. - -"), - -("Base","eye","eye(n) - - n-by-n identity matrix - -"), - -("Base","eye","eye(m, n) - - m-by-n identity matrix - -"), - -("Base","eye","eye(A) - - Constructs an identity matrix of the same dimensions and type as - \"A\". - -"), - -("Base","linspace","linspace(start, stop, n=100) - - Construct a range of \"n\" linearly spaced elements from \"start\" - to \"stop\". - -"), - -("Base","logspace","logspace(start, stop, n=50) - - Construct a vector of \"n\" logarithmically spaced numbers from - \"10^start\" to \"10^stop\". - -"), - -("Base","broadcast","broadcast(f, As...) - - Broadcasts the arrays \"As\" to a common size by expanding - singleton dimensions, and returns an array of the results - \"f(as...)\" for each position. - -"), - -("Base","broadcast!","broadcast!(f, dest, As...) - - Like \"broadcast\", but store the result of \"broadcast(f, As...)\" - in the \"dest\" array. Note that \"dest\" is only used to store the - result, and does not supply arguments to \"f\" unless it is also - listed in the \"As\", as in \"broadcast!(f, A, A, B)\" to perform - \"A[:] = broadcast(f, A, B)\". - -"), - -("Base","bitbroadcast","bitbroadcast(f, As...) - - Like \"broadcast\", but allocates a \"BitArray\" to store the - result, rather then an \"Array\". - -"), - -("Base","broadcast_function","broadcast_function(f) - - Returns a function \"broadcast_f\" such that - \"broadcast_function(f)(As...) === broadcast(f, As...)\". Most - useful in the form \"const broadcast_f = broadcast_function(f)\". - -"), - -("Base","broadcast!_function","broadcast!_function(f) - - Like \"broadcast_function\", but for \"broadcast!\". - -"), - -("Base","getindex","getindex(A, inds...) - - Returns a subset of array \"A\" as specified by \"inds\", where - each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See - the manual section on *array indexing* for details. - -"), - -("Base","sub","sub(A, inds...) - - Like \"getindex()\", but returns a view into the parent array \"A\" - with the given indices instead of making a copy. Calling - \"getindex()\" or \"setindex!()\" on the returned \"SubArray\" - computes the indices to the parent array on the fly without - checking bounds. - -"), - -("Base","parent","parent(A) - - Returns the \"parent array\" of an array view type (e.g., - SubArray), or the array itself if it is not a view - -"), - -("Base","parentindexes","parentindexes(A) - - From an array view \"A\", returns the corresponding indexes in the - parent - -"), - -("Base","slicedim","slicedim(A, d, i) - - Return all the data of \"A\" where the index for dimension \"d\" - equals \"i\". Equivalent to \"A[:,:,...,i,:,:,...]\" where \"i\" is - in position \"d\". - -"), - -("Base","slice","slice(A, inds...) - - Returns a view of array \"A\" with the given indices like - \"sub()\", but drops all dimensions indexed with scalars. - -"), - -("Base","setindex!","setindex!(A, X, inds...) - - Store values from array \"X\" within some subset of \"A\" as - specified by \"inds\". - -"), - -("Base","broadcast_getindex","broadcast_getindex(A, inds...) - - Broadcasts the \"inds\" arrays to a common size like \"broadcast\", - and returns an array of the results \"A[ks...]\", where \"ks\" goes - over the positions in the broadcast. - -"), - -("Base","broadcast_setindex!","broadcast_setindex!(A, X, inds...) - - Broadcasts the \"X\" and \"inds\" arrays to a common size and - stores the value from each position in \"X\" at the indices given - by the same positions in \"inds\". - -"), - -("Base","cat","cat(dims, A...) - - Concatenate the input arrays along the specified dimensions in the - iterable \"dims\". For dimensions not in \"dims\", all input arrays - should have the same size, which will also be the size of the - output array along that dimension. For dimensions in \"dims\", the - size of the output array is the sum of the sizes of the input - arrays along that dimension. If \"dims\" is a single number, the - different arrays are tightly stacked along that dimension. If - \"dims\" is an iterable containing several dimensions, this allows - to construct block diagonal matrices and their higher-dimensional - 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 with *matrices[1]*, *matrices[2]*, ... as diagonal - blocks and matching zero blocks away from the diagonal. - -"), - -("Base","vcat","vcat(A...) - - Concatenate along dimension 1 - -"), - -("Base","hcat","hcat(A...) - - Concatenate along dimension 2 - -"), - -("Base","hvcat","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. For example, - \"[a b;c d e]\" calls \"hvcat((2,3),a,b,c,d,e)\". - - If the first argument is a single integer \"n\", then all block - rows are assumed to have \"n\" block columns. - -"), - -("Base","flipdim","flipdim(A, d) - - Reverse \"A\" in dimension \"d\". - -"), - -("Base","circshift","circshift(A, shifts) - - Circularly shift the data in an array. The second argument is a - vector giving the amount to shift in each dimension. - -"), - -("Base","find","find(A) - - Return a vector of the linear indexes of the non-zeros in \"A\" - (determined by \"A[i]!=0\"). A common use of this is to convert a - boolean array to an array of indexes of the \"true\" elements. - -"), - -("Base","find","find(f, A) - - Return a vector of the linear indexes of \"A\" where \"f\" returns - true. - -"), - -("Base","findn","findn(A) - - Return a vector of indexes for each dimension giving the locations - of the non-zeros in \"A\" (determined by \"A[i]!=0\"). - -"), - -("Base","findnz","findnz(A) - - Return a tuple \"(I, J, V)\" where \"I\" and \"J\" are the row and - column indexes of the non-zero values in matrix \"A\", and \"V\" is - a vector of the non-zero values. - -"), - -("Base","findfirst","findfirst(A) - - Return the index of the first non-zero value in \"A\" (determined - by \"A[i]!=0\"). - -"), - -("Base","findfirst","findfirst(A, v) - - Return the index of the first element equal to \"v\" in \"A\". - -"), - -("Base","findfirst","findfirst(predicate, A) - - Return the index of the first element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findlast","findlast(A) - - Return the index of the last non-zero value in \"A\" (determined by - \"A[i]!=0\"). - -"), - -("Base","findlast","findlast(A, v) - - Return the index of the last element equal to \"v\" in \"A\". - -"), - -("Base","findlast","findlast(predicate, A) - - Return the index of the last element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findnext","findnext(A, i) - - Find the next index >= \"i\" of a non-zero element of \"A\", or - \"0\" if not found. - -"), - -("Base","findnext","findnext(predicate, A, i) - - Find the next index >= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - -"), - -("Base","findnext","findnext(A, v, i) - - Find the next index >= \"i\" of an element of \"A\" equal to \"v\" - (using \"==\"), or \"0\" if not found. - -"), - -("Base","findprev","findprev(A, i) - - Find the previous index <= \"i\" of a non-zero element of \"A\", or - 0 if not found. - -"), - -("Base","findprev","findprev(predicate, A, i) - - Find the previous index <= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - -"), - -("Base","findprev","findprev(A, v, i) - - Find the previous index <= \"i\" of an element of \"A\" equal to - \"v\" (using \"==\"), or \"0\" if not found. - -"), - -("Base","permutedims","permutedims(A, perm) - - Permute the dimensions of array \"A\". \"perm\" is a vector - specifying a permutation of length \"ndims(A)\". This is a - generalization of transpose for multi-dimensional arrays. Transpose - is equivalent to \"permutedims(A, [2,1])\". - -"), - -("Base","ipermutedims","ipermutedims(A, perm) - - Like \"permutedims()\", except the inverse of the given permutation - is applied. - -"), - -("Base","permutedims!","permutedims!(dest, src, perm) - - Permute the dimensions of array \"src\" and store the result in the - array \"dest\". \"perm\" is a vector specifying a permutation of - length \"ndims(src)\". The preallocated array \"dest\" should have - \"size(dest) == size(src)[perm]\" and is completely overwritten. No - in-place permutation is supported and unexpected results will - happen if *src* and *dest* have overlapping memory regions. - -"), - -("Base","squeeze","squeeze(A, dims) - - Remove the dimensions specified by \"dims\" from array \"A\". - Elements of \"dims\" must be unique and within the range - \"1:ndims(A)\". - -"), - -("Base","vec","vec(Array) -> Vector - - Vectorize an array using column-major convention. - -"), - -("Base","promote_shape","promote_shape(s1, s2) - - Check two array shapes for compatibility, allowing trailing - singleton dimensions, and return whichever shape has more - dimensions. - -"), - -("Base","checkbounds","checkbounds(array, indexes...) - - Throw an error if the specified indexes are not in bounds for the - given array. - -"), - -("Base","randsubseq","randsubseq(A, p) -> Vector - - Return a vector consisting of a random subsequence of the given - array \"A\", where each element of \"A\" is included (in order) - with independent probability \"p\". (Complexity is linear in - \"p*length(A)\", so this function is efficient even if \"p\" is - small and \"A\" is large.) Technically, this process is known as - \"Bernoulli sampling\" of \"A\". - -"), - -("Base","randsubseq!","randsubseq!(S, A, p) - - Like \"randsubseq\", but the results are stored in \"S\" (which is - resized as needed). - -"), - -("Base","cumprod","cumprod(A[, dim]) - - Cumulative product along a dimension \"dim\" (defaults to 1). See - also \"cumprod!()\" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). - -"), - -("Base","cumprod!","cumprod!(B, A[, dim]) - - Cumulative product of \"A\" along a dimension, storing the result - in \"B\". The dimension defaults to 1. - -"), - -("Base","cumsum","cumsum(A[, dim]) - - Cumulative sum along a dimension \"dim\" (defaults to 1). See also - \"cumsum!()\" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). - -"), - -("Base","cumsum!","cumsum!(B, A[, dim]) - - Cumulative sum of \"A\" along a dimension, storing the result in - \"B\". The dimension defaults to 1. - -"), - -("Base","cumsum_kbn","cumsum_kbn(A[, dim]) - - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. The - dimension defaults to 1. - -"), - -("Base","cummin","cummin(A[, dim]) - - Cumulative minimum along a dimension. The dimension defaults to 1. - -"), - -("Base","cummax","cummax(A[, dim]) - - Cumulative maximum along a dimension. The dimension defaults to 1. - -"), - -("Base","diff","diff(A[, dim]) - - Finite difference operator of matrix or vector. - -"), - -("Base","gradient","gradient(F[, h]) - - Compute differences along vector \"F\", using \"h\" as the spacing - between points. The default spacing is one. - -"), - -("Base","rot180","rot180(A) - - Rotate matrix \"A\" 180 degrees. - -"), - -("Base","rot180","rot180(A, k) - - Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. - If \"k\" is even, this is equivalent to a \"copy\". - -"), - -("Base","rotl90","rotl90(A) - - Rotate matrix \"A\" left 90 degrees. - -"), - -("Base","rotl90","rotl90(A, k) - - Rotate matrix \"A\" left 90 degrees an integer \"k\" number of - times. If \"k\" is zero or a multiple of four, this is equivalent - to a \"copy\". - -"), - -("Base","rotr90","rotr90(A) - - Rotate matrix \"A\" right 90 degrees. - -"), - -("Base","rotr90","rotr90(A, k) - - Rotate matrix \"A\" right 90 degrees an integer \"k\" number of - times. If \"k\" is zero or a multiple of four, this is equivalent - to a \"copy\". - -"), - -("Base","reducedim","reducedim(f, A, dims[, initial]) - - Reduce 2-argument function \"f\" along dimensions of \"A\". - \"dims\" is a vector specifying the dimensions to reduce, and - \"initial\" is the initial value to use in the reductions. For *+*, - ***, *max* and *min* the *initial* argument is optional. - - The associativity of the reduction is implementation-dependent; if - you need a particular associativity, e.g. left-to-right, you should - write your own loop. See documentation for \"reduce\". - -"), - -("Base","mapreducedim","mapreducedim(f, op, A, dims[, initial]) - - Evaluates to the same as *reducedim(op, map(f, A), dims, - f(initial))*, but is generally faster because the intermediate - array is avoided. - -"), - -("Base","mapslices","mapslices(f, A, dims) - - Transform the given dimensions of array \"A\" using function \"f\". - \"f\" is called on each slice of \"A\" of the form - \"A[...,:,...,:,...]\". \"dims\" is an integer vector specifying - where the colons go in this expression. The results are - concatenated along the remaining dimensions. For example, if - \"dims\" is \"[1,2]\" and A is 4-dimensional, \"f\" is called on - \"A[:,:,i,j]\" for all \"i\" and \"j\". - -"), - -("Base","sum_kbn","sum_kbn(A) - - Returns the sum of all array elements, using the Kahan-Babuska- - Neumaier compensated summation algorithm for additional accuracy. - -"), - -("Base","cartesianmap","cartesianmap(f, dims) - - Given a \"dims\" tuple of integers \"(m, n, ...)\", call \"f\" on - all combinations of integers in the ranges \"1:m\", \"1:n\", etc. - - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 - -"), - -("Base","nthperm","nthperm(v, k) - - Compute the kth lexicographic permutation of a vector. - -"), - -("Base","nthperm","nthperm(p) - - Return the \"k\" that generated permutation \"p\". Note that - \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". - -"), - -("Base","nthperm!","nthperm!(v, k) - - In-place version of \"nthperm()\". - -"), - -("Base","randperm","randperm([rng], n) - - Construct a random permutation of length \"n\". The optional - \"rng\" argument specifies a random number generator, see *Random - Numbers*. - -"), - -("Base","invperm","invperm(v) - - Return the inverse permutation of v. - -"), - -("Base","isperm","isperm(v) -> Bool - - Returns true if v is a valid permutation. - -"), - -("Base","permute!","permute!(v, p) - - Permute vector \"v\" in-place, according to permutation \"p\". No - checking is done to verify that \"p\" is a permutation. - - To return a new permutation, use \"v[p]\". Note that this is - generally faster than \"permute!(v,p)\" for large vectors. - -"), - -("Base","ipermute!","ipermute!(v, p) - - Like permute!, but the inverse of the given permutation is applied. - -"), - -("Base","randcycle","randcycle([rng], n) - - Construct a random cyclic permutation of length \"n\". The optional - \"rng\" argument specifies a random number generator, see *Random - Numbers*. - -"), - -("Base","shuffle","shuffle([rng], v) - - Return a randomly permuted copy of \"v\". The optional \"rng\" - argument specifies a random number generator, see *Random Numbers*. - -"), - -("Base","shuffle!","shuffle!([rng], v) - - In-place version of \"shuffle()\". - -"), - -("Base","reverse","reverse(v[, start=1[, stop=length(v)]]) - - Return a copy of \"v\" reversed from start to stop. - -"), - -("Base","reverseind","reverseind(v, i) - - Given an index \"i\" in \"reverse(v)\", return the corresponding - index in \"v\" so that \"v[reverseind(v,i)] == reverse(v)[i]\". - (This can be nontrivial in the case where \"v\" is a Unicode - string.) - -"), - -("Base","reverse!","reverse!(v[, start=1[, stop=length(v)]]) -> v - - In-place version of \"reverse()\". - -"), - -("Base","combinations","combinations(array, n) - - Generate all combinations of \"n\" elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - \"collect(combinations(array,n))\" to get an array of all - combinations. - -"), - -("Base","permutations","permutations(array) - - Generate all permutations of an indexable object. Because the - number of permutations can be very large, this function returns an - iterator object. Use \"collect(permutations(array))\" to get an - array of all permutations. - -"), - -("Base","partitions","partitions(n) - - Generate all integer arrays that sum to \"n\". Because the number - of partitions can be very large, this function returns an iterator - object. Use \"collect(partitions(n))\" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using \"length(partitions(n))\". - -"), - -("Base","partitions","partitions(n, m) - - Generate all arrays of \"m\" integers that sum to \"n\". Because - the number of partitions can be very large, this function returns - an iterator object. Use \"collect(partitions(n,m))\" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using \"length(partitions(n,m))\". - -"), - -("Base","partitions","partitions(array) - - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - \"collect(partitions(array))\" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using \"length(partitions(array))\". - -"), - -("Base","partitions","partitions(array, m) - - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use \"collect(partitions(array,m))\" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using \"length(partitions(array,m))\". - -"), - -("Base","bitpack","bitpack(A::AbstractArray{T, N}) -> BitArray - - Converts a numeric array to a packed boolean array - -"), - -("Base","bitunpack","bitunpack(B::BitArray{N}) -> Array{Bool,N} - - Converts a packed boolean array to an array of booleans - -"), - -("Base","flipbits!","flipbits!(B::BitArray{N}) -> BitArray{N} - - Performs a bitwise not operation on B. See *~ operator*. - -"), - -("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on \"src\" and put the result - into \"dest\". - -"), - -("Base","rol!","rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on B. - -"), - -("Base","rol","rol(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation. - -"), - -("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on \"src\" and put the result - into \"dest\". - -"), - -("Base","ror!","ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on B. - -"), - -("Base","ror","ror(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation. - -"), - -("Base","sparse","sparse(I, J, V[, m, n, combine]) - - Create a sparse matrix \"S\" of dimensions \"m x n\" such that - \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to - combine duplicates. If \"m\" and \"n\" are not specified, they are - set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" - function is not supplied, duplicates are added by default. - -"), - -("Base","sparsevec","sparsevec(I, V[, m, combine]) - - Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] - = V[k]\". Duplicates are combined using the \"combine\" function, - which defaults to \"+\" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. - -"), - -("Base","sparsevec","sparsevec(D::Dict[, m]) - - Create a sparse matrix of size \"m x 1\" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. - -"), - -("Base","issparse","issparse(S) - - Returns \"true\" if \"S\" is sparse, and \"false\" otherwise. - -"), - -("Base","sparse","sparse(A) - - Convert an AbstractMatrix \"A\" into a sparse matrix. - -"), - -("Base","sparsevec","sparsevec(A) - - Convert a dense vector \"A\" into a sparse matrix of size \"m x - 1\". In julia, sparse vectors are really just sparse matrices with - one column. - -"), - -("Base","full","full(S) - - Convert a sparse matrix \"S\" into a dense matrix. - -"), - -("Base","nnz","nnz(A) - - Returns the number of stored (filled) elements in a sparse matrix. - -"), - -("Base","spzeros","spzeros(m, n) - - Create a sparse matrix of size \"m x n\". This sparse matrix will - not contain any nonzero values. No storage will be allocated for - nonzero values during construction. - -"), - -("Base","spones","spones(S) - - Create a sparse matrix with the same structure as that of \"S\", - but with every nonzero element having the value \"1.0\". - -"), - -("Base","speye","speye(type, m[, n]) - - Create a sparse identity matrix of specified type of size \"m x - m\". In case \"n\" is supplied, create a sparse identity matrix of - size \"m x n\". - -"), - -("Base","spdiagm","spdiagm(B, d[, m, n]) - - Construct a sparse diagonal matrix. \"B\" is a tuple of vectors - containing the diagonals and \"d\" is a tuple containing the - positions of the diagonals. In the case the input contains only one - diagonaly, \"B\" can be a vector (instead of a tuple) and \"d\" can - be the diagonal position (instead of a tuple), defaulting to 0 - (diagonal). Optionally, \"m\" and \"n\" specify the size of the - resulting sparse matrix. - -"), - -("Base","sprand","sprand([rng], m, n, p[, rfn]) - - Create a random \"m\" by \"n\" sparse matrix, in which the - probability of any element being nonzero is independently given by - \"p\" (and hence the mean density of nonzeros is also exactly - \"p\"). Nonzero values are sampled from the distribution specified - by \"rfn\". The uniform distribution is used in case \"rfn\" is not - specified. The optional \"rng\" argument specifies a random number - generator, see *Random Numbers*. - -"), - -("Base","sprandn","sprandn(m, n, p) - - Create a random \"m\" by \"n\" sparse matrix with the specified - (independent) probability \"p\" of any entry being nonzero, where - nonzero values are sampled from the normal distribution. - -"), - -("Base","sprandbool","sprandbool(m, n, p) - - Create a random \"m\" by \"n\" sparse boolean matrix with the - specified (independent) probability \"p\" of any entry being - \"true\". - -"), - -("Base","etree","etree(A[, post]) - - Compute the elimination tree of a symmetric sparse matrix \"A\" - from \"triu(A)\" and, optionally, its post-ordering permutation. - -"), - -("Base","symperm","symperm(A, p) - - Return the symmetric permutation of A, which is \"A[p,p]\". A - should be symmetric and sparse, where only the upper triangular - part of the matrix is stored. This algorithm ignores the lower - triangular part of the matrix. Only the upper triangular part of - the result is returned as well. - -"), - -("Base","nonzeros","nonzeros(A) - - Return a vector of the structural nonzero values in sparse matrix - \"A\". This includes zeros that are explicitly stored in the sparse - matrix. The returned vector points directly to the internal nonzero - storage of \"A\", and any modifications to the returned vector will - mutate \"A\" as well. See \"rowvals(A)\" and \"nzrange(A, col)\". - -"), - -("Base","rowvals","rowvals(A) - - Return a vector of the row indices of \"A\", and any modifications - to the returned vector will mutate \"A\" as well. Given the - internal storage format of sparse matrices, providing access to how - the row indices are stored internally can be useful in conjuction - with iterating over structural nonzero values. See \"nonzeros(A)\" - and \"nzrange(A, col)\". - -"), - -("Base","nzrange","nzrange(A, col) - - Return the range of indices to the structural nonzero values of a - sparse matrix column. In conjunction with \"nonzeros(A)\" and - \"rowvals(A)\", 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 - -"), - -("Base","exit","exit([code]) - - Quit (or control-D at the prompt). The default exit code is zero, - indicating that the processes completed successfully. - -"), - -("Base","quit","quit() - - Quit the program indicating that the processes completed - successfully. This function calls \"exit(0)\" (see \"exit()\"). - -"), - -("Base","atexit","atexit(f) - - Register a zero-argument function to be called at exit. - -"), - -("Base","atreplinit","atreplinit(f) - - Register a one-argument function to be called before the REPL - interface is initialized in interactive sessions; this is useful to - customize the interface. The argument of \"f\" is the REPL object. - This function should be called from within the \".juliarc.jl\" - initialization file. - -"), - -("Base","isinteractive","isinteractive() -> Bool - - Determine whether Julia is running an interactive session. - -"), - -("Base","whos","whos([Module,] [pattern::Regex]) - - Print information about exported global variables in a module, - optionally restricted to those matching \"pattern\". - -"), - -("Base","edit","edit(file::AbstractString[, line]) - - Edit a file optionally providing a line number to edit at. Returns - to the julia prompt when you quit the editor. - -"), - -("Base","edit","edit(function[, types]) - - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. - -"), - -("Base","@edit","@edit() - - Evaluates the arguments to the function call, determines their - types, and calls the \"edit\" function on the resulting expression - -"), - -("Base","less","less(file::AbstractString[, line]) - - Show a file using the default pager, optionally providing a - starting line number. Returns to the julia prompt when you quit the - pager. - -"), - -("Base","less","less(function[, types]) - - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. - -"), - -("Base","@less","@less() - - Evaluates the arguments to the function call, determines their - types, and calls the \"less\" function on the resulting expression - -"), - -("Base","clipboard","clipboard(x) - - Send a printed form of \"x\" to the operating system clipboard - (\"copy\"). - -"), - -("Base","clipboard","clipboard() -> AbstractString - - Return a string with the contents of the operating system clipboard - (\"paste\"). - -"), - -("Base","require","require(file::AbstractString...) - - Load source files once, in the context of the \"Main\" module, on - every active node, searching standard locations for files. - \"require\" is considered a top-level operation, so it sets the - current \"include\" path but does not use it to search for files - (see help for \"include\"). This function is typically used to load - library code, and is implicitly called by \"using\" to load - packages. - - When searching for files, \"require\" first looks in the current - working directory, then looks for package code under \"Pkg.dir()\", - then tries paths in the global array \"LOAD_PATH\". - -"), - -("Base","reload","reload(file::AbstractString) - - Like \"require\", except forces loading of files regardless of - whether they have been loaded before. Typically used when - interactively developing libraries. - -"), - -("Base","include","include(path::AbstractString) - - Evaluate the contents of a source file in the current context. - During including, a task-local include path is set to the directory - containing the file. Nested calls to \"include\" will search - relative to that path. All paths refer to files on node 1 when - running in parallel, and files will be fetched from node 1. This - function is typically used to load source interactively, or to - combine files in packages that are broken into multiple source - files. - -"), - -("Base","include_string","include_string(code::AbstractString) - - Like \"include\", except reads code from the given string rather - than from a file. Since there is no file path involved, no path - processing or fetching from node 1 is done. - -"), - -("Base","help","help(name) - - Get help for a function. \"name\" can be an object or a string. - -"), - -("Base","apropos","apropos(string) - - Search documentation for functions related to \"string\". - -"), - -("Base","which","which(f, types) - - Returns the method of \"f\" (a \"Method\" object) that would be - called for arguments of the given types. - - If \"types\" is an abstract type, then the method that would be - called by \"invoke\" is returned. - -"), - -("Base","which","which(symbol) - - Return the module in which the binding for the variable referenced - by \"symbol\" was created. - -"), - -("Base","@which","@which() - - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the \"Method\" object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the \"which\" function. - -"), - -("Base","methods","methods(f[, types]) - - Returns the method table for \"f\". - - If \"types\" is specified, returns an array of methods whose types - match. - -"), - -("Base","methodswith","methodswith(typ[, module or function][, showparents]) - - Return an array of methods with an argument of type \"typ\". If - optional \"showparents\" is \"true\", also return arguments with a - parent type of \"typ\", excluding type \"Any\". - - The optional second argument restricts the search to a particular - module or function. - -"), - -("Base","@show","@show() - - Show an expression and result, returning the result - -"), - -("Base","versioninfo","versioninfo([verbose::Bool]) - - Print information about the version of Julia in use. If the - \"verbose\" argument is true, detailed system information is shown - as well. - -"), - -("Base","workspace","workspace() - - Replace the top-level module (\"Main\") with a new one, providing a - clean workspace. The previous \"Main\" module is made available as - \"LastMain\". A previously-loaded package can be accessed using a - statement such as \"using LastMain.Package\". - - This function should only be used interactively. - -"), - -("Base","ans","ans - - A variable referring to the last computed value, automatically set - at the interactive prompt. - -"), - -("Base","is","is(x, y) -> Bool -===(x, y) -> Bool -≡(x, y) -> Bool - - Determine whether \"x\" and \"y\" are identical, in the sense that - no program could distinguish them. Compares mutable objects by - address in memory, and compares immutable objects (such as numbers) - by contents at the bit level. This function is sometimes called - \"egal\". - -"), - -("Base","isa","isa(x, type) -> Bool - - Determine whether \"x\" is of the given \"type\". - -"), - -("Base","isequal","isequal(x, y) - - Similar to \"==\", except treats all floating-point \"NaN\" values - as equal to each other, and treats \"-0.0\" as unequal to \"0.0\". - The default implementation of \"isequal\" calls \"==\", so if you - have a type that doesn't have these floating-point subtleties then - you probably only need to define \"==\". - - \"isequal\" is the comparison function used by hash tables - (\"Dict\"). \"isequal(x,y)\" must imply that \"hash(x) == - hash(y)\". - - This typically means that if you define your own \"==\" function - then you must define a corresponding \"hash\" (and vice versa). - Collections typically implement \"isequal\" by calling \"isequal\" - recursively on all contents. - - Scalar types generally do not need to implement \"isequal\" - separate from \"==\", unless they represent floating-point numbers - amenable to a more efficient implementation than that provided as a - generic fallback (based on \"isnan\", \"signbit\", and \"==\"). - -"), - -("Base","isless","isless(x, y) - - Test whether \"x\" is less than \"y\", according to a canonical - total order. Values that are normally unordered, such as \"NaN\", - are ordered in an arbitrary but consistent fashion. This is the - default comparison used by \"sort\". Non-numeric types with a - canonical total order should implement this function. Numeric types - only need to implement it if they have special values such as - \"NaN\". - -"), - -("Base","ifelse","ifelse(condition::Bool, x, y) - - Return \"x\" if \"condition\" is true, otherwise return \"y\". This - differs from \"?\" or \"if\" in that it is an ordinary function, so - all the arguments are evaluated first. In some cases, using - \"ifelse\" instead of an \"if\" statement can eliminate the branch - in generated code and provide higher performance in tight loops. - -"), - -("Base","lexcmp","lexcmp(x, y) - - Compare \"x\" and \"y\" lexicographically and return -1, 0, or 1 - depending on whether \"x\" is less than, equal to, or greater than - \"y\", respectively. This function should be defined for - lexicographically comparable types, and \"lexless\" will call - \"lexcmp\" by default. - -"), - -("Base","lexless","lexless(x, y) - - Determine whether \"x\" is lexicographically less than \"y\". - -"), - -("Base","typeof","typeof(x) - - Get the concrete type of \"x\". - -"), - -("Base","tuple","tuple(xs...) - - Construct a tuple of the given objects. - -"), - -("Base","ntuple","ntuple(f::Function, n) - - Create a tuple of length \"n\", computing each element as \"f(i)\", - where \"i\" is the index of the element. - -"), - -("Base","object_id","object_id(x) - - Get a unique integer id for \"x\". \"object_id(x)==object_id(y)\" - if and only if \"is(x,y)\". - -"), - -("Base","hash","hash(x[, h]) - - Compute an integer hash code such that \"isequal(x,y)\" implies - \"hash(x)==hash(y)\". The optional second argument \"h\" is a hash - code to be mixed with the result. - - New types should implement the 2-argument form, typically by - calling the 2-argument \"hash\" method recursively in order to mix - hashes of the contents with each other (and with \"h\"). - Typically, any type that implements \"hash\" should also implement - its own \"==\" (hence \"isequal\") to guarantee the property - mentioned above. - -"), - -("Base","finalizer","finalizer(x, function) - - Register a function \"f(x)\" to be called when there are no - program-accessible references to \"x\". The behavior of this - function is unpredictable if \"x\" is of a bits type. - -"), - -("Base","finalize","finalize(x) - - Immediately run finalizers registered for object \"x\". - -"), - -("Base","copy","copy(x) - - Create a shallow copy of \"x\": the outer structure is copied, but - not all internal values. For example, copying an array produces a - new array with identically-same elements as the original. - -"), - -("Base","deepcopy","deepcopy(x) - - Create a deep copy of \"x\": everything is copied recursively, - resulting in a fully independent object. For example, deep-copying - an array produces a new array whose elements are deep copies of the - original elements. Calling *deepcopy* on an object should generally - have the same effect as serializing and then deserializing it. - - As a special case, functions can only be actually deep-copied if - they are anonymous, otherwise they are just copied. The difference - is only relevant in the case of closures, i.e. functions which may - contain hidden internal references. - - While it isn't normally necessary, user-defined types can override - the default \"deepcopy\" behavior by defining a specialized version - of the function \"deepcopy_internal(x::T, dict::ObjectIdDict)\" - (which shouldn't otherwise be used), where \"T\" is the type to be - specialized for, and \"dict\" keeps track of objects copied so far - within the recursion. Within the definition, \"deepcopy_internal\" - should be used in place of \"deepcopy\", and the \"dict\" variable - should be updated as appropriate before returning. - -"), - -("Base","isdefined","isdefined([object], index | symbol) - - Tests whether an assignable location is defined. The arguments can - be an array and index, a composite object and field name (as a - symbol), or a module and a symbol. With a single symbol argument, - tests whether a global variable with that name is defined in - \"current_module()\". - -"), - -("Base","convert","convert(T, x) - - Convert \"x\" to a value of type \"T\". - - If \"T\" is an \"Integer\" type, an \"InexactError\" will be raised - if \"x\" is not representable by \"T\", for example if \"x\" is not - integer-valued, or is outside the range supported by \"T\". - - julia> convert(Int, 3.0) - 3 - - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 - - If \"T\" is a \"FloatingPoint\" or \"Rational\" type, then it will - return the closest value to \"x\" representable by \"T\". - - julia> x = 1/3 - 0.3333333333333333 - - julia> convert(Float32, x) - 0.33333334f0 - - julia> convert(Rational{Int32}, x) - 1//3 - - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 - -"), - -("Base","promote","promote(xs...) - - Convert all arguments to their common promotion type (if any), and - return them all (as a tuple). - -"), - -("Base","oftype","oftype(x, y) - - Convert \"y\" to the type of \"x\" (\"convert(typeof(x), y)\"). - -"), - -("Base","widen","widen(type | x) - - If the argument is a type, return a \"larger\" type (for numeric - types, this will be a type with at least as much range and - precision as the argument, and usually more). Otherwise the - argument \"x\" is converted to \"widen(typeof(x))\". - - julia> widen(Int32) - Int64 - - julia> widen(1.5f0) - 1.5 - -"), - -("Base","identity","identity(x) - - The identity function. Returns its argument. - -"), - -("Base","super","super(T::DataType) - - Return the supertype of DataType T - -"), - -("Base","issubtype","issubtype(type1, type2) - - True if and only if all values of \"type1\" are also of \"type2\". - Can also be written using the \"<:\" infix operator as \"type1 <: - type2\". - -"), - -("Base","<:","<:(T1, T2) - - Subtype operator, equivalent to \"issubtype(T1,T2)\". - -"), - -("Base","subtypes","subtypes(T::DataType) - - Return a list of immediate subtypes of DataType T. Note that all - currently loaded subtypes are included, including those not visible - in the current module. - -"), - -("Base","typemin","typemin(type) - - The lowest value representable by the given (real) numeric type. - -"), - -("Base","typemax","typemax(type) - - The highest value representable by the given (real) numeric type. - -"), - -("Base","realmin","realmin(type) - - The smallest in absolute value non-subnormal value representable by - the given floating-point type - -"), - -("Base","realmax","realmax(type) - - The highest finite value representable by the given floating-point - type - -"), - -("Base","maxintfloat","maxintfloat(type) - - The largest integer losslessly representable by the given floating- - point type - -"), - -("Base","sizeof","sizeof(type) - - Size, in bytes, of the canonical binary representation of the given - type, if any. - -"), - -("Base","eps","eps([type]) - - The distance between 1.0 and the next larger representable - floating-point value of \"type\". Only floating-point types are - sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" - is returned. - -"), - -("Base","eps","eps(x) - - The distance between \"x\" and the next larger representable - floating-point value of the same type as \"x\". - -"), - -("Base","promote_type","promote_type(type1, type2) - - Determine a type big enough to hold values of each argument type - without loss, whenever possible. In some cases, where no type - exists to which both types can be promoted losslessly, some loss is - tolerated; for example, \"promote_type(Int64,Float64)\" returns - \"Float64\" even though strictly, not all \"Int64\" values can be - represented exactly as \"Float64\" values. - -"), - -("Base","promote_rule","promote_rule(type1, type2) - - Specifies what type should be used by \"promote\" when given values - of types \"type1\" and \"type2\". This function should not be - called directly, but should have definitions added to it for new - types as appropriate. - -"), - -("Base","getfield","getfield(value, name::Symbol) - - Extract a named field from a value of composite type. The syntax - \"a.b\" calls \"getfield(a, :b)\", and the syntax \"a.(b)\" calls - \"getfield(a, b)\". - -"), - -("Base","setfield!","setfield!(value, name::Symbol, x) - - Assign \"x\" to a named field in \"value\" of composite type. The - syntax \"a.b = c\" calls \"setfield!(a, :b, c)\", and the syntax - \"a.(b) = c\" calls \"setfield!(a, b, c)\". - -"), - -("Base","fieldoffsets","fieldoffsets(type) - - The byte offset of each field of a type relative to the data start. - For example, we could use it in the following manner to summarize - information about a struct type: - - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; - - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) - -"), - -("Base","fieldtype","fieldtype(type, name::Symbol | index::Int) - - Determine the declared type of a field (specified by name or index) - in a composite type. - -"), - -("Base","isimmutable","isimmutable(v) - - True if value \"v\" is immutable. See *Immutable Composite Types* - for a discussion of immutability. Note that this function works on - values, so if you give it a type, it will tell you that a value of - \"DataType\" is mutable. - -"), - -("Base","isbits","isbits(T) - - True if \"T\" is a \"plain data\" type, meaning it is immutable and - contains no references to other values. Typical examples are - numeric types such as \"UInt8\", \"Float64\", and - \"Complex{Float64}\". - - julia> isbits(Complex{Float64}) - true - - julia> isbits(Complex) - false - -"), - -("Base","isleaftype","isleaftype(T) - - Determine whether \"T\" is a concrete type that can have instances, - meaning its only subtypes are itself and \"None\" (but \"T\" itself - is not \"None\"). - -"), - -("Base","typejoin","typejoin(T, S) - - Compute a type that contains both \"T\" and \"S\". - -"), - -("Base","typeintersect","typeintersect(T, S) - - Compute a type that contains the intersection of \"T\" and \"S\". - Usually this will be the smallest such type or one close to it. - -"), - -("Base","Val{c}","Val{c}() - - Create a \"value type\" out of \"c\", which must be an \"isbits\" - value. The intent of this construct is to be able to dispatch on - constants, e.g., \"f(Val{false})\" allows you to dispatch directly - (at compile-time) to an implementation \"f(::Type{Val{false}})\", - without having to test the boolean value at runtime. - -"), - -("","@enum EnumName EnumValue1[=x] EnumValue2[=y]","@enum EnumName EnumValue1[=x] EnumValue2[=y] - - Create an \"Enum\" type with name \"EnumName\" and enum member - values of \"EnumValue1\" and \"EnumValue2\" with optional assigned - values of \"x\" and \"y\", respectively. \"EnumName\" can be used - just like other types and enum member values as regular values, - such as - - julia> @enum FRUIT apple=1 orange=2 kiwi=3 - - julia> f(x::FRUIT) = \"I'm a FRUIT with value: \$(Int(x))\" - f (generic function with 1 method) - - julia> f(apple) - \"I'm a FRUIT with value: 1\" - -"), - -("Base","instances","instances(T::Type) - - Return a collection of all instances of the given type, if - applicable. Mostly used for enumerated types (see \"@enum\"). - -"), - -("Base","method_exists","method_exists(f, Tuple type) -> Bool - - Determine whether the given generic function has a method matching - the given \"Tuple\" of argument types. - - julia> method_exists(length, Tuple{Array}) - true - -"), - -("Base","applicable","applicable(f, args...) -> Bool - - Determine whether the given generic function has a method - applicable to the given arguments. - - julia> function f(x, y) - x + y - end; - - julia> applicable(f, 1) - false - - julia> applicable(f, 1, 2) - true - -"), - -("Base","invoke","invoke(f, (types...), args...) - - Invoke a method for the given generic function matching the - specified types (as a tuple), on the specified arguments. The - arguments must be compatible with the specified types. This allows - invoking a method other than the most specific matching method, - which is useful when the behavior of a more general definition is - explicitly needed (often as part of the implementation of a more - specific method of the same function). - -"), - -("Base","|>","|>(x, f) - - Applies a function to the preceding argument. This allows for easy - function chaining. - - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 - -"), - -("Base","call","call(x, args...) - - If \"x\" is not a \"Function\", then \"x(args...)\" is equivalent - to \"call(x, args...)\". This means that function-like behavior - can be added to any type by defining new \"call\" methods. - -"), - -("Base","eval","eval([m::Module], expr::Expr) - - Evaluate an expression in the given module and return the result. - Every module (except those defined with \"baremodule\") has its own - 1-argument definition of \"eval\", which evaluates expressions in - that module. - -"), - -("Base","@eval","@eval() - - Evaluate an expression and return the value. - -"), - -("Base","evalfile","evalfile(path::AbstractString) - - Load the file using \"include\", evaluate all expressions, and - return the value of the last one. - -"), - -("Base","esc","esc(e::ANY) - - Only valid in the context of an Expr returned from a macro. - Prevents the macro hygiene pass from turning embedded variables - into gensym variables. See the *Macros* section of the - Metaprogramming chapter of the manual for more details and - examples. - -"), - -("Base","gensym","gensym([tag]) - - Generates a symbol which will not conflict with other variable - names. - -"), - -("Base","@gensym","@gensym() - - Generates a gensym symbol for a variable. For example, \"@gensym x - y\" is transformed into \"x = gensym(\"x\"); y = gensym(\"y\")\". - -"), - -("Base","parse","parse(str, start; greedy=true, raise=true) - - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If \"greedy\" is true (default), - \"parse\" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is - true (default), syntax errors other than incomplete expressions - will raise an error. If \"raise\" is false, \"parse\" will return - an expression that will raise an error upon evaluation. - -"), - -("Base","parse","parse(str; raise=true) - - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If \"raise\" is true (default), syntax errors will - raise an error; otherwise, \"parse\" will return an expression that - will raise an error upon evaluation. - -"), - -("Base","Nullable","Nullable(x) - - Wrap value \"x\" in an object of type \"Nullable\", which indicates - whether a value is present. \"Nullable(x)\" yields a non-empty - wrapper, and \"Nullable{T}()\" yields an empty instance of a - wrapper that might contain a value of type \"T\". - -"), - -("Base","get","get(x) - - Attempt to access the value of the \"Nullable\" object, \"x\". - Returns the value if it is present; otherwise, throws a - \"NullException\". - -"), - -("Base","get","get(x, y) - - Attempt to access the value of the \"Nullable{T}\" object, \"x\". - Returns the value if it is present; otherwise, returns \"convert(T, - y)\". - -"), - -("Base","isnull","isnull(x) - - Is the \"Nullable\" object \"x\" null, i.e. missing a value? - -"), - -("Base","run","run(command) - - Run a command object, constructed with backticks. Throws an error - if anything goes wrong, including the process exiting with a non- - zero status. - -"), - -("Base","spawn","spawn(command) - - Run a command object asynchronously, returning the resulting - \"Process\" object. - -"), - -("Base","DevNull","DevNull - - Used in a stream redirect to discard all data written to it. - Essentially equivalent to /dev/null on Unix or NUL on Windows. - Usage: \"run(`cat test.txt` |> DevNull)\" - -"), - -("Base","success","success(command) - - Run a command object, constructed with backticks, and tell whether - it was successful (exited with a code of 0). An exception is raised - if the process cannot be started. - -"), - -("Base","process_running","process_running(p::Process) - - Determine whether a process is currently running. - -"), - -("Base","process_exited","process_exited(p::Process) - - Determine whether a process has exited. - -"), - -("Base","kill","kill(p::Process, signum=SIGTERM) - - Send a signal to a process. The default is to terminate the - process. - -"), - -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) - - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. - -"), - -("Base","open","open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) - - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". - -"), - -("Base","Sys","Sys.set_process_title(title::AbstractString) - - Set the process title. No-op on some operating systems. (not - exported) - -"), - -("Base","Sys","Sys.get_process_title() - - Get the process title. On some systems, will always return empty - string. (not exported) - -"), - -("Base","readandwrite","readandwrite(command) - - Starts running a command asynchronously, and returns a tuple - (stdout,stdin,process) of the output stream and input stream of the - process, and the process object itself. - -"), - -("Base","ignorestatus","ignorestatus(command) - - Mark a command object so that running it will not throw an error if - the result code is non-zero. - -"), - -("Base","detach","detach(command) - - Mark a command object so that it will be run in a new process - group, allowing it to outlive the julia process, and not have - Ctrl-C interrupts passed to it. - -"), - -("Base","setenv","setenv(command, env; dir=working_dir) - - Set environment variables to use when running the given command. - \"env\" is either a dictionary mapping strings to strings, an array - of strings of the form \"\"var=val\"\", or zero or more - \"\"var\"=>val\" pair arguments. In order to modify (rather than - replace) the existing environment, create \"env\" by \"copy(ENV)\" - and then setting \"env[\"var\"]=val\" as desired, or use - \"withenv\". - - The \"dir\" keyword argument can be used to specify a working - directory for the command. - -"), - -("Base","withenv","withenv(f::Function, kv::Pair...) - - Execute \"f()\" in an environment that is temporarily modified (not - replaced as in \"setenv\") by zero or more \"\"var\"=>val\" - arguments \"kv\". \"withenv\" is generally used via the - \"withenv(kv...) do ... end\" syntax. A value of \"nothing\" can - be used to temporarily unset an environment variable (if it is - set). When \"withenv\" returns, the original environment has been - restored. - -"), - -("Base","pipe","pipe(from, to, ...) - - Create a pipeline from a data source to a destination. The source - and destination can be commands, I/O streams, strings, or results - of other \"pipe\" calls. At least one argument must be a command. - Strings refer to filenames. When called with more than two - arguments, they are chained together from left to right. For - example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". - This provides a more concise way to specify multi-stage pipelines. - - **Examples**: - * \"run(pipe(`ls`, `grep xyz`))\" - - * \"run(pipe(`ls`, \"out.txt\"))\" - - * \"run(pipe(\"out.txt\", `grep xyz`))\" - -"), - -("Base","pipe","pipe(command; stdin, stdout, stderr, append=false) - - Redirect I/O to or from the given \"command\". Keyword arguments - specify which of the command's streams should be redirected. - \"append\" controls whether file output appends to the file. This - is a more general version of the 2-argument \"pipe\" function. - \"pipe(from, to)\" is equivalent to \"pipe(from, stdout=to)\" when - \"from\" is a command, and to \"pipe(to, stdin=from)\" when - \"from\" is another kind of data source. - - **Examples**: - * \"run(pipe(`dothings`, stdout=\"out.txt\", - stderr=\"errs.txt\"))\" - - * \"run(pipe(`update`, stdout=\"log.txt\", append=true))\" - -"), - -("Base","gethostname","gethostname() -> AbstractString - - Get the local machine's host name. - -"), - -("Base","getipaddr","getipaddr() -> AbstractString - - Get the IP address of the local machine, as a string of the form - \"x.x.x.x\". - -"), - -("Base","getpid","getpid() -> Int32 - - Get julia's process ID. - -"), - -("Base","time","time() - - Get the system time in seconds since the epoch, with fairly high - (typically, microsecond) resolution. - -"), - -("Base","time_ns","time_ns() - - Get the time in nanoseconds. The time corresponding to 0 is - undefined, and wraps every 5.8 years. - -"), - -("Base","tic","tic() - - Set a timer to be read by the next call to \"toc()\" or \"toq()\". - The macro call \"@time expr\" can also be used to time evaluation. - -"), - -("Base","toc","toc() - - Print and return the time elapsed since the last \"tic()\". - -"), - -("Base","toq","toq() - - Return, but do not print, the time elapsed since the last - \"tic()\". - -"), - -("Base","@time","@time() - - A macro to execute an expression, printing the time it took to - execute, the number of allocations, and the total number of bytes - its execution caused to be allocated, before returning the value of - the expression. - -"), - -("Base","@timev","@timev() - - This is a verbose version of the \"@time\" macro, it first prints - the same information as \"@time\", then any non-zero memory - allocation counters, and then returns the value of the expression. - -"), - -("Base","@timed","@timed() - - A macro to execute an expression, and return the value of the - expression, elapsed time, total bytes allocated, garbage collection - time, and an object with various memory allocation counters. - -"), - -("Base","@elapsed","@elapsed() - - A macro to evaluate an expression, discarding the resulting value, - instead returning the number of seconds it took to execute as a - floating-point number. - -"), - -("Base","@allocated","@allocated() - - A macro to evaluate an expression, discarding the resulting value, - instead returning the total number of bytes allocated during - evaluation of the expression. Note: the expression is evaluated - inside a local function, instead of the current context, in order - to eliminate the effects of compilation, however, there still may - be some allocations due to JIT compilation. This also makes the - results inconsistent with the \"@time\" macros, which do not try to - adjust for the effects of compilation. - -"), - -("Base","EnvHash","EnvHash() -> EnvHash - - A singleton of this type provides a hash table interface to - environment variables. - -"), - -("Base","ENV","ENV - - Reference to the singleton \"EnvHash\", providing a dictionary - interface to system environment variables. - -"), - -("Base","@unix","@unix() - - Given \"@unix? a : b\", do \"a\" on Unix systems (including Linux - and OS X) and \"b\" elsewhere. See documentation for Handling - Platform Variations in the Calling C and Fortran Code section of - the manual. - -"), - -("Base","@osx","@osx() - - Given \"@osx? a : b\", do \"a\" on OS X and \"b\" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. - -"), - -("Base","@linux","@linux() - - Given \"@linux? a : b\", do \"a\" on Linux and \"b\" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. - -"), - -("Base","@windows","@windows() - - Given \"@windows? a : b\", do \"a\" on Windows and \"b\" elsewhere. - See documentation for Handling Platform Variations in the Calling C - and Fortran Code section of the manual. - -"), - -("Base","error","error(message::AbstractString) - - Raise an \"ErrorException\" with the given message - -"), - -("Base","throw","throw(e) - - Throw an object as an exception - -"), - -("Base","rethrow","rethrow([e]) - - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - \"catch\" block). - -"), - -("Base","backtrace","backtrace() - - Get a backtrace object for the current program point. - -"), - -("Base","catch_backtrace","catch_backtrace() - - Get the backtrace of the current exception, for use within - \"catch\" blocks. - -"), - -("Base","assert","assert(cond) - - Throw an \"AssertionError\" if \"cond\" is false. Also available as - the macro \"@assert expr\". - -"), - -("","@assert cond [text]","@assert cond [text] - - Throw an \"AssertionError\" if \"cond\" is false. Preferred syntax - for writing assertions. - -"), - -("Base","ArgumentError","ArgumentError(msg) - - The parameters to a function call do not match a valid signature. - -"), - -("Base","AssertionError","AssertionError([msg]) - - The asserted condition did not evalutate to \"true\". - -"), - -("Base","BoundsError","BoundsError([a][, i]) - - An indexing operation into an array, \"a\", tried to access an out- - of-bounds element, \"i\". - -"), - -("Base","DimensionMismatch","DimensionMismatch([msg]) - - The objects called do not have matching dimensionality. - -"), - -("Base","DivideError","DivideError() - - Integer division was attempted with a denominator value of 0. - -"), - -("Base","DomainError","DomainError() - - The arguments to a function or constructor are outside the valid - domain. - -"), - -("Base","EOFError","EOFError() - - No more data was available to read from a file or stream. - -"), - -("Base","ErrorException","ErrorException(msg) - - Generic error type. The error message, in the *.msg* field, may - provide more specific details. - -"), - -("Base","InexactError","InexactError() - - Type conversion cannot be done exactly. - -"), - -("Base","InterruptException","InterruptException() - - The process was stopped by a terminal interrupt (CTRL+C). - -"), - -("Base","KeyError","KeyError(key) - - An indexing operation into an \"Associative\" (\"Dict\") or \"Set\" - like object tried to access or delete a non-existent element. - -"), - -("Base","LoadError","LoadError(file::AbstractString, line::Int, error) - - An error occurred while *including*, *requiring*, or *using* a - file. The error specifics should be available in the *.error* - field. - -"), - -("Base","MethodError","MethodError(f, args) - - A method with the required type signature does not exist in the - given generic function. - -"), - -("Base","NullException","NullException() - - An attempted access to a \"Nullable\" with no defined value. - -"), - -("Base","OutOfMemoryError","OutOfMemoryError() - - An operation allocated too much memory for either the system or the - garbage collector to handle properly. - -"), - -("Base","ReadOnlyMemoryError","ReadOnlyMemoryError() - - An operation tried to write to memory that is read-only. - -"), - -("Base","OverflowError","OverflowError() - - The result of an expression is too large for the specified type and - will cause a wraparound. - -"), - -("Base","ParseError","ParseError(msg) - - The expression passed to the *parse* function could not be - interpreted as a valid Julia expression. - -"), - -("Base","ProcessExitedException","ProcessExitedException() - - After a client Julia process has exited, further attempts to - reference the dead child will throw this exception. - -"), - -("Base","StackOverflowError","StackOverflowError() - - The function call grew beyond the size of the call stack. This - usually happens when a call recurses infinitely. - -"), - -("Base","SystemError","SystemError(prefix::AbstractString[, errnum::Int32]) - - A system call failed with an error code (in the \"errno\" global - variable). - -"), - -("Base","TypeError","TypeError(func::Symbol, context::AbstractString, expected::Type, got) - - A type assertion failure, or calling an intrinsic function with an - incorrect argument type. - -"), - -("Base","UndefRefError","UndefRefError() - - The item or field is not defined for the given object. - -"), - -("Base","UndefVarError","UndefVarError(var::Symbol) - - A symbol in the current scope is not defined. - -"), - -("Base","Timer","Timer(callback::Function, delay, repeat=0) - - Create a timer to call the given callback function. The callback is - passed one argument, the timer object itself. The callback will be - invoked after the specified initial delay, and then repeating with - the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is - only triggered once. Times are in seconds. A timer is stopped and - has its resources freed by calling \"close\" on it. - -"), - -("Base","Timer","Timer(delay, repeat=0) - - Create a timer that wakes up tasks waiting for it (by calling - \"wait\" on the timer object) at a specified interval. - -"), - -("Base","module_name","module_name(m::Module) -> Symbol - - Get the name of a module as a symbol. - -"), - -("Base","module_parent","module_parent(m::Module) -> Module - - Get a module's enclosing module. \"Main\" is its own parent. - -"), - -("Base","current_module","current_module() -> Module - - Get the *dynamically* current module, which is the module code is - currently being read from. In general, this is not the same as the - module containing the call to this function. - -"), - -("Base","fullname","fullname(m::Module) - - Get the fully-qualified name of a module as a tuple of symbols. For - example, \"fullname(Base.Pkg)\" gives \"(:Base,:Pkg)\", and - \"fullname(Main)\" gives \"()\". - -"), - -("Base","names","names(x::Module[, all=false[, imported=false]]) - - Get an array of the names exported by a module, with optionally - more module globals according to the additional parameters. - -"), - -("Base","nfields","nfields(x::DataType) -> Int - - Get the number of fields of a data type. - -"), - -("Base","fieldnames","fieldnames(x::DataType) - - Get an array of the fields of a data type. - -"), - -("Base","isconst","isconst([m::Module], s::Symbol) -> Bool - - Determine whether a global is declared \"const\" in a given module. - The default module argument is \"current_module()\". - -"), - -("Base","isgeneric","isgeneric(f::Function) -> Bool - - Determine whether a function is generic. - -"), - -("Base","function_name","function_name(f::Function) -> Symbol - - Get the name of a generic function as a symbol, or \":anonymous\". - -"), - -("Base","function_module","function_module(f::Function, types) -> Module - - Determine the module containing a given definition of a generic - function. - -"), - -("Base","functionloc","functionloc(f::Function, types) - - Returns a tuple \"(filename,line)\" giving the location of a method - definition. - -"), - -("Base","functionloc","functionloc(m::Method) - - Returns a tuple \"(filename,line)\" giving the location of a method - definition. - -"), - -("Base","gc","gc() - - Perform garbage collection. This should not generally be used. - -"), - -("Base","gc_enable","gc_enable(on::Bool) - - Control whether garbage collection is enabled using a boolean - argument (true for enabled, false for disabled). Returns previous - GC state. Disabling garbage collection should be used only with - extreme caution, as it can cause memory use to grow without bound. - -"), - -("Base","macroexpand","macroexpand(x) - - Takes the expression x and returns an equivalent expression with - all macros removed (expanded). - -"), - -("Base","expand","expand(x) - - Takes the expression x and returns an equivalent expression in - lowered form - -"), - -("Base","code_lowered","code_lowered(f, types) - - Returns an array of lowered ASTs for the methods matching the given - generic function and type signature. - -"), - -("Base","@code_lowered","@code_lowered() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_lowered()\" on the resulting expression - -"), - -("Base","code_typed","code_typed(f, types; optimize=true) - - Returns an array of lowered and type-inferred ASTs for the methods - matching the given generic function and type signature. The keyword - argument \"optimize\" controls whether additional optimizations, - such as inlining, are also applied. - -"), - -("Base","@code_typed","@code_typed() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_typed()\" on the resulting expression - -"), - -("Base","code_warntype","code_warntype(f, types) - - Displays lowered and type-inferred ASTs for the methods matching - the given generic function and type signature. The ASTs are - annotated in such a way as to cause \"non-leaf\" types to be - emphasized (if color is available, displayed in red). This serves - as a warning of potential type instability. Not all non-leaf types - are particularly problematic for performance, so the results need - to be used judiciously. See *@code_warntype* for more information. - -"), - -("Base","@code_warntype","@code_warntype() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_warntype()\" on the resulting expression - -"), - -("Base","code_llvm","code_llvm(f, types) - - Prints the LLVM bitcodes generated for running the method matching - the given generic function and type signature to \"STDOUT\". - - All metadata and dbg.* calls are removed from the printed bitcode. - Use code_llvm_raw for the full IR. - -"), - -("Base","@code_llvm","@code_llvm() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_llvm()\" on the resulting expression - -"), - -("Base","code_native","code_native(f, types) - - Prints the native assembly instructions generated for running the - method matching the given generic function and type signature to - STDOUT. - -"), - -("Base","@code_native","@code_native() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_native()\" on the resulting expression - -"), - -("Base","precompile","precompile(f, args::Tuple{Vararg{Any}}) - - Compile the given function \"f\" for the argument tuple (of types) - \"args\", but do not execute it. - -"), - -("Base","ccall","ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - - Call function in C-exported shared library, specified by - \"(function name, library)\" tuple, where each component is an - AbstractString or :Symbol. - - Note that the argument type tuple must be a literal tuple, and not - a tuple-valued variable or expression. Alternatively, ccall may - also be used to call a function pointer, such as one returned by - dlsym. - - Each \"ArgumentValue\" to the \"ccall\" will be converted to the - corresponding \"ArgumentType\", by automatic insertion of calls to - \"unsafe_convert(ArgumentType, cconvert(ArgumentType, - ArgumentValue))\". (see also the documentation for each of these - functions for further details). In most cases, this simply results - in a call to \"convert(ArgumentType, ArgumentValue)\" - -"), - -("Base","cglobal","cglobal((symbol, library)[, type=Void]) - - Obtain a pointer to a global variable in a C-exported shared - library, specified exactly as in \"ccall\". Returns a - \"Ptr{Type}\", defaulting to \"Ptr{Void}\" if no Type argument is - supplied. The values can be read or written by \"unsafe_load\" or - \"unsafe_store!\", respectively. - -"), - -("Base","cfunction","cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - - Generate C-callable function pointer from Julia function. Type - annotation of the return value in the callback function is a must - for situations where Julia cannot infer the return type - automatically. - - For example: - - function foo() - # body - - retval::Float64 - end - - bar = cfunction(foo, Float64, ()) - -"), - -("Base","unsafe_convert","unsafe_convert(T, x) - - Convert \"x\" to a value of type \"T\" - - In cases where \"convert\" would need to take a Julia object and - turn it into a \"Ptr\", this function should be used to define and - perform that conversion. - - Be careful to ensure that a julia reference to \"x\" exists as long - as the result of this function will be used. Accordingly, the - argument \"x\" to this function should never be an expression, only - a variable name or field reference. For example, \"x=a.b.c\" is - acceptable, but \"x=[a,b,c]\" is not. - - The \"unsafe\" prefix on this function indicates that using the - result of this function after the \"x\" argument to this function - is no longer accessible to the program may cause undefined - behavior, including program corruption or segfaults, at any later - time. - -"), - -("Base","cconvert","cconvert(T, x) - - Convert \"x\" to a value of type \"T\", typically by calling - \"convert(T,x)\" - - In cases where \"x\" cannot be safely converted to \"T\", unlike - \"convert\", \"cconvert\" may return an object of a type different - from \"T\", which however is suitable for \"unsafe_convert\" to - handle. - - Neither \"convert\" nor \"cconvert\" should take a Julia object and - turn it into a \"Ptr\". - -"), - -("Base","unsafe_load","unsafe_load(p::Ptr{T}, i::Integer) - - Load a value of type \"T\" from the address of the ith element - (1-indexed) starting at \"p\". This is equivalent to the C - expression \"p[i-1]\". - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointer \"p\" to ensure that it is valid. - Incorrect usage may segfault your program or return garbage - answers, in the same manner as C. - -"), - -("Base","unsafe_store!","unsafe_store!(p::Ptr{T}, x, i::Integer) - - Store a value of type \"T\" to the address of the ith element - (1-indexed) starting at \"p\". This is equivalent to the C - expression \"p[i-1] = x\". - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointer \"p\" to ensure that it is valid. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - -"), - -("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - - Copy \"N\" elements from a source pointer to a destination, with no - checking. The size of an element is determined by the type of the - pointers. - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointers \"dest\" and \"src\" to ensure that - they are valid. Incorrect usage may corrupt or segfault your - program, in the same manner as C. - -"), - -("Base","unsafe_copy!","unsafe_copy!(dest::Array, do, src::Array, so, N) - - Copy \"N\" elements from a source array to a destination, starting - at offset \"so\" in the source and \"do\" in the destination - (1-indexed). - - The \"unsafe\" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - -"), - -("Base","copy!","copy!(dest, src) - - Copy all elements from collection \"src\" to array \"dest\". - Returns \"dest\". - -"), - -("Base","copy!","copy!(dest, do, src, so, N) - - Copy \"N\" elements from collection \"src\" starting at offset - \"so\", to array \"dest\" starting at offset \"do\". Returns - \"dest\". - -"), - -("Base","pointer","pointer(array[, index]) - - Get the native address of an array or string element. Be careful to - ensure that a julia reference to \"a\" exists as long as this - pointer will be used. This function is \"unsafe\" like - \"unsafe_convert\". - - Calling \"Ref(array[, index])\" is generally preferable to this - function. - -"), - -("Base","pointer_to_array","pointer_to_array(pointer, dims[, take_ownership::Bool]) - - Wrap a native pointer as a Julia Array object. The pointer element - type determines the array element type. \"own\" optionally - specifies whether Julia should take ownership of the memory, - calling \"free\" on the pointer when the array is no longer - referenced. - -"), - -("Base","pointer_from_objref","pointer_from_objref(object_instance) - - Get the memory address of a Julia object as a \"Ptr\". The - existence of the resulting \"Ptr\" will not protect the object from - garbage collection, so you must ensure that the object remains - referenced for the whole time that the \"Ptr\" will be used. - -"), - -("Base","unsafe_pointer_to_objref","unsafe_pointer_to_objref(p::Ptr) - - Convert a \"Ptr\" to an object reference. Assumes the pointer - refers to a valid heap-allocated Julia object. If this is not the - case, undefined behavior results, hence this function is considered - \"unsafe\" and should be used with care. - -"), - -("Base","disable_sigint","disable_sigint(f::Function) - - Disable Ctrl-C handler during execution of a function, for calling - external code that is not interrupt safe. Intended to be called - using \"do\" block syntax as follows: - - disable_sigint() do - # interrupt-unsafe code - ... - end - -"), - -("Base","reenable_sigint","reenable_sigint(f::Function) - - Re-enable Ctrl-C handler during execution of a function. - Temporarily reverses the effect of \"disable_sigint\". - -"), - -("Base","systemerror","systemerror(sysfunc, iftrue) - - Raises a \"SystemError\" for \"errno\" with the descriptive string - \"sysfunc\" if \"bool\" is true - -"), - -("Base","Ptr{T}","Ptr{T} - - A memory address referring to data of type \"T\". However, there is - no guarantee that the memory is actually valid, or that it actually - represents data of the specified type. - -"), - -("Base","Ref{T}","Ref{T} - - An object that safely references data of type \"T\". This type is - guaranteed to point to valid, Julia-allocated memory of the correct - type. The underlying data is protected from freeing by the garbage - collector as long as the \"Ref\" itself is referenced. - - When passed as a \"ccall\" argument (either as a \"Ptr\" or \"Ref\" - type), a \"Ref\" object will be converted to a native pointer to - the data it references. - - There is no invalid (NULL) \"Ref\". - -"), - -("Base","Cchar","Cchar - - Equivalent to the native \"char\" c-type - -"), - -("Base","Cuchar","Cuchar - - Equivalent to the native \"unsigned char\" c-type (UInt8) - -"), - -("Base","Cshort","Cshort - - Equivalent to the native \"signed short\" c-type (Int16) - -"), - -("Base","Cushort","Cushort - - Equivalent to the native \"unsigned short\" c-type (UInt16) - -"), - -("Base","Cint","Cint - - Equivalent to the native \"signed int\" c-type (Int32) - -"), - -("Base","Cuint","Cuint - - Equivalent to the native \"unsigned int\" c-type (UInt32) - -"), - -("Base","Clong","Clong - - Equivalent to the native \"signed long\" c-type - -"), - -("Base","Culong","Culong - - Equivalent to the native \"unsigned long\" c-type - -"), - -("Base","Clonglong","Clonglong - - Equivalent to the native \"signed long long\" c-type (Int64) - -"), - -("Base","Culonglong","Culonglong - - Equivalent to the native \"unsigned long long\" c-type (UInt64) - -"), - -("Base","Cintmax_t","Cintmax_t - - Equivalent to the native \"intmax_t\" c-type (Int64) - -"), - -("Base","Cuintmax_t","Cuintmax_t - - Equivalent to the native \"uintmax_t\" c-type (UInt64) - -"), - -("Base","Csize_t","Csize_t - - Equivalent to the native \"size_t\" c-type (UInt) - -"), - -("Base","Cssize_t","Cssize_t - - Equivalent to the native \"ssize_t\" c-type - -"), - -("Base","Cptrdiff_t","Cptrdiff_t - - Equivalent to the native \"ptrdiff_t\" c-type (Int) - -"), - -("Base","Coff_t","Coff_t - - Equivalent to the native \"off_t\" c-type - -"), - -("Base","Cwchar_t","Cwchar_t - - Equivalent to the native \"wchar_t\" c-type (Int32) - -"), - -("Base","Cfloat","Cfloat - - Equivalent to the native \"float\" c-type (Float32) - -"), - -("Base","Cdouble","Cdouble - - Equivalent to the native \"double\" c-type (Float64) - -"), - -("Base","start","start(iter) -> state - - Get initial iteration state for an iterable object - -"), - -("Base","done","done(iter, state) -> Bool - - Test whether we are done iterating - -"), - -("Base","next","next(iter, state) -> item, state - - For a given iterable object and iteration state, return the current - item and the next iteration state - -"), - -("Base","zip","zip(iters...) - - For a set of iterable objects, returns an iterable of tuples, where - the \"i\"th tuple contains the \"i\"th component of each input - iterable. - - Note that \"zip()\" is its own inverse: - \"collect(zip(zip(a...)...)) == collect(a)\". - -"), - -("Base","enumerate","enumerate(iter) - - An iterator that yields \"(i, x)\" where \"i\" is an index starting - at 1, and \"x\" is the \"i\"th value from the given iterator. It's - useful when you need not only the values \"x\" over which you are - iterating, but also the index \"i\" of the iterations. - - julia> a = [\"a\", \"b\", \"c\"]; - - julia> for (index, value) in enumerate(a) - println(\"\$index \$value\") - end - 1 a - 2 b - 3 c - -"), - -("Base","rest","rest(iter, state) - - An iterator that yields the same elements as \"iter\", but starting - at the given \"state\". - -"), - -("Base","countfrom","countfrom(start=1, step=1) - - An iterator that counts forever, starting at \"start\" and - incrementing by \"step\". - -"), - -("Base","take","take(iter, n) - - An iterator that generates at most the first \"n\" elements of - \"iter\". - -"), - -("Base","drop","drop(iter, n) - - An iterator that generates all but the first \"n\" elements of - \"iter\". - -"), - -("Base","cycle","cycle(iter) - - An iterator that cycles through \"iter\" forever. - -"), - -("Base","repeated","repeated(x[, n::Int]) - - An iterator that generates the value \"x\" forever. If \"n\" is - specified, generates \"x\" that many times (equivalent to - \"take(repeated(x), n)\"). - -"), - -("Base","isempty","isempty(collection) -> Bool - - Determine whether a collection is empty (has no elements). - - julia> isempty([]) - true - - julia> isempty([1 2 3]) - false - -"), - -("Base","empty!","empty!(collection) -> collection - - Remove all elements from a \"collection\". - -"), - -("Base","length","length(collection) -> Integer - - For ordered, indexable collections, the maximum index \"i\" for - which \"getindex(collection, i)\" is valid. For unordered - collections, the number of elements. - -"), - -("Base","endof","endof(collection) -> Integer - - Returns the last index of the collection. - - julia> endof([1,2,4]) - 3 - -"), - -("Base","in","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)\". - -"), - -("Base","eltype","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 \"(key,value)\" tuple type. 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. - -"), - -("Base","indexin","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\". - -"), - -("Base","findin","findin(a, b) - - Returns the indices of elements in collection \"a\" that appear in - collection \"b\" - -"), - -("Base","unique","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\". - -"), - -("Base","reduce","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. - -"), - -("Base","reduce","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\". - -"), - -("Base","foldl","foldl(op, v0, itr) - - Like \"reduce()\", but with guaranteed left associativity. \"v0\" - will be used exactly once. - -"), - -("Base","foldl","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)\"). - -"), - -("Base","foldr","foldr(op, v0, itr) - - Like \"reduce()\", but with guaranteed right associativity. \"v0\" - will be used exactly once. - -"), - -("Base","foldr","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)\"). - -"), - -("Base","maximum","maximum(itr) - - Returns the largest element in a collection. - -"), - -("Base","maximum","maximum(A, dims) - - Compute the maximum value of an array over the given dimensions. - -"), - -("Base","maximum!","maximum!(r, A) - - Compute the maximum value of \"A\" over the singleton dimensions of - \"r\", and write results to \"r\". - -"), - -("Base","minimum","minimum(itr) - - Returns the smallest element in a collection. - -"), - -("Base","minimum","minimum(A, dims) - - Compute the minimum value of an array over the given dimensions. - -"), - -("Base","minimum!","minimum!(r, A) - - Compute the minimum value of \"A\" over the singleton dimensions of - \"r\", and write results to \"r\". - -"), - -("Base","extrema","extrema(itr) - - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. - -"), - -("Base","indmax","indmax(itr) -> Integer - - Returns the index of the maximum element in a collection. - -"), - -("Base","indmin","indmin(itr) -> Integer - - Returns the index of the minimum element in a collection. - -"), - -("Base","findmax","findmax(itr) -> (x, index) - - Returns the maximum element and its index. - -"), - -("Base","findmax","findmax(A, dims) -> (maxval, index) - - For an array input, returns the value and index of the maximum over - the given dimensions. - -"), - -("Base","findmin","findmin(itr) -> (x, index) - - Returns the minimum element and its index. - -"), - -("Base","findmin","findmin(A, dims) -> (minval, index) - - For an array input, returns the value and index of the minimum over - the given dimensions. - -"), - -("Base","maxabs","maxabs(itr) - - Compute the maximum absolute value of a collection of values. - -"), - -("Base","maxabs","maxabs(A, dims) - - Compute the maximum absolute values over given dimensions. - -"), - -("Base","maxabs!","maxabs!(r, A) - - Compute the maximum absolute values over the singleton dimensions - of \"r\", and write values to \"r\". - -"), - -("Base","minabs","minabs(itr) - - Compute the minimum absolute value of a collection of values. - -"), - -("Base","minabs","minabs(A, dims) - - Compute the minimum absolute values over given dimensions. - -"), - -("Base","minabs!","minabs!(r, A) - - Compute the minimum absolute values over the singleton dimensions - of \"r\", and write values to \"r\". - -"), - -("Base","sum","sum(itr) - - Returns the sum of all elements in a collection. - -"), - -("Base","sum","sum(A, dims) - - Sum elements of an array over the given dimensions. - -"), - -("Base","sum!","sum!(r, A) - - Sum elements of \"A\" over the singleton dimensions of \"r\", and - write results to \"r\". - -"), - -("Base","sum","sum(f, itr) - - Sum the results of calling function \"f\" on each element of - \"itr\". - -"), - -("Base","sumabs","sumabs(itr) - - Sum absolute values of all elements in a collection. This is - equivalent to *sum(abs(itr))* but faster. - -"), - -("Base","sumabs","sumabs(A, dims) - - Sum absolute values of elements of an array over the given - dimensions. - -"), - -("Base","sumabs!","sumabs!(r, A) - - Sum absolute values of elements of \"A\" over the singleton - dimensions of \"r\", and write results to \"r\". - -"), - -("Base","sumabs2","sumabs2(itr) - - Sum squared absolute values of all elements in a collection. This - is equivalent to *sum(abs2(itr))* but faster. - -"), - -("Base","sumabs2","sumabs2(A, dims) - - Sum squared absolute values of elements of an array over the given - dimensions. - -"), - -("Base","sumabs2!","sumabs2!(r, A) - - Sum squared absolute values of elements of \"A\" over the singleton - dimensions of \"r\", and write results to \"r\". - -"), - -("Base","prod","prod(itr) - - Returns the product of all elements of a collection. - -"), - -("Base","prod","prod(A, dims) - - Multiply elements of an array over the given dimensions. - -"), - -("Base","prod!","prod!(r, A) - - Multiply elements of \"A\" over the singleton dimensions of \"r\", - and write results to \"r\". - -"), - -("Base","any","any(itr) -> Bool - - Test whether any elements of a boolean collection are true. - -"), - -("Base","any","any(A, dims) - - Test whether any values along the given dimensions of an array are - true. - -"), - -("Base","any!","any!(r, A) - - Test whether any values in \"A\" along the singleton dimensions of - \"r\" are true, and write results to \"r\". - -"), - -("Base","all","all(itr) -> Bool - - Test whether all elements of a boolean collection are true. - -"), - -("Base","all","all(A, dims) - - Test whether all values along the given dimensions of an array are - true. - -"), - -("Base","all!","all!(r, A) - - Test whether all values in \"A\" along the singleton dimensions of - \"r\" are true, and write results to \"r\". - -"), - -("Base","count","count(p, itr) -> Integer - - Count the number of elements in \"itr\" for which predicate \"p\" - returns true. - -"), - -("Base","any","any(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for any elements of - \"itr\". - -"), - -("Base","all","all(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for all elements of - \"itr\". - - julia> all(i->(4<=i<=6), [4,5,6]) - true - -"), - -("Base","map","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 - -"), - -("Base","map!","map!(function, collection) - - In-place version of \"map()\". - -"), - -("Base","map!","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. - -"), - -("Base","mapreduce","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","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","mapfoldl(f, op, v0, itr) - - Like \"mapreduce()\", but with guaranteed left associativity. - \"v0\" will be used exactly once. - -"), - -("Base","mapfoldl","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","mapfoldr(f, op, v0, itr) - - Like \"mapreduce()\", but with guaranteed right associativity. - \"v0\" will be used exactly once. - -"), - -("Base","mapfoldr","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","first(coll) - - Get the first element of an iterable collection. Returns the start - point of a \"Range\" even if it is empty. - -"), - -("Base","last","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. - -"), - -("Base","step","step(r) - - Get the step size of a \"Range\" object. - -"), - -("Base","collect","collect(collection) - - Return an array of all items in a collection. For associative - collections, returns (key, value) tuples. - -"), - -("Base","collect","collect(element_type, collection) - - Return an array of type \"Array{element_type,1}\" of all items in a - collection. - -"), - -("Base","issubset","issubset(a, b) -⊆(A, S) -> Bool -⊈(A, S) -> Bool -⊊(A, S) -> Bool - - Determine whether every element of \"a\" is also in \"b\", using - \"in()\". - -"), - -("Base","filter","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). - -"), - -("Base","filter!","filter!(function, collection) - - Update \"collection\", removing elements for which \"function\" is - false. For associative collections, the function is passed two - arguments (key and value). - -"), - -("Base","getindex","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, ...)\". - -"), - -("Base","setindex!","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, ...)\". - -"), - -("Base","Dict","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{ASCIIString,Int64} with 2 entries: - \"B\" => 2 - \"A\" => 1 - - Alternatively, a sequence of pair arguments may be passed. - - julia> Dict(\"A\"=>1, \"B\"=>2) - Dict{ASCIIString,Int64} with 2 entries: - \"B\" => 2 - \"A\" => 1 - -"), - -("Base","haskey","haskey(collection, key) -> Bool - - Determine whether a collection has a mapping for a given key. - -"), - -("Base","get","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. - -"), - -("Base","get","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 - -"), - -("Base","get!","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\". - -"), - -("Base","get!","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 - -"), - -("Base","getkey","getkey(collection, key, default) - - Return the key matching argument \"key\" if one exists in - \"collection\", otherwise return \"default\". - -"), - -("Base","delete!","delete!(collection, key) - - Delete the mapping for the given key in a collection, and return - the collection. - -"), - -("Base","pop!","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. - -"), - -("Base","keys","keys(collection) - - Return an iterator over all keys in a collection. - \"collect(keys(d))\" returns an array of keys. - -"), - -("Base","values","values(collection) - - Return an iterator over all values in a collection. - \"collect(values(d))\" returns an array of values. - -"), - -("Base","merge","merge(collection, others...) - - 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. - - julia> a = Dict(\"foo\" => 0.0, \"bar\" => 42.0) - Dict{ASCIIString,Float64} with 2 entries: - \"bar\" => 42.0 - \"foo\" => 0.0 - - julia> b = Dict(utf8(\"baz\") => 17, utf8(\"qux\") => 4711) - Dict{UTF8String,Int64} with 2 entries: - \"baz\" => 17 - \"qux\" => 4711 - - julia> merge(a, b) - Dict{UTF8String,Float64} with 4 entries: - \"qux\" => 4711.0 - \"bar\" => 42.0 - \"baz\" => 17.0 - \"foo\" => 0.0 - -"), - -("Base","merge!","merge!(collection, others...) - - Update collection with pairs from the other collections - -"), - -("Base","sizehint!","sizehint!(s, n) - - Suggest that collection \"s\" reserve capacity for at least \"n\" - elements. This can improve performance. - -"), - -("Base","Set","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","IntSet([itr]) - - Construct a sorted set of the integers generated by the given - iterable object, or an empty set. Implemented as a bit string, and - therefore designed for dense integer sets. Only non-negative - integers can be stored. If the set will be sparse (for example - holding a single very large integer), use \"Set\" instead. - -"), - -("Base","union","union(s1, s2...) -∪(s1, s2) - - Construct the union of two or more sets. Maintains order with - arrays. - -"), - -("Base","union!","union!(s, iterable) - - Union each element of \"iterable\" into set \"s\" in-place. - -"), - -("Base","intersect","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. - -"), - -("Base","setdiff","setdiff(s1, s2) - - Construct the set of elements in \"s1\" but not \"s2\". 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. - -"), - -("Base","setdiff!","setdiff!(s, iterable) - - Remove each element of \"iterable\" from set \"s\" in-place. - -"), - -("Base","symdiff","symdiff(s1, s2...) - - Construct the symmetric difference of elements in the passed in - sets or arrays. Maintains order with arrays. - -"), - -("Base","symdiff!","symdiff!(s, n) - - The set \"s\" is destructively modified to toggle the inclusion of - integer \"n\". - -"), - -("Base","symdiff!","symdiff!(s, itr) - - For each element in \"itr\", destructively toggle its inclusion in - set \"s\". - -"), - -("Base","symdiff!","symdiff!(s1, s2) - - Construct the symmetric difference of sets \"s1\" and \"s2\", - storing the result in \"s1\". - -"), - -("Base","complement","complement(s) - - Returns the set-complement of \"IntSet\" \"s\". - -"), - -("Base","complement!","complement!(s) - - Mutates \"IntSet\" \"s\" into its set-complement. - -"), - -("Base","intersect!","intersect!(s1, s2) - - 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","issubset(A, S) -> Bool -⊆(A, S) -> Bool - - True if A is a subset of or equal to S. - -"), - -("Base","push!","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])\". - -"), - -("Base","pop!","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 - -"), - -("Base","unshift!","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 - -"), - -("Base","shift!","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 - -"), - -("Base","insert!","insert!(collection, index, item) - - Insert an \"item\" into \"collection\" at the given \"index\". - \"index\" is the index of \"item\" in the resulting \"collection\". - - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 - -"), - -("Base","deleteat!","deleteat!(collection, index) - - Remove the item at the given \"index\" and return the modified - \"collection\". 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 - -"), - -("Base","deleteat!","deleteat!(collection, itr) - - Remove the items at the indices given by \"itr\", and return the - modified \"collection\". Subsequent items are shifted to fill the - resulting gap. \"itr\" must be sorted and unique. - - 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], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 - -"), - -("Base","splice!","splice!(collection, index[, replacement]) -> item - - Remove the item at the given index, and return the removed item. - Subsequent items are shifted down 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)\". - -"), - -("Base","splice!","splice!(collection, range[, replacement]) -> items - - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down 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 - -"), - -("Base","resize!","resize!(collection, n) -> collection - - Resize \"collection\" 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 - -"), - -("Base","append!","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)\". - -"), - -("Base","prepend!","prepend!(collection, items) -> collection - - Insert the elements of \"items\" to the beginning of - \"collection\". - - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 - -"), - -("Base.Collections","PriorityQueue","PriorityQueue(K, V[, ord]) - - Construct a new \"PriorityQueue\", with keys of type \"K\" and - values/priorites of type \"V\". If an order is not given, the - priority queue is min-ordered using the default comparison for - \"V\". - -"), - -("Base.Collections","enqueue!","enqueue!(pq, k, v) - - Insert the a key \"k\" into a priority queue \"pq\" with priority - \"v\". - -"), - -("Base.Collections","dequeue!","dequeue!(pq) - - Remove and return the lowest priority key from a priority queue. - -"), - -("Base.Collections","peek","peek(pq) - - Return the lowest priority key from a priority queue without - removing that key from the queue. - -"), - -("Base.Collections","heapify","heapify(v[, ord]) - - Return a new vector in binary heap order, optionally using the - given ordering. - -"), - -("Base.Collections","heapify!","heapify!(v[, ord]) - - In-place \"heapify()\". - -"), - -("Base.Collections","isheap","isheap(v[, ord]) - - Return true iff an array is heap-ordered according to the given - order. - -"), - -("Base.Collections","heappush!","heappush!(v, x[, ord]) - - Given a binary heap-ordered array, push a new element \"x\", - preserving the heap property. For efficiency, this function does - not check that the array is indeed heap-ordered. - -"), - -("Base.Collections","heappop!","heappop!(v[, ord]) - - Given a binary heap-ordered array, remove and return the lowest - ordered element. For efficiency, this function does not check that - the array is indeed heap-ordered. - -"), - -("Base","nothing","nothing - - The singleton instance of type \"Void\", used by convention when - there is no value to return (as in a C \"void\" function). Can be - converted to an empty \"Nullable\" value. - -"), - -("Base","OS_NAME","OS_NAME - - A symbol representing the name of the operating system. Possible - values are \":Linux\", \":Darwin\" (OS X), or \":Windows\". - -"), - -("Base","ARGS","ARGS - - An array of the command line arguments passed to Julia, as strings. - -"), - -("Base","C_NULL","C_NULL - - The C null pointer constant, sometimes used when calling external - code. - -"), - -("Base","CPU_CORES","CPU_CORES - - The number of CPU cores in the system. - -"), - -("Base","WORD_SIZE","WORD_SIZE - - Standard word size on the current machine, in bits. - -"), - -("Base","VERSION","VERSION - - An object describing which version of Julia is in use. - -"), - -("Base","LOAD_PATH","LOAD_PATH - - An array of paths (as strings) where the \"require\" function looks - for code. - -"), - -("Base","JULIA_HOME","JULIA_HOME - - A string containing the full path to the directory containing the - \"julia\" executable. - -"), - -("Base","ANY","ANY - - Equivalent to \"Any\" for dispatch purposes, but signals the - compiler to skip code generation specialization for that field - -"), - -("Dates","Period","Period - -"), - -("Dates","Year","Year - -"), - -("Dates","Month","Month - -"), - -("Dates","Week","Week - -"), - -("Dates","Day","Day - -"), - -("Dates","Hour","Hour - -"), - -("Dates","Minute","Minute - -"), - -("Dates","Second","Second - -"), - -("Dates","Millisecond","Millisecond - - \"Period\" types represent discrete, human representations of time. - -"), - -("Dates","Instant","Instant - - \"Instant\" types represent integer-based, machine representations - of time as continuous timelines starting from an epoch. - -"), - -("Dates","UTInstant{T}","UTInstant{T} - - The \"UTInstant\" represents a machine timeline based on *UT* time - (1 day = one revolution of the earth). The \"{T}\" is a \"Period\" - parameter that indicates the resolution or precision of the - instant. - -"), - -("Dates","TimeType","TimeType - - \"TimeType\" types wrap \"Instant\" machine instances to provide - human representations of the machine instant. - -"), - -("Dates","DateTime","DateTime - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - -"), - -("Dates","Date","Date - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - -"), - -("Dates","DateTime","DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - -"), - -("Dates","DateTime","DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - -"), - -("Dates","DateTime","DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - -"), - -("Dates","DateTime","DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - -"), - -("Dates","DateTime","DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +-----------------+-----------+-----------------------------------------------------------------+ - | Code | Matches | Comment | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"y\\\" | 1996, 96 | Returns year of 1996, 0096 | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"m\\\" | 1, 01 | Matches 1 or 2-digit months | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"u\\\" | Jan | Matches abbreviated months according to the \\\"locale\\\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"U\\\" | January | Matches full month names according to the \\\"locale\\\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"d\\\" | 1, 01 | Matches 1 or 2-digit days | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"H\\\" | 00 | Matches hours | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"M\\\" | 00 | Matches minutes | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"S\\\" | 00 | Matches seconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"s\\\" | .500 | Matches milliseconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"e\\\" | Mon, Tues | Matches abbreviated days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"E\\\" | Monday | Matches full name days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"yyyymmdd\\\" | 19960101 | Matches fixed-width year, month, and day | - +-----------------+-----------+-----------------------------------------------------------------+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - -"), - -("Dates","Dates","Dates.DateFormat(format::AbstractString) -> DateFormat - - Construct a date formatting object that can be passed repeatedly - for parsing similarly formatted date strings. \"format\" is a - format string in the form described above (e.g. \"\"yyyy-mm- - dd\"\"). - -"), - -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","Date","Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - -"), - -("Dates","Date","Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - -"), - -("Dates","Date","Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - -"), - -("Dates","Date","Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - -"), - -("Dates","Date","Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - -"), - -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","now","now() -> DateTime - - Returns a DateTime corresponding to the user's system time - including the system timezone locale. - -"), - -("Dates","now","now(::Type{UTC}) -> DateTime - - Returns a DateTime corresponding to the user's system time as - UTC/GMT. - -"), - -("Dates","eps","eps(::DateTime) -> Millisecond -eps(::Date) -> Day - - Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" - for \"Date\" values. - -"), - -("Dates","year","year(dt::TimeType) -> Int64 -month(dt::TimeType) -> Int64 -week(dt::TimeType) -> Int64 -day(dt::TimeType) -> Int64 -hour(dt::TimeType) -> Int64 -minute(dt::TimeType) -> Int64 -second(dt::TimeType) -> Int64 -millisecond(dt::TimeType) -> Int64 - - Return the field part of a Date or DateTime as an \"Int64\". - -"), - -("Dates","Year","Year(dt::TimeType) -> Year -Month(dt::TimeType) -> Month -Week(dt::TimeType) -> Week -Day(dt::TimeType) -> Day -Hour(dt::TimeType) -> Hour -Minute(dt::TimeType) -> Minute -Second(dt::TimeType) -> Second -Millisecond(dt::TimeType) -> Millisecond - - Return the field part of a Date or DateTime as a \"Period\" type. - -"), - -("Dates","yearmonth","yearmonth(dt::TimeType) -> (Int64, Int64) - - Simultaneously return the year and month parts of a Date or - DateTime. - -"), - -("Dates","monthday","monthday(dt::TimeType) -> (Int64, Int64) - - Simultaneously return the month and day parts of a Date or - DateTime. - -"), - -("Dates","yearmonthday","yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - - Simultaneously return the year, month, and day parts of a Date or - DateTime. - -"), - -("Dates","dayname","dayname(dt::TimeType; locale=\"english\") -> AbstractString - - Return the full day name corresponding to the day of the week of - the Date or DateTime in the given \"locale\". - -"), - -("Dates","dayabbr","dayabbr(dt::TimeType; locale=\"english\") -> AbstractString - - Return the abbreviated name corresponding to the day of the week of - the Date or DateTime in the given \"locale\". - -"), - -("Dates","dayofweek","dayofweek(dt::TimeType) -> Int64 - - Returns the day of the week as an \"Int64\" with \"1 = Monday, 2 = - Tuesday, etc.\". - -"), - -("Dates","dayofweekofmonth","dayofweekofmonth(dt::TimeType) -> Int - - For the day of week of \"dt\", returns which number it is in - \"dt\"'s month. So if the day of the week of \"dt\" is Monday, then - \"1 = First Monday of the month, 2 = Second Monday of the month, - etc.\" In the range 1:5. - -"), - -("Dates","daysofweekinmonth","daysofweekinmonth(dt::TimeType) -> Int - - For the day of week of \"dt\", returns the total number of that day - of the week in \"dt\"'s month. Returns 4 or 5. Useful in temporal - expressions for specifying the last day of a week in a month by - including \"dayofweekofmonth(dt) == daysofweekinmonth(dt)\" in the - adjuster function. - -"), - -("Dates","monthname","monthname(dt::TimeType; locale=\"english\") -> AbstractString - - Return the full name of the month of the Date or DateTime in the - given \"locale\". - -"), - -("Dates","monthabbr","monthabbr(dt::TimeType; locale=\"english\") -> AbstractString - - Return the abbreviated month name of the Date or DateTime in the - given \"locale\". - -"), - -("Dates","daysinmonth","daysinmonth(dt::TimeType) -> Int - - Returns the number of days in the month of \"dt\". Value will be - 28, 29, 30, or 31. - -"), - -("Dates","isleapyear","isleapyear(dt::TimeType) -> Bool - - Returns true if the year of \"dt\" is a leap year. - -"), - -("Dates","dayofyear","dayofyear(dt::TimeType) -> Int - - Returns the day of the year for \"dt\" with January 1st being day - 1. - -"), - -("Dates","daysinyear","daysinyear(dt::TimeType) -> Int - - Returns 366 if the year of \"dt\" is a leap year, otherwise returns - 365. - -"), - -("Dates","quarterofyear","quarterofyear(dt::TimeType) -> Int - - Returns the quarter that \"dt\" resides in. Range of value is 1:4. - -"), - -("Dates","dayofquarter","dayofquarter(dt::TimeType) -> Int - - Returns the day of the current quarter of \"dt\". Range of value is - 1:92. - -"), - -("Dates","trunc","trunc(dt::TimeType, ::Type{Period}) -> TimeType - - Truncates the value of \"dt\" according to the provided \"Period\" - type. E.g. if \"dt\" is \"1996-01-01T12:30:00\", then - \"trunc(dt,Day) == 1996-01-01T00:00:00\". - -"), - -("Dates","firstdayofweek","firstdayofweek(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the Monday of its week. - -"), - -("Dates","lastdayofweek","lastdayofweek(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the Sunday of its week. - -"), - -("Dates","firstdayofmonth","firstdayofmonth(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the first day of its month. - -"), - -("Dates","lastdayofmonth","lastdayofmonth(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the last day of its month. - -"), - -("Dates","firstdayofyear","firstdayofyear(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the first day of its year. - -"), - -("Dates","lastdayofyear","lastdayofyear(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the last day of its year. - -"), - -("Dates","firstdayofquarter","firstdayofquarter(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the first day of its quarter. - -"), - -("Dates","lastdayofquarter","lastdayofquarter(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the last day of its quarter. - -"), - -("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts \"dt\" to the next day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the next \"dow\", allowing - for no adjustment to occur. - -"), - -("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts \"dt\" to the previous day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the previous \"dow\", - allowing for no adjustment to occur. - -"), - -("Dates","tofirst","tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - - Adjusts \"dt\" to the first \"dow\" of its month. Alternatively, - \"of=Year\" will adjust to the first \"dow\" of the year. - -"), - -("Dates","tolast","tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - - Adjusts \"dt\" to the last \"dow\" of its month. Alternatively, - \"of=Year\" will adjust to the last \"dow\" of the year. - -"), - -("Dates","tonext","tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts \"dt\" by iterating at most \"limit\" iterations by - \"step\" increments until \"func\" returns true. \"func\" must take - a single \"TimeType\" argument and return a \"Bool\". \"same\" - allows \"dt\" to be considered in satisfying \"func\". \"negate\" - will make the adjustment process terminate when \"func\" returns - false instead of true. - -"), - -("Dates","toprev","toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts \"dt\" by iterating at most \"limit\" iterations by - \"step\" increments until \"func\" returns true. \"func\" must take - a single \"TimeType\" argument and return a \"Bool\". \"same\" - allows \"dt\" to be considered in satisfying \"func\". \"negate\" - will make the adjustment process terminate when \"func\" returns - false instead of true. - -"), - -("Dates","recur{T<:TimeType}","recur{T<:TimeType}(func::Function, dr::StepRange{T};negate=false, limit=10000) -> Vector{T} - - \"func\" takes a single TimeType argument and returns a \"Bool\" - indicating whether the input should be \"included\" in the final - set. \"recur\" applies \"func\" over each element in the range of - \"dr\", including those elements for which \"func\" returns - \"true\" in the resulting Array, unless \"negate=true\", then only - elements where \"func\" returns \"false\" are included. - -"), - -("Dates","Year","Year(v) -Month(v) -Week(v) -Day(v) -Hour(v) -Minute(v) -Second(v) -Millisecond(v) - - Construct a \"Period\" type with the given \"v\" value. Input must - be losslessly convertible to an \"Int64\". - -"), - -("Dates","default","default(p::Period) -> Period - - Returns a sensible \"default\" value for the input Period by - returning \"one(p)\" for Year, Month, and Day, and \"zero(p)\" for - Hour, Minute, Second, and Millisecond. - -"), - -("Dates","today","today() -> Date - - Returns the date portion of \"now()\". - -"), - -("Dates","unix2datetime","unix2datetime(x) -> DateTime - - Takes the number of seconds since unix epoch - \"1970-01-01T00:00:00\" and converts to the corresponding DateTime. - -"), - -("Dates","datetime2unix","datetime2unix(dt::DateTime) -> Float64 - - Takes the given DateTime and returns the number of seconds since - the unix epoch as a \"Float64\". - -"), - -("Dates","julian2datetime","julian2datetime(julian_days) -> DateTime - - Takes the number of Julian calendar days since epoch - \"-4713-11-24T12:00:00\" and returns the corresponding DateTime. - -"), - -("Dates","datetime2julian","datetime2julian(dt::DateTime) -> Float64 - - Takes the given DateTime and returns the number of Julian calendar - days since the julian epoch as a \"Float64\". - -"), - -("Dates","rata2datetime","rata2datetime(days) -> DateTime - - Takes the number of Rata Die days since epoch - \"0000-12-31T00:00:00\" and returns the corresponding DateTime. - -"), - -("Dates","datetime2rata","datetime2rata(dt::TimeType) -> Int64 - - Returns the number of Rata Die days since epoch from the given Date - or DateTime. - -"), - -("Base","pwd","pwd() -> AbstractString - - Get the current working directory. - -"), - -("Base","cd","cd(dir::AbstractString) - - Set the current working directory. - -"), - -("Base","cd","cd(f[, dir]) - - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. - -"), - -("Base","readdir","readdir([dir]) -> Vector{ByteString} - - Returns the files and directories in the directory *dir* (or the - current working directory if not given). - -"), - -("Base","mkdir","mkdir(path[, mode]) - - Make a new directory with name \"path\" and permissions \"mode\". - \"mode\" defaults to 0o777, modified by the current file creation - mask. - -"), - -("Base","mkpath","mkpath(path[, mode]) - - Create all directories in the given \"path\", with permissions - \"mode\". \"mode\" defaults to 0o777, modified by the current file - creation mask. - -"), - -("Base","symlink","symlink(target, link) - - Creates a symbolic link to \"target\" with the name \"link\". - - Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. - -"), - -("Base","readlink","readlink(path) -> AbstractString - - Returns the value of a symbolic link \"path\". - -"), - -("Base","chmod","chmod(path, mode) - - Change the permissions mode of \"path\" to \"mode\". Only integer - \"mode\"s (e.g. 0o777) are currently supported. - -"), - -("Base","stat","stat(file) - - Returns a structure whose fields contain information about the - file. The fields of the structure are: - - +-----------+------------------------------------------------------------------------+ - | size | The size (in bytes) of the file | - +-----------+------------------------------------------------------------------------+ - | device | ID of the device that contains the file | - +-----------+------------------------------------------------------------------------+ - | inode | The inode number of the file | - +-----------+------------------------------------------------------------------------+ - | mode | The protection mode of the file | - +-----------+------------------------------------------------------------------------+ - | nlink | The number of hard links to the file | - +-----------+------------------------------------------------------------------------+ - | uid | The user id of the owner of the file | - +-----------+------------------------------------------------------------------------+ - | gid | The group id of the file owner | - +-----------+------------------------------------------------------------------------+ - | rdev | If this file refers to a device, the ID of the device it refers to | - +-----------+------------------------------------------------------------------------+ - | blksize | The file-system preferred block size for the file | - +-----------+------------------------------------------------------------------------+ - | blocks | The number of such blocks allocated | - +-----------+------------------------------------------------------------------------+ - | mtime | Unix timestamp of when the file was last modified | - +-----------+------------------------------------------------------------------------+ - | ctime | Unix timestamp of when the file was created | - +-----------+------------------------------------------------------------------------+ - -"), - -("Base","lstat","lstat(file) - - Like stat, but for symbolic links gets the info for the link itself - rather than the file it refers to. This function must be called on - a file path rather than a file object or a file descriptor. - -"), - -("Base","ctime","ctime(file) - - Equivalent to stat(file).ctime - -"), - -("Base","mtime","mtime(file) - - Equivalent to stat(file).mtime - -"), - -("Base","filemode","filemode(file) - - Equivalent to stat(file).mode - -"), - -("Base","filesize","filesize(path...) - - Equivalent to stat(file).size - -"), - -("Base","uperm","uperm(file) - - Gets the permissions of the owner of the file as a bitfield of - - +------+-----------------------+ - | 01 | Execute Permission | - +------+-----------------------+ - | 02 | Write Permission | - +------+-----------------------+ - | 04 | Read Permission | - +------+-----------------------+ - - For allowed arguments, see \"stat\". - -"), - -("Base","gperm","gperm(file) - - Like uperm but gets the permissions of the group owning the file - -"), - -("Base","operm","operm(file) - - Like uperm but gets the permissions for people who neither own the - file nor are a member of the group owning the file - -"), - -("Base","cp","cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - - Copy the file, link, or directory from *src* to *dest*. - \"remove_destination=true\" will first remove an existing *dst*. - - If *follow_symlinks=false*, and src is a symbolic link, dst will be - created as a symbolic link. If *follow_symlinks=true* and src is a - symbolic link, dst will be a copy of the file or directory *src* - refers to. - -"), - -("Base","download","download(url[, localfile]) - - Download a file from the given url, optionally renaming it to the - given local file name. Note that this function relies on the - availability of external tools such as \"curl\", \"wget\" or - \"fetch\" to download the file and is provided for convenience. For - production use or situations in which more options are need, please - use a package that provides the desired functionality instead. - -"), - -("Base","mv","mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - - Move the file, link, or directory from *src* to *dest*. - \"remove_destination=true\" will first remove an existing *dst*. - -"), - -("Base","rm","rm(path::AbstractString; recursive=false) - - Delete the file, link, or empty directory at the given path. If - \"recursive=true\" is passed and the path is a directory, then all - contents are removed recursively. - -"), - -("Base","touch","touch(path::AbstractString) - - Update the last-modified timestamp on a file to the current time. - -"), - -("Base","tempname","tempname() - - Generate a unique temporary file path. - -"), - -("Base","tempdir","tempdir() - - Obtain the path of a temporary directory (possibly shared with - other processes). - -"), - -("Base","mktemp","mktemp([parent=tempdir()]) - - Returns \"(path, io)\", where \"path\" is the path of a new - temporary file in \"parent\" and \"io\" is an open file object for - this path. - -"), - -("Base","mktempdir","mktempdir([parent=tempdir()]) - - Create a temporary directory in the \"parent\" directory and return - its path. - -"), - -("Base","isblockdev","isblockdev(path) -> Bool - - Returns \"true\" if \"path\" is a block device, \"false\" - otherwise. - -"), - -("Base","ischardev","ischardev(path) -> Bool - - Returns \"true\" if \"path\" is a character device, \"false\" - otherwise. - -"), - -("Base","isdir","isdir(path) -> Bool - - Returns \"true\" if \"path\" is a directory, \"false\" otherwise. - -"), - -("Base","isexecutable","isexecutable(path) -> Bool - - Returns \"true\" if the current user has permission to execute - \"path\", \"false\" otherwise. - -"), - -("Base","isfifo","isfifo(path) -> Bool - - Returns \"true\" if \"path\" is a FIFO, \"false\" otherwise. - -"), - -("Base","isfile","isfile(path) -> Bool - - Returns \"true\" if \"path\" is a regular file, \"false\" - otherwise. - -"), - -("Base","islink","islink(path) -> Bool - - Returns \"true\" if \"path\" is a symbolic link, \"false\" - otherwise. - -"), - -("Base","ismount","ismount(path) -> Bool - - Returns \"true\" if \"path\" is a mount point, \"false\" otherwise. - -"), - -("Base","ispath","ispath(path) -> Bool - - Returns \"true\" if \"path\" is a valid filesystem path, \"false\" - otherwise. - -"), - -("Base","isreadable","isreadable(path) -> Bool - - Returns \"true\" if the current user has permission to read - \"path\", \"false\" otherwise. - -"), - -("Base","issetgid","issetgid(path) -> Bool - - Returns \"true\" if \"path\" has the setgid flag set, \"false\" - otherwise. - -"), - -("Base","issetuid","issetuid(path) -> Bool - - Returns \"true\" if \"path\" has the setuid flag set, \"false\" - otherwise. - -"), - -("Base","issocket","issocket(path) -> Bool - - Returns \"true\" if \"path\" is a socket, \"false\" otherwise. - -"), - -("Base","issticky","issticky(path) -> Bool - - Returns \"true\" if \"path\" has the sticky bit set, \"false\" - otherwise. - -"), - -("Base","iswritable","iswritable(path) -> Bool - - Returns \"true\" if the current user has permission to write to - \"path\", \"false\" otherwise. - -"), - -("Base","homedir","homedir() -> AbstractString - - Return the current user's home directory. - -"), - -("Base","dirname","dirname(path::AbstractString) -> AbstractString - - Get the directory part of a path. - -"), - -("Base","basename","basename(path::AbstractString) -> AbstractString - - Get the file name part of a path. - -"), - -("Base","@__FILE__","@__FILE__() -> AbstractString - - \"@__FILE__\" expands to a string with the absolute path and file - name of the script being run. Returns \"nothing\" if run from a - REPL or an empty string if evaluated by \"julia -e \". - -"), - -("Base","isabspath","isabspath(path::AbstractString) -> Bool - - Determines whether a path is absolute (begins at the root - directory). - -"), - -("Base","isdirpath","isdirpath(path::AbstractString) -> Bool - - Determines whether a path refers to a directory (for example, ends - with a path separator). - -"), - -("Base","joinpath","joinpath(parts...) -> AbstractString - - Join path components into a full path. If some argument is an - absolute path, then prior components are dropped. - -"), - -("Base","abspath","abspath(path::AbstractString) -> AbstractString - - Convert a path to an absolute path by adding the current directory - if necessary. - -"), - -("Base","normpath","normpath(path::AbstractString) -> AbstractString - - Normalize a path, removing \".\" and \"..\" entries. - -"), - -("Base","realpath","realpath(path::AbstractString) -> AbstractString - - Canonicalize a path by expanding symbolic links and removing \".\" - and \"..\" entries. - -"), - -("Base","relpath","relpath(path::AbstractString, startpath::AbstractString = \".\") -> AbstractString - - Return a relative filepath to path either from the current - directory or from an optional start directory. This is a path - computation: the filesystem is not accessed to confirm the - existence or nature of path or startpath. - -"), - -("Base","expanduser","expanduser(path::AbstractString) -> AbstractString - - On Unix systems, replace a tilde character at the start of a path - with the current user's home directory. - -"), - -("Base","splitdir","splitdir(path::AbstractString) -> (AbstractString, AbstractString) - - Split a path into a tuple of the directory name and file name. - -"), - -("Base","splitdrive","splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - - On Windows, split a path into the drive letter part and the path - part. On Unix systems, the first component is always the empty - string. - -"), - -("Base","splitext","splitext(path::AbstractString) -> (AbstractString, AbstractString) - - If the last component of a path contains a dot, split the path into - everything before the dot and everything including and after the - dot. Otherwise, return a tuple of the argument unmodified and the - empty string. - -"), - - -("Base","STDOUT","STDOUT - - Global variable referring to the standard out stream. - -"), - -("Base","STDERR","STDERR - - Global variable referring to the standard error stream. - -"), - -("Base","STDIN","STDIN - - Global variable referring to the standard input stream. - -"), - -("Base","open","open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - -"), - -("Base","open","open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: - - +------+-----------------------------------+ - | r | read | - +------+-----------------------------------+ - | r+ | read, write | - +------+-----------------------------------+ - | w | write, create, truncate | - +------+-----------------------------------+ - | w+ | read, write, create, truncate | - +------+-----------------------------------+ - | a | write, create, append | - +------+-----------------------------------+ - | a+ | read, write, create, append | - +------+-----------------------------------+ - -"), - -("Base","open","open(f::function, args...) - - Apply the function \"f\" to the result of \"open(args...)\" and - close the resulting file descriptor upon completion. - - **Example**: \"open(readall, \"file.txt\")\" - -"), - -("Base","IOBuffer","IOBuffer() -> IOBuffer - - Create an in-memory I/O stream. - -"), - -("Base","IOBuffer","IOBuffer(size::Int) - - Create a fixed size IOBuffer. The buffer will not grow dynamically. - -"), - -("Base","IOBuffer","IOBuffer(string) - - Create a read-only IOBuffer on the data underlying the given string - -"), - -("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) - - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. - -"), - -("Base","takebuf_array","takebuf_array(b::IOBuffer) - - Obtain the contents of an \"IOBuffer\" as an array, without - copying. Afterwards, the IOBuffer is reset to its initial state. - -"), - -("Base","takebuf_string","takebuf_string(b::IOBuffer) - - Obtain the contents of an \"IOBuffer\" as a string, without - copying. Afterwards, the IOBuffer is reset to its initial state. - -"), - -("Base","fdio","fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - - Create an \"IOStream\" object from an integer file descriptor. If - \"own\" is true, closing this object will close the underlying - descriptor. By default, an \"IOStream\" is closed when it is - garbage collected. \"name\" allows you to associate the descriptor - with a named file. - -"), - -("Base","flush","flush(stream) - - Commit all currently buffered writes to the given stream. - -"), - -("Base","close","close(stream) - - Close an I/O stream. Performs a \"flush\" first. - -"), - -("Base","write","write(stream, x) - - Write the canonical binary representation of a value to the given - stream. - -"), - -("Base","read","read(stream, type) - - Read a value of the given type from a stream, in canonical binary - representation. - -"), - -("Base","read","read(stream, type, dims) - - Read a series of values of the given type from a stream, in - canonical binary representation. \"dims\" is either a tuple or a - series of integer arguments specifying the size of \"Array\" to - return. - -"), - -("Base","read!","read!(stream, array::Array) - - Read binary data from a stream, filling in the argument \"array\". - -"), - -("Base","readbytes!","readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - - Read at most \"nb\" bytes from the stream into \"b\", returning the - number of bytes read (increasing the size of \"b\" as needed). - -"), - -("Base","readbytes","readbytes(stream, nb=typemax(Int)) - - Read at most \"nb\" bytes from the stream, returning a - \"Vector{UInt8}\" of the bytes read. - -"), - -("Base","position","position(s) - - Get the current position of a stream. - -"), - -("Base","seek","seek(s, pos) - - Seek a stream to the given position. - -"), - -("Base","seekstart","seekstart(s) - - Seek a stream to its beginning. - -"), - -("Base","seekend","seekend(s) - - Seek a stream to its end. - -"), - -("Base","skip","skip(s, offset) - - Seek a stream relative to the current position. - -"), - -("Base","mark","mark(s) - - Add a mark at the current position of stream \"s\". Returns the - marked position. - - See also \"unmark()\", \"reset()\", \"ismarked()\" - -"), - -("Base","unmark","unmark(s) - - Remove a mark from stream \"s\". Returns \"true\" if the stream was - marked, \"false\" otherwise. - - See also \"mark()\", \"reset()\", \"ismarked()\" - -"), - -("Base","reset","reset(s) - - Reset a stream \"s\" to a previously marked position, and remove - the mark. Returns the previously marked position. Throws an error - if the stream is not marked. - - See also \"mark()\", \"unmark()\", \"ismarked()\" - -"), - -("Base","ismarked","ismarked(s) - - Returns true if stream \"s\" is marked. - - See also \"mark()\", \"unmark()\", \"reset()\" - -"), - -("Base","eof","eof(stream) -> Bool - - Tests whether an I/O stream is at end-of-file. If the stream is not - yet exhausted, this function will block to wait for more data if - necessary, and then return \"false\". Therefore it is always safe - to read one byte after seeing \"eof\" return \"false\". \"eof\" - will return \"false\" as long as buffered data is still available, - even if the remote end of a connection is closed. - -"), - -("Base","isreadonly","isreadonly(stream) -> Bool - - Determine whether a stream is read-only. - -"), - -("Base","isopen","isopen(stream) -> Bool - - Determine whether a stream is open (i.e. has not been closed yet). - If the connection has been closed remotely (in case of e.g. a - socket), \"isopen\" will return \"false\" even though buffered data - may still be available. Use \"eof\" to check if necessary. - -"), - -("Base","serialize","serialize(stream, value) - - Write an arbitrary value to a stream in an opaque format, such that - it can be read back by \"deserialize\". The read-back value will be - as identical as possible to the original. In general, this process - will not work if the reading and writing are done by different - versions of Julia, or an instance of Julia with a different system - image. - -"), - -("Base","deserialize","deserialize(stream) - - Read a value written by \"serialize\". - -"), - -("Base","print_escaped","print_escaped(io, str::AbstractString, esc::AbstractString) - - General escaping of traditional C and Unicode escape sequences, - plus any characters in esc are also escaped (with a backslash). - -"), - -("Base","print_unescaped","print_unescaped(io, s::AbstractString) - - General unescaping of traditional C and Unicode escape sequences. - Reverse of \"print_escaped()\". - -"), - -("Base","print_joined","print_joined(io, items, delim[, last]) - - Print elements of \"items\" to \"io\" with \"delim\" between them. - If \"last\" is specified, it is used as the final delimiter instead - of \"delim\". - -"), - -("Base","print_shortest","print_shortest(io, x) - - Print the shortest possible representation, with the minimum number - of consecutive non-zero digits, of number \"x\", ensuring that it - would parse to the exact same number. - -"), - -("Base","fd","fd(stream) - - Returns the file descriptor backing the stream or file. Note that - this function only applies to synchronous *File*'s and *IOStream*'s - not to any of the asynchronous streams. - -"), - -("Base","redirect_stdout","redirect_stdout() - - Create a pipe to which all C and Julia level STDOUT output will be - redirected. Returns a tuple (rd,wr) representing the pipe ends. - Data written to STDOUT may now be read from the rd end of the pipe. - The wr end is given for convenience in case the old STDOUT object - was cached by the user and needs to be replaced elsewhere. - -"), - -("Base","redirect_stdout","redirect_stdout(stream) - - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - -"), - -("Base","redirect_stderr","redirect_stderr([stream]) - - Like redirect_stdout, but for STDERR - -"), - -("Base","redirect_stdin","redirect_stdin([stream]) - - Like redirect_stdout, but for STDIN. Note that the order of the - return tuple is still (rd,wr), i.e. data to be read from STDIN, may - be written to wr. - -"), - -("Base","readchomp","readchomp(x) - - Read the entirety of x as a string but remove trailing newlines. - Equivalent to chomp(readall(x)). - -"), - -("Base","truncate","truncate(file, n) - - Resize the file or buffer given by the first argument to exactly - *n* bytes, filling previously unallocated space with '\\0' if the - file or buffer is grown - -"), - -("Base","skipchars","skipchars(stream, predicate; linecomment::Char) - - Advance the stream until before the first character for which - \"predicate\" returns false. For example \"skipchars(stream, - isspace)\" will skip all whitespace. If keyword argument - \"linecomment\" is specified, characters from that character - through the end of a line will also be skipped. - -"), - -("Base","countlines","countlines(io[, eol::Char]) - - Read io until the end of the stream/file and count the number of - non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than '\\n' are supported by passing - them as the second argument. - -"), - -("Base","PipeBuffer","PipeBuffer() - - An IOBuffer that allows reading and performs writes by appending. - Seeking and truncating are not supported. See IOBuffer for the - available constructors. - -"), - -("Base","PipeBuffer","PipeBuffer(data::Vector{UInt8}[, maxsize]) - - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. - -"), - -("Base","readavailable","readavailable(stream) - - Read all available data on the stream, blocking the task only if no - data is available. The result is a \"Vector{UInt8,1}\". - -"), - -("Base","show","show(x) - - Write an informative text representation of a value to the current - output stream. New types should overload \"show(io, x)\" where the - first argument is a stream. The representation used by \"show\" - generally includes Julia-specific formatting and type information. - -"), - -("Base","showcompact","showcompact(x) - - Show a more compact representation of a value. This is used for - printing array elements. If a new type has a different compact - representation, it should overload \"showcompact(io, x)\" where the - first argument is a stream. - -"), - -("Base","showall","showall(x) - - Similar to \"show\", except shows all elements of arrays. - -"), - -("Base","summary","summary(x) - - Return a string giving a brief description of a value. By default - returns \"string(typeof(x))\". For arrays, returns strings like - \"2x2 Float64 Array\". - -"), - -("Base","print","print(x) - - Write (to the default output stream) a canonical (un-decorated) - text representation of a value if there is one, otherwise call - \"show\". The representation used by \"print\" includes minimal - formatting and tries to avoid Julia-specific details. - -"), - -("Base","println","println(x) - - Print (using \"print()\") \"x\" followed by a newline. - -"), - -("Base","print_with_color","print_with_color(color::Symbol[, io], strings...) - - Print strings in a color specified as a symbol, for example - \":red\" or \":blue\". - -"), - -("Base","info","info(msg) - - Display an informational message. - -"), - -("Base","warn","warn(msg) - - Display a warning. - -"), - -("Base","@printf","@printf([io::IOStream], \"%Fmt\", args...) - - Print arg(s) using C \"printf()\" style format specification - string. Optionally, an IOStream may be passed as the first argument - to redirect output. - -"), - -("Base","@sprintf","@sprintf(\"%Fmt\", args...) - - Return \"@printf\" formatted output as string. - -"), - -("Base","sprint","sprint(f::Function, args...) - - Call the given function with an I/O stream and the supplied extra - arguments. Everything written to this I/O stream is returned as a - string. - -"), - -("Base","showerror","showerror(io, e) - - Show a descriptive representation of an exception object. - -"), - -("Base","dump","dump(x) - - Show all user-visible structure of a value. - -"), - -("Base","xdump","xdump(x) - - Show all structure of a value, including all fields of objects. - -"), - -("Base","readall","readall(stream::IO) - - Read the entire contents of an I/O stream as a string. - -"), - -("Base","readall","readall(filename::AbstractString) - - Open \"filename\", read the entire contents as a string, then close - the file. Equivalent to \"open(readall, filename)\". - -"), - -("Base","readline","readline(stream=STDIN) - - Read a single line of text, including a trailing newline character - (if one is reached before the end of the input), from the given - \"stream\" (defaults to \"STDIN\"), - -"), - -("Base","readuntil","readuntil(stream, delim) - - Read a string, up to and including the given delimiter byte. - -"), - -("Base","readlines","readlines(stream) - - Read all lines as an array. - -"), - -("Base","eachline","eachline(stream) - - Create an iterable object that will yield each line from a stream. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - -"), - -("Base","readdlm","readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"\\n\". - -"), - -("Base","readdlm","readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"\\n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","readdlm","readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"\\n\". - -"), - -("Base","readdlm","readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"\\n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","writedlm","writedlm(f, A, delim='\\t') - - Write \"A\" (a vector, matrix or an iterable collection of iterable - rows) as text to \"f\" (either a filename string or an \"IO\" - stream) using the given delimeter \"delim\" (which defaults to tab, - but can be any printable Julia object, typically a \"Char\" or - \"AbstractString\"). - - For example, two vectors \"x\" and \"y\" of the same length can be - written as two columns of tab-delimited text to \"f\" by either - \"writedlm(f, [x y])\" or by \"writedlm(f, zip(x, y))\". - -"), - -("Base","readcsv","readcsv(source, [T::Type]; options...) - - Equivalent to \"readdlm\" with \"delim\" set to comma. - -"), - -("Base","writecsv","writecsv(filename, A) - - Equivalent to \"writedlm\" with \"delim\" set to comma. - -"), - -("Base","Base64EncodePipe","Base64EncodePipe(ostream) - - Returns a new write-only I/O stream, which converts any bytes - written to it into base64-encoded ASCII bytes written to - \"ostream\". Calling \"close\" on the \"Base64Pipe\" stream is - necessary to complete the encoding (but does not close - \"ostream\"). - -"), - -("Base","Base64DecodePipe","Base64DecodePipe(istream) - - Returns a new read-only I/O stream, which decodes base64-encoded - data read from \"istream\". - -"), - -("Base","base64encode","base64encode(writefunc, args...) -base64encode(args...) - - Given a \"write\"-like function \"writefunc\", which takes an I/O - stream as its first argument, \"base64(writefunc, args...)\" calls - \"writefunc\" to write \"args...\" to a base64-encoded string, and - returns the string. \"base64(args...)\" is equivalent to - \"base64(write, args...)\": it converts its arguments into bytes - using the standard \"write\" functions and returns the - base64-encoded string. - -"), - -("Base","base64decode","base64decode(string) - - Decodes the base64-encoded \"string\" and returns a - \"Vector{UInt8}\" of the decoded bytes. - -"), - -("Base","display","display(x) -display(d::Display, x) -display(mime, x) -display(d::Display, mime, x) - - Display \"x\" using the topmost applicable display in the display - stack, typically using the richest supported multimedia output for - \"x\", with plain-text \"STDOUT\" output as a fallback. The - \"display(d, x)\" variant attempts to display \"x\" on the given - display \"d\" only, throwing a \"MethodError\" if \"d\" cannot - display objects of this type. - - There are also two variants with a \"mime\" argument (a MIME type - string, such as \"\"image/png\"\"), which attempt to display \"x\" - using the requested MIME type *only*, throwing a \"MethodError\" if - this type is not supported by either the display(s) or by \"x\". - With these variants, one can also supply the \"raw\" data in the - requested MIME type by passing \"x::AbstractString\" (for MIME - types with text-based storage, such as text/html or - application/postscript) or \"x::Vector{UInt8}\" (for binary MIME - types). - -"), - -("Base","redisplay","redisplay(x) -redisplay(d::Display, x) -redisplay(mime, x) -redisplay(d::Display, mime, x) - - By default, the \"redisplay\" functions simply call \"display\". - However, some display backends may override \"redisplay\" to modify - an existing display of \"x\" (if any). Using \"redisplay\" is - also a hint to the backend that \"x\" may be redisplayed several - times, and the backend may choose to defer the display until (for - example) the next interactive prompt. - -"), - -("Base","displayable","displayable(mime) -> Bool -displayable(d::Display, mime) -> Bool - - Returns a boolean value indicating whether the given \"mime\" type - (string) is displayable by any of the displays in the current - display stack, or specifically by the display \"d\" in the second - variant. - -"), - -("Base","writemime","writemime(stream, mime, x) - - The \"display\" functions ultimately call \"writemime\" in order to - write an object \"x\" as a given \"mime\" type to a given I/O - \"stream\" (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - \"T\", it is only necessary to define a new \"writemime\" method - for \"T\", via: \"writemime(stream, ::MIME\"mime\", x::T) = ...\", - where \"mime\" is a MIME-type string and the function body calls - \"write\" (or similar) to write that representation of \"x\" to - \"stream\". (Note that the \"MIME\"\"\" notation only supports - literal strings; to construct \"MIME\" types in a more flexible - manner use \"MIME{symbol(\"\")}\".) - - For example, if you define a \"MyImage\" type and know how to write - it to a PNG file, you could define a function \"writemime(stream, - ::MIME\"image/png\", x::MyImage) = ...`\" to allow your images to - be displayed on any PNG-capable \"Display\" (such as IJulia). As - usual, be sure to \"import Base.writemime\" in order to add new - methods to the built-in Julia function \"writemime\". - - Technically, the \"MIME\"mime\"\" macro defines a singleton type - for the given \"mime\" string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. - -"), - -("Base","mimewritable","mimewritable(mime, x) - - Returns a boolean value indicating whether or not the object \"x\" - can be written as the given \"mime\" type. (By default, this is - determined automatically by the existence of the corresponding - \"writemime\" function for \"typeof(x)\".) - -"), - -("Base","reprmime","reprmime(mime, x) - - Returns an \"AbstractString\" or \"Vector{UInt8}\" containing the - representation of \"x\" in the requested \"mime\" type, as written - by \"writemime\" (throwing a \"MethodError\" if no appropriate - \"writemime\" is available). An \"AbstractString\" is returned for - MIME types with textual representations (such as \"\"text/html\"\" - or \"\"application/postscript\"\"), whereas binary data is returned - as \"Vector{UInt8}\". (The function \"istext(mime)\" returns - whether or not Julia treats a given \"mime\" type as text.) - - As a special case, if \"x\" is an \"AbstractString\" (for textual - MIME types) or a \"Vector{UInt8}\" (for binary MIME types), the - \"reprmime\" function assumes that \"x\" is already in the - requested \"mime\" format and simply returns \"x\". - -"), - -("Base","stringmime","stringmime(mime, x) - - Returns an \"AbstractString\" containing the representation of - \"x\" in the requested \"mime\" type. This is similar to - \"reprmime\" except that binary data is base64-encoded as an ASCII - string. - -"), - -("Base","pushdisplay","pushdisplay(d::Display) - - Pushes a new display \"d\" on top of the global display-backend - stack. Calling \"display(x)\" or \"display(mime, x)\" will display - \"x\" on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a \"MethodError\"). - -"), - -("Base","popdisplay","popdisplay() -popdisplay(d::Display) - - Pop the topmost backend off of the display-backend stack, or the - topmost copy of \"d\" in the second variant. - -"), - -("Base","TextDisplay","TextDisplay(stream) - - Returns a \"TextDisplay <: Display\", which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same as - the way an object is printed in the Julia REPL.) - -"), - -("Base","istext","istext(m::MIME) - - Determine whether a MIME type is text data. - -"), - -("Base","mmap_array","mmap_array(type, dims, stream[, offset]) - - Create an \"Array\" whose values are linked to a file, using - memory-mapping. This provides a convenient way of working with data - too large to fit in the computer's memory. - - The type determines how the bytes of the array are interpreted. - Note that the file must be stored in binary format, and no format - conversions are possible (this is a limitation of operating - systems, not Julia). - - \"dims\" is a tuple specifying the size of the array. - - The file is passed via the stream argument. When you initialize - the stream, use \"\"r\"\" for a \"read-only\" array, and \"\"w+\"\" - to create a new array used to write values to disk. - - Optionally, you can specify an offset (in bytes) if, for example, - you want to skip over a header in the file. The default value for - the offset is the current stream position. - - For example, the following code: - - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open(\"/tmp/mmap.bin\", \"w+\") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) - - # Test by reading it back in - s = open(\"/tmp/mmap.bin\") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) - - creates a \"m\"-by-\"n\" \"Matrix{Int}\", linked to the file - associated with stream \"s\". - - A more portable file would need to encode the word size---32 bit or - 64 bit---and endianness information in the header. In practice, - consider encoding binary data using standard formats like HDF5 - (which can be used with memory-mapping). - -"), - -("Base","mmap_bitarray","mmap_bitarray([type], dims, stream[, offset]) - - Create a \"BitArray\" whose values are linked to a file, using - memory-mapping; it has the same purpose, works in the same way, and - has the same arguments, as \"mmap_array()\", but the byte - representation is different. The \"type\" parameter is optional, - and must be \"Bool\" if given. - - **Example**: \"B = mmap_bitarray((25,30000), s)\" - - This would create a 25-by-30000 \"BitArray\", linked to the file - associated with stream \"s\". - -"), - -("Base","msync","msync(array) - - Forces synchronization between the in-memory version of a memory- - mapped \"Array\" or \"BitArray\" and the on-disk version. - -"), - -("Base","connect","connect([host], port) -> TcpSocket - - Connect to the host \"host\" on port \"port\" - -"), - -("Base","connect","connect(path) -> Pipe - - Connect to the Named Pipe/Domain Socket at \"path\" - -"), - -("Base","listen","listen([addr], port) -> TcpServer - - Listen on port on the address specified by \"addr\". By default - this listens on localhost only. To listen on all interfaces pass, - \"IPv4(0)\" or \"IPv6(0)\" as appropriate. - -"), - -("Base","listen","listen(path) -> PipeServer - - Listens on/Creates a Named Pipe/Domain Socket - -"), - -("Base","getaddrinfo","getaddrinfo(host) - - Gets the IP address of the \"host\" (may have to do a DNS lookup) - -"), - -("Base","parseip","parseip(addr) - - Parse a string specifying an IPv4 or IPv6 ip address. - -"), - -("Base","IPv4","IPv4(host::Integer) -> IPv4 - - Returns IPv4 object from ip address formatted as Integer - -"), - -("Base","IPv6","IPv6(host::Integer) -> IPv6 - - Returns IPv6 object from ip address formatted as Integer - -"), - -("Base","nb_available","nb_available(stream) - - Returns the number of bytes available for reading before a read - from this stream or buffer will block. - -"), - -("Base","accept","accept(server[, client]) - - Accepts a connection on the given server and returns a connection - to the client. An uninitialized client stream may be provided, in - which case it will be used instead of creating a new stream. - -"), - -("Base","listenany","listenany(port_hint) -> (UInt16, TcpServer) - - Create a TcpServer on any port, using hint as a starting point. - Returns a tuple of the actual port that the server was created on - and the server itself. - -"), - -("Base","watch_file","watch_file(cb=false, s; poll=false) - - Watch file or directory \"s\" and run callback \"cb\" when \"s\" is - modified. The \"poll\" parameter specifies whether to use file - system event monitoring or polling. The callback function \"cb\" - should accept 3 arguments: \"(filename, events, status)\" where - \"filename\" is the name of file that was modified, \"events\" is - an object with boolean fields \"changed\" and \"renamed\" when - using file system event monitoring, or \"readable\" and - \"writable\" when using polling, and \"status\" is always 0. Pass - \"false\" for \"cb\" to not use a callback function. - -"), - -("Base","poll_fd","poll_fd(fd, seconds::Real; readable=false, writable=false) - - Poll a file descriptor fd for changes in the read or write - availability and with a timeout given by the second argument. If - the timeout is not needed, use \"wait(fd)\" instead. The keyword - arguments determine which of read and/or write status should be - monitored and at least one of them needs to be set to true. The - returned value is an object with boolean fields \"readable\", - \"writable\", and \"timedout\", giving the result of the polling. - -"), - -("Base","poll_file","poll_file(s, interval_seconds::Real, seconds::Real) - - Monitor a file for changes by polling every *interval_seconds* - seconds for *seconds* seconds. A return value of true indicates the - file changed, a return value of false indicates a timeout. - -"), - -("Base","bind","bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - - Bind \"socket\" to the given \"host:port\". Note that *0.0.0.0* - will listen on all devices. - -"), - -("Base","send","send(socket::UDPSocket, host::IPv4, port::Integer, msg) - - Send \"msg\" over \"socket to ``host:port\". - -"), - -("Base","recv","recv(socket::UDPSocket) - - Read a UDP packet from the specified socket, and return the bytes - received. This call blocks. - -"), - -("Base","recvfrom","recvfrom(socket::UDPSocket) -> (address, data) - - Read a UDP packet from the specified socket, returning a tuple of - (address, data), where address will be either IPv4 or IPv6 as - appropriate. - -"), - -("Base","setopt","setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - - Set UDP socket options. \"multicast_loop\": loopback for multicast - packets (default: true). \"multicast_ttl\": TTL for multicast - packets. \"enable_broadcast\": flag must be set to true if socket - will be used for broadcast messages, or else the UDP system will - return an access error (default: false). \"ttl\": Time-to-live of - packets sent on the socket. - -"), - -("Base","ntoh","ntoh(x) - - Converts the endianness of a value from Network byte order (big- - endian) to that used by the Host. - -"), - -("Base","hton","hton(x) - - Converts the endianness of a value from that used by the Host to - Network byte order (big-endian). - -"), - -("Base","ltoh","ltoh(x) - - Converts the endianness of a value from Little-endian to that used - by the Host. - -"), - -("Base","htol","htol(x) - - Converts the endianness of a value from that used by the Host to - Little-endian. - -"), - -("Base","ENDIAN_BOM","ENDIAN_BOM - - The 32-bit byte-order-mark indicates the native byte order of the - host machine. Little-endian machines will contain the value - 0x04030201. Big-endian machines will contain the value 0x01020304. - -"), - -("Libc","malloc","malloc(size::Integer) -> Ptr{Void} - - Call \"malloc\" from the C standard library. - -"), - -("Libc","calloc","calloc(num::Integer, size::Integer) -> Ptr{Void} - - Call \"calloc\" from the C standard library. - -"), - -("Libc","realloc","realloc(addr::Ptr, size::Integer) -> Ptr{Void} - - Call \"realloc\" from the C standard library. - - See warning in the documentation for \"free\" regarding only using - this on memory originally obtained from \"malloc\". - -"), - -("Libc","free","free(addr::Ptr) - - Call \"free\" from the C standard library. Only use this on memory - obtained from \"malloc\", not on pointers retrieved from other C - libraries. \"Ptr\" objects obtained from C libraries should be - freed by the free functions defined in that library, to avoid - assertion failures if multiple \"libc\" libraries exist on the - system. - -"), - -("Libc","errno","errno([code]) - - Get the value of the C library's \"errno\". If an argument is - specified, it is used to set the value of \"errno\". - - The value of \"errno\" is only valid immediately after a \"ccall\" - to a C library routine that sets it. Specifically, you cannot call - \"errno\" at the next prompt in a REPL, because lots of code is - executed between prompts. - -"), - -("Libc","strerror","strerror(n) - - Convert a system call error code to a descriptive string - -"), - -("Libc","time","time(t::TmStruct) - - Converts a \"TmStruct\" struct to a number of seconds since the - epoch. - -"), - -("Libc","strftime","strftime([format], time) - - Convert time, given as a number of seconds since the epoch or a - \"TmStruct\", to a formatted string using the given format. - Supported formats are the same as those in the standard C library. - -"), - -("Libc","strptime","strptime([format], timestr) - - Parse a formatted time string into a \"TmStruct\" giving the - seconds, minute, hour, date, etc. Supported formats are the same as - those in the standard C library. On some platforms, timezones will - not be parsed correctly. If the result of this function will be - passed to \"time\" to convert it to seconds since the epoch, the - \"isdst\" field should be filled in manually. Setting it to \"-1\" - will tell the C library to use the current system settings to - determine the timezone. - -"), - -("Libc","TmStruct","TmStruct([seconds]) - - Convert a number of seconds since the epoch to broken-down format, - with fields \"sec\", \"min\", \"hour\", \"mday\", \"month\", - \"year\", \"wday\", \"yday\", and \"isdst\". - -"), - -("Libc","flush_cstdio","flush_cstdio() - - Flushes the C \"stdout\" and \"stderr\" streams (which may have - been written to by external C code). - -"), - -("Libc","msync","msync(ptr, len[, flags]) - - Forces synchronization of the \"mmap()\"ped memory region from - \"ptr\" to \"ptr+len\". Flags defaults to \"MS_SYNC\", but can be a - combination of \"MS_ASYNC\", \"MS_SYNC\", or \"MS_INVALIDATE\". See - your platform man page for specifics. The flags argument is not - valid on Windows. - - You may not need to call \"msync\", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. - -"), - -("Libc","MS_ASYNC","MS_ASYNC - - Enum constant for \"msync()\". See your platform man page for - details. (not available on Windows). - -"), - -("Libc","MS_SYNC","MS_SYNC - - Enum constant for \"msync()\". See your platform man page for - details. (not available on Windows). - -"), - -("Libc","MS_INVALIDATE","MS_INVALIDATE - - Enum constant for \"msync()\". See your platform man page for - details. (not available on Windows). - -"), - -("Libc","mmap","mmap(len, prot, flags, fd, offset) - - Low-level interface to the \"mmap\" system call. See the man page. - -"), - -("Libc","munmap","munmap(pointer, len) - - Low-level interface for unmapping memory (see the man page). With - \"mmap_array()\" you do not need to call this directly; the memory - is unmapped for you when the array goes out of scope. - -"), - -("Libdl","dlopen","dlopen(libfile::AbstractString[, flags::Integer]) - - Load a shared library, returning an opaque handle. - - The optional flags argument is a bitwise-or of zero or more of - \"RTLD_LOCAL\", \"RTLD_GLOBAL\", \"RTLD_LAZY\", \"RTLD_NOW\", - \"RTLD_NODELETE\", \"RTLD_NOLOAD\", \"RTLD_DEEPBIND\", and - \"RTLD_FIRST\". These are converted to the corresponding flags of - the POSIX (and/or GNU libc and/or MacOS) dlopen command, if - possible, or are ignored if the specified functionality is not - available on the current platform. The default is - \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL\". An important usage of - these flags, on POSIX platforms, is to specify - \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL\" in order for the library's - symbols to be available for usage in other shared libraries, in - situations where there are dependencies between shared libraries. - -"), - -("Libdl","dlopen_e","dlopen_e(libfile::AbstractString[, flags::Integer]) - - Similar to \"dlopen()\", except returns a \"NULL\" pointer instead - of raising errors. - -"), - -("Libdl","RTLD_DEEPBIND","RTLD_DEEPBIND - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_FIRST","RTLD_FIRST - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_GLOBAL","RTLD_GLOBAL - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_LAZY","RTLD_LAZY - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_LOCAL","RTLD_LOCAL - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_NODELETE","RTLD_NODELETE - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_NOLOAD","RTLD_NOLOAD - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_NOW","RTLD_NOW - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","dlsym","dlsym(handle, sym) - - Look up a symbol from a shared library handle, return callable - function pointer on success. - -"), - -("Libdl","dlsym_e","dlsym_e(handle, sym) - - Look up a symbol from a shared library handle, silently return NULL - pointer on lookup failure. - -"), - -("Libdl","dlclose","dlclose(handle) - - Close shared library referenced by handle. - -"), - -("Libdl","find_library","find_library(names, locations) - - Searches for the first library in \"names\" in the paths in the - \"locations\" list, \"DL_LOAD_PATH\", or system library paths (in - that order) which can successfully be dlopen'd. On success, the - return value will be one of the names (potentially prefixed by one - of the paths in locations). This string can be assigned to a - \"global const\" and used as the library name in future - \"ccall\"'s. On failure, it returns the empty string. - -"), - -("Libdl","DL_LOAD_PATH","DL_LOAD_PATH - - When calling \"dlopen\", the paths in this list will be searched - first, in order, before searching the system locations for a valid - library handle. - -"), - -("Base","*","*(A, B) - - Matrix multiplication - -"), - -("Base","\\","\\(A, B) - - Matrix division using a polyalgorithm. For input matrices \"A\" and - \"B\", the result \"X\" is such that \"A*X == B\" when \"A\" is - square. The solver that is used depends upon the structure of - \"A\". A direct solver is used for upper- or lower triangular - \"A\". For Hermitian \"A\" (equivalent to symmetric \"A\" for non- - complex \"A\") the \"BunchKaufman\" factorization is used. - Otherwise an LU factorization is used. For rectangular \"A\" the - result is the minimum-norm least squares solution computed by a - pivoted QR factorization of \"A\" and a rank estimate of A based on - the R factor. - - When \"A\" is sparse, a similar polyalgorithm is used. For - indefinite matrices, the LDLt factorization does not use pivoting - during the numerical factorization and therefore the procedure can - fail even for invertible matrices. - -"), - -("Base","dot","dot(x, y) -⋅(x, y) - - Compute the dot product. For complex vectors, the first vector is - conjugated. - -"), - -("Base","vecdot","vecdot(x, y) - - For any iterable containers \"x\" and \"y\" (including arrays of - any dimension) of numbers (or any element type for which \"dot\" is - defined), compute the Euclidean dot product (the sum of - \"dot(x[i],y[i])\") as if they were vectors. - -"), - -("Base","cross","cross(x, y) -×(x, y) - - Compute the cross product of two 3-vectors. - -"), - -("Base","factorize","factorize(A) - - Compute a convenient factorization (including LU, Cholesky, Bunch- - Kaufman, LowerTriangular, UpperTriangular) of A, based upon the - type of the input matrix. The return value can then be reused for - efficient solving of multiple systems. For example: - \"A=factorize(A); x=A\\\\b; y=A\\\\C\". - -"), - -("Base","full","full(F) - - Reconstruct the matrix \"A\" from the factorization - \"F=factorize(A)\". - -"), - -("Base","lu","lu(A) -> L, U, p - - Compute the LU factorization of \"A\", such that \"A[p,:] = L*U\". - -"), - -("Base","lufact","lufact(A[, pivot=Val{true}]) -> F - - Compute the LU factorization of \"A\". The return type of \"F\" - depends on the type of \"A\". In most cases, if \"A\" is a subtype - \"S\" of AbstractMatrix with an element type \"T`\" supporting - \"+\", \"-\", \"*\" and \"/\" the return type is \"LU{T,S{T}}\". If - pivoting is chosen (default) the element type should also support - \"abs\" and \"<\". When \"A\" is sparse and have element of type - \"Float32\", \"Float64\", \"Complex{Float32}\", or - \"Complex{Float64}\" the return type is \"UmfpackLU\". Some - examples are shown in the table below. - - +-------------------------+---------------------------+----------------------------------------------+ - | Type of input \\\"A\\\" | Type of output \\\"F\\\" | Relationship between \\\"F\\\" and \\\"A\\\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \\\"Matrix()\\\" | \\\"LU\\\" | \\\"F[:L]*F[:U] == A[F[:p], :]\\\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \\\"Tridiagonal()\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | N/A | - +-------------------------+---------------------------+----------------------------------------------+ - | \\\"SparseMatrixCSC()\\\" | \\\"UmfpackLU\\\" | \\\"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\\\" | - +-------------------------+---------------------------+----------------------------------------------+ - - The individual components of the factorization \"F\" can be - accessed by indexing: - - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | \\\"LU\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | \\\"UmfpackLU\\\" | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:L]\\\" | \\\"L\\\" (lower triangular) part of \\\"LU\\\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:U]\\\" | \\\"U\\\" (upper triangular) part of \\\"LU\\\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:p]\\\" | (right) permutation \\\"Vector\\\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:P]\\\" | (right) permutation \\\"Matrix\\\" | ✓ | | | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:q]\\\" | left permutation \\\"Vector\\\" | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:Rs]\\\" | \\\"Vector\\\" of scaling factors | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:(:)]\\\" | \\\"(L,U,p,q,Rs)\\\" components | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - - +--------------------+--------+--------------------------+---------------+ - | Supported function | \\\"LU\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | \\\"UmfpackLU\\\" | - +--------------------+--------+--------------------------+---------------+ - | \\\"/\\\" | ✓ | | | - +--------------------+--------+--------------------------+---------------+ - | \\\"\\\\\\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \\\"cond\\\" | ✓ | | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \\\"det\\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \\\"size\\\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - -"), - -("Base","lufact!","lufact!(A) -> LU - - \"lufact!\" is the same as \"lufact()\", but saves space by - overwriting the input A, instead of creating a copy. For sparse - \"A\" the \"nzval\" field is not overwritten but the index fields, - \"colptr\" and \"rowval\" are decremented in place, converting from - 1-based indices to 0-based indices. - -"), - -("Base","chol","chol(A[, LU]) -> F - - Compute the Cholesky factorization of a symmetric positive definite - matrix \"A\" and return the matrix \"F\". If \"LU\" is \"Val{:U}\" - (Upper), \"F\" is of type \"UpperTriangular\" and \"A = F'*F\". If - \"LU\" is \"Val{:L}\" (Lower), \"F\" is of type \"LowerTriangular\" - and \"A = F*F'\". \"LU\" defaults to \"Val{:U}\". - -"), - -("Base","cholfact","cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - - Compute the Cholesky factorization of a dense symmetric positive - (semi)definite matrix \"A\" and return either a \"Cholesky\" if - \"pivot==Val{false}\" or \"CholeskyPivoted\" if - \"pivot==Val{true}\". \"LU\" may be \":L\" for using the lower part - or \":U\" for the upper part. The default is to use \":U\". The - triangular matrix can be obtained from the factorization \"F\" - with: \"F[:L]\" and \"F[:U]\". The following functions are - available for \"Cholesky\" objects: \"size\", \"\\\", \"inv\", - \"det\". For \"CholeskyPivoted\" there is also defined a \"rank\". - If \"pivot==Val{false}\" a \"PosDefException\" exception is thrown - in case the matrix is not positive definite. The argument \"tol\" - determines the tolerance for determining the rank. For negative - values, the tolerance is the machine precision. - -"), - -("Base","cholfact","cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the Cholesky factorization of a sparse positive definite - matrix \"A\". A fill-reducing permutation is used. \"F = - cholfact(A)\" is most frequently used to solve systems of equations - with \"F\\b\", but also the methods \"diag\", \"det\", \"logdet\" - are defined for \"F\". You can also extract individual factors - from \"F\", using \"F[:L]\". However, since pivoting is on by - default, the factorization is internally represented as \"A == - P'*L*L'*P\" with a permutation matrix \"P\"; using just \"L\" - without accounting for \"P\" will give incorrect answers. To - include the effects of permutation, it's typically preferable to - extact \"combined\" factors like \"PtL = F[:PtL]\" (the equivalent - of \"P'*L\") and \"LtP = F[:UP]\" (the equivalent of \"L'*P\"). - - Setting optional \"shift\" keyword argument computes the - factorization of \"A+shift*I\" instead of \"A\". If the \"perm\" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. - -"), - -("Base","cholfact!","cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - - \"cholfact!\" is the same as \"cholfact()\", but saves space by - overwriting the input \"A\", instead of creating a copy. - \"cholfact!\" can also reuse the symbolic factorization from a - different matrix \"F\" with the same structure when used as: - \"cholfact!(F::CholmodFactor, A)\". - -"), - -("Base","ldltfact","ldltfact(A) -> LDLtFactorization - - Compute a factorization of a positive definite matrix \"A\" such - that \"A=L*Diagonal(d)*L'\" where \"L\" is a unit lower triangular - matrix and \"d\" is a vector with non-negative elements. - -"), - -("Base","ldltfact","ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix \"A\". A fill-reducing permutation is used. \"F = - ldltfact(A)\" is most frequently used to solve systems of equations - with \"F\\b\", but also the methods \"diag\", \"det\", \"logdet\" - are defined for \"F\". You can also extract individual factors from - \"F\", using \"F[:L]\". However, since pivoting is on by default, - the factorization is internally represented as \"A == P'*L*D*L'*P\" - with a permutation matrix \"P\"; using just \"L\" without - accounting for \"P\" will give incorrect answers. To include the - effects of permutation, it's typically preferable to extact - \"combined\" factors like \"PtL = F[:PtL]\" (the equivalent of - \"P'*L\") and \"LtP = F[:UP]\" (the equivalent of \"L'*P\"). The - complete list of supported factors is \":L, :PtL, :D, :UP, :U, :LD, - :DU, :PtLD, :DUP\". - - Setting optional \"shift\" keyword argument computes the - factorization of \"A+shift*I\" instead of \"A\". If the \"perm\" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. - -"), - -("Base","qr","qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - - Compute the (pivoted) QR factorization of \"A\" such that either - \"A = Q*R\" or \"A[:,p] = Q*R\". Also see \"qrfact\". The default - is to compute a thin factorization. Note that \"R\" is not extended - with zeros when the full \"Q\" is requested. - -"), - -("Base","qrfact","qrfact(A[, pivot=Val{false}]) -> F - - Computes the QR factorization of \"A\". The return type of \"F\" - depends on the element type of \"A\" and whether pivoting is - specified (with \"pivot==Val{true}\"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \\\"eltype(A)\\\" | \\\"pivot\\\" | Relationship between \\\"F\\\" and \\\"A\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \\\"QR\\\" | not \\\"BlasFloat\\\" | either | \\\"A==F[:Q]*F[:R]\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \\\"QRCompactWY\\\" | \\\"BlasFloat\\\" | \\\"Val{false}\\\" | \\\"A==F[:Q]*F[:R]\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \\\"QRPivoted\\\" | \\\"BlasFloat\\\" | \\\"Val{true}\\\" | \\\"A[:,F[:p]]==F[:Q]*F[:R]\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - - \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", - \"Complex64\" or \"Complex128\". - - The individual components of the factorization \"F\" can be - accessed by indexing: - - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \\\"QR\\\" | \\\"QRCompactWY\\\" | \\\"QRPivoted\\\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:Q]\\\" | \\\"Q\\\" (orthogonal/unitary) part of \\\"QR\\\" | ✓ (\\\"QRPackedQ\\\") | ✓ (\\\"QRCompactWYQ\\\") | ✓ (\\\"QRPackedQ\\\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:R]\\\" | \\\"R\\\" (upper right triangular) part of \\\"QR\\\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:p]\\\" | pivot \\\"Vector\\\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:P]\\\" | (pivot) permutation \\\"Matrix\\\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - - The following functions are available for the \"QR\" objects: - \"size\", \"\\\". When \"A\" is rectangular, \"\\\" will return a - least squares solution and if the solution is not unique, the one - with smallest norm is returned. - - Multiplication with respect to either thin or full \"Q\" is - allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A - \"Q\" matrix can be converted into a regular matrix with \"full()\" - which has a named argument \"thin\". - - Note: \"qrfact\" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the \"Q\" and \"R\" matrices can be stored compactly rather - as two separate dense matrices.The data contained in \"QR\" or - \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, - which is a compact representation of the rotation matrix: - - Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) - - where \\tau_i is the scale factor and v_i is the projection - vector associated with the i^{th} Householder elementary - reflector.The data contained in \"QRCompactWY\" can be used to - construct the \"QRCompactWYQ\" type, which is a compact - representation of the rotation matrix - - Q = I + Y T Y^T - - where \"Y\" is m \\times r lower trapezoidal and \"T\" is r - \\times r upper triangular. The *compact WY* representation - [Schreiber1989] is not to be confused with the older, *WY* - representation [Bischof1987]. (The LAPACK documentation uses - \"V\" in lieu of \"Y\".) - - [Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 - - [Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 - -"), - -("Base","qrfact","qrfact(A) -> SPQR.Factorization - - Compute the QR factorization of a sparse matrix \"A\". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with \"\\\". The function calls the - C library SPQR and a few additional functions from the library are - wrapped but not exported. - -"), - -("Base","qrfact!","qrfact!(A[, pivot=Val{false}]) - - \"qrfact!\" is the same as \"qrfact()\" when A is a subtype of - \"StridedMatrix\", but saves space by overwriting the input \"A\", - instead of creating a copy. - -"), - -("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix - - Converts an orthogonal or unitary matrix stored as a - \"QRCompactWYQ\" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. - - Optionally takes a \"thin\" Boolean argument, which if \"true\" - omits the columns that span the rows of \"R\" in the QR - factorization that are zero. The resulting matrix is the \"Q\" in a - thin QR factorization (sometimes called the reduced QR - factorization). If \"false\", returns a \"Q\" that spans all rows - of \"R\" in its corresponding QR factorization. - -"), - -("Base","bkfact","bkfact(A) -> BunchKaufman - - Compute the Bunch-Kaufman [Bunch1977] factorization of a real - symmetric or complex Hermitian matrix \"A\" and return a - \"BunchKaufman\" object. The following functions are available for - \"BunchKaufman\" objects: \"size\", \"\\\", \"inv\", \"issym\", - \"ishermitian\". - -"), - -("Base","bkfact!","bkfact!(A) -> BunchKaufman - - \"bkfact!\" is the same as \"bkfact()\", but saves space by - overwriting the input \"A\", instead of creating a copy. - -"), - -("Base","sqrtm","sqrtm(A) - - Compute the matrix square root of \"A\". If \"B = sqrtm(A)\", then - \"B*B == A\" within roundoff error. - - \"sqrtm\" uses a polyalgorithm, computing the matrix square root - using Schur factorizations (\"schurfact()\") unless it detects the - matrix to be Hermitian or real symmetric, in which case it computes - the matrix square root from an eigendecomposition (\"eigfact()\"). - In the latter situation for positive definite matrices, the matrix - square root has \"Real\" elements, otherwise it has \"Complex\" - elements. - -"), - -("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - - Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" - for details on the \"balance\" keyword argument. - - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) - - \"eig\" is a wrapper around \"eigfact()\", extracting all parts of - the factorization to a tuple; where possible, using \"eigfact()\" - is recommended. - -"), - -("Base","eig","eig(A, B) -> D, V - - Computes generalized eigenvalues and vectors of \"A\" with respect - to \"B\". - - \"eig\" is a wrapper around \"eigfact()\", extracting all parts of - the factorization to a tuple; where possible, using \"eigfact()\" - is recommended. - -"), - -("Base","eigvals","eigvals(A,[irange,][vl,][vu]) - - Returns the eigenvalues of \"A\". If \"A\" is \"Symmetric\", - \"Hermitian\" or \"SymTridiagonal\", it is possible to calculate - only a subset of the eigenvalues by specifying either a - \"UnitRange\" \"irange\" covering indices of the sorted - eigenvalues, or a pair \"vl\" and \"vu\" for the lower and upper - boundaries of the eigenvalues. - - For general non-symmetric matrices it is possible to specify how - the matrix is balanced before the eigenvector calculation. The - option \"permute=true\" permutes the matrix to become closer to - upper triangular, and \"scale=true\" scales the matrix by its - diagonal elements to make rows and columns more equal in norm. The - default is \"true\" for both options. - -"), - -("Base","eigmax","eigmax(A) - - Returns the largest eigenvalue of \"A\". - -"), - -("Base","eigmin","eigmin(A) - - Returns the smallest eigenvalue of \"A\". - -"), - -("Base","eigvecs","eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - - Returns a matrix \"M\" whose columns are the eigenvectors of \"A\". - (The \"k\"th eigenvector can be obtained from the slice \"M[:, - k]\".) The \"permute\" and \"scale\" keywords are the same as for - \"eigfact()\". - - For \"SymTridiagonal\" matrices, if the optional vector of - eigenvalues \"eigvals\" is specified, returns the specific - corresponding eigenvectors. - -"), - -("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - - Computes the eigenvalue decomposition of \"A\", returning an - \"Eigen\" factorization object \"F\" which contains the eigenvalues - in \"F[:values]\" and the eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the - slice \"F[:vectors][:, k]\".) - - The following functions are available for \"Eigen\" objects: - \"inv\", \"det\". - - If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it - is possible to calculate only a subset of the eigenvalues by - specifying either a \"UnitRange\" \"irange\" covering indices of - the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower - and upper boundaries of the eigenvalues. - - For general nonsymmetric matrices it is possible to specify how the - matrix is balanced before the eigenvector calculation. The option - \"permute=true\" permutes the matrix to become closer to upper - triangular, and \"scale=true\" scales the matrix by its diagonal - elements to make rows and columns more equal in norm. The default - is \"true\" for both options. - -"), - -("Base","eigfact","eigfact(A, B) -> GeneralizedEigen - - Computes the generalized eigenvalue decomposition of \"A\" and - \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" - which contains the generalized eigenvalues in \"F[:values]\" and - the generalized eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th generalized eigenvector can be - obtained from the slice \"F[:vectors][:, k]\".) - -"), - -("Base","eigfact!","eigfact!(A[, B]) - - Same as \"eigfact()\", but saves space by overwriting the input - \"A\" (and \"B\"), instead of creating a copy. - -"), - -("Base","hessfact","hessfact(A) - - Compute the Hessenberg decomposition of \"A\" and return a - \"Hessenberg\" object. If \"F\" is the factorization object, the - unitary matrix can be accessed with \"F[:Q]\" and the Hessenberg - matrix with \"F[:H]\". When \"Q\" is extracted, the resulting type - is the \"HessenbergQ\" object, and may be converted to a regular - matrix with \"full()\". - -"), - -("Base","hessfact!","hessfact!(A) - - \"hessfact!\" is the same as \"hessfact()\", but saves space by - overwriting the input A, instead of creating a copy. - -"), - -("Base","schurfact","schurfact(A) -> Schur - - Computes the Schur factorization of the matrix \"A\". The (quasi) - triangular Schur factor can be obtained from the \"Schur\" object - \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the - unitary/orthogonal Schur vectors can be obtained with - \"F[:vectors]\" or \"F[:Z]\" such that - \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" - can be obtained with \"F[:values]\". - -"), - -("Base","schurfact!","schurfact!(A) - - Computes the Schur factorization of \"A\", overwriting \"A\" in the - process. See \"schurfact()\" - -"), - -("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] - - See \"schurfact()\" - -"), - -("Base","ordschur","ordschur(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" - according to the logical array \"select\" returning a Schur object - \"F\". The selected eigenvalues appear in the leading diagonal of - \"F[:Schur]\" and the the corresponding leading columns of - \"F[:vectors]\" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via \"select\". - -"), - -("Base","ordschur!","ordschur!(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", - overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" - -"), - -("Base","ordschur","ordschur(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\". - -"), - -("Base","ordschur!","ordschur!(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\", - overwriting \"S\" in the process. See \"ordschur()\" - -"), - -("Base","schurfact","schurfact(A, B) -> GeneralizedSchur - - Computes the Generalized Schur (or QZ) factorization of the - matrices \"A\" and \"B\". The (quasi) triangular Schur factors can - be obtained from the \"Schur\" object \"F\" with \"F[:S]\" and - \"F[:T]\", the left unitary/orthogonal Schur vectors can be - obtained with \"F[:left]\" or \"F[:Q]\" and the right - unitary/orthogonal Schur vectors can be obtained with \"F[:right]\" - or \"F[:Z]\" such that \"A=F[:left]*F[:S]*F[:right]'\" and - \"B=F[:left]*F[:T]*F[:right]'\". The generalized eigenvalues of - \"A\" and \"B\" can be obtained with \"F[:alpha]./F[:beta]\". - -"), - -("Base","schur","schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - - See \"schurfact()\" - -"), - -("Base","ordschur","ordschur(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix \"(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" - and returns a GeneralizedSchur object \"GS\". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of - \"A\" and \"B\" can still be obtained with - \"GS[:alpha]./GS[:beta]\". - -"), - -("Base","ordschur!","ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices \"(S, T, Q, Z)\" in the process. See - \"ordschur()\". - -"), - -("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object. See \"ordschur()\". - -"), - -("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - \"ordschur()\". - -"), - -("Base","svdfact","svdfact(A[, thin=true]) -> SVD - - Compute the Singular Value Decomposition (SVD) of \"A\" and return - an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained - from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" - and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The algorithm - produces \"Vt\" and hence \"Vt\" is more efficient to extract than - \"V\". The default is to produce a thin decomposition. - -"), - -("Base","svdfact!","svdfact!(A[, thin=true]) -> SVD - - \"svdfact!\" is the same as \"svdfact()\", but saves space by - overwriting the input A, instead of creating a copy. If \"thin\" is - \"true\", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - -"), - -("Base","svd","svd(A[, thin=true]) -> U, S, V - - Wrapper around \"svdfact\" extracting all parts the factorization - to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. Computes the SVD of A, returning \"U\", vector \"S\", - and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - -"), - -("Base","svdvals","svdvals(A) - - Returns the singular values of \"A\". - -"), - -("Base","svdvals!","svdvals!(A) - - Returns the singular values of \"A\", while saving space by - overwriting the input. - -"), - -("Base","svdfact","svdfact(A, B) -> GeneralizedSVD - - Compute the generalized SVD of \"A\" and \"B\", returning a - \"GeneralizedSVD\" Factorization object \"F\", such that \"A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'\" and \"B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'\". - -"), - -("Base","svd","svd(A, B) -> U, V, Q, D1, D2, R0 - - Wrapper around \"svdfact\" extracting all parts the factorization - to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. The function returns the generalized SVD of \"A\" and - \"B\", returning \"U\", \"V\", \"Q\", \"D1\", \"D2\", and \"R0\" - such that \"A = U*D1*R0*Q'\" and \"B = V*D2*R0*Q'\". - -"), - -("Base","svdvals","svdvals(A, B) - - Return only the singular values from the generalized singular value - decomposition of \"A\" and \"B\". - -"), - -("Base","triu","triu(M) - - Upper triangle of a matrix. - -"), - -("Base","triu","triu(M, k) - - Returns the upper triangle of \"M\" starting from the \"k\"th - superdiagonal. - -"), - -("Base","triu!","triu!(M) - - Upper triangle of a matrix, overwriting \"M\" in the process. - -"), - -("Base","triu!","triu!(M, k) - - Returns the upper triangle of \"M\" starting from the \"k\"th - superdiagonal, overwriting \"M\" in the process. - -"), - -("Base","tril","tril(M) - - Lower triangle of a matrix. - -"), - -("Base","tril","tril(M, k) - - Returns the lower triangle of \"M\" starting from the \"k\"th - subdiagonal. - -"), - -("Base","tril!","tril!(M) - - Lower triangle of a matrix, overwriting \"M\" in the process. - -"), - -("Base","tril!","tril!(M, k) - - Returns the lower triangle of \"M\" starting from the \"k\"th - subdiagonal, overwriting \"M\" in the process. - -"), - -("Base","diagind","diagind(M[, k]) - - A \"Range\" giving the indices of the \"k\"th diagonal of the - matrix \"M\". - -"), - -("Base","diag","diag(M[, k]) - - The \"k\"th diagonal of a matrix, as a vector. Use \"diagm\" to - construct a diagonal matrix. - -"), - -("Base","diagm","diagm(v[, k]) - - Construct a diagonal matrix and place \"v\" on the \"k\"th - diagonal. - -"), - -("Base","scale","scale(A, b) - -"), - -("Base","scale","scale(b, A) - - Scale an array \"A\" by a scalar \"b\", returning a new array. - - If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" - scales each column \"i\" of \"A\" by \"b[i]\" (similar to - \"A*diagm(b)\"), while \"scale(b,A)\" scales each row \"i\" of - \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), returning a new - array. - - Note: for large \"A\", \"scale\" can be much faster than \"A .* b\" - or \"b .* A\", due to the use of BLAS. - -"), - -("Base","scale!","scale!(A, b) - -"), - -("Base","scale!","scale!(b, A) - - Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but - overwriting \"A\" in-place. - - If \"A\" is a matrix and \"b\" is a vector, then \"scale!(A,b)\" - scales each column \"i\" of \"A\" by \"b[i]\" (similar to - \"A*diagm(b)\"), while \"scale!(b,A)\" scales each row \"i\" of - \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), again operating in- - place on \"A\". - -"), - -("Base","Tridiagonal","Tridiagonal(dl, d, du) - - Construct a tridiagonal matrix from the lower diagonal, diagonal, - and upper diagonal, respectively. The result is of type - \"Tridiagonal\" and provides efficient specialized linear solvers, - but may be converted into a regular matrix with \"full()\". - -"), - -("Base","Bidiagonal","Bidiagonal(dv, ev, isupper) - - Constructs an upper (\"isupper=true\") or lower (\"isupper=false\") - bidiagonal matrix using the given diagonal (\"dv\") and off- - diagonal (\"ev\") vectors. The result is of type \"Bidiagonal\" - and provides efficient specialized linear solvers, but may be - converted into a regular matrix with \"full()\". - -"), - -("Base","SymTridiagonal","SymTridiagonal(d, du) - - Construct a real symmetric tridiagonal matrix from the diagonal and - upper diagonal, respectively. The result is of type - \"SymTridiagonal\" and provides efficient specialized eigensolvers, - but may be converted into a regular matrix with \"full()\". - -"), - -("Base","rank","rank(M) - - Compute the rank of a matrix. - -"), - -("Base","norm","norm(A[, p]) - - Compute the \"p\"-norm of a vector or the operator norm of a matrix - \"A\", defaulting to the \"p=2\"-norm. - - For vectors, \"p\" can assume any numeric value (even though not - all values produce a mathematically valid vector norm). In - particular, \"norm(A, Inf)\" returns the largest value in - \"abs(A)\", whereas \"norm(A, -Inf)\" returns the smallest. - - For matrices, valid values of \"p\" are \"1\", \"2\", or \"Inf\". - (Note that for sparse matrices, \"p=2\" is currently not - implemented.) Use \"vecnorm()\" to compute the Frobenius norm. - -"), - -("Base","vecnorm","vecnorm(A[, p]) - - For any iterable container \"A\" (including arrays of any - dimension) of numbers (or any element type for which \"norm\" is - defined), compute the \"p\"-norm (defaulting to \"p=2\") as if - \"A\" were a vector of the corresponding length. - - For example, if \"A\" is a matrix and \"p=2\", then this is - equivalent to the Frobenius norm. - -"), - -("Base","cond","cond(M[, p]) - - Condition number of the matrix \"M\", computed using the operator - \"p\"-norm. Valid values for \"p\" are \"1\", \"2\" (default), or - \"Inf\". - -"), - -("Base","condskeel","condskeel(M[, x, p]) - - \\kappa_S(M, p) & = \\left\\Vert \\left\\vert M \\right\\vert - \\left\\vert M^{-1} \\right\\vert \\right\\Vert_p \\\\ - \\kappa_S(M, x, p) & = \\left\\Vert \\left\\vert M \\right\\vert - \\left\\vert M^{-1} \\right\\vert \\left\\vert x \\right\\vert - \\right\\Vert_p - - Skeel condition number \\kappa_S of the matrix \"M\", optionally - with respect to the vector \"x\", as computed using the operator - \"p\"-norm. \"p\" is \"Inf\" by default, if not provided. Valid - values for \"p\" are \"1\", \"2\", or \"Inf\". - - This quantity is also known in the literature as the Bauer - condition number, relative condition number, or componentwise - relative condition number. - -"), - -("Base","trace","trace(M) - - Matrix trace - -"), - -("Base","det","det(M) - - Matrix determinant - -"), - -("Base","logdet","logdet(M) - - Log of matrix determinant. Equivalent to \"log(det(M))\", but may - provide increased accuracy and/or speed. - -"), - -("Base","inv","inv(M) - - Matrix inverse - -"), - -("Base","pinv","pinv(M[, tol]) - - Computes the Moore-Penrose pseudoinverse. - - For matrices \"M\" with floating point elements, it is convenient - to compute the pseudoinverse by inverting only singular values - above a given threshold, \"tol\". - - The optimal choice of \"tol\" varies both with the value of \"M\" - and the intended application of the pseudoinverse. The default - value of \"tol\" is - \"eps(real(float(one(eltype(M)))))*maximum(size(A))\", which is - essentially machine epsilon for the real part of a matrix element - multiplied by the larger matrix dimension. For inverting dense ill- - conditioned matrices in a least-squares sense, \"tol = - sqrt(eps(real(float(one(eltype(M))))))\" is recommended. - - For more information, see [8859], [B96], [S84], [KY88]. - - [8859] Issue 8859, \"Fix least squares\", - https://github.com/JuliaLang/julia/pull/8859 - - [B96] Åke Björck, \"Numerical Methods for Least Squares - Problems\", SIAM Press, Philadelphia, 1996, \"Other Titles in - Applied Mathematics\", Vol. 51. doi:10.1137/1.9781611971484 - - [S84] G. W. Stewart, \"Rank Degeneracy\", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 - - [KY88] Konstantinos Konstantinides and Kung Yao, - \"Statistical analysis of effective singular values in - matrix rank determination\", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 - -"), - -("Base","nullspace","nullspace(M) - - Basis for nullspace of \"M\". - -"), - -("Base","repmat","repmat(A, n, m) - - Construct a matrix by repeating the given matrix \"n\" times in - dimension 1 and \"m\" times in dimension 2. - -"), - -("Base","repeat","repeat(A, inner = Int[], outer = Int[]) - - Construct an array by repeating the entries of \"A\". The i-th - element of \"inner\" specifies the number of times that the - individual entries of the i-th dimension of \"A\" should be - repeated. The i-th element of \"outer\" specifies the number of - times that a slice along the i-th dimension of \"A\" should be - repeated. - -"), - -("Base","kron","kron(A, B) - - Kronecker tensor product of two vectors or two matrices. - -"), - -("Base","blkdiag","blkdiag(A...) - - Concatenate matrices block-diagonally. Currently only implemented - for sparse matrices. - -"), - -("Base","linreg","linreg(x, y) -> [a; b] - - Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is - the closest line to the given points \"(x,y)\". In other words, - this function determines parameters \"[a, b]\" that minimize the - squared error between \"y\" and \"a+b*x\". - - **Example**: - - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, \"o\") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression - -"), - -("Base","linreg","linreg(x, y, w) - - Weighted least-squares linear regression. - -"), - -("Base","expm","expm(A) - - Matrix exponential. - -"), - -("Base","lyap","lyap(A, C) - - Computes the solution \"X\" to the continuous Lyapunov equation - \"AX + XA' + C = 0\", where no eigenvalue of \"A\" has a zero real - part and no two eigenvalues are negative complex conjugates of each - other. - -"), - -("Base","sylvester","sylvester(A, B, C) - - Computes the solution \"X\" to the Sylvester equation \"AX + XB + C - = 0\", where \"A\", \"B\" and \"C\" have compatible dimensions and - \"A\" and \"-B\" have no eigenvalues with equal real part. - -"), - -("Base","issym","issym(A) -> Bool - - Test whether a matrix is symmetric. - -"), - -("Base","isposdef","isposdef(A) -> Bool - - Test whether a matrix is positive definite. - -"), - -("Base","isposdef!","isposdef!(A) -> Bool - - Test whether a matrix is positive definite, overwriting \"A\" in - the processes. - -"), - -("Base","istril","istril(A) -> Bool - - Test whether a matrix is lower triangular. - -"), - -("Base","istriu","istriu(A) -> Bool - - Test whether a matrix is upper triangular. - -"), - -("Base","isdiag","isdiag(A) -> Bool - - Test whether a matrix is diagonal. - -"), - -("Base","ishermitian","ishermitian(A) -> Bool - - Test whether a matrix is Hermitian. - -"), - -("Base","transpose","transpose(A) - - The transposition operator (\".'\"). - -"), - -("Base","transpose!","transpose!(dest, src) - - Transpose array \"src\" and store the result in the preallocated - array \"dest\", which should have a size corresponding to - \"(size(src,2),size(src,1))\". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. - -"), - -("Base","ctranspose","ctranspose(A) - - The conjugate transposition operator (\"'\"). - -"), - -("Base","ctranspose!","ctranspose!(dest, src) - - Conjugate transpose array \"src\" and store the result in the - preallocated array \"dest\", which should have a size corresponding - to \"(size(src,2),size(src,1))\". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. - -"), - -("Base","eigs","eigs(A[, B], ; nev=6, which=\"LM\", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - - Computes eigenvalues \"d\" of \"A\" using Lanczos or Arnoldi - iterations for real symmetric or general nonsymmetric matrices - respectively. If \"B\" is provided, the generalized eigenproblem is - solved. - - The following keyword arguments are supported: - * \"nev\": Number of eigenvalues - - * \"ncv\": Number of Krylov vectors used in the computation; - should satisfy - - \"nev+1 <= ncv <= n\" for real symmetric problems and - \"nev+2 <= ncv <= n\" for other problems, where \"n\" is - the size of the input matrix \"A\". The default is \"ncv = - max(20,2*nev+1)\". Note that these restrictions limit the - input matrix \"A\" to be of dimension at least 2. - - * \"which\": type of eigenvalues to compute. See the note - below. - - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\"which\\\" | type of eigenvalues | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":LM\\\" | eigenvalues of largest magnitude (default) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":SM\\\" | eigenvalues of smallest magnitude | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":LR\\\" | eigenvalues of largest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":SR\\\" | eigenvalues of smallest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":LI\\\" | eigenvalues of largest imaginary part (nonsymmetric or complex \\\"A\\\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":SI\\\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \\\"A\\\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":BE\\\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \\\"A\\\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - - * \"tol\": tolerance (tol \\le 0.0 defaults to - \"DLAMCH('EPS')\") - - * \"maxiter\": Maximum number of iterations (default = 300) - - * \"sigma\": Specifies the level shift used in inverse - iteration. If \"nothing\" (default), defaults to ordinary - (forward) iterations. Otherwise, find eigenvalues close to - \"sigma\" using shift and invert iterations. - - * \"ritzvec\": Returns the Ritz vectors \"v\" (eigenvectors) - if \"true\" - - * \"v0\": starting vector from which to start the iterations - - \"eigs\" returns the \"nev\" requested eigenvalues in \"d\", the - corresponding Ritz vectors \"v\" (only if \"ritzvec=true\"), the - number of converged eigenvalues \"nconv\", the number of iterations - \"niter\" and the number of matrix vector multiplications - \"nmult\", as well as the final residual vector \"resid\". - - Note: The \"sigma\" and \"which\" keywords interact: the - description of eigenvalues searched for by \"which\" do _not_ - necessarily refer to the eigenvalues of \"A\", but rather the - linear operator constructed by the specification of the iteration - mode implied by \"sigma\". - - +-----------------+------------------------------------+------------------------------------+ - | \\\"sigma\\\" | iteration mode | \\\"which\\\" refers to eigenvalues of | - +-----------------+------------------------------------+------------------------------------+ - | \\\"nothing\\\" | ordinary (forward) | A | - +-----------------+------------------------------------+------------------------------------+ - | real or complex | inverse with level shift \\\"sigma\\\" | (A - \\\\sigma I )^{-1} | - +-----------------+------------------------------------+------------------------------------+ - -"), - -("Base","svds","svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - - \"svds\" computes largest singular values \"s\" of \"A\" using - Lanczos or Arnoldi iterations. Uses \"eigs()\" underneath. - - Inputs are: - * \"A\": Linear operator. It can either subtype of - \"AbstractArray\" (e.g., sparse matrix) or duck typed. For - duck typing \"A\" has to support \"size(A)\", \"eltype(A)\", - \"A * vector\" and \"A' * vector\". - - * \"nsv\": Number of singular values. - - * \"ritzvec\": Whether to return the left and right singular - vectors \"left_sv\" and \"right_sv\", default is \"true\". If - \"false\" the singular vectors are omitted from the output. - - * \"tol\": tolerance, see \"eigs()\". - - * \"maxiter\": Maximum number of iterations, see \"eigs()\". - - **Example**: - - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) - -"), - -("Base","peakflops","peakflops(n; parallel=false) - - \"peakflops\" computes the peak flop rate of the computer by using - double precision \"Base.LinAlg.BLAS.gemm!()\". By default, if no - arguments are specified, it multiplies a matrix of size \"n x n\", - where \"n = 2000\". If the underlying BLAS is using multiple - threads, higher flop rates are realized. The number of BLAS threads - can be set with \"blas_set_num_threads(n)\". - - If the keyword argument \"parallel\" is set to \"true\", - \"peakflops\" is run in parallel on all the worker processors. The - flop rate of the entire parallel computer is returned. When running - in parallel, only 1 BLAS thread is used. The argument \"n\" still - refers to the size of the problem that is solved on each processor. - -"), - -("Base.LinAlg.BLAS","dot","dot(n, X, incx, Y, incy) - - Dot product of two vectors consisting of \"n\" elements of array - \"X\" with stride \"incx\" and \"n\" elements of array \"Y\" with - stride \"incy\". - -"), - -("Base.LinAlg.BLAS","dotu","dotu(n, X, incx, Y, incy) - - Dot function for two complex vectors. - -"), - -("Base.LinAlg.BLAS","dotc","dotc(n, X, incx, U, incy) - - Dot function for two complex vectors conjugating the first vector. - -"), - -("Base.LinAlg.BLAS","blascopy!","blascopy!(n, X, incx, Y, incy) - - Copy \"n\" elements of array \"X\" with stride \"incx\" to array - \"Y\" with stride \"incy\". Returns \"Y\". - -"), - -("Base.LinAlg.BLAS","nrm2","nrm2(n, X, incx) - - 2-norm of a vector consisting of \"n\" elements of array \"X\" with - stride \"incx\". - -"), - -("Base.LinAlg.BLAS","asum","asum(n, X, incx) - - sum of the absolute values of the first \"n\" elements of array - \"X\" with stride \"incx\". - -"), - -("Base.LinAlg.BLAS","axpy!","axpy!(a, X, Y) - - Overwrite \"Y\" with \"a*X + Y\". Returns \"Y\". - -"), - -("Base.LinAlg.BLAS","scal!","scal!(n, a, X, incx) - - Overwrite \"X\" with \"a*X\". Returns \"X\". - -"), - -("Base.LinAlg.BLAS","scal","scal(n, a, X, incx) - - Returns \"a*X\". - -"), - -("Base.LinAlg.BLAS","ger!","ger!(alpha, x, y, A) - - Rank-1 update of the matrix \"A\" with vectors \"x\" and \"y\" as - \"alpha*x*y' + A\". - -"), - -("Base.LinAlg.BLAS","syr!","syr!(uplo, alpha, x, A) - - Rank-1 update of the symmetric matrix \"A\" with vector \"x\" as - \"alpha*x*x.' + A\". When \"uplo\" is 'U' the upper triangle of - \"A\" is updated ('L' for lower triangle). Returns \"A\". - -"), - -("Base.LinAlg.BLAS","syrk!","syrk!(uplo, trans, alpha, A, beta, C) - - Rank-k update of the symmetric matrix \"C\" as \"alpha*A*A.' + - beta*C\" or \"alpha*A.'*A + beta*C\" according to whether \"trans\" - is 'N' or 'T'. When \"uplo\" is 'U' the upper triangle of \"C\" is - updated ('L' for lower triangle). Returns \"C\". - -"), - -("Base.LinAlg.BLAS","syrk","syrk(uplo, trans, alpha, A) - - Returns either the upper triangle or the lower triangle, according - to \"uplo\" ('U' or 'L'), of \"alpha*A*A.'\" or \"alpha*A.'*A\", - according to \"trans\" ('N' or 'T'). - -"), - -("Base.LinAlg.BLAS","her!","her!(uplo, alpha, x, A) - - Methods for complex arrays only. Rank-1 update of the Hermitian - matrix \"A\" with vector \"x\" as \"alpha*x*x' + A\". When - \"uplo\" is 'U' the upper triangle of \"A\" is updated ('L' for - lower triangle). Returns \"A\". - -"), - -("Base.LinAlg.BLAS","herk!","herk!(uplo, trans, alpha, A, beta, C) - - Methods for complex arrays only. Rank-k update of the Hermitian - matrix \"C\" as \"alpha*A*A' + beta*C\" or \"alpha*A'*A + beta*C\" - according to whether \"trans\" is 'N' or 'T'. When \"uplo\" is 'U' - the upper triangle of \"C\" is updated ('L' for lower triangle). - Returns \"C\". - -"), - -("Base.LinAlg.BLAS","herk","herk(uplo, trans, alpha, A) - - Methods for complex arrays only. Returns either the upper triangle - or the lower triangle, according to \"uplo\" ('U' or 'L'), of - \"alpha*A*A'\" or \"alpha*A'*A\", according to \"trans\" ('N' or - 'T'). - -"), - -("Base.LinAlg.BLAS","gbmv!","gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - - Update vector \"y\" as \"alpha*A*x + beta*y\" or \"alpha*A'*x + - beta*y\" according to \"trans\" ('N' or 'T'). The matrix \"A\" is - a general band matrix of dimension \"m\" by \"size(A,2)\" with - \"kl\" sub-diagonals and \"ku\" super-diagonals. Returns the - updated \"y\". - -"), - -("Base.LinAlg.BLAS","gbmv","gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - - Returns \"alpha*A*x\" or \"alpha*A'*x\" according to \"trans\" ('N' - or 'T'). The matrix \"A\" is a general band matrix of dimension - \"m\" by \"size(A,2)\" with \"kl\" sub-diagonals and \"ku\" super- - diagonals. - -"), - -("Base.LinAlg.BLAS","sbmv!","sbmv!(uplo, k, alpha, A, x, beta, y) - - Update vector \"y\" as \"alpha*A*x + beta*y\" where \"A\" is a a - symmetric band matrix of order \"size(A,2)\" with \"k\" super- - diagonals stored in the argument \"A\". The storage layout for - \"A\" is described the reference BLAS module, level-2 BLAS at - http://www.netlib.org/lapack/explore-html/. - - Returns the updated \"y\". - -"), - -("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, alpha, A, x) - - Returns \"alpha*A*x\" where \"A\" is a symmetric band matrix of - order \"size(A,2)\" with \"k\" super-diagonals stored in the - argument \"A\". - -"), - -("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, A, x) - - Returns \"A*x\" where \"A\" is a symmetric band matrix of order - \"size(A,2)\" with \"k\" super-diagonals stored in the argument - \"A\". - -"), - -("Base.LinAlg.BLAS","gemm!","gemm!(tA, tB, alpha, A, B, beta, C) - - Update \"C\" as \"alpha*A*B + beta*C\" or the other three variants - according to \"tA\" (transpose \"A\") and \"tB\". Returns the - updated \"C\". - -"), - -("Base.LinAlg.BLAS","gemm","gemm(tA, tB, alpha, A, B) - - Returns \"alpha*A*B\" or the other three variants according to - \"tA\" (transpose \"A\") and \"tB\". - -"), - -("Base.LinAlg.BLAS","gemm","gemm(tA, tB, A, B) - - Returns \"A*B\" or the other three variants according to \"tA\" - (transpose \"A\") and \"tB\". - -"), - -("Base.LinAlg.BLAS","gemv!","gemv!(tA, alpha, A, x, beta, y) - - Update the vector \"y\" as \"alpha*A*x + beta*y\" or \"alpha*A'x + - beta*y\" according to \"tA\" (transpose \"A\"). Returns the updated - \"y\". - -"), - -("Base.LinAlg.BLAS","gemv","gemv(tA, alpha, A, x) - - Returns \"alpha*A*x\" or \"alpha*A'x\" according to \"tA\" - (transpose \"A\"). - -"), - -("Base.LinAlg.BLAS","gemv","gemv(tA, A, x) - - Returns \"A*x\" or \"A'x\" according to \"tA\" (transpose \"A\"). - -"), - -("Base.LinAlg.BLAS","symm!","symm!(side, ul, alpha, A, B, beta, C) - - Update \"C\" as \"alpha*A*B + beta*C\" or \"alpha*B*A + beta*C\" - according to \"side\". \"A\" is assumed to be symmetric. Only the - \"ul\" triangle of \"A\" is used. Returns the updated \"C\". - -"), - -("Base.LinAlg.BLAS","symm","symm(side, ul, alpha, A, B) - - Returns \"alpha*A*B\" or \"alpha*B*A\" according to \"side\". \"A\" - is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is - used. - -"), - -("Base.LinAlg.BLAS","symm","symm(side, ul, A, B) - - Returns \"A*B\" or \"B*A\" according to \"side\". \"A\" is assumed - to be symmetric. Only the \"ul\" triangle of \"A\" is used. - -"), - -("Base.LinAlg.BLAS","symm","symm(tA, tB, alpha, A, B) - - Returns \"alpha*A*B\" or the other three variants according to - \"tA\" (transpose \"A\") and \"tB\". - -"), - -("Base.LinAlg.BLAS","symv!","symv!(ul, alpha, A, x, beta, y) - - Update the vector \"y\" as \"alpha*A*x + beta*y\". \"A\" is assumed - to be symmetric. Only the \"ul\" triangle of \"A\" is used. - Returns the updated \"y\". - -"), - -("Base.LinAlg.BLAS","symv","symv(ul, alpha, A, x) - - Returns \"alpha*A*x\". \"A\" is assumed to be symmetric. Only the - \"ul\" triangle of \"A\" is used. - -"), - -("Base.LinAlg.BLAS","symv","symv(ul, A, x) - - Returns \"A*x\". \"A\" is assumed to be symmetric. Only the - \"ul\" triangle of \"A\" is used. - -"), - -("Base.LinAlg.BLAS","trmm!","trmm!(side, ul, tA, dA, alpha, A, B) - - Update \"B\" as \"alpha*A*B\" or one of the other three variants - determined by \"side\" (A on left or right) and \"tA\" (transpose - A). Only the \"ul\" triangle of \"A\" is used. \"dA\" indicates if - \"A\" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated \"B\". - -"), - -("Base.LinAlg.BLAS","trmm","trmm(side, ul, tA, dA, alpha, A, B) - - Returns \"alpha*A*B\" or one of the other three variants determined - by \"side\" (A on left or right) and \"tA\" (transpose A). Only the - \"ul\" triangle of \"A\" is used. \"dA\" indicates if \"A\" is - unit-triangular (the diagonal is assumed to be all ones). - -"), - -("Base.LinAlg.BLAS","trsm!","trsm!(side, ul, tA, dA, alpha, A, B) - - Overwrite \"B\" with the solution to \"A*X = alpha*B\" or one of - the other three variants determined by \"side\" (A on left or right - of \"X\") and \"tA\" (transpose A). Only the \"ul\" triangle of - \"A\" is used. \"dA\" indicates if \"A\" is unit-triangular (the - diagonal is assumed to be all ones). Returns the updated \"B\". - -"), - -("Base.LinAlg.BLAS","trsm","trsm(side, ul, tA, dA, alpha, A, B) - - Returns the solution to \"A*X = alpha*B\" or one of the other three - variants determined by \"side\" (A on left or right of \"X\") and - \"tA\" (transpose A). Only the \"ul\" triangle of \"A\" is used. - \"dA\" indicates if \"A\" is unit-triangular (the diagonal is - assumed to be all ones). - -"), - -("Base.LinAlg.BLAS","trmv!","trmv!(side, ul, tA, dA, alpha, A, b) - - Update \"b\" as \"alpha*A*b\" or one of the other three variants - determined by \"side\" (A on left or right) and \"tA\" (transpose - A). Only the \"ul\" triangle of \"A\" is used. \"dA\" indicates if - \"A\" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated \"b\". - -"), - -("Base.LinAlg.BLAS","trmv","trmv(side, ul, tA, dA, alpha, A, b) - - Returns \"alpha*A*b\" or one of the other three variants determined - by \"side\" (A on left or right) and \"tA\" (transpose A). Only the - \"ul\" triangle of \"A\" is used. \"dA\" indicates if \"A\" is - unit-triangular (the diagonal is assumed to be all ones). - -"), - -("Base.LinAlg.BLAS","trsv!","trsv!(ul, tA, dA, A, b) - - Overwrite \"b\" with the solution to \"A*x = b\" or one of the - other two variants determined by \"tA\" (transpose A) and \"ul\" - (triangle of \"A\" used). \"dA\" indicates if \"A\" is unit- - triangular (the diagonal is assumed to be all ones). Returns the - updated \"b\". - -"), - -("Base.LinAlg.BLAS","trsv","trsv(ul, tA, dA, A, b) - - Returns the solution to \"A*x = b\" or one of the other two - variants determined by \"tA\" (transpose A) and \"ul\" (triangle of - \"A\" is used.) \"dA\" indicates if \"A\" is unit-triangular (the - diagonal is assumed to be all ones). - -"), - -("Base.LinAlg.BLAS","blas_set_num_threads","blas_set_num_threads(n) - - Set the number of threads the BLAS library should use. - -"), - -("Base.LinAlg.BLAS","I","I - - An object of type \"UniformScaling\", representing an identity - matrix of any size. - -"), - -("Base","-","-(x) - - Unary minus operator. - -"), - -("Base","+","+(x, y...) - - Addition operator. \"x+y+z+...\" calls this function with all - arguments, i.e. \"+(x, y, z, ...)\". - -"), - -("Base","-","-(x, y) - - Subtraction operator. - -"), - -("Base","*","*(x, y...) - - Multiplication operator. \"x*y*z*...\" calls this function with all - arguments, i.e. \"*(x, y, z, ...)\". - -"), - -("Base","/","/(x, y) - - Right division operator: multiplication of \"x\" by the inverse of - \"y\" on the right. Gives floating-point results for integer - arguments. - -"), - -("Base","\\","\\(x, y) - - Left division operator: multiplication of \"y\" by the inverse of - \"x\" on the left. Gives floating-point results for integer - arguments. - -"), - -("Base","^","^(x, y) - - Exponentiation operator. - -"), - -("Base",".+",".+(x, y) - - Element-wise addition operator. - -"), - -("Base",".-",".-(x, y) - - Element-wise subtraction operator. - -"), - -("Base",".*",".*(x, y) - - Element-wise multiplication operator. - -"), - -("Base","./","./(x, y) - - Element-wise right division operator. - -"), - -("Base",".\\",".\\(x, y) - - Element-wise left division operator. - -"), - -("Base",".^",".^(x, y) - - Element-wise exponentiation operator. - -"), - -("Base","fma","fma(x, y, z) - - Computes \"x*y+z\" without rounding the intermediate result - \"x*y\". On some systems this is significantly more expensive than - \"x*y+z\". \"fma\" is used to improve accuracy in certain - algorithms. See \"muladd\". - -"), - -("Base","muladd","muladd(x, y, z) - - Combined multiply-add, computes \"x*y+z\" in an efficient manner. - This may on some systems be equivalent to \"x*y+z\", or to - \"fma(x,y,z)\". \"muladd\" is used to improve performance. See - \"fma\". - -"), - -("Base","div","div(x, y) -÷(x, y) - - The quotient from Euclidean division. Computes \"x/y\", truncated - to an integer. - -"), - -("Base","fld","fld(x, y) - - Largest integer less than or equal to \"x/y\". - -"), - -("Base","cld","cld(x, y) - - Smallest integer larger than or equal to \"x/y\". - -"), - -("Base","mod","mod(x, y) - - Modulus after division, returning in the range [0,``y``), if \"y\" - is positive, or (\"y\",0] if \"y\" is negative. - -"), - -("Base","mod2pi","mod2pi(x) - - Modulus after division by 2pi, returning in the range [0,2pi). - - This function computes a floating point representation of the - modulus after division by numerically exact 2pi, and is therefore - not exactly the same as mod(x,2pi), which would compute the modulus - of x relative to division by the floating-point number 2pi. - -"), - -("Base","rem","rem(x, y) -%(x, y) - - Remainder from Euclidean division, returning a value of the same - sign as``x``, and smaller in magnitude than \"y\". This value is - always exact. - -"), - -("Base","divrem","divrem(x, y) - - The quotient and remainder from Euclidean division. Equivalent to - \"(x÷y, x%y)\". - -"), - -("Base","fldmod","fldmod(x, y) - - The floored quotient and modulus after division. Equivalent to - \"(fld(x,y), mod(x,y))\". - -"), - -("Base","mod1","mod1(x, m) - - Modulus after division, returning in the range (0,m] - -"), - -("Base","rem1","rem1(x, m) - - Remainder after division, returning in the range (0,m] - -"), - -("Base","//","//(num, den) - - Divide two integers or rational numbers, giving a \"Rational\" - result. - -"), - -("Base","rationalize","rationalize([Type=Int], x; tol=eps(x)) - - Approximate floating point number \"x\" as a Rational number with - components of the given integer type. The result will differ from - \"x\" by no more than \"tol\". - -"), - -("Base","num","num(x) - - Numerator of the rational representation of \"x\" - -"), - -("Base","den","den(x) - - Denominator of the rational representation of \"x\" - -"), - -("Base","<<","<<(x, n) - - Left bit shift operator. - -"), - -("Base",">>",">>(x, n) - - Right bit shift operator, preserving the sign of \"x\". - -"), - -("Base",">>>",">>>(x, n) - - Unsigned right bit shift operator. - -"), - -("Base",":",":(start[, step], stop) - - Range operator. \"a:b\" constructs a range from \"a\" to \"b\" with - a step size of 1, and \"a:s:b\" is similar but uses a step size of - \"s\". These syntaxes call the function \"colon\". The colon is - also used in indexing to select whole dimensions. - -"), - -("Base","colon","colon(start[, step], stop) - - Called by \":\" syntax for constructing ranges. - -"), - -("Base","range","range(start[, step], length) - - Construct a range by length, given a starting value and optional - step (defaults to 1). - -"), - -("Base","==","==(x, y) - - Generic equality operator, giving a single \"Bool\" result. Falls - back to \"===\". Should be implemented for all types with a notion - of equality, based on the abstract value that an instance - represents. For example, all numeric types are compared by numeric - value, ignoring type. Strings are compared as sequences of - characters, ignoring encoding. - - Follows IEEE semantics for floating-point numbers. - - Collections should generally implement \"==\" by calling \"==\" - recursively on all contents. - - New numeric types should implement this function for two arguments - of the new type, and handle comparison to other types via promotion - rules where possible. - -"), - -("Base","!=","!=(x, y) -≠(x, y) - - Not-equals comparison operator. Always gives the opposite answer as - \"==\". New types should generally not implement this, and rely on - the fallback definition \"!=(x,y) = !(x==y)\" instead. - -"), - -("Base","===","===(x, y) -≡(x, y) - - See the \"is()\" operator - -"), - -("Base","!==","!==(x, y) -≢(x, y) - - Equivalent to \"!is(x, y)\" - -"), - -("Base","<","<(x, y) - - Less-than comparison operator. New numeric types should implement - this function for two arguments of the new type. Because of the - behavior of floating-point NaN values, \"<\" implements a partial - order. Types with a canonical partial order should implement \"<\", - and types with a canonical total order should implement \"isless\". - -"), - -("Base","<=","<=(x, y) -≤(x, y) - - Less-than-or-equals comparison operator. - -"), - -("Base",">",">(x, y) - - Greater-than comparison operator. Generally, new types should - implement \"<\" instead of this function, and rely on the fallback - definition \">(x,y) = y=",">=(x, y) -≥(x, y) - - Greater-than-or-equals comparison operator. - -"), - -("Base",".==",".==(x, y) - - Element-wise equality comparison operator. - -"), - -("Base",".!=",".!=(x, y) -.≠(x, y) - - Element-wise not-equals comparison operator. - -"), - -("Base",".<",".<(x, y) - - Element-wise less-than comparison operator. - -"), - -("Base",".<=",".<=(x, y) -.≤(x, y) - - Element-wise less-than-or-equals comparison operator. - -"), - -("Base",".>",".>(x, y) - - Element-wise greater-than comparison operator. - -"), - -("Base",".>=",".>=(x, y) -.≥(x, y) - - Element-wise greater-than-or-equals comparison operator. - -"), - -("Base","cmp","cmp(x, y) - - Return -1, 0, or 1 depending on whether \"x\" is less than, equal - to, or greater than \"y\", respectively. Uses the total order - implemented by \"isless\". For floating-point numbers, uses \"<\" - but throws an error for unordered arguments. - -"), - -("Base","~","~(x) - - Bitwise not - -"), - -("Base","&","&(x, y) - - Bitwise and - -"), - -("Base","|","|(x, y) - - Bitwise or - -"), - -("Base","\$","\$(x, y) - - Bitwise exclusive or - -"), - -("Base","!","!(x) - - Boolean not - -"), - -("","x && y","x && y - - Short-circuiting boolean and - -"), - -("","x || y","x || y - - Short-circuiting boolean or - -"), - -("Base","A_ldiv_Bc","A_ldiv_Bc(a, b) - - Matrix operator A \\ B^H - -"), - -("Base","A_ldiv_Bt","A_ldiv_Bt(a, b) - - Matrix operator A \\ B^T - -"), - -("Base","A_mul_B!","A_mul_B!(Y, A, B) -> Y - - Calculates the matrix-matrix or matrix-vector product *A B* and - stores the result in *Y*, overwriting the existing value of *Y*. - - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); - - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 - -"), - -("Base","A_mul_Bc","A_mul_Bc(...) - - Matrix operator A B^H - -"), - -("Base","A_mul_Bt","A_mul_Bt(...) - - Matrix operator A B^T - -"), - -("Base","A_rdiv_Bc","A_rdiv_Bc(...) - - Matrix operator A / B^H - -"), - -("Base","A_rdiv_Bt","A_rdiv_Bt(a, b) - - Matrix operator A / B^T - -"), - -("Base","Ac_ldiv_B","Ac_ldiv_B(...) - - Matrix operator A^H \\ B - -"), - -("Base","Ac_ldiv_Bc","Ac_ldiv_Bc(...) - - Matrix operator A^H \\ B^H - -"), - -("Base","Ac_mul_B","Ac_mul_B(...) - - Matrix operator A^H B - -"), - -("Base","Ac_mul_Bc","Ac_mul_Bc(...) - - Matrix operator A^H B^H - -"), - -("Base","Ac_rdiv_B","Ac_rdiv_B(a, b) - - Matrix operator A^H / B - -"), - -("Base","Ac_rdiv_Bc","Ac_rdiv_Bc(a, b) - - Matrix operator A^H / B^H - -"), - -("Base","At_ldiv_B","At_ldiv_B(...) - - Matrix operator A^T \\ B - -"), - -("Base","At_ldiv_Bt","At_ldiv_Bt(...) - - Matrix operator A^T \\ B^T - -"), - -("Base","At_mul_B","At_mul_B(...) - - Matrix operator A^T B - -"), - -("Base","At_mul_Bt","At_mul_Bt(...) - - Matrix operator A^T B^T - -"), - -("Base","At_rdiv_B","At_rdiv_B(a, b) - - Matrix operator A^T / B - -"), - -("Base","At_rdiv_Bt","At_rdiv_Bt(a, b) - - Matrix operator A^T / B^T - -"), - -("Base","isapprox","isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - - Inexact equality comparison - behaves slightly different depending - on types of input args: - - * For \"FloatingPoint\" numbers, \"isapprox\" returns \"true\" if - \"abs(x-y) <= atol + rtol*max(abs(x), abs(y))\". - - * For \"Integer\" and \"Rational\" numbers, \"isapprox\" returns - \"true\" if \"abs(x-y) <= atol\". The *rtol* argument is ignored. - If one of \"x\" and \"y\" is \"FloatingPoint\", the other is - promoted, and the method above is called instead. - - * For \"Complex\" numbers, the distance in the complex plane is - compared, using the same criterion as above. - - For default tolerance arguments, \"maxeps = max(eps(abs(x)), - eps(abs(y)))\". - -"), - -("Base","sin","sin(x) - - Compute sine of \"x\", where \"x\" is in radians - -"), - -("Base","cos","cos(x) - - Compute cosine of \"x\", where \"x\" is in radians - -"), - -("Base","tan","tan(x) - - Compute tangent of \"x\", where \"x\" is in radians - -"), - -("Base","sind","sind(x) - - Compute sine of \"x\", where \"x\" is in degrees - -"), - -("Base","cosd","cosd(x) - - Compute cosine of \"x\", where \"x\" is in degrees - -"), - -("Base","tand","tand(x) - - Compute tangent of \"x\", where \"x\" is in degrees - -"), - -("Base","sinpi","sinpi(x) - - Compute \\sin(\\pi x) more accurately than \"sin(pi*x)\", - especially for large \"x\". - -"), - -("Base","cospi","cospi(x) - - Compute \\cos(\\pi x) more accurately than \"cos(pi*x)\", - especially for large \"x\". - -"), - -("Base","sinh","sinh(x) - - Compute hyperbolic sine of \"x\" - -"), - -("Base","cosh","cosh(x) - - Compute hyperbolic cosine of \"x\" - -"), - -("Base","tanh","tanh(x) - - Compute hyperbolic tangent of \"x\" - -"), - -("Base","asin","asin(x) - - Compute the inverse sine of \"x\", where the output is in radians - -"), - -("Base","acos","acos(x) - - Compute the inverse cosine of \"x\", where the output is in radians - -"), - -("Base","atan","atan(x) - - Compute the inverse tangent of \"x\", where the output is in - radians - -"), - -("Base","atan2","atan2(y, x) - - Compute the inverse tangent of \"y/x\", using the signs of both - \"x\" and \"y\" to determine the quadrant of the return value. - -"), - -("Base","asind","asind(x) - - Compute the inverse sine of \"x\", where the output is in degrees - -"), - -("Base","acosd","acosd(x) - - Compute the inverse cosine of \"x\", where the output is in degrees - -"), - -("Base","atand","atand(x) - - Compute the inverse tangent of \"x\", where the output is in - degrees - -"), - -("Base","sec","sec(x) - - Compute the secant of \"x\", where \"x\" is in radians - -"), - -("Base","csc","csc(x) - - Compute the cosecant of \"x\", where \"x\" is in radians - -"), - -("Base","cot","cot(x) - - Compute the cotangent of \"x\", where \"x\" is in radians - -"), - -("Base","secd","secd(x) - - Compute the secant of \"x\", where \"x\" is in degrees - -"), - -("Base","cscd","cscd(x) - - Compute the cosecant of \"x\", where \"x\" is in degrees - -"), - -("Base","cotd","cotd(x) - - Compute the cotangent of \"x\", where \"x\" is in degrees - -"), - -("Base","asec","asec(x) - - Compute the inverse secant of \"x\", where the output is in radians - -"), - -("Base","acsc","acsc(x) - - Compute the inverse cosecant of \"x\", where the output is in - radians - -"), - -("Base","acot","acot(x) - - Compute the inverse cotangent of \"x\", where the output is in - radians - -"), - -("Base","asecd","asecd(x) - - Compute the inverse secant of \"x\", where the output is in degrees - -"), - -("Base","acscd","acscd(x) - - Compute the inverse cosecant of \"x\", where the output is in - degrees - -"), - -("Base","acotd","acotd(x) - - Compute the inverse cotangent of \"x\", where the output is in - degrees - -"), - -("Base","sech","sech(x) - - Compute the hyperbolic secant of \"x\" - -"), - -("Base","csch","csch(x) - - Compute the hyperbolic cosecant of \"x\" - -"), - -("Base","coth","coth(x) - - Compute the hyperbolic cotangent of \"x\" - -"), - -("Base","asinh","asinh(x) - - Compute the inverse hyperbolic sine of \"x\" - -"), - -("Base","acosh","acosh(x) - - Compute the inverse hyperbolic cosine of \"x\" - -"), - -("Base","atanh","atanh(x) - - Compute the inverse hyperbolic tangent of \"x\" - -"), - -("Base","asech","asech(x) - - Compute the inverse hyperbolic secant of \"x\" - -"), - -("Base","acsch","acsch(x) - - Compute the inverse hyperbolic cosecant of \"x\" - -"), - -("Base","acoth","acoth(x) - - Compute the inverse hyperbolic cotangent of \"x\" - -"), - -("Base","sinc","sinc(x) - - Compute \\sin(\\pi x) / (\\pi x) if x \\neq 0, and 1 if x = 0. - -"), - -("Base","cosc","cosc(x) - - Compute \\cos(\\pi x) / x - \\sin(\\pi x) / (\\pi x^2) if x \\neq - 0, and 0 if x = 0. This is the derivative of \"sinc(x)\". - -"), - -("Base","deg2rad","deg2rad(x) - - Convert \"x\" from degrees to radians - -"), - -("Base","rad2deg","rad2deg(x) - - Convert \"x\" from radians to degrees - -"), - -("Base","hypot","hypot(x, y) - - Compute the \\sqrt{x^2+y^2} avoiding overflow and underflow - -"), - -("Base","log","log(x) - - Compute the natural logarithm of \"x\". Throws \"DomainError\" for - negative \"Real\" arguments. Use complex negative arguments to - obtain complex results. - - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. - -"), - -("Base","log","log(b, x) - - Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log2","log2(x) - - Compute the logarithm of \"x\" to base 2. Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log10","log10(x) - - Compute the logarithm of \"x\" to base 10. Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log1p","log1p(x) - - Accurate natural logarithm of \"1+x\". Throws \"DomainError\" for - \"Real\" arguments less than -1. - - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. - -"), - -("Base","frexp","frexp(val) - - Return \"(x,exp)\" such that \"x\" has a magnitude in the interval - \"[1/2, 1)\" or 0, and val = x \\times 2^{exp}. - -"), - -("Base","exp","exp(x) - - Compute e^x - -"), - -("Base","exp2","exp2(x) - - Compute 2^x - -"), - -("Base","exp10","exp10(x) - - Compute 10^x - -"), - -("Base","ldexp","ldexp(x, n) - - Compute x \\times 2^n - -"), - -("Base","modf","modf(x) - - Return a tuple (fpart,ipart) of the fractional and integral parts - of a number. Both parts have the same sign as the argument. - -"), - -("Base","expm1","expm1(x) - - Accurately compute e^x-1 - -"), - -("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) - - \"round(x)\" rounds \"x\" to an integer value according to the - default rounding mode (see \"get_rounding()\"), returning a value - of the same type as \"x\". By default (\"RoundNearest\"), this will - round to the nearest integer, with ties (fractional values of 0.5) - being rounded to the even integer. - - julia> round(1.7) - 2.0 - - julia> round(1.5) - 2.0 - - julia> round(2.5) - 2.0 - - The optional \"RoundingMode\" argument will change how the number - gets rounded. - - \"round(T, x, [r::RoundingMode])\" converts the result to type - \"T\", throwing an \"InexactError\" if the value is not - representable. - - \"round(x, digits)\" rounds to the specified number of digits after - the decimal place (or before if negative). \"round(x, digits, - base)\" rounds using a base other than 10. - - julia> round(pi, 2) - 3.14 - - julia> round(pi, 3, 2) - 3.125 - - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the \"Float64\" value represented by \"1.15\" is - actually *less* than 1.15, yet will be rounded to 1.2. - - julia> x = 1.15 - 1.15 - - julia> @sprintf \"%.20f\" x - \"1.14999999999999991118\" - - julia> x < 115//100 - true - - julia> round(x, 1) - 1.2 - -"), - -("Base","RoundingMode","RoundingMode - - A type which controls rounding behavior. Currently supported - rounding modes are: - - * \"RoundNearest\" (default) - - * \"RoundNearestTiesAway\" - - * \"RoundNearestTiesUp\" - - * \"RoundToZero\" - - * \"RoundUp\" - - * \"RoundDown\" - -"), - -("Base","RoundNearest","RoundNearest - - The default rounding mode. Rounds to the nearest integer, with ties - (fractional values of 0.5) being rounded to the nearest even - integer. - -"), - -("Base","RoundNearestTiesAway","RoundNearestTiesAway - - Rounds to nearest integer, with ties rounded away from zero (C/C++ - \"round()\" behaviour). - -"), - -("Base","RoundNearestTiesUp","RoundNearestTiesUp - - Rounds to nearest integer, with ties rounded toward positive - infinity (Java/JavaScript \"round()\" behaviour). - -"), - -("Base","RoundToZero","RoundToZero - - \"round()\" using this rounding mode is an alias for \"trunc()\". - -"), - -("Base","RoundUp","RoundUp - - \"round()\" using this rounding mode is an alias for \"ceil()\". - -"), - -("Base","RoundDown","RoundDown - - \"round()\" using this rounding mode is an alias for \"floor()\". - -"), - -("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) - - Returns the nearest integral value of the same type as the complex- - valued \"z\" to \"z\", breaking ties using the specified - \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding - the real components while the second is used for rounding the - imaginary components. - -"), - -("Base","ceil","ceil([T], x[, digits[, base]]) - - \"ceil(x)\" returns the nearest integral value of the same type as - \"x\" that is greater than or equal to \"x\". - - \"ceil(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","floor","floor([T], x[, digits[, base]]) - - \"floor(x)\" returns the nearest integral value of the same type as - \"x\" that is less than or equal to \"x\". - - \"floor(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","trunc","trunc([T], x[, digits[, base]]) - - \"trunc(x)\" returns the nearest integral value of the same type as - \"x\" whose absolute value is less than or equal to \"x\". - - \"trunc(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","unsafe_trunc","unsafe_trunc(T, x) - - \"unsafe_trunc(T, x)\" returns the nearest integral value of type - \"T\" whose absolute value is less than or equal to \"x\". If the - value is not representable by \"T\", an arbitrary value will be - returned. - -"), - -("Base","signif","signif(x, digits[, base]) - - Rounds (in the sense of \"round\") \"x\" so that there are - \"digits\" significant digits, under a base \"base\" - representation, default 10. E.g., \"signif(123.456, 2)\" is - \"120.0\", and \"signif(357.913, 4, 2)\" is \"352.0\". - -"), - -("Base","min","min(x, y, ...) - - Return the minimum of the arguments. Operates elementwise over - arrays. - -"), - -("Base","max","max(x, y, ...) - - Return the maximum of the arguments. Operates elementwise over - arrays. - -"), - -("Base","minmax","minmax(x, y) - - Return \"(min(x,y), max(x,y))\". See also: \"extrema()\" that - returns \"(minimum(x), maximum(x))\" - -"), - -("Base","clamp","clamp(x, lo, hi) - - Return x if \"lo <= x <= hi\". If \"x < lo\", return \"lo\". If \"x - > hi\", return \"hi\". Arguments are promoted to a common type. - Operates elementwise over \"x\" if it is an array. - -"), - -("Base","abs","abs(x) - - Absolute value of \"x\" - -"), - -("Base","abs2","abs2(x) - - Squared absolute value of \"x\" - -"), - -("Base","copysign","copysign(x, y) - - Return \"x\" such that it has the same sign as \"y\" - -"), - -("Base","sign","sign(x) - - Return \"+1\" if \"x\" is positive, \"0\" if \"x == 0\", and \"-1\" - if \"x\" is negative. - -"), - -("Base","signbit","signbit(x) - - Returns \"true\" if the value of the sign of \"x\" is negative, - otherwise \"false\". - -"), - -("Base","flipsign","flipsign(x, y) - - Return \"x\" with its sign flipped if \"y\" is negative. For - example \"abs(x) = flipsign(x,x)\". - -"), - -("Base","sqrt","sqrt(x) - - Return \\sqrt{x}. Throws \"DomainError\" for negative \"Real\" - arguments. Use complex negative arguments instead. The prefix - operator \"√\" is equivalent to \"sqrt\". - -"), - -("Base","isqrt","isqrt(n) - - Integer square root: the largest integer \"m\" such that \"m*m <= - n\". - -"), - -("Base","cbrt","cbrt(x) - - Return x^{1/3}. The prefix operator \"∛\" is equivalent to - \"cbrt\". - -"), - -("Base","erf","erf(x) - - Compute the error function of \"x\", defined by - \\frac{2}{\\sqrt{\\pi}} \\int_0^x e^{-t^2} dt for arbitrary complex - \"x\". - -"), - -("Base","erfc","erfc(x) - - Compute the complementary error function of \"x\", defined by 1 - - \\operatorname{erf}(x). - -"), - -("Base","erfcx","erfcx(x) - - Compute the scaled complementary error function of \"x\", defined - by e^{x^2} \\operatorname{erfc}(x). Note also that - \\operatorname{erfcx}(-ix) computes the Faddeeva function w(x). - -"), - -("Base","erfi","erfi(x) - - Compute the imaginary error function of \"x\", defined by -i - \\operatorname{erf}(ix). - -"), - -("Base","dawson","dawson(x) - - Compute the Dawson function (scaled imaginary error function) of - \"x\", defined by \\frac{\\sqrt{\\pi}}{2} e^{-x^2} - \\operatorname{erfi}(x). - -"), - -("Base","erfinv","erfinv(x) - - Compute the inverse error function of a real \"x\", defined by - \\operatorname{erf}(\\operatorname{erfinv}(x)) = x. - -"), - -("Base","erfcinv","erfcinv(x) - - Compute the inverse error complementary function of a real \"x\", - defined by \\operatorname{erfc}(\\operatorname{erfcinv}(x)) = x. - -"), - -("Base","real","real(z) - - Return the real part of the complex number \"z\" - -"), - -("Base","imag","imag(z) - - Return the imaginary part of the complex number \"z\" - -"), - -("Base","reim","reim(z) - - Return both the real and imaginary parts of the complex number - \"z\" - -"), - -("Base","conj","conj(z) - - Compute the complex conjugate of a complex number \"z\" - -"), - -("Base","angle","angle(z) - - Compute the phase angle in radians of a complex number \"z\" - -"), - -("Base","cis","cis(z) - - Return \\exp(iz). - -"), - -("Base","binomial","binomial(n, k) - - Number of ways to choose \"k\" out of \"n\" items - -"), - -("Base","factorial","factorial(n) - - Factorial of \"n\". If \"n\" is an \"Integer\", the factorial is - computed as an integer (promoted to at least 64 bits). Note that - this may overflow if \"n\" is not small, but you can use - \"factorial(big(n))\" to compute the result exactly in arbitrary - precision. If \"n\" is not an \"Integer\", \"factorial(n)\" is - equivalent to \"gamma(n+1)\". - -"), - -("Base","factorial","factorial(n, k) - - Compute \"factorial(n)/factorial(k)\" - -"), - -("Base","factor","factor(n) -> Dict - - Compute the prime factorization of an integer \"n\". Returns a - dictionary. The keys of the dictionary correspond to the factors, - and hence are of the same type as \"n\". The value associated with - each key indicates the number of times the factor appears in the - factorization. - - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 - -"), - -("Base","gcd","gcd(x, y) - - Greatest common (positive) divisor (or zero if x and y are both - zero). - -"), - -("Base","lcm","lcm(x, y) - - Least common (non-negative) multiple. - -"), - -("Base","gcdx","gcdx(x, y) - - Computes the greatest common (positive) divisor of \"x\" and \"y\" - and their Bézout coefficients, i.e. the integer coefficients \"u\" - and \"v\" that satisfy ux+vy = d = gcd(x,y). - - julia> gcdx(12, 42) - (6,-3,1) - - julia> gcdx(240, 46) - (2,-9,47) - - Note: Bézout coefficients are *not* uniquely defined. \"gcdx\" - returns the minimal Bézout coefficients that are computed by the - extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, - Algorithm X.) These coefficients \"u\" and \"v\" are minimal in - the sense that |u| < |\\frac y d and |v| < |\\frac x d. - Furthermore, the signs of \"u\" and \"v\" are chosen so that - \"d\" is positive. - -"), - -("Base","ispow2","ispow2(n) -> Bool - - Test whether \"n\" is a power of two - -"), - -("Base","nextpow2","nextpow2(n) - - The smallest power of two not less than \"n\". Returns 0 for - \"n==0\", and returns \"-nextpow2(-n)\" for negative arguments. - -"), - -("Base","prevpow2","prevpow2(n) - - The largest power of two not greater than \"n\". Returns 0 for - \"n==0\", and returns \"-prevpow2(-n)\" for negative arguments. - -"), - -("Base","nextpow","nextpow(a, x) - - The smallest \"a^n\" not less than \"x\", where \"n\" is a non- - negative integer. \"a\" must be greater than 1, and \"x\" must be - greater than 0. - -"), - -("Base","prevpow","prevpow(a, x) - - The largest \"a^n\" not greater than \"x\", where \"n\" is a non- - negative integer. \"a\" must be greater than 1, and \"x\" must not - be less than 1. - -"), - -("Base","nextprod","nextprod([k_1, k_2, ...], n) - - Next integer not less than \"n\" that can be written as \\prod - k_i^{p_i} for integers p_1, p_2, etc. - -"), - -("Base","prevprod","prevprod([k_1, k_2, ...], n) - - Previous integer not greater than \"n\" that can be written as - \\prod k_i^{p_i} for integers p_1, p_2, etc. - -"), - -("Base","invmod","invmod(x, m) - - Take the inverse of \"x\" modulo \"m\": \"y\" such that xy = 1 - \\pmod m - -"), - -("Base","powermod","powermod(x, p, m) - - Compute x^p \\pmod m - -"), - -("Base","gamma","gamma(x) - - Compute the gamma function of \"x\" - -"), - -("Base","lgamma","lgamma(x) - - Compute the logarithm of the absolute value of \"gamma()\" for - \"Real\" \"x\", while for \"Complex\" \"x\" it computes the - logarithm of \"gamma(x)\". - -"), - -("Base","lfact","lfact(x) - - Compute the logarithmic factorial of \"x\" - -"), - -("Base","digamma","digamma(x) - - Compute the digamma function of \"x\" (the logarithmic derivative - of \"gamma(x)\") - -"), - -("Base","invdigamma","invdigamma(x) - - Compute the inverse digamma function of \"x\". - -"), - -("Base","trigamma","trigamma(x) - - Compute the trigamma function of \"x\" (the logarithmic second - derivative of \"gamma(x)\") - -"), - -("Base","polygamma","polygamma(m, x) - - Compute the polygamma function of order \"m\" of argument \"x\" - (the \"(m+1)th\" derivative of the logarithm of \"gamma(x)\") - -"), - -("Base","airy","airy(k, x) - - kth derivative of the Airy function \\operatorname{Ai}(x). - -"), - -("Base","airyai","airyai(x) - - Airy function \\operatorname{Ai}(x). - -"), - -("Base","airyprime","airyprime(x) - - Airy function derivative \\operatorname{Ai}'(x). - -"), - -("Base","airyaiprime","airyaiprime(x) - - Airy function derivative \\operatorname{Ai}'(x). - -"), - -("Base","airybi","airybi(x) - - Airy function \\operatorname{Bi}(x). - -"), - -("Base","airybiprime","airybiprime(x) - - Airy function derivative \\operatorname{Bi}'(x). - -"), - -("Base","airyx","airyx(k, x) - - scaled kth derivative of the Airy function, return - \\operatorname{Ai}(x) e^{\\frac{2}{3} x \\sqrt{x}} for \"k == 0 || - k == 1\", and \\operatorname{Ai}(x) e^{- \\left| \\operatorname{Re} - \\left( \\frac{2}{3} x \\sqrt{x} \\right) \\right|} for \"k == 2 || - k == 3\". - -"), - -("Base","besselj0","besselj0(x) - - Bessel function of the first kind of order 0, J_0(x). - -"), - -("Base","besselj1","besselj1(x) - - Bessel function of the first kind of order 1, J_1(x). - -"), - -("Base","besselj","besselj(nu, x) - - Bessel function of the first kind of order \"nu\", J_\\nu(x). - -"), - -("Base","besseljx","besseljx(nu, x) - - Scaled Bessel function of the first kind of order \"nu\", J_\\nu(x) - e^{- | \\operatorname{Im}(x) |}. - -"), - -("Base","bessely0","bessely0(x) - - Bessel function of the second kind of order 0, Y_0(x). - -"), - -("Base","bessely1","bessely1(x) - - Bessel function of the second kind of order 1, Y_1(x). - -"), - -("Base","bessely","bessely(nu, x) - - Bessel function of the second kind of order \"nu\", Y_\\nu(x). - -"), - -("Base","besselyx","besselyx(nu, x) - - Scaled Bessel function of the second kind of order \"nu\", - Y_\\nu(x) e^{- | \\operatorname{Im}(x) |}. - -"), - -("Base","hankelh1","hankelh1(nu, x) - - Bessel function of the third kind of order \"nu\", H^{(1)}_\\nu(x). - -"), - -("Base","hankelh1x","hankelh1x(nu, x) - - Scaled Bessel function of the third kind of order \"nu\", - H^{(1)}_\\nu(x) e^{-x i}. - -"), - -("Base","hankelh2","hankelh2(nu, x) - - Bessel function of the third kind of order \"nu\", H^{(2)}_\\nu(x). - -"), - -("Base","hankelh2x","hankelh2x(nu, x) - - Scaled Bessel function of the third kind of order \"nu\", - H^{(2)}_\\nu(x) e^{x i}. - -"), - -("Base","besselh","besselh(nu, k, x) - - Bessel function of the third kind of order \"nu\" (Hankel - function). \"k\" is either 1 or 2, selecting \"hankelh1\" or - \"hankelh2\", respectively. - -"), - -("Base","besseli","besseli(nu, x) - - Modified Bessel function of the first kind of order \"nu\", - I_\\nu(x). - -"), - -("Base","besselix","besselix(nu, x) - - Scaled modified Bessel function of the first kind of order \"nu\", - I_\\nu(x) e^{- | \\operatorname{Re}(x) |}. - -"), - -("Base","besselk","besselk(nu, x) - - Modified Bessel function of the second kind of order \"nu\", - K_\\nu(x). - -"), - -("Base","besselkx","besselkx(nu, x) - - Scaled modified Bessel function of the second kind of order \"nu\", - K_\\nu(x) e^x. - -"), - -("Base","beta","beta(x, y) - - Euler integral of the first kind \\operatorname{B}(x,y) = - \\Gamma(x)\\Gamma(y)/\\Gamma(x+y). - -"), - -("Base","lbeta","lbeta(x, y) - - Natural logarithm of the absolute value of the beta function - \\log(|\\operatorname{B}(x,y)|). - -"), - -("Base","eta","eta(x) - - Dirichlet eta function \\eta(s) = - \\sum^\\infty_{n=1}(-)^{n-1}/n^{s}. - -"), - -("Base","zeta","zeta(s) - - Riemann zeta function \\zeta(s). - -"), - -("Base","zeta","zeta(s, z) - - Hurwitz zeta function \\zeta(s, z). (This is equivalent to the - Riemann zeta function \\zeta(s) for the case of \"z=1\".) - -"), - -("Base","ndigits","ndigits(n, b) - - Compute the number of digits in number \"n\" written in base \"b\". - -"), - -("Base","widemul","widemul(x, y) - - Multiply \"x\" and \"y\", giving the result as a larger type. - -"), - -("Base","@evalpoly","@evalpoly(z, c...) - - Evaluate the polynomial \\sum_k c[k] z^{k-1} for the coefficients - \"c[1]\", \"c[2]\", ...; that is, the coefficients are given in - ascending order by power of \"z\". This macro expands to efficient - inline code that uses either Horner's method or, for complex \"z\", - a more efficient Goertzel-like algorithm. - -"), - -("Base","mean","mean(v[, region]) - - Compute the mean of whole array \"v\", or optionally along the - dimensions in \"region\". Note: Julia does not ignore \"NaN\" - values in the computation. For applications requiring the handling - of missing data, the \"DataArray\" package is recommended. - -"), - -("Base","mean!","mean!(r, v) - - Compute the mean of \"v\" over the singleton dimensions of \"r\", - and write results to \"r\". - -"), - -("Base","std","std(v[, region]) - - Compute the sample standard deviation of a vector or array \"v\", - optionally along dimensions in \"region\". The algorithm returns an - estimator of the generative distribution's standard deviation under - the assumption that each entry of \"v\" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating \"sqrt(sum((v - mean(v)).^2) / (length(v) - 1))\". - Note: Julia does not ignore \"NaN\" values in the computation. For - applications requiring the handling of missing data, the - \"DataArray\" package is recommended. - -"), - -("Base","stdm","stdm(v, m) - - Compute the sample standard deviation of a vector \"v\" with known - mean \"m\". Note: Julia does not ignore \"NaN\" values in the - computation. - -"), - -("Base","var","var(v[, region]) - - Compute the sample variance of a vector or array \"v\", optionally - along dimensions in \"region\". The algorithm will return an - estimator of the generative distribution's variance under the - assumption that each entry of \"v\" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating \"sum((v - mean(v)).^2) / (length(v) - 1)\". Note: - Julia does not ignore \"NaN\" values in the computation. For - applications requiring the handling of missing data, the - \"DataArray\" package is recommended. - -"), - -("Base","varm","varm(v, m) - - Compute the sample variance of a vector \"v\" with known mean - \"m\". Note: Julia does not ignore \"NaN\" values in the - computation. - -"), - -("Base","middle","middle(x) - - Compute the middle of a scalar value, which is equivalent to \"x\" - itself, but of the type of \"middle(x, x)\" for consistency. - -"), - -("Base","middle","middle(x, y) - - Compute the middle of two reals \"x\" and \"y\", which is - equivalent in both value and type to computing their mean (\"(x + - y) / 2\"). - -"), - -("Base","middle","middle(range) - - Compute the middle of a range, which consists in computing the mean - of its extrema. Since a range is sorted, the mean is performed with - the first and last element. - -"), - -("Base","middle","middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - -"), - -("Base","median","median(v) - - Compute the median of a vector \"v\". \"NaN\" is returned if the - data contains any \"NaN\" values. For applications requiring the - handling of missing data, the \"DataArrays\" package is - recommended. - -"), - -("Base","median!","median!(v) - - Like \"median\", but may overwrite the input vector. - -"), - -("Base","hist","hist(v[, n]) -> e, counts - - Compute the histogram of \"v\", optionally using approximately - \"n\" bins. The return values are a range \"e\", which correspond - to the edges of the bins, and \"counts\" containing the number of - elements of \"v\" in each bin. Note: Julia does not ignore \"NaN\" - values in the computation. - -"), - -("Base","hist","hist(v, e) -> e, counts - - Compute the histogram of \"v\" using a vector/range \"e\" as the - edges for the bins. The result will be a vector of length - \"length(e) - 1\", such that the element at location \"i\" - satisfies \"sum(e[i] .< v .<= e[i+1])\". Note: Julia does not - ignore \"NaN\" values in the computation. - -"), - -("Base","hist!","hist!(counts, v, e) -> e, counts - - Compute the histogram of \"v\", using a vector/range \"e\" as the - edges for the bins. This function writes the resultant counts to a - pre-allocated array \"counts\". - -"), - -("Base","hist2d","hist2d(M, e1, e2) -> (edge1, edge2, counts) - - Compute a \"2d histogram\" of a set of N points specified by N-by-2 - matrix \"M\". Arguments \"e1\" and \"e2\" are bins for each - dimension, specified either as integer bin counts or vectors of bin - edges. The result is a tuple of \"edge1\" (the bin edges used in - the first dimension), \"edge2\" (the bin edges used in the second - dimension), and \"counts\", a histogram matrix of size - \"(length(edge1)-1, length(edge2)-1)\". Note: Julia does not ignore - \"NaN\" values in the computation. - -"), - -("Base","hist2d!","hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - - Compute a \"2d histogram\" with respect to the bins delimited by - the edges given in \"e1\" and \"e2\". This function writes the - results to a pre-allocated array \"counts\". - -"), - -("Base","histrange","histrange(v, n) - - Compute *nice* bin ranges for the edges of a histogram of \"v\", - using approximately \"n\" bins. The resulting step sizes will be 1, - 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - \"NaN\" values in the computation. - -"), - -("Base","midpoints","midpoints(e) - - Compute the midpoints of the bins with edges \"e\". The result is a - vector/range of length \"length(e) - 1\". Note: Julia does not - ignore \"NaN\" values in the computation. - -"), - -("Base","quantile","quantile(v, p) - - Compute the quantiles of a vector \"v\" at a specified set of - probability values \"p\". Note: Julia does not ignore \"NaN\" - values in the computation. - -"), - -("Base","quantile","quantile(v, p) - - Compute the quantile of a vector \"v\" at the probability \"p\". - Note: Julia does not ignore \"NaN\" values in the computation. - -"), - -("Base","quantile!","quantile!(v, p) - - Like \"quantile\", but overwrites the input vector. - -"), - -("Base","cov","cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - - Compute the Pearson covariance between the vector(s) in \"v1\" and - \"v2\". Here, \"v1\" and \"v2\" can be either vectors or matrices. - - This function accepts three keyword arguments: - - * \"vardim\": the dimension of variables. When \"vardim = 1\", - variables are considered in columns while observations in rows; - when \"vardim = 2\", variables are in rows while observations in - columns. By default, it is set to \"1\". - - * \"corrected\": whether to apply Bessel's correction (divide by - \"n-1\" instead of \"n\"). By default, it is set to \"true\". - - * \"mean\": allow users to supply mean values that are known. By - default, it is set to \"nothing\", which indicates that the - mean(s) are unknown, and the function will compute the mean. - Users can use \"mean=0\" to indicate that the input data are - centered, and hence there's no need to subtract the mean. - - The size of the result depends on the size of \"v1\" and \"v2\". - When both \"v1\" and \"v2\" are vectors, it returns the covariance - between them as a scalar. When either one is a matrix, it returns a - covariance matrix of size \"(n1, n2)\", where \"n1\" and \"n2\" are - the numbers of slices in \"v1\" and \"v2\", which depend on the - setting of \"vardim\". - - Note: \"v2\" can be omitted, which indicates \"v2 = v1\". - -"), - -("Base","cor","cor(v1[, v2][, vardim=1, mean=nothing]) - - Compute the Pearson correlation between the vector(s) in \"v1\" and - \"v2\". - - Users can use the keyword argument \"vardim\" to specify the - variable dimension, and \"mean\" to supply pre-computed mean - values. - -"), - -("Base","fft","fft(A[, dims]) - - Performs a multidimensional FFT of the array \"A\". The optional - \"dims\" argument specifies an iterable subset of dimensions (e.g. - an integer, range, tuple, or array) to transform along. Most - efficient if the size of \"A\" along the transformed dimensions is - a product of small primes; see \"nextprod()\". See also - \"plan_fft()\" for even greater efficiency. - - A one-dimensional FFT computes the one-dimensional discrete Fourier - transform (DFT) as defined by - - \\operatorname{DFT}(A)[k] = - \\sum_{n=1}^{\\operatorname{length}(A)} - \\exp\\left(-i\\frac{2\\pi - (n-1)(k-1)}{\\operatorname{length}(A)} \\right) A[n]. - - A multidimensional FFT simply performs this operation along each - transformed dimension of \"A\". - - Higher performance is usually possible with multi-threading. Use - *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* - processors. - -"), - -("Base","fft!","fft!(A[, dims]) - - Same as \"fft()\", but operates in-place on \"A\", which must be an - array of complex floating-point numbers. - -"), - -("Base","ifft","ifft(A[, dims]) - - Multidimensional inverse FFT. - - A one-dimensional inverse FFT computes - - \\operatorname{IDFT}(A)[k] = - \\frac{1}{\\operatorname{length}(A)} - \\sum_{n=1}^{\\operatorname{length}(A)} - \\exp\\left(+i\\frac{2\\pi (n-1)(k-1)} - {\\operatorname{length}(A)} \\right) A[n]. - - A multidimensional inverse FFT simply performs this operation along - each transformed dimension of \"A\". - -"), - -("Base","ifft!","ifft!(A[, dims]) - - Same as \"ifft()\", but operates in-place on \"A\". - -"), - -("Base","bfft","bfft(A[, dims]) - - Similar to \"ifft()\", but computes an unnormalized inverse - (backward) transform, which must be divided by the product of the - sizes of the transformed dimensions in order to obtain the inverse. - (This is slightly more efficient than \"ifft()\" because it omits a - scaling step, which in some applications can be combined with other - computational steps elsewhere.) - - \\operatorname{BDFT}(A)[k] = \\operatorname{length}(A) - \\operatorname{IDFT}(A)[k] - -"), - -("Base","bfft!","bfft!(A[, dims]) - - Same as \"bfft()\", but operates in-place on \"A\". - -"), - -("Base","plan_fft","plan_fft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized FFT along given dimensions (\"dims\") of - arrays matching the shape and type of \"A\". (The first two - arguments have the same meaning as for \"fft()\".) Returns a - function \"plan(A)\" that computes \"fft(A, dims)\" quickly. - - The \"flags\" argument is a bitwise-or of FFTW planner flags, - defaulting to \"FFTW.ESTIMATE\". e.g. passing \"FFTW.MEASURE\" or - \"FFTW.PATIENT\" will instead spend several seconds (or more) - benchmarking different possible FFT algorithms and picking the - fastest one; see the FFTW manual for more information on planner - flags. The optional \"timelimit\" argument specifies a rough upper - bound on the allowed planning time, in seconds. Passing - \"FFTW.MEASURE\" or \"FFTW.PATIENT\" may cause the input array - \"A\" to be overwritten with zeros during plan creation. - - \"plan_fft!()\" is the same as \"plan_fft()\" but creates a plan - that operates in-place on its argument (which must be an array of - complex floating-point numbers). \"plan_ifft()\" and so on are - similar but produce plans that perform the equivalent of the - inverse transforms \"ifft()\" and so on. - -"), - -("Base","plan_ifft","plan_ifft(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_fft()\", but produces a plan that performs inverse - transforms \"ifft()\". - -"), - -("Base","plan_bfft","plan_bfft(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_fft()\", but produces a plan that performs an - unnormalized backwards transform \"bfft()\". - -"), - -("Base","plan_fft!","plan_fft!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_fft()\", but operates in-place on \"A\". - -"), - -("Base","plan_ifft!","plan_ifft!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_ifft()\", but operates in-place on \"A\". - -"), - -("Base","plan_bfft!","plan_bfft!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_bfft()\", but operates in-place on \"A\". - -"), - -("Base","rfft","rfft(A[, dims]) - - Multidimensional FFT of a real array A, exploiting the fact that - the transform has conjugate symmetry in order to save roughly half - the computational time and storage costs compared with \"fft()\". - If \"A\" has size \"(n_1, ..., n_d)\", the result has size - \"(floor(n_1/2)+1, ..., n_d)\". - - The optional \"dims\" argument specifies an iterable subset of one - or more dimensions of \"A\" to transform, similar to \"fft()\". - Instead of (roughly) halving the first dimension of \"A\" in the - result, the \"dims[1]\" dimension is (roughly) halved in the same - way. - -"), - -("Base","irfft","irfft(A, d[, dims]) - - Inverse of \"rfft()\": for a complex array \"A\", gives the - corresponding real array whose FFT yields \"A\" in the first half. - As for \"rfft()\", \"dims\" is an optional subset of dimensions to - transform, defaulting to \"1:ndims(A)\". - - \"d\" is the length of the transformed real array along the - \"dims[1]\" dimension, which must satisfy \"d == - floor(size(A,dims[1])/2)+1\". (This parameter cannot be inferred - from \"size(A)\" due to the possibility of rounding by the - \"floor\" function here.) - -"), - -("Base","brfft","brfft(A, d[, dims]) - - Similar to \"irfft()\" but computes an unnormalized inverse - transform (similar to \"bfft()\"), which must be divided by the - product of the sizes of the transformed dimensions (of the real - output array) in order to obtain the inverse transform. - -"), - -("Base","plan_rfft","plan_rfft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized real-input FFT, similar to \"plan_fft()\" - except for \"rfft()\" instead of \"fft()\". The first two - arguments, and the size of the transformed result, are the same as - for \"rfft()\". - -"), - -("Base","plan_brfft","plan_brfft(A, d[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized real-input unnormalized transform, similar to - \"plan_rfft()\" except for \"brfft()\" instead of \"rfft()\". The - first two arguments and the size of the transformed result, are the - same as for \"brfft()\". - -"), - -("Base","plan_irfft","plan_irfft(A, d[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized inverse real-input FFT, similar to - \"plan_rfft()\" except for \"irfft()\" and \"brfft()\", - respectively. The first three arguments have the same meaning as - for \"irfft()\". - -"), - -("Base","dct","dct(A[, dims]) - - Performs a multidimensional type-II discrete cosine transform (DCT) - of the array \"A\", using the unitary normalization of the DCT. The - optional \"dims\" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of \"A\" along the transformed - dimensions is a product of small primes; see \"nextprod()\". See - also \"plan_dct()\" for even greater efficiency. - -"), - -("Base","dct!","dct!(A[, dims]) - - Same as \"dct!()\", except that it operates in-place on \"A\", - which must be an array of real or complex floating-point values. - -"), - -("Base","idct","idct(A[, dims]) - - Computes the multidimensional inverse discrete cosine transform - (DCT) of the array \"A\" (technically, a type-III DCT with the - unitary normalization). The optional \"dims\" argument specifies an - iterable subset of dimensions (e.g. an integer, range, tuple, or - array) to transform along. Most efficient if the size of \"A\" - along the transformed dimensions is a product of small primes; see - \"nextprod()\". See also \"plan_idct()\" for even greater - efficiency. - -"), - -("Base","idct!","idct!(A[, dims]) - - Same as \"idct!()\", but operates in-place on \"A\". - -"), - -("Base","plan_dct","plan_dct(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized discrete cosine transform (DCT), similar to - \"plan_fft()\" except producing a function that computes \"dct()\". - The first two arguments have the same meaning as for \"dct()\". - -"), - -("Base","plan_dct!","plan_dct!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_dct()\", but operates in-place on \"A\". - -"), - -("Base","plan_idct","plan_idct(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized inverse discrete cosine transform (DCT), - similar to \"plan_fft()\" except producing a function that computes - \"idct()\". The first two arguments have the same meaning as for - \"idct()\". - -"), - -("Base","plan_idct!","plan_idct!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_idct()\", but operates in-place on \"A\". - -"), - -("Base","fftshift","fftshift(x) - - Swap the first and second halves of each dimension of \"x\". - -"), - -("Base","fftshift","fftshift(x, dim) - - Swap the first and second halves of the given dimension of array - \"x\". - -"), - -("Base","ifftshift","ifftshift(x[, dim]) - - Undoes the effect of \"fftshift\". - -"), - -("Base","filt","filt(b, a, x[, si]) - - Apply filter described by vectors \"a\" and \"b\" to vector \"x\", - with an optional initial filter state vector \"si\" (defaults to - zeros). - -"), - -("Base","filt!","filt!(out, b, a, x[, si]) - - Same as \"filt()\" but writes the result into the \"out\" argument, - which may alias the input \"x\" to modify it in-place. - -"), - -("Base","deconv","deconv(b, a) - - Construct vector \"c\" such that \"b = conv(a,c) + r\". Equivalent - to polynomial division. - -"), - -("Base","conv","conv(u, v) - - Convolution of two vectors. Uses FFT algorithm. - -"), - -("Base","conv2","conv2(u, v, A) - - 2-D convolution of the matrix \"A\" with the 2-D separable kernel - generated by the vectors \"u\" and \"v\". Uses 2-D FFT algorithm - -"), - -("Base","conv2","conv2(B, A) - - 2-D convolution of the matrix \"B\" with the matrix \"A\". Uses - 2-D FFT algorithm - -"), - -("Base","xcorr","xcorr(u, v) - - Compute the cross-correlation of two vectors. - -"), - -("Base.FFTW","r2r","r2r(A, kind[, dims]) - - Performs a multidimensional real-input/real-output (r2r) transform - of type \"kind\" of the array \"A\", as defined in the FFTW manual. - \"kind\" specifies either a discrete cosine transform of various - types (\"FFTW.REDFT00\", \"FFTW.REDFT01\", \"FFTW.REDFT10\", or - \"FFTW.REDFT11\"), a discrete sine transform of various types - (\"FFTW.RODFT00\", \"FFTW.RODFT01\", \"FFTW.RODFT10\", or - \"FFTW.RODFT11\"), a real-input DFT with halfcomplex-format output - (\"FFTW.R2HC\" and its inverse \"FFTW.HC2R\"), or a discrete - Hartley transform (\"FFTW.DHT\"). The \"kind\" argument may be an - array or tuple in order to specify different transform types along - the different dimensions of \"A\"; \"kind[end]\" is used for any - unspecified dimensions. See the FFTW manual for precise - definitions of these transform types, at http://www.fftw.org/doc. - - The optional \"dims\" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. \"kind[i]\" is then the transform type for \"dims[i]\", with - \"kind[end]\" being used for \"i > length(kind)\". - - See also \"plan_r2r()\" to pre-plan optimized r2r transforms. - -"), - -("Base.FFTW","r2r!","r2r!(A, kind[, dims]) - - Same as \"r2r()\", but operates in-place on \"A\", which must be an - array of real or complex floating-point numbers. - -"), - -("Base.FFTW","plan_r2r","plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized r2r transform, similar to \"Base.plan_fft()\" - except that the transforms (and the first three arguments) - correspond to \"r2r()\" and \"r2r!()\", respectively. - -"), - -("Base.FFTW","plan_r2r!","plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) - - Similar to \"Base.plan_fft()\", but corresponds to \"r2r!()\". - -"), - -("Base","quadgk","quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - - Numerically integrate the function \"f(x)\" from \"a\" to \"b\", - and optionally over additional intervals \"b\" to \"c\" and so on. - Keyword options include a relative error tolerance \"reltol\" - (defaults to \"sqrt(eps)\" in the precision of the endpoints), an - absolute error tolerance \"abstol\" (defaults to 0), a maximum - number of function evaluations \"maxevals\" (defaults to \"10^7\"), - and the \"order\" of the integration rule (defaults to 7). - - Returns a pair \"(I,E)\" of the estimated integral \"I\" and an - estimated upper bound on the absolute error \"E\". If \"maxevals\" - is not exceeded then \"E <= max(abstol, reltol*norm(I))\" will - hold. (Note that it is useful to specify a positive \"abstol\" in - cases where \"norm(I)\" may be zero.) - - The endpoints \"a\" etcetera can also be complex (in which case the - integral is performed over straight-line segments in the complex - plane). If the endpoints are \"BigFloat\", then the integration - will be performed in \"BigFloat\" precision as well (note: it is - advisable to increase the integration \"order\" in rough proportion - to the precision, for smooth integrands). More generally, the - precision is set by the precision of the integration endpoints - (promoted to floating-point types). - - The integrand \"f(x)\" can return any numeric scalar, vector, or - matrix type, or in fact any type supporting \"+\", \"-\", - multiplication by real values, and a \"norm\" (i.e., any normed - vector space). Alternatively, a different norm can be specified by - passing a *norm*-like function as the *norm* keyword argument - (which defaults to *vecnorm*). - - [Only one-dimensional integrals are provided by this function. For - multi-dimensional integration (cubature), there are many different - algorithms (often much better than simple nested 1d integrals) and - the optimal choice tends to be very problem-dependent. See the - Julia external-package listing for available algorithms for - multidimensional integration or other specialized tasks (such as - integrals of highly oscillatory or singular functions).] - - The algorithm is an adaptive Gauss-Kronrod integration technique: - the integral in each interval is estimated using a Kronrod rule - (\"2*order+1\" points) and the error is estimated using an embedded - Gauss rule (\"order\" points). The interval with the largest - error is then subdivided into two intervals and the process is - repeated until the desired error tolerance is achieved. - - These quadrature rules work best for smooth functions within each - interval, so if your function has a known discontinuity or other - singularity, it is best to subdivide your interval to put the - singularity at an endpoint. For example, if \"f\" has a - discontinuity at \"x=0.7\" and you want to integrate from 0 to 1, - you should use \"quadgk(f, 0,0.7,1)\" to subdivide the interval at - the point of discontinuity. The integrand is never evaluated - exactly at the endpoints of the intervals, so it is possible to - integrate functions that diverge at the endpoints as long as the - singularity is integrable (for example, a \"log(x)\" or - \"1/sqrt(x)\" singularity). - - For real-valued endpoints, the starting and/or ending points may be - infinite. (A coordinate transformation is performed internally to - map the infinite interval to a finite one.) - -"), - -("Base","bin","bin(n[, pad]) - - Convert an integer to a binary string, optionally specifying a - number of digits to pad to. - -"), - -("Base","hex","hex(n[, pad]) - - Convert an integer to a hexadecimal string, optionally specifying a - number of digits to pad to. - -"), - -("Base","dec","dec(n[, pad]) - - Convert an integer to a decimal string, optionally specifying a - number of digits to pad to. - -"), - -("Base","oct","oct(n[, pad]) - - Convert an integer to an octal string, optionally specifying a - number of digits to pad to. - -"), - -("Base","base","base(base, n[, pad]) - - Convert an integer to a string in the given base, optionally - specifying a number of digits to pad to. The base can be specified - as either an integer, or as a \"UInt8\" array of character values - to use as digit symbols. - -"), - -("Base","digits","digits(n[, base][, pad]) - - Returns an array of the digits of \"n\" in the given base, - optionally padded with zeros to a specified size. More significant - digits are at higher indexes, such that \"n == - sum([digits[k]*base^(k-1) for k=1:length(digits)])\". - -"), - -("Base","digits!","digits!(array, n[, base]) - - Fills an array of the digits of \"n\" in the given base. More - significant digits are at higher indexes. If the array length is - insufficient, the least significant digits are filled up to the - array length. If the array length is excessive, the excess portion - is filled with zeros. - -"), - -("Base","bits","bits(n) - - A string giving the literal bit representation of a number. - -"), - -("Base","parse","parse(type, str[, base]) - - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. - -"), - -("Base","tryparse","tryparse(type, str[, base]) - - Like \"parse\", but returns a \"Nullable\" of the requested type. - The result will be null if the string does not contain a valid - number. - -"), - -("Base","big","big(x) - - Convert a number to a maximum precision representation (typically - \"BigInt\" or \"BigFloat\"). See \"BigFloat\" for information about - some pitfalls with floating-point numbers. - -"), - -("Base","signed","signed(x) - - Convert a number to a signed integer. If the argument is unsigned, - it is reinterpreted as signed without checking for overflow. - -"), - -("Base","unsigned","unsigned(x) -> Unsigned - - Convert a number to an unsigned integer. If the argument is signed, - it is reinterpreted as unsigned without checking for negative - values. - -"), - -("Base","float","float(x) - - Convert a number, array, or string to a \"FloatingPoint\" data - type. For numeric data, the smallest suitable \"FloatingPoint\" - type is used. Converts strings to \"Float64\". - -"), - -("Base","significand","significand(x) - - Extract the significand(s) (a.k.a. mantissa), in binary - representation, of a floating-point number or array. If \"x\" is a - non-zero finite number, than the result will be a number of the - same type on the interval [1,2). Otherwise \"x\" is returned. - - julia> significand(15.2)/15.2 - 0.125 - - julia> significand(15.2)*8 - 15.2 - -"), - -("Base","exponent","exponent(x) -> Int - - Get the exponent of a normalized floating-point number. - -"), - -("Base","complex","complex(r[, i]) - - Convert real numbers or arrays to complex. \"i\" defaults to zero. - -"), - -("Base","bswap","bswap(n) - - Byte-swap an integer - -"), - -("Base","num2hex","num2hex(f) - - Get a hexadecimal string of the binary representation of a floating - point number - -"), - -("Base","hex2num","hex2num(str) - - Convert a hexadecimal string to the floating point number it - represents - -"), - -("Base","hex2bytes","hex2bytes(s::ASCIIString) - - Convert an arbitrarily long hexadecimal string to its binary - representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. - -"), - -("Base","bytes2hex","bytes2hex(bin_arr::Array{UInt8, 1}) - - Convert an array of bytes to its hexadecimal representation. All - characters are in lower-case. Returns an ASCIIString. - -"), - -("Base","one","one(x) - - Get the multiplicative identity element for the type of x (x can - also specify the type itself). For matrices, returns an identity - matrix of the appropriate size and type. - -"), - -("Base","zero","zero(x) - - Get the additive identity element for the type of x (x can also - specify the type itself). - -"), - -("Base","pi","pi -π - - The constant pi - -"), - -("Base","im","im - - The imaginary unit - -"), - -("Base","e","e -eu - - The constant e - -"), - -("Base","catalan","catalan - - Catalan's constant - -"), - -("Base","γ","γ -eulergamma - - Euler's constant - -"), - -("Base","φ","φ -golden - - The golden ratio - -"), - -("Base","Inf","Inf - - Positive infinity of type Float64 - -"), - -("Base","Inf32","Inf32 - - Positive infinity of type Float32 - -"), - -("Base","Inf16","Inf16 - - Positive infinity of type Float16 - -"), - -("Base","NaN","NaN - - A not-a-number value of type Float64 - -"), - -("Base","NaN32","NaN32 - - A not-a-number value of type Float32 - -"), - -("Base","NaN16","NaN16 - - A not-a-number value of type Float16 - -"), - -("Base","issubnormal","issubnormal(f) -> Bool - - Test whether a floating point number is subnormal - -"), - -("Base","isfinite","isfinite(f) -> Bool - - Test whether a number is finite - -"), - -("Base","isinf","isinf(f) -> Bool - - Test whether a number is infinite - -"), - -("Base","isnan","isnan(f) -> Bool - - Test whether a floating point number is not a number (NaN) - -"), - -("Base","inf","inf(f) - - Returns positive infinity of the floating point type \"f\" or of - the same floating point type as \"f\" - -"), - -("Base","nan","nan(f) - - Returns NaN (not-a-number) of the floating point type \"f\" or of - the same floating point type as \"f\" - -"), - -("Base","nextfloat","nextfloat(f) - - Get the next floating point number in lexicographic order - -"), - -("Base","prevfloat","prevfloat(f) -> FloatingPoint - - Get the previous floating point number in lexicographic order - -"), - -("Base","isinteger","isinteger(x) -> Bool - - Test whether \"x\" or all its elements are numerically equal to - some integer - -"), - -("Base","isreal","isreal(x) -> Bool - - Test whether \"x\" or all its elements are numerically equal to - some real number - -"), - -("Base","Float32","Float32(x[, mode::RoundingMode]) - - Create a Float32 from \"x\". If \"x\" is not exactly representable - then \"mode\" determines how \"x\" is rounded. - - julia> Float32(1/3, RoundDown) - 0.3333333f0 - - julia> Float32(1/3, RoundUp) - 0.33333334f0 - - See \"get_rounding\" for available rounding modes. - -"), - -("Base","Float64","Float64(x[, mode::RoundingMode]) - - Create a Float64 from \"x\". If \"x\" is not exactly representable - then \"mode\" determines how \"x\" is rounded. - - julia> Float64(pi, RoundDown) - 3.141592653589793 - - julia> Float64(pi, RoundUp) - 3.1415926535897936 - - See \"get_rounding\" for available rounding modes. - -"), - -("Base","BigInt","BigInt(x) - - Create an arbitrary precision integer. \"x\" may be an \"Int\" (or - anything that can be converted to an \"Int\"). The usual - mathematical operators are defined for this type, and results are - promoted to a \"BigInt\". - - Instances can be constructed from strings via \"parse()\", or using - the \"big\" string literal. - -"), - -("Base","BigFloat","BigFloat(x) - - Create an arbitrary precision floating point number. \"x\" may be - an \"Integer\", a \"Float64\" or a \"BigInt\". The usual - mathematical operators are defined for this type, and results are - promoted to a \"BigFloat\". - - Note that because decimal literals are converted to floating point - numbers when parsed, \"BigFloat(2.1)\" may not yield what you - expect. You may instead prefer to initialize constants from strings - via \"parse()\", or using the \"big\" string literal. - - julia> big\"2.1\" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision - -"), - -("Base","get_rounding","get_rounding(T) - - Get the current floating point rounding mode for type \"T\", - controlling the rounding of basic arithmetic functions (\"+()\", - \"-()\", \"*()\", \"/()\" and \"sqrt()\") and type conversion. - - Valid modes are \"RoundNearest\", \"RoundToZero\", \"RoundUp\", - \"RoundDown\", and \"RoundFromZero\" (\"BigFloat\" only). - -"), - -("Base","set_rounding","set_rounding(T, mode) - - Set the rounding mode of floating point type \"T\", controlling the - rounding of basic arithmetic functions (\"+()\", \"-()\", \"*()\", - \"/()\" and \"sqrt()\") and type conversion. - - Note that this may affect other types, for instance changing the - rounding mode of \"Float64\" will change the rounding mode of - \"Float32\". See \"get_rounding\" for available modes - -"), - -("Base","with_rounding","with_rounding(f::Function, T, mode) - - Change the rounding mode of floating point type \"T\" for the - duration of \"f\". It is logically equivalent to: - - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) - - See \"get_rounding\" for available rounding modes. - -"), - -("Base","count_ones","count_ones(x::Integer) -> Integer - - Number of ones in the binary representation of \"x\". - - julia> count_ones(7) - 3 - -"), - -("Base","count_zeros","count_zeros(x::Integer) -> Integer - - Number of zeros in the binary representation of \"x\". - - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 - -"), - -("Base","leading_zeros","leading_zeros(x::Integer) -> Integer - - Number of zeros leading the binary representation of \"x\". - - julia> leading_zeros(Int32(1)) - 31 - -"), - -("Base","leading_ones","leading_ones(x::Integer) -> Integer - - Number of ones leading the binary representation of \"x\". - - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 - -"), - -("Base","trailing_zeros","trailing_zeros(x::Integer) -> Integer - - Number of zeros trailing the binary representation of \"x\". - - julia> trailing_zeros(2) - 1 - -"), - -("Base","trailing_ones","trailing_ones(x::Integer) -> Integer - - Number of ones trailing the binary representation of \"x\". - - julia> trailing_ones(3) - 2 - -"), - -("Base","isprime","isprime(x::Integer) -> Bool - - Returns \"true\" if \"x\" is prime, and \"false\" otherwise. - - julia> isprime(3) - true - -"), - -("Base","isprime","isprime(x::BigInt[, reps = 25]) -> Bool - - Probabilistic primality test. Returns \"true\" if \"x\" is prime; - and \"false\" if \"x\" is not prime with high probability. The - false positive rate is about \"0.25^reps\". \"reps = 25\" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). - - julia> isprime(big(3)) - true - -"), - -("Base","primes","primes(n) - - Returns a collection of the prime numbers <= \"n\". - -"), - -("Base","isodd","isodd(x::Integer) -> Bool - - Returns \"true\" if \"x\" is odd (that is, not divisible by 2), and - \"false\" otherwise. - - julia> isodd(9) - true - - julia> isodd(10) - false - -"), - -("Base","iseven","iseven(x::Integer) -> Bool - - Returns \"true\" is \"x\" is even (that is, divisible by 2), and - \"false\" otherwise. - - julia> iseven(9) - false - - julia> iseven(10) - true - -"), - -("Base","precision","precision(num::FloatingPoint) - - Get the precision of a floating point number, as defined by the - effective number of bits in the mantissa. - -"), - -("Base","get_bigfloat_precision","get_bigfloat_precision() - - Get the precision (in bits) currently used for BigFloat arithmetic. - -"), - -("Base","set_bigfloat_precision","set_bigfloat_precision(x::Int64) - - Set the precision (in bits) to be used to BigFloat arithmetic. - -"), - -("Base","with_bigfloat_precision","with_bigfloat_precision(f::Function, precision::Integer) - - Change the BigFloat arithmetic precision (in bits) for the duration - of \"f\". It is logically equivalent to: - - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) - -"), - -("Base","srand","srand([rng][, seed]) - - Reseed the random number generator. If a \"seed\" is provided, the - RNG will give a reproducible sequence of numbers, otherwise Julia - will get entropy from the system. For \"MersenneTwister\", the - \"seed\" may be a non-negative integer, a vector of \"UInt32\" - integers or a filename, in which case the seed is read from a file. - \"RandomDevice\" does not support seeding. - -"), - -("Base","MersenneTwister","MersenneTwister([seed]) - - Create a \"MersenneTwister\" RNG object. Different RNG objects can - have their own seeds, which may be useful for generating different - streams of random numbers. - -"), - -("Base","RandomDevice","RandomDevice() - - Create a \"RandomDevice\" RNG object. Two such objects will always - generate different streams of random numbers. - -"), - -("Base","rand","rand([rng][, S][, dims...]) - - Pick a random element or array of random elements from the set of - values specified by \"S\"; \"S\" can be - - * an indexable collection (for example \"1:n\" or - \"['x','y','z']\"), or - - * a type: the set of values to pick from is then equivalent to - \"typemin(S):typemax(S)\" for integers (this is not applicable to - \"BigInt\"), and to [0,1) for floating point numbers; - - \"S\" defaults to \"Float64\". - -"), - -("Base","rand!","rand!([rng], A[, coll]) - - Populate the array A with random values. If the indexable - collection \"coll\" is specified, the values are picked randomly - from \"coll\". This is equivalent to \"copy!(A, rand(rng, coll, - size(A)))\" or \"copy!(A, rand(rng, eltype(A), size(A)))\" but - without allocating a new array. - -"), - -("Base","bitrand","bitrand([rng][, dims...]) - - Generate a \"BitArray\" of random boolean values. - -"), - -("Base","randn","randn([rng][, dims...]) - - Generate a normally-distributed random number with mean 0 and - standard deviation 1. Optionally generate an array of normally- - distributed random numbers. - -"), - -("Base","randn!","randn!([rng], A::Array{Float64, N}) - - Fill the array A with normally-distributed (mean 0, standard - deviation 1) random numbers. Also see the rand function. - -"), - -("Base","randexp","randexp([rng][, dims...]) - - Generate a random number according to the exponential distribution - with scale 1. Optionally generate an array of such random numbers. - -"), - -("Base","randexp!","randexp!([rng], A::Array{Float64, N}) - - Fill the array A with random numbers following the exponential - distribution (with scale 1). - -"), - -("Base","Task","Task(func) - - Create a \"Task\" (i.e. thread, or coroutine) to execute the given - function (which must be callable with no arguments). The task exits - when this function returns. - -"), - -("Base","yieldto","yieldto(task, arg = nothing) - - Switch to the given task. The first time a task is switched to, the - task's function is called with no arguments. On subsequent - switches, \"arg\" is returned from the task's last call to - \"yieldto\". This is a low-level call that only switches tasks, not - considering states or scheduling in any way. Its use is - discouraged. - -"), - -("Base","current_task","current_task() - - Get the currently running Task. - -"), - -("Base","istaskdone","istaskdone(task) -> Bool - - Tell whether a task has exited. - -"), - -("Base","istaskstarted","istaskstarted(task) -> Bool - - Tell whether a task has started executing. - -"), - -("Base","consume","consume(task, values...) - - Receive the next value passed to \"produce\" by the specified task. - Additional arguments may be passed, to be returned from the last - \"produce\" call in the producer. - -"), - -("Base","produce","produce(value) - - Send the given value to the last \"consume\" call, switching to the - consumer task. If the next \"consume\" call passes any values, they - are returned by \"produce\". - -"), - -("Base","yield","yield() - - Switch to the scheduler to allow another scheduled task to run. A - task that calls this function is still runnable, and will be - restarted immediately if there are no other runnable tasks. - -"), - -("Base","task_local_storage","task_local_storage(symbol) - - Look up the value of a symbol in the current task's task-local - storage. - -"), - -("Base","task_local_storage","task_local_storage(symbol, value) - - Assign a value to a symbol in the current task's task-local - storage. - -"), - -("Base","task_local_storage","task_local_storage(body, symbol, value) - - Call the function \"body\" with a modified task-local storage, in - which \"value\" is assigned to \"symbol\"; the previous value of - \"symbol\", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. - -"), - -("Base","Condition","Condition() - - Create an edge-triggered event source that tasks can wait for. - Tasks that call \"wait\" on a \"Condition\" are suspended and - queued. Tasks are woken up when \"notify\" is later called on the - \"Condition\". Edge triggering means that only tasks waiting at the - time \"notify\" is called can be woken up. For level-triggered - notifications, you must keep extra state to keep track of whether a - notification has happened. The \"RemoteRef\" type does this, and so - can be used for level-triggered events. - -"), - -("Base","notify","notify(condition, val=nothing; all=true, error=false) - - Wake up tasks waiting for a condition, passing them \"val\". If - \"all\" is true (the default), all waiting tasks are woken, - otherwise only one is. If \"error\" is true, the passed value is - raised as an exception in the woken tasks. - -"), - -("Base","schedule","schedule(t::Task, [val]; error=false) - - Add a task to the scheduler's queue. This causes the task to run - constantly when the system is otherwise idle, unless the task - performs a blocking operation such as \"wait\". - - If a second argument is provided, it will be passed to the task - (via the return value of \"yieldto\") when it runs again. If - \"error\" is true, the value is raised as an exception in the woken - task. - -"), - -("Base","@schedule","@schedule() - - Wrap an expression in a Task and add it to the scheduler's queue. - -"), - -("Base","@task","@task() - - Wrap an expression in a Task without executing it, and return the - Task. This only creates a task, and does not run it. - -"), - -("Base","sleep","sleep(seconds) - - Block the current task for a specified number of seconds. The - minimum sleep time is 1 millisecond or input of \"0.001\". - -"), - -("Base","ReentrantLock","ReentrantLock() - - Creates a reentrant lock. The same task can acquire the lock as - many times as required. Each lock must be matched with an unlock. - -"), - -("Base","lock","lock(l::ReentrantLock) - - Associates \"l\" with the current task. If \"l\" is already locked - by a different task, waits for it to become available. The same - task can acquire the lock multiple times. Each \"lock\" must be - matched by an \"unlock\" - -"), - -("Base","unlock","unlock(l::ReentrantLock) - - Releases ownership of the lock by the current task. If the lock had - been acquired before, it just decrements an internal counter and - returns immediately. - -"), - -("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built \"LocalManager\" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. \"addprocs(4)\" will add 4 processes - on the local machine. - -"), - -("Base","addprocs","addprocs() -> List of process identifiers - - Equivalent to \"addprocs(CPU_CORES)\" - -"), - -("Base","addprocs","addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - \"machines\" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string \"machine_spec\" or a - tuple - \"(machine_spec, count)\" - - \"machine_spec\" is a string of the form \"[user@]host[:port] - [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" - to the standard ssh port. If \"[bind_addr[:port]]\" is specified, - other workers will connect to this worker at the specified - \"bind_addr\" and \"port\". - - \"count\" is the number of workers to be launched on the specified - host. If specified as \":auto\" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: - - \"tunnel\" : if \"true\" then SSH tunneling will be used to connect - to the worker from the master process. - - \"sshflags\" : specifies additional ssh options, e.g. - \"sshflags=`-i /home/foo/bar.pem`\" . - - \"max_parallel\" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. - - \"dir\" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) - - \"exename\" : name of the julia executable. Defaults to - \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case - may be. - - \"exeflags\" : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable \"JULIA_WORKER_TIMEOUT\". The value of - \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. - -"), - -("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster - manager implemented in package \"ClusterManagers\". - - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. - Relevant only when using TCP/IP as transport. - -"), - -("Base","nprocs","nprocs() - - Get the number of available processes. - -"), - -("Base","nworkers","nworkers() - - Get the number of available worker processes. This is one less than - nprocs(). Equal to nprocs() if nprocs() == 1. - -"), - -("Base","procs","procs() - - Returns a list of all process identifiers. - -"), - -("Base","workers","workers() - - Returns a list of all worker process identifiers. - -"), - -("Base","rmprocs","rmprocs(pids...) - - Removes the specified workers. - -"), - -("Base","interrupt","interrupt([pids...]) - - Interrupt the current executing task on the specified workers. This - is equivalent to pressing Ctrl-C on the local machine. If no - arguments are given, all workers are interrupted. - -"), - -("Base","myid","myid() - - Get the id of the current process. - -"), - -("Base","pmap","pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - - Transform collections \"lsts\" by applying \"f\" to each element in - parallel. If \"nprocs() > 1\", the calling process will be - dedicated to assigning tasks. All other available processes will be - used as parallel workers, or on the processes specified by - \"pids\". - - If \"err_retry\" is true, it retries a failed application of \"f\" - on a different worker. If \"err_stop\" is true, it takes precedence - over the value of \"err_retry\" and \"pmap\" stops execution on the - first error. - -"), - -("Base","remotecall","remotecall(id, func, args...) - - Call a function asynchronously on the given arguments on the - specified process. Returns a \"RemoteRef\". - -"), - -("Base","wait","wait([x]) - - Block the current task until some event occurs, depending on the - type of the argument: - - * \"RemoteRef\": Wait for a value to become available for the - specified remote reference. - - * \"Condition\": Wait for \"notify\" on a condition. - - * \"Process\": Wait for a process or process chain to exit. The - \"exitcode\" field of a process can be used to determine success - or failure. - - * \"Task\": Wait for a \"Task\" to finish, returning its result - value. If the task fails with an exception, the exception is - propagated (re-thrown in the task that called \"wait\"). - - * \"RawFD\": Wait for changes on a file descriptor (see *poll_fd* - for keyword arguments and return code) - - If no argument is passed, the task blocks for an undefined period. - If the task's state is set to \":waiting\", it can only be - restarted by an explicit call to \"schedule\" or \"yieldto\". If - the task's state is \":runnable\", it might be restarted - unpredictably. - - Often \"wait\" is called within a \"while\" loop to ensure a - waited-for condition is met before proceeding. - -"), - -("Base","fetch","fetch(RemoteRef) - - Wait for and get the value of a remote reference. - -"), - -("Base","remotecall_wait","remotecall_wait(id, func, args...) - - Perform \"wait(remotecall(...))\" in one message. - -"), - -("Base","remotecall_fetch","remotecall_fetch(id, func, args...) - - Perform \"fetch(remotecall(...))\" in one message. - -"), - -("Base","put!","put!(RemoteRef, value) - - Store a value to a remote reference. Implements \"shared queue of - length 1\" semantics: if a value is already present, blocks until - the value is removed with \"take!\". Returns its first argument. - -"), - -("Base","take!","take!(RemoteRef) - - Fetch the value of a remote reference, removing it so that the - reference is empty again. - -"), - -("Base","isready","isready(r::RemoteRef) - - Determine whether a \"RemoteRef\" has a value stored to it. Note - that this function can cause race conditions, since by the time you - receive its result it may no longer be true. It is recommended that - this function only be used on a \"RemoteRef\" that is assigned - once. - - If the argument \"RemoteRef\" is owned by a different node, this - call will block to wait for the answer. It is recommended to wait - for \"r\" in a separate task instead, or to use a local - \"RemoteRef\" as a proxy: - - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block - -"), - -("Base","RemoteRef","RemoteRef() - - Make an uninitialized remote reference on the local machine. - -"), - -("Base","RemoteRef","RemoteRef(n) - - Make an uninitialized remote reference on process \"n\". - -"), - -("Base","timedwait","timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - - Waits till \"testcb\" returns \"true\" or for \"secs`\" seconds, - whichever is earlier. \"testcb\" is polled every \"pollint\" - seconds. - -"), - -("Base","@spawn","@spawn() - - Execute an expression on an automatically-chosen process, returning - a \"RemoteRef\" to the result. - -"), - -("Base","@spawnat","@spawnat() - - Accepts two arguments, \"p\" and an expression, and runs the - expression asynchronously on process \"p\", returning a - \"RemoteRef\" to the result. - -"), - -("Base","@fetch","@fetch() - - Equivalent to \"fetch(@spawn expr)\". - -"), - -("Base","@fetchfrom","@fetchfrom() - - Equivalent to \"fetch(@spawnat p expr)\". - -"), - -("Base","@async","@async() - - Schedule an expression to run on the local machine, also adding it - to the set of items that the nearest enclosing \"@sync\" waits for. - -"), - -("Base","@sync","@sync() - - Wait until all dynamically-enclosed uses of \"@async\", \"@spawn\", - \"@spawnat\" and \"@parallel\" are complete. - -"), - -("Base","@parallel","@parallel() - - A parallel for loop of the form - - @parallel [reducer] for var = range - body - end - - The specified range is partitioned and locally executed across all - workers. In case an optional reducer function is specified, - @parallel performs local reductions on each worker with a final - reduction on the calling process. - - Note that without a reducer function, @parallel executes - asynchronously, i.e. it spawns independent tasks on all available - workers and returns immediately without waiting for completion. To - wait for completion, prefix the call with \"@sync\", like - - @sync @parallel for var = range - body - end - -"), - -("Base","SharedArray","SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - - Construct a SharedArray of a bitstype \"T\" and size \"dims\" - across the processes specified by \"pids\" - all of which have to - be on the same host. - - If \"pids\" is left unspecified, the shared array will be mapped - across all processes on the current host, including the master. - But, \"localindexes\" and \"indexpids\" will only refer to worker - processes. This facilitates work distribution code to use workers - for actual computation with the master process acting as a driver. - - If an \"init\" function of the type \"initfn(S::SharedArray)\" is - specified, it is called on all the participating workers. - -"), - -("Base","procs","procs(S::SharedArray) - - Get the vector of processes that have mapped the shared array - -"), - -("Base","sdata","sdata(S::SharedArray) - - Returns the actual \"Array\" object backing \"S\" - -"), - -("Base","indexpids","indexpids(S::SharedArray) - - Returns the index of the current worker into the \"pids\" vector, - i.e., the list of workers mapping the SharedArray - -"), - -("Base","launch","launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - - Implemented by cluster managers. For every Julia worker launched by - this function, it should append a \"WorkerConfig\" entry to - \"launched\" and notify \"launch_ntfy\". The function MUST exit - once all workers, requested by \"manager\" have been launched. - \"params\" is a dictionary of all keyword arguments \"addprocs\" - was called with. - -"), - -("Base","manage","manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - - Implemented by cluster managers. It is called on the master - process, during a worker's lifetime, with appropriate \"op\" - values: - - * with \":register\"/\":deregister\" when a worker is added / - removed from the Julia worker pool. - - * with \":interrupt\" when \"interrupt(workers)\" is called. - The \"ClusterManager\" should signal the appropriate worker - with an interrupt signal. - - * with \":finalize\" for cleanup purposes. - -"), - -("Base","kill","kill(manager::FooManager, pid::Int, config::WorkerConfig) - - Implemented by cluster managers. It is called on the master - process, by \"rmprocs\". It should cause the remote worker - specified by \"pid\" to exit. - \"Base.kill(manager::ClusterManager.....)\" executes a remote - \"exit()\" on \"pid\" - -"), - -("Base","init_worker","init_worker(manager::FooManager) - - Called by cluster managers implementing custom transports. It - initializes a newly launched process as a worker. Command line - argument \"--worker\" has the effect of initializing a process as a - worker using TCP/IP sockets for transport. - -"), - -("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id \"pid\", specified - by \"config\" and return a pair of \"AsyncStream\" objects. - Messages from \"pid\" to current process will be read off - \"instrm\", while messages to be sent to \"pid\" will be written to - \"outstrm\". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP - socket connections in-between workers. - -"), - -("Base","Base","Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) - - Called by cluster managers using custom transports. It should be - called when the custom transport implementation receives the first - message from a remote worker. The custom transport must manage a - logical connection to the remote worker and provide two AsyncStream - objects, one for incoming messages and the other for messages - addressed to the remote worker. - -"), - -("Base.Pkg","dir","dir() -> AbstractString - - Returns the absolute path of the package directory. This defaults - to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION - .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell - syntax). If the \"JULIA_PKGDIR\" environment variable is set, then - that path is used in the returned value as \"joinpath(ENV[\"JULIA_ - PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If - \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to - whatever the current working directory is. - -"), - -("Base.Pkg","dir","dir(names...) -> AbstractString - - Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, \"Pkg.dir(pkg)\" returns the path to - the package \"pkg\". - -"), - -("Base.Pkg","init","init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - - Initialize \"Pkg.dir()\" as a package directory. This will be done - automatically when the \"JULIA_PKGDIR\" is not set and - \"Pkg.dir()\" uses its default value. As part of this process, - clones a local METADATA git repository from the site and branch - specified by its arguments, which are typically not provided. - Explicit (non-default) arguments can be used to support a custom - METADATA setup. - -"), - -("Base.Pkg","resolve","resolve() - - Determines an optimal, consistent set of package versions to - install or upgrade to. The optimal set of package versions is based - on the contents of \"Pkg.dir(\"REQUIRE\")\" and the state of - installed packages in \"Pkg.dir()\", Packages that are no longer - required are moved into \"Pkg.dir(\".trash\")\". - -"), - -("Base.Pkg","edit","edit() - - Opens \"Pkg.dir(\"REQUIRE\")\" in the editor specified by the - \"VISUAL\" or \"EDITOR\" environment variables; when the editor - command returns, it runs \"Pkg.resolve()\" to determine and install - a new optimal set of installed package versions. - -"), - -("Base.Pkg","add","add(pkg, vers...) - - Add a requirement entry for \"pkg\" to \"Pkg.dir(\"REQUIRE\")\" and - call \"Pkg.resolve()\". If \"vers\" are given, they must be - \"VersionNumber\" objects and they specify acceptable version - intervals for \"pkg\". - -"), - -("Base.Pkg","rm","rm(pkg) - - Remove all requirement entries for \"pkg\" from - \"Pkg.dir(\"REQUIRE\")\" and call \"Pkg.resolve()\". - -"), - -("Base.Pkg","clone","clone(url[, pkg]) - - Clone a package directly from the git URL \"url\". The package does - not need to be a registered in \"Pkg.dir(\"METADATA\")\". The - package repo is cloned by the name \"pkg\" if provided; if not - provided, \"pkg\" is determined automatically from \"url\". - -"), - -("Base.Pkg","clone","clone(pkg) - - If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone - it from that URL on the default branch. The package does not need - to have any registered versions. - -"), - -("Base.Pkg","available","available() -> Vector{ASCIIString} - - Returns the names of available packages. - -"), - -("Base.Pkg","available","available(pkg) -> Vector{VersionNumber} - - Returns the version numbers available for package \"pkg\". - -"), - -("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} - - Returns a dictionary mapping installed package names to the - installed version number of each package. - -"), - -("Base.Pkg","installed","installed(pkg) -> Void | VersionNumber - - If \"pkg\" is installed, return the installed version number, - otherwise return \"nothing\". - -"), - -("Base.Pkg","status","status() - - Prints out a summary of what packages are installed and what - version and state they're in. - -"), - -("Base.Pkg","update","update() - - Update package the metadata repo – kept in - \"Pkg.dir(\"METADATA\")\" – then update any fixed packages that can - safely be pulled from their origin; then call \"Pkg.resolve()\" to - determine a new optimal set of packages versions. - -"), - -("Base.Pkg","checkout","checkout(pkg[, branch=\"master\"]) - - Checkout the \"Pkg.dir(pkg)\" repo to the branch \"branch\". - Defaults to checking out the \"master\" branch. To go back to using - the newest compatible released version, use \"Pkg.free(pkg)\" - -"), - -("Base.Pkg","pin","pin(pkg) - - Pin \"pkg\" at the current version. To go back to using the newest - compatible released version, use \"Pkg.free(pkg)\" - -"), - -("Base.Pkg","pin","pin(pkg, version) - - Pin \"pkg\" at registered version \"version\". - -"), - -("Base.Pkg","free","free(pkg) - - Free the package \"pkg\" to be managed by the package manager - again. It calls \"Pkg.resolve()\" to determine optimal package - versions after. This is an inverse for both \"Pkg.checkout\" and - \"Pkg.pin\". - - You can also supply an iterable collection of package names, e.g., - \"Pkg.free((\"Pkg1\", \"Pkg2\"))\" to free multiple packages at - once. - -"), - -("Base.Pkg","build","build() - - Run the build scripts for all installed packages in depth-first - recursive order. - -"), - -("Base.Pkg","build","build(pkgs...) - - Run the build script in \"deps/build.jl\" for each package in - \"pkgs\" and all of their dependencies in depth-first recursive - order. This is called automatically by \"Pkg.resolve()\" on all - installed or updated packages. - -"), - -("Base.Pkg","generate","generate(pkg, license) - - Generate a new package named \"pkg\" with one of these license - keys: \"\"MIT\"\", \"\"BSD\"\" or \"\"ASL\"\". If you want to make - a package with a different license, you can edit it afterwards. - Generate creates a git repo at \"Pkg.dir(pkg)\" for the package and - inside it \"LICENSE.md\", \"README.md\", the julia entrypoint - \"\$pkg/src/\$pkg.jl\", and a travis test file, \".travis.yml\". - -"), - -("Base.Pkg","register","register(pkg[, url]) - - Register \"pkg\" at the git URL \"url\", defaulting to the - configured origin URL of the git repo \"Pkg.dir(pkg)\". - -"), - -("Base.Pkg","tag","tag(pkg[, ver[, commit]]) - - Tag \"commit\" as version \"ver\" of package \"pkg\" and create a - version entry in \"METADATA\". If not provided, \"commit\" defaults - to the current commit of the \"pkg\" repo. If \"ver\" is one of the - symbols \":patch\", \":minor\", \":major\" the next patch, minor or - major version is used. If \"ver\" is not provided, it defaults to - \":patch\". - -"), - -("Base.Pkg","publish","publish() - - For each new package version tagged in \"METADATA\" not already - published, make sure that the tagged package commits have been - pushed to the repo at the registered URL for the package and if - they all have, open a pull request to \"METADATA\". - -"), - -("Base.Pkg","test","test() - - Run the tests for all installed packages ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its \"test/runtests.jl\" file - and test dependencies are specified in \"test/REQUIRE\". - -"), - -("Base.Pkg","test","test(pkgs...) - - Run the tests for each package in \"pkgs\" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its \"test/runtests.jl\" file - and test dependencies are specified in \"test/REQUIRE\". - -"), - -("Base","@profile","@profile() - - \"@profile \" runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. - -"), - -("Base.Profile","clear","clear() - - Clear any existing backtraces from the internal buffer. - -"), - -("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) - - Prints profiling results to \"io\" (by default, \"STDOUT\"). If you - do not supply a \"data\" vector, the internal buffer of accumulated - backtraces will be used. \"format\" can be \":tree\" or \":flat\". - If \"C==true\", backtraces from C and Fortran code are shown. - \"combine==true\" merges instruction pointers that correspond to - the same line of code. \"cols\" controls the width of the display. - -"), - -("Base.Profile","print","print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - - Prints profiling results to \"io\". This variant is used to examine - results exported by a previous call to \"retrieve()\". Supply the - vector \"data\" of backtraces and a dictionary \"lidict\" of line - information. - -"), - -("Base.Profile","init","init(; n::Integer, delay::Float64) - - Configure the \"delay\" between backtraces (measured in seconds), - and the number \"n\" of instruction pointers that may be stored. - Each instruction pointer corresponds to a single line of code; - backtraces generally consist of a long list of instruction - pointers. Default settings can be obtained by calling this function - with no arguments, and each can be set independently using keywords - or in the order \"(n, delay)\". - -"), - -("Base.Profile","fetch","fetch() -> data - - Returns a reference to the internal buffer of backtraces. Note that - subsequent operations, like \"clear()\", can affect \"data\" unless - you first make a copy. Note that the values in \"data\" have - meaning only on this machine in the current session, because it - depends on the exact memory addresses used in JIT-compiling. This - function is primarily for internal use; \"retrieve()\" may be a - better choice for most users. - -"), - -("Base.Profile","retrieve","retrieve() -> data, lidict - - \"Exports\" profiling results in a portable format, returning the - set of all backtraces (\"data\") and a dictionary that maps the - (session-specific) instruction pointers in \"data\" to \"LineInfo\" - values that store the file name, function name, and line number. - This function allows you to save profiling results for future - analysis. - -"), - -("Base.Profile","callers","callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - - Given a previous profiling run, determine who called a particular - function. Supplying the filename (and optionally, range of line - numbers over which the function is defined) allows you to - disambiguate an overloaded method. The returned value is a vector - containing a count of the number of calls and line information - about the caller. One can optionally supply backtrace data - obtained from \"retrieve()\"; otherwise, the current internal - profile buffer is used. - -"), - -("Base.Profile","clear_malloc_data","clear_malloc_data() - - Clears any stored memory allocation data when running julia with \" - --track-allocation\". Execute the command(s) you want to test (to - force JIT-compilation), then call \"clear_malloc_data()\". Then - execute your command(s) again, quit Julia, and examine the - resulting \"*.mem\" files. - -"), - - -("Base","sort!","sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the vector \"v\" in place. \"QuickSort\" is used by default - for numeric arrays while \"MergeSort\" is used for other arrays. - You can specify an algorithm to use via the \"alg\" keyword (see - Sorting Algorithms for available algorithms). The \"by\" keyword - lets you provide a function that will be applied to each element - before comparison; the \"lt\" keyword allows providing a custom - \"less than\" function; use \"rev=true\" to reverse the sorting - order. These options are independent and can be used together in - all possible combinations: if both \"by\" and \"lt\" are specified, - the \"lt\" function is applied to the result of the \"by\" - function; \"rev=true\" reverses whatever ordering specified via the - \"by\" and \"lt\" keywords. - -"), - -("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Variant of \"sort!\" that returns a sorted copy of \"v\" leaving - \"v\" itself unmodified. - -"), - -("Base","sort","sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort a multidimensional array \"A\" along the given dimension. - -"), - -("Base","sortperm","sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Return a permutation vector of indices of \"v\" that puts it in - sorted order. Specify \"alg\" to choose a particular sorting - algorithm (see Sorting Algorithms). \"MergeSort\" is used by - default, and since it is stable, the resulting permutation will be - the lexicographically first one that puts the input array into - sorted order – i.e. indices of equal elements appear in ascending - order. If you choose a non-stable sorting algorithm such as - \"QuickSort\", a different permutation that puts the array into - order may be returned. The order is specified using the same - keywords as \"sort!\". - - See also \"sortperm!()\" - -"), - -("Base","sortperm!","sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - - Like \"sortperm\", but accepts a preallocated index vector \"ix\". - If \"initialized\" is \"false\" (the default), ix is initialized to - contain the values \"1:length(v)\". - - See also \"sortperm()\" - -"), - -("Base","sortrows","sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the rows of matrix \"A\" lexicographically. - -"), - -("Base","sortcols","sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the columns of matrix \"A\" lexicographically. - -"), - -("Base","issorted","issorted(v, [by=,] [lt=,] [rev=false]) - - Test whether a vector is in sorted order. The \"by\", \"lt\" and - \"rev\" keywords modify what order is considered to be sorted just - as they do for \"sort\". - -"), - -("Base","searchsorted","searchsorted(a, x, [by=,] [lt=,] [rev=false]) - - Returns the range of indices of \"a\" which compare as equal to - \"x\" according to the order specified by the \"by\", \"lt\" and - \"rev\" keywords, assuming that \"a\" is already sorted in that - order. Returns an empty range located at the insertion point if - \"a\" does not contain values equal to \"x\". - -"), - -("Base","searchsortedfirst","searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - - Returns the index of the first value in \"a\" greater than or equal - to \"x\", according to the specified order. Returns \"length(a)+1\" - if \"x\" is greater than all values in \"a\". - -"), - -("Base","searchsortedlast","searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - - Returns the index of the last value in \"a\" less than or equal to - \"x\", according to the specified order. Returns \"0\" if \"x\" is - less than all values in \"a\". - -"), - -("Base","select!","select!(v, k, [by=,] [lt=,] [rev=false]) - - Partially sort the vector \"v\" in place, according to the order - specified by \"by\", \"lt\" and \"rev\" so that the value at index - \"k\" (or range of adjacent values if \"k\" is a range) occurs at - the position where it would appear if the array were fully sorted - via a non-stable algorithm. If \"k\" is a single index, that value - is returned; if \"k\" is a range, an array of values at those - indices is returned. Note that \"select!\" does not fully sort the - input array. - -"), - -("Base","select","select(v, k, [by=,] [lt=,] [rev=false]) - - Variant of \"select!\" which copies \"v\" before partially sorting - it, thereby returning the same thing as \"select!\" but leaving - \"v\" unmodified. - -"), - -("Base","length","length(s) - - The number of characters in string \"s\". - -"), - -("Base","sizeof","sizeof(s::AbstractString) - - The number of bytes in string \"s\". - -"), - -("Base","*","*(s, t) - - Concatenate strings. The \"*\" operator is an alias to this - function. - - julia> \"Hello \" * \"world\" - \"Hello world\" - -"), - -("Base","^","^(s, n) - - Repeat \"n\" times the string \"s\". The \"^\" operator is an alias - to this function. - - julia> \"Test \"^3 - \"Test Test Test \" - -"), - -("Base","string","string(xs...) - - Create a string from any values using the \"print\" function. - -"), - -("Base","repr","repr(x) - - Create a string from any value using the \"showall\" function. - -"), - -("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) - - Create a string from the address of a C (0-terminated) string - encoded in ASCII or UTF-8. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - -"), - -("Base","bytestring","bytestring(s) - - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. - -"), - -("Base","ascii","ascii(::Array{UInt8, 1}) - - Create an ASCII string from a byte array. - -"), - -("Base","ascii","ascii(s) - - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). - -"), - -("Base","ascii","ascii(::Ptr{UInt8}[, length]) - - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - -"), - -("Base","utf8","utf8(::Array{UInt8, 1}) - - Create a UTF-8 string from a byte array. - -"), - -("Base","utf8","utf8(::Ptr{UInt8}[, length]) - - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - \"length\" is specified, the string does not have to be - 0-terminated. - -"), - -("Base","utf8","utf8(s) - - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). - -"), - -("Base","normalize_string","normalize_string(s, normalform::Symbol) - - Normalize the string \"s\" according to one of the four \"normal - forms\" of the Unicode standard: \"normalform\" can be \":NFC\", - \":NFD\", \":NFKC\", or \":NFKD\". Normal forms C (canonical - composition) and D (canonical decomposition) convert different - visually identical representations of the same abstract string into - a single canonical form, with form C being more compact. Normal - forms KC and KD additionally canonicalize \"compatibility - equivalents\": they convert characters that are abstractly similar - but visually distinct into a single canonical choice (e.g. they - expand ligatures into the individual characters), with form KC - being more compact. - - Alternatively, finer control and additional transformations may be - be obtained by calling *normalize_string(s; keywords...)*, where - any number of the following boolean keywords options (which all - default to \"false\" except for \"compose\") are specified: - - * \"compose=false\": do not perform canonical composition - - * \"decompose=true\": do canonical decomposition instead of - canonical composition (\"compose=true\" is ignored if present) - - * \"compat=true\": compatibility equivalents are canonicalized - - * \"casefold=true\": perform Unicode case folding, e.g. for case- - insensitive string comparison - - * \"newline2lf=true\", \"newline2ls=true\", or - \"newline2ps=true\": convert various newline sequences (LF, CRLF, - CR, NEL) into a linefeed (LF), line-separation (LS), or - paragraph-separation (PS) character, respectively - - * \"stripmark=true\": strip diacritical marks (e.g. accents) - - * \"stripignore=true\": strip Unicode's \"default ignorable\" - characters (e.g. the soft hyphen or the left-to-right marker) - - * \"stripcc=true\": strip control characters; horizontal tabs and - form feeds are converted to spaces; newlines are also converted - to spaces unless a newline-conversion flag was specified - - * \"rejectna=true\": throw an error if unassigned code points are - found - - * \"stable=true\": enforce Unicode Versioning Stability - - For example, NFKC corresponds to the options \"compose=true, - compat=true, stable=true\". - -"), - -("Base","graphemes","graphemes(s) -> iterator over substrings of s - - Returns an iterator over substrings of \"s\" that correspond to the - extended graphemes in the string, as defined by Unicode UAX #29. - (Roughly, these are what users would perceive as single characters, - even though they may contain more than one codepoint; for example a - letter combined with an accent mark is a single grapheme.) - -"), - -("Base","isvalid","isvalid(value) -> Bool - - Returns true if the given value is valid for its type, which - currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" - -"), - -("Base","isvalid","isvalid(T, value) -> Bool - - Returns true if the given value is valid for that type. Types - currently can be \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of - type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and - \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for - \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values - for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or - \"Vector{UInt32}\" - -"), - -("Base","is_assigned_char","is_assigned_char(c) -> Bool - - Returns true if the given char or integer is an assigned Unicode - code point. - -"), - -("Base","ismatch","ismatch(r::Regex, s::AbstractString) -> Bool - - Test whether a string contains a match of the given regular - expression. - -"), - -("Base","match","match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - - Search for the first match of the regular expression \"r\" in \"s\" - and return a RegexMatch object containing the match, or nothing if - the match failed. The matching substring can be retrieved by - accessing \"m.match\" and the captured sequences can be retrieved - by accessing \"m.captures\" The optional \"idx\" argument specifies - an index at which to start the search. - -"), - -("Base","eachmatch","eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - - Search for all matches of a the regular expression \"r\" in \"s\" - and return a iterator over the matches. If overlap is true, the - matching sequences are allowed to overlap indices in the original - string, otherwise they must be from distinct character ranges. - -"), - -("Base","matchall","matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - - Return a vector of the matching substrings from eachmatch. - -"), - -("Base","lpad","lpad(string, n, p) - - Make a string at least \"n\" columns wide when printed, by padding - on the left with copies of \"p\". - -"), - -("Base","rpad","rpad(string, n, p) - - Make a string at least \"n\" columns wide when printed, by padding - on the right with copies of \"p\". - -"), - -("Base","search","search(string, chars[, start]) - - Search for the first occurrence of the given characters within the - given string. The second argument may be a single character, a - vector or a set of characters, a string, or a regular expression - (though regular expressions are only allowed on contiguous strings, - such as ASCII or UTF-8 strings). The third argument optionally - specifies a starting index. The return value is a range of indexes - where the matching sequence is found, such that \"s[search(s,x)] == - x\": - - \"search(string, \"substring\")\" = \"start:end\" such that - \"string[start:end] == \"substring\"\", or \"0:-1\" if unmatched. - - \"search(string, 'c')\" = \"index\" such that - \"string[index] == 'c'\", or \"0\" if unmatched. - -"), - -("Base","rsearch","rsearch(string, chars[, start]) - - Similar to \"search\", but returning the last occurrence of the - given characters within the given string, searching in reverse from - \"start\". - -"), - -("Base","searchindex","searchindex(string, substring[, start]) - - Similar to \"search\", but return only the start index at which the - substring is found, or 0 if it is not. - -"), - -("Base","rsearchindex","rsearchindex(string, substring[, start]) - - Similar to \"rsearch\", but return only the start index at which - the substring is found, or 0 if it is not. - -"), - -("Base","contains","contains(haystack, needle) - - Determine whether the second argument is a substring of the first. - -"), - -("Base","replace","replace(string, pat, r[, n]) - - Search for the given pattern \"pat\", and replace each occurrence - with \"r\". If \"n\" is provided, replace at most \"n\" - occurrences. As with search, the second argument may be a single - character, a vector or a set of characters, a string, or a regular - expression. If \"r\" is a function, each occurrence is replaced - with \"r(s)\" where \"s\" is the matched substring. - -"), - -("Base","split","split(string, [chars]; limit=0, keep=true) - - Return an array of substrings by splitting the given string on - occurrences of the given character delimiters, which may be - specified in any of the formats allowed by \"search\"'s second - argument (i.e. a single character, collection of characters, - string, or regular expression). If \"chars\" is omitted, it - defaults to the set of all space characters, and \"keep\" is taken - to be false. The two keyword arguments are optional: they are are a - maximum size for the result and a flag determining whether empty - fields should be kept in the result. - -"), - -("Base","rsplit","rsplit(string, [chars]; limit=0, keep=true) - - Similar to \"split\", but starting from the end of the string. - -"), - -("Base","strip","strip(string[, chars]) - - Return \"string\" with any leading and trailing whitespace removed. - If \"chars\" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. - -"), - -("Base","lstrip","lstrip(string[, chars]) - - Return \"string\" with any leading whitespace removed. If \"chars\" - (a character, or vector or set of characters) is provided, instead - remove characters contained in it. - -"), - -("Base","rstrip","rstrip(string[, chars]) - - Return \"string\" with any trailing whitespace removed. If - \"chars\" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. - -"), - -("Base","startswith","startswith(string, prefix | chars) - - Returns \"true\" if \"string\" starts with \"prefix\". If the - second argument is a vector or set of characters, tests whether the - first character of \"string\" belongs to that set. - -"), - -("Base","endswith","endswith(string, suffix | chars) - - Returns \"true\" if \"string\" ends with \"suffix\". If the second - argument is a vector or set of characters, tests whether the last - character of \"string\" belongs to that set. - -"), - -("Base","uppercase","uppercase(string) - - Returns \"string\" with all characters converted to uppercase. - -"), - -("Base","lowercase","lowercase(string) - - Returns \"string\" with all characters converted to lowercase. - -"), - -("Base","ucfirst","ucfirst(string) - - Returns \"string\" with the first character converted to uppercase. - -"), - -("Base","lcfirst","lcfirst(string) - - Returns \"string\" with the first character converted to lowercase. - -"), - -("Base","join","join(strings, delim[, last]) - - Join an array of \"strings\" into a single string, inserting the - given delimiter between adjacent strings. If \"last\" is given, it - will be used instead of \"delim\" between the last two strings. For - example, \"join([\"apples\", \"bananas\", \"pineapples\"], \", \", - \" and \") == \"apples, bananas and pineapples\"\". - - \"strings\" can be any iterable over elements \"x\" which are - convertible to strings via \"print(io::IOBuffer, x)\". - -"), - -("Base","chop","chop(string) - - Remove the last character from a string - -"), - -("Base","chomp","chomp(string) - - Remove a trailing newline from a string - -"), - -("Base","ind2chr","ind2chr(string, i) - - Convert a byte index to a character index - -"), - -("Base","chr2ind","chr2ind(string, i) - - Convert a character index to a byte index - -"), - -("Base","isvalid","isvalid(str, i) - - Tells whether index \"i\" is valid for the given string - -"), - -("Base","nextind","nextind(str, i) - - Get the next valid string index after \"i\". Returns a value - greater than \"endof(str)\" at or after the end of the string. - -"), - -("Base","prevind","prevind(str, i) - - Get the previous valid string index before \"i\". Returns a value - less than \"1\" at the beginning of the string. - -"), - -("Base","randstring","randstring([rng], len=8) - - Create a random ASCII string of length \"len\", consisting of - upper- and lower-case letters and the digits 0-9. The optional - \"rng\" argument specifies a random number generator, see *Random - Numbers*. - -"), - -("Base","charwidth","charwidth(c) - - Gives the number of columns needed to print a character. - -"), - -("Base","strwidth","strwidth(s) - - Gives the number of columns needed to print a string. - -"), - -("Base","isalnum","isalnum(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is alphanumeric, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter or - Number, i.e. a character whose category code begins with 'L' or - 'N'. - -"), - -("Base","isalpha","isalpha(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is alphabetic, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter, - i.e. a character whose category code begins with 'L'. - -"), - -("Base","isascii","isascii(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character belongs to the ASCII character set, or - whether this is true for all elements of a string. - -"), - -("Base","iscntrl","iscntrl(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a control character, or whether this - is true for all elements of a string. Control characters are the - non-printing characters of the Latin-1 subset of Unicode. - -"), - -("Base","isdigit","isdigit(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a numeric digit (0-9), or whether this - is true for all elements of a string. - -"), - -("Base","isgraph","isgraph(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is printable, and not a space, or whether - this is true for all elements of a string. Any character that - would cause a printer to use ink should be classified with - isgraph(c)==true. - -"), - -("Base","islower","islower(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a lowercase letter, or whether this is - true for all elements of a string. A character is classified as - lowercase if it belongs to Unicode category Ll, Letter: Lowercase. - -"), - -("Base","isnumber","isnumber(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is numeric, or whether this is true for - all elements of a string. A character is classified as numeric if - it belongs to the Unicode general category Number, i.e. a character - whose category code begins with 'N'. - -"), - -("Base","isprint","isprint(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is printable, including spaces, but not a - control character. For strings, tests whether this is true for all - elements of the string. - -"), - -("Base","ispunct","ispunct(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character belongs to the Unicode general category - Punctuation, i.e. a character whose category code begins with 'P'. - For strings, tests whether this is true for all elements of the - string. - -"), - -("Base","isspace","isspace(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is any whitespace character. Includes - ASCII characters '\\t', '\\n', '\\v', '\\f', '\\r', and ' ', - Latin-1 character U+0085, and characters in Unicode category Zs. - For strings, tests whether this is true for all elements of the - string. - -"), - -("Base","isupper","isupper(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is an uppercase letter, or whether this - is true for all elements of a string. A character is classified - as uppercase if it belongs to Unicode category Lu, Letter: - Uppercase, or Lt, Letter: Titlecase. - -"), - -("Base","isxdigit","isxdigit(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a valid hexadecimal digit, or whether - this is true for all elements of a string. - -"), - -("Base","symbol","symbol(x...) -> Symbol - - Create a \"Symbol\" by concatenating the string representations of - the arguments together. - -"), - -("Base","escape_string","escape_string(str::AbstractString) -> AbstractString - - General escaping of traditional C and Unicode escape sequences. See - \"print_escaped()\" for more general escaping. - -"), - -("Base","unescape_string","unescape_string(s::AbstractString) -> AbstractString - - General unescaping of traditional C and Unicode escape sequences. - Reverse of \"escape_string()\". See also \"print_unescaped()\". - -"), - -("Base","utf16","utf16(s) - - Create a UTF-16 string from a byte array, array of \"UInt16\", or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) - - Note that the resulting \"UTF16String\" data is terminated by the - NUL codepoint (16-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf16(s)* conversion function. If you have a \"UInt16\" array - \"A\" that is already NUL-terminated valid UTF-16 data, then you - can instead use *UTF16String(A)`* to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. - -"), - -("Base","utf16","utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If \"length\" is - specified, the string does not have to be NUL-terminated. - -"), - -("Base","utf32","utf32(s) - - Create a UTF-32 string from a byte array, array of \"Char\" or - \"UInt32\", or any other string type. (Conversions of byte arrays - check for a byte-order marker in the first four bytes, and do not - include it in the resulting string.) - - Note that the resulting \"UTF32String\" data is terminated by the - NUL codepoint (32-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf32(s)* conversion function. If you have a \"Char\" or - \"UInt32\" array \"A\" that is already NUL-terminated UTF-32 data, - then you can instead use *UTF32String(A)`* to construct the string - without making a copy of the data and treating the NUL as a - terminator rather than as part of the string. - -"), - -("Base","utf32","utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) - - Create a string from the address of a NUL-terminated UTF-32 string. - A copy is made; the pointer can be safely freed. If \"length\" is - specified, the string does not have to be NUL-terminated. - -"), - -("Base","wstring","wstring(s) - - This is a synonym for either \"utf32(s)\" or \"utf16(s)\", - depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. - The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is - also provided. - -"), - -("Base","runtests","runtests([tests=[\"all\"][, numcores=iceil(CPU_CORES/2)]]) - - Run the Julia unit tests listed in \"tests\", which can be either a - string or an array of strings, using \"numcores\" processors. (not - exported) - -"), - -("Base.Test","@test","@test(ex) - - Test the expression \"ex\" and calls the current handler to handle - the result. - -"), - -("Base.Test","@test_throws","@test_throws(extype, ex) - - Test that the expression \"ex\" throws an exception of type - \"extype\" and calls the current handler to handle the result. - -"), - -("Base.Test","@test_approx_eq","@test_approx_eq(a, b) - - Test two floating point numbers \"a\" and \"b\" for equality taking - in account small numerical errors. - -"), - -("Base.Test","@test_approx_eq_eps","@test_approx_eq_eps(a, b, tol) - - Test two floating point numbers \"a\" and \"b\" for equality taking - in account a margin of tolerance given by \"tol\". - -"), - -("Base.Test","with_handler","with_handler(f, handler) - - Run the function \"f\" using the \"handler\" as the handler. - -"), - - -] diff --git a/test/docs.jl b/test/docs.jl index 956455e4d7dba..8f66c0f32348b 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -20,70 +20,3 @@ end @test (@doc ModuleMacroDoc) == "I am a module" @test (@doc ModuleMacroDoc.@m) == ["I am a macro"] - -# apropos function testing - -@test sprint(apropos, "non-documented object") == "No help information found.\n" - -# issue 11438 (partial) - -for (typ, name) in [ - (RoundingMode, "RoundingMode"), - (Dates.DateTime, "DateTime"), - (Libc.TmStruct, "TmStruct") - ] - @test sprint(help, typ) == sprint(help, name) -end - -module DataTypeHelpTest - -module M - type T end -end - -module N - type T end -end - -module P - module R - type U end - type T end - end - import .R.T -end - -const mod = string(current_module()) - -Base.Help.eval(quote - - init_help() - - import $(parse(mod)) - import $(parse(mod)): M, N, P - - const mod = $mod - - MODULE_DICT["T"] = ["$mod.M","$mod.N","$mod.P"] - MODULE_DICT["U"] = ["$mod.P","$mod.P.R"] - - FUNCTION_DICT["$mod.M.T"] = ["M.T"] - FUNCTION_DICT["$mod.N.T"] = ["N.T"] - FUNCTION_DICT["$mod.P.T"] = ["P.R.T"] - FUNCTION_DICT["$mod.P.U"] = ["P.U"] - FUNCTION_DICT["$mod.P.R.U"] = ["P.R.U"] - -end) - -import Base.Test.@test - -@test sprint(help, M.T) == "M.T\n" -@test sprint(help, N.T) == "N.T\n" -@test sprint(help, P.T) == "P.R.T\n" -@test sprint(help, P.R.U) == "P.R.U\n" -@test sprint(help, "$mod.M.T") == "M.T\n" -@test sprint(help, "$mod.N.T") == "N.T\n" -@test sprint(help, "$mod.P.T") == "P.R.T\n" -@test sprint(help, "$mod.P.R.U") == "P.R.U\n" -@test sprint(help, "T") == "M.T\n\nN.T\n\nP.R.T\n" -end From db6eccfd6c5767b1c977618899b50f4041502585 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 16:24:26 -0400 Subject: [PATCH 05/27] stdlib generating script --- doc/genstdlib.jl | 66 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 doc/genstdlib.jl diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl new file mode 100644 index 0000000000000..73e9a824e3b52 --- /dev/null +++ b/doc/genstdlib.jl @@ -0,0 +1,66 @@ +using .Markdown + +cd(dirname(@__FILE__)) + +isrst(md) = + length(md.content) == 1 && + isa(md.content[1], Markdown.Code) && + md.content[1].language == "rst" + +rst(md) = isrst(md) ? join(split(md.content[1].code, "\n")[3:end], "\n") : Markdown.rst(md) + +isop(func) = ismatch(r"[^\w@!.]|^!$", func) + +ident(mod, x) = "$mod.$(isop(x) ? "(:($x))" : x)" + +getdoc(mod, x) = try eval(parse("@doc $(ident(mod, x))")) catch e end + +function translate(file) + @assert isfile(file) + ls = split(readall(file), "\n")[1:end-1] + doccing = false + func = nothing + mod = "Base" + + open(file, "w+") do io + for l in ls + if ismatch(r".. (current)?module::", l) + mod = match(r".. (current)?module:: ([\w\.]+)", l).captures[2] + println(io, l) + elseif startswith(l, ".. function::") + func = match(r".. function:: (@?[^\(\s\{]+)", l) + func == nothing && (warn("bad function $l"); continue) + func = func.captures[1] + + if getdoc(mod, func) == nothing + info("no docs for $(ident(mod, func))") + println(io, l) + doccing = false + continue + end + + doccing = true + println(io, l) + println(io) + println(io, rst(getdoc(mod, func))) + println(io) + elseif doccing && (startswith(l, " ") || ismatch(r"^\s*$", l)) + else + doccing = false + println(io, l) + end + end + end +end + +println("\nConveting stdlib/\n") + +for file in readdir("stdlib") + translate("stdlib/$file") +end + +println("\nConverting devdocs/\n") + +for file in readdir("devdocs") + translate("devdocs/$file") +end From 49deb27526d53723fa233194a6d8aa8e025b8ab2 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 16:49:06 -0400 Subject: [PATCH 06/27] delete newdoc.jl --- doc/newdoc.jl | 30 ------------------------------ 1 file changed, 30 deletions(-) delete mode 100644 doc/newdoc.jl diff --git a/doc/newdoc.jl b/doc/newdoc.jl deleted file mode 100644 index 5d0857894d78d..0000000000000 --- a/doc/newdoc.jl +++ /dev/null @@ -1,30 +0,0 @@ -using Base.Meta - -exceptions = ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN"] - -qualify = ["ccall", "in", "<:", "|>", "*", "\\", "*", "/", "^", ".+", ".-", ".*", - "./", ".\\", ".^", "//", "<<", ">>", ">>>", "==", "!=", "===", "!==", - "<", "<=", ">", ">=", ".==", ".!=", ".<", ".<=", ".>", ".>=", "|", "*", - "^"] - -cd(joinpath(dirname(@__FILE__), "..", "base", "docs")) do - open("helpdb.jl", "w") do io - for (mod, func, desc) in evalfile(Base.Help.helpdb_filename()) - (func in exceptions || ismatch(r"[\{\} ]", func)) && continue - isop = ismatch(r"[^\w@!]|^!$", func) - isbase = mod == "Base" && !(func in qualify) - - isop && !isbase && (func = "(:($func))") - desc = replace(rstrip(desc), "\$", "\\\$") - desc = replace(desc, "\"\"\"", "\\\"\"\"") - - println(io, """ - @doc doc\""" - ```rst - $desc - ``` - \""" $(isbase ? func : "$mod.$func") - """) - end - end -end From f66b9c0bd9e316db6e84f6a8311de0a571d0b279 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 17:25:41 -0400 Subject: [PATCH 07/27] convert help to markdown yay --- base/docs/helpdb.jl | 28578 +++++++++++++++++++----------------------- 1 file changed, 12644 insertions(+), 15934 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index b3d6398567e8c..952a01ea82c9e 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -1,16098 +1,12808 @@ - @doc doc""" - ```rst - ndims(A) -> Integer - - Returns the number of dimensions of A - ``` - """ ndims - - @doc doc""" - ```rst - size(A[, 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 = rand(2,3,4); - - julia> size(A, 2) - 3 - - julia> size(A,3,2) - (4,3) - ``` - """ size - - @doc doc""" - ```rst - iseltype(A, T) - - Tests whether A or its elements are of type T - ``` - """ iseltype - - @doc doc""" - ```rst - length(A) -> Integer - - Returns the number of elements in A - ``` - """ length - - @doc doc""" - ```rst - 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 (like "Array"), this is - simply the range "1:length(A)". For other array types, this - returns a specialized Cartesian range to efficiently index into the - array with indices specified for every dimension. Example for a - sparse 2-d array: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 - ``` - """ eachindex - - @doc doc""" - ```rst - Base.linearindexing(A) - - "linearindexing" defines how an AbstractArray most efficiently - accesses its elements. If "Base.linearindexing(A)" returns - "Base.LinearFast()", this means that linear indexing with only - one index is an efficient operation. If it instead returns - "Base.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 - traits-based 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 define "linearindexing" in the - type-domain: - - Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() - ``` - """ Base - - @doc doc""" - ```rst - countnz(A) - - Counts the number of nonzero values in array A (dense or sparse). - Note that this is not a constant-time operation. For sparse - matrices, one should usually use "nnz", which returns the number - of stored values. - ``` - """ countnz - - @doc doc""" - ```rst - conj!(A) - - Convert an array to its complex conjugate in-place - ``` - """ conj! - - @doc doc""" - ```rst - stride(A, k) - - Returns the distance in memory (in number of elements) between - adjacent elements in dimension k - ``` - """ stride - - @doc doc""" - ```rst - strides(A) - - Returns a tuple of the memory strides in each dimension - ``` - """ strides - - @doc doc""" - ```rst - ind2sub(dims, index) -> subscripts - - Returns a tuple of subscripts into an array with dimensions - "dims", corresponding to the linear index "index" - - **Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides - the indices of the maximum element - ``` - """ ind2sub - - @doc doc""" - ```rst - ind2sub(a, index) -> subscripts - - Returns a tuple of subscripts into array "a" corresponding to the - linear index "index" - ``` - """ ind2sub - - @doc doc""" - ```rst - sub2ind(dims, i, j, k...) -> index - - The inverse of "ind2sub", returns the linear index corresponding - to the provided subscripts - ``` - """ sub2ind - - @doc doc""" - ```rst - Array(dims) - - "Array{T}(dims)" constructs an uninitialized dense array with - element type "T". "dims" may be a tuple or a series of integer - arguments. The syntax "Array(T, dims)" is also available, but - deprecated. - ``` - """ Array - - @doc doc""" - ```rst - getindex(type[, elements...]) - - Construct a 1-d array of the specified type. This is usually called - with the syntax "Type[]". Element values can be specified using - "Type[a,b,c,...]". - ``` - """ getindex - - @doc doc""" - ```rst - cell(dims) - - Construct an uninitialized cell array (heterogeneous array). - "dims" can be either a tuple or a series of integer arguments. - ``` - """ cell - - @doc doc""" - ```rst - zeros(type, dims) - - Create an array of all zeros of specified type. The type defaults - to Float64 if not specified. - ``` - """ zeros - - @doc doc""" - ```rst - zeros(A) - - Create an array of all zeros with the same element type and shape - as A. - ``` - """ zeros - - @doc doc""" - ```rst - ones(type, dims) - - Create an array of all ones of specified type. The type defaults to - Float64 if not specified. - ``` - """ ones - - @doc doc""" - ```rst - ones(A) - - Create an array of all ones with the same element type and shape as - A. - ``` - """ ones - - @doc doc""" - ```rst - trues(dims) - - Create a "BitArray" with all values set to true - ``` - """ trues - - @doc doc""" - ```rst - falses(dims) - - Create a "BitArray" with all values set to false - ``` - """ falses - - @doc doc""" - ```rst - fill(x, dims) - - Create an array filled with the value "x". For example, - "fill(1.0, (10,10))" returns a 10x10 array of floats, with each - element initialized to 1.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 evaluating "Foo()" once. - ``` - """ fill - - @doc doc""" - ```rst - fill!(A, x) - - Fill array "A" with the value "x". If "x" is an object - reference, all elements will refer to the same object. "fill!(A, - Foo())" will return "A" filled with the result of evaluating - "Foo()" once. - ``` - """ fill! - - @doc doc""" - ```rst - reshape(A, dims) - - Create an array with the same data as the given array, but with - different dimensions. An implementation for a particular type of - array may choose whether the data is copied or shared. - ``` - """ reshape - - @doc doc""" - ```rst - similar(array, element_type, dims) - - Create an uninitialized array of the same type as the given array, - but with the specified element type and dimensions. The second and - third arguments are both optional. The "dims" argument may be a - tuple or a series of integer arguments. For some special - "AbstractArray" objects which are not real containers (like - ranges), this function returns a standard "Array" to allow - operating on elements. - ``` - """ similar - - @doc doc""" - ```rst - reinterpret(type, A) - - Change the type-interpretation of a block of memory. For example, - "reinterpret(Float32, UInt32(7))" interprets the 4 bytes - corresponding to "UInt32(7)" as a "Float32". For arrays, this - constructs an array with the same binary data as the given array, - but with the specified element type. - ``` - """ reinterpret - - @doc doc""" - ```rst - eye(n) - - n-by-n identity matrix - ``` - """ eye - - @doc doc""" - ```rst - eye(m, n) - - m-by-n identity matrix - ``` - """ eye - - @doc doc""" - ```rst - eye(A) - - Constructs an identity matrix of the same dimensions and type as - "A". - ``` - """ eye - - @doc doc""" - ```rst - linspace(start, stop, n=100) - - Construct a range of "n" linearly spaced elements from "start" - to "stop". - ``` - """ linspace - - @doc doc""" - ```rst - logspace(start, stop, n=50) - - Construct a vector of "n" logarithmically spaced numbers from - "10^start" to "10^stop". - ``` - """ logspace - - @doc doc""" - ```rst - broadcast(f, As...) - - Broadcasts the arrays "As" to a common size by expanding - singleton dimensions, and returns an array of the results - "f(as...)" for each position. - ``` - """ broadcast - - @doc doc""" - ```rst - broadcast!(f, dest, As...) - - Like "broadcast", but store the result of "broadcast(f, As...)" - in the "dest" array. Note that "dest" is only used to store the - result, and does not supply arguments to "f" unless it is also - listed in the "As", as in "broadcast!(f, A, A, B)" to perform - "A[:] = broadcast(f, A, B)". - ``` - """ broadcast! - - @doc doc""" - ```rst - bitbroadcast(f, As...) - - Like "broadcast", but allocates a "BitArray" to store the - result, rather then an "Array". - ``` - """ bitbroadcast - - @doc doc""" - ```rst - broadcast_function(f) - - Returns a function "broadcast_f" such that - "broadcast_function(f)(As...) === broadcast(f, As...)". Most - useful in the form "const broadcast_f = broadcast_function(f)". - ``` - """ broadcast_function - - @doc doc""" - ```rst - broadcast!_function(f) - - Like "broadcast_function", but for "broadcast!". - ``` - """ broadcast!_function - - @doc doc""" - ```rst - getindex(A, inds...) - - Returns a subset of array "A" as specified by "inds", where - each "ind" may be an "Int", a "Range", or a "Vector". See - the manual section on *array indexing* for details. - ``` - """ getindex - - @doc doc""" - ```rst - sub(A, inds...) - - Like "getindex()", but returns a view into the parent array "A" - with the given indices instead of making a copy. Calling - "getindex()" or "setindex!()" on the returned "SubArray" - computes the indices to the parent array on the fly without - checking bounds. - ``` - """ sub - - @doc doc""" - ```rst - parent(A) - - Returns the "parent array" of an array view type (e.g., - SubArray), or the array itself if it is not a view - ``` - """ parent - - @doc doc""" - ```rst - parentindexes(A) - - From an array view "A", returns the corresponding indexes in the - parent - ``` - """ parentindexes - - @doc doc""" - ```rst - slicedim(A, d, i) - - Return all the data of "A" where the index for dimension "d" - equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is - in position "d". - ``` - """ slicedim - - @doc doc""" - ```rst - slice(A, inds...) - - Returns a view of array "A" with the given indices like - "sub()", but drops all dimensions indexed with scalars. - ``` - """ slice - - @doc doc""" - ```rst - setindex!(A, X, inds...) - - Store values from array "X" within some subset of "A" as - specified by "inds". - ``` - """ setindex! - - @doc doc""" - ```rst - broadcast_getindex(A, inds...) - - Broadcasts the "inds" arrays to a common size like "broadcast", - and returns an array of the results "A[ks...]", where "ks" goes - over the positions in the broadcast. - ``` - """ broadcast_getindex - - @doc doc""" - ```rst - broadcast_setindex!(A, X, inds...) - - Broadcasts the "X" and "inds" arrays to a common size and - stores the value from each position in "X" at the indices given - by the same positions in "inds". - ``` - """ broadcast_setindex! - - @doc doc""" - ```rst - cat(dims, A...) - - Concatenate the input arrays along the specified dimensions in the - iterable "dims". For dimensions not in "dims", all input arrays - should have the same size, which will also be the size of the - output array along that dimension. For dimensions in "dims", the - size of the output array is the sum of the sizes of the input - arrays along that dimension. If "dims" is a single number, the - different arrays are tightly stacked along that dimension. If - "dims" is an iterable containing several dimensions, this allows - to construct block diagonal matrices and their higher-dimensional - 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 with *matrices[1]*, *matrices[2]*, ... as diagonal - blocks and matching zero blocks away from the diagonal. - ``` - """ cat - - @doc doc""" - ```rst - vcat(A...) - - Concatenate along dimension 1 - ``` - """ vcat - - @doc doc""" - ```rst - hcat(A...) - - Concatenate along dimension 2 - ``` - """ hcat - - @doc doc""" - ```rst - 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. For example, - "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". - - If the first argument is a single integer "n", then all block - rows are assumed to have "n" block columns. - ``` - """ hvcat - - @doc doc""" - ```rst - flipdim(A, d) - - Reverse "A" in dimension "d". - ``` - """ flipdim - - @doc doc""" - ```rst - circshift(A, shifts) - - Circularly shift the data in an array. The second argument is a - vector giving the amount to shift in each dimension. - ``` - """ circshift - - @doc doc""" - ```rst - find(A) - - Return a vector of the linear indexes of the non-zeros in "A" - (determined by "A[i]!=0"). A common use of this is to convert a - boolean array to an array of indexes of the "true" elements. - ``` - """ find - - @doc doc""" - ```rst - find(f, A) - - Return a vector of the linear indexes of "A" where "f" returns - true. - ``` - """ find - - @doc doc""" - ```rst - findn(A) - - Return a vector of indexes for each dimension giving the locations - of the non-zeros in "A" (determined by "A[i]!=0"). - ``` - """ findn - - @doc doc""" - ```rst - findnz(A) - - Return a tuple "(I, J, V)" where "I" and "J" are the row and - column indexes of the non-zero values in matrix "A", and "V" is - a vector of the non-zero values. - ``` - """ findnz - - @doc doc""" - ```rst - findfirst(A) - - Return the index of the first non-zero value in "A" (determined - by "A[i]!=0"). - ``` - """ findfirst - - @doc doc""" - ```rst - findfirst(A, v) - - Return the index of the first element equal to "v" in "A". - ``` - """ findfirst - - @doc doc""" - ```rst - findfirst(predicate, A) - - Return the index of the first element of "A" for which - "predicate" returns true. - ``` - """ findfirst - - @doc doc""" - ```rst - findlast(A) - - Return the index of the last non-zero value in "A" (determined by - "A[i]!=0"). - ``` - """ findlast - - @doc doc""" - ```rst - findlast(A, v) - - Return the index of the last element equal to "v" in "A". - ``` - """ findlast - - @doc doc""" - ```rst - findlast(predicate, A) - - Return the index of the last element of "A" for which - "predicate" returns true. - ``` - """ findlast - - @doc doc""" - ```rst - findnext(A, i) - - Find the next index >= "i" of a non-zero element of "A", or - "0" if not found. - ``` - """ findnext - - @doc doc""" - ```rst - findnext(predicate, A, i) - - Find the next index >= "i" of an element of "A" for which - "predicate" returns true, or "0" if not found. - ``` - """ findnext - - @doc doc""" - ```rst - findnext(A, v, i) - - Find the next index >= "i" of an element of "A" equal to "v" - (using "=="), or "0" if not found. - ``` - """ findnext - - @doc doc""" - ```rst - findprev(A, i) - - Find the previous index <= "i" of a non-zero element of "A", or - 0 if not found. - ``` - """ findprev - - @doc doc""" - ```rst - findprev(predicate, A, i) - - Find the previous index <= "i" of an element of "A" for which - "predicate" returns true, or "0" if not found. - ``` - """ findprev - - @doc doc""" - ```rst - findprev(A, v, i) - - Find the previous index <= "i" of an element of "A" equal to - "v" (using "=="), or "0" if not found. - ``` - """ findprev - - @doc doc""" - ```rst - permutedims(A, perm) - - Permute the dimensions of array "A". "perm" is a vector - specifying a permutation of length "ndims(A)". This is a - generalization of transpose for multi-dimensional arrays. Transpose - is equivalent to "permutedims(A, [2,1])". - ``` - """ permutedims - - @doc doc""" - ```rst - ipermutedims(A, perm) - - Like "permutedims()", except the inverse of the given permutation - is applied. - ``` - """ ipermutedims - - @doc doc""" - ```rst - permutedims!(dest, src, perm) - - Permute the dimensions of array "src" and store the result in the - array "dest". "perm" is a vector specifying a permutation of - length "ndims(src)". The preallocated array "dest" should have - "size(dest) == size(src)[perm]" and is completely overwritten. No - in-place permutation is supported and unexpected results will - happen if *src* and *dest* have overlapping memory regions. - ``` - """ permutedims! - - @doc doc""" - ```rst - squeeze(A, dims) - - Remove the dimensions specified by "dims" from array "A". - Elements of "dims" must be unique and within the range - "1:ndims(A)". - ``` - """ squeeze - - @doc doc""" - ```rst - vec(Array) -> Vector - - Vectorize an array using column-major convention. - ``` - """ vec - - @doc doc""" - ```rst - promote_shape(s1, s2) - - Check two array shapes for compatibility, allowing trailing - singleton dimensions, and return whichever shape has more - dimensions. - ``` - """ promote_shape - - @doc doc""" - ```rst - checkbounds(array, indexes...) - - Throw an error if the specified indexes are not in bounds for the - given array. - ``` - """ checkbounds - - @doc doc""" - ```rst - randsubseq(A, p) -> Vector - - Return a vector consisting of a random subsequence of the given - array "A", where each element of "A" is included (in order) - with independent probability "p". (Complexity is linear in - "p*length(A)", so this function is efficient even if "p" is - small and "A" is large.) Technically, this process is known as - "Bernoulli sampling" of "A". - ``` - """ randsubseq - - @doc doc""" - ```rst - randsubseq!(S, A, p) - - Like "randsubseq", but the results are stored in "S" (which is - resized as needed). - ``` - """ randsubseq! - - @doc doc""" - ```rst - cumprod(A[, dim]) - - Cumulative product along a dimension "dim" (defaults to 1). See - also "cumprod!()" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). - ``` - """ cumprod - - @doc doc""" - ```rst - cumprod!(B, A[, dim]) - - Cumulative product of "A" along a dimension, storing the result - in "B". The dimension defaults to 1. - ``` - """ cumprod! - - @doc doc""" - ```rst - cumsum(A[, dim]) - - Cumulative sum along a dimension "dim" (defaults to 1). See also - "cumsum!()" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). - ``` - """ cumsum - - @doc doc""" - ```rst - cumsum!(B, A[, dim]) - - Cumulative sum of "A" along a dimension, storing the result in - "B". The dimension defaults to 1. - ``` - """ cumsum! - - @doc doc""" - ```rst - cumsum_kbn(A[, dim]) - - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. The - dimension defaults to 1. - ``` - """ cumsum_kbn - - @doc doc""" - ```rst - cummin(A[, dim]) - - Cumulative minimum along a dimension. The dimension defaults to 1. - ``` - """ cummin - - @doc doc""" - ```rst - cummax(A[, dim]) - - Cumulative maximum along a dimension. The dimension defaults to 1. - ``` - """ cummax - - @doc doc""" - ```rst - diff(A[, dim]) - - Finite difference operator of matrix or vector. - ``` - """ diff - - @doc doc""" - ```rst - gradient(F[, h]) - - Compute differences along vector "F", using "h" as the spacing - between points. The default spacing is one. - ``` - """ gradient - - @doc doc""" - ```rst - rot180(A) - - Rotate matrix "A" 180 degrees. - ``` - """ rot180 - - @doc doc""" - ```rst - rot180(A, k) - - Rotate matrix "A" 180 degrees an integer "k" number of times. - If "k" is even, this is equivalent to a "copy". - ``` - """ rot180 - - @doc doc""" - ```rst - rotl90(A) - - Rotate matrix "A" left 90 degrees. - ``` - """ rotl90 - - @doc doc""" - ```rst - rotl90(A, k) - - Rotate matrix "A" left 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". - ``` - """ rotl90 - - @doc doc""" - ```rst - rotr90(A) - - Rotate matrix "A" right 90 degrees. - ``` - """ rotr90 - - @doc doc""" - ```rst - rotr90(A, k) - - Rotate matrix "A" right 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". - ``` - """ rotr90 - - @doc doc""" - ```rst - reducedim(f, A, dims[, initial]) - - Reduce 2-argument function "f" along dimensions of "A". - "dims" is a vector specifying the dimensions to reduce, and - "initial" is the initial value to use in the reductions. For *+*, - ***, *max* and *min* the *initial* argument is optional. - - The associativity of the reduction is implementation-dependent; if - you need a particular associativity, e.g. left-to-right, you should - write your own loop. See documentation for "reduce". - ``` - """ reducedim - - @doc doc""" - ```rst - mapreducedim(f, op, A, dims[, initial]) - - Evaluates to the same as *reducedim(op, map(f, A), dims, - f(initial))*, but is generally faster because the intermediate - array is avoided. - ``` - """ mapreducedim - - @doc doc""" - ```rst - mapslices(f, A, dims) - - Transform the given dimensions of array "A" using function "f". - "f" is called on each slice of "A" of the form - "A[...,:,...,:,...]". "dims" is an integer vector specifying - where the colons go in this expression. The results are - concatenated along the remaining dimensions. For example, if - "dims" is "[1,2]" and A is 4-dimensional, "f" is called on - "A[:,:,i,j]" for all "i" and "j". - ``` - """ mapslices - - @doc doc""" - ```rst - sum_kbn(A) - - Returns the sum of all array elements, using the Kahan-Babuska- - Neumaier compensated summation algorithm for additional accuracy. - ``` - """ sum_kbn - - @doc doc""" - ```rst - cartesianmap(f, dims) - - Given a "dims" tuple of integers "(m, n, ...)", call "f" on - all combinations of integers in the ranges "1:m", "1:n", etc. - - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 - ``` - """ cartesianmap - - @doc doc""" - ```rst - nthperm(v, k) - - Compute the kth lexicographic permutation of a vector. - ``` - """ nthperm - - @doc doc""" - ```rst - nthperm(p) - - Return the "k" that generated permutation "p". Note that - "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". - ``` - """ nthperm - - @doc doc""" - ```rst - nthperm!(v, k) - - In-place version of "nthperm()". - ``` - """ nthperm! - - @doc doc""" - ```rst - randperm([rng], n) - - Construct a random permutation of length "n". The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. - ``` - """ randperm - - @doc doc""" - ```rst - invperm(v) - - Return the inverse permutation of v. - ``` - """ invperm - - @doc doc""" - ```rst - isperm(v) -> Bool - - Returns true if v is a valid permutation. - ``` - """ isperm - - @doc doc""" - ```rst - permute!(v, p) - - Permute vector "v" in-place, according to permutation "p". No - checking is done to verify that "p" is a permutation. - - To return a new permutation, use "v[p]". Note that this is - generally faster than "permute!(v,p)" for large vectors. - ``` - """ permute! - - @doc doc""" - ```rst - ipermute!(v, p) - - Like permute!, but the inverse of the given permutation is applied. - ``` - """ ipermute! - - @doc doc""" - ```rst - randcycle([rng], n) - - Construct a random cyclic permutation of length "n". The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. - ``` - """ randcycle - - @doc doc""" - ```rst - shuffle([rng], v) - - Return a randomly permuted copy of "v". The optional "rng" - argument specifies a random number generator, see *Random Numbers*. - ``` - """ shuffle - - @doc doc""" - ```rst - shuffle!([rng], v) - - In-place version of "shuffle()". - ``` - """ shuffle! - - @doc doc""" - ```rst - reverse(v[, start=1[, stop=length(v)]]) - - Return a copy of "v" reversed from start to stop. - ``` - """ reverse - - @doc doc""" - ```rst - reverseind(v, i) - - Given an index "i" in "reverse(v)", return the corresponding - index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". - (This can be nontrivial in the case where "v" is a Unicode - string.) - ``` - """ reverseind - - @doc doc""" - ```rst - reverse!(v[, start=1[, stop=length(v)]]) -> v - - In-place version of "reverse()". - ``` - """ reverse! - - @doc doc""" - ```rst - combinations(array, n) - - Generate all combinations of "n" elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - "collect(combinations(array,n))" to get an array of all - combinations. - ``` - """ combinations - - @doc doc""" - ```rst - permutations(array) - - Generate all permutations of an indexable object. Because the - number of permutations can be very large, this function returns an - iterator object. Use "collect(permutations(array))" to get an - array of all permutations. - ``` - """ permutations - - @doc doc""" - ```rst - partitions(n) - - Generate all integer arrays that sum to "n". Because the number - of partitions can be very large, this function returns an iterator - object. Use "collect(partitions(n))" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using "length(partitions(n))". - ``` - """ partitions - - @doc doc""" - ```rst - partitions(n, m) - - Generate all arrays of "m" integers that sum to "n". Because - the number of partitions can be very large, this function returns - an iterator object. Use "collect(partitions(n,m))" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using "length(partitions(n,m))". - ``` - """ partitions - - @doc doc""" - ```rst - partitions(array) - - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - "collect(partitions(array))" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using "length(partitions(array))". - ``` - """ partitions - - @doc doc""" - ```rst - partitions(array, m) - - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use "collect(partitions(array,m))" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using "length(partitions(array,m))". - ``` - """ partitions - - @doc doc""" - ```rst - bitpack(A::AbstractArray{T, N}) -> BitArray - - Converts a numeric array to a packed boolean array - ``` - """ bitpack - - @doc doc""" - ```rst - bitunpack(B::BitArray{N}) -> Array{Bool,N} - - Converts a packed boolean array to an array of booleans - ``` - """ bitunpack - - @doc doc""" - ```rst - flipbits!(B::BitArray{N}) -> BitArray{N} - - Performs a bitwise not operation on B. See *~ operator*. - ``` - """ flipbits! - - @doc doc""" - ```rst - rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on "src" and put the result - into "dest". - ``` - """ rol! - - @doc doc""" - ```rst - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on B. - ``` - """ rol! - - @doc doc""" - ```rst - rol(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation. - ``` - """ rol - - @doc doc""" - ```rst - ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on "src" and put the result - into "dest". - ``` - """ ror! - - @doc doc""" - ```rst - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on B. - ``` - """ ror! - - @doc doc""" - ```rst - ror(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation. - ``` - """ ror - - @doc doc""" - ```rst - sparse(I, J, V[, m, n, combine]) - - Create a sparse matrix "S" of dimensions "m x n" such that - "S[I[k], J[k]] = V[k]". The "combine" function is used to - combine duplicates. If "m" and "n" are not specified, they are - set to "max(I)" and "max(J)" respectively. If the "combine" - function is not supplied, duplicates are added by default. - ``` - """ sparse - - @doc doc""" - ```rst - sparsevec(I, V[, m, combine]) - - Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] - = V[k]". Duplicates are combined using the "combine" function, - which defaults to "+" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. - ``` - """ sparsevec - - @doc doc""" - ```rst - sparsevec(D::Dict[, m]) - - Create a sparse matrix of size "m x 1" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. - ``` - """ sparsevec - - @doc doc""" - ```rst - issparse(S) - - Returns "true" if "S" is sparse, and "false" otherwise. - ``` - """ issparse - - @doc doc""" - ```rst - sparse(A) - - Convert an AbstractMatrix "A" into a sparse matrix. - ``` - """ sparse - - @doc doc""" - ```rst - sparsevec(A) - - Convert a dense vector "A" into a sparse matrix of size "m x - 1". In julia, sparse vectors are really just sparse matrices with - one column. - ``` - """ sparsevec - - @doc doc""" - ```rst - full(S) - - Convert a sparse matrix "S" into a dense matrix. - ``` - """ full - - @doc doc""" - ```rst - nnz(A) - - Returns the number of stored (filled) elements in a sparse matrix. - ``` - """ nnz - - @doc doc""" - ```rst - spzeros(m, n) - - Create a sparse matrix of size "m x n". This sparse matrix will - not contain any nonzero values. No storage will be allocated for - nonzero values during construction. - ``` - """ spzeros - - @doc doc""" - ```rst - spones(S) - - Create a sparse matrix with the same structure as that of "S", - but with every nonzero element having the value "1.0". - ``` - """ spones - - @doc doc""" - ```rst - speye(type, m[, n]) - - Create a sparse identity matrix of specified type of size "m x - m". In case "n" is supplied, create a sparse identity matrix of - size "m x n". - ``` - """ speye - - @doc doc""" - ```rst - spdiagm(B, d[, m, n]) - - Construct a sparse diagonal matrix. "B" is a tuple of vectors - containing the diagonals and "d" is a tuple containing the - positions of the diagonals. In the case the input contains only one - diagonaly, "B" can be a vector (instead of a tuple) and "d" can - be the diagonal position (instead of a tuple), defaulting to 0 - (diagonal). Optionally, "m" and "n" specify the size of the - resulting sparse matrix. - ``` - """ spdiagm - - @doc doc""" - ```rst - sprand([rng], m, n, p[, rfn]) - - Create a random "m" by "n" sparse matrix, in which the - probability of any element being nonzero is independently given by - "p" (and hence the mean density of nonzeros is also exactly - "p"). Nonzero values are sampled from the distribution specified - by "rfn". The uniform distribution is used in case "rfn" is not - specified. The optional "rng" argument specifies a random number - generator, see *Random Numbers*. - ``` - """ sprand - - @doc doc""" - ```rst - sprandn(m, n, p) - - Create a random "m" by "n" sparse matrix with the specified - (independent) probability "p" of any entry being nonzero, where - nonzero values are sampled from the normal distribution. - ``` - """ sprandn - - @doc doc""" - ```rst - sprandbool(m, n, p) - - Create a random "m" by "n" sparse boolean matrix with the - specified (independent) probability "p" of any entry being - "true". - ``` - """ sprandbool - - @doc doc""" - ```rst - etree(A[, post]) - - Compute the elimination tree of a symmetric sparse matrix "A" - from "triu(A)" and, optionally, its post-ordering permutation. - ``` - """ etree - - @doc doc""" - ```rst - symperm(A, p) - - Return the symmetric permutation of A, which is "A[p,p]". A - should be symmetric and sparse, where only the upper triangular - part of the matrix is stored. This algorithm ignores the lower - triangular part of the matrix. Only the upper triangular part of - the result is returned as well. - ``` - """ symperm - - @doc doc""" - ```rst - nonzeros(A) - - Return a vector of the structural nonzero values in sparse matrix - "A". This includes zeros that are explicitly stored in the sparse - matrix. The returned vector points directly to the internal nonzero - storage of "A", and any modifications to the returned vector will - mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". - ``` - """ nonzeros - - @doc doc""" - ```rst - rowvals(A) - - Return a vector of the row indices of "A", and any modifications - to the returned vector will mutate "A" as well. Given the - internal storage format of sparse matrices, providing access to how - the row indices are stored internally can be useful in conjuction - with iterating over structural nonzero values. See "nonzeros(A)" - and "nzrange(A, col)". - ``` - """ rowvals - - @doc doc""" - ```rst - nzrange(A, col) - - Return the range of indices to the structural nonzero values of a - sparse matrix column. In conjunction with "nonzeros(A)" and - "rowvals(A)", 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 - ``` - """ nzrange - - @doc doc""" - ```rst - exit([code]) - - Quit (or control-D at the prompt). The default exit code is zero, - indicating that the processes completed successfully. - ``` - """ exit - - @doc doc""" - ```rst - quit() - - Quit the program indicating that the processes completed - successfully. This function calls "exit(0)" (see "exit()"). - ``` - """ quit - - @doc doc""" - ```rst - atexit(f) - - Register a zero-argument function to be called at exit. - ``` - """ atexit - - @doc doc""" - ```rst - atreplinit(f) - - Register a one-argument function to be called before the REPL - interface is initialized in interactive sessions; this is useful to - customize the interface. The argument of "f" is the REPL object. - This function should be called from within the ".juliarc.jl" - initialization file. - ``` - """ atreplinit - - @doc doc""" - ```rst - isinteractive() -> Bool - - Determine whether Julia is running an interactive session. - ``` - """ isinteractive - - @doc doc""" - ```rst - whos([Module,] [pattern::Regex]) - - Print information about exported global variables in a module, - optionally restricted to those matching "pattern". - ``` - """ whos - - @doc doc""" - ```rst - edit(file::AbstractString[, line]) - - Edit a file optionally providing a line number to edit at. Returns - to the julia prompt when you quit the editor. - ``` - """ edit - - @doc doc""" - ```rst - edit(function[, types]) - - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. - ``` - """ edit - - @doc doc""" - ```rst - @edit() - - Evaluates the arguments to the function call, determines their - types, and calls the "edit" function on the resulting expression - ``` - """ @edit - - @doc doc""" - ```rst - less(file::AbstractString[, line]) - - Show a file using the default pager, optionally providing a - starting line number. Returns to the julia prompt when you quit the - pager. - ``` - """ less - - @doc doc""" - ```rst - less(function[, types]) - - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. - ``` - """ less - - @doc doc""" - ```rst - @less() - - Evaluates the arguments to the function call, determines their - types, and calls the "less" function on the resulting expression - ``` - """ @less - - @doc doc""" - ```rst - clipboard(x) - - Send a printed form of "x" to the operating system clipboard - ("copy"). - ``` - """ clipboard - - @doc doc""" - ```rst - clipboard() -> AbstractString - - Return a string with the contents of the operating system clipboard - ("paste"). - ``` - """ clipboard - - @doc doc""" - ```rst - require(file::AbstractString...) - - Load source files once, in the context of the "Main" module, on - every active node, searching standard locations for files. - "require" is considered a top-level operation, so it sets the - current "include" path but does not use it to search for files - (see help for "include"). This function is typically used to load - library code, and is implicitly called by "using" to load - packages. - - When searching for files, "require" first looks in the current - working directory, then looks for package code under "Pkg.dir()", - then tries paths in the global array "LOAD_PATH". - ``` - """ require - - @doc doc""" - ```rst - reload(file::AbstractString) - - Like "require", except forces loading of files regardless of - whether they have been loaded before. Typically used when - interactively developing libraries. - ``` - """ reload - - @doc doc""" - ```rst - include(path::AbstractString) - - Evaluate the contents of a source file in the current context. - During including, a task-local include path is set to the directory - containing the file. Nested calls to "include" will search - relative to that path. All paths refer to files on node 1 when - running in parallel, and files will be fetched from node 1. This - function is typically used to load source interactively, or to - combine files in packages that are broken into multiple source - files. - ``` - """ include - - @doc doc""" - ```rst - include_string(code::AbstractString) - - Like "include", except reads code from the given string rather - than from a file. Since there is no file path involved, no path - processing or fetching from node 1 is done. - ``` - """ include_string - - @doc doc""" - ```rst - which(f, types) - - Returns the method of "f" (a "Method" object) that would be - called for arguments of the given types. - - If "types" is an abstract type, then the method that would be - called by "invoke" is returned. - ``` - """ which - - @doc doc""" - ```rst - which(symbol) - - Return the module in which the binding for the variable referenced - by "symbol" was created. - ``` - """ which - - @doc doc""" - ```rst - @which() - - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the "Method" object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the "which" function. - ``` - """ @which - - @doc doc""" - ```rst - methods(f[, types]) - - Returns the method table for "f". - - If "types" is specified, returns an array of methods whose types - match. - ``` - """ methods - - @doc doc""" - ```rst - methodswith(typ[, module or function][, showparents]) - - Return an array of methods with an argument of type "typ". If - optional "showparents" is "true", also return arguments with a - parent type of "typ", excluding type "Any". - - The optional second argument restricts the search to a particular - module or function. - ``` - """ methodswith - - @doc doc""" - ```rst - @show() - - Show an expression and result, returning the result - ``` - """ @show - - @doc doc""" - ```rst - versioninfo([verbose::Bool]) - - Print information about the version of Julia in use. If the - "verbose" argument is true, detailed system information is shown - as well. - ``` - """ versioninfo - - @doc doc""" - ```rst - workspace() - - Replace the top-level module ("Main") with a new one, providing a - clean workspace. The previous "Main" module is made available as - "LastMain". A previously-loaded package can be accessed using a - statement such as "using LastMain.Package". - - This function should only be used interactively. - ``` - """ workspace - - @doc doc""" - ```rst - is(x, y) -> Bool -===(x, y) -> Bool -≡(x, y) -> Bool - - Determine whether "x" and "y" are identical, in the sense that - no program could distinguish them. Compares mutable objects by - address in memory, and compares immutable objects (such as numbers) - by contents at the bit level. This function is sometimes called - "egal". - ``` - """ is - - @doc doc""" - ```rst - isa(x, type) -> Bool - - Determine whether "x" is of the given "type". - ``` - """ isa - - @doc doc""" - ```rst - isequal(x, y) - - Similar to "==", except treats all floating-point "NaN" values - as equal to each other, and treats "-0.0" as unequal to "0.0". - The default implementation of "isequal" calls "==", so if you - have a type that doesn't have these floating-point subtleties then - you probably only need to define "==". - - "isequal" is the comparison function used by hash tables - ("Dict"). "isequal(x,y)" must imply that "hash(x) == - hash(y)". - - This typically means that if you define your own "==" function - then you must define a corresponding "hash" (and vice versa). - Collections typically implement "isequal" by calling "isequal" - recursively on all contents. - - Scalar types generally do not need to implement "isequal" - separate from "==", unless they represent floating-point numbers - amenable to a more efficient implementation than that provided as a - generic fallback (based on "isnan", "signbit", and "=="). - ``` - """ isequal - - @doc doc""" - ```rst - isless(x, y) - - Test whether "x" is less than "y", according to a canonical - total order. Values that are normally unordered, such as "NaN", - are ordered in an arbitrary but consistent fashion. This is the - default comparison used by "sort". Non-numeric types with a - canonical total order should implement this function. Numeric types - only need to implement it if they have special values such as - "NaN". - ``` - """ isless - - @doc doc""" - ```rst - ifelse(condition::Bool, x, y) - - Return "x" if "condition" is true, otherwise return "y". This - differs from "?" or "if" in that it is an ordinary function, so - all the arguments are evaluated first. In some cases, using - "ifelse" instead of an "if" statement can eliminate the branch - in generated code and provide higher performance in tight loops. - ``` - """ ifelse - - @doc doc""" - ```rst - lexcmp(x, y) - - Compare "x" and "y" lexicographically and return -1, 0, or 1 - depending on whether "x" is less than, equal to, or greater than - "y", respectively. This function should be defined for - lexicographically comparable types, and "lexless" will call - "lexcmp" by default. - ``` - """ lexcmp - - @doc doc""" - ```rst - lexless(x, y) - - Determine whether "x" is lexicographically less than "y". - ``` - """ lexless - - @doc doc""" - ```rst - typeof(x) - - Get the concrete type of "x". - ``` - """ typeof - - @doc doc""" - ```rst - tuple(xs...) - - Construct a tuple of the given objects. - ``` - """ tuple - - @doc doc""" - ```rst - ntuple(f::Function, n) - - Create a tuple of length "n", computing each element as "f(i)", - where "i" is the index of the element. - ``` - """ ntuple - - @doc doc""" - ```rst - object_id(x) - - Get a unique integer id for "x". "object_id(x)==object_id(y)" - if and only if "is(x,y)". - ``` - """ object_id - - @doc doc""" - ```rst - hash(x[, h]) - - Compute an integer hash code such that "isequal(x,y)" implies - "hash(x)==hash(y)". The optional second argument "h" is a hash - code to be mixed with the result. - - New types should implement the 2-argument form, typically by - calling the 2-argument "hash" method recursively in order to mix - hashes of the contents with each other (and with "h"). - Typically, any type that implements "hash" should also implement - its own "==" (hence "isequal") to guarantee the property - mentioned above. - ``` - """ hash - - @doc doc""" - ```rst - finalizer(x, function) - - Register a function "f(x)" to be called when there are no - program-accessible references to "x". The behavior of this - function is unpredictable if "x" is of a bits type. - ``` - """ finalizer - - @doc doc""" - ```rst - finalize(x) - - Immediately run finalizers registered for object "x". - ``` - """ finalize - - @doc doc""" - ```rst - copy(x) - - Create a shallow copy of "x": the outer structure is copied, but - not all internal values. For example, copying an array produces a - new array with identically-same elements as the original. - ``` - """ copy - - @doc doc""" - ```rst - deepcopy(x) - - Create a deep copy of "x": everything is copied recursively, - resulting in a fully independent object. For example, deep-copying - an array produces a new array whose elements are deep copies of the - original elements. Calling *deepcopy* on an object should generally - have the same effect as serializing and then deserializing it. - - As a special case, functions can only be actually deep-copied if - they are anonymous, otherwise they are just copied. The difference - is only relevant in the case of closures, i.e. functions which may - contain hidden internal references. - - While it isn't normally necessary, user-defined types can override - the default "deepcopy" behavior by defining a specialized version - of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" - (which shouldn't otherwise be used), where "T" is the type to be - specialized for, and "dict" keeps track of objects copied so far - within the recursion. Within the definition, "deepcopy_internal" - should be used in place of "deepcopy", and the "dict" variable - should be updated as appropriate before returning. - ``` - """ deepcopy - - @doc doc""" - ```rst - isdefined([object], index | symbol) - - Tests whether an assignable location is defined. The arguments can - be an array and index, a composite object and field name (as a - symbol), or a module and a symbol. With a single symbol argument, - tests whether a global variable with that name is defined in - "current_module()". - ``` - """ isdefined - - @doc doc""" - ```rst - convert(T, x) - - Convert "x" to a value of type "T". - - If "T" is an "Integer" type, an "InexactError" will be raised - if "x" is not representable by "T", for example if "x" is not - integer-valued, or is outside the range supported by "T". - - julia> convert(Int, 3.0) - 3 - - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 - - If "T" is a "FloatingPoint" or "Rational" type, then it will - return the closest value to "x" representable by "T". - - julia> x = 1/3 - 0.3333333333333333 - - julia> convert(Float32, x) - 0.33333334f0 - - julia> convert(Rational{Int32}, x) - 1//3 - - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 - ``` - """ convert - - @doc doc""" - ```rst - promote(xs...) - - Convert all arguments to their common promotion type (if any), and - return them all (as a tuple). - ``` - """ promote - - @doc doc""" - ```rst - oftype(x, y) - - Convert "y" to the type of "x" ("convert(typeof(x), y)"). - ``` - """ oftype - - @doc doc""" - ```rst - widen(type | x) - - If the argument is a type, return a "larger" type (for numeric - types, this will be a type with at least as much range and - precision as the argument, and usually more). Otherwise the - argument "x" is converted to "widen(typeof(x))". - - julia> widen(Int32) - Int64 - - julia> widen(1.5f0) - 1.5 - ``` - """ widen - - @doc doc""" - ```rst - identity(x) - - The identity function. Returns its argument. - ``` - """ identity - - @doc doc""" - ```rst - super(T::DataType) - - Return the supertype of DataType T - ``` - """ super - - @doc doc""" - ```rst - issubtype(type1, type2) - - True if and only if all values of "type1" are also of "type2". - Can also be written using the "<:" infix operator as "type1 <: - type2". - ``` - """ issubtype - - @doc doc""" - ```rst - <:(T1, T2) - - Subtype operator, equivalent to "issubtype(T1,T2)". - ``` - """ Base.(:(<:)) - - @doc doc""" - ```rst - subtypes(T::DataType) - - Return a list of immediate subtypes of DataType T. Note that all - currently loaded subtypes are included, including those not visible - in the current module. - ``` - """ subtypes - - @doc doc""" - ```rst - typemin(type) - - The lowest value representable by the given (real) numeric type. - ``` - """ typemin - - @doc doc""" - ```rst - typemax(type) - - The highest value representable by the given (real) numeric type. - ``` - """ typemax - - @doc doc""" - ```rst - realmin(type) - - The smallest in absolute value non-subnormal value representable by - the given floating-point type - ``` - """ realmin - - @doc doc""" - ```rst - realmax(type) - - The highest finite value representable by the given floating-point - type - ``` - """ realmax - - @doc doc""" - ```rst - maxintfloat(type) - - The largest integer losslessly representable by the given floating- - point type - ``` - """ maxintfloat - - @doc doc""" - ```rst - sizeof(type) - - Size, in bytes, of the canonical binary representation of the given - type, if any. - ``` - """ sizeof - - @doc doc""" - ```rst - eps([type]) - - The distance between 1.0 and the next larger representable - floating-point value of "type". Only floating-point types are - sensible arguments. If "type" is omitted, then "eps(Float64)" - is returned. - ``` - """ eps - - @doc doc""" - ```rst - eps(x) - - The distance between "x" and the next larger representable - floating-point value of the same type as "x". - ``` - """ eps - - @doc doc""" - ```rst - promote_type(type1, type2) - - Determine a type big enough to hold values of each argument type - without loss, whenever possible. In some cases, where no type - exists to which both types can be promoted losslessly, some loss is - tolerated; for example, "promote_type(Int64,Float64)" returns - "Float64" even though strictly, not all "Int64" values can be - represented exactly as "Float64" values. - ``` - """ promote_type - - @doc doc""" - ```rst - promote_rule(type1, type2) - - Specifies what type should be used by "promote" when given values - of types "type1" and "type2". This function should not be - called directly, but should have definitions added to it for new - types as appropriate. - ``` - """ promote_rule - - @doc doc""" - ```rst - getfield(value, name::Symbol) - - Extract a named field from a value of composite type. The syntax - "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls - "getfield(a, b)". - ``` - """ getfield - - @doc doc""" - ```rst - setfield!(value, name::Symbol, x) - - Assign "x" to a named field in "value" of composite type. The - syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax - "a.(b) = c" calls "setfield!(a, b, c)". - ``` - """ setfield! - - @doc doc""" - ```rst - fieldoffsets(type) - - The byte offset of each field of a type relative to the data start. - For example, we could use it in the following manner to summarize - information about a struct type: - - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; - - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) - ``` - """ fieldoffsets - - @doc doc""" - ```rst - fieldtype(type, name::Symbol | index::Int) - - Determine the declared type of a field (specified by name or index) - in a composite type. - ``` - """ fieldtype - - @doc doc""" - ```rst - isimmutable(v) - - True if value "v" is immutable. See *Immutable Composite Types* - for a discussion of immutability. Note that this function works on - values, so if you give it a type, it will tell you that a value of - "DataType" is mutable. - ``` - """ isimmutable - - @doc doc""" - ```rst - isbits(T) - - True if "T" is a "plain data" type, meaning it is immutable and - contains no references to other values. Typical examples are - numeric types such as "UInt8", "Float64", and - "Complex{Float64}". - - julia> isbits(Complex{Float64}) - true - - julia> isbits(Complex) - false - ``` - """ isbits - - @doc doc""" - ```rst - isleaftype(T) - - Determine whether "T" is a concrete type that can have instances, - meaning its only subtypes are itself and "None" (but "T" itself - is not "None"). - ``` - """ isleaftype - - @doc doc""" - ```rst - typejoin(T, S) - - Compute a type that contains both "T" and "S". - ``` - """ typejoin - - @doc doc""" - ```rst - typeintersect(T, S) - - Compute a type that contains the intersection of "T" and "S". - Usually this will be the smallest such type or one close to it. - ``` - """ typeintersect - - @doc doc""" - ```rst - instances(T::Type) - - Return a collection of all instances of the given type, if - applicable. Mostly used for enumerated types (see "@enum"). - ``` - """ instances - - @doc doc""" - ```rst - method_exists(f, Tuple type) -> Bool - - Determine whether the given generic function has a method matching - the given "Tuple" of argument types. - - julia> method_exists(length, Tuple{Array}) - true - ``` - """ method_exists - - @doc doc""" - ```rst - applicable(f, args...) -> Bool - - Determine whether the given generic function has a method - applicable to the given arguments. - - julia> function f(x, y) - x + y - end; - - julia> applicable(f, 1) - false - - julia> applicable(f, 1, 2) - true - ``` - """ applicable - - @doc doc""" - ```rst - invoke(f, (types...), args...) - - Invoke a method for the given generic function matching the - specified types (as a tuple), on the specified arguments. The - arguments must be compatible with the specified types. This allows - invoking a method other than the most specific matching method, - which is useful when the behavior of a more general definition is - explicitly needed (often as part of the implementation of a more - specific method of the same function). - ``` - """ invoke - - @doc doc""" - ```rst - |>(x, f) - - Applies a function to the preceding argument. This allows for easy - function chaining. - - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 - ``` - """ Base.(:(|>)) - - @doc doc""" - ```rst - call(x, args...) - - If "x" is not a "Function", then "x(args...)" is equivalent - to "call(x, args...)". This means that function-like behavior - can be added to any type by defining new "call" methods. - ``` - """ call - - @doc doc""" - ```rst - eval([m::Module], expr::Expr) - - Evaluate an expression in the given module and return the result. - Every module (except those defined with "baremodule") has its own - 1-argument definition of "eval", which evaluates expressions in - that module. - ``` - """ eval - - @doc doc""" - ```rst - @eval() - - Evaluate an expression and return the value. - ``` - """ @eval - - @doc doc""" - ```rst - evalfile(path::AbstractString) - - Load the file using "include", evaluate all expressions, and - return the value of the last one. - ``` - """ evalfile - - @doc doc""" - ```rst - esc(e::ANY) - - Only valid in the context of an Expr returned from a macro. - Prevents the macro hygiene pass from turning embedded variables - into gensym variables. See the *Macros* section of the - Metaprogramming chapter of the manual for more details and - examples. - ``` - """ esc - - @doc doc""" - ```rst - gensym([tag]) - - Generates a symbol which will not conflict with other variable - names. - ``` - """ gensym - - @doc doc""" - ```rst - @gensym() - - Generates a gensym symbol for a variable. For example, "@gensym x - y" is transformed into "x = gensym("x"); y = gensym("y")". - ``` - """ @gensym - - @doc doc""" - ```rst - parse(str, start; greedy=true, raise=true) - - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If "greedy" is true (default), - "parse" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return "Expr(:incomplete, "(error message)")". If "raise" is - true (default), syntax errors other than incomplete expressions - will raise an error. If "raise" is false, "parse" will return - an expression that will raise an error upon evaluation. - ``` - """ parse - - @doc doc""" - ```rst - parse(str; raise=true) - - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If "raise" is true (default), syntax errors will - raise an error; otherwise, "parse" will return an expression that - will raise an error upon evaluation. - ``` - """ parse - - @doc doc""" - ```rst - Nullable(x) - - Wrap value "x" in an object of type "Nullable", which indicates - whether a value is present. "Nullable(x)" yields a non-empty - wrapper, and "Nullable{T}()" yields an empty instance of a - wrapper that might contain a value of type "T". - ``` - """ Nullable - - @doc doc""" - ```rst - get(x) - - Attempt to access the value of the "Nullable" object, "x". - Returns the value if it is present; otherwise, throws a - "NullException". - ``` - """ get - - @doc doc""" - ```rst - get(x, y) - - Attempt to access the value of the "Nullable{T}" object, "x". - Returns the value if it is present; otherwise, returns "convert(T, - y)". - ``` - """ get - - @doc doc""" - ```rst - isnull(x) - - Is the "Nullable" object "x" null, i.e. missing a value? - ``` - """ isnull - - @doc doc""" - ```rst - run(command) - - Run a command object, constructed with backticks. Throws an error - if anything goes wrong, including the process exiting with a non- - zero status. - ``` - """ run - - @doc doc""" - ```rst - spawn(command) - - Run a command object asynchronously, returning the resulting - "Process" object. - ``` - """ spawn - - @doc doc""" - ```rst - DevNull - - Used in a stream redirect to discard all data written to it. - Essentially equivalent to /dev/null on Unix or NUL on Windows. - Usage: "run(`cat test.txt` |> DevNull)" - ``` - """ DevNull - - @doc doc""" - ```rst - success(command) - - Run a command object, constructed with backticks, and tell whether - it was successful (exited with a code of 0). An exception is raised - if the process cannot be started. - ``` - """ success - - @doc doc""" - ```rst - process_running(p::Process) - - Determine whether a process is currently running. - ``` - """ process_running - - @doc doc""" - ```rst - process_exited(p::Process) - - Determine whether a process has exited. - ``` - """ process_exited - - @doc doc""" - ```rst - kill(p::Process, signum=SIGTERM) - - Send a signal to a process. The default is to terminate the - process. - ``` - """ kill - - @doc doc""" - ```rst - open(command, mode::AbstractString="r", stdio=DevNull) - - Start running "command" asynchronously, and return a tuple - "(stream,process)". If "mode" is ""r"", then "stream" - reads from the process's standard output and "stdio" optionally - specifies the process's standard input stream. If "mode" is - ""w"", then "stream" writes to the process's standard input - and "stdio" optionally specifies the process's standard output - stream. - ``` - """ open - - @doc doc""" - ```rst - open(f::Function, command, mode::AbstractString="r", stdio=DevNull) - - Similar to "open(command, mode, stdio)", but calls "f(stream)" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - "f". - ``` - """ open - - @doc doc""" - ```rst - Sys.set_process_title(title::AbstractString) - - Set the process title. No-op on some operating systems. (not - exported) - ``` - """ Sys - - @doc doc""" - ```rst - Sys.get_process_title() - - Get the process title. On some systems, will always return empty - string. (not exported) - ``` - """ Sys - - @doc doc""" - ```rst - readandwrite(command) - - Starts running a command asynchronously, and returns a tuple - (stdout,stdin,process) of the output stream and input stream of the - process, and the process object itself. - ``` - """ readandwrite - - @doc doc""" - ```rst - ignorestatus(command) - - Mark a command object so that running it will not throw an error if - the result code is non-zero. - ``` - """ ignorestatus - - @doc doc""" - ```rst - detach(command) - - Mark a command object so that it will be run in a new process - group, allowing it to outlive the julia process, and not have - Ctrl-C interrupts passed to it. - ``` - """ detach - - @doc doc""" - ```rst - setenv(command, env; dir=working_dir) - - Set environment variables to use when running the given command. - "env" is either a dictionary mapping strings to strings, an array - of strings of the form ""var=val"", or zero or more - ""var"=>val" pair arguments. In order to modify (rather than - replace) the existing environment, create "env" by "copy(ENV)" - and then setting "env["var"]=val" as desired, or use - "withenv". - - The "dir" keyword argument can be used to specify a working - directory for the command. - ``` - """ setenv - - @doc doc""" - ```rst - withenv(f::Function, kv::Pair...) - - Execute "f()" in an environment that is temporarily modified (not - replaced as in "setenv") by zero or more ""var"=>val" - arguments "kv". "withenv" is generally used via the - "withenv(kv...) do ... end" syntax. A value of "nothing" can - be used to temporarily unset an environment variable (if it is - set). When "withenv" returns, the original environment has been - restored. - ``` - """ withenv - - @doc doc""" - ```rst - pipe(from, to, ...) - - Create a pipeline from a data source to a destination. The source - and destination can be commands, I/O streams, strings, or results - of other "pipe" calls. At least one argument must be a command. - Strings refer to filenames. When called with more than two - arguments, they are chained together from left to right. For - example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". - This provides a more concise way to specify multi-stage pipelines. - - **Examples**: - * "run(pipe(`ls`, `grep xyz`))" - - * "run(pipe(`ls`, "out.txt"))" - - * "run(pipe("out.txt", `grep xyz`))" - ``` - """ pipe - - @doc doc""" - ```rst - pipe(command; stdin, stdout, stderr, append=false) - - Redirect I/O to or from the given "command". Keyword arguments - specify which of the command's streams should be redirected. - "append" controls whether file output appends to the file. This - is a more general version of the 2-argument "pipe" function. - "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when - "from" is a command, and to "pipe(to, stdin=from)" when - "from" is another kind of data source. - - **Examples**: - * "run(pipe(`dothings`, stdout="out.txt", - stderr="errs.txt"))" - - * "run(pipe(`update`, stdout="log.txt", append=true))" - ``` - """ pipe - - @doc doc""" - ```rst - gethostname() -> AbstractString - - Get the local machine's host name. - ``` - """ gethostname - - @doc doc""" - ```rst - getipaddr() -> AbstractString - - Get the IP address of the local machine, as a string of the form - "x.x.x.x". - ``` - """ getipaddr - - @doc doc""" - ```rst - getpid() -> Int32 - - Get julia's process ID. - ``` - """ getpid - - @doc doc""" - ```rst - time() - - Get the system time in seconds since the epoch, with fairly high - (typically, microsecond) resolution. - ``` - """ time - - @doc doc""" - ```rst - time_ns() - - Get the time in nanoseconds. The time corresponding to 0 is - undefined, and wraps every 5.8 years. - ``` - """ time_ns - - @doc doc""" - ```rst - tic() - - Set a timer to be read by the next call to "toc()" or "toq()". - The macro call "@time expr" can also be used to time evaluation. - ``` - """ tic - - @doc doc""" - ```rst - toc() - - Print and return the time elapsed since the last "tic()". - ``` - """ toc - - @doc doc""" - ```rst - toq() - - Return, but do not print, the time elapsed since the last - "tic()". - ``` - """ toq - - @doc doc""" - ```rst - @time() - - A macro to execute an expression, printing the time it took to - execute, the number of allocations, and the total number of bytes - its execution caused to be allocated, before returning the value of - the expression. - ``` - """ @time - - @doc doc""" - ```rst - @timev() - - This is a verbose version of the "@time" macro, it first prints - the same information as "@time", then any non-zero memory - allocation counters, and then returns the value of the expression. - ``` - """ @timev - - @doc doc""" - ```rst - @timed() - - A macro to execute an expression, and return the value of the - expression, elapsed time, total bytes allocated, garbage collection - time, and an object with various memory allocation counters. - ``` - """ @timed - - @doc doc""" - ```rst - @elapsed() - - A macro to evaluate an expression, discarding the resulting value, - instead returning the number of seconds it took to execute as a - floating-point number. - ``` - """ @elapsed - - @doc doc""" - ```rst - @allocated() - - A macro to evaluate an expression, discarding the resulting value, - instead returning the total number of bytes allocated during - evaluation of the expression. Note: the expression is evaluated - inside a local function, instead of the current context, in order - to eliminate the effects of compilation, however, there still may - be some allocations due to JIT compilation. This also makes the - results inconsistent with the "@time" macros, which do not try to - adjust for the effects of compilation. - ``` - """ @allocated - - @doc doc""" - ```rst - EnvHash() -> EnvHash - - A singleton of this type provides a hash table interface to - environment variables. - ``` - """ EnvHash - - @doc doc""" - ```rst - ENV - - Reference to the singleton "EnvHash", providing a dictionary - interface to system environment variables. - ``` - """ ENV - - @doc doc""" - ```rst - @unix() - - Given "@unix? a : b", do "a" on Unix systems (including Linux - and OS X) and "b" elsewhere. See documentation for Handling - Platform Variations in the Calling C and Fortran Code section of - the manual. - ``` - """ @unix - - @doc doc""" - ```rst - @osx() - - Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. - ``` - """ @osx - - @doc doc""" - ```rst - @linux() - - Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. - ``` - """ @linux - - @doc doc""" - ```rst - @windows() - - Given "@windows? a : b", do "a" on Windows and "b" elsewhere. - See documentation for Handling Platform Variations in the Calling C - and Fortran Code section of the manual. - ``` - """ @windows - - @doc doc""" - ```rst - error(message::AbstractString) - - Raise an "ErrorException" with the given message - ``` - """ error - - @doc doc""" - ```rst - throw(e) - - Throw an object as an exception - ``` - """ throw - - @doc doc""" - ```rst - rethrow([e]) - - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - "catch" block). - ``` - """ rethrow - - @doc doc""" - ```rst - backtrace() - - Get a backtrace object for the current program point. - ``` - """ backtrace - - @doc doc""" - ```rst - catch_backtrace() - - Get the backtrace of the current exception, for use within - "catch" blocks. - ``` - """ catch_backtrace - - @doc doc""" - ```rst - assert(cond) - - Throw an "AssertionError" if "cond" is false. Also available as - the macro "@assert expr". - ``` - """ assert - - @doc doc""" - ```rst - ArgumentError(msg) - - The parameters to a function call do not match a valid signature. - ``` - """ ArgumentError - - @doc doc""" - ```rst - AssertionError([msg]) - - The asserted condition did not evalutate to "true". - ``` - """ AssertionError - - @doc doc""" - ```rst - BoundsError([a][, i]) - - An indexing operation into an array, "a", tried to access an out- - of-bounds element, "i". - ``` - """ BoundsError - - @doc doc""" - ```rst - DimensionMismatch([msg]) - - The objects called do not have matching dimensionality. - ``` - """ DimensionMismatch - - @doc doc""" - ```rst - DivideError() - - Integer division was attempted with a denominator value of 0. - ``` - """ DivideError - - @doc doc""" - ```rst - DomainError() - - The arguments to a function or constructor are outside the valid - domain. - ``` - """ DomainError - - @doc doc""" - ```rst - EOFError() - - No more data was available to read from a file or stream. - ``` - """ EOFError - - @doc doc""" - ```rst - ErrorException(msg) - - Generic error type. The error message, in the *.msg* field, may - provide more specific details. - ``` - """ ErrorException - - @doc doc""" - ```rst - InexactError() - - Type conversion cannot be done exactly. - ``` - """ InexactError - - @doc doc""" - ```rst - InterruptException() - - The process was stopped by a terminal interrupt (CTRL+C). - ``` - """ InterruptException - - @doc doc""" - ```rst - KeyError(key) - - An indexing operation into an "Associative" ("Dict") or "Set" - like object tried to access or delete a non-existent element. - ``` - """ KeyError - - @doc doc""" - ```rst - LoadError(file::AbstractString, line::Int, error) - - An error occurred while *including*, *requiring*, or *using* a - file. The error specifics should be available in the *.error* - field. - ``` - """ LoadError - - @doc doc""" - ```rst - MethodError(f, args) - - A method with the required type signature does not exist in the - given generic function. - ``` - """ MethodError - - @doc doc""" - ```rst - NullException() - - An attempted access to a "Nullable" with no defined value. - ``` - """ NullException - - @doc doc""" - ```rst - OutOfMemoryError() - - An operation allocated too much memory for either the system or the - garbage collector to handle properly. - ``` - """ OutOfMemoryError - - @doc doc""" - ```rst - ReadOnlyMemoryError() - - An operation tried to write to memory that is read-only. - ``` - """ ReadOnlyMemoryError - - @doc doc""" - ```rst - OverflowError() - - The result of an expression is too large for the specified type and - will cause a wraparound. - ``` - """ OverflowError - - @doc doc""" - ```rst - ParseError(msg) - - The expression passed to the *parse* function could not be - interpreted as a valid Julia expression. - ``` - """ ParseError - - @doc doc""" - ```rst - ProcessExitedException() - - After a client Julia process has exited, further attempts to - reference the dead child will throw this exception. - ``` - """ ProcessExitedException - - @doc doc""" - ```rst - StackOverflowError() - - The function call grew beyond the size of the call stack. This - usually happens when a call recurses infinitely. - ``` - """ StackOverflowError - - @doc doc""" - ```rst - SystemError(prefix::AbstractString[, errnum::Int32]) - - A system call failed with an error code (in the "errno" global - variable). - ``` - """ SystemError - - @doc doc""" - ```rst - TypeError(func::Symbol, context::AbstractString, expected::Type, got) - - A type assertion failure, or calling an intrinsic function with an - incorrect argument type. - ``` - """ TypeError - - @doc doc""" - ```rst - UndefRefError() - - The item or field is not defined for the given object. - ``` - """ UndefRefError - - @doc doc""" - ```rst - UndefVarError(var::Symbol) - - A symbol in the current scope is not defined. - ``` - """ UndefVarError - - @doc doc""" - ```rst - Timer(callback::Function, delay, repeat=0) - - Create a timer to call the given callback function. The callback is - passed one argument, the timer object itself. The callback will be - invoked after the specified initial delay, and then repeating with - the given "repeat" interval. If "repeat" is "0", the timer is - only triggered once. Times are in seconds. A timer is stopped and - has its resources freed by calling "close" on it. - ``` - """ Timer - - @doc doc""" - ```rst - Timer(delay, repeat=0) - - Create a timer that wakes up tasks waiting for it (by calling - "wait" on the timer object) at a specified interval. - ``` - """ Timer - - @doc doc""" - ```rst - module_name(m::Module) -> Symbol - - Get the name of a module as a symbol. - ``` - """ module_name - - @doc doc""" - ```rst - module_parent(m::Module) -> Module - - Get a module's enclosing module. "Main" is its own parent. - ``` - """ module_parent - - @doc doc""" - ```rst - current_module() -> Module - - Get the *dynamically* current module, which is the module code is - currently being read from. In general, this is not the same as the - module containing the call to this function. - ``` - """ current_module - - @doc doc""" - ```rst - fullname(m::Module) - - Get the fully-qualified name of a module as a tuple of symbols. For - example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and - "fullname(Main)" gives "()". - ``` - """ fullname - - @doc doc""" - ```rst - names(x::Module[, all=false[, imported=false]]) - - Get an array of the names exported by a module, with optionally - more module globals according to the additional parameters. - ``` - """ names - - @doc doc""" - ```rst - nfields(x::DataType) -> Int - - Get the number of fields of a data type. - ``` - """ nfields - - @doc doc""" - ```rst - fieldnames(x::DataType) - - Get an array of the fields of a data type. - ``` - """ fieldnames - - @doc doc""" - ```rst - isconst([m::Module], s::Symbol) -> Bool - - Determine whether a global is declared "const" in a given module. - The default module argument is "current_module()". - ``` - """ isconst - - @doc doc""" - ```rst - isgeneric(f::Function) -> Bool - - Determine whether a function is generic. - ``` - """ isgeneric - - @doc doc""" - ```rst - function_name(f::Function) -> Symbol - - Get the name of a generic function as a symbol, or ":anonymous". - ``` - """ function_name - - @doc doc""" - ```rst - function_module(f::Function, types) -> Module - - Determine the module containing a given definition of a generic - function. - ``` - """ function_module - - @doc doc""" - ```rst - functionloc(f::Function, types) - - Returns a tuple "(filename,line)" giving the location of a method - definition. - ``` - """ functionloc - - @doc doc""" - ```rst - functionloc(m::Method) - - Returns a tuple "(filename,line)" giving the location of a method - definition. - ``` - """ functionloc - - @doc doc""" - ```rst - gc() - - Perform garbage collection. This should not generally be used. - ``` - """ gc - - @doc doc""" - ```rst - gc_enable(on::Bool) - - Control whether garbage collection is enabled using a boolean - argument (true for enabled, false for disabled). Returns previous - GC state. Disabling garbage collection should be used only with - extreme caution, as it can cause memory use to grow without bound. - ``` - """ gc_enable - - @doc doc""" - ```rst - macroexpand(x) - - Takes the expression x and returns an equivalent expression with - all macros removed (expanded). - ``` - """ macroexpand - - @doc doc""" - ```rst - expand(x) - - Takes the expression x and returns an equivalent expression in - lowered form - ``` - """ expand - - @doc doc""" - ```rst - code_lowered(f, types) - - Returns an array of lowered ASTs for the methods matching the given - generic function and type signature. - ``` - """ code_lowered - - @doc doc""" - ```rst - @code_lowered() - - Evaluates the arguments to the function call, determines their - types, and calls "code_lowered()" on the resulting expression - ``` - """ @code_lowered - - @doc doc""" - ```rst - code_typed(f, types; optimize=true) - - Returns an array of lowered and type-inferred ASTs for the methods - matching the given generic function and type signature. The keyword - argument "optimize" controls whether additional optimizations, - such as inlining, are also applied. - ``` - """ code_typed - - @doc doc""" - ```rst - @code_typed() - - Evaluates the arguments to the function call, determines their - types, and calls "code_typed()" on the resulting expression - ``` - """ @code_typed - - @doc doc""" - ```rst - code_warntype(f, types) - - Displays lowered and type-inferred ASTs for the methods matching - the given generic function and type signature. The ASTs are - annotated in such a way as to cause "non-leaf" types to be - emphasized (if color is available, displayed in red). This serves - as a warning of potential type instability. Not all non-leaf types - are particularly problematic for performance, so the results need - to be used judiciously. See *@code_warntype* for more information. - ``` - """ code_warntype - - @doc doc""" - ```rst - @code_warntype() - - Evaluates the arguments to the function call, determines their - types, and calls "code_warntype()" on the resulting expression - ``` - """ @code_warntype - - @doc doc""" - ```rst - code_llvm(f, types) - - Prints the LLVM bitcodes generated for running the method matching - the given generic function and type signature to "STDOUT". - - All metadata and dbg.* calls are removed from the printed bitcode. - Use code_llvm_raw for the full IR. - ``` - """ code_llvm - - @doc doc""" - ```rst - @code_llvm() - - Evaluates the arguments to the function call, determines their - types, and calls "code_llvm()" on the resulting expression - ``` - """ @code_llvm - - @doc doc""" - ```rst - code_native(f, types) - - Prints the native assembly instructions generated for running the - method matching the given generic function and type signature to - STDOUT. - ``` - """ code_native - - @doc doc""" - ```rst - @code_native() - - Evaluates the arguments to the function call, determines their - types, and calls "code_native()" on the resulting expression - ``` - """ @code_native - - @doc doc""" - ```rst - precompile(f, args::Tuple{Vararg{Any}}) - - Compile the given function "f" for the argument tuple (of types) - "args", but do not execute it. - ``` - """ precompile - - @doc doc""" - ```rst - ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - - Call function in C-exported shared library, specified by - "(function name, library)" tuple, where each component is an - AbstractString or :Symbol. - - Note that the argument type tuple must be a literal tuple, and not - a tuple-valued variable or expression. Alternatively, ccall may - also be used to call a function pointer, such as one returned by - dlsym. - - Each "ArgumentValue" to the "ccall" will be converted to the - corresponding "ArgumentType", by automatic insertion of calls to - "unsafe_convert(ArgumentType, cconvert(ArgumentType, - ArgumentValue))". (see also the documentation for each of these - functions for further details). In most cases, this simply results - in a call to "convert(ArgumentType, ArgumentValue)" - ``` - """ Base.ccall - - @doc doc""" - ```rst - cglobal((symbol, library)[, type=Void]) - - Obtain a pointer to a global variable in a C-exported shared - library, specified exactly as in "ccall". Returns a - "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is - supplied. The values can be read or written by "unsafe_load" or - "unsafe_store!", respectively. - ``` - """ cglobal - - @doc doc""" - ```rst - cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - - Generate C-callable function pointer from Julia function. Type - annotation of the return value in the callback function is a must - for situations where Julia cannot infer the return type - automatically. - - For example: - - function foo() - # body - - retval::Float64 - end - - bar = cfunction(foo, Float64, ()) - ``` - """ cfunction - - @doc doc""" - ```rst - unsafe_convert(T, x) - - Convert "x" to a value of type "T" - - In cases where "convert" would need to take a Julia object and - turn it into a "Ptr", this function should be used to define and - perform that conversion. - - Be careful to ensure that a julia reference to "x" exists as long - as the result of this function will be used. Accordingly, the - argument "x" to this function should never be an expression, only - a variable name or field reference. For example, "x=a.b.c" is - acceptable, but "x=[a,b,c]" is not. - - The "unsafe" prefix on this function indicates that using the - result of this function after the "x" argument to this function - is no longer accessible to the program may cause undefined - behavior, including program corruption or segfaults, at any later - time. - ``` - """ unsafe_convert - - @doc doc""" - ```rst - cconvert(T, x) - - Convert "x" to a value of type "T", typically by calling - "convert(T,x)" - - In cases where "x" cannot be safely converted to "T", unlike - "convert", "cconvert" may return an object of a type different - from "T", which however is suitable for "unsafe_convert" to - handle. - - Neither "convert" nor "cconvert" should take a Julia object and - turn it into a "Ptr". - ``` - """ cconvert - - @doc doc""" - ```rst - unsafe_load(p::Ptr{T}, i::Integer) - - Load a value of type "T" from the address of the ith element - (1-indexed) starting at "p". This is equivalent to the C - expression "p[i-1]". - - The "unsafe" prefix on this function indicates that no validation - is performed on the pointer "p" to ensure that it is valid. - Incorrect usage may segfault your program or return garbage - answers, in the same manner as C. - ``` - """ unsafe_load - - @doc doc""" - ```rst - unsafe_store!(p::Ptr{T}, x, i::Integer) - - Store a value of type "T" to the address of the ith element - (1-indexed) starting at "p". This is equivalent to the C - expression "p[i-1] = x". - - The "unsafe" prefix on this function indicates that no validation - is performed on the pointer "p" to ensure that it is valid. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - ``` - """ unsafe_store! - - @doc doc""" - ```rst - unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - - Copy "N" elements from a source pointer to a destination, with no - checking. The size of an element is determined by the type of the - pointers. - - The "unsafe" prefix on this function indicates that no validation - is performed on the pointers "dest" and "src" to ensure that - they are valid. Incorrect usage may corrupt or segfault your - program, in the same manner as C. - ``` - """ unsafe_copy! - - @doc doc""" - ```rst - unsafe_copy!(dest::Array, do, src::Array, so, N) - - Copy "N" elements from a source array to a destination, starting - at offset "so" in the source and "do" in the destination - (1-indexed). - - The "unsafe" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - ``` - """ unsafe_copy! - - @doc doc""" - ```rst - copy!(dest, src) - - Copy all elements from collection "src" to array "dest". - Returns "dest". - ``` - """ copy! - - @doc doc""" - ```rst - copy!(dest, do, src, so, N) - - Copy "N" elements from collection "src" starting at offset - "so", to array "dest" starting at offset "do". Returns - "dest". - ``` - """ copy! - - @doc doc""" - ```rst - pointer(array[, index]) - - Get the native address of an array or string element. Be careful to - ensure that a julia reference to "a" exists as long as this - pointer will be used. This function is "unsafe" like - "unsafe_convert". - - Calling "Ref(array[, index])" is generally preferable to this - function. - ``` - """ pointer - - @doc doc""" - ```rst - pointer_to_array(pointer, dims[, take_ownership::Bool]) - - Wrap a native pointer as a Julia Array object. The pointer element - type determines the array element type. "own" optionally - specifies whether Julia should take ownership of the memory, - calling "free" on the pointer when the array is no longer - referenced. - ``` - """ pointer_to_array - - @doc doc""" - ```rst - pointer_from_objref(object_instance) - - Get the memory address of a Julia object as a "Ptr". The - existence of the resulting "Ptr" will not protect the object from - garbage collection, so you must ensure that the object remains - referenced for the whole time that the "Ptr" will be used. - ``` - """ pointer_from_objref - - @doc doc""" - ```rst - unsafe_pointer_to_objref(p::Ptr) - - Convert a "Ptr" to an object reference. Assumes the pointer - refers to a valid heap-allocated Julia object. If this is not the - case, undefined behavior results, hence this function is considered - "unsafe" and should be used with care. - ``` - """ unsafe_pointer_to_objref - - @doc doc""" - ```rst - disable_sigint(f::Function) - - Disable Ctrl-C handler during execution of a function, for calling - external code that is not interrupt safe. Intended to be called - using "do" block syntax as follows: - - disable_sigint() do - # interrupt-unsafe code - ... - end - ``` - """ disable_sigint - - @doc doc""" - ```rst - reenable_sigint(f::Function) - - Re-enable Ctrl-C handler during execution of a function. - Temporarily reverses the effect of "disable_sigint". - ``` - """ reenable_sigint - - @doc doc""" - ```rst - systemerror(sysfunc, iftrue) - - Raises a "SystemError" for "errno" with the descriptive string - "sysfunc" if "bool" is true - ``` - """ systemerror - - @doc doc""" - ```rst - Cchar - - Equivalent to the native "char" c-type - ``` - """ Cchar - - @doc doc""" - ```rst - Cuchar - - Equivalent to the native "unsigned char" c-type (UInt8) - ``` - """ Cuchar - - @doc doc""" - ```rst - Cshort - - Equivalent to the native "signed short" c-type (Int16) - ``` - """ Cshort - - @doc doc""" - ```rst - Cushort - - Equivalent to the native "unsigned short" c-type (UInt16) - ``` - """ Cushort - - @doc doc""" - ```rst - Cint - - Equivalent to the native "signed int" c-type (Int32) - ``` - """ Cint - - @doc doc""" - ```rst - Cuint - - Equivalent to the native "unsigned int" c-type (UInt32) - ``` - """ Cuint - - @doc doc""" - ```rst - Clong - - Equivalent to the native "signed long" c-type - ``` - """ Clong - - @doc doc""" - ```rst - Culong - - Equivalent to the native "unsigned long" c-type - ``` - """ Culong - - @doc doc""" - ```rst - Clonglong - - Equivalent to the native "signed long long" c-type (Int64) - ``` - """ Clonglong - - @doc doc""" - ```rst - Culonglong - - Equivalent to the native "unsigned long long" c-type (UInt64) - ``` - """ Culonglong - - @doc doc""" - ```rst - Cintmax_t - - Equivalent to the native "intmax_t" c-type (Int64) - ``` - """ Cintmax_t - - @doc doc""" - ```rst - Cuintmax_t - - Equivalent to the native "uintmax_t" c-type (UInt64) - ``` - """ Cuintmax_t - - @doc doc""" - ```rst - Csize_t +doc""" + ndims(A) -> Integer + +Returns the number of dimensions of A +""" +ndims + +doc""" + size(A[, 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.: +""" +size + +doc""" + iseltype(A, T) + +Tests whether A or its elements are of type T +""" +iseltype + +doc""" + length(A) -> Integer + +Returns the number of elements in A +""" +length + +doc""" + 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 (like `Array`), this is +simply the range `1:length(A)`. For other array types, this +returns a specialized Cartesian range to efficiently index into the +array with indices specified for every dimension. Example for a +sparse 2-d array: +""" +eachindex + +doc""" + Base.linearindexing(A) + +accesses its elements. If `Base.linearindexing(A)` returns +one index is an efficient operation. If it instead returns +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 +traits-based 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 define `linearindexing` in the +type-domain: +""" +Base + +doc""" + countnz(A) + +Counts the number of nonzero values in array A (dense or sparse). +Note that this is not a constant-time operation. For sparse +matrices, one should usually use `nnz`, which returns the number +of stored values. +""" +countnz + +doc""" + conj!(A) + +Convert an array to its complex conjugate in-place +""" +conj! + +doc""" + stride(A, k) + +Returns the distance in memory (in number of elements) between +adjacent elements in dimension k +""" +stride + +doc""" + strides(A) + +Returns a tuple of the memory strides in each dimension +""" +strides + +doc""" + ind2sub(dims, index) -> subscripts + +Returns a tuple of subscripts into an array with dimensions +the indices of the maximum element +""" +ind2sub + +doc""" + ind2sub(a, index) -> subscripts + +Returns a tuple of subscripts into array `a` corresponding to the +linear index `index` +""" +ind2sub + +doc""" + sub2ind(dims, i, j, k...) -> index + +The inverse of `ind2sub`, returns the linear index corresponding +to the provided subscripts +""" +sub2ind + +doc""" + Array(dims) + +element type `T`. `dims` may be a tuple or a series of integer +arguments. The syntax `Array(T, dims)` is also available, but +deprecated. +""" +Array + +doc""" + getindex(type[, elements...]) + +Construct a 1-d array of the specified type. This is usually called +with the syntax `Type[]`. Element values can be specified using +""" +getindex + +doc""" + cell(dims) + +Construct an uninitialized cell array (heterogeneous array). +""" +cell + +doc""" + zeros(type, dims) + +Create an array of all zeros of specified type. The type defaults +to Float64 if not specified. +""" +zeros + +doc""" + zeros(A) + +Create an array of all zeros with the same element type and shape +as A. +""" +zeros + +doc""" + ones(type, dims) + +Create an array of all ones of specified type. The type defaults to +Float64 if not specified. +""" +ones + +doc""" + ones(A) + +Create an array of all ones with the same element type and shape as +A. +""" +ones + +doc""" + trues(dims) + +Create a `BitArray` with all values set to true +""" +trues + +doc""" + falses(dims) + +Create a `BitArray` with all values set to false +""" +falses + +doc""" + fill(x, dims) + +Create an array filled with the value `x`. For example, +element initialized to 1.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 evaluating `Foo()` once. +""" +fill + +doc""" + fill!(A, x) + +Fill array `A` with the value `x`. If `x` is an object +reference, all elements will refer to the same object. `fill!(A, +Foo())` will return `A` filled with the result of evaluating +""" +fill! + +doc""" + reshape(A, dims) + +Create an array with the same data as the given array, but with +different dimensions. An implementation for a particular type of +array may choose whether the data is copied or shared. +""" +reshape + +doc""" + similar(array, element_type, dims) + +Create an uninitialized array of the same type as the given array, +but with the specified element type and dimensions. The second and +third arguments are both optional. The `dims` argument may be a +tuple or a series of integer arguments. For some special +ranges), this function returns a standard `Array` to allow +operating on elements. +""" +similar + +doc""" + reinterpret(type, A) + +Change the type-interpretation of a block of memory. For example, +corresponding to `UInt32(7)` as a `Float32`. For arrays, this +constructs an array with the same binary data as the given array, +but with the specified element type. +""" +reinterpret + +doc""" + eye(n) + +n-by-n identity matrix +""" +eye + +doc""" + eye(m, n) + +m-by-n identity matrix +""" +eye + +doc""" + eye(A) + +Constructs an identity matrix of the same dimensions and type as +""" +eye + +doc""" + linspace(start, stop, n=100) + +Construct a range of `n` linearly spaced elements from `start` +to `stop`. +""" +linspace + +doc""" + logspace(start, stop, n=50) + +Construct a vector of `n` logarithmically spaced numbers from +""" +logspace + +doc""" + broadcast(f, As...) + +Broadcasts the arrays `As` to a common size by expanding +singleton dimensions, and returns an array of the results +""" +broadcast + +doc""" + broadcast!(f, dest, As...) + +Like `broadcast`, but store the result of `broadcast(f, As...)` +in the `dest` array. Note that `dest` is only used to store the +result, and does not supply arguments to `f` unless it is also +listed in the `As`, as in `broadcast!(f, A, A, B)` to perform +""" +broadcast! + +doc""" + bitbroadcast(f, As...) + +Like `broadcast`, but allocates a `BitArray` to store the +result, rather then an `Array`. +""" +bitbroadcast + +doc""" + broadcast_function(f) + +Returns a function `broadcast_f` such that +useful in the form `const broadcast_f = broadcast_function(f)`. +""" +broadcast_function + +doc""" + broadcast!_function(f) + +Like `broadcast_function`, but for `broadcast!`. +""" +broadcast!_function + +doc""" + getindex(A, inds...) + +Returns a subset of array `A` as specified by `inds`, where +each `ind` may be an `Int`, a `Range`, or a `Vector`. See +the manual section on *array indexing* for details. +""" +getindex + +doc""" + sub(A, inds...) + +Like `getindex()`, but returns a view into the parent array `A` +with the given indices instead of making a copy. Calling +computes the indices to the parent array on the fly without +checking bounds. +""" +sub + +doc""" + parent(A) + +Returns the `parent array` of an array view type (e.g., +SubArray), or the array itself if it is not a view +""" +parent + +doc""" + parentindexes(A) + +From an array view `A`, returns the corresponding indexes in the +parent +""" +parentindexes + +doc""" + slicedim(A, d, i) + +Return all the data of `A` where the index for dimension `d` +equals `i`. Equivalent to `A[:,:,...,i,:,:,...]` where `i` is +in position `d`. +""" +slicedim + +doc""" + slice(A, inds...) + +Returns a view of array `A` with the given indices like +""" +slice + +doc""" + setindex!(A, X, inds...) + +Store values from array `X` within some subset of `A` as +specified by `inds`. +""" +setindex! + +doc""" + broadcast_getindex(A, inds...) + +Broadcasts the `inds` arrays to a common size like `broadcast`, +and returns an array of the results `A[ks...]`, where `ks` goes +over the positions in the broadcast. +""" +broadcast_getindex + +doc""" + broadcast_setindex!(A, X, inds...) + +Broadcasts the `X` and `inds` arrays to a common size and +stores the value from each position in `X` at the indices given +by the same positions in `inds`. +""" +broadcast_setindex! + +doc""" + cat(dims, A...) + +Concatenate the input arrays along the specified dimensions in the +iterable `dims`. For dimensions not in `dims`, all input arrays +should have the same size, which will also be the size of the +output array along that dimension. For dimensions in `dims`, the +size of the output array is the sum of the sizes of the input +arrays along that dimension. If `dims` is a single number, the +different arrays are tightly stacked along that dimension. If +to construct block diagonal matrices and their higher-dimensional +analogues by simultaneously increasing several dimensions for every +new input array and putting zero blocks elsewhere. For example, +block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal +blocks and matching zero blocks away from the diagonal. +""" +cat + +doc""" + vcat(A...) + +Concatenate along dimension 1 +""" +vcat + +doc""" + hcat(A...) + +Concatenate along dimension 2 +""" +hcat + +doc""" + 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. For example, +If the first argument is a single integer `n`, then all block +rows are assumed to have `n` block columns. +""" +hvcat + +doc""" + flipdim(A, d) + +Reverse `A` in dimension `d`. +""" +flipdim + +doc""" + circshift(A, shifts) + +Circularly shift the data in an array. The second argument is a +vector giving the amount to shift in each dimension. +""" +circshift - Equivalent to the native "size_t" c-type (UInt) - ``` - """ Csize_t +doc""" + find(A) + +Return a vector of the linear indexes of the non-zeros in `A` +boolean array to an array of indexes of the `true` elements. +""" +find - @doc doc""" - ```rst - Cssize_t - - Equivalent to the native "ssize_t" c-type - ``` - """ Cssize_t - - @doc doc""" - ```rst - Cptrdiff_t - - Equivalent to the native "ptrdiff_t" c-type (Int) - ``` - """ Cptrdiff_t - - @doc doc""" - ```rst - Coff_t - - Equivalent to the native "off_t" c-type - ``` - """ Coff_t - - @doc doc""" - ```rst - Cwchar_t - - Equivalent to the native "wchar_t" c-type (Int32) - ``` - """ Cwchar_t - - @doc doc""" - ```rst - Cfloat - - Equivalent to the native "float" c-type (Float32) - ``` - """ Cfloat - - @doc doc""" - ```rst - Cdouble - - Equivalent to the native "double" c-type (Float64) - ``` - """ Cdouble - - @doc doc""" - ```rst - start(iter) -> state - - Get initial iteration state for an iterable object - ``` - """ start - - @doc doc""" - ```rst - done(iter, state) -> Bool - - Test whether we are done iterating - ``` - """ done - - @doc doc""" - ```rst - next(iter, state) -> item, state - - For a given iterable object and iteration state, return the current - item and the next iteration state - ``` - """ next - - @doc doc""" - ```rst - zip(iters...) - - For a set of iterable objects, returns an iterable of tuples, where - the "i"th tuple contains the "i"th component of each input - iterable. - - Note that "zip()" is its own inverse: - "collect(zip(zip(a...)...)) == collect(a)". - ``` - """ zip - - @doc doc""" - ```rst - enumerate(iter) - - An iterator that yields "(i, x)" where "i" is an index starting - at 1, and "x" is the "i"th value from the given iterator. It's - useful when you need not only the values "x" over which you are - iterating, but also the index "i" of the iterations. - - julia> a = ["a", "b", "c"]; - - julia> for (index, value) in enumerate(a) - println("\$index \$value") - end - 1 a - 2 b - 3 c - ``` - """ enumerate - - @doc doc""" - ```rst - rest(iter, state) - - An iterator that yields the same elements as "iter", but starting - at the given "state". - ``` - """ rest - - @doc doc""" - ```rst - countfrom(start=1, step=1) - - An iterator that counts forever, starting at "start" and - incrementing by "step". - ``` - """ countfrom - - @doc doc""" - ```rst - take(iter, n) - - An iterator that generates at most the first "n" elements of - "iter". - ``` - """ take - - @doc doc""" - ```rst - drop(iter, n) - - An iterator that generates all but the first "n" elements of - "iter". - ``` - """ drop - - @doc doc""" - ```rst - cycle(iter) - - An iterator that cycles through "iter" forever. - ``` - """ cycle - - @doc doc""" - ```rst - repeated(x[, n::Int]) - - An iterator that generates the value "x" forever. If "n" is - specified, generates "x" that many times (equivalent to - "take(repeated(x), n)"). - ``` - """ repeated - - @doc doc""" - ```rst - isempty(collection) -> Bool - - Determine whether a collection is empty (has no elements). - - julia> isempty([]) - true - - julia> isempty([1 2 3]) - false - ``` - """ isempty - - @doc doc""" - ```rst - empty!(collection) -> collection - - Remove all elements from a "collection". - ``` - """ empty! - - @doc doc""" - ```rst - length(collection) -> Integer - - For ordered, indexable collections, the maximum index "i" for - which "getindex(collection, i)" is valid. For unordered - collections, the number of elements. - ``` - """ length - - @doc doc""" - ```rst - endof(collection) -> Integer - - Returns the last index of the collection. - - julia> endof([1,2,4]) - 3 - ``` - """ endof - - @doc doc""" - ```rst - 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)". - ``` - """ Base.in - - @doc doc""" - ```rst - 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 "(key,value)" tuple type. 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. - ``` - """ eltype - - @doc doc""" - ```rst - 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". - ``` - """ indexin - - @doc doc""" - ```rst - findin(a, b) - - Returns the indices of elements in collection "a" that appear in - collection "b" - ``` - """ findin - - @doc doc""" - ```rst - 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". - ``` - """ unique - - @doc doc""" - ```rst - 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. - ``` - """ reduce - - @doc doc""" - ```rst - 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". - ``` - """ reduce - - @doc doc""" - ```rst - foldl(op, v0, itr) - - Like "reduce()", but with guaranteed left associativity. "v0" - will be used exactly once. - ``` - """ foldl - - @doc doc""" - ```rst - 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)"). - ``` - """ foldl - - @doc doc""" - ```rst - foldr(op, v0, itr) - - Like "reduce()", but with guaranteed right associativity. "v0" - will be used exactly once. - ``` - """ foldr - - @doc doc""" - ```rst - 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)"). - ``` - """ foldr - - @doc doc""" - ```rst - maximum(itr) - - Returns the largest element in a collection. - ``` - """ maximum - - @doc doc""" - ```rst - maximum(A, dims) - - Compute the maximum value of an array over the given dimensions. - ``` - """ maximum - - @doc doc""" - ```rst - maximum!(r, A) - - Compute the maximum value of "A" over the singleton dimensions of - "r", and write results to "r". - ``` - """ maximum! - - @doc doc""" - ```rst - minimum(itr) - - Returns the smallest element in a collection. - ``` - """ minimum - - @doc doc""" - ```rst - minimum(A, dims) - - Compute the minimum value of an array over the given dimensions. - ``` - """ minimum - - @doc doc""" - ```rst - minimum!(r, A) - - Compute the minimum value of "A" over the singleton dimensions of - "r", and write results to "r". - ``` - """ minimum! - - @doc doc""" - ```rst - extrema(itr) - - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. - ``` - """ extrema - - @doc doc""" - ```rst - indmax(itr) -> Integer - - Returns the index of the maximum element in a collection. - ``` - """ indmax - - @doc doc""" - ```rst - indmin(itr) -> Integer - - Returns the index of the minimum element in a collection. - ``` - """ indmin - - @doc doc""" - ```rst - findmax(itr) -> (x, index) - - Returns the maximum element and its index. - ``` - """ findmax - - @doc doc""" - ```rst - findmax(A, dims) -> (maxval, index) - - For an array input, returns the value and index of the maximum over - the given dimensions. - ``` - """ findmax - - @doc doc""" - ```rst - findmin(itr) -> (x, index) - - Returns the minimum element and its index. - ``` - """ findmin - - @doc doc""" - ```rst - findmin(A, dims) -> (minval, index) - - For an array input, returns the value and index of the minimum over - the given dimensions. - ``` - """ findmin - - @doc doc""" - ```rst - maxabs(itr) - - Compute the maximum absolute value of a collection of values. - ``` - """ maxabs - - @doc doc""" - ```rst - maxabs(A, dims) - - Compute the maximum absolute values over given dimensions. - ``` - """ maxabs - - @doc doc""" - ```rst - maxabs!(r, A) - - Compute the maximum absolute values over the singleton dimensions - of "r", and write values to "r". - ``` - """ maxabs! - - @doc doc""" - ```rst - minabs(itr) - - Compute the minimum absolute value of a collection of values. - ``` - """ minabs - - @doc doc""" - ```rst - minabs(A, dims) - - Compute the minimum absolute values over given dimensions. - ``` - """ minabs - - @doc doc""" - ```rst - minabs!(r, A) - - Compute the minimum absolute values over the singleton dimensions - of "r", and write values to "r". - ``` - """ minabs! - - @doc doc""" - ```rst - sum(itr) - - Returns the sum of all elements in a collection. - ``` - """ sum - - @doc doc""" - ```rst - sum(A, dims) - - Sum elements of an array over the given dimensions. - ``` - """ sum - - @doc doc""" - ```rst - sum!(r, A) - - Sum elements of "A" over the singleton dimensions of "r", and - write results to "r". - ``` - """ sum! - - @doc doc""" - ```rst - sum(f, itr) - - Sum the results of calling function "f" on each element of - "itr". - ``` - """ sum - - @doc doc""" - ```rst - sumabs(itr) - - Sum absolute values of all elements in a collection. This is - equivalent to *sum(abs(itr))* but faster. - ``` - """ sumabs - - @doc doc""" - ```rst - sumabs(A, dims) - - Sum absolute values of elements of an array over the given - dimensions. - ``` - """ sumabs - - @doc doc""" - ```rst - sumabs!(r, A) - - Sum absolute values of elements of "A" over the singleton - dimensions of "r", and write results to "r". - ``` - """ sumabs! - - @doc doc""" - ```rst - sumabs2(itr) - - Sum squared absolute values of all elements in a collection. This - is equivalent to *sum(abs2(itr))* but faster. - ``` - """ sumabs2 - - @doc doc""" - ```rst - sumabs2(A, dims) - - Sum squared absolute values of elements of an array over the given - dimensions. - ``` - """ sumabs2 - - @doc doc""" - ```rst - sumabs2!(r, A) - - Sum squared absolute values of elements of "A" over the singleton - dimensions of "r", and write results to "r". - ``` - """ sumabs2! - - @doc doc""" - ```rst - prod(itr) - - Returns the product of all elements of a collection. - ``` - """ prod - - @doc doc""" - ```rst - prod(A, dims) - - Multiply elements of an array over the given dimensions. - ``` - """ prod - - @doc doc""" - ```rst - prod!(r, A) - - Multiply elements of "A" over the singleton dimensions of "r", - and write results to "r". - ``` - """ prod! - - @doc doc""" - ```rst - any(itr) -> Bool - - Test whether any elements of a boolean collection are true. - ``` - """ any - - @doc doc""" - ```rst - any(A, dims) - - Test whether any values along the given dimensions of an array are - true. - ``` - """ any - - @doc doc""" - ```rst - any!(r, A) - - Test whether any values in "A" along the singleton dimensions of - "r" are true, and write results to "r". - ``` - """ any! - - @doc doc""" - ```rst - all(itr) -> Bool - - Test whether all elements of a boolean collection are true. - ``` - """ all - - @doc doc""" - ```rst - all(A, dims) - - Test whether all values along the given dimensions of an array are - true. - ``` - """ all - - @doc doc""" - ```rst - all!(r, A) - - Test whether all values in "A" along the singleton dimensions of - "r" are true, and write results to "r". - ``` - """ all! - - @doc doc""" - ```rst - count(p, itr) -> Integer - - Count the number of elements in "itr" for which predicate "p" - returns true. - ``` - """ count - - @doc doc""" - ```rst - any(p, itr) -> Bool - - Determine whether predicate "p" returns true for any elements of - "itr". - ``` - """ any - - @doc doc""" - ```rst - all(p, itr) -> Bool - - Determine whether predicate "p" returns true for all elements of - "itr". - - julia> all(i->(4<=i<=6), [4,5,6]) - true - ``` - """ all - - @doc doc""" - ```rst - 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 - ``` - """ map - - @doc doc""" - ```rst - map!(function, collection) - - In-place version of "map()". - ``` - """ map! - - @doc doc""" - ```rst - 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. - ``` - """ map! - - @doc doc""" - ```rst - 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. - ``` - """ mapreduce - - @doc doc""" - ```rst - mapreduce(f, op, itr) - - Like "mapreduce(f, op, v0, itr)". In general, this cannot be used - with empty collections (see "reduce(op, itr)"). - ``` - """ mapreduce - - @doc doc""" - ```rst - mapfoldl(f, op, v0, itr) - - Like "mapreduce()", but with guaranteed left associativity. - "v0" will be used exactly once. - ``` - """ mapfoldl - - @doc doc""" - ```rst - 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)"). - ``` - """ mapfoldl - - @doc doc""" - ```rst - mapfoldr(f, op, v0, itr) - - Like "mapreduce()", but with guaranteed right associativity. - "v0" will be used exactly once. - ``` - """ mapfoldr - - @doc doc""" - ```rst - 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)"). - ``` - """ mapfoldr - - @doc doc""" - ```rst - first(coll) - - Get the first element of an iterable collection. Returns the start - point of a "Range" even if it is empty. - ``` - """ first - - @doc doc""" - ```rst - 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. - ``` - """ last - - @doc doc""" - ```rst - step(r) - - Get the step size of a "Range" object. - ``` - """ step - - @doc doc""" - ```rst - collect(collection) - - Return an array of all items in a collection. For associative - collections, returns (key, value) tuples. - ``` - """ collect - - @doc doc""" - ```rst - collect(element_type, collection) - - Return an array of type "Array{element_type,1}" of all items in a - collection. - ``` - """ collect - - @doc doc""" - ```rst - issubset(a, b) -⊆(A, S) -> Bool -⊈(A, S) -> Bool -⊊(A, S) -> Bool - - Determine whether every element of "a" is also in "b", using - "in()". - ``` - """ issubset - - @doc doc""" - ```rst - 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). - ``` - """ filter - - @doc doc""" - ```rst - filter!(function, collection) - - Update "collection", removing elements for which "function" is - false. For associative collections, the function is passed two - arguments (key and value). - ``` - """ filter! - - @doc doc""" - ```rst - 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, ...)". - ``` - """ getindex - - @doc doc""" - ```rst - 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, ...)". - ``` - """ setindex! - - @doc doc""" - ```rst - 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{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 - - Alternatively, a sequence of pair arguments may be passed. - - julia> Dict("A"=>1, "B"=>2) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 - ``` - """ Dict - - @doc doc""" - ```rst - haskey(collection, key) -> Bool - - Determine whether a collection has a mapping for a given key. - ``` - """ haskey - - @doc doc""" - ```rst - 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. - ``` - """ get - - @doc doc""" - ```rst - 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 - ``` - """ get - - @doc doc""" - ```rst - 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". - ``` - """ get! - - @doc doc""" - ```rst - 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 - ``` - """ get! - - @doc doc""" - ```rst - getkey(collection, key, default) - - Return the key matching argument "key" if one exists in - "collection", otherwise return "default". - ``` - """ getkey - - @doc doc""" - ```rst - delete!(collection, key) - - Delete the mapping for the given key in a collection, and return - the collection. - ``` - """ delete! - - @doc doc""" - ```rst - 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. - ``` - """ pop! - - @doc doc""" - ```rst - keys(collection) - - Return an iterator over all keys in a collection. - "collect(keys(d))" returns an array of keys. - ``` - """ keys - - @doc doc""" - ```rst - values(collection) - - Return an iterator over all values in a collection. - "collect(values(d))" returns an array of values. - ``` - """ values - - @doc doc""" - ```rst - merge(collection, others...) - - 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. - - julia> a = Dict("foo" => 0.0, "bar" => 42.0) - Dict{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 - - julia> b = Dict(utf8("baz") => 17, utf8("qux") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "baz" => 17 - "qux" => 4711 - - julia> merge(a, b) - Dict{UTF8String,Float64} with 4 entries: - "qux" => 4711.0 - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 - ``` - """ merge - - @doc doc""" - ```rst - merge!(collection, others...) - - Update collection with pairs from the other collections - ``` - """ merge! - - @doc doc""" - ```rst - sizehint!(s, n) - - Suggest that collection "s" reserve capacity for at least "n" - elements. This can improve performance. - ``` - """ sizehint! - - @doc doc""" - ```rst - 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. - ``` - """ Set - - @doc doc""" - ```rst - IntSet([itr]) - - Construct a sorted set of the integers generated by the given - iterable object, or an empty set. Implemented as a bit string, and - therefore designed for dense integer sets. Only non-negative - integers can be stored. If the set will be sparse (for example - holding a single very large integer), use "Set" instead. - ``` - """ IntSet - - @doc doc""" - ```rst - union(s1, s2...) -∪(s1, s2) - - Construct the union of two or more sets. Maintains order with - arrays. - ``` - """ union - - @doc doc""" - ```rst - union!(s, iterable) - - Union each element of "iterable" into set "s" in-place. - ``` - """ union! - - @doc doc""" - ```rst - 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. - ``` - """ intersect - - @doc doc""" - ```rst - setdiff(s1, s2) - - Construct the set of elements in "s1" but not "s2". 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. - ``` - """ setdiff - - @doc doc""" - ```rst - setdiff!(s, iterable) - - Remove each element of "iterable" from set "s" in-place. - ``` - """ setdiff! - - @doc doc""" - ```rst - symdiff(s1, s2...) - - Construct the symmetric difference of elements in the passed in - sets or arrays. Maintains order with arrays. - ``` - """ symdiff - - @doc doc""" - ```rst - symdiff!(s, n) - - The set "s" is destructively modified to toggle the inclusion of - integer "n". - ``` - """ symdiff! - - @doc doc""" - ```rst - symdiff!(s, itr) - - For each element in "itr", destructively toggle its inclusion in - set "s". - ``` - """ symdiff! - - @doc doc""" - ```rst - symdiff!(s1, s2) - - Construct the symmetric difference of sets "s1" and "s2", - storing the result in "s1". - ``` - """ symdiff! - - @doc doc""" - ```rst - complement(s) - - Returns the set-complement of "IntSet" "s". - ``` - """ complement - - @doc doc""" - ```rst - complement!(s) - - Mutates "IntSet" "s" into its set-complement. - ``` - """ complement! - - @doc doc""" - ```rst - intersect!(s1, s2) - - Intersects sets "s1" and "s2" and overwrites the set "s1" - with the result. If needed, "s1" will be expanded to the size of - "s2". - ``` - """ intersect! - - @doc doc""" - ```rst - issubset(A, S) -> Bool -⊆(A, S) -> Bool - - True if A is a subset of or equal to S. - ``` - """ issubset - - @doc doc""" - ```rst - 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])". - ``` - """ push! - - @doc doc""" - ```rst - 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 - ``` - """ pop! - - @doc doc""" - ```rst - 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 - ``` - """ unshift! - - @doc doc""" - ```rst - 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 - ``` - """ shift! - - @doc doc""" - ```rst - insert!(collection, index, item) - - Insert an "item" into "collection" at the given "index". - "index" is the index of "item" in the resulting "collection". - - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 - ``` - """ insert! - - @doc doc""" - ```rst - deleteat!(collection, index) - - Remove the item at the given "index" and return the modified - "collection". 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 - ``` - """ deleteat! - - @doc doc""" - ```rst - deleteat!(collection, itr) - - Remove the items at the indices given by "itr", and return the - modified "collection". Subsequent items are shifted to fill the - resulting gap. "itr" must be sorted and unique. - - 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], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 - ``` - """ deleteat! - - @doc doc""" - ```rst - splice!(collection, index[, replacement]) -> item - - Remove the item at the given index, and return the removed item. - Subsequent items are shifted down 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)". - ``` - """ splice! - - @doc doc""" - ```rst - splice!(collection, range[, replacement]) -> items - - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down 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 - ``` - """ splice! - - @doc doc""" - ```rst - resize!(collection, n) -> collection - - Resize "collection" 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 - ``` - """ resize! - - @doc doc""" - ```rst - 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)". - ``` - """ append! - - @doc doc""" - ```rst - prepend!(collection, items) -> collection - - Insert the elements of "items" to the beginning of - "collection". - - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 - ``` - """ prepend! - - @doc doc""" - ```rst - PriorityQueue(K, V[, ord]) - - Construct a new "PriorityQueue", with keys of type "K" and - values/priorites of type "V". If an order is not given, the - priority queue is min-ordered using the default comparison for - "V". - ``` - """ Base.Collections.PriorityQueue - - @doc doc""" - ```rst - enqueue!(pq, k, v) - - Insert the a key "k" into a priority queue "pq" with priority - "v". - ``` - """ Base.Collections.enqueue! - - @doc doc""" - ```rst - dequeue!(pq) - - Remove and return the lowest priority key from a priority queue. - ``` - """ Base.Collections.dequeue! - - @doc doc""" - ```rst - peek(pq) - - Return the lowest priority key from a priority queue without - removing that key from the queue. - ``` - """ Base.Collections.peek - - @doc doc""" - ```rst - heapify(v[, ord]) - - Return a new vector in binary heap order, optionally using the - given ordering. - ``` - """ Base.Collections.heapify - - @doc doc""" - ```rst - heapify!(v[, ord]) - - In-place "heapify()". - ``` - """ Base.Collections.heapify! - - @doc doc""" - ```rst - isheap(v[, ord]) - - Return true iff an array is heap-ordered according to the given - order. - ``` - """ Base.Collections.isheap - - @doc doc""" - ```rst - heappush!(v, x[, ord]) - - Given a binary heap-ordered array, push a new element "x", - preserving the heap property. For efficiency, this function does - not check that the array is indeed heap-ordered. - ``` - """ Base.Collections.heappush! - - @doc doc""" - ```rst - heappop!(v[, ord]) - - Given a binary heap-ordered array, remove and return the lowest - ordered element. For efficiency, this function does not check that - the array is indeed heap-ordered. - ``` - """ Base.Collections.heappop! - - @doc doc""" - ```rst - nothing - - The singleton instance of type "Void", used by convention when - there is no value to return (as in a C "void" function). Can be - converted to an empty "Nullable" value. - ``` - """ nothing - - @doc doc""" - ```rst - OS_NAME - - A symbol representing the name of the operating system. Possible - values are ":Linux", ":Darwin" (OS X), or ":Windows". - ``` - """ OS_NAME - - @doc doc""" - ```rst - ARGS - - An array of the command line arguments passed to Julia, as strings. - ``` - """ ARGS - - @doc doc""" - ```rst - C_NULL - - The C null pointer constant, sometimes used when calling external - code. - ``` - """ C_NULL - - @doc doc""" - ```rst - WORD_SIZE - - Standard word size on the current machine, in bits. - ``` - """ WORD_SIZE - - @doc doc""" - ```rst - VERSION - - An object describing which version of Julia is in use. - ``` - """ VERSION - - @doc doc""" - ```rst - LOAD_PATH - - An array of paths (as strings) where the "require" function looks - for code. - ``` - """ LOAD_PATH - - @doc doc""" - ```rst - ANY - - Equivalent to "Any" for dispatch purposes, but signals the - compiler to skip code generation specialization for that field - ``` - """ ANY - - @doc doc""" - ```rst - Period - ``` - """ Dates.Period - - @doc doc""" - ```rst - Year - ``` - """ Dates.Year - - @doc doc""" - ```rst - Month - ``` - """ Dates.Month - - @doc doc""" - ```rst - Week - ``` - """ Dates.Week - - @doc doc""" - ```rst - Day - ``` - """ Dates.Day - - @doc doc""" - ```rst - Hour - ``` - """ Dates.Hour - - @doc doc""" - ```rst - Minute - ``` - """ Dates.Minute - - @doc doc""" - ```rst - Second - ``` - """ Dates.Second - - @doc doc""" - ```rst - Millisecond - - "Period" types represent discrete, human representations of time. - ``` - """ Dates.Millisecond - - @doc doc""" - ```rst - Instant - - "Instant" types represent integer-based, machine representations - of time as continuous timelines starting from an epoch. - ``` - """ Dates.Instant - - @doc doc""" - ```rst - TimeType - - "TimeType" types wrap "Instant" machine instances to provide - human representations of the machine instant. - ``` - """ Dates.TimeType - - @doc doc""" - ```rst - DateTime - - "DateTime" wraps a "UTInstant{Millisecond}" and interprets it - according to the proleptic Gregorian calendar. - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - Date - - "Date" wraps a "UTInstant{Day}" and interprets it according to - the proleptic Gregorian calendar. - ``` - """ Dates.Date - - @doc doc""" - ```rst - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to "Int64". - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by "Period" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of "Dates.default(period)". - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided "y, m, d..." arguments, and will - be adjusted until "f::Function" returns true. The step size in - adjusting can be provided manually through the "step" keyword. If - "negate=true", then the adjusting will stop when "f::Function" - returns false instead of true. "limit" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that "f::Function" is never - satisfied). - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - DateTime(dt::Date) -> DateTime - - Converts a "Date" type to a "DateTime". The hour, minute, - second, and millisecond parts of the new "DateTime" are assumed - to be zero. - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime - - Construct a DateTime type by parsing the "dt" date string - following the pattern given in the "format" string. The following - codes can be used for constructing format strings: - - +-----------------+-----------+-----------------------------------------------------------------+ - | Code | Matches | Comment | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"y\" | 1996, 96 | Returns year of 1996, 0096 | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"m\" | 1, 01 | Matches 1 or 2-digit months | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"U\" | January | Matches full month names according to the \"locale\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"d\" | 1, 01 | Matches 1 or 2-digit days | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"H\" | 00 | Matches hours | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"M\" | 00 | Matches minutes | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"S\" | 00 | Matches seconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"s\" | .500 | Matches milliseconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"e\" | Mon, Tues | Matches abbreviated days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"E\" | Monday | Matches full name days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | - +-----------------+-----------+-----------------------------------------------------------------+ - - All characters not listed above are treated as delimiters between - date and time slots. So a "dt" string of - "1996-01-15T00:00:00.0" would have a "format" string like - "y-m-dTH:M:S.s". - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - Dates.DateFormat(format::AbstractString) -> DateFormat - - Construct a date formatting object that can be passed repeatedly - for parsing similarly formatted date strings. "format" is a - format string in the form described above (e.g. ""yyyy-mm- - dd""). - ``` - """ Dates.Dates - - @doc doc""" - ```rst - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. - ``` - """ Dates.DateTime - - @doc doc""" - ```rst - Date(y[, m, d]) -> Date - - Construct a "Date" type by parts. Arguments must be convertible - to "Int64". - ``` - """ Dates.Date - - @doc doc""" - ```rst - Date(period::Period...) -> Date - - Constuct a Date type by "Period" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - "Dates.default(period)". - ``` - """ Dates.Date - - @doc doc""" - ```rst - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided "y, m" arguments, and will be - adjusted until "f::Function" returns true. The step size in - adjusting can be provided manually through the "step" keyword. If - "negate=true", then the adjusting will stop when "f::Function" - returns false instead of true. "limit" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that "f::Function" is never satisfied). - ``` - """ Dates.Date - - @doc doc""" - ```rst - Date(dt::DateTime) -> Date - - Converts a "DateTime" type to a "Date". The hour, minute, - second, and millisecond parts of the "DateTime" are truncated, so - only the year, month and day parts are used in construction. - ``` - """ Dates.Date - - @doc doc""" - ```rst - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - - Construct a Date type by parsing a "dt" date string following the - pattern given in the "format" string. Follows the same - conventions as "DateTime" above. - ``` - """ Dates.Date - - @doc doc""" - ```rst - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string "dt" using a "DateFormat" - object "df". - ``` - """ Dates.Date - - @doc doc""" - ```rst - now() -> DateTime - - Returns a DateTime corresponding to the user's system time - including the system timezone locale. - ``` - """ Dates.now - - @doc doc""" - ```rst - now(::Type{UTC}) -> DateTime - - Returns a DateTime corresponding to the user's system time as - UTC/GMT. - ``` - """ Dates.now - - @doc doc""" - ```rst - eps(::DateTime) -> Millisecond -eps(::Date) -> Day - - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" - for "Date" values. - ``` - """ Dates.eps - - @doc doc""" - ```rst - year(dt::TimeType) -> Int64 -month(dt::TimeType) -> Int64 -week(dt::TimeType) -> Int64 -day(dt::TimeType) -> Int64 -hour(dt::TimeType) -> Int64 -minute(dt::TimeType) -> Int64 -second(dt::TimeType) -> Int64 -millisecond(dt::TimeType) -> Int64 - - Return the field part of a Date or DateTime as an "Int64". - ``` - """ Dates.year - - @doc doc""" - ```rst - Year(dt::TimeType) -> Year -Month(dt::TimeType) -> Month -Week(dt::TimeType) -> Week -Day(dt::TimeType) -> Day -Hour(dt::TimeType) -> Hour -Minute(dt::TimeType) -> Minute -Second(dt::TimeType) -> Second -Millisecond(dt::TimeType) -> Millisecond - - Return the field part of a Date or DateTime as a "Period" type. - ``` - """ Dates.Year - - @doc doc""" - ```rst - yearmonth(dt::TimeType) -> (Int64, Int64) - - Simultaneously return the year and month parts of a Date or - DateTime. - ``` - """ Dates.yearmonth - - @doc doc""" - ```rst - monthday(dt::TimeType) -> (Int64, Int64) - - Simultaneously return the month and day parts of a Date or - DateTime. - ``` - """ Dates.monthday - - @doc doc""" - ```rst - yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - - Simultaneously return the year, month, and day parts of a Date or - DateTime. - ``` - """ Dates.yearmonthday - - @doc doc""" - ```rst - dayname(dt::TimeType; locale="english") -> AbstractString - - Return the full day name corresponding to the day of the week of - the Date or DateTime in the given "locale". - ``` - """ Dates.dayname - - @doc doc""" - ```rst - dayabbr(dt::TimeType; locale="english") -> AbstractString - - Return the abbreviated name corresponding to the day of the week of - the Date or DateTime in the given "locale". - ``` - """ Dates.dayabbr - - @doc doc""" - ```rst - dayofweek(dt::TimeType) -> Int64 - - Returns the day of the week as an "Int64" with "1 = Monday, 2 = - Tuesday, etc.". - ``` - """ Dates.dayofweek - - @doc doc""" - ```rst - dayofweekofmonth(dt::TimeType) -> Int - - For the day of week of "dt", returns which number it is in - "dt"'s month. So if the day of the week of "dt" is Monday, then - "1 = First Monday of the month, 2 = Second Monday of the month, - etc." In the range 1:5. - ``` - """ Dates.dayofweekofmonth - - @doc doc""" - ```rst - daysofweekinmonth(dt::TimeType) -> Int - - For the day of week of "dt", returns the total number of that day - of the week in "dt"'s month. Returns 4 or 5. Useful in temporal - expressions for specifying the last day of a week in a month by - including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the - adjuster function. - ``` - """ Dates.daysofweekinmonth - - @doc doc""" - ```rst - monthname(dt::TimeType; locale="english") -> AbstractString - - Return the full name of the month of the Date or DateTime in the - given "locale". - ``` - """ Dates.monthname - - @doc doc""" - ```rst - monthabbr(dt::TimeType; locale="english") -> AbstractString - - Return the abbreviated month name of the Date or DateTime in the - given "locale". - ``` - """ Dates.monthabbr - - @doc doc""" - ```rst - daysinmonth(dt::TimeType) -> Int - - Returns the number of days in the month of "dt". Value will be - 28, 29, 30, or 31. - ``` - """ Dates.daysinmonth - - @doc doc""" - ```rst - isleapyear(dt::TimeType) -> Bool - - Returns true if the year of "dt" is a leap year. - ``` - """ Dates.isleapyear - - @doc doc""" - ```rst - dayofyear(dt::TimeType) -> Int - - Returns the day of the year for "dt" with January 1st being day - 1. - ``` - """ Dates.dayofyear - - @doc doc""" - ```rst - daysinyear(dt::TimeType) -> Int - - Returns 366 if the year of "dt" is a leap year, otherwise returns - 365. - ``` - """ Dates.daysinyear - - @doc doc""" - ```rst - quarterofyear(dt::TimeType) -> Int - - Returns the quarter that "dt" resides in. Range of value is 1:4. - ``` - """ Dates.quarterofyear - - @doc doc""" - ```rst - dayofquarter(dt::TimeType) -> Int - - Returns the day of the current quarter of "dt". Range of value is - 1:92. - ``` - """ Dates.dayofquarter - - @doc doc""" - ```rst - trunc(dt::TimeType, ::Type{Period}) -> TimeType - - Truncates the value of "dt" according to the provided "Period" - type. E.g. if "dt" is "1996-01-01T12:30:00", then - "trunc(dt,Day) == 1996-01-01T00:00:00". - ``` - """ Dates.trunc - - @doc doc""" - ```rst - firstdayofweek(dt::TimeType) -> TimeType - - Adjusts "dt" to the Monday of its week. - ``` - """ Dates.firstdayofweek - - @doc doc""" - ```rst - lastdayofweek(dt::TimeType) -> TimeType - - Adjusts "dt" to the Sunday of its week. - ``` - """ Dates.lastdayofweek - - @doc doc""" - ```rst - firstdayofmonth(dt::TimeType) -> TimeType - - Adjusts "dt" to the first day of its month. - ``` - """ Dates.firstdayofmonth - - @doc doc""" - ```rst - lastdayofmonth(dt::TimeType) -> TimeType - - Adjusts "dt" to the last day of its month. - ``` - """ Dates.lastdayofmonth - - @doc doc""" - ```rst - firstdayofyear(dt::TimeType) -> TimeType - - Adjusts "dt" to the first day of its year. - ``` - """ Dates.firstdayofyear - - @doc doc""" - ```rst - lastdayofyear(dt::TimeType) -> TimeType - - Adjusts "dt" to the last day of its year. - ``` - """ Dates.lastdayofyear - - @doc doc""" - ```rst - firstdayofquarter(dt::TimeType) -> TimeType - - Adjusts "dt" to the first day of its quarter. - ``` - """ Dates.firstdayofquarter - - @doc doc""" - ```rst - lastdayofquarter(dt::TimeType) -> TimeType - - Adjusts "dt" to the last day of its quarter. - ``` - """ Dates.lastdayofquarter - - @doc doc""" - ```rst - tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts "dt" to the next day of week corresponding to "dow" - with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows - the current "dt" to be considered as the next "dow", allowing - for no adjustment to occur. - ``` - """ Dates.tonext - - @doc doc""" - ```rst - toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts "dt" to the previous day of week corresponding to "dow" - with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows - the current "dt" to be considered as the previous "dow", - allowing for no adjustment to occur. - ``` - """ Dates.toprev - - @doc doc""" - ```rst - tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - - Adjusts "dt" to the first "dow" of its month. Alternatively, - "of=Year" will adjust to the first "dow" of the year. - ``` - """ Dates.tofirst - - @doc doc""" - ```rst - tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - - Adjusts "dt" to the last "dow" of its month. Alternatively, - "of=Year" will adjust to the last "dow" of the year. - ``` - """ Dates.tolast - - @doc doc""" - ```rst - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. - ``` - """ Dates.tonext - - @doc doc""" - ```rst - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. - ``` - """ Dates.toprev - - @doc doc""" - ```rst - Year(v) -Month(v) -Week(v) -Day(v) -Hour(v) -Minute(v) -Second(v) -Millisecond(v) - - Construct a "Period" type with the given "v" value. Input must - be losslessly convertible to an "Int64". - ``` - """ Dates.Year - - @doc doc""" - ```rst - default(p::Period) -> Period - - Returns a sensible "default" value for the input Period by - returning "one(p)" for Year, Month, and Day, and "zero(p)" for - Hour, Minute, Second, and Millisecond. - ``` - """ Dates.default - - @doc doc""" - ```rst - today() -> Date - - Returns the date portion of "now()". - ``` - """ Dates.today - - @doc doc""" - ```rst - unix2datetime(x) -> DateTime - - Takes the number of seconds since unix epoch - "1970-01-01T00:00:00" and converts to the corresponding DateTime. - ``` - """ Dates.unix2datetime - - @doc doc""" - ```rst - datetime2unix(dt::DateTime) -> Float64 - - Takes the given DateTime and returns the number of seconds since - the unix epoch as a "Float64". - ``` - """ Dates.datetime2unix - - @doc doc""" - ```rst - julian2datetime(julian_days) -> DateTime - - Takes the number of Julian calendar days since epoch - "-4713-11-24T12:00:00" and returns the corresponding DateTime. - ``` - """ Dates.julian2datetime - - @doc doc""" - ```rst - datetime2julian(dt::DateTime) -> Float64 - - Takes the given DateTime and returns the number of Julian calendar - days since the julian epoch as a "Float64". - ``` - """ Dates.datetime2julian - - @doc doc""" - ```rst - rata2datetime(days) -> DateTime - - Takes the number of Rata Die days since epoch - "0000-12-31T00:00:00" and returns the corresponding DateTime. - ``` - """ Dates.rata2datetime - - @doc doc""" - ```rst - datetime2rata(dt::TimeType) -> Int64 - - Returns the number of Rata Die days since epoch from the given Date - or DateTime. - ``` - """ Dates.datetime2rata - - @doc doc""" - ```rst - pwd() -> AbstractString - - Get the current working directory. - ``` - """ pwd - - @doc doc""" - ```rst - cd(dir::AbstractString) - - Set the current working directory. - ``` - """ cd - - @doc doc""" - ```rst - cd(f[, dir]) - - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. - ``` - """ cd - - @doc doc""" - ```rst - readdir([dir]) -> Vector{ByteString} - - Returns the files and directories in the directory *dir* (or the - current working directory if not given). - ``` - """ readdir - - @doc doc""" - ```rst - mkdir(path[, mode]) - - Make a new directory with name "path" and permissions "mode". - "mode" defaults to 0o777, modified by the current file creation - mask. - ``` - """ mkdir - - @doc doc""" - ```rst - mkpath(path[, mode]) - - Create all directories in the given "path", with permissions - "mode". "mode" defaults to 0o777, modified by the current file - creation mask. - ``` - """ mkpath - - @doc doc""" - ```rst - symlink(target, link) - - Creates a symbolic link to "target" with the name "link". - - Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. - ``` - """ symlink - - @doc doc""" - ```rst - readlink(path) -> AbstractString - - Returns the value of a symbolic link "path". - ``` - """ readlink - - @doc doc""" - ```rst - chmod(path, mode) - - Change the permissions mode of "path" to "mode". Only integer - "mode"s (e.g. 0o777) are currently supported. - ``` - """ chmod - - @doc doc""" - ```rst - stat(file) - - Returns a structure whose fields contain information about the - file. The fields of the structure are: - - +-----------+------------------------------------------------------------------------+ - | size | The size (in bytes) of the file | - +-----------+------------------------------------------------------------------------+ - | device | ID of the device that contains the file | - +-----------+------------------------------------------------------------------------+ - | inode | The inode number of the file | - +-----------+------------------------------------------------------------------------+ - | mode | The protection mode of the file | - +-----------+------------------------------------------------------------------------+ - | nlink | The number of hard links to the file | - +-----------+------------------------------------------------------------------------+ - | uid | The user id of the owner of the file | - +-----------+------------------------------------------------------------------------+ - | gid | The group id of the file owner | - +-----------+------------------------------------------------------------------------+ - | rdev | If this file refers to a device, the ID of the device it refers to | - +-----------+------------------------------------------------------------------------+ - | blksize | The file-system preferred block size for the file | - +-----------+------------------------------------------------------------------------+ - | blocks | The number of such blocks allocated | - +-----------+------------------------------------------------------------------------+ - | mtime | Unix timestamp of when the file was last modified | - +-----------+------------------------------------------------------------------------+ - | ctime | Unix timestamp of when the file was created | - +-----------+------------------------------------------------------------------------+ - ``` - """ stat - - @doc doc""" - ```rst - lstat(file) - - Like stat, but for symbolic links gets the info for the link itself - rather than the file it refers to. This function must be called on - a file path rather than a file object or a file descriptor. - ``` - """ lstat - - @doc doc""" - ```rst - ctime(file) - - Equivalent to stat(file).ctime - ``` - """ ctime - - @doc doc""" - ```rst - mtime(file) - - Equivalent to stat(file).mtime - ``` - """ mtime - - @doc doc""" - ```rst - filemode(file) - - Equivalent to stat(file).mode - ``` - """ filemode - - @doc doc""" - ```rst - filesize(path...) - - Equivalent to stat(file).size - ``` - """ filesize - - @doc doc""" - ```rst - uperm(file) - - Gets the permissions of the owner of the file as a bitfield of - - +------+-----------------------+ - | 01 | Execute Permission | - +------+-----------------------+ - | 02 | Write Permission | - +------+-----------------------+ - | 04 | Read Permission | - +------+-----------------------+ - - For allowed arguments, see "stat". - ``` - """ uperm - - @doc doc""" - ```rst - gperm(file) - - Like uperm but gets the permissions of the group owning the file - ``` - """ gperm - - @doc doc""" - ```rst - operm(file) - - Like uperm but gets the permissions for people who neither own the - file nor are a member of the group owning the file - ``` - """ operm - - @doc doc""" - ```rst - cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - - Copy the file, link, or directory from *src* to *dest*. - "remove_destination=true" will first remove an existing *dst*. - - If *follow_symlinks=false*, and src is a symbolic link, dst will be - created as a symbolic link. If *follow_symlinks=true* and src is a - symbolic link, dst will be a copy of the file or directory *src* - refers to. - ``` - """ cp - - @doc doc""" - ```rst - download(url[, localfile]) - - Download a file from the given url, optionally renaming it to the - given local file name. Note that this function relies on the - availability of external tools such as "curl", "wget" or - "fetch" to download the file and is provided for convenience. For - production use or situations in which more options are need, please - use a package that provides the desired functionality instead. - ``` - """ download - - @doc doc""" - ```rst - mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - - Move the file, link, or directory from *src* to *dest*. - "remove_destination=true" will first remove an existing *dst*. - ``` - """ mv - - @doc doc""" - ```rst - rm(path::AbstractString; recursive=false) - - Delete the file, link, or empty directory at the given path. If - "recursive=true" is passed and the path is a directory, then all - contents are removed recursively. - ``` - """ rm - - @doc doc""" - ```rst - touch(path::AbstractString) - - Update the last-modified timestamp on a file to the current time. - ``` - """ touch - - @doc doc""" - ```rst - tempname() - - Generate a unique temporary file path. - ``` - """ tempname - - @doc doc""" - ```rst - tempdir() - - Obtain the path of a temporary directory (possibly shared with - other processes). - ``` - """ tempdir - - @doc doc""" - ```rst - mktemp([parent=tempdir()]) - - Returns "(path, io)", where "path" is the path of a new - temporary file in "parent" and "io" is an open file object for - this path. - ``` - """ mktemp - - @doc doc""" - ```rst - mktempdir([parent=tempdir()]) - - Create a temporary directory in the "parent" directory and return - its path. - ``` - """ mktempdir - - @doc doc""" - ```rst - isblockdev(path) -> Bool - - Returns "true" if "path" is a block device, "false" - otherwise. - ``` - """ isblockdev - - @doc doc""" - ```rst - ischardev(path) -> Bool - - Returns "true" if "path" is a character device, "false" - otherwise. - ``` - """ ischardev - - @doc doc""" - ```rst - isdir(path) -> Bool - - Returns "true" if "path" is a directory, "false" otherwise. - ``` - """ isdir - - @doc doc""" - ```rst - isexecutable(path) -> Bool - - Returns "true" if the current user has permission to execute - "path", "false" otherwise. - ``` - """ isexecutable - - @doc doc""" - ```rst - isfifo(path) -> Bool - - Returns "true" if "path" is a FIFO, "false" otherwise. - ``` - """ isfifo - - @doc doc""" - ```rst - isfile(path) -> Bool - - Returns "true" if "path" is a regular file, "false" - otherwise. - ``` - """ isfile - - @doc doc""" - ```rst - islink(path) -> Bool - - Returns "true" if "path" is a symbolic link, "false" - otherwise. - ``` - """ islink - - @doc doc""" - ```rst - ismount(path) -> Bool - - Returns "true" if "path" is a mount point, "false" otherwise. - ``` - """ ismount - - @doc doc""" - ```rst - ispath(path) -> Bool - - Returns "true" if "path" is a valid filesystem path, "false" - otherwise. - ``` - """ ispath - - @doc doc""" - ```rst - isreadable(path) -> Bool - - Returns "true" if the current user has permission to read - "path", "false" otherwise. - ``` - """ isreadable - - @doc doc""" - ```rst - issetgid(path) -> Bool - - Returns "true" if "path" has the setgid flag set, "false" - otherwise. - ``` - """ issetgid - - @doc doc""" - ```rst - issetuid(path) -> Bool - - Returns "true" if "path" has the setuid flag set, "false" - otherwise. - ``` - """ issetuid - - @doc doc""" - ```rst - issocket(path) -> Bool - - Returns "true" if "path" is a socket, "false" otherwise. - ``` - """ issocket - - @doc doc""" - ```rst - issticky(path) -> Bool - - Returns "true" if "path" has the sticky bit set, "false" - otherwise. - ``` - """ issticky - - @doc doc""" - ```rst - iswritable(path) -> Bool - - Returns "true" if the current user has permission to write to - "path", "false" otherwise. - ``` - """ iswritable - - @doc doc""" - ```rst - homedir() -> AbstractString - - Return the current user's home directory. - ``` - """ homedir - - @doc doc""" - ```rst - dirname(path::AbstractString) -> AbstractString - - Get the directory part of a path. - ``` - """ dirname - - @doc doc""" - ```rst - basename(path::AbstractString) -> AbstractString - - Get the file name part of a path. - ``` - """ basename - - @doc doc""" - ```rst - @__FILE__() -> AbstractString - - "@__FILE__" expands to a string with the absolute path and file - name of the script being run. Returns "nothing" if run from a - REPL or an empty string if evaluated by "julia -e ". - ``` - """ @__FILE__ - - @doc doc""" - ```rst - isabspath(path::AbstractString) -> Bool - - Determines whether a path is absolute (begins at the root - directory). - ``` - """ isabspath - - @doc doc""" - ```rst - isdirpath(path::AbstractString) -> Bool - - Determines whether a path refers to a directory (for example, ends - with a path separator). - ``` - """ isdirpath - - @doc doc""" - ```rst - joinpath(parts...) -> AbstractString - - Join path components into a full path. If some argument is an - absolute path, then prior components are dropped. - ``` - """ joinpath - - @doc doc""" - ```rst - abspath(path::AbstractString) -> AbstractString - - Convert a path to an absolute path by adding the current directory - if necessary. - ``` - """ abspath - - @doc doc""" - ```rst - normpath(path::AbstractString) -> AbstractString - - Normalize a path, removing "." and ".." entries. - ``` - """ normpath - - @doc doc""" - ```rst - realpath(path::AbstractString) -> AbstractString - - Canonicalize a path by expanding symbolic links and removing "." - and ".." entries. - ``` - """ realpath - - @doc doc""" - ```rst - relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - - Return a relative filepath to path either from the current - directory or from an optional start directory. This is a path - computation: the filesystem is not accessed to confirm the - existence or nature of path or startpath. - ``` - """ relpath - - @doc doc""" - ```rst - expanduser(path::AbstractString) -> AbstractString - - On Unix systems, replace a tilde character at the start of a path - with the current user's home directory. - ``` - """ expanduser - - @doc doc""" - ```rst - splitdir(path::AbstractString) -> (AbstractString, AbstractString) - - Split a path into a tuple of the directory name and file name. - ``` - """ splitdir - - @doc doc""" - ```rst - splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - - On Windows, split a path into the drive letter part and the path - part. On Unix systems, the first component is always the empty - string. - ``` - """ splitdrive - - @doc doc""" - ```rst - splitext(path::AbstractString) -> (AbstractString, AbstractString) - - If the last component of a path contains a dot, split the path into - everything before the dot and everything including and after the - dot. Otherwise, return a tuple of the argument unmodified and the - empty string. - ``` - """ splitext - - @doc doc""" - ```rst - open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - ``` - """ open - - @doc doc""" - ```rst - open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of "mode" - correspond to those from "fopen(3)" or Perl "open", and are - equivalent to setting the following boolean groups: - - +------+-----------------------------------+ - | r | read | - +------+-----------------------------------+ - | r+ | read, write | - +------+-----------------------------------+ - | w | write, create, truncate | - +------+-----------------------------------+ - | w+ | read, write, create, truncate | - +------+-----------------------------------+ - | a | write, create, append | - +------+-----------------------------------+ - | a+ | read, write, create, append | - +------+-----------------------------------+ - ``` - """ open - - @doc doc""" - ```rst - open(f::function, args...) - - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. - - **Example**: "open(readall, "file.txt")" - ``` - """ open - - @doc doc""" - ```rst - IOBuffer() -> IOBuffer - - Create an in-memory I/O stream. - ``` - """ IOBuffer - - @doc doc""" - ```rst - IOBuffer(size::Int) - - Create a fixed size IOBuffer. The buffer will not grow dynamically. - ``` - """ IOBuffer - - @doc doc""" - ```rst - IOBuffer(string) - - Create a read-only IOBuffer on the data underlying the given string - ``` - """ IOBuffer - - @doc doc""" - ```rst - IOBuffer([data][, readable, writable[, maxsize]]) - - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. - ``` - """ IOBuffer - - @doc doc""" - ```rst - takebuf_array(b::IOBuffer) - - Obtain the contents of an "IOBuffer" as an array, without - copying. Afterwards, the IOBuffer is reset to its initial state. - ``` - """ takebuf_array - - @doc doc""" - ```rst - takebuf_string(b::IOBuffer) - - Obtain the contents of an "IOBuffer" as a string, without - copying. Afterwards, the IOBuffer is reset to its initial state. - ``` - """ takebuf_string - - @doc doc""" - ```rst - fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - - Create an "IOStream" object from an integer file descriptor. If - "own" is true, closing this object will close the underlying - descriptor. By default, an "IOStream" is closed when it is - garbage collected. "name" allows you to associate the descriptor - with a named file. - ``` - """ fdio - - @doc doc""" - ```rst - flush(stream) - - Commit all currently buffered writes to the given stream. - ``` - """ flush - - @doc doc""" - ```rst - close(stream) - - Close an I/O stream. Performs a "flush" first. - ``` - """ close - - @doc doc""" - ```rst - write(stream, x) - - Write the canonical binary representation of a value to the given - stream. - ``` - """ write - - @doc doc""" - ```rst - read(stream, type) - - Read a value of the given type from a stream, in canonical binary - representation. - ``` - """ read - - @doc doc""" - ```rst - read(stream, type, dims) - - Read a series of values of the given type from a stream, in - canonical binary representation. "dims" is either a tuple or a - series of integer arguments specifying the size of "Array" to - return. - ``` - """ read - - @doc doc""" - ```rst - read!(stream, array::Array) - - Read binary data from a stream, filling in the argument "array". - ``` - """ read! - - @doc doc""" - ```rst - readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - - Read at most "nb" bytes from the stream into "b", returning the - number of bytes read (increasing the size of "b" as needed). - ``` - """ readbytes! - - @doc doc""" - ```rst - readbytes(stream, nb=typemax(Int)) - - Read at most "nb" bytes from the stream, returning a - "Vector{UInt8}" of the bytes read. - ``` - """ readbytes - - @doc doc""" - ```rst - position(s) - - Get the current position of a stream. - ``` - """ position - - @doc doc""" - ```rst - seek(s, pos) - - Seek a stream to the given position. - ``` - """ seek - - @doc doc""" - ```rst - seekstart(s) - - Seek a stream to its beginning. - ``` - """ seekstart - - @doc doc""" - ```rst - seekend(s) - - Seek a stream to its end. - ``` - """ seekend - - @doc doc""" - ```rst - skip(s, offset) - - Seek a stream relative to the current position. - ``` - """ skip - - @doc doc""" - ```rst - mark(s) - - Add a mark at the current position of stream "s". Returns the - marked position. - - See also "unmark()", "reset()", "ismarked()" - ``` - """ mark - - @doc doc""" - ```rst - unmark(s) - - Remove a mark from stream "s". Returns "true" if the stream was - marked, "false" otherwise. - - See also "mark()", "reset()", "ismarked()" - ``` - """ unmark - - @doc doc""" - ```rst - reset(s) - - Reset a stream "s" to a previously marked position, and remove - the mark. Returns the previously marked position. Throws an error - if the stream is not marked. - - See also "mark()", "unmark()", "ismarked()" - ``` - """ reset - - @doc doc""" - ```rst - ismarked(s) - - Returns true if stream "s" is marked. - - See also "mark()", "unmark()", "reset()" - ``` - """ ismarked - - @doc doc""" - ```rst - eof(stream) -> Bool - - Tests whether an I/O stream is at end-of-file. If the stream is not - yet exhausted, this function will block to wait for more data if - necessary, and then return "false". Therefore it is always safe - to read one byte after seeing "eof" return "false". "eof" - will return "false" as long as buffered data is still available, - even if the remote end of a connection is closed. - ``` - """ eof - - @doc doc""" - ```rst - isreadonly(stream) -> Bool - - Determine whether a stream is read-only. - ``` - """ isreadonly - - @doc doc""" - ```rst - isopen(stream) -> Bool - - Determine whether a stream is open (i.e. has not been closed yet). - If the connection has been closed remotely (in case of e.g. a - socket), "isopen" will return "false" even though buffered data - may still be available. Use "eof" to check if necessary. - ``` - """ isopen - - @doc doc""" - ```rst - serialize(stream, value) - - Write an arbitrary value to a stream in an opaque format, such that - it can be read back by "deserialize". The read-back value will be - as identical as possible to the original. In general, this process - will not work if the reading and writing are done by different - versions of Julia, or an instance of Julia with a different system - image. - ``` - """ serialize - - @doc doc""" - ```rst - deserialize(stream) - - Read a value written by "serialize". - ``` - """ deserialize - - @doc doc""" - ```rst - print_escaped(io, str::AbstractString, esc::AbstractString) - - General escaping of traditional C and Unicode escape sequences, - plus any characters in esc are also escaped (with a backslash). - ``` - """ print_escaped - - @doc doc""" - ```rst - print_unescaped(io, s::AbstractString) - - General unescaping of traditional C and Unicode escape sequences. - Reverse of "print_escaped()". - ``` - """ print_unescaped - - @doc doc""" - ```rst - print_joined(io, items, delim[, last]) - - Print elements of "items" to "io" with "delim" between them. - If "last" is specified, it is used as the final delimiter instead - of "delim". - ``` - """ print_joined - - @doc doc""" - ```rst - print_shortest(io, x) - - Print the shortest possible representation, with the minimum number - of consecutive non-zero digits, of number "x", ensuring that it - would parse to the exact same number. - ``` - """ print_shortest - - @doc doc""" - ```rst - fd(stream) - - Returns the file descriptor backing the stream or file. Note that - this function only applies to synchronous *File*'s and *IOStream*'s - not to any of the asynchronous streams. - ``` - """ fd - - @doc doc""" - ```rst - redirect_stdout() - - Create a pipe to which all C and Julia level STDOUT output will be - redirected. Returns a tuple (rd,wr) representing the pipe ends. - Data written to STDOUT may now be read from the rd end of the pipe. - The wr end is given for convenience in case the old STDOUT object - was cached by the user and needs to be replaced elsewhere. - ``` - """ redirect_stdout - - @doc doc""" - ```rst - redirect_stdout(stream) - - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - ``` - """ redirect_stdout - - @doc doc""" - ```rst - redirect_stderr([stream]) - - Like redirect_stdout, but for STDERR - ``` - """ redirect_stderr - - @doc doc""" - ```rst - redirect_stdin([stream]) - - Like redirect_stdout, but for STDIN. Note that the order of the - return tuple is still (rd,wr), i.e. data to be read from STDIN, may - be written to wr. - ``` - """ redirect_stdin - - @doc doc""" - ```rst - readchomp(x) - - Read the entirety of x as a string but remove trailing newlines. - Equivalent to chomp(readall(x)). - ``` - """ readchomp - - @doc doc""" - ```rst - truncate(file, n) - - Resize the file or buffer given by the first argument to exactly - *n* bytes, filling previously unallocated space with '\0' if the - file or buffer is grown - ``` - """ truncate - - @doc doc""" - ```rst - skipchars(stream, predicate; linecomment::Char) - - Advance the stream until before the first character for which - "predicate" returns false. For example "skipchars(stream, - isspace)" will skip all whitespace. If keyword argument - "linecomment" is specified, characters from that character - through the end of a line will also be skipped. - ``` - """ skipchars - - @doc doc""" - ```rst - countlines(io[, eol::Char]) - - Read io until the end of the stream/file and count the number of - non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than '\n' are supported by passing - them as the second argument. - ``` - """ countlines - - @doc doc""" - ```rst - PipeBuffer() - - An IOBuffer that allows reading and performs writes by appending. - Seeking and truncating are not supported. See IOBuffer for the - available constructors. - ``` - """ PipeBuffer - - @doc doc""" - ```rst - PipeBuffer(data::Vector{UInt8}[, maxsize]) - - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. - ``` - """ PipeBuffer - - @doc doc""" - ```rst - readavailable(stream) - - Read all available data on the stream, blocking the task only if no - data is available. The result is a "Vector{UInt8,1}". - ``` - """ readavailable - - @doc doc""" - ```rst - show(x) - - Write an informative text representation of a value to the current - output stream. New types should overload "show(io, x)" where the - first argument is a stream. The representation used by "show" - generally includes Julia-specific formatting and type information. - ``` - """ show - - @doc doc""" - ```rst - showcompact(x) - - Show a more compact representation of a value. This is used for - printing array elements. If a new type has a different compact - representation, it should overload "showcompact(io, x)" where the - first argument is a stream. - ``` - """ showcompact - - @doc doc""" - ```rst - showall(x) - - Similar to "show", except shows all elements of arrays. - ``` - """ showall - - @doc doc""" - ```rst - summary(x) - - Return a string giving a brief description of a value. By default - returns "string(typeof(x))". For arrays, returns strings like - "2x2 Float64 Array". - ``` - """ summary - - @doc doc""" - ```rst - print(x) - - Write (to the default output stream) a canonical (un-decorated) - text representation of a value if there is one, otherwise call - "show". The representation used by "print" includes minimal - formatting and tries to avoid Julia-specific details. - ``` - """ print - - @doc doc""" - ```rst - println(x) - - Print (using "print()") "x" followed by a newline. - ``` - """ println - - @doc doc""" - ```rst - print_with_color(color::Symbol[, io], strings...) - - Print strings in a color specified as a symbol, for example - ":red" or ":blue". - ``` - """ print_with_color - - @doc doc""" - ```rst - info(msg) - - Display an informational message. - ``` - """ info - - @doc doc""" - ```rst - warn(msg) - - Display a warning. - ``` - """ warn - - @doc doc""" - ```rst - @printf([io::IOStream], "%Fmt", args...) - - Print arg(s) using C "printf()" style format specification - string. Optionally, an IOStream may be passed as the first argument - to redirect output. - ``` - """ @printf - - @doc doc""" - ```rst - @sprintf("%Fmt", args...) - - Return "@printf" formatted output as string. - ``` - """ @sprintf - - @doc doc""" - ```rst - sprint(f::Function, args...) - - Call the given function with an I/O stream and the supplied extra - arguments. Everything written to this I/O stream is returned as a - string. - ``` - """ sprint - - @doc doc""" - ```rst - showerror(io, e) - - Show a descriptive representation of an exception object. - ``` - """ showerror - - @doc doc""" - ```rst - dump(x) - - Show all user-visible structure of a value. - ``` - """ dump - - @doc doc""" - ```rst - xdump(x) - - Show all structure of a value, including all fields of objects. - ``` - """ xdump - - @doc doc""" - ```rst - readall(stream::IO) - - Read the entire contents of an I/O stream as a string. - ``` - """ readall - - @doc doc""" - ```rst - readall(filename::AbstractString) - - Open "filename", read the entire contents as a string, then close - the file. Equivalent to "open(readall, filename)". - ``` - """ readall - - @doc doc""" - ```rst - readline(stream=STDIN) - - Read a single line of text, including a trailing newline character - (if one is reached before the end of the input), from the given - "stream" (defaults to "STDIN"), - ``` - """ readline - - @doc doc""" - ```rst - readuntil(stream, delim) - - Read a string, up to and including the given delimiter byte. - ``` - """ readuntil - - @doc doc""" - ```rst - readlines(stream) - - Read all lines as an array. - ``` - """ readlines - - @doc doc""" - ```rst - eachline(stream) - - Create an iterable object that will yield each line from a stream. - ``` - """ eachline - - @doc doc""" - ```rst - readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - "eol") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If "T" is a numeric type, the result is an array of that type, - with any non-numeric elements as "NaN" for floating-point types, - or zero. Other useful values of "T" include "ASCIIString", - "AbstractString", and "Any". - - If "header" is "true", the first row of data will be read as - header and the tuple "(data_cells, header_cells)" is returned - instead of only "data_cells". - - Specifying "skipstart" will ignore the corresponding number of - initial lines from the input. - - If "skipblanks" is "true", blank lines in the input will be - ignored. - - If "use_mmap" is "true", the file specified by "source" is - memory mapped for potential speedups. Default is "true" except on - Windows. On Windows, you may want to specify "true" if the file - is large, and is only read once and not written to. - - If "ignore_invalid_chars" is "true", bytes in "source" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If "quotes" is "true", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying "dims" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If "comments" is "true", lines beginning with "comment_char" - and text following "comment_char" in any line are ignored. - ``` - """ readdlm - - @doc doc""" - ```rst - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - ``` - """ readdlm - - @doc doc""" - ```rst - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as "\n". - ``` - """ readdlm - - @doc doc""" - ```rst - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - ``` - """ readdlm - - @doc doc""" - ```rst - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". - ``` - """ readdlm - - @doc doc""" - ```rst - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - ``` - """ readdlm - - @doc doc""" - ```rst - writedlm(f, A, delim='\t') - - Write "A" (a vector, matrix or an iterable collection of iterable - rows) as text to "f" (either a filename string or an "IO" - stream) using the given delimeter "delim" (which defaults to tab, - but can be any printable Julia object, typically a "Char" or - "AbstractString"). - - For example, two vectors "x" and "y" of the same length can be - written as two columns of tab-delimited text to "f" by either - "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". - ``` - """ writedlm - - @doc doc""" - ```rst - readcsv(source, [T::Type]; options...) - - Equivalent to "readdlm" with "delim" set to comma. - ``` - """ readcsv - - @doc doc""" - ```rst - writecsv(filename, A) - - Equivalent to "writedlm" with "delim" set to comma. - ``` - """ writecsv - - @doc doc""" - ```rst - Base64EncodePipe(ostream) - - Returns a new write-only I/O stream, which converts any bytes - written to it into base64-encoded ASCII bytes written to - "ostream". Calling "close" on the "Base64Pipe" stream is - necessary to complete the encoding (but does not close - "ostream"). - ``` - """ Base64EncodePipe - - @doc doc""" - ```rst - Base64DecodePipe(istream) - - Returns a new read-only I/O stream, which decodes base64-encoded - data read from "istream". - ``` - """ Base64DecodePipe - - @doc doc""" - ```rst - base64encode(writefunc, args...) -base64encode(args...) - - Given a "write"-like function "writefunc", which takes an I/O - stream as its first argument, "base64(writefunc, args...)" calls - "writefunc" to write "args..." to a base64-encoded string, and - returns the string. "base64(args...)" is equivalent to - "base64(write, args...)": it converts its arguments into bytes - using the standard "write" functions and returns the - base64-encoded string. - ``` - """ base64encode - - @doc doc""" - ```rst - base64decode(string) - - Decodes the base64-encoded "string" and returns a - "Vector{UInt8}" of the decoded bytes. - ``` - """ base64decode - - @doc doc""" - ```rst - display(x) -display(d::Display, x) -display(mime, x) -display(d::Display, mime, x) - - Display "x" using the topmost applicable display in the display - stack, typically using the richest supported multimedia output for - "x", with plain-text "STDOUT" output as a fallback. The - "display(d, x)" variant attempts to display "x" on the given - display "d" only, throwing a "MethodError" if "d" cannot - display objects of this type. - - There are also two variants with a "mime" argument (a MIME type - string, such as ""image/png""), which attempt to display "x" - using the requested MIME type *only*, throwing a "MethodError" if - this type is not supported by either the display(s) or by "x". - With these variants, one can also supply the "raw" data in the - requested MIME type by passing "x::AbstractString" (for MIME - types with text-based storage, such as text/html or - application/postscript) or "x::Vector{UInt8}" (for binary MIME - types). - ``` - """ display - - @doc doc""" - ```rst - redisplay(x) -redisplay(d::Display, x) -redisplay(mime, x) -redisplay(d::Display, mime, x) - - By default, the "redisplay" functions simply call "display". - However, some display backends may override "redisplay" to modify - an existing display of "x" (if any). Using "redisplay" is - also a hint to the backend that "x" may be redisplayed several - times, and the backend may choose to defer the display until (for - example) the next interactive prompt. - ``` - """ redisplay - - @doc doc""" - ```rst - displayable(mime) -> Bool -displayable(d::Display, mime) -> Bool - - Returns a boolean value indicating whether the given "mime" type - (string) is displayable by any of the displays in the current - display stack, or specifically by the display "d" in the second - variant. - ``` - """ displayable - - @doc doc""" - ```rst - writemime(stream, mime, x) - - The "display" functions ultimately call "writemime" in order to - write an object "x" as a given "mime" type to a given I/O - "stream" (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - "T", it is only necessary to define a new "writemime" method - for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", - where "mime" is a MIME-type string and the function body calls - "write" (or similar) to write that representation of "x" to - "stream". (Note that the "MIME\""" notation only supports - literal strings; to construct "MIME" types in a more flexible - manner use "MIME{symbol("")}".) - - For example, if you define a "MyImage" type and know how to write - it to a PNG file, you could define a function "writemime(stream, - ::MIME"image/png", x::MyImage) = ...`" to allow your images to - be displayed on any PNG-capable "Display" (such as IJulia). As - usual, be sure to "import Base.writemime" in order to add new - methods to the built-in Julia function "writemime". - - Technically, the "MIME"mime"" macro defines a singleton type - for the given "mime" string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. - ``` - """ writemime - - @doc doc""" - ```rst - mimewritable(mime, x) - - Returns a boolean value indicating whether or not the object "x" - can be written as the given "mime" type. (By default, this is - determined automatically by the existence of the corresponding - "writemime" function for "typeof(x)".) - ``` - """ mimewritable - - @doc doc""" - ```rst - reprmime(mime, x) - - Returns an "AbstractString" or "Vector{UInt8}" containing the - representation of "x" in the requested "mime" type, as written - by "writemime" (throwing a "MethodError" if no appropriate - "writemime" is available). An "AbstractString" is returned for - MIME types with textual representations (such as ""text/html"" - or ""application/postscript""), whereas binary data is returned - as "Vector{UInt8}". (The function "istext(mime)" returns - whether or not Julia treats a given "mime" type as text.) - - As a special case, if "x" is an "AbstractString" (for textual - MIME types) or a "Vector{UInt8}" (for binary MIME types), the - "reprmime" function assumes that "x" is already in the - requested "mime" format and simply returns "x". - ``` - """ reprmime - - @doc doc""" - ```rst - stringmime(mime, x) - - Returns an "AbstractString" containing the representation of - "x" in the requested "mime" type. This is similar to - "reprmime" except that binary data is base64-encoded as an ASCII - string. - ``` - """ stringmime - - @doc doc""" - ```rst - pushdisplay(d::Display) - - Pushes a new display "d" on top of the global display-backend - stack. Calling "display(x)" or "display(mime, x)" will display - "x" on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a "MethodError"). - ``` - """ pushdisplay - - @doc doc""" - ```rst - popdisplay() -popdisplay(d::Display) - - Pop the topmost backend off of the display-backend stack, or the - topmost copy of "d" in the second variant. - ``` - """ popdisplay - - @doc doc""" - ```rst - TextDisplay(stream) - - Returns a "TextDisplay <: Display", which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same as - the way an object is printed in the Julia REPL.) - ``` - """ TextDisplay - - @doc doc""" - ```rst - istext(m::MIME) - - Determine whether a MIME type is text data. - ``` - """ istext - - @doc doc""" - ```rst - mmap_array(type, dims, stream[, offset]) - - Create an "Array" whose values are linked to a file, using - memory-mapping. This provides a convenient way of working with data - too large to fit in the computer's memory. - - The type determines how the bytes of the array are interpreted. - Note that the file must be stored in binary format, and no format - conversions are possible (this is a limitation of operating - systems, not Julia). - - "dims" is a tuple specifying the size of the array. - - The file is passed via the stream argument. When you initialize - the stream, use ""r"" for a "read-only" array, and ""w+"" - to create a new array used to write values to disk. - - Optionally, you can specify an offset (in bytes) if, for example, - you want to skip over a header in the file. The default value for - the offset is the current stream position. - - For example, the following code: - - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open("/tmp/mmap.bin", "w+") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) - - # Test by reading it back in - s = open("/tmp/mmap.bin") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) - - creates a "m"-by-"n" "Matrix{Int}", linked to the file - associated with stream "s". - - A more portable file would need to encode the word size---32 bit or - 64 bit---and endianness information in the header. In practice, - consider encoding binary data using standard formats like HDF5 - (which can be used with memory-mapping). - ``` - """ mmap_array - - @doc doc""" - ```rst - mmap_bitarray([type], dims, stream[, offset]) - - Create a "BitArray" whose values are linked to a file, using - memory-mapping; it has the same purpose, works in the same way, and - has the same arguments, as "mmap_array()", but the byte - representation is different. The "type" parameter is optional, - and must be "Bool" if given. - - **Example**: "B = mmap_bitarray((25,30000), s)" - - This would create a 25-by-30000 "BitArray", linked to the file - associated with stream "s". - ``` - """ mmap_bitarray - - @doc doc""" - ```rst - msync(array) - - Forces synchronization between the in-memory version of a memory- - mapped "Array" or "BitArray" and the on-disk version. - ``` - """ msync - - @doc doc""" - ```rst - connect([host], port) -> TcpSocket - - Connect to the host "host" on port "port" - ``` - """ connect - - @doc doc""" - ```rst - connect(path) -> Pipe - - Connect to the Named Pipe/Domain Socket at "path" - ``` - """ connect - - @doc doc""" - ```rst - listen([addr], port) -> TcpServer - - Listen on port on the address specified by "addr". By default - this listens on localhost only. To listen on all interfaces pass, - "IPv4(0)" or "IPv6(0)" as appropriate. - ``` - """ listen - - @doc doc""" - ```rst - listen(path) -> PipeServer - - Listens on/Creates a Named Pipe/Domain Socket - ``` - """ listen - - @doc doc""" - ```rst - getaddrinfo(host) - - Gets the IP address of the "host" (may have to do a DNS lookup) - ``` - """ getaddrinfo - - @doc doc""" - ```rst - parseip(addr) - - Parse a string specifying an IPv4 or IPv6 ip address. - ``` - """ parseip - - @doc doc""" - ```rst - IPv4(host::Integer) -> IPv4 - - Returns IPv4 object from ip address formatted as Integer - ``` - """ IPv4 - - @doc doc""" - ```rst - IPv6(host::Integer) -> IPv6 - - Returns IPv6 object from ip address formatted as Integer - ``` - """ IPv6 - - @doc doc""" - ```rst - nb_available(stream) - - Returns the number of bytes available for reading before a read - from this stream or buffer will block. - ``` - """ nb_available - - @doc doc""" - ```rst - accept(server[, client]) - - Accepts a connection on the given server and returns a connection - to the client. An uninitialized client stream may be provided, in - which case it will be used instead of creating a new stream. - ``` - """ accept - - @doc doc""" - ```rst - listenany(port_hint) -> (UInt16, TcpServer) - - Create a TcpServer on any port, using hint as a starting point. - Returns a tuple of the actual port that the server was created on - and the server itself. - ``` - """ listenany - - @doc doc""" - ```rst - watch_file(cb=false, s; poll=false) - - Watch file or directory "s" and run callback "cb" when "s" is - modified. The "poll" parameter specifies whether to use file - system event monitoring or polling. The callback function "cb" - should accept 3 arguments: "(filename, events, status)" where - "filename" is the name of file that was modified, "events" is - an object with boolean fields "changed" and "renamed" when - using file system event monitoring, or "readable" and - "writable" when using polling, and "status" is always 0. Pass - "false" for "cb" to not use a callback function. - ``` - """ watch_file - - @doc doc""" - ```rst - poll_fd(fd, seconds::Real; readable=false, writable=false) - - Poll a file descriptor fd for changes in the read or write - availability and with a timeout given by the second argument. If - the timeout is not needed, use "wait(fd)" instead. The keyword - arguments determine which of read and/or write status should be - monitored and at least one of them needs to be set to true. The - returned value is an object with boolean fields "readable", - "writable", and "timedout", giving the result of the polling. - ``` - """ poll_fd - - @doc doc""" - ```rst - poll_file(s, interval_seconds::Real, seconds::Real) - - Monitor a file for changes by polling every *interval_seconds* - seconds for *seconds* seconds. A return value of true indicates the - file changed, a return value of false indicates a timeout. - ``` - """ poll_file - - @doc doc""" - ```rst - bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - - Bind "socket" to the given "host:port". Note that *0.0.0.0* - will listen on all devices. - ``` - """ bind - - @doc doc""" - ```rst - send(socket::UDPSocket, host::IPv4, port::Integer, msg) - - Send "msg" over "socket to ``host:port". - ``` - """ send - - @doc doc""" - ```rst - recv(socket::UDPSocket) - - Read a UDP packet from the specified socket, and return the bytes - received. This call blocks. - ``` - """ recv - - @doc doc""" - ```rst - recvfrom(socket::UDPSocket) -> (address, data) - - Read a UDP packet from the specified socket, returning a tuple of - (address, data), where address will be either IPv4 or IPv6 as - appropriate. - ``` - """ recvfrom - - @doc doc""" - ```rst - setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - - Set UDP socket options. "multicast_loop": loopback for multicast - packets (default: true). "multicast_ttl": TTL for multicast - packets. "enable_broadcast": flag must be set to true if socket - will be used for broadcast messages, or else the UDP system will - return an access error (default: false). "ttl": Time-to-live of - packets sent on the socket. - ``` - """ setopt - - @doc doc""" - ```rst - ntoh(x) - - Converts the endianness of a value from Network byte order (big- - endian) to that used by the Host. - ``` - """ ntoh - - @doc doc""" - ```rst - hton(x) - - Converts the endianness of a value from that used by the Host to - Network byte order (big-endian). - ``` - """ hton - - @doc doc""" - ```rst - ltoh(x) - - Converts the endianness of a value from Little-endian to that used - by the Host. - ``` - """ ltoh - - @doc doc""" - ```rst - htol(x) - - Converts the endianness of a value from that used by the Host to - Little-endian. - ``` - """ htol - - @doc doc""" - ```rst - ENDIAN_BOM - - The 32-bit byte-order-mark indicates the native byte order of the - host machine. Little-endian machines will contain the value - 0x04030201. Big-endian machines will contain the value 0x01020304. - ``` - """ ENDIAN_BOM - - @doc doc""" - ```rst - malloc(size::Integer) -> Ptr{Void} - - Call "malloc" from the C standard library. - ``` - """ Libc.malloc - - @doc doc""" - ```rst - calloc(num::Integer, size::Integer) -> Ptr{Void} - - Call "calloc" from the C standard library. - ``` - """ Libc.calloc - - @doc doc""" - ```rst - realloc(addr::Ptr, size::Integer) -> Ptr{Void} - - Call "realloc" from the C standard library. - - See warning in the documentation for "free" regarding only using - this on memory originally obtained from "malloc". - ``` - """ Libc.realloc - - @doc doc""" - ```rst - free(addr::Ptr) - - Call "free" from the C standard library. Only use this on memory - obtained from "malloc", not on pointers retrieved from other C - libraries. "Ptr" objects obtained from C libraries should be - freed by the free functions defined in that library, to avoid - assertion failures if multiple "libc" libraries exist on the - system. - ``` - """ Libc.free - - @doc doc""" - ```rst - errno([code]) - - Get the value of the C library's "errno". If an argument is - specified, it is used to set the value of "errno". - - The value of "errno" is only valid immediately after a "ccall" - to a C library routine that sets it. Specifically, you cannot call - "errno" at the next prompt in a REPL, because lots of code is - executed between prompts. - ``` - """ Libc.errno - - @doc doc""" - ```rst - strerror(n) - - Convert a system call error code to a descriptive string - ``` - """ Libc.strerror - - @doc doc""" - ```rst - time(t::TmStruct) - - Converts a "TmStruct" struct to a number of seconds since the - epoch. - ``` - """ Libc.time - - @doc doc""" - ```rst - strftime([format], time) - - Convert time, given as a number of seconds since the epoch or a - "TmStruct", to a formatted string using the given format. - Supported formats are the same as those in the standard C library. - ``` - """ Libc.strftime - - @doc doc""" - ```rst - strptime([format], timestr) - - Parse a formatted time string into a "TmStruct" giving the - seconds, minute, hour, date, etc. Supported formats are the same as - those in the standard C library. On some platforms, timezones will - not be parsed correctly. If the result of this function will be - passed to "time" to convert it to seconds since the epoch, the - "isdst" field should be filled in manually. Setting it to "-1" - will tell the C library to use the current system settings to - determine the timezone. - ``` - """ Libc.strptime - - @doc doc""" - ```rst - TmStruct([seconds]) - - Convert a number of seconds since the epoch to broken-down format, - with fields "sec", "min", "hour", "mday", "month", - "year", "wday", "yday", and "isdst". - ``` - """ Libc.TmStruct - - @doc doc""" - ```rst - flush_cstdio() - - Flushes the C "stdout" and "stderr" streams (which may have - been written to by external C code). - ``` - """ Libc.flush_cstdio - - @doc doc""" - ```rst - msync(ptr, len[, flags]) - - Forces synchronization of the "mmap()"ped memory region from - "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a - combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See - your platform man page for specifics. The flags argument is not - valid on Windows. - - You may not need to call "msync", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. - ``` - """ Libc.msync - - @doc doc""" - ```rst - MS_ASYNC - - Enum constant for "msync()". See your platform man page for - details. (not available on Windows). - ``` - """ Libc.MS_ASYNC - - @doc doc""" - ```rst - MS_SYNC - - Enum constant for "msync()". See your platform man page for - details. (not available on Windows). - ``` - """ Libc.MS_SYNC - - @doc doc""" - ```rst - MS_INVALIDATE - - Enum constant for "msync()". See your platform man page for - details. (not available on Windows). - ``` - """ Libc.MS_INVALIDATE - - @doc doc""" - ```rst - mmap(len, prot, flags, fd, offset) - - Low-level interface to the "mmap" system call. See the man page. - ``` - """ Libc.mmap - - @doc doc""" - ```rst - munmap(pointer, len) - - Low-level interface for unmapping memory (see the man page). With - "mmap_array()" you do not need to call this directly; the memory - is unmapped for you when the array goes out of scope. - ``` - """ Libc.munmap - - @doc doc""" - ```rst - dlopen(libfile::AbstractString[, flags::Integer]) - - Load a shared library, returning an opaque handle. - - The optional flags argument is a bitwise-or of zero or more of - "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", - "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and - "RTLD_FIRST". These are converted to the corresponding flags of - the POSIX (and/or GNU libc and/or MacOS) dlopen command, if - possible, or are ignored if the specified functionality is not - available on the current platform. The default is - "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of - these flags, on POSIX platforms, is to specify - "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's - symbols to be available for usage in other shared libraries, in - situations where there are dependencies between shared libraries. - ``` - """ Libdl.dlopen - - @doc doc""" - ```rst - dlopen_e(libfile::AbstractString[, flags::Integer]) - - Similar to "dlopen()", except returns a "NULL" pointer instead - of raising errors. - ``` - """ Libdl.dlopen_e - - @doc doc""" - ```rst - RTLD_DEEPBIND - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_DEEPBIND - - @doc doc""" - ```rst - RTLD_FIRST - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_FIRST - - @doc doc""" - ```rst - RTLD_GLOBAL - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_GLOBAL - - @doc doc""" - ```rst - RTLD_LAZY - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_LAZY - - @doc doc""" - ```rst - RTLD_LOCAL - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_LOCAL - - @doc doc""" - ```rst - RTLD_NODELETE - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_NODELETE - - @doc doc""" - ```rst - RTLD_NOLOAD - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_NOLOAD - - @doc doc""" - ```rst - RTLD_NOW - - Enum constant for "dlopen()". See your platform man page for - details, if applicable. - ``` - """ Libdl.RTLD_NOW - - @doc doc""" - ```rst - dlsym(handle, sym) - - Look up a symbol from a shared library handle, return callable - function pointer on success. - ``` - """ Libdl.dlsym - - @doc doc""" - ```rst - dlsym_e(handle, sym) - - Look up a symbol from a shared library handle, silently return NULL - pointer on lookup failure. - ``` - """ Libdl.dlsym_e - - @doc doc""" - ```rst - dlclose(handle) - - Close shared library referenced by handle. - ``` - """ Libdl.dlclose - - @doc doc""" - ```rst - find_library(names, locations) - - Searches for the first library in "names" in the paths in the - "locations" list, "DL_LOAD_PATH", or system library paths (in - that order) which can successfully be dlopen'd. On success, the - return value will be one of the names (potentially prefixed by one - of the paths in locations). This string can be assigned to a - "global const" and used as the library name in future - "ccall"'s. On failure, it returns the empty string. - ``` - """ Libdl.find_library - - @doc doc""" - ```rst - DL_LOAD_PATH - - When calling "dlopen", the paths in this list will be searched - first, in order, before searching the system locations for a valid - library handle. - ``` - """ Libdl.DL_LOAD_PATH - - @doc doc""" - ```rst - *(A, B) - - Matrix multiplication - ``` - """ Base.(:(*)) - - @doc doc""" - ```rst - \(A, B) - - Matrix division using a polyalgorithm. For input matrices "A" and - "B", the result "X" is such that "A*X == B" when "A" is - square. The solver that is used depends upon the structure of - "A". A direct solver is used for upper- or lower triangular - "A". For Hermitian "A" (equivalent to symmetric "A" for non- - complex "A") the "BunchKaufman" factorization is used. - Otherwise an LU factorization is used. For rectangular "A" the - result is the minimum-norm least squares solution computed by a - pivoted QR factorization of "A" and a rank estimate of A based on - the R factor. - - When "A" is sparse, a similar polyalgorithm is used. For - indefinite matrices, the LDLt factorization does not use pivoting - during the numerical factorization and therefore the procedure can - fail even for invertible matrices. - ``` - """ Base.(:(\)) - - @doc doc""" - ```rst - dot(x, y) -⋅(x, y) - - Compute the dot product. For complex vectors, the first vector is - conjugated. - ``` - """ dot - - @doc doc""" - ```rst - vecdot(x, y) - - For any iterable containers "x" and "y" (including arrays of - any dimension) of numbers (or any element type for which "dot" is - defined), compute the Euclidean dot product (the sum of - "dot(x[i],y[i])") as if they were vectors. - ``` - """ vecdot - - @doc doc""" - ```rst - cross(x, y) -×(x, y) - - Compute the cross product of two 3-vectors. - ``` - """ cross - - @doc doc""" - ```rst - factorize(A) - - Compute a convenient factorization (including LU, Cholesky, Bunch- - Kaufman, LowerTriangular, UpperTriangular) of A, based upon the - type of the input matrix. The return value can then be reused for - efficient solving of multiple systems. For example: - "A=factorize(A); x=A\\b; y=A\\C". - ``` - """ factorize - - @doc doc""" - ```rst - full(F) - - Reconstruct the matrix "A" from the factorization - "F=factorize(A)". - ``` - """ full - - @doc doc""" - ```rst - lu(A) -> L, U, p - - Compute the LU factorization of "A", such that "A[p,:] = L*U". - ``` - """ lu - - @doc doc""" - ```rst - lufact(A[, pivot=Val{true}]) -> F - - Compute the LU factorization of "A". The return type of "F" - depends on the type of "A". In most cases, if "A" is a subtype - "S" of AbstractMatrix with an element type "T`" supporting - "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If - pivoting is chosen (default) the element type should also support - "abs" and "<". When "A" is sparse and have element of type - "Float32", "Float64", "Complex{Float32}", or - "Complex{Float64}" the return type is "UmfpackLU". Some - examples are shown in the table below. - - +-------------------------+---------------------------+----------------------------------------------+ - | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | - +-------------------------+---------------------------+----------------------------------------------+ - | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | - +-------------------------+---------------------------+----------------------------------------------+ - - The individual components of the factorization "F" can be - accessed by indexing: - - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - - +--------------------+--------+--------------------------+---------------+ - | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +--------------------+--------+--------------------------+---------------+ - | \"/\" | ✓ | | | - +--------------------+--------+--------------------------+---------------+ - | \"\\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"cond\" | ✓ | | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"det\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"size\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - ``` - """ lufact - - @doc doc""" - ```rst - lufact!(A) -> LU - - "lufact!" is the same as "lufact()", but saves space by - overwriting the input A, instead of creating a copy. For sparse - "A" the "nzval" field is not overwritten but the index fields, - "colptr" and "rowval" are decremented in place, converting from - 1-based indices to 0-based indices. - ``` - """ lufact! - - @doc doc""" - ```rst - chol(A[, LU]) -> F - - Compute the Cholesky factorization of a symmetric positive definite - matrix "A" and return the matrix "F". If "LU" is "Val{:U}" - (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If - "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" - and "A = F*F'". "LU" defaults to "Val{:U}". - ``` - """ chol - - @doc doc""" - ```rst - cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - - Compute the Cholesky factorization of a dense symmetric positive - (semi)definite matrix "A" and return either a "Cholesky" if - "pivot==Val{false}" or "CholeskyPivoted" if - "pivot==Val{true}". "LU" may be ":L" for using the lower part - or ":U" for the upper part. The default is to use ":U". The - triangular matrix can be obtained from the factorization "F" - with: "F[:L]" and "F[:U]". The following functions are - available for "Cholesky" objects: "size", "\", "inv", - "det". For "CholeskyPivoted" there is also defined a "rank". - If "pivot==Val{false}" a "PosDefException" exception is thrown - in case the matrix is not positive definite. The argument "tol" - determines the tolerance for determining the rank. For negative - values, the tolerance is the machine precision. - ``` - """ cholfact - - @doc doc""" - ```rst - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the Cholesky factorization of a sparse positive definite - matrix "A". A fill-reducing permutation is used. "F = - cholfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors - from "F", using "F[:L]". However, since pivoting is on by - default, the factorization is internally represented as "A == - P'*L*L'*P" with a permutation matrix "P"; using just "L" - without accounting for "P" will give incorrect answers. To - include the effects of permutation, it's typically preferable to - extact "combined" factors like "PtL = F[:PtL]" (the equivalent - of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. - ``` - """ cholfact - - @doc doc""" - ```rst - cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - - "cholfact!" is the same as "cholfact()", but saves space by - overwriting the input "A", instead of creating a copy. - "cholfact!" can also reuse the symbolic factorization from a - different matrix "F" with the same structure when used as: - "cholfact!(F::CholmodFactor, A)". - ``` - """ cholfact! - - @doc doc""" - ```rst - ldltfact(A) -> LDLtFactorization - - Compute a factorization of a positive definite matrix "A" such - that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular - matrix and "d" is a vector with non-negative elements. - ``` - """ ldltfact - - @doc doc""" - ```rst - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix "A". A fill-reducing permutation is used. "F = - ldltfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors from - "F", using "F[:L]". However, since pivoting is on by default, - the factorization is internally represented as "A == P'*L*D*L'*P" - with a permutation matrix "P"; using just "L" without - accounting for "P" will give incorrect answers. To include the - effects of permutation, it's typically preferable to extact - "combined" factors like "PtL = F[:PtL]" (the equivalent of - "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The - complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, - :DU, :PtLD, :DUP". - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. - ``` - """ ldltfact - - @doc doc""" - ```rst - qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - - Compute the (pivoted) QR factorization of "A" such that either - "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default - is to compute a thin factorization. Note that "R" is not extended - with zeros when the full "Q" is requested. - ``` - """ qr - - @doc doc""" - ```rst - qrfact(A[, pivot=Val{false}]) -> F - - Computes the QR factorization of "A". The return type of "F" - depends on the element type of "A" and whether pivoting is - specified (with "pivot==Val{true}"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - - "BlasFloat" refers to any of: "Float32", "Float64", - "Complex64" or "Complex128". - - The individual components of the factorization "F" can be - accessed by indexing: - - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:p]\" | pivot \"Vector\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - - The following functions are available for the "QR" objects: - "size", "\". When "A" is rectangular, "\" will return a - least squares solution and if the solution is not unique, the one - with smallest norm is returned. - - Multiplication with respect to either thin or full "Q" is - allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A - "Q" matrix can be converted into a regular matrix with "full()" - which has a named argument "thin". - - Note: "qrfact" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the "Q" and "R" matrices can be stored compactly rather - as two separate dense matrices.The data contained in "QR" or - "QRPivoted" can be used to construct the "QRPackedQ" type, - which is a compact representation of the rotation matrix: - - Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) - - where \tau_i is the scale factor and v_i is the projection - vector associated with the i^{th} Householder elementary - reflector.The data contained in "QRCompactWY" can be used to - construct the "QRCompactWYQ" type, which is a compact - representation of the rotation matrix - - Q = I + Y T Y^T - - where "Y" is m \times r lower trapezoidal and "T" is r - \times r upper triangular. The *compact WY* representation - [Schreiber1989] is not to be confused with the older, *WY* - representation [Bischof1987]. (The LAPACK documentation uses - "V" in lieu of "Y".) - - [Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 - - [Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 - ``` - """ qrfact - - @doc doc""" - ```rst - qrfact(A) -> SPQR.Factorization - - Compute the QR factorization of a sparse matrix "A". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with "\". The function calls the - C library SPQR and a few additional functions from the library are - wrapped but not exported. - ``` - """ qrfact - - @doc doc""" - ```rst - qrfact!(A[, pivot=Val{false}]) - - "qrfact!" is the same as "qrfact()" when A is a subtype of - "StridedMatrix", but saves space by overwriting the input "A", - instead of creating a copy. - ``` - """ qrfact! - - @doc doc""" - ```rst - full(QRCompactWYQ[, thin=true]) -> Matrix - - Converts an orthogonal or unitary matrix stored as a - "QRCompactWYQ" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. - - Optionally takes a "thin" Boolean argument, which if "true" - omits the columns that span the rows of "R" in the QR - factorization that are zero. The resulting matrix is the "Q" in a - thin QR factorization (sometimes called the reduced QR - factorization). If "false", returns a "Q" that spans all rows - of "R" in its corresponding QR factorization. - ``` - """ full - - @doc doc""" - ```rst - bkfact(A) -> BunchKaufman - - Compute the Bunch-Kaufman [Bunch1977] factorization of a real - symmetric or complex Hermitian matrix "A" and return a - "BunchKaufman" object. The following functions are available for - "BunchKaufman" objects: "size", "\", "inv", "issym", - "ishermitian". - ``` - """ bkfact - - @doc doc""" - ```rst - bkfact!(A) -> BunchKaufman - - "bkfact!" is the same as "bkfact()", but saves space by - overwriting the input "A", instead of creating a copy. - ``` - """ bkfact! - - @doc doc""" - ```rst - sqrtm(A) - - Compute the matrix square root of "A". If "B = sqrtm(A)", then - "B*B == A" within roundoff error. - - "sqrtm" uses a polyalgorithm, computing the matrix square root - using Schur factorizations ("schurfact()") unless it detects the - matrix to be Hermitian or real symmetric, in which case it computes - the matrix square root from an eigendecomposition ("eigfact()"). - In the latter situation for positive definite matrices, the matrix - square root has "Real" elements, otherwise it has "Complex" - elements. - ``` - """ sqrtm - - @doc doc""" - ```rst - eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - - Computes eigenvalues and eigenvectors of "A". See "eigfact()" - for details on the "balance" keyword argument. - - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) - - "eig" is a wrapper around "eigfact()", extracting all parts of - the factorization to a tuple; where possible, using "eigfact()" - is recommended. - ``` - """ eig - - @doc doc""" - ```rst - eig(A, B) -> D, V - - Computes generalized eigenvalues and vectors of "A" with respect - to "B". - - "eig" is a wrapper around "eigfact()", extracting all parts of - the factorization to a tuple; where possible, using "eigfact()" - is recommended. - ``` - """ eig - - @doc doc""" - ```rst - eigvals(A,[irange,][vl,][vu]) - - Returns the eigenvalues of "A". If "A" is "Symmetric", - "Hermitian" or "SymTridiagonal", it is possible to calculate - only a subset of the eigenvalues by specifying either a - "UnitRange" "irange" covering indices of the sorted - eigenvalues, or a pair "vl" and "vu" for the lower and upper - boundaries of the eigenvalues. - - For general non-symmetric matrices it is possible to specify how - the matrix is balanced before the eigenvector calculation. The - option "permute=true" permutes the matrix to become closer to - upper triangular, and "scale=true" scales the matrix by its - diagonal elements to make rows and columns more equal in norm. The - default is "true" for both options. - ``` - """ eigvals - - @doc doc""" - ```rst - eigmax(A) - - Returns the largest eigenvalue of "A". - ``` - """ eigmax - - @doc doc""" - ```rst - eigmin(A) - - Returns the smallest eigenvalue of "A". - ``` - """ eigmin - - @doc doc""" - ```rst - eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - - Returns a matrix "M" whose columns are the eigenvectors of "A". - (The "k"th eigenvector can be obtained from the slice "M[:, - k]".) The "permute" and "scale" keywords are the same as for - "eigfact()". - - For "SymTridiagonal" matrices, if the optional vector of - eigenvalues "eigvals" is specified, returns the specific - corresponding eigenvectors. - ``` - """ eigvecs - - @doc doc""" - ```rst - eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - - Computes the eigenvalue decomposition of "A", returning an - "Eigen" factorization object "F" which contains the eigenvalues - in "F[:values]" and the eigenvectors in the columns of the matrix - "F[:vectors]". (The "k"th eigenvector can be obtained from the - slice "F[:vectors][:, k]".) - - The following functions are available for "Eigen" objects: - "inv", "det". - - If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it - is possible to calculate only a subset of the eigenvalues by - specifying either a "UnitRange" "irange" covering indices of - the sorted eigenvalues or a pair "vl" and "vu" for the lower - and upper boundaries of the eigenvalues. - - For general nonsymmetric matrices it is possible to specify how the - matrix is balanced before the eigenvector calculation. The option - "permute=true" permutes the matrix to become closer to upper - triangular, and "scale=true" scales the matrix by its diagonal - elements to make rows and columns more equal in norm. The default - is "true" for both options. - ``` - """ eigfact - - @doc doc""" - ```rst - eigfact(A, B) -> GeneralizedEigen - - Computes the generalized eigenvalue decomposition of "A" and - "B", returning a "GeneralizedEigen" factorization object "F" - which contains the generalized eigenvalues in "F[:values]" and - the generalized eigenvectors in the columns of the matrix - "F[:vectors]". (The "k"th generalized eigenvector can be - obtained from the slice "F[:vectors][:, k]".) - ``` - """ eigfact - - @doc doc""" - ```rst - eigfact!(A[, B]) - - Same as "eigfact()", but saves space by overwriting the input - "A" (and "B"), instead of creating a copy. - ``` - """ eigfact! - - @doc doc""" - ```rst - hessfact(A) - - Compute the Hessenberg decomposition of "A" and return a - "Hessenberg" object. If "F" is the factorization object, the - unitary matrix can be accessed with "F[:Q]" and the Hessenberg - matrix with "F[:H]". When "Q" is extracted, the resulting type - is the "HessenbergQ" object, and may be converted to a regular - matrix with "full()". - ``` - """ hessfact - - @doc doc""" - ```rst - hessfact!(A) - - "hessfact!" is the same as "hessfact()", but saves space by - overwriting the input A, instead of creating a copy. - ``` - """ hessfact! - - @doc doc""" - ```rst - schurfact(A) -> Schur - - Computes the Schur factorization of the matrix "A". The (quasi) - triangular Schur factor can be obtained from the "Schur" object - "F" with either "F[:Schur]" or "F[:T]" and the - unitary/orthogonal Schur vectors can be obtained with - "F[:vectors]" or "F[:Z]" such that - "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" - can be obtained with "F[:values]". - ``` - """ schurfact - - @doc doc""" - ```rst - schurfact!(A) - - Computes the Schur factorization of "A", overwriting "A" in the - process. See "schurfact()" - ``` - """ schurfact! - - @doc doc""" - ```rst - schur(A) -> Schur[:T], Schur[:Z], Schur[:values] - - See "schurfact()" - ``` - """ schur - - @doc doc""" - ```rst - ordschur(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix "A=Q*T*Q'" - according to the logical array "select" returning a Schur object - "F". The selected eigenvalues appear in the leading diagonal of - "F[:Schur]" and the the corresponding leading columns of - "F[:vectors]" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via "select". - ``` - """ ordschur - - @doc doc""" - ```rst - ordschur!(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix "A=Q*T*Q'", - overwriting "Q" and "T" in the process. See "ordschur()" - ``` - """ ordschur! - - @doc doc""" - ```rst - ordschur(S, select) -> Schur - - Reorders the Schur factorization "S" of type "Schur". - ``` - """ ordschur - - @doc doc""" - ```rst - ordschur!(S, select) -> Schur - - Reorders the Schur factorization "S" of type "Schur", - overwriting "S" in the process. See "ordschur()" - ``` - """ ordschur! - - @doc doc""" - ```rst - schurfact(A, B) -> GeneralizedSchur - - Computes the Generalized Schur (or QZ) factorization of the - matrices "A" and "B". The (quasi) triangular Schur factors can - be obtained from the "Schur" object "F" with "F[:S]" and - "F[:T]", the left unitary/orthogonal Schur vectors can be - obtained with "F[:left]" or "F[:Q]" and the right - unitary/orthogonal Schur vectors can be obtained with "F[:right]" - or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and - "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of - "A" and "B" can be obtained with "F[:alpha]./F[:beta]". - ``` - """ schurfact - - @doc doc""" - ```rst - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - - See "schurfact()" - ``` - """ schur - - @doc doc""" - ```rst - ordschur(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix "(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" - and returns a GeneralizedSchur object "GS". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that "(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of - "A" and "B" can still be obtained with - "GS[:alpha]./GS[:beta]". - ``` - """ ordschur - - @doc doc""" - ```rst - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices "(S, T, Q, Z)" in the process. See - "ordschur()". - ``` - """ ordschur! - - @doc doc""" - ```rst - ordschur(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object. See "ordschur()". - ``` - """ ordschur - - @doc doc""" - ```rst - ordschur!(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - "ordschur()". - ``` - """ ordschur! - - @doc doc""" - ```rst - svdfact(A[, thin=true]) -> SVD - - Compute the Singular Value Decomposition (SVD) of "A" and return - an "SVD" object. "U", "S", "V" and "Vt" can be obtained - from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" - and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is - "true", an economy mode decomposition is returned. The algorithm - produces "Vt" and hence "Vt" is more efficient to extract than - "V". The default is to produce a thin decomposition. - ``` - """ svdfact - - @doc doc""" - ```rst - svdfact!(A[, thin=true]) -> SVD - - "svdfact!" is the same as "svdfact()", but saves space by - overwriting the input A, instead of creating a copy. If "thin" is - "true", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - ``` - """ svdfact! - - @doc doc""" - ```rst - svd(A[, thin=true]) -> U, S, V - - Wrapper around "svdfact" extracting all parts the factorization - to a tuple. Direct use of "svdfact" is therefore generally more - efficient. Computes the SVD of A, returning "U", vector "S", - and "V" such that "A == U*diagm(S)*V'". If "thin" is - "true", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - ``` - """ svd - - @doc doc""" - ```rst - svdvals(A) - - Returns the singular values of "A". - ``` - """ svdvals - - @doc doc""" - ```rst - svdvals!(A) - - Returns the singular values of "A", while saving space by - overwriting the input. - ``` - """ svdvals! - - @doc doc""" - ```rst - svdfact(A, B) -> GeneralizedSVD - - Compute the generalized SVD of "A" and "B", returning a - "GeneralizedSVD" Factorization object "F", such that "A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'". - ``` - """ svdfact - - @doc doc""" - ```rst - svd(A, B) -> U, V, Q, D1, D2, R0 - - Wrapper around "svdfact" extracting all parts the factorization - to a tuple. Direct use of "svdfact" is therefore generally more - efficient. The function returns the generalized SVD of "A" and - "B", returning "U", "V", "Q", "D1", "D2", and "R0" - such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". - ``` - """ svd - - @doc doc""" - ```rst - svdvals(A, B) - - Return only the singular values from the generalized singular value - decomposition of "A" and "B". - ``` - """ svdvals - - @doc doc""" - ```rst - triu(M) - - Upper triangle of a matrix. - ``` - """ triu - - @doc doc""" - ```rst - triu(M, k) - - Returns the upper triangle of "M" starting from the "k"th - superdiagonal. - ``` - """ triu - - @doc doc""" - ```rst - triu!(M) - - Upper triangle of a matrix, overwriting "M" in the process. - ``` - """ triu! - - @doc doc""" - ```rst - triu!(M, k) - - Returns the upper triangle of "M" starting from the "k"th - superdiagonal, overwriting "M" in the process. - ``` - """ triu! - - @doc doc""" - ```rst - tril(M) - - Lower triangle of a matrix. - ``` - """ tril - - @doc doc""" - ```rst - tril(M, k) - - Returns the lower triangle of "M" starting from the "k"th - subdiagonal. - ``` - """ tril - - @doc doc""" - ```rst - tril!(M) - - Lower triangle of a matrix, overwriting "M" in the process. - ``` - """ tril! - - @doc doc""" - ```rst - tril!(M, k) - - Returns the lower triangle of "M" starting from the "k"th - subdiagonal, overwriting "M" in the process. - ``` - """ tril! - - @doc doc""" - ```rst - diagind(M[, k]) - - A "Range" giving the indices of the "k"th diagonal of the - matrix "M". - ``` - """ diagind - - @doc doc""" - ```rst - diag(M[, k]) - - The "k"th diagonal of a matrix, as a vector. Use "diagm" to - construct a diagonal matrix. - ``` - """ diag - - @doc doc""" - ```rst - diagm(v[, k]) - - Construct a diagonal matrix and place "v" on the "k"th - diagonal. - ``` - """ diagm - - @doc doc""" - ```rst - scale(A, b) - ``` - """ scale - - @doc doc""" - ```rst - scale(b, A) - - Scale an array "A" by a scalar "b", returning a new array. - - If "A" is a matrix and "b" is a vector, then "scale(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), returning a new - array. - - Note: for large "A", "scale" can be much faster than "A .* b" - or "b .* A", due to the use of BLAS. - ``` - """ scale - - @doc doc""" - ```rst - scale!(A, b) - ``` - """ scale! - - @doc doc""" - ```rst - scale!(b, A) - - Scale an array "A" by a scalar "b", similar to "scale()" but - overwriting "A" in-place. - - If "A" is a matrix and "b" is a vector, then "scale!(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- - place on "A". - ``` - """ scale! - - @doc doc""" - ```rst - Tridiagonal(dl, d, du) - - Construct a tridiagonal matrix from the lower diagonal, diagonal, - and upper diagonal, respectively. The result is of type - "Tridiagonal" and provides efficient specialized linear solvers, - but may be converted into a regular matrix with "full()". - ``` - """ Tridiagonal - - @doc doc""" - ```rst - Bidiagonal(dv, ev, isupper) - - Constructs an upper ("isupper=true") or lower ("isupper=false") - bidiagonal matrix using the given diagonal ("dv") and off- - diagonal ("ev") vectors. The result is of type "Bidiagonal" - and provides efficient specialized linear solvers, but may be - converted into a regular matrix with "full()". - ``` - """ Bidiagonal - - @doc doc""" - ```rst - SymTridiagonal(d, du) - - Construct a real symmetric tridiagonal matrix from the diagonal and - upper diagonal, respectively. The result is of type - "SymTridiagonal" and provides efficient specialized eigensolvers, - but may be converted into a regular matrix with "full()". - ``` - """ SymTridiagonal - - @doc doc""" - ```rst - rank(M) - - Compute the rank of a matrix. - ``` - """ rank - - @doc doc""" - ```rst - norm(A[, p]) - - Compute the "p"-norm of a vector or the operator norm of a matrix - "A", defaulting to the "p=2"-norm. - - For vectors, "p" can assume any numeric value (even though not - all values produce a mathematically valid vector norm). In - particular, "norm(A, Inf)" returns the largest value in - "abs(A)", whereas "norm(A, -Inf)" returns the smallest. - - For matrices, valid values of "p" are "1", "2", or "Inf". - (Note that for sparse matrices, "p=2" is currently not - implemented.) Use "vecnorm()" to compute the Frobenius norm. - ``` - """ norm - - @doc doc""" - ```rst - vecnorm(A[, p]) - - For any iterable container "A" (including arrays of any - dimension) of numbers (or any element type for which "norm" is - defined), compute the "p"-norm (defaulting to "p=2") as if - "A" were a vector of the corresponding length. - - For example, if "A" is a matrix and "p=2", then this is - equivalent to the Frobenius norm. - ``` - """ vecnorm - - @doc doc""" - ```rst - cond(M[, p]) - - Condition number of the matrix "M", computed using the operator - "p"-norm. Valid values for "p" are "1", "2" (default), or - "Inf". - ``` - """ cond - - @doc doc""" - ```rst - condskeel(M[, x, p]) - - \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \right\Vert_p \\ - \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \left\vert x \right\vert - \right\Vert_p - - Skeel condition number \kappa_S of the matrix "M", optionally - with respect to the vector "x", as computed using the operator - "p"-norm. "p" is "Inf" by default, if not provided. Valid - values for "p" are "1", "2", or "Inf". - - This quantity is also known in the literature as the Bauer - condition number, relative condition number, or componentwise - relative condition number. - ``` - """ condskeel - - @doc doc""" - ```rst - trace(M) - - Matrix trace - ``` - """ trace - - @doc doc""" - ```rst - det(M) - - Matrix determinant - ``` - """ det - - @doc doc""" - ```rst - logdet(M) - - Log of matrix determinant. Equivalent to "log(det(M))", but may - provide increased accuracy and/or speed. - ``` - """ logdet - - @doc doc""" - ```rst - inv(M) - - Matrix inverse - ``` - """ inv - - @doc doc""" - ```rst - pinv(M[, tol]) - - Computes the Moore-Penrose pseudoinverse. - - For matrices "M" with floating point elements, it is convenient - to compute the pseudoinverse by inverting only singular values - above a given threshold, "tol". - - The optimal choice of "tol" varies both with the value of "M" - and the intended application of the pseudoinverse. The default - value of "tol" is - "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is - essentially machine epsilon for the real part of a matrix element - multiplied by the larger matrix dimension. For inverting dense ill- - conditioned matrices in a least-squares sense, "tol = - sqrt(eps(real(float(one(eltype(M))))))" is recommended. - - For more information, see [8859], [B96], [S84], [KY88]. - - [8859] Issue 8859, "Fix least squares", - https://github.com/JuliaLang/julia/pull/8859 - - [B96] Åke Björck, "Numerical Methods for Least Squares - Problems", SIAM Press, Philadelphia, 1996, "Other Titles in - Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 - - [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 - - [KY88] Konstantinos Konstantinides and Kung Yao, - "Statistical analysis of effective singular values in - matrix rank determination", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 - ``` - """ pinv - - @doc doc""" - ```rst - nullspace(M) - - Basis for nullspace of "M". - ``` - """ nullspace - - @doc doc""" - ```rst - repmat(A, n, m) - - Construct a matrix by repeating the given matrix "n" times in - dimension 1 and "m" times in dimension 2. - ``` - """ repmat - - @doc doc""" - ```rst - repeat(A, inner = Int[], outer = Int[]) - - Construct an array by repeating the entries of "A". The i-th - element of "inner" specifies the number of times that the - individual entries of the i-th dimension of "A" should be - repeated. The i-th element of "outer" specifies the number of - times that a slice along the i-th dimension of "A" should be - repeated. - ``` - """ repeat - - @doc doc""" - ```rst - kron(A, B) - - Kronecker tensor product of two vectors or two matrices. - ``` - """ kron - - @doc doc""" - ```rst - blkdiag(A...) - - Concatenate matrices block-diagonally. Currently only implemented - for sparse matrices. - ``` - """ blkdiag - - @doc doc""" - ```rst - linreg(x, y) -> [a; b] - - Linear Regression. Returns "a" and "b" such that "a+b*x" is - the closest line to the given points "(x,y)". In other words, - this function determines parameters "[a, b]" that minimize the - squared error between "y" and "a+b*x". - - **Example**: - - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, "o") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression - ``` - """ linreg - - @doc doc""" - ```rst - linreg(x, y, w) - - Weighted least-squares linear regression. - ``` - """ linreg - - @doc doc""" - ```rst - expm(A) - - Matrix exponential. - ``` - """ expm - - @doc doc""" - ```rst - lyap(A, C) - - Computes the solution "X" to the continuous Lyapunov equation - "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real - part and no two eigenvalues are negative complex conjugates of each - other. - ``` - """ lyap - - @doc doc""" - ```rst - sylvester(A, B, C) - - Computes the solution "X" to the Sylvester equation "AX + XB + C - = 0", where "A", "B" and "C" have compatible dimensions and - "A" and "-B" have no eigenvalues with equal real part. - ``` - """ sylvester - - @doc doc""" - ```rst - issym(A) -> Bool - - Test whether a matrix is symmetric. - ``` - """ issym - - @doc doc""" - ```rst - isposdef(A) -> Bool - - Test whether a matrix is positive definite. - ``` - """ isposdef - - @doc doc""" - ```rst - isposdef!(A) -> Bool - - Test whether a matrix is positive definite, overwriting "A" in - the processes. - ``` - """ isposdef! - - @doc doc""" - ```rst - istril(A) -> Bool - - Test whether a matrix is lower triangular. - ``` - """ istril - - @doc doc""" - ```rst - istriu(A) -> Bool - - Test whether a matrix is upper triangular. - ``` - """ istriu - - @doc doc""" - ```rst - isdiag(A) -> Bool - - Test whether a matrix is diagonal. - ``` - """ isdiag - - @doc doc""" - ```rst - ishermitian(A) -> Bool - - Test whether a matrix is Hermitian. - ``` - """ ishermitian - - @doc doc""" - ```rst - transpose(A) - - The transposition operator (".'"). - ``` - """ transpose - - @doc doc""" - ```rst - transpose!(dest, src) - - Transpose array "src" and store the result in the preallocated - array "dest", which should have a size corresponding to - "(size(src,2),size(src,1))". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. - ``` - """ transpose! - - @doc doc""" - ```rst - ctranspose(A) - - The conjugate transposition operator ("'"). - ``` - """ ctranspose - - @doc doc""" - ```rst - ctranspose!(dest, src) - - Conjugate transpose array "src" and store the result in the - preallocated array "dest", which should have a size corresponding - to "(size(src,2),size(src,1))". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. - ``` - """ ctranspose! - - @doc doc""" - ```rst - eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - - Computes eigenvalues "d" of "A" using Lanczos or Arnoldi - iterations for real symmetric or general nonsymmetric matrices - respectively. If "B" is provided, the generalized eigenproblem is - solved. - - The following keyword arguments are supported: - * "nev": Number of eigenvalues - - * "ncv": Number of Krylov vectors used in the computation; - should satisfy - - "nev+1 <= ncv <= n" for real symmetric problems and - "nev+2 <= ncv <= n" for other problems, where "n" is - the size of the input matrix "A". The default is "ncv = - max(20,2*nev+1)". Note that these restrictions limit the - input matrix "A" to be of dimension at least 2. - - * "which": type of eigenvalues to compute. See the note - below. - - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \"which\" | type of eigenvalues | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LM\" | eigenvalues of largest magnitude (default) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SM\" | eigenvalues of smallest magnitude | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LR\" | eigenvalues of largest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SR\" | eigenvalues of smallest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - - * "tol": tolerance (tol \le 0.0 defaults to - "DLAMCH('EPS')") - - * "maxiter": Maximum number of iterations (default = 300) - - * "sigma": Specifies the level shift used in inverse - iteration. If "nothing" (default), defaults to ordinary - (forward) iterations. Otherwise, find eigenvalues close to - "sigma" using shift and invert iterations. - - * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) - if "true" - - * "v0": starting vector from which to start the iterations - - "eigs" returns the "nev" requested eigenvalues in "d", the - corresponding Ritz vectors "v" (only if "ritzvec=true"), the - number of converged eigenvalues "nconv", the number of iterations - "niter" and the number of matrix vector multiplications - "nmult", as well as the final residual vector "resid". - - Note: The "sigma" and "which" keywords interact: the - description of eigenvalues searched for by "which" do _not_ - necessarily refer to the eigenvalues of "A", but rather the - linear operator constructed by the specification of the iteration - mode implied by "sigma". - - +-----------------+------------------------------------+------------------------------------+ - | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | - +-----------------+------------------------------------+------------------------------------+ - | \"nothing\" | ordinary (forward) | A | - +-----------------+------------------------------------+------------------------------------+ - | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | - +-----------------+------------------------------------+------------------------------------+ - ``` - """ eigs - - @doc doc""" - ```rst - svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - - "svds" computes largest singular values "s" of "A" using - Lanczos or Arnoldi iterations. Uses "eigs()" underneath. - - Inputs are: - * "A": Linear operator. It can either subtype of - "AbstractArray" (e.g., sparse matrix) or duck typed. For - duck typing "A" has to support "size(A)", "eltype(A)", - "A * vector" and "A' * vector". - - * "nsv": Number of singular values. - - * "ritzvec": Whether to return the left and right singular - vectors "left_sv" and "right_sv", default is "true". If - "false" the singular vectors are omitted from the output. - - * "tol": tolerance, see "eigs()". - - * "maxiter": Maximum number of iterations, see "eigs()". - - **Example**: - - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) - ``` - """ svds - - @doc doc""" - ```rst - peakflops(n; parallel=false) - - "peakflops" computes the peak flop rate of the computer by using - double precision "Base.LinAlg.BLAS.gemm!()". By default, if no - arguments are specified, it multiplies a matrix of size "n x n", - where "n = 2000". If the underlying BLAS is using multiple - threads, higher flop rates are realized. The number of BLAS threads - can be set with "blas_set_num_threads(n)". - - If the keyword argument "parallel" is set to "true", - "peakflops" is run in parallel on all the worker processors. The - flop rate of the entire parallel computer is returned. When running - in parallel, only 1 BLAS thread is used. The argument "n" still - refers to the size of the problem that is solved on each processor. - ``` - """ peakflops - - @doc doc""" - ```rst - dot(n, X, incx, Y, incy) - - Dot product of two vectors consisting of "n" elements of array - "X" with stride "incx" and "n" elements of array "Y" with - stride "incy". - ``` - """ Base.LinAlg.BLAS.dot - - @doc doc""" - ```rst - dotu(n, X, incx, Y, incy) - - Dot function for two complex vectors. - ``` - """ Base.LinAlg.BLAS.dotu - - @doc doc""" - ```rst - dotc(n, X, incx, U, incy) - - Dot function for two complex vectors conjugating the first vector. - ``` - """ Base.LinAlg.BLAS.dotc - - @doc doc""" - ```rst - blascopy!(n, X, incx, Y, incy) - - Copy "n" elements of array "X" with stride "incx" to array - "Y" with stride "incy". Returns "Y". - ``` - """ Base.LinAlg.BLAS.blascopy! - - @doc doc""" - ```rst - nrm2(n, X, incx) - - 2-norm of a vector consisting of "n" elements of array "X" with - stride "incx". - ``` - """ Base.LinAlg.BLAS.nrm2 - - @doc doc""" - ```rst - asum(n, X, incx) - - sum of the absolute values of the first "n" elements of array - "X" with stride "incx". - ``` - """ Base.LinAlg.BLAS.asum - - @doc doc""" - ```rst - axpy!(a, X, Y) - - Overwrite "Y" with "a*X + Y". Returns "Y". - ``` - """ Base.LinAlg.BLAS.axpy! - - @doc doc""" - ```rst - scal!(n, a, X, incx) - - Overwrite "X" with "a*X". Returns "X". - ``` - """ Base.LinAlg.BLAS.scal! - - @doc doc""" - ```rst - scal(n, a, X, incx) - - Returns "a*X". - ``` - """ Base.LinAlg.BLAS.scal - - @doc doc""" - ```rst - ger!(alpha, x, y, A) - - Rank-1 update of the matrix "A" with vectors "x" and "y" as - "alpha*x*y' + A". - ``` - """ Base.LinAlg.BLAS.ger! - - @doc doc""" - ```rst - syr!(uplo, alpha, x, A) - - Rank-1 update of the symmetric matrix "A" with vector "x" as - "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of - "A" is updated ('L' for lower triangle). Returns "A". - ``` - """ Base.LinAlg.BLAS.syr! - - @doc doc""" - ```rst - syrk!(uplo, trans, alpha, A, beta, C) - - Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + - beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" - is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is - updated ('L' for lower triangle). Returns "C". - ``` - """ Base.LinAlg.BLAS.syrk! - - @doc doc""" - ```rst - syrk(uplo, trans, alpha, A) - - Returns either the upper triangle or the lower triangle, according - to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", - according to "trans" ('N' or 'T'). - ``` - """ Base.LinAlg.BLAS.syrk - - @doc doc""" - ```rst - her!(uplo, alpha, x, A) - - Methods for complex arrays only. Rank-1 update of the Hermitian - matrix "A" with vector "x" as "alpha*x*x' + A". When - "uplo" is 'U' the upper triangle of "A" is updated ('L' for - lower triangle). Returns "A". - ``` - """ Base.LinAlg.BLAS.her! - - @doc doc""" - ```rst - herk!(uplo, trans, alpha, A, beta, C) - - Methods for complex arrays only. Rank-k update of the Hermitian - matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" - according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' - the upper triangle of "C" is updated ('L' for lower triangle). - Returns "C". - ``` - """ Base.LinAlg.BLAS.herk! - - @doc doc""" - ```rst - herk(uplo, trans, alpha, A) - - Methods for complex arrays only. Returns either the upper triangle - or the lower triangle, according to "uplo" ('U' or 'L'), of - "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or - 'T'). - ``` - """ Base.LinAlg.BLAS.herk - - @doc doc""" - ```rst - gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - - Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + - beta*y" according to "trans" ('N' or 'T'). The matrix "A" is - a general band matrix of dimension "m" by "size(A,2)" with - "kl" sub-diagonals and "ku" super-diagonals. Returns the - updated "y". - ``` - """ Base.LinAlg.BLAS.gbmv! - - @doc doc""" - ```rst - gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - - Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' - or 'T'). The matrix "A" is a general band matrix of dimension - "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- - diagonals. - ``` - """ Base.LinAlg.BLAS.gbmv - - @doc doc""" - ```rst - sbmv!(uplo, k, alpha, A, x, beta, y) - - Update vector "y" as "alpha*A*x + beta*y" where "A" is a a - symmetric band matrix of order "size(A,2)" with "k" super- - diagonals stored in the argument "A". The storage layout for - "A" is described the reference BLAS module, level-2 BLAS at - http://www.netlib.org/lapack/explore-html/. - - Returns the updated "y". - ``` - """ Base.LinAlg.BLAS.sbmv! - - @doc doc""" - ```rst - sbmv(uplo, k, alpha, A, x) - - Returns "alpha*A*x" where "A" is a symmetric band matrix of - order "size(A,2)" with "k" super-diagonals stored in the - argument "A". - ``` - """ Base.LinAlg.BLAS.sbmv - - @doc doc""" - ```rst - sbmv(uplo, k, A, x) - - Returns "A*x" where "A" is a symmetric band matrix of order - "size(A,2)" with "k" super-diagonals stored in the argument - "A". - ``` - """ Base.LinAlg.BLAS.sbmv - - @doc doc""" - ```rst - gemm!(tA, tB, alpha, A, B, beta, C) - - Update "C" as "alpha*A*B + beta*C" or the other three variants - according to "tA" (transpose "A") and "tB". Returns the - updated "C". - ``` - """ Base.LinAlg.BLAS.gemm! - - @doc doc""" - ```rst - gemm(tA, tB, alpha, A, B) - - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". - ``` - """ Base.LinAlg.BLAS.gemm - - @doc doc""" - ```rst - gemm(tA, tB, A, B) - - Returns "A*B" or the other three variants according to "tA" - (transpose "A") and "tB". - ``` - """ Base.LinAlg.BLAS.gemm - - @doc doc""" - ```rst - gemv!(tA, alpha, A, x, beta, y) - - Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + - beta*y" according to "tA" (transpose "A"). Returns the updated - "y". - ``` - """ Base.LinAlg.BLAS.gemv! - - @doc doc""" - ```rst - gemv(tA, alpha, A, x) - - Returns "alpha*A*x" or "alpha*A'x" according to "tA" - (transpose "A"). - ``` - """ Base.LinAlg.BLAS.gemv - - @doc doc""" - ```rst - gemv(tA, A, x) - - Returns "A*x" or "A'x" according to "tA" (transpose "A"). - ``` - """ Base.LinAlg.BLAS.gemv - - @doc doc""" - ```rst - symm!(side, ul, alpha, A, B, beta, C) - - Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" - according to "side". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. Returns the updated "C". - ``` - """ Base.LinAlg.BLAS.symm! - - @doc doc""" - ```rst - symm(side, ul, alpha, A, B) - - Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" - is assumed to be symmetric. Only the "ul" triangle of "A" is - used. - ``` - """ Base.LinAlg.BLAS.symm - - @doc doc""" - ```rst - symm(side, ul, A, B) - - Returns "A*B" or "B*A" according to "side". "A" is assumed - to be symmetric. Only the "ul" triangle of "A" is used. - ``` - """ Base.LinAlg.BLAS.symm - - @doc doc""" - ```rst - symm(tA, tB, alpha, A, B) - - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". - ``` - """ Base.LinAlg.BLAS.symm - - @doc doc""" - ```rst - symv!(ul, alpha, A, x, beta, y) - - Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed - to be symmetric. Only the "ul" triangle of "A" is used. - Returns the updated "y". - ``` - """ Base.LinAlg.BLAS.symv! - - @doc doc""" - ```rst - symv(ul, alpha, A, x) - - Returns "alpha*A*x". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. - ``` - """ Base.LinAlg.BLAS.symv - - @doc doc""" - ```rst - symv(ul, A, x) - - Returns "A*x". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. - ``` - """ Base.LinAlg.BLAS.symv - - @doc doc""" - ```rst - trmm!(side, ul, tA, dA, alpha, A, B) - - Update "B" as "alpha*A*B" or one of the other three variants - determined by "side" (A on left or right) and "tA" (transpose - A). Only the "ul" triangle of "A" is used. "dA" indicates if - "A" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated "B". - ``` - """ Base.LinAlg.BLAS.trmm! - - @doc doc""" - ```rst - trmm(side, ul, tA, dA, alpha, A, B) - - Returns "alpha*A*B" or one of the other three variants determined - by "side" (A on left or right) and "tA" (transpose A). Only the - "ul" triangle of "A" is used. "dA" indicates if "A" is - unit-triangular (the diagonal is assumed to be all ones). - ``` - """ Base.LinAlg.BLAS.trmm - - @doc doc""" - ```rst - trsm!(side, ul, tA, dA, alpha, A, B) - - Overwrite "B" with the solution to "A*X = alpha*B" or one of - the other three variants determined by "side" (A on left or right - of "X") and "tA" (transpose A). Only the "ul" triangle of - "A" is used. "dA" indicates if "A" is unit-triangular (the - diagonal is assumed to be all ones). Returns the updated "B". - ``` - """ Base.LinAlg.BLAS.trsm! - - @doc doc""" - ```rst - trsm(side, ul, tA, dA, alpha, A, B) - - Returns the solution to "A*X = alpha*B" or one of the other three - variants determined by "side" (A on left or right of "X") and - "tA" (transpose A). Only the "ul" triangle of "A" is used. - "dA" indicates if "A" is unit-triangular (the diagonal is - assumed to be all ones). - ``` - """ Base.LinAlg.BLAS.trsm - - @doc doc""" - ```rst - trmv!(side, ul, tA, dA, alpha, A, b) - - Update "b" as "alpha*A*b" or one of the other three variants - determined by "side" (A on left or right) and "tA" (transpose - A). Only the "ul" triangle of "A" is used. "dA" indicates if - "A" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated "b". - ``` - """ Base.LinAlg.BLAS.trmv! - - @doc doc""" - ```rst - trmv(side, ul, tA, dA, alpha, A, b) - - Returns "alpha*A*b" or one of the other three variants determined - by "side" (A on left or right) and "tA" (transpose A). Only the - "ul" triangle of "A" is used. "dA" indicates if "A" is - unit-triangular (the diagonal is assumed to be all ones). - ``` - """ Base.LinAlg.BLAS.trmv - - @doc doc""" - ```rst - trsv!(ul, tA, dA, A, b) - - Overwrite "b" with the solution to "A*x = b" or one of the - other two variants determined by "tA" (transpose A) and "ul" - (triangle of "A" used). "dA" indicates if "A" is unit- - triangular (the diagonal is assumed to be all ones). Returns the - updated "b". - ``` - """ Base.LinAlg.BLAS.trsv! - - @doc doc""" - ```rst - trsv(ul, tA, dA, A, b) - - Returns the solution to "A*x = b" or one of the other two - variants determined by "tA" (transpose A) and "ul" (triangle of - "A" is used.) "dA" indicates if "A" is unit-triangular (the - diagonal is assumed to be all ones). - ``` - """ Base.LinAlg.BLAS.trsv - - @doc doc""" - ```rst - blas_set_num_threads(n) - - Set the number of threads the BLAS library should use. - ``` - """ Base.LinAlg.BLAS.blas_set_num_threads - - @doc doc""" - ```rst - I - - An object of type "UniformScaling", representing an identity - matrix of any size. - ``` - """ Base.LinAlg.BLAS.I - - @doc doc""" - ```rst - -(x) - - Unary minus operator. - ``` - """ - - - @doc doc""" - ```rst - +(x, y...) - - Addition operator. "x+y+z+..." calls this function with all - arguments, i.e. "+(x, y, z, ...)". - ``` - """ + - - @doc doc""" - ```rst - -(x, y) - - Subtraction operator. - ``` - """ - - - @doc doc""" - ```rst - *(x, y...) - - Multiplication operator. "x*y*z*..." calls this function with all - arguments, i.e. "*(x, y, z, ...)". - ``` - """ Base.(:(*)) - - @doc doc""" - ```rst - /(x, y) - - Right division operator: multiplication of "x" by the inverse of - "y" on the right. Gives floating-point results for integer - arguments. - ``` - """ Base.(:(/)) - - @doc doc""" - ```rst - \(x, y) - - Left division operator: multiplication of "y" by the inverse of - "x" on the left. Gives floating-point results for integer - arguments. - ``` - """ Base.(:(\)) - - @doc doc""" - ```rst - ^(x, y) - - Exponentiation operator. - ``` - """ Base.(:(^)) - - @doc doc""" - ```rst - .+(x, y) - - Element-wise addition operator. - ``` - """ Base.(:(.+)) - - @doc doc""" - ```rst - .-(x, y) - - Element-wise subtraction operator. - ``` - """ Base.(:(.-)) - - @doc doc""" - ```rst - .*(x, y) - - Element-wise multiplication operator. - ``` - """ Base.(:(.*)) - - @doc doc""" - ```rst - ./(x, y) - - Element-wise right division operator. - ``` - """ Base.(:(./)) - - @doc doc""" - ```rst - .\(x, y) - - Element-wise left division operator. - ``` - """ Base.(:(.\)) - - @doc doc""" - ```rst - .^(x, y) - - Element-wise exponentiation operator. - ``` - """ Base.(:(.^)) - - @doc doc""" - ```rst - fma(x, y, z) - - Computes "x*y+z" without rounding the intermediate result - "x*y". On some systems this is significantly more expensive than - "x*y+z". "fma" is used to improve accuracy in certain - algorithms. See "muladd". - ``` - """ fma - - @doc doc""" - ```rst - muladd(x, y, z) - - Combined multiply-add, computes "x*y+z" in an efficient manner. - This may on some systems be equivalent to "x*y+z", or to - "fma(x,y,z)". "muladd" is used to improve performance. See - "fma". - ``` - """ muladd - - @doc doc""" - ```rst - div(x, y) -÷(x, y) - - The quotient from Euclidean division. Computes "x/y", truncated - to an integer. - ``` - """ div - - @doc doc""" - ```rst - fld(x, y) - - Largest integer less than or equal to "x/y". - ``` - """ fld - - @doc doc""" - ```rst - cld(x, y) - - Smallest integer larger than or equal to "x/y". - ``` - """ cld - - @doc doc""" - ```rst - mod(x, y) - - Modulus after division, returning in the range [0,``y``), if "y" - is positive, or ("y",0] if "y" is negative. - ``` - """ mod - - @doc doc""" - ```rst - mod2pi(x) - - Modulus after division by 2pi, returning in the range [0,2pi). - - This function computes a floating point representation of the - modulus after division by numerically exact 2pi, and is therefore - not exactly the same as mod(x,2pi), which would compute the modulus - of x relative to division by the floating-point number 2pi. - ``` - """ mod2pi - - @doc doc""" - ```rst - rem(x, y) -%(x, y) - - Remainder from Euclidean division, returning a value of the same - sign as``x``, and smaller in magnitude than "y". This value is - always exact. - ``` - """ rem - - @doc doc""" - ```rst - divrem(x, y) - - The quotient and remainder from Euclidean division. Equivalent to - "(x÷y, x%y)". - ``` - """ divrem - - @doc doc""" - ```rst - fldmod(x, y) - - The floored quotient and modulus after division. Equivalent to - "(fld(x,y), mod(x,y))". - ``` - """ fldmod - - @doc doc""" - ```rst - mod1(x, m) - - Modulus after division, returning in the range (0,m] - ``` - """ mod1 - - @doc doc""" - ```rst - rem1(x, m) - - Remainder after division, returning in the range (0,m] - ``` - """ rem1 - - @doc doc""" - ```rst - //(num, den) - - Divide two integers or rational numbers, giving a "Rational" - result. - ``` - """ Base.(:(//)) - - @doc doc""" - ```rst - rationalize([Type=Int], x; tol=eps(x)) - - Approximate floating point number "x" as a Rational number with - components of the given integer type. The result will differ from - "x" by no more than "tol". - ``` - """ rationalize - - @doc doc""" - ```rst - num(x) - - Numerator of the rational representation of "x" - ``` - """ num - - @doc doc""" - ```rst - den(x) - - Denominator of the rational representation of "x" - ``` - """ den - - @doc doc""" - ```rst - <<(x, n) - - Left bit shift operator. - ``` - """ Base.(:(<<)) - - @doc doc""" - ```rst - >>(x, n) - - Right bit shift operator, preserving the sign of "x". - ``` - """ Base.(:(>>)) - - @doc doc""" - ```rst - >>>(x, n) - - Unsigned right bit shift operator. - ``` - """ Base.(:(>>>)) - - @doc doc""" - ```rst - :(start[, step], stop) - - Range operator. "a:b" constructs a range from "a" to "b" with - a step size of 1, and "a:s:b" is similar but uses a step size of - "s". These syntaxes call the function "colon". The colon is - also used in indexing to select whole dimensions. - ``` - """ : - - @doc doc""" - ```rst - colon(start[, step], stop) - - Called by ":" syntax for constructing ranges. - ``` - """ colon - - @doc doc""" - ```rst - range(start[, step], length) - - Construct a range by length, given a starting value and optional - step (defaults to 1). - ``` - """ range - - @doc doc""" - ```rst - ==(x, y) - - Generic equality operator, giving a single "Bool" result. Falls - back to "===". Should be implemented for all types with a notion - of equality, based on the abstract value that an instance - represents. For example, all numeric types are compared by numeric - value, ignoring type. Strings are compared as sequences of - characters, ignoring encoding. - - Follows IEEE semantics for floating-point numbers. - - Collections should generally implement "==" by calling "==" - recursively on all contents. - - New numeric types should implement this function for two arguments - of the new type, and handle comparison to other types via promotion - rules where possible. - ``` - """ Base.(:(==)) - - @doc doc""" - ```rst - !=(x, y) -≠(x, y) - - Not-equals comparison operator. Always gives the opposite answer as - "==". New types should generally not implement this, and rely on - the fallback definition "!=(x,y) = !(x==y)" instead. - ``` - """ Base.(:(!=)) - - @doc doc""" - ```rst - ===(x, y) -≡(x, y) - - See the "is()" operator - ``` - """ Base.(:(===)) - - @doc doc""" - ```rst - !==(x, y) -≢(x, y) - - Equivalent to "!is(x, y)" - ``` - """ Base.(:(!==)) - - @doc doc""" - ```rst - <(x, y) - - Less-than comparison operator. New numeric types should implement - this function for two arguments of the new type. Because of the - behavior of floating-point NaN values, "<" implements a partial - order. Types with a canonical partial order should implement "<", - and types with a canonical total order should implement "isless". - ``` - """ Base.(:(<)) - - @doc doc""" - ```rst - <=(x, y) -≤(x, y) - - Less-than-or-equals comparison operator. - ``` - """ Base.(:(<=)) - - @doc doc""" - ```rst - >(x, y) - - Greater-than comparison operator. Generally, new types should - implement "<" instead of this function, and rely on the fallback - definition ">(x,y) = y)) - - @doc doc""" - ```rst - >=(x, y) -≥(x, y) - - Greater-than-or-equals comparison operator. - ``` - """ Base.(:(>=)) - - @doc doc""" - ```rst - .==(x, y) - - Element-wise equality comparison operator. - ``` - """ Base.(:(.==)) - - @doc doc""" - ```rst - .!=(x, y) -.≠(x, y) - - Element-wise not-equals comparison operator. - ``` - """ Base.(:(.!=)) - - @doc doc""" - ```rst - .<(x, y) - - Element-wise less-than comparison operator. - ``` - """ Base.(:(.<)) - - @doc doc""" - ```rst - .<=(x, y) -.≤(x, y) - - Element-wise less-than-or-equals comparison operator. - ``` - """ Base.(:(.<=)) - - @doc doc""" - ```rst - .>(x, y) - - Element-wise greater-than comparison operator. - ``` - """ Base.(:(.>)) - - @doc doc""" - ```rst - .>=(x, y) -.≥(x, y) - - Element-wise greater-than-or-equals comparison operator. - ``` - """ Base.(:(.>=)) - - @doc doc""" - ```rst - cmp(x, y) - - Return -1, 0, or 1 depending on whether "x" is less than, equal - to, or greater than "y", respectively. Uses the total order - implemented by "isless". For floating-point numbers, uses "<" - but throws an error for unordered arguments. - ``` - """ cmp - - @doc doc""" - ```rst - ~(x) - - Bitwise not - ``` - """ ~ - - @doc doc""" - ```rst - &(x, y) - - Bitwise and - ``` - """ & - - @doc doc""" - ```rst - |(x, y) - - Bitwise or - ``` - """ Base.(:(|)) - - @doc doc""" - ```rst - \$(x, y) - - Bitwise exclusive or - ``` - """ $ - - @doc doc""" - ```rst - !(x) - - Boolean not - ``` - """ ! - - @doc doc""" - ```rst - A_ldiv_Bc(a, b) - - Matrix operator A \ B^H - ``` - """ A_ldiv_Bc - - @doc doc""" - ```rst - A_ldiv_Bt(a, b) - - Matrix operator A \ B^T - ``` - """ A_ldiv_Bt - - @doc doc""" - ```rst - A_mul_B!(Y, A, B) -> Y - - Calculates the matrix-matrix or matrix-vector product *A B* and - stores the result in *Y*, overwriting the existing value of *Y*. - - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); - - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 - ``` - """ A_mul_B! +doc""" + find(f, A) + +Return a vector of the linear indexes of `A` where `f` returns +true. +""" +find - @doc doc""" - ```rst - A_mul_Bc(...) +doc""" + findn(A) - Matrix operator A B^H - ``` - """ A_mul_Bc +Return a vector of indexes for each dimension giving the locations +of the non-zeros in `A` (determined by `A[i]!=0`). +""" +findn - @doc doc""" - ```rst - A_mul_Bt(...) +doc""" + findnz(A) + +Return a tuple `(I, J, V)` where `I` and `J` are the row and +column indexes of the non-zero values in matrix `A`, and `V` is +a vector of the non-zero values. +""" +findnz - Matrix operator A B^T - ``` - """ A_mul_Bt +doc""" + findfirst(A) + +Return the index of the first non-zero value in `A` (determined +by `A[i]!=0`). +""" +findfirst - @doc doc""" - ```rst - A_rdiv_Bc(...) +doc""" + findfirst(A, v) + +Return the index of the first element equal to `v` in `A`. +""" +findfirst + +doc""" + findfirst(predicate, A) - Matrix operator A / B^H - ``` - """ A_rdiv_Bc +Return the index of the first element of `A` for which +""" +findfirst - @doc doc""" - ```rst - A_rdiv_Bt(a, b) +doc""" + findlast(A) - Matrix operator A / B^T - ``` - """ A_rdiv_Bt +Return the index of the last non-zero value in `A` (determined by +""" +findlast - @doc doc""" - ```rst - Ac_ldiv_B(...) +doc""" + findlast(A, v) - Matrix operator A^H \ B - ``` - """ Ac_ldiv_B +Return the index of the last element equal to `v` in `A`. +""" +findlast - @doc doc""" - ```rst - Ac_ldiv_Bc(...) +doc""" + findlast(predicate, A) - Matrix operator A^H \ B^H - ``` - """ Ac_ldiv_Bc +Return the index of the last element of `A` for which +""" +findlast - @doc doc""" - ```rst - Ac_mul_B(...) +doc""" + findnext(A, i) - Matrix operator A^H B - ``` - """ Ac_mul_B +Find the next index >= `i` of a non-zero element of `A`, or +""" +findnext - @doc doc""" - ```rst - Ac_mul_Bc(...) +doc""" + findnext(predicate, A, i) - Matrix operator A^H B^H - ``` - """ Ac_mul_Bc +Find the next index >= `i` of an element of `A` for which +""" +findnext - @doc doc""" - ```rst - Ac_rdiv_B(a, b) +doc""" + findnext(A, v, i) - Matrix operator A^H / B - ``` - """ Ac_rdiv_B +Find the next index >= `i` of an element of `A` equal to `v` +""" +findnext - @doc doc""" - ```rst - Ac_rdiv_Bc(a, b) +doc""" + findprev(A, i) - Matrix operator A^H / B^H - ``` - """ Ac_rdiv_Bc +Find the previous index <= `i` of a non-zero element of `A`, or +0 if not found. +""" +findprev - @doc doc""" - ```rst - At_ldiv_B(...) +doc""" + findprev(predicate, A, i) - Matrix operator A^T \ B - ``` - """ At_ldiv_B +Find the previous index <= `i` of an element of `A` for which +""" +findprev - @doc doc""" - ```rst - At_ldiv_Bt(...) +doc""" + findprev(A, v, i) - Matrix operator A^T \ B^T - ``` - """ At_ldiv_Bt +Find the previous index <= `i` of an element of `A` equal to +""" +findprev - @doc doc""" - ```rst - At_mul_B(...) +doc""" + permutedims(A, perm) - Matrix operator A^T B - ``` - """ At_mul_B +Permute the dimensions of array `A`. `perm` is a vector +specifying a permutation of length `ndims(A)`. This is a +generalization of transpose for multi-dimensional arrays. Transpose +is equivalent to `permutedims(A, [2,1])`. +""" +permutedims - @doc doc""" - ```rst - At_mul_Bt(...) +doc""" + ipermutedims(A, perm) - Matrix operator A^T B^T - ``` - """ At_mul_Bt +Like `permutedims()`, except the inverse of the given permutation +is applied. +""" +ipermutedims - @doc doc""" - ```rst - At_rdiv_B(a, b) +doc""" + permutedims!(dest, src, perm) - Matrix operator A^T / B - ``` - """ At_rdiv_B +Permute the dimensions of array `src` and store the result in the +array `dest`. `perm` is a vector specifying a permutation of +length `ndims(src)`. The preallocated array `dest` should have +in-place permutation is supported and unexpected results will +happen if *src* and *dest* have overlapping memory regions. +""" +permutedims! - @doc doc""" - ```rst - At_rdiv_Bt(a, b) +doc""" + squeeze(A, dims) - Matrix operator A^T / B^T - ``` - """ At_rdiv_Bt +Remove the dimensions specified by `dims` from array `A`. +Elements of `dims` must be unique and within the range +""" +squeeze - @doc doc""" - ```rst - isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) +doc""" + vec(Array) -> Vector - Inexact equality comparison - behaves slightly different depending - on types of input args: +Vectorize an array using column-major convention. +""" +vec - * For "FloatingPoint" numbers, "isapprox" returns "true" if - "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". +doc""" + promote_shape(s1, s2) - * For "Integer" and "Rational" numbers, "isapprox" returns - "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. - If one of "x" and "y" is "FloatingPoint", the other is - promoted, and the method above is called instead. +Check two array shapes for compatibility, allowing trailing +singleton dimensions, and return whichever shape has more +dimensions. +""" +promote_shape - * For "Complex" numbers, the distance in the complex plane is - compared, using the same criterion as above. +doc""" + checkbounds(array, indexes...) - For default tolerance arguments, "maxeps = max(eps(abs(x)), - eps(abs(y)))". - ``` - """ isapprox +Throw an error if the specified indexes are not in bounds for the +given array. +""" +checkbounds - @doc doc""" - ```rst - sin(x) +doc""" + randsubseq(A, p) -> Vector - Compute sine of "x", where "x" is in radians - ``` - """ sin +Return a vector consisting of a random subsequence of the given +array `A`, where each element of `A` is included (in order) +with independent probability `p`. (Complexity is linear in +small and `A` is large.) Technically, this process is known as +""" +randsubseq - @doc doc""" - ```rst - cos(x) +doc""" + randsubseq!(S, A, p) - Compute cosine of "x", where "x" is in radians - ``` - """ cos +Like `randsubseq`, but the results are stored in `S` (which is +resized as needed). +""" +randsubseq! + +doc""" + cumprod(A[, dim]) + +Cumulative product along a dimension `dim` (defaults to 1). See +also `cumprod!()` to use a preallocated output array, both for +performance and to control the precision of the output (e.g. to +avoid overflow). +""" +cumprod - @doc doc""" - ```rst - tan(x) +doc""" + cumprod!(B, A[, dim]) - Compute tangent of "x", where "x" is in radians - ``` - """ tan +Cumulative product of `A` along a dimension, storing the result +in `B`. The dimension defaults to 1. +""" +cumprod! + +doc""" + cumsum(A[, dim]) + +Cumulative sum along a dimension `dim` (defaults to 1). See also +performance and to control the precision of the output (e.g. to +avoid overflow). +""" +cumsum + +doc""" + cumsum!(B, A[, dim]) + +Cumulative sum of `A` along a dimension, storing the result in +""" +cumsum! + +doc""" + cumsum_kbn(A[, dim]) + +Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier +compensated summation algorithm for additional accuracy. The +dimension defaults to 1. +""" +cumsum_kbn + +doc""" + cummin(A[, dim]) + +Cumulative minimum along a dimension. The dimension defaults to 1. +""" +cummin - @doc doc""" - ```rst - sind(x) +doc""" + cummax(A[, dim]) + +Cumulative maximum along a dimension. The dimension defaults to 1. +""" +cummax + +doc""" + diff(A[, dim]) + +Finite difference operator of matrix or vector. +""" +diff + +doc""" + gradient(F[, h]) + +Compute differences along vector `F`, using `h` as the spacing +between points. The default spacing is one. +""" +gradient + +doc""" + rot180(A) + +Rotate matrix `A` 180 degrees. +""" +rot180 + +doc""" + rot180(A, k) - Compute sine of "x", where "x" is in degrees - ``` - """ sind +Rotate matrix `A` 180 degrees an integer `k` number of times. +If `k` is even, this is equivalent to a `copy`. +""" +rot180 - @doc doc""" - ```rst - cosd(x) +doc""" + rotl90(A) - Compute cosine of "x", where "x" is in degrees - ``` - """ cosd +Rotate matrix `A` left 90 degrees. +""" +rotl90 - @doc doc""" - ```rst - tand(x) +doc""" + rotl90(A, k) - Compute tangent of "x", where "x" is in degrees - ``` - """ tand - - @doc doc""" - ```rst - sinpi(x) - - Compute \sin(\pi x) more accurately than "sin(pi*x)", - especially for large "x". - ``` - """ sinpi +Rotate matrix `A` left 90 degrees an integer `k` number of +times. If `k` is zero or a multiple of four, this is equivalent +to a `copy`. +""" +rotl90 - @doc doc""" - ```rst - cospi(x) +doc""" + rotr90(A) - Compute \cos(\pi x) more accurately than "cos(pi*x)", - especially for large "x". - ``` - """ cospi - - @doc doc""" - ```rst - sinh(x) - - Compute hyperbolic sine of "x" - ``` - """ sinh - - @doc doc""" - ```rst - cosh(x) - - Compute hyperbolic cosine of "x" - ``` - """ cosh - - @doc doc""" - ```rst - tanh(x) - - Compute hyperbolic tangent of "x" - ``` - """ tanh - - @doc doc""" - ```rst - asin(x) - - Compute the inverse sine of "x", where the output is in radians - ``` - """ asin - - @doc doc""" - ```rst - acos(x) - - Compute the inverse cosine of "x", where the output is in radians - ``` - """ acos - - @doc doc""" - ```rst - atan(x) - - Compute the inverse tangent of "x", where the output is in - radians - ``` - """ atan - - @doc doc""" - ```rst - atan2(y, x) - - Compute the inverse tangent of "y/x", using the signs of both - "x" and "y" to determine the quadrant of the return value. - ``` - """ atan2 - - @doc doc""" - ```rst - asind(x) - - Compute the inverse sine of "x", where the output is in degrees - ``` - """ asind - - @doc doc""" - ```rst - acosd(x) - - Compute the inverse cosine of "x", where the output is in degrees - ``` - """ acosd - - @doc doc""" - ```rst - atand(x) - - Compute the inverse tangent of "x", where the output is in - degrees - ``` - """ atand - - @doc doc""" - ```rst - sec(x) - - Compute the secant of "x", where "x" is in radians - ``` - """ sec - - @doc doc""" - ```rst - csc(x) - - Compute the cosecant of "x", where "x" is in radians - ``` - """ csc - - @doc doc""" - ```rst - cot(x) - - Compute the cotangent of "x", where "x" is in radians - ``` - """ cot - - @doc doc""" - ```rst - secd(x) - - Compute the secant of "x", where "x" is in degrees - ``` - """ secd - - @doc doc""" - ```rst - cscd(x) - - Compute the cosecant of "x", where "x" is in degrees - ``` - """ cscd - - @doc doc""" - ```rst - cotd(x) - - Compute the cotangent of "x", where "x" is in degrees - ``` - """ cotd - - @doc doc""" - ```rst - asec(x) - - Compute the inverse secant of "x", where the output is in radians - ``` - """ asec - - @doc doc""" - ```rst - acsc(x) - - Compute the inverse cosecant of "x", where the output is in - radians - ``` - """ acsc - - @doc doc""" - ```rst - acot(x) - - Compute the inverse cotangent of "x", where the output is in - radians - ``` - """ acot - - @doc doc""" - ```rst - asecd(x) - - Compute the inverse secant of "x", where the output is in degrees - ``` - """ asecd - - @doc doc""" - ```rst - acscd(x) - - Compute the inverse cosecant of "x", where the output is in - degrees - ``` - """ acscd - - @doc doc""" - ```rst - acotd(x) - - Compute the inverse cotangent of "x", where the output is in - degrees - ``` - """ acotd - - @doc doc""" - ```rst - sech(x) - - Compute the hyperbolic secant of "x" - ``` - """ sech - - @doc doc""" - ```rst - csch(x) - - Compute the hyperbolic cosecant of "x" - ``` - """ csch - - @doc doc""" - ```rst - coth(x) - - Compute the hyperbolic cotangent of "x" - ``` - """ coth - - @doc doc""" - ```rst - asinh(x) - - Compute the inverse hyperbolic sine of "x" - ``` - """ asinh - - @doc doc""" - ```rst - acosh(x) - - Compute the inverse hyperbolic cosine of "x" - ``` - """ acosh - - @doc doc""" - ```rst - atanh(x) - - Compute the inverse hyperbolic tangent of "x" - ``` - """ atanh - - @doc doc""" - ```rst - asech(x) - - Compute the inverse hyperbolic secant of "x" - ``` - """ asech - - @doc doc""" - ```rst - acsch(x) - - Compute the inverse hyperbolic cosecant of "x" - ``` - """ acsch - - @doc doc""" - ```rst - acoth(x) - - Compute the inverse hyperbolic cotangent of "x" - ``` - """ acoth - - @doc doc""" - ```rst - sinc(x) - - Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. - ``` - """ sinc - - @doc doc""" - ```rst - cosc(x) - - Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq - 0, and 0 if x = 0. This is the derivative of "sinc(x)". - ``` - """ cosc - - @doc doc""" - ```rst - deg2rad(x) - - Convert "x" from degrees to radians - ``` - """ deg2rad - - @doc doc""" - ```rst - rad2deg(x) - - Convert "x" from radians to degrees - ``` - """ rad2deg - - @doc doc""" - ```rst - hypot(x, y) - - Compute the \sqrt{x^2+y^2} avoiding overflow and underflow - ``` - """ hypot - - @doc doc""" - ```rst - log(x) - - Compute the natural logarithm of "x". Throws "DomainError" for - negative "Real" arguments. Use complex negative arguments to - obtain complex results. - - There is an experimental variant in the "Base.Math.JuliaLibm" - module, which is typically faster and more accurate. - ``` - """ log - - @doc doc""" - ```rst - log(b, x) - - Compute the base "b" logarithm of "x". Throws "DomainError" - for negative "Real" arguments. - ``` - """ log - - @doc doc""" - ```rst - log2(x) - - Compute the logarithm of "x" to base 2. Throws "DomainError" - for negative "Real" arguments. - ``` - """ log2 - - @doc doc""" - ```rst - log10(x) - - Compute the logarithm of "x" to base 10. Throws "DomainError" - for negative "Real" arguments. - ``` - """ log10 - - @doc doc""" - ```rst - log1p(x) - - Accurate natural logarithm of "1+x". Throws "DomainError" for - "Real" arguments less than -1. +Rotate matrix `A` right 90 degrees. +""" +rotr90 - There is an experimental variant in the "Base.Math.JuliaLibm" - module, which is typically faster and more accurate. - ``` - """ log1p - - @doc doc""" - ```rst - frexp(val) - - Return "(x,exp)" such that "x" has a magnitude in the interval - "[1/2, 1)" or 0, and val = x \times 2^{exp}. - ``` - """ frexp +doc""" + rotr90(A, k) - @doc doc""" - ```rst - exp(x) +Rotate matrix `A` right 90 degrees an integer `k` number of +times. If `k` is zero or a multiple of four, this is equivalent +to a `copy`. +""" +rotr90 - Compute e^x - ``` - """ exp +doc""" + reducedim(f, A, dims[, initial]) - @doc doc""" - ```rst - exp2(x) +Reduce 2-argument function `f` along dimensions of `A`. +The associativity of the reduction is implementation-dependent; if +you need a particular associativity, e.g. left-to-right, you should +write your own loop. See documentation for `reduce`. +""" +reducedim - Compute 2^x - ``` - """ exp2 +doc""" + mapreducedim(f, op, A, dims[, initial]) - @doc doc""" - ```rst - exp10(x) +Evaluates to the same as *reducedim(op, map(f, A), dims, +f(initial))*, but is generally faster because the intermediate +array is avoided. +""" +mapreducedim - Compute 10^x - ``` - """ exp10 +doc""" + mapslices(f, A, dims) - @doc doc""" - ```rst - ldexp(x, n) +Transform the given dimensions of array `A` using function `f`. +where the colons go in this expression. The results are +concatenated along the remaining dimensions. For example, if +""" +mapslices - Compute x \times 2^n - ``` - """ ldexp +doc""" + sum_kbn(A) - @doc doc""" - ```rst - modf(x) +Returns the sum of all array elements, using the Kahan-Babuska- +Neumaier compensated summation algorithm for additional accuracy. +""" +sum_kbn - Return a tuple (fpart,ipart) of the fractional and integral parts - of a number. Both parts have the same sign as the argument. - ``` - """ modf +doc""" + cartesianmap(f, dims) - @doc doc""" - ```rst - expm1(x) +Given a `dims` tuple of integers `(m, n, ...)`, call `f` on +all combinations of integers in the ranges `1:m`, `1:n`, etc. +""" +cartesianmap - Accurately compute e^x-1 - ``` - """ expm1 +doc""" + nthperm(v, k) - @doc doc""" - ```rst - round([T], x[, digits[, base]][, r::RoundingMode]) +Compute the kth lexicographic permutation of a vector. +""" +nthperm - "round(x)" rounds "x" to an integer value according to the - default rounding mode (see "get_rounding()"), returning a value - of the same type as "x". By default ("RoundNearest"), this will - round to the nearest integer, with ties (fractional values of 0.5) - being rounded to the even integer. +doc""" + nthperm(p) - julia> round(1.7) - 2.0 +Return the `k` that generated permutation `p`. Note that +""" +nthperm - julia> round(1.5) - 2.0 +doc""" + nthperm!(v, k) - julia> round(2.5) - 2.0 +In-place version of `nthperm()`. +""" +nthperm! - The optional "RoundingMode" argument will change how the number - gets rounded. +doc""" + randperm([rng], n) - "round(T, x, [r::RoundingMode])" converts the result to type - "T", throwing an "InexactError" if the value is not - representable. +Construct a random permutation of length `n`. The optional +Numbers*. +""" +randperm - "round(x, digits)" rounds to the specified number of digits after - the decimal place (or before if negative). "round(x, digits, - base)" rounds using a base other than 10. +doc""" + invperm(v) + +Return the inverse permutation of v. +""" +invperm + +doc""" + isperm(v) -> Bool + +Returns true if v is a valid permutation. +""" +isperm + +doc""" + permute!(v, p) + +Permute vector `v` in-place, according to permutation `p`. No +checking is done to verify that `p` is a permutation. +To return a new permutation, use `v[p]`. Note that this is +generally faster than `permute!(v,p)` for large vectors. +""" +permute! + +doc""" + ipermute!(v, p) + +Like permute!, but the inverse of the given permutation is applied. +""" +ipermute! + +doc""" + randcycle([rng], n) + +Construct a random cyclic permutation of length `n`. The optional +Numbers*. +""" +randcycle + +doc""" + shuffle([rng], v) + +Return a randomly permuted copy of `v`. The optional `rng` +argument specifies a random number generator, see *Random Numbers*. +""" +shuffle + +doc""" + shuffle!([rng], v) + +In-place version of `shuffle()`. +""" +shuffle! + +doc""" + reverse(v[, start=1[, stop=length(v)]]) + +Return a copy of `v` reversed from start to stop. +""" +reverse + +doc""" + reverseind(v, i) + +Given an index `i` in `reverse(v)`, return the corresponding +index in `v` so that `v[reverseind(v,i)] == reverse(v)[i]`. +string.) +""" +reverseind + +doc""" + reverse!(v[, start=1[, stop=length(v)]]) -> v + +In-place version of `reverse()`. +""" +reverse! + +doc""" + combinations(array, n) + +Generate all combinations of `n` elements from an indexable +object. Because the number of combinations can be very large, this +function returns an iterator object. Use +combinations. +""" +combinations + +doc""" + permutations(array) + +Generate all permutations of an indexable object. Because the +number of permutations can be very large, this function returns an +iterator object. Use `collect(permutations(array))` to get an +array of all permutations. +""" +permutations + +doc""" + partitions(n) + +Generate all integer arrays that sum to `n`. Because the number +of partitions can be very large, this function returns an iterator +object. Use `collect(partitions(n))` to get an array of all +partitions. The number of partitions to generate can be efficiently +computed using `length(partitions(n))`. +""" +partitions + +doc""" + partitions(n, m) + +Generate all arrays of `m` integers that sum to `n`. Because +the number of partitions can be very large, this function returns +an iterator object. Use `collect(partitions(n,m))` to get an +array of all partitions. The number of partitions to generate can +be efficiently computed using `length(partitions(n,m))`. +""" +partitions + +doc""" + partitions(array) + +Generate all set partitions of the elements of an array, +represented as arrays of arrays. Because the number of partitions +can be very large, this function returns an iterator object. Use +The number of partitions to generate can be efficiently computed +using `length(partitions(array))`. +""" +partitions + +doc""" + partitions(array, m) + +Generate all set partitions of the elements of an array into +exactly m subsets, represented as arrays of arrays. Because the +number of partitions can be very large, this function returns an +iterator object. Use `collect(partitions(array,m))` to get an +array of all partitions. The number of partitions into m subsets is +equal to the Stirling number of the second kind and can be +efficiently computed using `length(partitions(array,m))`. +""" +partitions + +doc""" + bitpack(A::AbstractArray{T, N}) -> BitArray + +Converts a numeric array to a packed boolean array +""" +bitpack + +doc""" + bitunpack(B::BitArray{N}) -> Array{Bool,N} + +Converts a packed boolean array to an array of booleans +""" +bitunpack + +doc""" + flipbits!(B::BitArray{N}) -> BitArray{N} + +Performs a bitwise not operation on B. See *~ operator*. +""" +flipbits! + +doc""" + rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a left rotation operation on `src` and put the result +into `dest`. +""" +rol! + +doc""" + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a left rotation operation on B. +""" +rol! + +doc""" + rol(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a left rotation operation. +""" +rol + +doc""" + ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a right rotation operation on `src` and put the result +into `dest`. +""" +ror! + +doc""" + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a right rotation operation on B. +""" +ror! + +doc""" + ror(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a right rotation operation. +""" +ror + +doc""" + sparse(I, J, V[, m, n, combine]) + +Create a sparse matrix `S` of dimensions `m x n` such that +combine duplicates. If `m` and `n` are not specified, they are +set to `max(I)` and `max(J)` respectively. If the `combine` +function is not supplied, duplicates are added by default. +""" +sparse + +doc""" + sparsevec(I, V[, m, combine]) + +Create a sparse matrix `S` of size `m x 1` such that `S[I[k]] +which defaults to `+` if it is not provided. In julia, sparse +vectors are really just sparse matrices with one column. Given +Julia's Compressed Sparse Columns (CSC) storage format, a sparse +column matrix with one column is sparse, whereas a sparse row +matrix with one row ends up being dense. +""" +sparsevec + +doc""" + sparsevec(D::Dict[, m]) + +Create a sparse matrix of size `m x 1` where the row values are +keys from the dictionary, and the nonzero values are the values +from the dictionary. +""" +sparsevec + +doc""" + issparse(S) + +Returns `true` if `S` is sparse, and `false` otherwise. +""" +issparse + +doc""" + sparse(A) + +Convert an AbstractMatrix `A` into a sparse matrix. +""" +sparse + +doc""" + sparsevec(A) + +Convert a dense vector `A` into a sparse matrix of size `m x +1`. In julia, sparse vectors are really just sparse matrices with +one column. +""" +sparsevec + +doc""" + full(S) + +Convert a sparse matrix `S` into a dense matrix. +""" +full + +doc""" + nnz(A) + +Returns the number of stored (filled) elements in a sparse matrix. +""" +nnz + +doc""" + spzeros(m, n) + +Create a sparse matrix of size `m x n`. This sparse matrix will +not contain any nonzero values. No storage will be allocated for +nonzero values during construction. +""" +spzeros + +doc""" + spones(S) + +Create a sparse matrix with the same structure as that of `S`, +but with every nonzero element having the value `1.0`. +""" +spones + +doc""" + speye(type, m[, n]) + +Create a sparse identity matrix of specified type of size `m x +m`. In case `n` is supplied, create a sparse identity matrix of +size `m x n`. +""" +speye + +doc""" + spdiagm(B, d[, m, n]) + +Construct a sparse diagonal matrix. `B` is a tuple of vectors +containing the diagonals and `d` is a tuple containing the +positions of the diagonals. In the case the input contains only one +diagonaly, `B` can be a vector (instead of a tuple) and `d` can +be the diagonal position (instead of a tuple), defaulting to 0 +resulting sparse matrix. +""" +spdiagm + +doc""" + sprand([rng], m, n, p[, rfn]) + +Create a random `m` by `n` sparse matrix, in which the +probability of any element being nonzero is independently given by +by `rfn`. The uniform distribution is used in case `rfn` is not +specified. The optional `rng` argument specifies a random number +generator, see *Random Numbers*. +""" +sprand + +doc""" + sprandn(m, n, p) + +Create a random `m` by `n` sparse matrix with the specified +nonzero values are sampled from the normal distribution. +""" +sprandn + +doc""" + sprandbool(m, n, p) + +Create a random `m` by `n` sparse boolean matrix with the +specified (independent) probability `p` of any entry being +""" +sprandbool + +doc""" + etree(A[, post]) + +Compute the elimination tree of a symmetric sparse matrix `A` +from `triu(A)` and, optionally, its post-ordering permutation. +""" +etree + +doc""" + symperm(A, p) + +Return the symmetric permutation of A, which is `A[p,p]`. A +should be symmetric and sparse, where only the upper triangular +part of the matrix is stored. This algorithm ignores the lower +triangular part of the matrix. Only the upper triangular part of +the result is returned as well. +""" +symperm + +doc""" + nonzeros(A) + +Return a vector of the structural nonzero values in sparse matrix +matrix. The returned vector points directly to the internal nonzero +storage of `A`, and any modifications to the returned vector will +mutate `A` as well. See `rowvals(A)` and `nzrange(A, col)`. +""" +nonzeros + +doc""" + rowvals(A) + +Return a vector of the row indices of `A`, and any modifications +to the returned vector will mutate `A` as well. Given the +internal storage format of sparse matrices, providing access to how +the row indices are stored internally can be useful in conjuction +with iterating over structural nonzero values. See `nonzeros(A)` +and `nzrange(A, col)`. +""" +rowvals + +doc""" + nzrange(A, col) + +Return the range of indices to the structural nonzero values of a +sparse matrix column. In conjunction with `nonzeros(A)` and +matrix +""" +nzrange + +doc""" + exit([code]) + +Quit (or control-D at the prompt). The default exit code is zero, +indicating that the processes completed successfully. +""" +exit + +doc""" + quit() + +Quit the program indicating that the processes completed +successfully. This function calls `exit(0)` (see `exit()`). +""" +quit + +doc""" + atexit(f) + +Register a zero-argument function to be called at exit. +""" +atexit + +doc""" + atreplinit(f) + +Register a one-argument function to be called before the REPL +interface is initialized in interactive sessions; this is useful to +customize the interface. The argument of `f` is the REPL object. +This function should be called from within the `.juliarc.jl` +initialization file. +""" +atreplinit + +doc""" + isinteractive() -> Bool + +Determine whether Julia is running an interactive session. +""" +isinteractive + +doc""" + whos([Module,] [pattern::Regex]) + +Print information about exported global variables in a module, +optionally restricted to those matching `pattern`. +""" +whos + +doc""" + edit(file::AbstractString[, line]) + +Edit a file optionally providing a line number to edit at. Returns +to the julia prompt when you quit the editor. +""" +edit + +doc""" + edit(function[, types]) + +Edit the definition of a function, optionally specifying a tuple of +types to indicate which method to edit. +""" +edit + +doc""" + @edit() + +Evaluates the arguments to the function call, determines their +types, and calls the `edit` function on the resulting expression +""" +@edit + +doc""" + less(file::AbstractString[, line]) + +Show a file using the default pager, optionally providing a +starting line number. Returns to the julia prompt when you quit the +pager. +""" +less + +doc""" + less(function[, types]) + +Show the definition of a function using the default pager, +optionally specifying a tuple of types to indicate which method to +see. +""" +less + +doc""" + @less() + +Evaluates the arguments to the function call, determines their +types, and calls the `less` function on the resulting expression +""" +@less + +doc""" + clipboard(x) + +Send a printed form of `x` to the operating system clipboard +""" +clipboard + +doc""" + clipboard() -> AbstractString + +Return a string with the contents of the operating system clipboard +""" +clipboard + +doc""" + require(file::AbstractString...) + +Load source files once, in the context of the `Main` module, on +every active node, searching standard locations for files. +current `include` path but does not use it to search for files +library code, and is implicitly called by `using` to load +packages. +When searching for files, `require` first looks in the current +working directory, then looks for package code under `Pkg.dir()`, +then tries paths in the global array `LOAD_PATH`. +""" +require + +doc""" + reload(file::AbstractString) + +Like `require`, except forces loading of files regardless of +whether they have been loaded before. Typically used when +interactively developing libraries. +""" +reload + +doc""" + include(path::AbstractString) + +Evaluate the contents of a source file in the current context. +During including, a task-local include path is set to the directory +containing the file. Nested calls to `include` will search +relative to that path. All paths refer to files on node 1 when +running in parallel, and files will be fetched from node 1. This +function is typically used to load source interactively, or to +combine files in packages that are broken into multiple source +files. +""" +include + +doc""" + include_string(code::AbstractString) + +Like `include`, except reads code from the given string rather +than from a file. Since there is no file path involved, no path +processing or fetching from node 1 is done. +""" +include_string + +doc""" + which(f, types) + +Returns the method of `f` (a `Method` object) that would be +called for arguments of the given types. +If `types` is an abstract type, then the method that would be +called by `invoke` is returned. +""" +which + +doc""" + which(symbol) + +Return the module in which the binding for the variable referenced +by `symbol` was created. +""" +which + +doc""" + @which() + +Applied to a function call, it evaluates the arguments to the +specified function call, and returns the `Method` object for the +method that would be called for those arguments. Applied to a +variable, it returns the module in which the variable was bound. It +calls out to the `which` function. +""" +@which + +doc""" + methods(f[, types]) + +Returns the method table for `f`. +If `types` is specified, returns an array of methods whose types +match. +""" +methods + +doc""" + methodswith(typ[, module or function][, showparents]) + +Return an array of methods with an argument of type `typ`. If +optional `showparents` is `true`, also return arguments with a +parent type of `typ`, excluding type `Any`. +The optional second argument restricts the search to a particular +module or function. +""" +methodswith + +doc""" + @show() + +Show an expression and result, returning the result +""" +@show + +doc""" + versioninfo([verbose::Bool]) + +Print information about the version of Julia in use. If the +as well. +""" +versioninfo + +doc""" + workspace() + +Replace the top-level module (`Main`) with a new one, providing a +clean workspace. The previous `Main` module is made available as +statement such as `using LastMain.Package`. +This function should only be used interactively. +""" +workspace + +doc""" + is(x, y) -> Bool + +Determine whether `x` and `y` are identical, in the sense that +no program could distinguish them. Compares mutable objects by +address in memory, and compares immutable objects (such as numbers) +by contents at the bit level. This function is sometimes called +""" +is + +doc""" + isa(x, type) -> Bool + +Determine whether `x` is of the given `type`. +""" +isa + +doc""" + isequal(x, y) + +Similar to `==`, except treats all floating-point `NaN` values +as equal to each other, and treats `-0.0` as unequal to `0.0`. +The default implementation of `isequal` calls `==`, so if you +have a type that doesn't have these floating-point subtleties then +you probably only need to define `==`. +hash(y)`. +This typically means that if you define your own `==` function +then you must define a corresponding `hash` (and vice versa). +Collections typically implement `isequal` by calling `isequal` +recursively on all contents. +Scalar types generally do not need to implement `isequal` +separate from `==`, unless they represent floating-point numbers +amenable to a more efficient implementation than that provided as a +generic fallback (based on `isnan`, `signbit`, and `==`). +""" +isequal + +doc""" + isless(x, y) + +Test whether `x` is less than `y`, according to a canonical +total order. Values that are normally unordered, such as `NaN`, +are ordered in an arbitrary but consistent fashion. This is the +default comparison used by `sort`. Non-numeric types with a +canonical total order should implement this function. Numeric types +only need to implement it if they have special values such as +""" +isless + +doc""" + ifelse(condition::Bool, x, y) + +Return `x` if `condition` is true, otherwise return `y`. This +differs from `?` or `if` in that it is an ordinary function, so +all the arguments are evaluated first. In some cases, using +in generated code and provide higher performance in tight loops. +""" +ifelse + +doc""" + lexcmp(x, y) + +Compare `x` and `y` lexicographically and return -1, 0, or 1 +depending on whether `x` is less than, equal to, or greater than +lexicographically comparable types, and `lexless` will call +""" +lexcmp + +doc""" + lexless(x, y) + +Determine whether `x` is lexicographically less than `y`. +""" +lexless + +doc""" + typeof(x) + +Get the concrete type of `x`. +""" +typeof + +doc""" + tuple(xs...) + +Construct a tuple of the given objects. +""" +tuple + +doc""" + ntuple(f::Function, n) + +Create a tuple of length `n`, computing each element as `f(i)`, +where `i` is the index of the element. +""" +ntuple + +doc""" + object_id(x) + +Get a unique integer id for `x`. `object_id(x)==object_id(y)` +if and only if `is(x,y)`. +""" +object_id + +doc""" + hash(x[, h]) + +Compute an integer hash code such that `isequal(x,y)` implies +code to be mixed with the result. +New types should implement the 2-argument form, typically by +calling the 2-argument `hash` method recursively in order to mix +hashes of the contents with each other (and with `h`). +Typically, any type that implements `hash` should also implement +its own `==` (hence `isequal`) to guarantee the property +mentioned above. +""" +hash + +doc""" + finalizer(x, function) + +Register a function `f(x)` to be called when there are no +program-accessible references to `x`. The behavior of this +function is unpredictable if `x` is of a bits type. +""" +finalizer + +doc""" + finalize(x) + +Immediately run finalizers registered for object `x`. +""" +finalize + +doc""" + copy(x) + +Create a shallow copy of `x`: the outer structure is copied, but +not all internal values. For example, copying an array produces a +new array with identically-same elements as the original. +""" +copy + +doc""" + deepcopy(x) + +Create a deep copy of `x`: everything is copied recursively, +resulting in a fully independent object. For example, deep-copying +an array produces a new array whose elements are deep copies of the +original elements. Calling *deepcopy* on an object should generally +have the same effect as serializing and then deserializing it. +As a special case, functions can only be actually deep-copied if +they are anonymous, otherwise they are just copied. The difference +is only relevant in the case of closures, i.e. functions which may +contain hidden internal references. +While it isn't normally necessary, user-defined types can override +the default `deepcopy` behavior by defining a specialized version +of the function `deepcopy_internal(x::T, dict::ObjectIdDict)` +specialized for, and `dict` keeps track of objects copied so far +within the recursion. Within the definition, `deepcopy_internal` +should be used in place of `deepcopy`, and the `dict` variable +should be updated as appropriate before returning. +""" +deepcopy + +doc""" + isdefined([object], index | symbol) + +Tests whether an assignable location is defined. The arguments can +be an array and index, a composite object and field name (as a +symbol), or a module and a symbol. With a single symbol argument, +tests whether a global variable with that name is defined in +""" +isdefined + +doc""" + convert(T, x) + +Convert `x` to a value of type `T`. +If `T` is an `Integer` type, an `InexactError` will be raised +if `x` is not representable by `T`, for example if `x` is not +integer-valued, or is outside the range supported by `T`. +If `T` is a `FloatingPoint` or `Rational` type, then it will +return the closest value to `x` representable by `T`. +""" +convert + +doc""" + promote(xs...) + +Convert all arguments to their common promotion type (if any), and +return them all (as a tuple). +""" +promote + +doc""" + oftype(x, y) + +Convert `y` to the type of `x` (`convert(typeof(x), y)`). +""" +oftype + +doc""" + widen(type | x) + +If the argument is a type, return a `larger` type (for numeric +types, this will be a type with at least as much range and +precision as the argument, and usually more). Otherwise the +argument `x` is converted to `widen(typeof(x))`. +""" +widen + +doc""" + identity(x) + +The identity function. Returns its argument. +""" +identity + +doc""" + super(T::DataType) + +Return the supertype of DataType T +""" +super + +doc""" + issubtype(type1, type2) + +True if and only if all values of `type1` are also of `type2`. +Can also be written using the `<:` infix operator as `type1 <: +type2`. +""" +issubtype + +doc""" + <:(T1, T2) + +Subtype operator, equivalent to `issubtype(T1,T2)`. +""" +Base.(:(<:)) + +doc""" + subtypes(T::DataType) + +Return a list of immediate subtypes of DataType T. Note that all +currently loaded subtypes are included, including those not visible +in the current module. +""" +subtypes + +doc""" + typemin(type) + +The lowest value representable by the given (real) numeric type. +""" +typemin + +doc""" + typemax(type) + +The highest value representable by the given (real) numeric type. +""" +typemax + +doc""" + realmin(type) + +The smallest in absolute value non-subnormal value representable by +the given floating-point type +""" +realmin + +doc""" + realmax(type) + +The highest finite value representable by the given floating-point +type +""" +realmax + +doc""" + maxintfloat(type) + +The largest integer losslessly representable by the given floating- +point type +""" +maxintfloat + +doc""" + sizeof(type) + +Size, in bytes, of the canonical binary representation of the given +type, if any. +""" +sizeof + +doc""" + eps([type]) + +The distance between 1.0 and the next larger representable +floating-point value of `type`. Only floating-point types are +sensible arguments. If `type` is omitted, then `eps(Float64)` +is returned. +""" +eps + +doc""" + eps(x) + +The distance between `x` and the next larger representable +floating-point value of the same type as `x`. +""" +eps + +doc""" + promote_type(type1, type2) + +Determine a type big enough to hold values of each argument type +without loss, whenever possible. In some cases, where no type +exists to which both types can be promoted losslessly, some loss is +tolerated; for example, `promote_type(Int64,Float64)` returns +represented exactly as `Float64` values. +""" +promote_type + +doc""" + promote_rule(type1, type2) + +Specifies what type should be used by `promote` when given values +of types `type1` and `type2`. This function should not be +called directly, but should have definitions added to it for new +types as appropriate. +""" +promote_rule + +doc""" + getfield(value, name::Symbol) + +Extract a named field from a value of composite type. The syntax +""" +getfield + +doc""" + setfield!(value, name::Symbol, x) + +Assign `x` to a named field in `value` of composite type. The +syntax `a.b = c` calls `setfield!(a, :b, c)`, and the syntax +""" +setfield! + +doc""" + fieldoffsets(type) + +The byte offset of each field of a type relative to the data start. +For example, we could use it in the following manner to summarize +information about a struct type: +""" +fieldoffsets + +doc""" + fieldtype(type, name::Symbol | index::Int) + +Determine the declared type of a field (specified by name or index) +in a composite type. +""" +fieldtype + +doc""" + isimmutable(v) + +True if value `v` is immutable. See *Immutable Composite Types* +for a discussion of immutability. Note that this function works on +values, so if you give it a type, it will tell you that a value of +""" +isimmutable + +doc""" + isbits(T) + +True if `T` is a `plain data` type, meaning it is immutable and +contains no references to other values. Typical examples are +numeric types such as `UInt8`, `Float64`, and +""" +isbits + +doc""" + isleaftype(T) + +Determine whether `T` is a concrete type that can have instances, +meaning its only subtypes are itself and `None` (but `T` itself +is not `None`). +""" +isleaftype + +doc""" + typejoin(T, S) + +Compute a type that contains both `T` and `S`. +""" +typejoin + +doc""" + typeintersect(T, S) + +Compute a type that contains the intersection of `T` and `S`. +Usually this will be the smallest such type or one close to it. +""" +typeintersect + +doc""" + instances(T::Type) + +Return a collection of all instances of the given type, if +applicable. Mostly used for enumerated types (see `@enum`). +""" +instances + +doc""" + method_exists(f, Tuple type) -> Bool + +Determine whether the given generic function has a method matching +the given `Tuple` of argument types. +""" +method_exists + +doc""" + applicable(f, args...) -> Bool + +Determine whether the given generic function has a method +applicable to the given arguments. +""" +applicable + +doc""" + invoke(f, (types...), args...) + +Invoke a method for the given generic function matching the +specified types (as a tuple), on the specified arguments. The +arguments must be compatible with the specified types. This allows +invoking a method other than the most specific matching method, +which is useful when the behavior of a more general definition is +explicitly needed (often as part of the implementation of a more +specific method of the same function). +""" +invoke + +doc""" + |>(x, f) + +Applies a function to the preceding argument. This allows for easy +function chaining. +""" +Base.(:(|>)) + +doc""" + call(x, args...) + +If `x` is not a `Function`, then `x(args...)` is equivalent +to `call(x, args...)`. This means that function-like behavior +can be added to any type by defining new `call` methods. +""" +call + +doc""" + eval([m::Module], expr::Expr) + +Evaluate an expression in the given module and return the result. +Every module (except those defined with `baremodule`) has its own +1-argument definition of `eval`, which evaluates expressions in +that module. +""" +eval + +doc""" + @eval() + +Evaluate an expression and return the value. +""" +@eval + +doc""" + evalfile(path::AbstractString) + +Load the file using `include`, evaluate all expressions, and +return the value of the last one. +""" +evalfile + +doc""" + esc(e::ANY) + +Only valid in the context of an Expr returned from a macro. +Prevents the macro hygiene pass from turning embedded variables +into gensym variables. See the *Macros* section of the +Metaprogramming chapter of the manual for more details and +examples. +""" +esc + +doc""" + gensym([tag]) + +Generates a symbol which will not conflict with other variable +names. +""" +gensym + +doc""" + @gensym() + +Generates a gensym symbol for a variable. For example, `@gensym x +y` is transformed into `x = gensym(`x`); y = gensym(`y`)`. +""" +@gensym + +doc""" + parse(str, start; greedy=true, raise=true) + +Parse the expression string and return an expression (which could +later be passed to eval for execution). Start is the index of the +first character to start parsing. If `greedy` is true (default), +it will stop as soon as it has parsed a valid expression. +Incomplete but otherwise syntactically valid expressions will +return `Expr(:incomplete, `(error message)`)`. If `raise` is +true (default), syntax errors other than incomplete expressions +will raise an error. If `raise` is false, `parse` will return +an expression that will raise an error upon evaluation. +""" +parse + +doc""" + parse(str; raise=true) + +Parse the whole string greedily, returning a single expression. An +error is thrown if there are additional characters after the first +expression. If `raise` is true (default), syntax errors will +raise an error; otherwise, `parse` will return an expression that +will raise an error upon evaluation. +""" +parse + +doc""" + Nullable(x) + +Wrap value `x` in an object of type `Nullable`, which indicates +whether a value is present. `Nullable(x)` yields a non-empty +wrapper, and `Nullable{T}()` yields an empty instance of a +wrapper that might contain a value of type `T`. +""" +Nullable + +doc""" + get(x) + +Attempt to access the value of the `Nullable` object, `x`. +Returns the value if it is present; otherwise, throws a +""" +get + +doc""" + get(x, y) + +Attempt to access the value of the `Nullable{T}` object, `x`. +Returns the value if it is present; otherwise, returns `convert(T, +y)`. +""" +get + +doc""" + isnull(x) + +Is the `Nullable` object `x` null, i.e. missing a value? +""" +isnull + +doc""" + run(command) + +Run a command object, constructed with backticks. Throws an error +if anything goes wrong, including the process exiting with a non- +zero status. +""" +run + +doc""" + spawn(command) + +Run a command object asynchronously, returning the resulting +""" +spawn + +doc""" + DevNull + +Used in a stream redirect to discard all data written to it. +Essentially equivalent to /dev/null on Unix or NUL on Windows. +Usage: `run(`cat test.txt` |> DevNull)` +""" +DevNull + +doc""" + success(command) + +Run a command object, constructed with backticks, and tell whether +it was successful (exited with a code of 0). An exception is raised +if the process cannot be started. +""" +success + +doc""" + process_running(p::Process) + +Determine whether a process is currently running. +""" +process_running + +doc""" + process_exited(p::Process) + +Determine whether a process has exited. +""" +process_exited + +doc""" + kill(p::Process, signum=SIGTERM) + +Send a signal to a process. The default is to terminate the +process. +""" +kill + +doc""" + open(command, mode::AbstractString="r", stdio=DevNull) + +Start running `command` asynchronously, and return a tuple +reads from the process's standard output and `stdio` optionally +specifies the process's standard input stream. If `mode` is +and `stdio` optionally specifies the process's standard output +stream. +""" +open + +doc""" + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + +Similar to `open(command, mode, stdio)`, but calls `f(stream)` +on the resulting read or write stream, then closes the stream and +waits for the process to complete. Returns the value returned by +""" +open + +doc""" + Sys.set_process_title(title::AbstractString) + +Set the process title. No-op on some operating systems. (not +exported) +""" +Sys + +doc""" + Sys.get_process_title() + +Get the process title. On some systems, will always return empty +string. (not exported) +""" +Sys + +doc""" + readandwrite(command) + +Starts running a command asynchronously, and returns a tuple +process, and the process object itself. +""" +readandwrite + +doc""" + ignorestatus(command) + +Mark a command object so that running it will not throw an error if +the result code is non-zero. +""" +ignorestatus + +doc""" + detach(command) + +Mark a command object so that it will be run in a new process +group, allowing it to outlive the julia process, and not have +Ctrl-C interrupts passed to it. +""" +detach + +doc""" + setenv(command, env; dir=working_dir) + +Set environment variables to use when running the given command. +of strings of the form ``var=val``, or zero or more +replace) the existing environment, create `env` by `copy(ENV)` +and then setting `env[`var`]=val` as desired, or use +The `dir` keyword argument can be used to specify a working +directory for the command. +""" +setenv + +doc""" + withenv(f::Function, kv::Pair...) + +Execute `f()` in an environment that is temporarily modified (not +replaced as in `setenv`) by zero or more ``var`=>val` +arguments `kv`. `withenv` is generally used via the +be used to temporarily unset an environment variable (if it is +set). When `withenv` returns, the original environment has been +restored. +""" +withenv + +doc""" + pipe(from, to, ...) + +Create a pipeline from a data source to a destination. The source +and destination can be commands, I/O streams, strings, or results +of other `pipe` calls. At least one argument must be a command. +Strings refer to filenames. When called with more than two +arguments, they are chained together from left to right. For +example `pipe(a,b,c)` is equivalent to `pipe(pipe(a,b),c)`. +This provides a more concise way to specify multi-stage pipelines. +""" +pipe + +doc""" + pipe(command; stdin, stdout, stderr, append=false) + +Redirect I/O to or from the given `command`. Keyword arguments +specify which of the command's streams should be redirected. +is a more general version of the 2-argument `pipe` function. +""" +pipe + +doc""" + gethostname() -> AbstractString + +Get the local machine's host name. +""" +gethostname + +doc""" + getipaddr() -> AbstractString + +Get the IP address of the local machine, as a string of the form +""" +getipaddr + +doc""" + getpid() -> Int32 + +Get julia's process ID. +""" +getpid + +doc""" + time() + +Get the system time in seconds since the epoch, with fairly high +""" +time + +doc""" + time_ns() + +Get the time in nanoseconds. The time corresponding to 0 is +undefined, and wraps every 5.8 years. +""" +time_ns + +doc""" + tic() + +Set a timer to be read by the next call to `toc()` or `toq()`. +The macro call `@time expr` can also be used to time evaluation. +""" +tic + +doc""" + toc() + +Print and return the time elapsed since the last `tic()`. +""" +toc + +doc""" + toq() + +Return, but do not print, the time elapsed since the last +""" +toq + +doc""" + @time() + +A macro to execute an expression, printing the time it took to +execute, the number of allocations, and the total number of bytes +its execution caused to be allocated, before returning the value of +the expression. +""" +@time + +doc""" + @timev() + +This is a verbose version of the `@time` macro, it first prints +the same information as `@time`, then any non-zero memory +allocation counters, and then returns the value of the expression. +""" +@timev + +doc""" + @timed() + +A macro to execute an expression, and return the value of the +expression, elapsed time, total bytes allocated, garbage collection +time, and an object with various memory allocation counters. +""" +@timed + +doc""" + @elapsed() + +A macro to evaluate an expression, discarding the resulting value, +instead returning the number of seconds it took to execute as a +floating-point number. +""" +@elapsed + +doc""" + @allocated() + +A macro to evaluate an expression, discarding the resulting value, +instead returning the total number of bytes allocated during +evaluation of the expression. Note: the expression is evaluated +inside a local function, instead of the current context, in order +to eliminate the effects of compilation, however, there still may +be some allocations due to JIT compilation. This also makes the +results inconsistent with the `@time` macros, which do not try to +adjust for the effects of compilation. +""" +@allocated + +doc""" + EnvHash() -> EnvHash + +A singleton of this type provides a hash table interface to +environment variables. +""" +EnvHash + +doc""" + ENV + +Reference to the singleton `EnvHash`, providing a dictionary +interface to system environment variables. +""" +ENV + +doc""" + @unix() + +Given `@unix? a : b`, do `a` on Unix systems (including Linux +and OS X) and `b` elsewhere. See documentation for Handling +Platform Variations in the Calling C and Fortran Code section of +the manual. +""" +@unix + +doc""" + @osx() + +Given `@osx? a : b`, do `a` on OS X and `b` elsewhere. See +documentation for Handling Platform Variations in the Calling C and +Fortran Code section of the manual. +""" +@osx + +doc""" + @linux() + +Given `@linux? a : b`, do `a` on Linux and `b` elsewhere. See +documentation for Handling Platform Variations in the Calling C and +Fortran Code section of the manual. +""" +@linux + +doc""" + @windows() + +Given `@windows? a : b`, do `a` on Windows and `b` elsewhere. +See documentation for Handling Platform Variations in the Calling C +and Fortran Code section of the manual. +""" +@windows + +doc""" + error(message::AbstractString) + +Raise an `ErrorException` with the given message +""" +error + +doc""" + throw(e) + +Throw an object as an exception +""" +throw - julia> round(pi, 2) - 3.14 +doc""" + rethrow([e]) - julia> round(pi, 3, 2) - 3.125 +Throw an object without changing the current exception backtrace. +The default argument is the current exception (if called within a +""" +rethrow - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the "Float64" value represented by "1.15" is - actually *less* than 1.15, yet will be rounded to 1.2. +doc""" + backtrace() - julia> x = 1.15 - 1.15 +Get a backtrace object for the current program point. +""" +backtrace - julia> @sprintf "%.20f" x - "1.14999999999999991118" +doc""" + catch_backtrace() - julia> x < 115//100 - true +Get the backtrace of the current exception, for use within +""" +catch_backtrace - julia> round(x, 1) - 1.2 - ``` - """ round +doc""" + assert(cond) - @doc doc""" - ```rst - RoundingMode +Throw an `AssertionError` if `cond` is false. Also available as +the macro `@assert expr`. +""" +assert - A type which controls rounding behavior. Currently supported - rounding modes are: +doc""" + ArgumentError(msg) - * "RoundNearest" (default) +The parameters to a function call do not match a valid signature. +""" +ArgumentError - * "RoundNearestTiesAway" +doc""" + AssertionError([msg]) - * "RoundNearestTiesUp" +The asserted condition did not evalutate to `true`. +""" +AssertionError - * "RoundToZero" +doc""" + BoundsError([a][, i]) - * "RoundUp" +An indexing operation into an array, `a`, tried to access an out- +of-bounds element, `i`. +""" +BoundsError - * "RoundDown" - ``` - """ RoundingMode +doc""" + DimensionMismatch([msg]) - @doc doc""" - ```rst - RoundNearest +The objects called do not have matching dimensionality. +""" +DimensionMismatch - The default rounding mode. Rounds to the nearest integer, with ties - (fractional values of 0.5) being rounded to the nearest even - integer. - ``` - """ RoundNearest +doc""" + DivideError() - @doc doc""" - ```rst - RoundNearestTiesAway +Integer division was attempted with a denominator value of 0. +""" +DivideError - Rounds to nearest integer, with ties rounded away from zero (C/C++ - "round()" behaviour). - ``` - """ RoundNearestTiesAway +doc""" + DomainError() - @doc doc""" - ```rst - RoundNearestTiesUp +The arguments to a function or constructor are outside the valid +domain. +""" +DomainError - Rounds to nearest integer, with ties rounded toward positive - infinity (Java/JavaScript "round()" behaviour). - ``` - """ RoundNearestTiesUp +doc""" + EOFError() - @doc doc""" - ```rst - RoundToZero +No more data was available to read from a file or stream. +""" +EOFError - "round()" using this rounding mode is an alias for "trunc()". - ``` - """ RoundToZero +doc""" + ErrorException(msg) - @doc doc""" - ```rst - RoundUp +Generic error type. The error message, in the *.msg* field, may +provide more specific details. +""" +ErrorException - "round()" using this rounding mode is an alias for "ceil()". - ``` - """ RoundUp +doc""" + InexactError() - @doc doc""" - ```rst - RoundDown +Type conversion cannot be done exactly. +""" +InexactError - "round()" using this rounding mode is an alias for "floor()". - ``` - """ RoundDown +doc""" + InterruptException() - @doc doc""" - ```rst - round(z, RoundingModeReal, RoundingModeImaginary) +The process was stopped by a terminal interrupt (CTRL+C). +""" +InterruptException - Returns the nearest integral value of the same type as the complex- - valued "z" to "z", breaking ties using the specified - "RoundingMode"s. The first "RoundingMode" is used for rounding - the real components while the second is used for rounding the - imaginary components. - ``` - """ round +doc""" + KeyError(key) - @doc doc""" - ```rst - ceil([T], x[, digits[, base]]) +An indexing operation into an `Associative` (`Dict`) or `Set` +like object tried to access or delete a non-existent element. +""" +KeyError - "ceil(x)" returns the nearest integral value of the same type as - "x" that is greater than or equal to "x". +doc""" + LoadError(file::AbstractString, line::Int, error) - "ceil(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. +An error occurred while *including*, *requiring*, or *using* a +file. The error specifics should be available in the *.error* +field. +""" +LoadError - "digits" and "base" work as for "round()". - ``` - """ ceil +doc""" + MethodError(f, args) - @doc doc""" - ```rst - floor([T], x[, digits[, base]]) +A method with the required type signature does not exist in the +given generic function. +""" +MethodError - "floor(x)" returns the nearest integral value of the same type as - "x" that is less than or equal to "x". +doc""" + NullException() - "floor(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. - - "digits" and "base" work as for "round()". - ``` - """ floor - - @doc doc""" - ```rst - trunc([T], x[, digits[, base]]) - - "trunc(x)" returns the nearest integral value of the same type as - "x" whose absolute value is less than or equal to "x". - - "trunc(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. - - "digits" and "base" work as for "round()". - ``` - """ trunc - - @doc doc""" - ```rst - unsafe_trunc(T, x) - - "unsafe_trunc(T, x)" returns the nearest integral value of type - "T" whose absolute value is less than or equal to "x". If the - value is not representable by "T", an arbitrary value will be - returned. - ``` - """ unsafe_trunc - - @doc doc""" - ```rst - signif(x, digits[, base]) - - Rounds (in the sense of "round") "x" so that there are - "digits" significant digits, under a base "base" - representation, default 10. E.g., "signif(123.456, 2)" is - "120.0", and "signif(357.913, 4, 2)" is "352.0". - ``` - """ signif - - @doc doc""" - ```rst - min(x, y, ...) - - Return the minimum of the arguments. Operates elementwise over - arrays. - ``` - """ min - - @doc doc""" - ```rst - max(x, y, ...) - - Return the maximum of the arguments. Operates elementwise over - arrays. - ``` - """ max - - @doc doc""" - ```rst - minmax(x, y) - - Return "(min(x,y), max(x,y))". See also: "extrema()" that - returns "(minimum(x), maximum(x))" - ``` - """ minmax - - @doc doc""" - ```rst - clamp(x, lo, hi) - - Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x - > hi", return "hi". Arguments are promoted to a common type. - Operates elementwise over "x" if it is an array. - ``` - """ clamp - - @doc doc""" - ```rst - abs(x) - - Absolute value of "x" - ``` - """ abs - - @doc doc""" - ```rst - abs2(x) - - Squared absolute value of "x" - ``` - """ abs2 - - @doc doc""" - ```rst - copysign(x, y) - - Return "x" such that it has the same sign as "y" - ``` - """ copysign - - @doc doc""" - ```rst - sign(x) - - Return "+1" if "x" is positive, "0" if "x == 0", and "-1" - if "x" is negative. - ``` - """ sign - - @doc doc""" - ```rst - signbit(x) - - Returns "true" if the value of the sign of "x" is negative, - otherwise "false". - ``` - """ signbit - - @doc doc""" - ```rst - flipsign(x, y) - - Return "x" with its sign flipped if "y" is negative. For - example "abs(x) = flipsign(x,x)". - ``` - """ flipsign - - @doc doc""" - ```rst - sqrt(x) - - Return \sqrt{x}. Throws "DomainError" for negative "Real" - arguments. Use complex negative arguments instead. The prefix - operator "√" is equivalent to "sqrt". - ``` - """ sqrt - - @doc doc""" - ```rst - isqrt(n) - - Integer square root: the largest integer "m" such that "m*m <= - n". - ``` - """ isqrt - - @doc doc""" - ```rst - cbrt(x) - - Return x^{1/3}. The prefix operator "∛" is equivalent to - "cbrt". - ``` - """ cbrt - - @doc doc""" - ```rst - erf(x) - - Compute the error function of "x", defined by - \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex - "x". - ``` - """ erf - - @doc doc""" - ```rst - erfc(x) - - Compute the complementary error function of "x", defined by 1 - - \operatorname{erf}(x). - ``` - """ erfc - - @doc doc""" - ```rst - erfcx(x) - - Compute the scaled complementary error function of "x", defined - by e^{x^2} \operatorname{erfc}(x). Note also that - \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). - ``` - """ erfcx - - @doc doc""" - ```rst - erfi(x) - - Compute the imaginary error function of "x", defined by -i - \operatorname{erf}(ix). - ``` - """ erfi - - @doc doc""" - ```rst - dawson(x) - - Compute the Dawson function (scaled imaginary error function) of - "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} - \operatorname{erfi}(x). - ``` - """ dawson - - @doc doc""" - ```rst - erfinv(x) - - Compute the inverse error function of a real "x", defined by - \operatorname{erf}(\operatorname{erfinv}(x)) = x. - ``` - """ erfinv - - @doc doc""" - ```rst - erfcinv(x) - - Compute the inverse error complementary function of a real "x", - defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. - ``` - """ erfcinv - - @doc doc""" - ```rst - real(z) - - Return the real part of the complex number "z" - ``` - """ real - - @doc doc""" - ```rst - imag(z) - - Return the imaginary part of the complex number "z" - ``` - """ imag - - @doc doc""" - ```rst - reim(z) - - Return both the real and imaginary parts of the complex number - "z" - ``` - """ reim - - @doc doc""" - ```rst - conj(z) - - Compute the complex conjugate of a complex number "z" - ``` - """ conj - - @doc doc""" - ```rst - angle(z) - - Compute the phase angle in radians of a complex number "z" - ``` - """ angle - - @doc doc""" - ```rst - cis(z) - - Return \exp(iz). - ``` - """ cis - - @doc doc""" - ```rst - binomial(n, k) - - Number of ways to choose "k" out of "n" items - ``` - """ binomial - - @doc doc""" - ```rst - factorial(n) - - Factorial of "n". If "n" is an "Integer", the factorial is - computed as an integer (promoted to at least 64 bits). Note that - this may overflow if "n" is not small, but you can use - "factorial(big(n))" to compute the result exactly in arbitrary - precision. If "n" is not an "Integer", "factorial(n)" is - equivalent to "gamma(n+1)". - ``` - """ factorial - - @doc doc""" - ```rst - factorial(n, k) - - Compute "factorial(n)/factorial(k)" - ``` - """ factorial - - @doc doc""" - ```rst - factor(n) -> Dict - - Compute the prime factorization of an integer "n". Returns a - dictionary. The keys of the dictionary correspond to the factors, - and hence are of the same type as "n". The value associated with - each key indicates the number of times the factor appears in the - factorization. - - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 - ``` - """ factor - - @doc doc""" - ```rst - gcd(x, y) - - Greatest common (positive) divisor (or zero if x and y are both - zero). - ``` - """ gcd - - @doc doc""" - ```rst - lcm(x, y) - - Least common (non-negative) multiple. - ``` - """ lcm - - @doc doc""" - ```rst - gcdx(x, y) - - Computes the greatest common (positive) divisor of "x" and "y" - and their Bézout coefficients, i.e. the integer coefficients "u" - and "v" that satisfy ux+vy = d = gcd(x,y). - - julia> gcdx(12, 42) - (6,-3,1) - - julia> gcdx(240, 46) - (2,-9,47) - - Note: Bézout coefficients are *not* uniquely defined. "gcdx" - returns the minimal Bézout coefficients that are computed by the - extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, - Algorithm X.) These coefficients "u" and "v" are minimal in - the sense that |u| < |\frac y d and |v| < |\frac x d. - Furthermore, the signs of "u" and "v" are chosen so that - "d" is positive. - ``` - """ gcdx - - @doc doc""" - ```rst - ispow2(n) -> Bool - - Test whether "n" is a power of two - ``` - """ ispow2 - - @doc doc""" - ```rst - nextpow2(n) - - The smallest power of two not less than "n". Returns 0 for - "n==0", and returns "-nextpow2(-n)" for negative arguments. - ``` - """ nextpow2 - - @doc doc""" - ```rst - prevpow2(n) - - The largest power of two not greater than "n". Returns 0 for - "n==0", and returns "-prevpow2(-n)" for negative arguments. - ``` - """ prevpow2 - - @doc doc""" - ```rst - nextpow(a, x) - - The smallest "a^n" not less than "x", where "n" is a non- - negative integer. "a" must be greater than 1, and "x" must be - greater than 0. - ``` - """ nextpow - - @doc doc""" - ```rst - prevpow(a, x) - - The largest "a^n" not greater than "x", where "n" is a non- - negative integer. "a" must be greater than 1, and "x" must not - be less than 1. - ``` - """ prevpow - - @doc doc""" - ```rst - nextprod([k_1, k_2, ...], n) - - Next integer not less than "n" that can be written as \prod - k_i^{p_i} for integers p_1, p_2, etc. - ``` - """ nextprod - - @doc doc""" - ```rst - prevprod([k_1, k_2, ...], n) - - Previous integer not greater than "n" that can be written as - \prod k_i^{p_i} for integers p_1, p_2, etc. - ``` - """ prevprod - - @doc doc""" - ```rst - invmod(x, m) - - Take the inverse of "x" modulo "m": "y" such that xy = 1 - \pmod m - ``` - """ invmod - - @doc doc""" - ```rst - powermod(x, p, m) - - Compute x^p \pmod m - ``` - """ powermod - - @doc doc""" - ```rst - gamma(x) - - Compute the gamma function of "x" - ``` - """ gamma - - @doc doc""" - ```rst - lgamma(x) - - Compute the logarithm of the absolute value of "gamma()" for - "Real" "x", while for "Complex" "x" it computes the - logarithm of "gamma(x)". - ``` - """ lgamma - - @doc doc""" - ```rst - lfact(x) - - Compute the logarithmic factorial of "x" - ``` - """ lfact - - @doc doc""" - ```rst - digamma(x) - - Compute the digamma function of "x" (the logarithmic derivative - of "gamma(x)") - ``` - """ digamma - - @doc doc""" - ```rst - invdigamma(x) - - Compute the inverse digamma function of "x". - ``` - """ invdigamma - - @doc doc""" - ```rst - trigamma(x) - - Compute the trigamma function of "x" (the logarithmic second - derivative of "gamma(x)") - ``` - """ trigamma - - @doc doc""" - ```rst - polygamma(m, x) - - Compute the polygamma function of order "m" of argument "x" - (the "(m+1)th" derivative of the logarithm of "gamma(x)") - ``` - """ polygamma - - @doc doc""" - ```rst - airy(k, x) - - kth derivative of the Airy function \operatorname{Ai}(x). - ``` - """ airy - - @doc doc""" - ```rst - airyai(x) - - Airy function \operatorname{Ai}(x). - ``` - """ airyai - - @doc doc""" - ```rst - airyprime(x) - - Airy function derivative \operatorname{Ai}'(x). - ``` - """ airyprime - - @doc doc""" - ```rst - airyaiprime(x) - - Airy function derivative \operatorname{Ai}'(x). - ``` - """ airyaiprime - - @doc doc""" - ```rst - airybi(x) - - Airy function \operatorname{Bi}(x). - ``` - """ airybi - - @doc doc""" - ```rst - airybiprime(x) - - Airy function derivative \operatorname{Bi}'(x). - ``` - """ airybiprime - - @doc doc""" - ```rst - airyx(k, x) - - scaled kth derivative of the Airy function, return - \operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || - k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} - \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || - k == 3". - ``` - """ airyx - - @doc doc""" - ```rst - besselj0(x) - - Bessel function of the first kind of order 0, J_0(x). - ``` - """ besselj0 - - @doc doc""" - ```rst - besselj1(x) - - Bessel function of the first kind of order 1, J_1(x). - ``` - """ besselj1 - - @doc doc""" - ```rst - besselj(nu, x) - - Bessel function of the first kind of order "nu", J_\nu(x). - ``` - """ besselj - - @doc doc""" - ```rst - besseljx(nu, x) - - Scaled Bessel function of the first kind of order "nu", J_\nu(x) - e^{- | \operatorname{Im}(x) |}. - ``` - """ besseljx - - @doc doc""" - ```rst - bessely0(x) - - Bessel function of the second kind of order 0, Y_0(x). - ``` - """ bessely0 - - @doc doc""" - ```rst - bessely1(x) - - Bessel function of the second kind of order 1, Y_1(x). - ``` - """ bessely1 - - @doc doc""" - ```rst - bessely(nu, x) - - Bessel function of the second kind of order "nu", Y_\nu(x). - ``` - """ bessely - - @doc doc""" - ```rst - besselyx(nu, x) - - Scaled Bessel function of the second kind of order "nu", - Y_\nu(x) e^{- | \operatorname{Im}(x) |}. - ``` - """ besselyx - - @doc doc""" - ```rst - hankelh1(nu, x) - - Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). - ``` - """ hankelh1 - - @doc doc""" - ```rst - hankelh1x(nu, x) - - Scaled Bessel function of the third kind of order "nu", - H^{(1)}_\nu(x) e^{-x i}. - ``` - """ hankelh1x - - @doc doc""" - ```rst - hankelh2(nu, x) - - Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). - ``` - """ hankelh2 - - @doc doc""" - ```rst - hankelh2x(nu, x) - - Scaled Bessel function of the third kind of order "nu", - H^{(2)}_\nu(x) e^{x i}. - ``` - """ hankelh2x - - @doc doc""" - ```rst - besselh(nu, k, x) - - Bessel function of the third kind of order "nu" (Hankel - function). "k" is either 1 or 2, selecting "hankelh1" or - "hankelh2", respectively. - ``` - """ besselh - - @doc doc""" - ```rst - besseli(nu, x) - - Modified Bessel function of the first kind of order "nu", - I_\nu(x). - ``` - """ besseli - - @doc doc""" - ```rst - besselix(nu, x) - - Scaled modified Bessel function of the first kind of order "nu", - I_\nu(x) e^{- | \operatorname{Re}(x) |}. - ``` - """ besselix - - @doc doc""" - ```rst - besselk(nu, x) - - Modified Bessel function of the second kind of order "nu", - K_\nu(x). - ``` - """ besselk - - @doc doc""" - ```rst - besselkx(nu, x) - - Scaled modified Bessel function of the second kind of order "nu", - K_\nu(x) e^x. - ``` - """ besselkx - - @doc doc""" - ```rst - beta(x, y) - - Euler integral of the first kind \operatorname{B}(x,y) = - \Gamma(x)\Gamma(y)/\Gamma(x+y). - ``` - """ beta - - @doc doc""" - ```rst - lbeta(x, y) - - Natural logarithm of the absolute value of the beta function - \log(|\operatorname{B}(x,y)|). - ``` - """ lbeta - - @doc doc""" - ```rst - eta(x) - - Dirichlet eta function \eta(s) = - \sum^\infty_{n=1}(-)^{n-1}/n^{s}. - ``` - """ eta - - @doc doc""" - ```rst - zeta(s) - - Riemann zeta function \zeta(s). - ``` - """ zeta - - @doc doc""" - ```rst - zeta(s, z) - - Hurwitz zeta function \zeta(s, z). (This is equivalent to the - Riemann zeta function \zeta(s) for the case of "z=1".) - ``` - """ zeta - - @doc doc""" - ```rst - ndigits(n, b) - - Compute the number of digits in number "n" written in base "b". - ``` - """ ndigits - - @doc doc""" - ```rst - widemul(x, y) - - Multiply "x" and "y", giving the result as a larger type. - ``` - """ widemul - - @doc doc""" - ```rst - @evalpoly(z, c...) - - Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients - "c[1]", "c[2]", ...; that is, the coefficients are given in - ascending order by power of "z". This macro expands to efficient - inline code that uses either Horner's method or, for complex "z", - a more efficient Goertzel-like algorithm. - ``` - """ @evalpoly - - @doc doc""" - ```rst - mean(v[, region]) - - Compute the mean of whole array "v", or optionally along the - dimensions in "region". Note: Julia does not ignore "NaN" - values in the computation. For applications requiring the handling - of missing data, the "DataArray" package is recommended. - ``` - """ mean - - @doc doc""" - ```rst - mean!(r, v) - - Compute the mean of "v" over the singleton dimensions of "r", - and write results to "r". - ``` - """ mean! - - @doc doc""" - ```rst - std(v[, region]) - - Compute the sample standard deviation of a vector or array "v", - optionally along dimensions in "region". The algorithm returns an - estimator of the generative distribution's standard deviation under - the assumption that each entry of "v" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". - Note: Julia does not ignore "NaN" values in the computation. For - applications requiring the handling of missing data, the - "DataArray" package is recommended. - ``` - """ std - - @doc doc""" - ```rst - stdm(v, m) - - Compute the sample standard deviation of a vector "v" with known - mean "m". Note: Julia does not ignore "NaN" values in the - computation. - ``` - """ stdm - - @doc doc""" - ```rst - var(v[, region]) - - Compute the sample variance of a vector or array "v", optionally - along dimensions in "region". The algorithm will return an - estimator of the generative distribution's variance under the - assumption that each entry of "v" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: - Julia does not ignore "NaN" values in the computation. For - applications requiring the handling of missing data, the - "DataArray" package is recommended. - ``` - """ var - - @doc doc""" - ```rst - varm(v, m) - - Compute the sample variance of a vector "v" with known mean - "m". Note: Julia does not ignore "NaN" values in the - computation. - ``` - """ varm - - @doc doc""" - ```rst - middle(x) - - Compute the middle of a scalar value, which is equivalent to "x" - itself, but of the type of "middle(x, x)" for consistency. - ``` - """ middle - - @doc doc""" - ```rst - middle(x, y) - - Compute the middle of two reals "x" and "y", which is - equivalent in both value and type to computing their mean ("(x + - y) / 2"). - ``` - """ middle - - @doc doc""" - ```rst - middle(range) - - Compute the middle of a range, which consists in computing the mean - of its extrema. Since a range is sorted, the mean is performed with - the first and last element. - ``` - """ middle - - @doc doc""" - ```rst - middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - ``` - """ middle - - @doc doc""" - ```rst - median(v) - - Compute the median of a vector "v". "NaN" is returned if the - data contains any "NaN" values. For applications requiring the - handling of missing data, the "DataArrays" package is - recommended. - ``` - """ median - - @doc doc""" - ```rst - median!(v) - - Like "median", but may overwrite the input vector. - ``` - """ median! - - @doc doc""" - ```rst - hist(v[, n]) -> e, counts - - Compute the histogram of "v", optionally using approximately - "n" bins. The return values are a range "e", which correspond - to the edges of the bins, and "counts" containing the number of - elements of "v" in each bin. Note: Julia does not ignore "NaN" - values in the computation. - ``` - """ hist - - @doc doc""" - ```rst - hist(v, e) -> e, counts - - Compute the histogram of "v" using a vector/range "e" as the - edges for the bins. The result will be a vector of length - "length(e) - 1", such that the element at location "i" - satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not - ignore "NaN" values in the computation. - ``` - """ hist - - @doc doc""" - ```rst - hist!(counts, v, e) -> e, counts - - Compute the histogram of "v", using a vector/range "e" as the - edges for the bins. This function writes the resultant counts to a - pre-allocated array "counts". - ``` - """ hist! - - @doc doc""" - ```rst - hist2d(M, e1, e2) -> (edge1, edge2, counts) - - Compute a "2d histogram" of a set of N points specified by N-by-2 - matrix "M". Arguments "e1" and "e2" are bins for each - dimension, specified either as integer bin counts or vectors of bin - edges. The result is a tuple of "edge1" (the bin edges used in - the first dimension), "edge2" (the bin edges used in the second - dimension), and "counts", a histogram matrix of size - "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore - "NaN" values in the computation. - ``` - """ hist2d - - @doc doc""" - ```rst - hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - - Compute a "2d histogram" with respect to the bins delimited by - the edges given in "e1" and "e2". This function writes the - results to a pre-allocated array "counts". - ``` - """ hist2d! - - @doc doc""" - ```rst - histrange(v, n) - - Compute *nice* bin ranges for the edges of a histogram of "v", - using approximately "n" bins. The resulting step sizes will be 1, - 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - "NaN" values in the computation. - ``` - """ histrange - - @doc doc""" - ```rst - midpoints(e) - - Compute the midpoints of the bins with edges "e". The result is a - vector/range of length "length(e) - 1". Note: Julia does not - ignore "NaN" values in the computation. - ``` - """ midpoints - - @doc doc""" - ```rst - quantile(v, p) - - Compute the quantiles of a vector "v" at a specified set of - probability values "p". Note: Julia does not ignore "NaN" - values in the computation. - ``` - """ quantile - - @doc doc""" - ```rst - quantile(v, p) - - Compute the quantile of a vector "v" at the probability "p". - Note: Julia does not ignore "NaN" values in the computation. - ``` - """ quantile - - @doc doc""" - ```rst - quantile!(v, p) - - Like "quantile", but overwrites the input vector. - ``` - """ quantile! - - @doc doc""" - ```rst - cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - - Compute the Pearson covariance between the vector(s) in "v1" and - "v2". Here, "v1" and "v2" can be either vectors or matrices. - - This function accepts three keyword arguments: - - * "vardim": the dimension of variables. When "vardim = 1", - variables are considered in columns while observations in rows; - when "vardim = 2", variables are in rows while observations in - columns. By default, it is set to "1". - - * "corrected": whether to apply Bessel's correction (divide by - "n-1" instead of "n"). By default, it is set to "true". - - * "mean": allow users to supply mean values that are known. By - default, it is set to "nothing", which indicates that the - mean(s) are unknown, and the function will compute the mean. - Users can use "mean=0" to indicate that the input data are - centered, and hence there's no need to subtract the mean. - - The size of the result depends on the size of "v1" and "v2". - When both "v1" and "v2" are vectors, it returns the covariance - between them as a scalar. When either one is a matrix, it returns a - covariance matrix of size "(n1, n2)", where "n1" and "n2" are - the numbers of slices in "v1" and "v2", which depend on the - setting of "vardim". - - Note: "v2" can be omitted, which indicates "v2 = v1". - ``` - """ cov - - @doc doc""" - ```rst - cor(v1[, v2][, vardim=1, mean=nothing]) - - Compute the Pearson correlation between the vector(s) in "v1" and - "v2". - - Users can use the keyword argument "vardim" to specify the - variable dimension, and "mean" to supply pre-computed mean - values. - ``` - """ cor - - @doc doc""" - ```rst - fft(A[, dims]) - - Performs a multidimensional FFT of the array "A". The optional - "dims" argument specifies an iterable subset of dimensions (e.g. - an integer, range, tuple, or array) to transform along. Most - efficient if the size of "A" along the transformed dimensions is - a product of small primes; see "nextprod()". See also - "plan_fft()" for even greater efficiency. - - A one-dimensional FFT computes the one-dimensional discrete Fourier - transform (DFT) as defined by - - \operatorname{DFT}(A)[k] = - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(-i\frac{2\pi - (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. - - A multidimensional FFT simply performs this operation along each - transformed dimension of "A". - - Higher performance is usually possible with multi-threading. Use - *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* - processors. - ``` - """ fft - - @doc doc""" - ```rst - fft!(A[, dims]) - - Same as "fft()", but operates in-place on "A", which must be an - array of complex floating-point numbers. - ``` - """ fft! - - @doc doc""" - ```rst - ifft(A[, dims]) - - Multidimensional inverse FFT. - - A one-dimensional inverse FFT computes - - \operatorname{IDFT}(A)[k] = - \frac{1}{\operatorname{length}(A)} - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(+i\frac{2\pi (n-1)(k-1)} - {\operatorname{length}(A)} \right) A[n]. - - A multidimensional inverse FFT simply performs this operation along - each transformed dimension of "A". - ``` - """ ifft - - @doc doc""" - ```rst - ifft!(A[, dims]) - - Same as "ifft()", but operates in-place on "A". - ``` - """ ifft! - - @doc doc""" - ```rst - bfft(A[, dims]) - - Similar to "ifft()", but computes an unnormalized inverse - (backward) transform, which must be divided by the product of the - sizes of the transformed dimensions in order to obtain the inverse. - (This is slightly more efficient than "ifft()" because it omits a - scaling step, which in some applications can be combined with other - computational steps elsewhere.) - - \operatorname{BDFT}(A)[k] = \operatorname{length}(A) - \operatorname{IDFT}(A)[k] - ``` - """ bfft - - @doc doc""" - ```rst - bfft!(A[, dims]) - - Same as "bfft()", but operates in-place on "A". - ``` - """ bfft! - - @doc doc""" - ```rst - plan_fft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized FFT along given dimensions ("dims") of - arrays matching the shape and type of "A". (The first two - arguments have the same meaning as for "fft()".) Returns a - function "plan(A)" that computes "fft(A, dims)" quickly. - - The "flags" argument is a bitwise-or of FFTW planner flags, - defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or - "FFTW.PATIENT" will instead spend several seconds (or more) - benchmarking different possible FFT algorithms and picking the - fastest one; see the FFTW manual for more information on planner - flags. The optional "timelimit" argument specifies a rough upper - bound on the allowed planning time, in seconds. Passing - "FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array - "A" to be overwritten with zeros during plan creation. - - "plan_fft!()" is the same as "plan_fft()" but creates a plan - that operates in-place on its argument (which must be an array of - complex floating-point numbers). "plan_ifft()" and so on are - similar but produce plans that perform the equivalent of the - inverse transforms "ifft()" and so on. - ``` - """ plan_fft - - @doc doc""" - ```rst - plan_ifft(A[, dims[, flags[, timelimit]]]) - - Same as "plan_fft()", but produces a plan that performs inverse - transforms "ifft()". - ``` - """ plan_ifft - - @doc doc""" - ```rst - plan_bfft(A[, dims[, flags[, timelimit]]]) - - Same as "plan_fft()", but produces a plan that performs an - unnormalized backwards transform "bfft()". - ``` - """ plan_bfft - - @doc doc""" - ```rst - plan_fft!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_fft()", but operates in-place on "A". - ``` - """ plan_fft! - - @doc doc""" - ```rst - plan_ifft!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_ifft()", but operates in-place on "A". - ``` - """ plan_ifft! - - @doc doc""" - ```rst - plan_bfft!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_bfft()", but operates in-place on "A". - ``` - """ plan_bfft! - - @doc doc""" - ```rst - rfft(A[, dims]) - - Multidimensional FFT of a real array A, exploiting the fact that - the transform has conjugate symmetry in order to save roughly half - the computational time and storage costs compared with "fft()". - If "A" has size "(n_1, ..., n_d)", the result has size - "(floor(n_1/2)+1, ..., n_d)". - - The optional "dims" argument specifies an iterable subset of one - or more dimensions of "A" to transform, similar to "fft()". - Instead of (roughly) halving the first dimension of "A" in the - result, the "dims[1]" dimension is (roughly) halved in the same - way. - ``` - """ rfft - - @doc doc""" - ```rst - irfft(A, d[, dims]) - - Inverse of "rfft()": for a complex array "A", gives the - corresponding real array whose FFT yields "A" in the first half. - As for "rfft()", "dims" is an optional subset of dimensions to - transform, defaulting to "1:ndims(A)". - - "d" is the length of the transformed real array along the - "dims[1]" dimension, which must satisfy "d == - floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred - from "size(A)" due to the possibility of rounding by the - "floor" function here.) - ``` - """ irfft - - @doc doc""" - ```rst - brfft(A, d[, dims]) - - Similar to "irfft()" but computes an unnormalized inverse - transform (similar to "bfft()"), which must be divided by the - product of the sizes of the transformed dimensions (of the real - output array) in order to obtain the inverse transform. - ``` - """ brfft - - @doc doc""" - ```rst - plan_rfft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized real-input FFT, similar to "plan_fft()" - except for "rfft()" instead of "fft()". The first two - arguments, and the size of the transformed result, are the same as - for "rfft()". - ``` - """ plan_rfft - - @doc doc""" - ```rst - plan_brfft(A, d[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized real-input unnormalized transform, similar to - "plan_rfft()" except for "brfft()" instead of "rfft()". The - first two arguments and the size of the transformed result, are the - same as for "brfft()". - ``` - """ plan_brfft - - @doc doc""" - ```rst - plan_irfft(A, d[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized inverse real-input FFT, similar to - "plan_rfft()" except for "irfft()" and "brfft()", - respectively. The first three arguments have the same meaning as - for "irfft()". - ``` - """ plan_irfft - - @doc doc""" - ```rst - dct(A[, dims]) - - Performs a multidimensional type-II discrete cosine transform (DCT) - of the array "A", using the unitary normalization of the DCT. The - optional "dims" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of "A" along the transformed - dimensions is a product of small primes; see "nextprod()". See - also "plan_dct()" for even greater efficiency. - ``` - """ dct - - @doc doc""" - ```rst - dct!(A[, dims]) - - Same as "dct!()", except that it operates in-place on "A", - which must be an array of real or complex floating-point values. - ``` - """ dct! - - @doc doc""" - ```rst - idct(A[, dims]) - - Computes the multidimensional inverse discrete cosine transform - (DCT) of the array "A" (technically, a type-III DCT with the - unitary normalization). The optional "dims" argument specifies an - iterable subset of dimensions (e.g. an integer, range, tuple, or - array) to transform along. Most efficient if the size of "A" - along the transformed dimensions is a product of small primes; see - "nextprod()". See also "plan_idct()" for even greater - efficiency. - ``` - """ idct - - @doc doc""" - ```rst - idct!(A[, dims]) - - Same as "idct!()", but operates in-place on "A". - ``` - """ idct! - - @doc doc""" - ```rst - plan_dct(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized discrete cosine transform (DCT), similar to - "plan_fft()" except producing a function that computes "dct()". - The first two arguments have the same meaning as for "dct()". - ``` - """ plan_dct - - @doc doc""" - ```rst - plan_dct!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_dct()", but operates in-place on "A". - ``` - """ plan_dct! - - @doc doc""" - ```rst - plan_idct(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized inverse discrete cosine transform (DCT), - similar to "plan_fft()" except producing a function that computes - "idct()". The first two arguments have the same meaning as for - "idct()". - ``` - """ plan_idct - - @doc doc""" - ```rst - plan_idct!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_idct()", but operates in-place on "A". - ``` - """ plan_idct! - - @doc doc""" - ```rst - fftshift(x) - - Swap the first and second halves of each dimension of "x". - ``` - """ fftshift - - @doc doc""" - ```rst - fftshift(x, dim) - - Swap the first and second halves of the given dimension of array - "x". - ``` - """ fftshift - - @doc doc""" - ```rst - ifftshift(x[, dim]) - - Undoes the effect of "fftshift". - ``` - """ ifftshift - - @doc doc""" - ```rst - filt(b, a, x[, si]) - - Apply filter described by vectors "a" and "b" to vector "x", - with an optional initial filter state vector "si" (defaults to - zeros). - ``` - """ filt - - @doc doc""" - ```rst - filt!(out, b, a, x[, si]) - - Same as "filt()" but writes the result into the "out" argument, - which may alias the input "x" to modify it in-place. - ``` - """ filt! - - @doc doc""" - ```rst - deconv(b, a) - - Construct vector "c" such that "b = conv(a,c) + r". Equivalent - to polynomial division. - ``` - """ deconv - - @doc doc""" - ```rst - conv(u, v) - - Convolution of two vectors. Uses FFT algorithm. - ``` - """ conv - - @doc doc""" - ```rst - conv2(u, v, A) - - 2-D convolution of the matrix "A" with the 2-D separable kernel - generated by the vectors "u" and "v". Uses 2-D FFT algorithm - ``` - """ conv2 - - @doc doc""" - ```rst - conv2(B, A) - - 2-D convolution of the matrix "B" with the matrix "A". Uses - 2-D FFT algorithm - ``` - """ conv2 - - @doc doc""" - ```rst - xcorr(u, v) - - Compute the cross-correlation of two vectors. - ``` - """ xcorr - - @doc doc""" - ```rst - r2r(A, kind[, dims]) - - Performs a multidimensional real-input/real-output (r2r) transform - of type "kind" of the array "A", as defined in the FFTW manual. - "kind" specifies either a discrete cosine transform of various - types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or - "FFTW.REDFT11"), a discrete sine transform of various types - ("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or - "FFTW.RODFT11"), a real-input DFT with halfcomplex-format output - ("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete - Hartley transform ("FFTW.DHT"). The "kind" argument may be an - array or tuple in order to specify different transform types along - the different dimensions of "A"; "kind[end]" is used for any - unspecified dimensions. See the FFTW manual for precise - definitions of these transform types, at http://www.fftw.org/doc. - - The optional "dims" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. "kind[i]" is then the transform type for "dims[i]", with - "kind[end]" being used for "i > length(kind)". - - See also "plan_r2r()" to pre-plan optimized r2r transforms. - ``` - """ Base.FFTW.r2r - - @doc doc""" - ```rst - r2r!(A, kind[, dims]) - - Same as "r2r()", but operates in-place on "A", which must be an - array of real or complex floating-point numbers. - ``` - """ Base.FFTW.r2r! - - @doc doc""" - ```rst - plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" - except that the transforms (and the first three arguments) - correspond to "r2r()" and "r2r!()", respectively. - ``` - """ Base.FFTW.plan_r2r - - @doc doc""" - ```rst - plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) - - Similar to "Base.plan_fft()", but corresponds to "r2r!()". - ``` - """ Base.FFTW.plan_r2r! - - @doc doc""" - ```rst - quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - - Numerically integrate the function "f(x)" from "a" to "b", - and optionally over additional intervals "b" to "c" and so on. - Keyword options include a relative error tolerance "reltol" - (defaults to "sqrt(eps)" in the precision of the endpoints), an - absolute error tolerance "abstol" (defaults to 0), a maximum - number of function evaluations "maxevals" (defaults to "10^7"), - and the "order" of the integration rule (defaults to 7). - - Returns a pair "(I,E)" of the estimated integral "I" and an - estimated upper bound on the absolute error "E". If "maxevals" - is not exceeded then "E <= max(abstol, reltol*norm(I))" will - hold. (Note that it is useful to specify a positive "abstol" in - cases where "norm(I)" may be zero.) - - The endpoints "a" etcetera can also be complex (in which case the - integral is performed over straight-line segments in the complex - plane). If the endpoints are "BigFloat", then the integration - will be performed in "BigFloat" precision as well (note: it is - advisable to increase the integration "order" in rough proportion - to the precision, for smooth integrands). More generally, the - precision is set by the precision of the integration endpoints - (promoted to floating-point types). - - The integrand "f(x)" can return any numeric scalar, vector, or - matrix type, or in fact any type supporting "+", "-", - multiplication by real values, and a "norm" (i.e., any normed - vector space). Alternatively, a different norm can be specified by - passing a *norm*-like function as the *norm* keyword argument - (which defaults to *vecnorm*). - - [Only one-dimensional integrals are provided by this function. For - multi-dimensional integration (cubature), there are many different - algorithms (often much better than simple nested 1d integrals) and - the optimal choice tends to be very problem-dependent. See the - Julia external-package listing for available algorithms for - multidimensional integration or other specialized tasks (such as - integrals of highly oscillatory or singular functions).] - - The algorithm is an adaptive Gauss-Kronrod integration technique: - the integral in each interval is estimated using a Kronrod rule - ("2*order+1" points) and the error is estimated using an embedded - Gauss rule ("order" points). The interval with the largest - error is then subdivided into two intervals and the process is - repeated until the desired error tolerance is achieved. - - These quadrature rules work best for smooth functions within each - interval, so if your function has a known discontinuity or other - singularity, it is best to subdivide your interval to put the - singularity at an endpoint. For example, if "f" has a - discontinuity at "x=0.7" and you want to integrate from 0 to 1, - you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at - the point of discontinuity. The integrand is never evaluated - exactly at the endpoints of the intervals, so it is possible to - integrate functions that diverge at the endpoints as long as the - singularity is integrable (for example, a "log(x)" or - "1/sqrt(x)" singularity). - - For real-valued endpoints, the starting and/or ending points may be - infinite. (A coordinate transformation is performed internally to - map the infinite interval to a finite one.) - ``` - """ quadgk - - @doc doc""" - ```rst - bin(n[, pad]) - - Convert an integer to a binary string, optionally specifying a - number of digits to pad to. - ``` - """ bin - - @doc doc""" - ```rst - hex(n[, pad]) - - Convert an integer to a hexadecimal string, optionally specifying a - number of digits to pad to. - ``` - """ hex - - @doc doc""" - ```rst - dec(n[, pad]) - - Convert an integer to a decimal string, optionally specifying a - number of digits to pad to. - ``` - """ dec - - @doc doc""" - ```rst - oct(n[, pad]) - - Convert an integer to an octal string, optionally specifying a - number of digits to pad to. - ``` - """ oct - - @doc doc""" - ```rst - base(base, n[, pad]) - - Convert an integer to a string in the given base, optionally - specifying a number of digits to pad to. The base can be specified - as either an integer, or as a "UInt8" array of character values - to use as digit symbols. - ``` - """ base - - @doc doc""" - ```rst - digits(n[, base][, pad]) - - Returns an array of the digits of "n" in the given base, - optionally padded with zeros to a specified size. More significant - digits are at higher indexes, such that "n == - sum([digits[k]*base^(k-1) for k=1:length(digits)])". - ``` - """ digits - - @doc doc""" - ```rst - digits!(array, n[, base]) - - Fills an array of the digits of "n" in the given base. More - significant digits are at higher indexes. If the array length is - insufficient, the least significant digits are filled up to the - array length. If the array length is excessive, the excess portion - is filled with zeros. - ``` - """ digits! - - @doc doc""" - ```rst - bits(n) - - A string giving the literal bit representation of a number. - ``` - """ bits - - @doc doc""" - ```rst - parse(type, str[, base]) - - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. - ``` - """ parse - - @doc doc""" - ```rst - tryparse(type, str[, base]) - - Like "parse", but returns a "Nullable" of the requested type. - The result will be null if the string does not contain a valid - number. - ``` - """ tryparse - - @doc doc""" - ```rst - big(x) - - Convert a number to a maximum precision representation (typically - "BigInt" or "BigFloat"). See "BigFloat" for information about - some pitfalls with floating-point numbers. - ``` - """ big - - @doc doc""" - ```rst - signed(x) - - Convert a number to a signed integer. If the argument is unsigned, - it is reinterpreted as signed without checking for overflow. - ``` - """ signed - - @doc doc""" - ```rst - unsigned(x) -> Unsigned - - Convert a number to an unsigned integer. If the argument is signed, - it is reinterpreted as unsigned without checking for negative - values. - ``` - """ unsigned - - @doc doc""" - ```rst - float(x) - - Convert a number, array, or string to a "FloatingPoint" data - type. For numeric data, the smallest suitable "FloatingPoint" - type is used. Converts strings to "Float64". - ``` - """ float - - @doc doc""" - ```rst - significand(x) - - Extract the significand(s) (a.k.a. mantissa), in binary - representation, of a floating-point number or array. If "x" is a - non-zero finite number, than the result will be a number of the - same type on the interval [1,2). Otherwise "x" is returned. - - julia> significand(15.2)/15.2 - 0.125 - - julia> significand(15.2)*8 - 15.2 - ``` - """ significand - - @doc doc""" - ```rst - exponent(x) -> Int - - Get the exponent of a normalized floating-point number. - ``` - """ exponent - - @doc doc""" - ```rst - complex(r[, i]) - - Convert real numbers or arrays to complex. "i" defaults to zero. - ``` - """ complex - - @doc doc""" - ```rst - bswap(n) - - Byte-swap an integer - ``` - """ bswap - - @doc doc""" - ```rst - num2hex(f) - - Get a hexadecimal string of the binary representation of a floating - point number - ``` - """ num2hex - - @doc doc""" - ```rst - hex2num(str) - - Convert a hexadecimal string to the floating point number it - represents - ``` - """ hex2num - - @doc doc""" - ```rst - hex2bytes(s::ASCIIString) - - Convert an arbitrarily long hexadecimal string to its binary - representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. - ``` - """ hex2bytes - - @doc doc""" - ```rst - bytes2hex(bin_arr::Array{UInt8, 1}) - - Convert an array of bytes to its hexadecimal representation. All - characters are in lower-case. Returns an ASCIIString. - ``` - """ bytes2hex - - @doc doc""" - ```rst - one(x) - - Get the multiplicative identity element for the type of x (x can - also specify the type itself). For matrices, returns an identity - matrix of the appropriate size and type. - ``` - """ one - - @doc doc""" - ```rst - zero(x) - - Get the additive identity element for the type of x (x can also - specify the type itself). - ``` - """ zero - - @doc doc""" - ```rst - pi -π - - The constant pi - ``` - """ pi - - @doc doc""" - ```rst - im - - The imaginary unit - ``` - """ im - - @doc doc""" - ```rst - e -eu - - The constant e - ``` - """ e - - @doc doc""" - ```rst - catalan - - Catalan's constant - ``` - """ catalan - - @doc doc""" - ```rst - γ -eulergamma - - Euler's constant - ``` - """ γ - - @doc doc""" - ```rst - φ -golden - - The golden ratio - ``` - """ φ - - @doc doc""" - ```rst - Inf - - Positive infinity of type Float64 - ``` - """ Inf - - @doc doc""" - ```rst - Inf32 - - Positive infinity of type Float32 - ``` - """ Inf32 - - @doc doc""" - ```rst - Inf16 - - Positive infinity of type Float16 - ``` - """ Inf16 - - @doc doc""" - ```rst - NaN - - A not-a-number value of type Float64 - ``` - """ NaN - - @doc doc""" - ```rst - NaN32 - - A not-a-number value of type Float32 - ``` - """ NaN32 - - @doc doc""" - ```rst - NaN16 - - A not-a-number value of type Float16 - ``` - """ NaN16 - - @doc doc""" - ```rst - issubnormal(f) -> Bool - - Test whether a floating point number is subnormal - ``` - """ issubnormal +An attempted access to a `Nullable` with no defined value. +""" +NullException - @doc doc""" - ```rst - isfinite(f) -> Bool +doc""" + OutOfMemoryError() - Test whether a number is finite - ``` - """ isfinite +An operation allocated too much memory for either the system or the +garbage collector to handle properly. +""" +OutOfMemoryError - @doc doc""" - ```rst - isinf(f) -> Bool +doc""" + ReadOnlyMemoryError() - Test whether a number is infinite - ``` - """ isinf +An operation tried to write to memory that is read-only. +""" +ReadOnlyMemoryError - @doc doc""" - ```rst - isnan(f) -> Bool +doc""" + OverflowError() - Test whether a floating point number is not a number (NaN) - ``` - """ isnan +The result of an expression is too large for the specified type and +will cause a wraparound. +""" +OverflowError - @doc doc""" - ```rst - inf(f) +doc""" + ParseError(msg) - Returns positive infinity of the floating point type "f" or of - the same floating point type as "f" - ``` - """ inf +The expression passed to the *parse* function could not be +interpreted as a valid Julia expression. +""" +ParseError - @doc doc""" - ```rst - nan(f) - - Returns NaN (not-a-number) of the floating point type "f" or of - the same floating point type as "f" - ``` - """ nan - - @doc doc""" - ```rst - nextfloat(f) - - Get the next floating point number in lexicographic order - ``` - """ nextfloat - - @doc doc""" - ```rst - prevfloat(f) -> FloatingPoint - - Get the previous floating point number in lexicographic order - ``` - """ prevfloat - - @doc doc""" - ```rst - isinteger(x) -> Bool - - Test whether "x" or all its elements are numerically equal to - some integer - ``` - """ isinteger - - @doc doc""" - ```rst - isreal(x) -> Bool - - Test whether "x" or all its elements are numerically equal to - some real number - ``` - """ isreal - - @doc doc""" - ```rst - Float32(x[, mode::RoundingMode]) - - Create a Float32 from "x". If "x" is not exactly representable - then "mode" determines how "x" is rounded. - - julia> Float32(1/3, RoundDown) - 0.3333333f0 - - julia> Float32(1/3, RoundUp) - 0.33333334f0 - - See "get_rounding" for available rounding modes. - ``` - """ Float32 - - @doc doc""" - ```rst - Float64(x[, mode::RoundingMode]) - - Create a Float64 from "x". If "x" is not exactly representable - then "mode" determines how "x" is rounded. - - julia> Float64(pi, RoundDown) - 3.141592653589793 +doc""" + ProcessExitedException() - julia> Float64(pi, RoundUp) - 3.1415926535897936 - - See "get_rounding" for available rounding modes. - ``` - """ Float64 - - @doc doc""" - ```rst - BigInt(x) +After a client Julia process has exited, further attempts to +reference the dead child will throw this exception. +""" +ProcessExitedException - Create an arbitrary precision integer. "x" may be an "Int" (or - anything that can be converted to an "Int"). The usual - mathematical operators are defined for this type, and results are - promoted to a "BigInt". +doc""" + StackOverflowError() - Instances can be constructed from strings via "parse()", or using - the "big" string literal. - ``` - """ BigInt +The function call grew beyond the size of the call stack. This +usually happens when a call recurses infinitely. +""" +StackOverflowError - @doc doc""" - ```rst - BigFloat(x) +doc""" + SystemError(prefix::AbstractString[, errnum::Int32]) - Create an arbitrary precision floating point number. "x" may be - an "Integer", a "Float64" or a "BigInt". The usual - mathematical operators are defined for this type, and results are - promoted to a "BigFloat". +A system call failed with an error code (in the `errno` global +variable). +""" +SystemError - Note that because decimal literals are converted to floating point - numbers when parsed, "BigFloat(2.1)" may not yield what you - expect. You may instead prefer to initialize constants from strings - via "parse()", or using the "big" string literal. +doc""" + TypeError(func::Symbol, context::AbstractString, expected::Type, got) - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision - ``` - """ BigFloat +A type assertion failure, or calling an intrinsic function with an +incorrect argument type. +""" +TypeError - @doc doc""" - ```rst - get_rounding(T) +doc""" + UndefRefError() - Get the current floating point rounding mode for type "T", - controlling the rounding of basic arithmetic functions ("+()", - "-()", "*()", "/()" and "sqrt()") and type conversion. +The item or field is not defined for the given object. +""" +UndefRefError - Valid modes are "RoundNearest", "RoundToZero", "RoundUp", - "RoundDown", and "RoundFromZero" ("BigFloat" only). - ``` - """ get_rounding +doc""" + UndefVarError(var::Symbol) - @doc doc""" - ```rst - set_rounding(T, mode) +A symbol in the current scope is not defined. +""" +UndefVarError - Set the rounding mode of floating point type "T", controlling the - rounding of basic arithmetic functions ("+()", "-()", "*()", - "/()" and "sqrt()") and type conversion. +doc""" + Timer(callback::Function, delay, repeat=0) - Note that this may affect other types, for instance changing the - rounding mode of "Float64" will change the rounding mode of - "Float32". See "get_rounding" for available modes - ``` - """ set_rounding +Create a timer to call the given callback function. The callback is +passed one argument, the timer object itself. The callback will be +invoked after the specified initial delay, and then repeating with +the given `repeat` interval. If `repeat` is `0`, the timer is +only triggered once. Times are in seconds. A timer is stopped and +has its resources freed by calling `close` on it. +""" +Timer - @doc doc""" - ```rst - with_rounding(f::Function, T, mode) +doc""" + Timer(delay, repeat=0) - Change the rounding mode of floating point type "T" for the - duration of "f". It is logically equivalent to: +Create a timer that wakes up tasks waiting for it (by calling +""" +Timer - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) +doc""" + module_name(m::Module) -> Symbol - See "get_rounding" for available rounding modes. - ``` - """ with_rounding +Get the name of a module as a symbol. +""" +module_name - @doc doc""" - ```rst - count_ones(x::Integer) -> Integer +doc""" + module_parent(m::Module) -> Module - Number of ones in the binary representation of "x". +Get a module's enclosing module. `Main` is its own parent. +""" +module_parent - julia> count_ones(7) - 3 - ``` - """ count_ones +doc""" + current_module() -> Module - @doc doc""" - ```rst - count_zeros(x::Integer) -> Integer +Get the *dynamically* current module, which is the module code is +currently being read from. In general, this is not the same as the +module containing the call to this function. +""" +current_module - Number of zeros in the binary representation of "x". +doc""" + fullname(m::Module) - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 - ``` - """ count_zeros +Get the fully-qualified name of a module as a tuple of symbols. For +example, `fullname(Base.Pkg)` gives `(:Base,:Pkg)`, and +""" +fullname - @doc doc""" - ```rst - leading_zeros(x::Integer) -> Integer +doc""" + names(x::Module[, all=false[, imported=false]]) - Number of zeros leading the binary representation of "x". +Get an array of the names exported by a module, with optionally +more module globals according to the additional parameters. +""" +names - julia> leading_zeros(Int32(1)) - 31 - ``` - """ leading_zeros +doc""" + nfields(x::DataType) -> Int - @doc doc""" - ```rst - leading_ones(x::Integer) -> Integer +Get the number of fields of a data type. +""" +nfields - Number of ones leading the binary representation of "x". +doc""" + fieldnames(x::DataType) - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 - ``` - """ leading_ones +Get an array of the fields of a data type. +""" +fieldnames - @doc doc""" - ```rst - trailing_zeros(x::Integer) -> Integer +doc""" + isconst([m::Module], s::Symbol) -> Bool - Number of zeros trailing the binary representation of "x". +Determine whether a global is declared `const` in a given module. +The default module argument is `current_module()`. +""" +isconst - julia> trailing_zeros(2) - 1 - ``` - """ trailing_zeros +doc""" + isgeneric(f::Function) -> Bool - @doc doc""" - ```rst - trailing_ones(x::Integer) -> Integer +Determine whether a function is generic. +""" +isgeneric - Number of ones trailing the binary representation of "x". +doc""" + function_name(f::Function) -> Symbol - julia> trailing_ones(3) - 2 - ``` - """ trailing_ones +Get the name of a generic function as a symbol, or `:anonymous`. +""" +function_name + +doc""" + function_module(f::Function, types) -> Module + +Determine the module containing a given definition of a generic +function. +""" +function_module + +doc""" + functionloc(f::Function, types) + +Returns a tuple `(filename,line)` giving the location of a method +definition. +""" +functionloc - @doc doc""" - ```rst - isprime(x::Integer) -> Bool +doc""" + functionloc(m::Method) + +Returns a tuple `(filename,line)` giving the location of a method +definition. +""" +functionloc + +doc""" + gc() + +Perform garbage collection. This should not generally be used. +""" +gc + +doc""" + gc_enable(on::Bool) + +Control whether garbage collection is enabled using a boolean +argument (true for enabled, false for disabled). Returns previous +GC state. Disabling garbage collection should be used only with +extreme caution, as it can cause memory use to grow without bound. +""" +gc_enable + +doc""" + macroexpand(x) + +Takes the expression x and returns an equivalent expression with +all macros removed (expanded). +""" +macroexpand + +doc""" + expand(x) + +Takes the expression x and returns an equivalent expression in +lowered form +""" +expand + +doc""" + code_lowered(f, types) + +Returns an array of lowered ASTs for the methods matching the given +generic function and type signature. +""" +code_lowered + +doc""" + @code_lowered() + +Evaluates the arguments to the function call, determines their +types, and calls `code_lowered()` on the resulting expression +""" +@code_lowered + +doc""" + code_typed(f, types; optimize=true) + +Returns an array of lowered and type-inferred ASTs for the methods +matching the given generic function and type signature. The keyword +argument `optimize` controls whether additional optimizations, +such as inlining, are also applied. +""" +code_typed + +doc""" + @code_typed() + +Evaluates the arguments to the function call, determines their +types, and calls `code_typed()` on the resulting expression +""" +@code_typed + +doc""" + code_warntype(f, types) + +Displays lowered and type-inferred ASTs for the methods matching +the given generic function and type signature. The ASTs are +annotated in such a way as to cause `non-leaf` types to be +emphasized (if color is available, displayed in red). This serves +as a warning of potential type instability. Not all non-leaf types +are particularly problematic for performance, so the results need +to be used judiciously. See *@code_warntype* for more information. +""" +code_warntype + +doc""" + @code_warntype() + +Evaluates the arguments to the function call, determines their +types, and calls `code_warntype()` on the resulting expression +""" +@code_warntype + +doc""" + code_llvm(f, types) + +Prints the LLVM bitcodes generated for running the method matching +the given generic function and type signature to `STDOUT`. +All metadata and dbg.* calls are removed from the printed bitcode. +Use code_llvm_raw for the full IR. +""" +code_llvm + +doc""" + @code_llvm() + +Evaluates the arguments to the function call, determines their +types, and calls `code_llvm()` on the resulting expression +""" +@code_llvm + +doc""" + code_native(f, types) + +Prints the native assembly instructions generated for running the +method matching the given generic function and type signature to +STDOUT. +""" +code_native + +doc""" + @code_native() + +Evaluates the arguments to the function call, determines their +types, and calls `code_native()` on the resulting expression +""" +@code_native + +doc""" + precompile(f, args::Tuple{Vararg{Any}}) + +Compile the given function `f` for the argument tuple (of types) +""" +precompile + +doc""" + ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) + +Call function in C-exported shared library, specified by +AbstractString or :Symbol. +Note that the argument type tuple must be a literal tuple, and not +a tuple-valued variable or expression. Alternatively, ccall may +also be used to call a function pointer, such as one returned by +dlsym. +Each `ArgumentValue` to the `ccall` will be converted to the +corresponding `ArgumentType`, by automatic insertion of calls to +ArgumentValue))`. (see also the documentation for each of these +functions for further details). In most cases, this simply results +in a call to `convert(ArgumentType, ArgumentValue)` +""" +Base.ccall + +doc""" + cglobal((symbol, library)[, type=Void]) + +Obtain a pointer to a global variable in a C-exported shared +library, specified exactly as in `ccall`. Returns a +supplied. The values can be read or written by `unsafe_load` or +""" +cglobal + +doc""" + cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + +Generate C-callable function pointer from Julia function. Type +annotation of the return value in the callback function is a must +for situations where Julia cannot infer the return type +automatically. +For example: +""" +cfunction + +doc""" + unsafe_convert(T, x) + +Convert `x` to a value of type `T` +In cases where `convert` would need to take a Julia object and +turn it into a `Ptr`, this function should be used to define and +perform that conversion. +Be careful to ensure that a julia reference to `x` exists as long +as the result of this function will be used. Accordingly, the +argument `x` to this function should never be an expression, only +a variable name or field reference. For example, `x=a.b.c` is +acceptable, but `x=[a,b,c]` is not. +The `unsafe` prefix on this function indicates that using the +result of this function after the `x` argument to this function +is no longer accessible to the program may cause undefined +behavior, including program corruption or segfaults, at any later +time. +""" +unsafe_convert + +doc""" + cconvert(T, x) + +Convert `x` to a value of type `T`, typically by calling +In cases where `x` cannot be safely converted to `T`, unlike +from `T`, which however is suitable for `unsafe_convert` to +handle. +Neither `convert` nor `cconvert` should take a Julia object and +turn it into a `Ptr`. +""" +cconvert + +doc""" + unsafe_load(p::Ptr{T}, i::Integer) + +Load a value of type `T` from the address of the ith element +expression `p[i-1]`. +The `unsafe` prefix on this function indicates that no validation +is performed on the pointer `p` to ensure that it is valid. +Incorrect usage may segfault your program or return garbage +answers, in the same manner as C. +""" +unsafe_load + +doc""" + unsafe_store!(p::Ptr{T}, x, i::Integer) + +Store a value of type `T` to the address of the ith element +expression `p[i-1] = x`. +The `unsafe` prefix on this function indicates that no validation +is performed on the pointer `p` to ensure that it is valid. +Incorrect usage may corrupt or segfault your program, in the same +manner as C. +""" +unsafe_store! + +doc""" + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + +Copy `N` elements from a source pointer to a destination, with no +checking. The size of an element is determined by the type of the +pointers. +The `unsafe` prefix on this function indicates that no validation +is performed on the pointers `dest` and `src` to ensure that +they are valid. Incorrect usage may corrupt or segfault your +program, in the same manner as C. +""" +unsafe_copy! + +doc""" + unsafe_copy!(dest::Array, do, src::Array, so, N) + +Copy `N` elements from a source array to a destination, starting +at offset `so` in the source and `do` in the destination +The `unsafe` prefix on this function indicates that no validation +is performed to ensure that N is inbounds on either array. +Incorrect usage may corrupt or segfault your program, in the same +manner as C. +""" +unsafe_copy! + +doc""" + copy!(dest, src) + +Copy all elements from collection `src` to array `dest`. +Returns `dest`. +""" +copy! + +doc""" + copy!(dest, do, src, so, N) + +Copy `N` elements from collection `src` starting at offset +""" +copy! + +doc""" + pointer(array[, index]) + +Get the native address of an array or string element. Be careful to +ensure that a julia reference to `a` exists as long as this +pointer will be used. This function is `unsafe` like +Calling `Ref(array[, index])` is generally preferable to this +function. +""" +pointer + +doc""" + pointer_to_array(pointer, dims[, take_ownership::Bool]) + +Wrap a native pointer as a Julia Array object. The pointer element +type determines the array element type. `own` optionally +specifies whether Julia should take ownership of the memory, +calling `free` on the pointer when the array is no longer +referenced. +""" +pointer_to_array + +doc""" + pointer_from_objref(object_instance) + +Get the memory address of a Julia object as a `Ptr`. The +existence of the resulting `Ptr` will not protect the object from +garbage collection, so you must ensure that the object remains +referenced for the whole time that the `Ptr` will be used. +""" +pointer_from_objref + +doc""" + unsafe_pointer_to_objref(p::Ptr) + +Convert a `Ptr` to an object reference. Assumes the pointer +refers to a valid heap-allocated Julia object. If this is not the +case, undefined behavior results, hence this function is considered +""" +unsafe_pointer_to_objref + +doc""" + disable_sigint(f::Function) + +Disable Ctrl-C handler during execution of a function, for calling +external code that is not interrupt safe. Intended to be called +using `do` block syntax as follows: +""" +disable_sigint + +doc""" + reenable_sigint(f::Function) + +Re-enable Ctrl-C handler during execution of a function. +Temporarily reverses the effect of `disable_sigint`. +""" +reenable_sigint + +doc""" + systemerror(sysfunc, iftrue) + +Raises a `SystemError` for `errno` with the descriptive string +""" +systemerror + +doc""" + Cchar - Returns "true" if "x" is prime, and "false" otherwise. +Equivalent to the native `char` c-type +""" +Cchar - julia> isprime(3) - true - ``` - """ isprime +doc""" + Cuchar - @doc doc""" - ```rst - isprime(x::BigInt[, reps = 25]) -> Bool - - Probabilistic primality test. Returns "true" if "x" is prime; - and "false" if "x" is not prime with high probability. The - false positive rate is about "0.25^reps". "reps = 25" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). +Equivalent to the native `unsigned char` c-type (UInt8) +""" +Cuchar - julia> isprime(big(3)) - true - ``` - """ isprime - - @doc doc""" - ```rst - primes(n) +doc""" + Cshort - Returns a collection of the prime numbers <= "n". - ``` - """ primes - - @doc doc""" - ```rst - isodd(x::Integer) -> Bool - - Returns "true" if "x" is odd (that is, not divisible by 2), and - "false" otherwise. - - julia> isodd(9) - true - - julia> isodd(10) - false - ``` - """ isodd +Equivalent to the native `signed short` c-type (Int16) +""" +Cshort + +doc""" + Cushort + +Equivalent to the native `unsigned short` c-type (UInt16) +""" +Cushort + +doc""" + Cint + +Equivalent to the native `signed int` c-type (Int32) +""" +Cint + +doc""" + Cuint + +Equivalent to the native `unsigned int` c-type (UInt32) +""" +Cuint + +doc""" + Clong + +Equivalent to the native `signed long` c-type +""" +Clong + +doc""" + Culong + +Equivalent to the native `unsigned long` c-type +""" +Culong + +doc""" + Clonglong + +Equivalent to the native `signed long long` c-type (Int64) +""" +Clonglong + +doc""" + Culonglong + +Equivalent to the native `unsigned long long` c-type (UInt64) +""" +Culonglong + +doc""" + Cintmax_t + +Equivalent to the native `intmax_t` c-type (Int64) +""" +Cintmax_t + +doc""" + Cuintmax_t + +Equivalent to the native `uintmax_t` c-type (UInt64) +""" +Cuintmax_t + +doc""" + Csize_t + +Equivalent to the native `size_t` c-type (UInt) +""" +Csize_t + +doc""" + Cssize_t + +Equivalent to the native `ssize_t` c-type +""" +Cssize_t + +doc""" + Cptrdiff_t + +Equivalent to the native `ptrdiff_t` c-type (Int) +""" +Cptrdiff_t + +doc""" + Coff_t + +Equivalent to the native `off_t` c-type +""" +Coff_t + +doc""" + Cwchar_t + +Equivalent to the native `wchar_t` c-type (Int32) +""" +Cwchar_t + +doc""" + Cfloat + +Equivalent to the native `float` c-type (Float32) +""" +Cfloat + +doc""" + Cdouble + +Equivalent to the native `double` c-type (Float64) +""" +Cdouble + +doc""" + start(iter) -> state + +Get initial iteration state for an iterable object +""" +start + +doc""" + done(iter, state) -> Bool + +Test whether we are done iterating +""" +done + +doc""" + next(iter, state) -> item, state + +For a given iterable object and iteration state, return the current +item and the next iteration state +""" +next + +doc""" + zip(iters...) + +For a set of iterable objects, returns an iterable of tuples, where +the `i`th tuple contains the `i`th component of each input +iterable. +Note that `zip()` is its own inverse: +""" +zip + +doc""" + enumerate(iter) + +An iterator that yields `(i, x)` where `i` is an index starting +at 1, and `x` is the `i`th value from the given iterator. It's +useful when you need not only the values `x` over which you are +iterating, but also the index `i` of the iterations. +""" +enumerate + +doc""" + rest(iter, state) + +An iterator that yields the same elements as `iter`, but starting +at the given `state`. +""" +rest + +doc""" + countfrom(start=1, step=1) + +An iterator that counts forever, starting at `start` and +incrementing by `step`. +""" +countfrom + +doc""" + take(iter, n) + +An iterator that generates at most the first `n` elements of +""" +take + +doc""" + drop(iter, n) + +An iterator that generates all but the first `n` elements of +""" +drop + +doc""" + cycle(iter) + +An iterator that cycles through `iter` forever. +""" +cycle + +doc""" + repeated(x[, n::Int]) + +An iterator that generates the value `x` forever. If `n` is +specified, generates `x` that many times (equivalent to +""" +repeated + +doc""" + isempty(collection) -> Bool + +Determine whether a collection is empty (has no elements). +""" +isempty + +doc""" + empty!(collection) -> collection + +Remove all elements from a `collection`. +""" +empty! + +doc""" + length(collection) -> Integer + +For ordered, indexable collections, the maximum index `i` for +which `getindex(collection, i)` is valid. For unordered +collections, the number of elements. +""" +length + +doc""" + endof(collection) -> Integer + +Returns the last index of the collection. +""" +endof + +doc""" + in(item, collection) -> Bool + +Determine whether an item is in the given collection, in the sense +that it is `==` to one of the values generated by iterating over +the collection. Some collections need a slightly different +definition; for example `Set`s check whether the item +To test for the presence of a key in a dictionary, use `haskey()` +or `k in keys(dict)`. +""" +Base.in + +doc""" + 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 `(key,value)` tuple type. The definition +that instances can be passed instead of types. However the form +that accepts a type argument should be defined for new types. +""" +eltype + +doc""" + 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`. +""" +indexin + +doc""" + findin(a, b) + +Returns the indices of elements in collection `a` that appear in +collection `b` +""" +findin + +doc""" + 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`. +""" +unique + +doc""" + reduce(op, v0, itr) + +Reduce the given collection `ìtr` with the given binary operator +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)`, +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. +""" +reduce + +doc""" + 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`. +""" +reduce + +doc""" + foldl(op, v0, itr) + +Like `reduce()`, but with guaranteed left associativity. `v0` +will be used exactly once. +""" +foldl + +doc""" + 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 +""" +foldl + +doc""" + foldr(op, v0, itr) + +Like `reduce()`, but with guaranteed right associativity. `v0` +will be used exactly once. +""" +foldr + +doc""" + 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 +""" +foldr + +doc""" + maximum(itr) + +Returns the largest element in a collection. +""" +maximum + +doc""" + maximum(A, dims) + +Compute the maximum value of an array over the given dimensions. +""" +maximum + +doc""" + maximum!(r, A) + +Compute the maximum value of `A` over the singleton dimensions of +""" +maximum! + +doc""" + minimum(itr) + +Returns the smallest element in a collection. +""" +minimum + +doc""" + minimum(A, dims) + +Compute the minimum value of an array over the given dimensions. +""" +minimum + +doc""" + minimum!(r, A) + +Compute the minimum value of `A` over the singleton dimensions of +""" +minimum! + +doc""" + extrema(itr) + +Compute both the minimum and maximum element in a single pass, and +return them as a 2-tuple. +""" +extrema + +doc""" + indmax(itr) -> Integer + +Returns the index of the maximum element in a collection. +""" +indmax + +doc""" + indmin(itr) -> Integer + +Returns the index of the minimum element in a collection. +""" +indmin + +doc""" + findmax(itr) -> (x, index) + +Returns the maximum element and its index. +""" +findmax + +doc""" + findmax(A, dims) -> (maxval, index) + +For an array input, returns the value and index of the maximum over +the given dimensions. +""" +findmax + +doc""" + findmin(itr) -> (x, index) + +Returns the minimum element and its index. +""" +findmin + +doc""" + findmin(A, dims) -> (minval, index) + +For an array input, returns the value and index of the minimum over +the given dimensions. +""" +findmin + +doc""" + maxabs(itr) + +Compute the maximum absolute value of a collection of values. +""" +maxabs + +doc""" + maxabs(A, dims) + +Compute the maximum absolute values over given dimensions. +""" +maxabs + +doc""" + maxabs!(r, A) + +Compute the maximum absolute values over the singleton dimensions +of `r`, and write values to `r`. +""" +maxabs! + +doc""" + minabs(itr) + +Compute the minimum absolute value of a collection of values. +""" +minabs + +doc""" + minabs(A, dims) + +Compute the minimum absolute values over given dimensions. +""" +minabs + +doc""" + minabs!(r, A) + +Compute the minimum absolute values over the singleton dimensions +of `r`, and write values to `r`. +""" +minabs! + +doc""" + sum(itr) + +Returns the sum of all elements in a collection. +""" +sum + +doc""" + sum(A, dims) + +Sum elements of an array over the given dimensions. +""" +sum + +doc""" + sum!(r, A) + +Sum elements of `A` over the singleton dimensions of `r`, and +write results to `r`. +""" +sum! + +doc""" + sum(f, itr) + +Sum the results of calling function `f` on each element of +""" +sum + +doc""" + sumabs(itr) + +Sum absolute values of all elements in a collection. This is +equivalent to *sum(abs(itr))* but faster. +""" +sumabs + +doc""" + sumabs(A, dims) + +Sum absolute values of elements of an array over the given +dimensions. +""" +sumabs + +doc""" + sumabs!(r, A) + +Sum absolute values of elements of `A` over the singleton +dimensions of `r`, and write results to `r`. +""" +sumabs! + +doc""" + sumabs2(itr) + +Sum squared absolute values of all elements in a collection. This +is equivalent to *sum(abs2(itr))* but faster. +""" +sumabs2 + +doc""" + sumabs2(A, dims) + +Sum squared absolute values of elements of an array over the given +dimensions. +""" +sumabs2 + +doc""" + sumabs2!(r, A) + +Sum squared absolute values of elements of `A` over the singleton +dimensions of `r`, and write results to `r`. +""" +sumabs2! + +doc""" + prod(itr) + +Returns the product of all elements of a collection. +""" +prod + +doc""" + prod(A, dims) + +Multiply elements of an array over the given dimensions. +""" +prod + +doc""" + prod!(r, A) + +Multiply elements of `A` over the singleton dimensions of `r`, +and write results to `r`. +""" +prod! + +doc""" + any(itr) -> Bool + +Test whether any elements of a boolean collection are true. +""" +any + +doc""" + any(A, dims) + +Test whether any values along the given dimensions of an array are +true. +""" +any + +doc""" + any!(r, A) + +Test whether any values in `A` along the singleton dimensions of +""" +any! + +doc""" + all(itr) -> Bool + +Test whether all elements of a boolean collection are true. +""" +all + +doc""" + all(A, dims) + +Test whether all values along the given dimensions of an array are +true. +""" +all + +doc""" + all!(r, A) + +Test whether all values in `A` along the singleton dimensions of +""" +all! + +doc""" + count(p, itr) -> Integer + +Count the number of elements in `itr` for which predicate `p` +returns true. +""" +count + +doc""" + any(p, itr) -> Bool + +Determine whether predicate `p` returns true for any elements of +""" +any + +doc""" + all(p, itr) -> Bool + +Determine whether predicate `p` returns true for all elements of +""" +all + +doc""" + map(f, c...) -> collection + +Transform collection `c` by applying `f` to each element. For +multiple collection arguments, apply `f` elementwise. +""" +map + +doc""" + map!(function, collection) + +In-place version of `map()`. +""" +map! + +doc""" + 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. +""" +map! + +doc""" + 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. +v0, map(f, itr))`, but will in general execute faster since no +intermediate collection needs to be created. See documentation for +The associativity of the reduction is implementation-dependent. +Additionally, some implementations may reuse the return value of +right associativity and invocation of `f` for every value. +""" +mapreduce + +doc""" + mapreduce(f, op, itr) + +Like `mapreduce(f, op, v0, itr)`. In general, this cannot be used +with empty collections (see `reduce(op, itr)`). +""" +mapreduce + +doc""" + mapfoldl(f, op, v0, itr) + +Like `mapreduce()`, but with guaranteed left associativity. +""" +mapfoldl + +doc""" + mapfoldl(f, op, itr) + +Like `mapfoldl(f, op, v0, itr)`, but using the first element of +collections (see `reduce(op, itr)`). +""" +mapfoldl + +doc""" + mapfoldr(f, op, v0, itr) + +Like `mapreduce()`, but with guaranteed right associativity. +""" +mapfoldr + +doc""" + mapfoldr(f, op, itr) + +Like `mapfoldr(f, op, v0, itr)`, but using the first element of +collections (see `reduce(op, itr)`). +""" +mapfoldr + +doc""" + first(coll) + +Get the first element of an iterable collection. Returns the start +point of a `Range` even if it is empty. +""" +first + +doc""" + 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. +""" +last + +doc""" + step(r) + +Get the step size of a `Range` object. +""" +step + +doc""" + collect(collection) + +Return an array of all items in a collection. For associative +collections, returns (key, value) tuples. +""" +collect + +doc""" + collect(element_type, collection) + +Return an array of type `Array{element_type,1}` of all items in a +collection. +""" +collect + +doc""" + issubset(a, b) + +Determine whether every element of `a` is also in `b`, using +""" +issubset + +doc""" + filter(function, collection) + +Return a copy of `collection`, removing elements for which +passed two arguments (key and value). +""" +filter + +doc""" + filter!(function, collection) + +Update `collection`, removing elements for which `function` is +false. For associative collections, the function is passed two +arguments (key and value). +""" +filter! + +doc""" + 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, ...)`. +""" +getindex + +doc""" + 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, ...)`. +""" +setindex! + +doc""" + Dict([itr]) + +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. +Alternatively, a sequence of pair arguments may be passed. +""" +Dict + +doc""" + haskey(collection, key) -> Bool + +Determine whether a collection has a mapping for a given key. +""" +haskey + +doc""" + 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. +""" +get + +doc""" + 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 + +doc""" + 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`. +""" +get! + +doc""" + 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! + +doc""" + getkey(collection, key, default) + +Return the key matching argument `key` if one exists in +""" +getkey + +doc""" + delete!(collection, key) + +Delete the mapping for the given key in a collection, and return +the collection. +""" +delete! + +doc""" + pop!(collection, key[, default]) + +Delete and return the mapping for `key` if it exists in +default is not specified. +""" +pop! + +doc""" + keys(collection) + +Return an iterator over all keys in a collection. +""" +keys + +doc""" + values(collection) + +Return an iterator over all values in a collection. +""" +values + +doc""" + merge(collection, others...) + +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. +""" +merge + +doc""" + merge!(collection, others...) + +Update collection with pairs from the other collections +""" +merge! + +doc""" + sizehint!(s, n) + +Suggest that collection `s` reserve capacity for at least `n` +elements. This can improve performance. +""" +sizehint! + +doc""" + 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. +""" +Set + +doc""" + IntSet([itr]) + +Construct a sorted set of the integers generated by the given +iterable object, or an empty set. Implemented as a bit string, and +therefore designed for dense integer sets. Only non-negative +integers can be stored. If the set will be sparse (for example +holding a single very large integer), use `Set` instead. +""" +IntSet + +doc""" + union(s1, s2...) + +Construct the union of two or more sets. Maintains order with +arrays. +""" +union + +doc""" + union!(s, iterable) + +Union each element of `iterable` into set `s` in-place. +""" +union! + +doc""" + intersect(s1, s2...) + +Construct the intersection of two or more sets. Maintains order and +multiplicity of the first argument for arrays and ranges. +""" +intersect + +doc""" + setdiff(s1, s2) + +Construct the set of elements in `s1` but not `s2`. Maintains +order with arrays. Note that both arguments must be collections, +and both will be iterated over. In particular, +""" +setdiff + +doc""" + setdiff!(s, iterable) + +Remove each element of `iterable` from set `s` in-place. +""" +setdiff! + +doc""" + symdiff(s1, s2...) + +Construct the symmetric difference of elements in the passed in +sets or arrays. Maintains order with arrays. +""" +symdiff + +doc""" + symdiff!(s, n) + +The set `s` is destructively modified to toggle the inclusion of +integer `n`. +""" +symdiff! + +doc""" + symdiff!(s, itr) + +For each element in `itr`, destructively toggle its inclusion in +set `s`. +""" +symdiff! + +doc""" + symdiff!(s1, s2) + +Construct the symmetric difference of sets `s1` and `s2`, +storing the result in `s1`. +""" +symdiff! + +doc""" + complement(s) + +Returns the set-complement of `IntSet` `s`. +""" +complement + +doc""" + complement!(s) + +Mutates `IntSet` `s` into its set-complement. +""" +complement! + +doc""" + intersect!(s1, s2) + +Intersects sets `s1` and `s2` and overwrites the set `s1` +with the result. If needed, `s1` will be expanded to the size of +""" +intersect! + +doc""" + issubset(A, S) -> Bool + +True if A is a subset of or equal to S. +""" +issubset + +doc""" + push!(collection, items...) -> collection + +Insert one or more `items` at the end of `collection`. +Use `append!()` to add all the elements of another collection to +to `append!([1, 2, 3], [4, 5, 6])`. +""" +push! + +doc""" + pop!(collection) -> item + +Remove the last item in `collection` and return it. +""" +pop! + +doc""" + unshift!(collection, items...) -> collection + +Insert one or more `items` at the beginning of `collection`. +""" +unshift! + +doc""" + shift!(collection) -> item + +Remove the first `item` from `collection`. +""" +shift! + +doc""" + insert!(collection, index, item) + +Insert an `item` into `collection` at the given `index`. +""" +insert! + +doc""" + deleteat!(collection, index) + +Remove the item at the given `index` and return the modified +gap. +""" +deleteat! + +doc""" + deleteat!(collection, itr) + +Remove the items at the indices given by `itr`, and return the +modified `collection`. Subsequent items are shifted to fill the +resulting gap. `itr` must be sorted and unique. +""" +deleteat! + +doc""" + splice!(collection, index[, replacement]) -> item + +Remove the item at the given index, and return the removed item. +Subsequent items are shifted down to fill the resulting gap. If +specified, replacement values from an ordered collection will be +spliced in place of the removed item. +To insert `replacement` before an index `n` without removing +any items, use `splice!(collection, n:n-1, replacement)`. +""" +splice! + +doc""" + splice!(collection, range[, replacement]) -> items + +Remove items in the specified index range, and return a collection +containing the removed items. Subsequent items are shifted down 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)`. +""" +splice! + +doc""" + resize!(collection, n) -> collection + +Resize `collection` 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. +""" +resize! + +doc""" + append!(collection, collection2) -> collection. + +Add the elements of `collection2` to the end of `collection`. +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)`. +""" +append! + +doc""" + prepend!(collection, items) -> collection + +Insert the elements of `items` to the beginning of +""" +prepend! + +doc""" + PriorityQueue(K, V[, ord]) + +Construct a new `PriorityQueue`, with keys of type `K` and +values/priorites of type `V`. If an order is not given, the +priority queue is min-ordered using the default comparison for +""" +Base.Collections.PriorityQueue + +doc""" + enqueue!(pq, k, v) + +Insert the a key `k` into a priority queue `pq` with priority +""" +Base.Collections.enqueue! + +doc""" + dequeue!(pq) + +Remove and return the lowest priority key from a priority queue. +""" +Base.Collections.dequeue! + +doc""" + peek(pq) + +Return the lowest priority key from a priority queue without +removing that key from the queue. +""" +Base.Collections.peek + +doc""" + heapify(v[, ord]) + +Return a new vector in binary heap order, optionally using the +given ordering. +""" +Base.Collections.heapify + +doc""" + heapify!(v[, ord]) + +In-place `heapify()`. +""" +Base.Collections.heapify! + +doc""" + isheap(v[, ord]) + +Return true iff an array is heap-ordered according to the given +order. +""" +Base.Collections.isheap + +doc""" + heappush!(v, x[, ord]) + +Given a binary heap-ordered array, push a new element `x`, +preserving the heap property. For efficiency, this function does +not check that the array is indeed heap-ordered. +""" +Base.Collections.heappush! + +doc""" + heappop!(v[, ord]) + +Given a binary heap-ordered array, remove and return the lowest +ordered element. For efficiency, this function does not check that +the array is indeed heap-ordered. +""" +Base.Collections.heappop! + +doc""" + nothing + +The singleton instance of type `Void`, used by convention when +there is no value to return (as in a C `void` function). Can be +converted to an empty `Nullable` value. +""" +nothing + +doc""" + OS_NAME + +A symbol representing the name of the operating system. Possible +values are `:Linux`, `:Darwin` (OS X), or `:Windows`. +""" +OS_NAME + +doc""" + ARGS + +An array of the command line arguments passed to Julia, as strings. +""" +ARGS + +doc""" + C_NULL + +The C null pointer constant, sometimes used when calling external +code. +""" +C_NULL + +doc""" + WORD_SIZE + +Standard word size on the current machine, in bits. +""" +WORD_SIZE + +doc""" + VERSION + +An object describing which version of Julia is in use. +""" +VERSION + +doc""" + LOAD_PATH + +An array of paths (as strings) where the `require` function looks +for code. +""" +LOAD_PATH + +doc""" + ANY + +Equivalent to `Any` for dispatch purposes, but signals the +compiler to skip code generation specialization for that field +""" +ANY + +doc""" + Period + +""" +Dates.Period + +doc""" + Year + +""" +Dates.Year + +doc""" + Month + +""" +Dates.Month + +doc""" + Week + +""" +Dates.Week + +doc""" + Day + +""" +Dates.Day + +doc""" + Hour + +""" +Dates.Hour + +doc""" + Minute + +""" +Dates.Minute + +doc""" + Second + +""" +Dates.Second + +doc""" + Millisecond + +""" +Dates.Millisecond + +doc""" + Instant + +of time as continuous timelines starting from an epoch. +""" +Dates.Instant + +doc""" + TimeType + +human representations of the machine instant. +""" +Dates.TimeType + +doc""" + DateTime + +according to the proleptic Gregorian calendar. +""" +Dates.DateTime + +doc""" + Date + +the proleptic Gregorian calendar. +""" +Dates.Date + +doc""" + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + +Construct a DateTime type by parts. Arguments must be convertible +to `Int64`. +""" +Dates.DateTime + +doc""" + DateTime(periods::Period...) -> DateTime + +Constuct a DateTime type by `Period` type parts. Arguments may be +in any order. DateTime parts not provided will default to the value +of `Dates.default(period)`. +""" +Dates.DateTime + +doc""" + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + +Create a DateTime through the adjuster API. The starting point will +be constructed from the provided `y, m, d...` arguments, and will +be adjusted until `f::Function` returns true. The step size in +adjusting can be provided manually through the `step` keyword. If +returns false instead of true. `limit` provides a limit to the +max number of iterations the adjustment API will pursue before +throwing an error (in the case that `f::Function` is never +satisfied). +""" +Dates.DateTime + +doc""" + DateTime(dt::Date) -> DateTime + +Converts a `Date` type to a `DateTime`. The hour, minute, +second, and millisecond parts of the new `DateTime` are assumed +to be zero. +""" +Dates.DateTime + +doc""" + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + +Construct a DateTime type by parsing the `dt` date string +following the pattern given in the `format` string. The following +codes can be used for constructing format strings: +All characters not listed above are treated as delimiters between +date and time slots. So a `dt` string of +""" +Dates.DateTime + +doc""" + Dates.DateFormat(format::AbstractString) -> DateFormat + +Construct a date formatting object that can be passed repeatedly +for parsing similarly formatted date strings. `format` is a +format string in the form described above (e.g. ``yyyy-mm- +dd``). +""" +Dates.Dates + +doc""" + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + +Similar form as above for parsing a `DateTime`, but passes a +more efficient if similarly formatted date strings will be parsed +repeatedly to first create a `DateFormat` object then use this +method for parsing. +""" +Dates.DateTime + +doc""" + Date(y[, m, d]) -> Date + +Construct a `Date` type by parts. Arguments must be convertible +to `Int64`. +""" +Dates.Date + +doc""" + Date(period::Period...) -> Date + +Constuct a Date type by `Period` type parts. Arguments may be in +any order. Date parts not provided will default to the value of +""" +Dates.Date + +doc""" + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + +Create a Date through the adjuster API. The starting point will be +constructed from the provided `y, m` arguments, and will be +adjusted until `f::Function` returns true. The step size in +adjusting can be provided manually through the `step` keyword. If +returns false instead of true. `limit` provides a limit to the +max number of iterations the adjustment API will pursue before +throwing an error (given that `f::Function` is never satisfied). +""" +Dates.Date + +doc""" + Date(dt::DateTime) -> Date + +Converts a `DateTime` type to a `Date`. The hour, minute, +second, and millisecond parts of the `DateTime` are truncated, so +only the year, month and day parts are used in construction. +""" +Dates.Date + +doc""" + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + +Construct a Date type by parsing a `dt` date string following the +pattern given in the `format` string. Follows the same +conventions as `DateTime` above. +""" +Dates.Date + +doc""" + Date(dt::AbstractString, df::DateFormat) -> Date + +Parse a date from a date string `dt` using a `DateFormat` +object `df`. +""" +Dates.Date + +doc""" + now() -> DateTime + +Returns a DateTime corresponding to the user's system time +including the system timezone locale. +""" +Dates.now + +doc""" + now(::Type{UTC}) -> DateTime + +Returns a DateTime corresponding to the user's system time as +UTC/GMT. +""" +Dates.now + +doc""" + eps(::DateTime) -> Millisecond + +Returns `Millisecond(1)` for `DateTime` values and `Day(1)` +for `Date` values. +""" +Dates.eps + +doc""" + year(dt::TimeType) -> Int64 + +Return the field part of a Date or DateTime as an `Int64`. +""" +Dates.year + +doc""" + Year(dt::TimeType) -> Year + +Return the field part of a Date or DateTime as a `Period` type. +""" +Dates.Year + +doc""" + yearmonth(dt::TimeType) -> (Int64, Int64) + +Simultaneously return the year and month parts of a Date or +DateTime. +""" +Dates.yearmonth + +doc""" + monthday(dt::TimeType) -> (Int64, Int64) + +Simultaneously return the month and day parts of a Date or +DateTime. +""" +Dates.monthday + +doc""" + yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + +Simultaneously return the year, month, and day parts of a Date or +DateTime. +""" +Dates.yearmonthday + +doc""" + dayname(dt::TimeType; locale="english") -> AbstractString + +Return the full day name corresponding to the day of the week of +the Date or DateTime in the given `locale`. +""" +Dates.dayname + +doc""" + dayabbr(dt::TimeType; locale="english") -> AbstractString + +Return the abbreviated name corresponding to the day of the week of +the Date or DateTime in the given `locale`. +""" +Dates.dayabbr + +doc""" + dayofweek(dt::TimeType) -> Int64 + +Returns the day of the week as an `Int64` with `1 = Monday, 2 = +Tuesday, etc.`. +""" +Dates.dayofweek + +doc""" + dayofweekofmonth(dt::TimeType) -> Int + +For the day of week of `dt`, returns which number it is in +etc.` In the range 1:5. +""" +Dates.dayofweekofmonth + +doc""" + daysofweekinmonth(dt::TimeType) -> Int + +For the day of week of `dt`, returns the total number of that day +of the week in `dt`'s month. Returns 4 or 5. Useful in temporal +expressions for specifying the last day of a week in a month by +including `dayofweekofmonth(dt) == daysofweekinmonth(dt)` in the +adjuster function. +""" +Dates.daysofweekinmonth + +doc""" + monthname(dt::TimeType; locale="english") -> AbstractString + +Return the full name of the month of the Date or DateTime in the +given `locale`. +""" +Dates.monthname + +doc""" + monthabbr(dt::TimeType; locale="english") -> AbstractString + +Return the abbreviated month name of the Date or DateTime in the +given `locale`. +""" +Dates.monthabbr + +doc""" + daysinmonth(dt::TimeType) -> Int + +Returns the number of days in the month of `dt`. Value will be +28, 29, 30, or 31. +""" +Dates.daysinmonth + +doc""" + isleapyear(dt::TimeType) -> Bool + +Returns true if the year of `dt` is a leap year. +""" +Dates.isleapyear + +doc""" + dayofyear(dt::TimeType) -> Int + +Returns the day of the year for `dt` with January 1st being day +1. +""" +Dates.dayofyear + +doc""" + daysinyear(dt::TimeType) -> Int + +Returns 366 if the year of `dt` is a leap year, otherwise returns +365. +""" +Dates.daysinyear + +doc""" + quarterofyear(dt::TimeType) -> Int + +Returns the quarter that `dt` resides in. Range of value is 1:4. +""" +Dates.quarterofyear + +doc""" + dayofquarter(dt::TimeType) -> Int + +Returns the day of the current quarter of `dt`. Range of value is +1:92. +""" +Dates.dayofquarter + +doc""" + trunc(dt::TimeType, ::Type{Period}) -> TimeType + +Truncates the value of `dt` according to the provided `Period` +type. E.g. if `dt` is `1996-01-01T12:30:00`, then +""" +Dates.trunc + +doc""" + firstdayofweek(dt::TimeType) -> TimeType + +Adjusts `dt` to the Monday of its week. +""" +Dates.firstdayofweek + +doc""" + lastdayofweek(dt::TimeType) -> TimeType + +Adjusts `dt` to the Sunday of its week. +""" +Dates.lastdayofweek + +doc""" + firstdayofmonth(dt::TimeType) -> TimeType + +Adjusts `dt` to the first day of its month. +""" +Dates.firstdayofmonth + +doc""" + lastdayofmonth(dt::TimeType) -> TimeType + +Adjusts `dt` to the last day of its month. +""" +Dates.lastdayofmonth + +doc""" + firstdayofyear(dt::TimeType) -> TimeType + +Adjusts `dt` to the first day of its year. +""" +Dates.firstdayofyear + +doc""" + lastdayofyear(dt::TimeType) -> TimeType + +Adjusts `dt` to the last day of its year. +""" +Dates.lastdayofyear + +doc""" + firstdayofquarter(dt::TimeType) -> TimeType + +Adjusts `dt` to the first day of its quarter. +""" +Dates.firstdayofquarter + +doc""" + lastdayofquarter(dt::TimeType) -> TimeType + +Adjusts `dt` to the last day of its quarter. +""" +Dates.lastdayofquarter + +doc""" + tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + +Adjusts `dt` to the next day of week corresponding to `dow` +with `1 = Monday, 2 = Tuesday, etc`. Setting `same=true` allows +the current `dt` to be considered as the next `dow`, allowing +for no adjustment to occur. +""" +Dates.tonext + +doc""" + toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + +Adjusts `dt` to the previous day of week corresponding to `dow` +with `1 = Monday, 2 = Tuesday, etc`. Setting `same=true` allows +the current `dt` to be considered as the previous `dow`, +allowing for no adjustment to occur. +""" +Dates.toprev + +doc""" + tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + +Adjusts `dt` to the first `dow` of its month. Alternatively, +""" +Dates.tofirst + +doc""" + tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + +Adjusts `dt` to the last `dow` of its month. Alternatively, +""" +Dates.tolast + +doc""" + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + +Adjusts `dt` by iterating at most `limit` iterations by +a single `TimeType` argument and return a `Bool`. `same` +allows `dt` to be considered in satisfying `func`. `negate` +will make the adjustment process terminate when `func` returns +false instead of true. +""" +Dates.tonext + +doc""" + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + +Adjusts `dt` by iterating at most `limit` iterations by +a single `TimeType` argument and return a `Bool`. `same` +allows `dt` to be considered in satisfying `func`. `negate` +will make the adjustment process terminate when `func` returns +false instead of true. +""" +Dates.toprev + +doc""" + Year(v) + +Construct a `Period` type with the given `v` value. Input must +be losslessly convertible to an `Int64`. +""" +Dates.Year + +doc""" + default(p::Period) -> Period + +Returns a sensible `default` value for the input Period by +returning `one(p)` for Year, Month, and Day, and `zero(p)` for +Hour, Minute, Second, and Millisecond. +""" +Dates.default + +doc""" + today() -> Date + +Returns the date portion of `now()`. +""" +Dates.today + +doc""" + unix2datetime(x) -> DateTime + +Takes the number of seconds since unix epoch +""" +Dates.unix2datetime + +doc""" + datetime2unix(dt::DateTime) -> Float64 + +Takes the given DateTime and returns the number of seconds since +the unix epoch as a `Float64`. +""" +Dates.datetime2unix + +doc""" + julian2datetime(julian_days) -> DateTime + +Takes the number of Julian calendar days since epoch +""" +Dates.julian2datetime + +doc""" + datetime2julian(dt::DateTime) -> Float64 + +Takes the given DateTime and returns the number of Julian calendar +days since the julian epoch as a `Float64`. +""" +Dates.datetime2julian + +doc""" + rata2datetime(days) -> DateTime + +Takes the number of Rata Die days since epoch +""" +Dates.rata2datetime + +doc""" + datetime2rata(dt::TimeType) -> Int64 + +Returns the number of Rata Die days since epoch from the given Date +or DateTime. +""" +Dates.datetime2rata + +doc""" + pwd() -> AbstractString + +Get the current working directory. +""" +pwd + +doc""" + cd(dir::AbstractString) + +Set the current working directory. +""" +cd + +doc""" + cd(f[, dir]) + +Temporarily changes the current working directory (HOME if not +specified) and applies function f before returning. +""" +cd + +doc""" + readdir([dir]) -> Vector{ByteString} + +Returns the files and directories in the directory *dir* (or the +current working directory if not given). +""" +readdir + +doc""" + mkdir(path[, mode]) + +Make a new directory with name `path` and permissions `mode`. +mask. +""" +mkdir + +doc""" + mkpath(path[, mode]) + +Create all directories in the given `path`, with permissions +creation mask. +""" +mkpath + +doc""" + symlink(target, link) + +Creates a symbolic link to `target` with the name `link`. +Note: This function raises an error under operating systems that +""" +symlink + +doc""" + readlink(path) -> AbstractString + +Returns the value of a symbolic link `path`. +""" +readlink + +doc""" + chmod(path, mode) + +Change the permissions mode of `path` to `mode`. Only integer +""" +chmod + +doc""" + stat(file) + +Returns a structure whose fields contain information about the +file. The fields of the structure are: +""" +stat + +doc""" + lstat(file) + +Like stat, but for symbolic links gets the info for the link itself +rather than the file it refers to. This function must be called on +a file path rather than a file object or a file descriptor. +""" +lstat + +doc""" + ctime(file) + +Equivalent to stat(file).ctime +""" +ctime + +doc""" + mtime(file) + +Equivalent to stat(file).mtime +""" +mtime + +doc""" + filemode(file) + +Equivalent to stat(file).mode +""" +filemode + +doc""" + filesize(path...) + +Equivalent to stat(file).size +""" +filesize + +doc""" + uperm(file) + +Gets the permissions of the owner of the file as a bitfield of +For allowed arguments, see `stat`. +""" +uperm + +doc""" + gperm(file) + +Like uperm but gets the permissions of the group owning the file +""" +gperm + +doc""" + operm(file) + +Like uperm but gets the permissions for people who neither own the +file nor are a member of the group owning the file +""" +operm + +doc""" + cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + +Copy the file, link, or directory from *src* to *dest*. +If *follow_symlinks=false*, and src is a symbolic link, dst will be +created as a symbolic link. If *follow_symlinks=true* and src is a +symbolic link, dst will be a copy of the file or directory *src* +refers to. +""" +cp + +doc""" + download(url[, localfile]) + +Download a file from the given url, optionally renaming it to the +given local file name. Note that this function relies on the +availability of external tools such as `curl`, `wget` or +production use or situations in which more options are need, please +use a package that provides the desired functionality instead. +""" +download + +doc""" + mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + +Move the file, link, or directory from *src* to *dest*. +""" +mv + +doc""" + rm(path::AbstractString; recursive=false) + +Delete the file, link, or empty directory at the given path. If +contents are removed recursively. +""" +rm + +doc""" + touch(path::AbstractString) + +Update the last-modified timestamp on a file to the current time. +""" +touch + +doc""" + tempname() + +Generate a unique temporary file path. +""" +tempname + +doc""" + tempdir() + +Obtain the path of a temporary directory (possibly shared with +other processes). +""" +tempdir + +doc""" + mktemp([parent=tempdir()]) + +Returns `(path, io)`, where `path` is the path of a new +temporary file in `parent` and `io` is an open file object for +this path. +""" +mktemp + +doc""" + mktempdir([parent=tempdir()]) + +Create a temporary directory in the `parent` directory and return +its path. +""" +mktempdir + +doc""" + isblockdev(path) -> Bool + +Returns `true` if `path` is a block device, `false` +otherwise. +""" +isblockdev + +doc""" + ischardev(path) -> Bool + +Returns `true` if `path` is a character device, `false` +otherwise. +""" +ischardev + +doc""" + isdir(path) -> Bool + +Returns `true` if `path` is a directory, `false` otherwise. +""" +isdir + +doc""" + isexecutable(path) -> Bool + +Returns `true` if the current user has permission to execute +""" +isexecutable + +doc""" + isfifo(path) -> Bool + +Returns `true` if `path` is a FIFO, `false` otherwise. +""" +isfifo + +doc""" + isfile(path) -> Bool + +Returns `true` if `path` is a regular file, `false` +otherwise. +""" +isfile + +doc""" + islink(path) -> Bool + +Returns `true` if `path` is a symbolic link, `false` +otherwise. +""" +islink + +doc""" + ismount(path) -> Bool + +Returns `true` if `path` is a mount point, `false` otherwise. +""" +ismount + +doc""" + ispath(path) -> Bool + +Returns `true` if `path` is a valid filesystem path, `false` +otherwise. +""" +ispath + +doc""" + isreadable(path) -> Bool + +Returns `true` if the current user has permission to read +""" +isreadable + +doc""" + issetgid(path) -> Bool + +Returns `true` if `path` has the setgid flag set, `false` +otherwise. +""" +issetgid + +doc""" + issetuid(path) -> Bool + +Returns `true` if `path` has the setuid flag set, `false` +otherwise. +""" +issetuid + +doc""" + issocket(path) -> Bool + +Returns `true` if `path` is a socket, `false` otherwise. +""" +issocket + +doc""" + issticky(path) -> Bool + +Returns `true` if `path` has the sticky bit set, `false` +otherwise. +""" +issticky + +doc""" + iswritable(path) -> Bool + +Returns `true` if the current user has permission to write to +""" +iswritable + +doc""" + homedir() -> AbstractString + +Return the current user's home directory. +""" +homedir + +doc""" + dirname(path::AbstractString) -> AbstractString + +Get the directory part of a path. +""" +dirname + +doc""" + basename(path::AbstractString) -> AbstractString + +Get the file name part of a path. +""" +basename + +doc""" + @__FILE__() -> AbstractString + +name of the script being run. Returns `nothing` if run from a +REPL or an empty string if evaluated by `julia -e `. +""" +@__FILE__ + +doc""" + isabspath(path::AbstractString) -> Bool + +Determines whether a path is absolute (begins at the root +directory). +""" +isabspath + +doc""" + isdirpath(path::AbstractString) -> Bool + +Determines whether a path refers to a directory (for example, ends +with a path separator). +""" +isdirpath + +doc""" + joinpath(parts...) -> AbstractString + +Join path components into a full path. If some argument is an +absolute path, then prior components are dropped. +""" +joinpath + +doc""" + abspath(path::AbstractString) -> AbstractString + +Convert a path to an absolute path by adding the current directory +if necessary. +""" +abspath + +doc""" + normpath(path::AbstractString) -> AbstractString + +Normalize a path, removing `.` and `..` entries. +""" +normpath + +doc""" + realpath(path::AbstractString) -> AbstractString + +Canonicalize a path by expanding symbolic links and removing `.` +and `..` entries. +""" +realpath + +doc""" + relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString + +Return a relative filepath to path either from the current +directory or from an optional start directory. This is a path +computation: the filesystem is not accessed to confirm the +existence or nature of path or startpath. +""" +relpath + +doc""" + expanduser(path::AbstractString) -> AbstractString + +On Unix systems, replace a tilde character at the start of a path +with the current user's home directory. +""" +expanduser + +doc""" + splitdir(path::AbstractString) -> (AbstractString, AbstractString) + +Split a path into a tuple of the directory name and file name. +""" +splitdir + +doc""" + splitdrive(path::AbstractString) -> (AbstractString, AbstractString) + +On Windows, split a path into the drive letter part and the path +part. On Unix systems, the first component is always the empty +string. +""" +splitdrive + +doc""" + splitext(path::AbstractString) -> (AbstractString, AbstractString) + +If the last component of a path contains a dot, split the path into +everything before the dot and everything including and after the +dot. Otherwise, return a tuple of the argument unmodified and the +empty string. +""" +splitext + +doc""" + open(file_name[, read, write, create, truncate, append]) -> IOStream + +Open a file in a mode specified by five boolean arguments. The +default is to open files for reading only. Returns a stream for +accessing the file. +""" +open + +doc""" + open(file_name[, mode]) -> IOStream + +Alternate syntax for open, where a string-based mode specifier is +used instead of the five booleans. The values of `mode` +correspond to those from `fopen(3)` or Perl `open`, and are +equivalent to setting the following boolean groups: +""" +open + +doc""" + open(f::function, args...) + +Apply the function `f` to the result of `open(args...)` and +close the resulting file descriptor upon completion. +""" +open + +doc""" + IOBuffer() -> IOBuffer + +Create an in-memory I/O stream. +""" +IOBuffer + +doc""" + IOBuffer(size::Int) + +Create a fixed size IOBuffer. The buffer will not grow dynamically. +""" +IOBuffer + +doc""" + IOBuffer(string) + +Create a read-only IOBuffer on the data underlying the given string +""" +IOBuffer + +doc""" + IOBuffer([data][, readable, writable[, maxsize]]) + +Create an IOBuffer, which may optionally operate on a pre-existing +array. If the readable/writable arguments are given, they restrict +whether or not the buffer may be read from or written to +respectively. By default the buffer is readable but not writable. +The last argument optionally specifies a size beyond which the +buffer may not be grown. +""" +IOBuffer + +doc""" + takebuf_array(b::IOBuffer) + +Obtain the contents of an `IOBuffer` as an array, without +copying. Afterwards, the IOBuffer is reset to its initial state. +""" +takebuf_array + +doc""" + takebuf_string(b::IOBuffer) + +Obtain the contents of an `IOBuffer` as a string, without +copying. Afterwards, the IOBuffer is reset to its initial state. +""" +takebuf_string + +doc""" + fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + +Create an `IOStream` object from an integer file descriptor. If +descriptor. By default, an `IOStream` is closed when it is +garbage collected. `name` allows you to associate the descriptor +with a named file. +""" +fdio + +doc""" + flush(stream) + +Commit all currently buffered writes to the given stream. +""" +flush + +doc""" + close(stream) + +Close an I/O stream. Performs a `flush` first. +""" +close + +doc""" + write(stream, x) + +Write the canonical binary representation of a value to the given +stream. +""" +write + +doc""" + read(stream, type) + +Read a value of the given type from a stream, in canonical binary +representation. +""" +read + +doc""" + read(stream, type, dims) + +Read a series of values of the given type from a stream, in +canonical binary representation. `dims` is either a tuple or a +series of integer arguments specifying the size of `Array` to +return. +""" +read + +doc""" + read!(stream, array::Array) + +Read binary data from a stream, filling in the argument `array`. +""" +read! + +doc""" + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + +Read at most `nb` bytes from the stream into `b`, returning the +number of bytes read (increasing the size of `b` as needed). +""" +readbytes! + +doc""" + readbytes(stream, nb=typemax(Int)) + +Read at most `nb` bytes from the stream, returning a +""" +readbytes + +doc""" + position(s) + +Get the current position of a stream. +""" +position + +doc""" + seek(s, pos) + +Seek a stream to the given position. +""" +seek + +doc""" + seekstart(s) + +Seek a stream to its beginning. +""" +seekstart + +doc""" + seekend(s) + +Seek a stream to its end. +""" +seekend + +doc""" + skip(s, offset) + +Seek a stream relative to the current position. +""" +skip + +doc""" + mark(s) + +Add a mark at the current position of stream `s`. Returns the +marked position. +See also `unmark()`, `reset()`, `ismarked()` +""" +mark + +doc""" + unmark(s) + +Remove a mark from stream `s`. Returns `true` if the stream was +marked, `false` otherwise. +See also `mark()`, `reset()`, `ismarked()` +""" +unmark + +doc""" + reset(s) + +Reset a stream `s` to a previously marked position, and remove +the mark. Returns the previously marked position. Throws an error +if the stream is not marked. +See also `mark()`, `unmark()`, `ismarked()` +""" +reset + +doc""" + ismarked(s) + +Returns true if stream `s` is marked. +See also `mark()`, `unmark()`, `reset()` +""" +ismarked + +doc""" + eof(stream) -> Bool + +Tests whether an I/O stream is at end-of-file. If the stream is not +yet exhausted, this function will block to wait for more data if +necessary, and then return `false`. Therefore it is always safe +to read one byte after seeing `eof` return `false`. `eof` +will return `false` as long as buffered data is still available, +even if the remote end of a connection is closed. +""" +eof + +doc""" + isreadonly(stream) -> Bool + +Determine whether a stream is read-only. +""" +isreadonly + +doc""" + isopen(stream) -> Bool + +Determine whether a stream is open (i.e. has not been closed yet). +If the connection has been closed remotely (in case of e.g. a +socket), `isopen` will return `false` even though buffered data +may still be available. Use `eof` to check if necessary. +""" +isopen + +doc""" + serialize(stream, value) + +Write an arbitrary value to a stream in an opaque format, such that +it can be read back by `deserialize`. The read-back value will be +as identical as possible to the original. In general, this process +will not work if the reading and writing are done by different +versions of Julia, or an instance of Julia with a different system +image. +""" +serialize + +doc""" + deserialize(stream) + +Read a value written by `serialize`. +""" +deserialize + +doc""" + print_escaped(io, str::AbstractString, esc::AbstractString) + +General escaping of traditional C and Unicode escape sequences, +plus any characters in esc are also escaped (with a backslash). +""" +print_escaped + +doc""" + print_unescaped(io, s::AbstractString) + +General unescaping of traditional C and Unicode escape sequences. +Reverse of `print_escaped()`. +""" +print_unescaped + +doc""" + print_joined(io, items, delim[, last]) + +Print elements of `items` to `io` with `delim` between them. +If `last` is specified, it is used as the final delimiter instead +of `delim`. +""" +print_joined + +doc""" + print_shortest(io, x) + +Print the shortest possible representation, with the minimum number +of consecutive non-zero digits, of number `x`, ensuring that it +would parse to the exact same number. +""" +print_shortest + +doc""" + fd(stream) + +Returns the file descriptor backing the stream or file. Note that +this function only applies to synchronous *File*'s and *IOStream*'s +not to any of the asynchronous streams. +""" +fd + +doc""" + redirect_stdout() + +Create a pipe to which all C and Julia level STDOUT output will be +redirected. Returns a tuple (rd,wr) representing the pipe ends. +Data written to STDOUT may now be read from the rd end of the pipe. +The wr end is given for convenience in case the old STDOUT object +was cached by the user and needs to be replaced elsewhere. +""" +redirect_stdout + +doc""" + redirect_stdout(stream) + +Replace STDOUT by stream for all C and julia level output to +STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. +""" +redirect_stdout + +doc""" + redirect_stderr([stream]) + +Like redirect_stdout, but for STDERR +""" +redirect_stderr + +doc""" + redirect_stdin([stream]) + +Like redirect_stdout, but for STDIN. Note that the order of the +return tuple is still (rd,wr), i.e. data to be read from STDIN, may +be written to wr. +""" +redirect_stdin + +doc""" + readchomp(x) + +Read the entirety of x as a string but remove trailing newlines. +Equivalent to chomp(readall(x)). +""" +readchomp + +doc""" + truncate(file, n) + +Resize the file or buffer given by the first argument to exactly +file or buffer is grown +""" +truncate + +doc""" + skipchars(stream, predicate; linecomment::Char) + +Advance the stream until before the first character for which +isspace)` will skip all whitespace. If keyword argument +through the end of a line will also be skipped. +""" +skipchars + +doc""" + countlines(io[, eol::Char]) + +Read io until the end of the stream/file and count the number of +non-empty lines. To specify a file pass the filename as the first +argument. EOL markers other than '\n' are supported by passing +them as the second argument. +""" +countlines + +doc""" + PipeBuffer() + +An IOBuffer that allows reading and performs writes by appending. +Seeking and truncating are not supported. See IOBuffer for the +available constructors. +""" +PipeBuffer + +doc""" + PipeBuffer(data::Vector{UInt8}[, maxsize]) + +Create a PipeBuffer to operate on a data vector, optionally +specifying a size beyond which the underlying Array may not be +grown. +""" +PipeBuffer + +doc""" + readavailable(stream) + +Read all available data on the stream, blocking the task only if no +data is available. The result is a `Vector{UInt8,1}`. +""" +readavailable + +doc""" + show(x) + +Write an informative text representation of a value to the current +output stream. New types should overload `show(io, x)` where the +first argument is a stream. The representation used by `show` +generally includes Julia-specific formatting and type information. +""" +show + +doc""" + showcompact(x) + +Show a more compact representation of a value. This is used for +printing array elements. If a new type has a different compact +representation, it should overload `showcompact(io, x)` where the +first argument is a stream. +""" +showcompact + +doc""" + showall(x) + +Similar to `show`, except shows all elements of arrays. +""" +showall + +doc""" + summary(x) + +Return a string giving a brief description of a value. By default +returns `string(typeof(x))`. For arrays, returns strings like +""" +summary + +doc""" + print(x) + +Write (to the default output stream) a canonical (un-decorated) +text representation of a value if there is one, otherwise call +formatting and tries to avoid Julia-specific details. +""" +print + +doc""" + println(x) + +Print (using `print()`) `x` followed by a newline. +""" +println + +doc""" + print_with_color(color::Symbol[, io], strings...) + +Print strings in a color specified as a symbol, for example +""" +print_with_color + +doc""" + info(msg) + +Display an informational message. +""" +info + +doc""" + warn(msg) + +Display a warning. +""" +warn + +doc""" + @printf([io::IOStream], "%Fmt", args...) + +Print arg(s) using C `printf()` style format specification +string. Optionally, an IOStream may be passed as the first argument +to redirect output. +""" +@printf + +doc""" + @sprintf("%Fmt", args...) + +Return `@printf` formatted output as string. +""" +@sprintf + +doc""" + sprint(f::Function, args...) + +Call the given function with an I/O stream and the supplied extra +arguments. Everything written to this I/O stream is returned as a +string. +""" +sprint + +doc""" + showerror(io, e) + +Show a descriptive representation of an exception object. +""" +showerror + +doc""" + dump(x) + +Show all user-visible structure of a value. +""" +dump + +doc""" + xdump(x) + +Show all structure of a value, including all fields of objects. +""" +xdump + +doc""" + readall(stream::IO) + +Read the entire contents of an I/O stream as a string. +""" +readall + +doc""" + readall(filename::AbstractString) + +Open `filename`, read the entire contents as a string, then close +the file. Equivalent to `open(readall, filename)`. +""" +readall + +doc""" + readline(stream=STDIN) + +Read a single line of text, including a trailing newline character +""" +readline + +doc""" + readuntil(stream, delim) + +Read a string, up to and including the given delimiter byte. +""" +readuntil + +doc""" + readlines(stream) + +Read all lines as an array. +""" +readlines + +doc""" + eachline(stream) + +Create an iterable object that will yield each line from a stream. +""" +eachline + +doc""" + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + +Read a matrix from the source where each line (separated by +delimeter. The source can be a text file, stream or byte array. +Memory mapped files can be used by passing the byte array +representation of the mapped segment as source. +If `T` is a numeric type, the result is an array of that type, +with any non-numeric elements as `NaN` for floating-point types, +or zero. Other useful values of `T` include `ASCIIString`, +If `header` is `true`, the first row of data will be read as +header and the tuple `(data_cells, header_cells)` is returned +instead of only `data_cells`. +Specifying `skipstart` will ignore the corresponding number of +initial lines from the input. +If `skipblanks` is `true`, blank lines in the input will be +ignored. +If `use_mmap` is `true`, the file specified by `source` is +memory mapped for potential speedups. Default is `true` except on +Windows. On Windows, you may want to specify `true` if the file +is large, and is only read once and not written to. +If `ignore_invalid_chars` is `true`, bytes in `source` with +invalid character encoding will be ignored. Otherwise an error is +thrown indicating the offending character position. +If `quotes` is `true`, column enclosed within double-quote (``) +characters are allowed to contain new lines and column delimiters. +Double-quote characters within a quoted field must be escaped with +another double-quote. +Specifying `dims` as a tuple of the expected rows and columns +If `comments` is `true`, lines beginning with `comment_char` +and text following `comment_char` in any line are ignored. +""" +readdlm + +doc""" + readdlm(source, delim::Char, eol::Char; options...) + +If all data is numeric, the result will be a numeric array. If some +elements cannot be parsed as numbers, a cell array of numbers and +strings is returned. +""" +readdlm + +doc""" + readdlm(source, delim::Char, T::Type; options...) + +The end of line delimiter is taken as `\n`. +""" +readdlm + +doc""" + readdlm(source, delim::Char; options...) + +The end of line delimiter is taken as `\n`. If all data is +numeric, the result will be a numeric array. If some elements +cannot be parsed as numbers, a cell array of numbers and strings is +returned. +""" +readdlm + +doc""" + readdlm(source, T::Type; options...) + +The columns are assumed to be separated by one or more whitespaces. +The end of line delimiter is taken as `\n`. +""" +readdlm + +doc""" + readdlm(source; options...) + +The columns are assumed to be separated by one or more whitespaces. +The end of line delimiter is taken as `\n`. If all data is +numeric, the result will be a numeric array. If some elements +cannot be parsed as numbers, a cell array of numbers and strings is +returned. +""" +readdlm + +doc""" + writedlm(f, A, delim='\t') + +Write `A` (a vector, matrix or an iterable collection of iterable +rows) as text to `f` (either a filename string or an `IO` +stream) using the given delimeter `delim` (which defaults to tab, +but can be any printable Julia object, typically a `Char` or +For example, two vectors `x` and `y` of the same length can be +written as two columns of tab-delimited text to `f` by either +""" +writedlm + +doc""" + readcsv(source, [T::Type]; options...) + +Equivalent to `readdlm` with `delim` set to comma. +""" +readcsv + +doc""" + writecsv(filename, A) + +Equivalent to `writedlm` with `delim` set to comma. +""" +writecsv + +doc""" + Base64EncodePipe(ostream) + +Returns a new write-only I/O stream, which converts any bytes +written to it into base64-encoded ASCII bytes written to +necessary to complete the encoding (but does not close +""" +Base64EncodePipe + +doc""" + Base64DecodePipe(istream) + +Returns a new read-only I/O stream, which decodes base64-encoded +data read from `istream`. +""" +Base64DecodePipe + +doc""" + base64encode(writefunc, args...) + +Given a `write`-like function `writefunc`, which takes an I/O +stream as its first argument, `base64(writefunc, args...)` calls +returns the string. `base64(args...)` is equivalent to +using the standard `write` functions and returns the +base64-encoded string. +""" +base64encode + +doc""" + base64decode(string) + +Decodes the base64-encoded `string` and returns a +""" +base64decode + +doc""" + display(x) + +Display `x` using the topmost applicable display in the display +stack, typically using the richest supported multimedia output for +display `d` only, throwing a `MethodError` if `d` cannot +display objects of this type. +There are also two variants with a `mime` argument (a MIME type +string, such as ``image/png``), which attempt to display `x` +using the requested MIME type *only*, throwing a `MethodError` if +this type is not supported by either the display(s) or by `x`. +With these variants, one can also supply the `raw` data in the +requested MIME type by passing `x::AbstractString` (for MIME +types with text-based storage, such as text/html or +application/postscript) or `x::Vector{UInt8}` (for binary MIME +types). +""" +display + +doc""" + redisplay(x) + +By default, the `redisplay` functions simply call `display`. +However, some display backends may override `redisplay` to modify +an existing display of `x` (if any). Using `redisplay` is +also a hint to the backend that `x` may be redisplayed several +times, and the backend may choose to defer the display until (for +example) the next interactive prompt. +""" +redisplay + +doc""" + displayable(mime) -> Bool + +Returns a boolean value indicating whether the given `mime` type +display stack, or specifically by the display `d` in the second +variant. +""" +displayable + +doc""" + writemime(stream, mime, x) + +The `display` functions ultimately call `writemime` in order to +write an object `x` as a given `mime` type to a given I/O +provide a rich multimedia representation of a user-defined type +for `T`, via: `writemime(stream, ::MIME`mime`, x::T) = ...`, +where `mime` is a MIME-type string and the function body calls +literal strings; to construct `MIME` types in a more flexible +manner use `MIME{symbol(``)}`.) +For example, if you define a `MyImage` type and know how to write +it to a PNG file, you could define a function `writemime(stream, +be displayed on any PNG-capable `Display` (such as IJulia). As +usual, be sure to `import Base.writemime` in order to add new +methods to the built-in Julia function `writemime`. +Technically, the `MIME`mime`` macro defines a singleton type +for the given `mime` string, which allows us to exploit Julia's +dispatch mechanisms in determining how to display objects of any +given type. +""" +writemime + +doc""" + mimewritable(mime, x) + +Returns a boolean value indicating whether or not the object `x` +can be written as the given `mime` type. (By default, this is +determined automatically by the existence of the corresponding +""" +mimewritable + +doc""" + reprmime(mime, x) + +Returns an `AbstractString` or `Vector{UInt8}` containing the +representation of `x` in the requested `mime` type, as written +by `writemime` (throwing a `MethodError` if no appropriate +MIME types with textual representations (such as ``text/html`` +or ``application/postscript``), whereas binary data is returned +as `Vector{UInt8}`. (The function `istext(mime)` returns +whether or not Julia treats a given `mime` type as text.) +As a special case, if `x` is an `AbstractString` (for textual +MIME types) or a `Vector{UInt8}` (for binary MIME types), the +requested `mime` format and simply returns `x`. +""" +reprmime + +doc""" + stringmime(mime, x) + +Returns an `AbstractString` containing the representation of +string. +""" +stringmime + +doc""" + pushdisplay(d::Display) + +Pushes a new display `d` on top of the global display-backend +stack. Calling `display(x)` or `display(mime, x)` will display +topmost backend that does not throw a `MethodError`). +""" +pushdisplay + +doc""" + popdisplay() + +Pop the topmost backend off of the display-backend stack, or the +topmost copy of `d` in the second variant. +""" +popdisplay + +doc""" + TextDisplay(stream) + +Returns a `TextDisplay <: Display`, which can display any object +as the text/plain MIME type (only), writing the text representation +to the given I/O stream. (The text representation is the same as +the way an object is printed in the Julia REPL.) +""" +TextDisplay + +doc""" + istext(m::MIME) + +Determine whether a MIME type is text data. +""" +istext + +doc""" + mmap_array(type, dims, stream[, offset]) + +Create an `Array` whose values are linked to a file, using +memory-mapping. This provides a convenient way of working with data +too large to fit in the computer's memory. +The type determines how the bytes of the array are interpreted. +Note that the file must be stored in binary format, and no format +conversions are possible (this is a limitation of operating +systems, not Julia). +The file is passed via the stream argument. When you initialize +the stream, use ``r`` for a `read-only` array, and ``w+`` +to create a new array used to write values to disk. +Optionally, you can specify an offset (in bytes) if, for example, +you want to skip over a header in the file. The default value for +the offset is the current stream position. +For example, the following code: +creates a `m`-by-`n` `Matrix{Int}`, linked to the file +associated with stream `s`. +A more portable file would need to encode the word size---32 bit or +64 bit---and endianness information in the header. In practice, +consider encoding binary data using standard formats like HDF5 +""" +mmap_array + +doc""" + mmap_bitarray([type], dims, stream[, offset]) + +Create a `BitArray` whose values are linked to a file, using +memory-mapping; it has the same purpose, works in the same way, and +has the same arguments, as `mmap_array()`, but the byte +representation is different. The `type` parameter is optional, +and must be `Bool` if given. +This would create a 25-by-30000 `BitArray`, linked to the file +associated with stream `s`. +""" +mmap_bitarray + +doc""" + msync(array) + +Forces synchronization between the in-memory version of a memory- +mapped `Array` or `BitArray` and the on-disk version. +""" +msync + +doc""" + connect([host], port) -> TcpSocket + +Connect to the host `host` on port `port` +""" +connect + +doc""" + connect(path) -> Pipe + +Connect to the Named Pipe/Domain Socket at `path` +""" +connect + +doc""" + listen([addr], port) -> TcpServer + +Listen on port on the address specified by `addr`. By default +this listens on localhost only. To listen on all interfaces pass, +""" +listen + +doc""" + listen(path) -> PipeServer + +Listens on/Creates a Named Pipe/Domain Socket +""" +listen + +doc""" + getaddrinfo(host) + +Gets the IP address of the `host` (may have to do a DNS lookup) +""" +getaddrinfo + +doc""" + parseip(addr) + +Parse a string specifying an IPv4 or IPv6 ip address. +""" +parseip + +doc""" + IPv4(host::Integer) -> IPv4 + +Returns IPv4 object from ip address formatted as Integer +""" +IPv4 + +doc""" + IPv6(host::Integer) -> IPv6 + +Returns IPv6 object from ip address formatted as Integer +""" +IPv6 + +doc""" + nb_available(stream) + +Returns the number of bytes available for reading before a read +from this stream or buffer will block. +""" +nb_available + +doc""" + accept(server[, client]) + +Accepts a connection on the given server and returns a connection +to the client. An uninitialized client stream may be provided, in +which case it will be used instead of creating a new stream. +""" +accept + +doc""" + listenany(port_hint) -> (UInt16, TcpServer) + +Create a TcpServer on any port, using hint as a starting point. +Returns a tuple of the actual port that the server was created on +and the server itself. +""" +listenany + +doc""" + watch_file(cb=false, s; poll=false) + +Watch file or directory `s` and run callback `cb` when `s` is +modified. The `poll` parameter specifies whether to use file +system event monitoring or polling. The callback function `cb` +should accept 3 arguments: `(filename, events, status)` where +an object with boolean fields `changed` and `renamed` when +using file system event monitoring, or `readable` and +""" +watch_file + +doc""" + poll_fd(fd, seconds::Real; readable=false, writable=false) + +Poll a file descriptor fd for changes in the read or write +availability and with a timeout given by the second argument. If +the timeout is not needed, use `wait(fd)` instead. The keyword +arguments determine which of read and/or write status should be +monitored and at least one of them needs to be set to true. The +returned value is an object with boolean fields `readable`, +""" +poll_fd + +doc""" + poll_file(s, interval_seconds::Real, seconds::Real) + +Monitor a file for changes by polling every *interval_seconds* +seconds for *seconds* seconds. A return value of true indicates the +file changed, a return value of false indicates a timeout. +""" +poll_file + +doc""" + bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + +Bind `socket` to the given `host:port`. Note that *0.0.0.0* +will listen on all devices. +""" +bind + +doc""" + send(socket::UDPSocket, host::IPv4, port::Integer, msg) + +Send `msg` over `socket to ``host:port`. +""" +send + +doc""" + recv(socket::UDPSocket) + +Read a UDP packet from the specified socket, and return the bytes +received. This call blocks. +""" +recv + +doc""" + recvfrom(socket::UDPSocket) -> (address, data) + +Read a UDP packet from the specified socket, returning a tuple of +appropriate. +""" +recvfrom + +doc""" + setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + +Set UDP socket options. `multicast_loop`: loopback for multicast +packets (default: true). `multicast_ttl`: TTL for multicast +packets. `enable_broadcast`: flag must be set to true if socket +will be used for broadcast messages, or else the UDP system will +return an access error (default: false). `ttl`: Time-to-live of +packets sent on the socket. +""" +setopt + +doc""" + ntoh(x) + +Converts the endianness of a value from Network byte order (big- +endian) to that used by the Host. +""" +ntoh + +doc""" + hton(x) + +Converts the endianness of a value from that used by the Host to +Network byte order (big-endian). +""" +hton + +doc""" + ltoh(x) + +Converts the endianness of a value from Little-endian to that used +by the Host. +""" +ltoh + +doc""" + htol(x) + +Converts the endianness of a value from that used by the Host to +Little-endian. +""" +htol + +doc""" + ENDIAN_BOM + +The 32-bit byte-order-mark indicates the native byte order of the +host machine. Little-endian machines will contain the value +0x04030201. Big-endian machines will contain the value 0x01020304. +""" +ENDIAN_BOM + +doc""" + malloc(size::Integer) -> Ptr{Void} + +Call `malloc` from the C standard library. +""" +Libc.malloc + +doc""" + calloc(num::Integer, size::Integer) -> Ptr{Void} + +Call `calloc` from the C standard library. +""" +Libc.calloc + +doc""" + realloc(addr::Ptr, size::Integer) -> Ptr{Void} + +Call `realloc` from the C standard library. +See warning in the documentation for `free` regarding only using +this on memory originally obtained from `malloc`. +""" +Libc.realloc + +doc""" + free(addr::Ptr) + +Call `free` from the C standard library. Only use this on memory +obtained from `malloc`, not on pointers retrieved from other C +libraries. `Ptr` objects obtained from C libraries should be +freed by the free functions defined in that library, to avoid +assertion failures if multiple `libc` libraries exist on the +system. +""" +Libc.free + +doc""" + errno([code]) + +Get the value of the C library's `errno`. If an argument is +specified, it is used to set the value of `errno`. +The value of `errno` is only valid immediately after a `ccall` +to a C library routine that sets it. Specifically, you cannot call +executed between prompts. +""" +Libc.errno + +doc""" + strerror(n) + +Convert a system call error code to a descriptive string +""" +Libc.strerror + +doc""" + time(t::TmStruct) + +Converts a `TmStruct` struct to a number of seconds since the +epoch. +""" +Libc.time + +doc""" + strftime([format], time) + +Convert time, given as a number of seconds since the epoch or a +Supported formats are the same as those in the standard C library. +""" +Libc.strftime + +doc""" + strptime([format], timestr) + +Parse a formatted time string into a `TmStruct` giving the +seconds, minute, hour, date, etc. Supported formats are the same as +those in the standard C library. On some platforms, timezones will +not be parsed correctly. If the result of this function will be +passed to `time` to convert it to seconds since the epoch, the +will tell the C library to use the current system settings to +determine the timezone. +""" +Libc.strptime + +doc""" + TmStruct([seconds]) + +Convert a number of seconds since the epoch to broken-down format, +with fields `sec`, `min`, `hour`, `mday`, `month`, +""" +Libc.TmStruct + +doc""" + flush_cstdio() + +Flushes the C `stdout` and `stderr` streams (which may have +been written to by external C code). +""" +Libc.flush_cstdio + +doc""" + msync(ptr, len[, flags]) + +Forces synchronization of the `mmap()`ped memory region from +combination of `MS_ASYNC`, `MS_SYNC`, or `MS_INVALIDATE`. See +your platform man page for specifics. The flags argument is not +valid on Windows. +You may not need to call `msync`, because synchronization is +performed at intervals automatically by the operating system. +However, you can call this directly if, for example, you are +concerned about losing the result of a long-running calculation. +""" +Libc.msync + +doc""" + MS_ASYNC + +Enum constant for `msync()`. See your platform man page for +details. (not available on Windows). +""" +Libc.MS_ASYNC + +doc""" + MS_SYNC + +Enum constant for `msync()`. See your platform man page for +details. (not available on Windows). +""" +Libc.MS_SYNC + +doc""" + MS_INVALIDATE + +Enum constant for `msync()`. See your platform man page for +details. (not available on Windows). +""" +Libc.MS_INVALIDATE + +doc""" + mmap(len, prot, flags, fd, offset) + +Low-level interface to the `mmap` system call. See the man page. +""" +Libc.mmap + +doc""" + munmap(pointer, len) + +Low-level interface for unmapping memory (see the man page). With +is unmapped for you when the array goes out of scope. +""" +Libc.munmap + +doc""" + dlopen(libfile::AbstractString[, flags::Integer]) + +Load a shared library, returning an opaque handle. +The optional flags argument is a bitwise-or of zero or more of +the POSIX (and/or GNU libc and/or MacOS) dlopen command, if +possible, or are ignored if the specified functionality is not +available on the current platform. The default is +these flags, on POSIX platforms, is to specify +symbols to be available for usage in other shared libraries, in +situations where there are dependencies between shared libraries. +""" +Libdl.dlopen + +doc""" + dlopen_e(libfile::AbstractString[, flags::Integer]) + +Similar to `dlopen()`, except returns a `NULL` pointer instead +of raising errors. +""" +Libdl.dlopen_e + +doc""" + RTLD_DEEPBIND + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_DEEPBIND + +doc""" + RTLD_FIRST + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_FIRST + +doc""" + RTLD_GLOBAL + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_GLOBAL + +doc""" + RTLD_LAZY + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_LAZY + +doc""" + RTLD_LOCAL + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_LOCAL + +doc""" + RTLD_NODELETE + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_NODELETE + +doc""" + RTLD_NOLOAD + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_NOLOAD + +doc""" + RTLD_NOW + +Enum constant for `dlopen()`. See your platform man page for +details, if applicable. +""" +Libdl.RTLD_NOW + +doc""" + dlsym(handle, sym) + +Look up a symbol from a shared library handle, return callable +function pointer on success. +""" +Libdl.dlsym + +doc""" + dlsym_e(handle, sym) + +Look up a symbol from a shared library handle, silently return NULL +pointer on lookup failure. +""" +Libdl.dlsym_e + +doc""" + dlclose(handle) + +Close shared library referenced by handle. +""" +Libdl.dlclose + +doc""" + find_library(names, locations) + +Searches for the first library in `names` in the paths in the +that order) which can successfully be dlopen'd. On success, the +return value will be one of the names (potentially prefixed by one +of the paths in locations). This string can be assigned to a +""" +Libdl.find_library + +doc""" + DL_LOAD_PATH + +When calling `dlopen`, the paths in this list will be searched +first, in order, before searching the system locations for a valid +library handle. +""" +Libdl.DL_LOAD_PATH + +doc""" + *(A, B) + +Matrix multiplication +""" +Base.(:(*)) + +doc""" + \(A, B) + +Matrix division using a polyalgorithm. For input matrices `A` and +square. The solver that is used depends upon the structure of +complex `A`) the `BunchKaufman` factorization is used. +Otherwise an LU factorization is used. For rectangular `A` the +result is the minimum-norm least squares solution computed by a +pivoted QR factorization of `A` and a rank estimate of A based on +the R factor. +When `A` is sparse, a similar polyalgorithm is used. For +indefinite matrices, the LDLt factorization does not use pivoting +during the numerical factorization and therefore the procedure can +fail even for invertible matrices. +""" +Base.(:(\)) + +doc""" + dot(x, y) + +Compute the dot product. For complex vectors, the first vector is +conjugated. +""" +dot + +doc""" + vecdot(x, y) + +For any iterable containers `x` and `y` (including arrays of +any dimension) of numbers (or any element type for which `dot` is +defined), compute the Euclidean dot product (the sum of +""" +vecdot + +doc""" + cross(x, y) + +Compute the cross product of two 3-vectors. +""" +cross + +doc""" + factorize(A) + +Compute a convenient factorization (including LU, Cholesky, Bunch- +Kaufman, LowerTriangular, UpperTriangular) of A, based upon the +type of the input matrix. The return value can then be reused for +efficient solving of multiple systems. For example: +""" +factorize + +doc""" + full(F) + +Reconstruct the matrix `A` from the factorization +""" +full + +doc""" + lu(A) -> L, U, p + +Compute the LU factorization of `A`, such that `A[p,:] = L*U`. +""" +lu + +doc""" + lufact(A[, pivot=Val{true}]) -> F + +Compute the LU factorization of `A`. The return type of `F` +depends on the type of `A`. In most cases, if `A` is a subtype +pivoting is chosen (default) the element type should also support +examples are shown in the table below. +The individual components of the factorization `F` can be +accessed by indexing: +""" +lufact + +doc""" + lufact!(A) -> LU + +overwriting the input A, instead of creating a copy. For sparse +1-based indices to 0-based indices. +""" +lufact! + +doc""" + chol(A[, LU]) -> F + +Compute the Cholesky factorization of a symmetric positive definite +matrix `A` and return the matrix `F`. If `LU` is `Val{:U}` +and `A = F*F'`. `LU` defaults to `Val{:U}`. +""" +chol + +doc""" + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + +Compute the Cholesky factorization of a dense symmetric positive +or `:U` for the upper part. The default is to use `:U`. The +triangular matrix can be obtained from the factorization `F` +with: `F[:L]` and `F[:U]`. The following functions are +available for `Cholesky` objects: `size`, `\`, `inv`, +If `pivot==Val{false}` a `PosDefException` exception is thrown +in case the matrix is not positive definite. The argument `tol` +determines the tolerance for determining the rank. For negative +values, the tolerance is the machine precision. +""" +cholfact + +doc""" + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + +Compute the Cholesky factorization of a sparse positive definite +matrix `A`. A fill-reducing permutation is used. `F = +cholfact(A)` is most frequently used to solve systems of equations +with `F\b`, but also the methods `diag`, `det`, `logdet` +are defined for `F`. You can also extract individual factors +from `F`, using `F[:L]`. However, since pivoting is on by +default, the factorization is internally represented as `A == +P'*L*L'*P` with a permutation matrix `P`; using just `L` +without accounting for `P` will give incorrect answers. To +include the effects of permutation, it's typically preferable to +extact `combined` factors like `PtL = F[:PtL]` (the equivalent +of `P'*L`) and `LtP = F[:UP]` (the equivalent of `L'*P`). +Setting optional `shift` keyword argument computes the +factorization of `A+shift*I` instead of `A`. If the `perm` +argument is nonempty, it should be a permutation of *1:size(A,1)* +giving the ordering to use (instead of CHOLMOD's default AMD +ordering). +The function calls the C library CHOLMOD and many other functions +from the library are wrapped but not exported. +""" +cholfact + +doc""" + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + +overwriting the input `A`, instead of creating a copy. +different matrix `F` with the same structure when used as: +""" +cholfact! + +doc""" + ldltfact(A) -> LDLtFactorization + +Compute a factorization of a positive definite matrix `A` such +that `A=L*Diagonal(d)*L'` where `L` is a unit lower triangular +matrix and `d` is a vector with non-negative elements. +""" +ldltfact + +doc""" + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + +Compute the LDLt factorization of a sparse symmetric or Hermitian +matrix `A`. A fill-reducing permutation is used. `F = +ldltfact(A)` is most frequently used to solve systems of equations +with `F\b`, but also the methods `diag`, `det`, `logdet` +are defined for `F`. You can also extract individual factors from +the factorization is internally represented as `A == P'*L*D*L'*P` +with a permutation matrix `P`; using just `L` without +accounting for `P` will give incorrect answers. To include the +effects of permutation, it's typically preferable to extact +complete list of supported factors is `:L, :PtL, :D, :UP, :U, :LD, +Setting optional `shift` keyword argument computes the +factorization of `A+shift*I` instead of `A`. If the `perm` +argument is nonempty, it should be a permutation of *1:size(A,1)* +giving the ordering to use (instead of CHOLMOD's default AMD +ordering). +The function calls the C library CHOLMOD and many other functions +from the library are wrapped but not exported. +""" +ldltfact + +doc""" + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + +Compute the (pivoted) QR factorization of `A` such that either +is to compute a thin factorization. Note that `R` is not extended +with zeros when the full `Q` is requested. +""" +qr + +doc""" + qrfact(A[, pivot=Val{false}]) -> F + +Computes the QR factorization of `A`. The return type of `F` +depends on the element type of `A` and whether pivoting is +specified (with `pivot==Val{true}`). +The individual components of the factorization `F` can be +accessed by indexing: +The following functions are available for the `QR` objects: +least squares solution and if the solution is not unique, the one +with smallest norm is returned. +Multiplication with respect to either thin or full `Q` is +allowed, i.e. both `F[:Q]*F[:R]` and `F[:Q]*A` are supported. A +which has a named argument `thin`. +Note: `qrfact` returns multiple types because LAPACK uses +""" +qrfact + +doc""" + qrfact(A) -> SPQR.Factorization + +Compute the QR factorization of a sparse matrix `A`. A fill- +reducing permutation is used. The main application of this type is +to solve least squares problems with `\`. The function calls the +C library SPQR and a few additional functions from the library are +wrapped but not exported. +""" +qrfact + +doc""" + qrfact!(A[, pivot=Val{false}]) + +instead of creating a copy. +""" +qrfact! + +doc""" + full(QRCompactWYQ[, thin=true]) -> Matrix + +Converts an orthogonal or unitary matrix stored as a +Optionally takes a `thin` Boolean argument, which if `true` +omits the columns that span the rows of `R` in the QR +factorization that are zero. The resulting matrix is the `Q` in a +thin QR factorization (sometimes called the reduced QR +factorization). If `false`, returns a `Q` that spans all rows +of `R` in its corresponding QR factorization. +""" +full + +doc""" + bkfact(A) -> BunchKaufman + +Compute the Bunch-Kaufman [Bunch1977] factorization of a real +symmetric or complex Hermitian matrix `A` and return a +""" +bkfact + +doc""" + bkfact!(A) -> BunchKaufman + +overwriting the input `A`, instead of creating a copy. +""" +bkfact! + +doc""" + sqrtm(A) + +Compute the matrix square root of `A`. If `B = sqrtm(A)`, then +using Schur factorizations (`schurfact()`) unless it detects the +matrix to be Hermitian or real symmetric, in which case it computes +the matrix square root from an eigendecomposition (`eigfact()`). +In the latter situation for positive definite matrices, the matrix +square root has `Real` elements, otherwise it has `Complex` +elements. +""" +sqrtm + +doc""" + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + +Computes eigenvalues and eigenvectors of `A`. See `eigfact()` +for details on the `balance` keyword argument. +the factorization to a tuple; where possible, using `eigfact()` +is recommended. +""" +eig + +doc""" + eig(A, B) -> D, V + +Computes generalized eigenvalues and vectors of `A` with respect +to `B`. +the factorization to a tuple; where possible, using `eigfact()` +is recommended. +""" +eig + +doc""" + eigvals(A,[irange,][vl,][vu]) + +Returns the eigenvalues of `A`. If `A` is `Symmetric`, +only a subset of the eigenvalues by specifying either a +eigenvalues, or a pair `vl` and `vu` for the lower and upper +boundaries of the eigenvalues. +For general non-symmetric matrices it is possible to specify how +the matrix is balanced before the eigenvector calculation. The +option `permute=true` permutes the matrix to become closer to +upper triangular, and `scale=true` scales the matrix by its +diagonal elements to make rows and columns more equal in norm. The +default is `true` for both options. +""" +eigvals + +doc""" + eigmax(A) + +Returns the largest eigenvalue of `A`. +""" +eigmax + +doc""" + eigmin(A) + +Returns the smallest eigenvalue of `A`. +""" +eigmin + +doc""" + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + +Returns a matrix `M` whose columns are the eigenvectors of `A`. +k]`.) The `permute` and `scale` keywords are the same as for +For `SymTridiagonal` matrices, if the optional vector of +eigenvalues `eigvals` is specified, returns the specific +corresponding eigenvectors. +""" +eigvecs + +doc""" + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + +Computes the eigenvalue decomposition of `A`, returning an +in `F[:values]` and the eigenvectors in the columns of the matrix +slice `F[:vectors][:, k]`.) +The following functions are available for `Eigen` objects: +If `A` is `Symmetric`, `Hermitian` or `SymTridiagonal`, it +is possible to calculate only a subset of the eigenvalues by +specifying either a `UnitRange` `irange` covering indices of +the sorted eigenvalues or a pair `vl` and `vu` for the lower +and upper boundaries of the eigenvalues. +For general nonsymmetric matrices it is possible to specify how the +matrix is balanced before the eigenvector calculation. The option +triangular, and `scale=true` scales the matrix by its diagonal +elements to make rows and columns more equal in norm. The default +is `true` for both options. +""" +eigfact + +doc""" + eigfact(A, B) -> GeneralizedEigen + +Computes the generalized eigenvalue decomposition of `A` and +which contains the generalized eigenvalues in `F[:values]` and +the generalized eigenvectors in the columns of the matrix +obtained from the slice `F[:vectors][:, k]`.) +""" +eigfact + +doc""" + eigfact!(A[, B]) + +Same as `eigfact()`, but saves space by overwriting the input +""" +eigfact! + +doc""" + hessfact(A) + +Compute the Hessenberg decomposition of `A` and return a +unitary matrix can be accessed with `F[:Q]` and the Hessenberg +matrix with `F[:H]`. When `Q` is extracted, the resulting type +is the `HessenbergQ` object, and may be converted to a regular +matrix with `full()`. +""" +hessfact + +doc""" + hessfact!(A) + +overwriting the input A, instead of creating a copy. +""" +hessfact! + +doc""" + schurfact(A) -> Schur + +Computes the Schur factorization of the matrix `A`. The (quasi) +triangular Schur factor can be obtained from the `Schur` object +unitary/orthogonal Schur vectors can be obtained with +can be obtained with `F[:values]`. +""" +schurfact + +doc""" + schurfact!(A) + +Computes the Schur factorization of `A`, overwriting `A` in the +process. See `schurfact()` +""" +schurfact! + +doc""" + schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + +See `schurfact()` +""" +schur + +doc""" + ordschur(Q, T, select) -> Schur + +Reorders the Schur factorization of a real matrix `A=Q*T*Q'` +according to the logical array `select` returning a Schur object +right invariant subspace. A complex conjugate pair of eigenvalues +must be either both included or excluded via `select`. +""" +ordschur + +doc""" + ordschur!(Q, T, select) -> Schur + +Reorders the Schur factorization of a real matrix `A=Q*T*Q'`, +overwriting `Q` and `T` in the process. See `ordschur()` +""" +ordschur! + +doc""" + ordschur(S, select) -> Schur + +Reorders the Schur factorization `S` of type `Schur`. +""" +ordschur + +doc""" + ordschur!(S, select) -> Schur + +Reorders the Schur factorization `S` of type `Schur`, +overwriting `S` in the process. See `ordschur()` +""" +ordschur! + +doc""" + schurfact(A, B) -> GeneralizedSchur + +Computes the Generalized Schur (or QZ) factorization of the +matrices `A` and `B`. The (quasi) triangular Schur factors can +be obtained from the `Schur` object `F` with `F[:S]` and +obtained with `F[:left]` or `F[:Q]` and the right +unitary/orthogonal Schur vectors can be obtained with `F[:right]` +or `F[:Z]` such that `A=F[:left]*F[:S]*F[:right]'` and +""" +schurfact + +doc""" + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + +See `schurfact()` +""" +schur + +doc""" + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a matrix `(A, B) = +and returns a GeneralizedSchur object `GS`. The selected +eigenvalues appear in the leading diagonal of both``(GS[:S], +GS[:T])`` and the left and right unitary/orthogonal Schur vectors +are also reordered such that `(A, B) = GS[:Q]*(GS[:S], +GS[:T])*GS[:Z]^{H}` still holds and the generalized eigenvalues of +""" +ordschur + +doc""" + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a matrix by +overwriting the matrices `(S, T, Q, Z)` in the process. See +""" +ordschur! + +doc""" + ordschur(GS, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a Generalized Schur +object. See `ordschur()`. +""" +ordschur + +doc""" + ordschur!(GS, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a Generalized Schur +object by overwriting the object with the new factorization. See +""" +ordschur! + +doc""" + svdfact(A[, thin=true]) -> SVD + +Compute the Singular Value Decomposition (SVD) of `A` and return +an `SVD` object. `U`, `S`, `V` and `Vt` can be obtained +from the factorization `F` with `F[:U]`, `F[:S]`, `F[:V]` +and `F[:Vt]`, such that `A = U*diagm(S)*Vt`. If `thin` is +produces `Vt` and hence `Vt` is more efficient to extract than +""" +svdfact + +doc""" + svdfact!(A[, thin=true]) -> SVD + +overwriting the input A, instead of creating a copy. If `thin` is +to produce a thin decomposition. +""" +svdfact! + +doc""" + svd(A[, thin=true]) -> U, S, V + +Wrapper around `svdfact` extracting all parts the factorization +to a tuple. Direct use of `svdfact` is therefore generally more +efficient. Computes the SVD of A, returning `U`, vector `S`, +and `V` such that `A == U*diagm(S)*V'`. If `thin` is +to produce a thin decomposition. +""" +svd + +doc""" + svdvals(A) + +Returns the singular values of `A`. +""" +svdvals + +doc""" + svdvals!(A) + +Returns the singular values of `A`, while saving space by +overwriting the input. +""" +svdvals! + +doc""" + svdfact(A, B) -> GeneralizedSVD + +Compute the generalized SVD of `A` and `B`, returning a +F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = +F[:V]*F[:D2]*F[:R0]*F[:Q]'`. +""" +svdfact + +doc""" + svd(A, B) -> U, V, Q, D1, D2, R0 + +Wrapper around `svdfact` extracting all parts the factorization +to a tuple. Direct use of `svdfact` is therefore generally more +efficient. The function returns the generalized SVD of `A` and +such that `A = U*D1*R0*Q'` and `B = V*D2*R0*Q'`. +""" +svd + +doc""" + svdvals(A, B) + +Return only the singular values from the generalized singular value +decomposition of `A` and `B`. +""" +svdvals + +doc""" + triu(M) + +Upper triangle of a matrix. +""" +triu + +doc""" + triu(M, k) + +Returns the upper triangle of `M` starting from the `k`th +superdiagonal. +""" +triu + +doc""" + triu!(M) + +Upper triangle of a matrix, overwriting `M` in the process. +""" +triu! + +doc""" + triu!(M, k) + +Returns the upper triangle of `M` starting from the `k`th +superdiagonal, overwriting `M` in the process. +""" +triu! + +doc""" + tril(M) + +Lower triangle of a matrix. +""" +tril + +doc""" + tril(M, k) + +Returns the lower triangle of `M` starting from the `k`th +subdiagonal. +""" +tril + +doc""" + tril!(M) + +Lower triangle of a matrix, overwriting `M` in the process. +""" +tril! + +doc""" + tril!(M, k) + +Returns the lower triangle of `M` starting from the `k`th +subdiagonal, overwriting `M` in the process. +""" +tril! + +doc""" + diagind(M[, k]) + +A `Range` giving the indices of the `k`th diagonal of the +matrix `M`. +""" +diagind + +doc""" + diag(M[, k]) + +The `k`th diagonal of a matrix, as a vector. Use `diagm` to +construct a diagonal matrix. +""" +diag + +doc""" + diagm(v[, k]) + +Construct a diagonal matrix and place `v` on the `k`th +diagonal. +""" +diagm + +doc""" + scale(A, b) + +""" +scale + +doc""" + scale(b, A) + +Scale an array `A` by a scalar `b`, returning a new array. +If `A` is a matrix and `b` is a vector, then `scale(A,b)` +scales each column `i` of `A` by `b[i]` (similar to +array. +Note: for large `A`, `scale` can be much faster than `A .* b` +or `b .* A`, due to the use of BLAS. +""" +scale + +doc""" + scale!(A, b) + +""" +scale! + +doc""" + scale!(b, A) + +Scale an array `A` by a scalar `b`, similar to `scale()` but +overwriting `A` in-place. +If `A` is a matrix and `b` is a vector, then `scale!(A,b)` +scales each column `i` of `A` by `b[i]` (similar to +place on `A`. +""" +scale! + +doc""" + Tridiagonal(dl, d, du) + +Construct a tridiagonal matrix from the lower diagonal, diagonal, +and upper diagonal, respectively. The result is of type +but may be converted into a regular matrix with `full()`. +""" +Tridiagonal + +doc""" + Bidiagonal(dv, ev, isupper) + +Constructs an upper (`isupper=true`) or lower (`isupper=false`) +bidiagonal matrix using the given diagonal (`dv`) and off- +diagonal (`ev`) vectors. The result is of type `Bidiagonal` +and provides efficient specialized linear solvers, but may be +converted into a regular matrix with `full()`. +""" +Bidiagonal + +doc""" + SymTridiagonal(d, du) + +Construct a real symmetric tridiagonal matrix from the diagonal and +upper diagonal, respectively. The result is of type +but may be converted into a regular matrix with `full()`. +""" +SymTridiagonal + +doc""" + rank(M) + +Compute the rank of a matrix. +""" +rank + +doc""" + norm(A[, p]) + +Compute the `p`-norm of a vector or the operator norm of a matrix +For vectors, `p` can assume any numeric value (even though not +all values produce a mathematically valid vector norm). In +particular, `norm(A, Inf)` returns the largest value in +For matrices, valid values of `p` are `1`, `2`, or `Inf`. +implemented.) Use `vecnorm()` to compute the Frobenius norm. +""" +norm + +doc""" + vecnorm(A[, p]) + +For any iterable container `A` (including arrays of any +dimension) of numbers (or any element type for which `norm` is +defined), compute the `p`-norm (defaulting to `p=2`) as if +For example, if `A` is a matrix and `p=2`, then this is +equivalent to the Frobenius norm. +""" +vecnorm + +doc""" + cond(M[, p]) + +Condition number of the matrix `M`, computed using the operator +""" +cond + +doc""" + condskeel(M[, x, p]) + +Skeel condition number \kappa_S of the matrix `M`, optionally +with respect to the vector `x`, as computed using the operator +values for `p` are `1`, `2`, or `Inf`. +This quantity is also known in the literature as the Bauer +condition number, relative condition number, or componentwise +relative condition number. +""" +condskeel + +doc""" + trace(M) + +Matrix trace +""" +trace + +doc""" + det(M) + +Matrix determinant +""" +det + +doc""" + logdet(M) + +Log of matrix determinant. Equivalent to `log(det(M))`, but may +provide increased accuracy and/or speed. +""" +logdet + +doc""" + inv(M) + +Matrix inverse +""" +inv + +doc""" + pinv(M[, tol]) + +Computes the Moore-Penrose pseudoinverse. +For matrices `M` with floating point elements, it is convenient +to compute the pseudoinverse by inverting only singular values +above a given threshold, `tol`. +The optimal choice of `tol` varies both with the value of `M` +and the intended application of the pseudoinverse. The default +value of `tol` is +essentially machine epsilon for the real part of a matrix element +multiplied by the larger matrix dimension. For inverting dense ill- +conditioned matrices in a least-squares sense, `tol = +sqrt(eps(real(float(one(eltype(M))))))` is recommended. +For more information, see [8859], [B96], [S84], [KY88]. +""" +pinv + +doc""" + nullspace(M) + +Basis for nullspace of `M`. +""" +nullspace + +doc""" + repmat(A, n, m) + +Construct a matrix by repeating the given matrix `n` times in +dimension 1 and `m` times in dimension 2. +""" +repmat + +doc""" + repeat(A, inner = Int[], outer = Int[]) + +Construct an array by repeating the entries of `A`. The i-th +element of `inner` specifies the number of times that the +individual entries of the i-th dimension of `A` should be +repeated. The i-th element of `outer` specifies the number of +times that a slice along the i-th dimension of `A` should be +repeated. +""" +repeat + +doc""" + kron(A, B) + +Kronecker tensor product of two vectors or two matrices. +""" +kron + +doc""" + blkdiag(A...) + +Concatenate matrices block-diagonally. Currently only implemented +for sparse matrices. +""" +blkdiag + +doc""" + linreg(x, y) -> [a; b] + +Linear Regression. Returns `a` and `b` such that `a+b*x` is +the closest line to the given points `(x,y)`. In other words, +this function determines parameters `[a, b]` that minimize the +squared error between `y` and `a+b*x`. +""" +linreg + +doc""" + linreg(x, y, w) + +Weighted least-squares linear regression. +""" +linreg + +doc""" + expm(A) + +Matrix exponential. +""" +expm + +doc""" + lyap(A, C) + +Computes the solution `X` to the continuous Lyapunov equation +part and no two eigenvalues are negative complex conjugates of each +other. +""" +lyap + +doc""" + sylvester(A, B, C) + +Computes the solution `X` to the Sylvester equation `AX + XB + C +""" +sylvester + +doc""" + issym(A) -> Bool + +Test whether a matrix is symmetric. +""" +issym + +doc""" + isposdef(A) -> Bool + +Test whether a matrix is positive definite. +""" +isposdef + +doc""" + isposdef!(A) -> Bool + +Test whether a matrix is positive definite, overwriting `A` in +the processes. +""" +isposdef! + +doc""" + istril(A) -> Bool + +Test whether a matrix is lower triangular. +""" +istril + +doc""" + istriu(A) -> Bool + +Test whether a matrix is upper triangular. +""" +istriu + +doc""" + isdiag(A) -> Bool + +Test whether a matrix is diagonal. +""" +isdiag + +doc""" + ishermitian(A) -> Bool + +Test whether a matrix is Hermitian. +""" +ishermitian + +doc""" + transpose(A) + +The transposition operator (`.'`). +""" +transpose + +doc""" + transpose!(dest, src) + +Transpose array `src` and store the result in the preallocated +array `dest`, which should have a size corresponding to +supported and unexpected results will happen if *src* and *dest* +have overlapping memory regions. +""" +transpose! + +doc""" + ctranspose(A) + +The conjugate transposition operator (`'`). +""" +ctranspose + +doc""" + ctranspose!(dest, src) + +Conjugate transpose array `src` and store the result in the +preallocated array `dest`, which should have a size corresponding +to `(size(src,2),size(src,1))`. No in-place transposition is +supported and unexpected results will happen if *src* and *dest* +have overlapping memory regions. +""" +ctranspose! + +doc""" + eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) + +Computes eigenvalues `d` of `A` using Lanczos or Arnoldi +iterations for real symmetric or general nonsymmetric matrices +respectively. If `B` is provided, the generalized eigenproblem is +solved. +The following keyword arguments are supported: +corresponding Ritz vectors `v` (only if `ritzvec=true`), the +number of converged eigenvalues `nconv`, the number of iterations +Note: The `sigma` and `which` keywords interact: the +""" +eigs + +doc""" + svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + +Lanczos or Arnoldi iterations. Uses `eigs()` underneath. +Inputs are: +""" +svds + +doc""" + peakflops(n; parallel=false) + +double precision `Base.LinAlg.BLAS.gemm!()`. By default, if no +arguments are specified, it multiplies a matrix of size `n x n`, +where `n = 2000`. If the underlying BLAS is using multiple +threads, higher flop rates are realized. The number of BLAS threads +can be set with `blas_set_num_threads(n)`. +If the keyword argument `parallel` is set to `true`, +flop rate of the entire parallel computer is returned. When running +in parallel, only 1 BLAS thread is used. The argument `n` still +refers to the size of the problem that is solved on each processor. +""" +peakflops + +doc""" + dot(n, X, incx, Y, incy) + +Dot product of two vectors consisting of `n` elements of array +stride `incy`. +""" +Base.LinAlg.BLAS.dot + +doc""" + dotu(n, X, incx, Y, incy) + +Dot function for two complex vectors. +""" +Base.LinAlg.BLAS.dotu + +doc""" + dotc(n, X, incx, U, incy) + +Dot function for two complex vectors conjugating the first vector. +""" +Base.LinAlg.BLAS.dotc + +doc""" + blascopy!(n, X, incx, Y, incy) + +Copy `n` elements of array `X` with stride `incx` to array +""" +Base.LinAlg.BLAS.blascopy! + +doc""" + nrm2(n, X, incx) + +2-norm of a vector consisting of `n` elements of array `X` with +stride `incx`. +""" +Base.LinAlg.BLAS.nrm2 + +doc""" + asum(n, X, incx) + +sum of the absolute values of the first `n` elements of array +""" +Base.LinAlg.BLAS.asum + +doc""" + axpy!(a, X, Y) + +Overwrite `Y` with `a*X + Y`. Returns `Y`. +""" +Base.LinAlg.BLAS.axpy! + +doc""" + scal!(n, a, X, incx) + +Overwrite `X` with `a*X`. Returns `X`. +""" +Base.LinAlg.BLAS.scal! + +doc""" + scal(n, a, X, incx) + +Returns `a*X`. +""" +Base.LinAlg.BLAS.scal + +doc""" + ger!(alpha, x, y, A) + +Rank-1 update of the matrix `A` with vectors `x` and `y` as +""" +Base.LinAlg.BLAS.ger! + +doc""" + syr!(uplo, alpha, x, A) + +Rank-1 update of the symmetric matrix `A` with vector `x` as +""" +Base.LinAlg.BLAS.syr! + +doc""" + syrk!(uplo, trans, alpha, A, beta, C) + +Rank-k update of the symmetric matrix `C` as `alpha*A*A.' + +beta*C` or `alpha*A.'*A + beta*C` according to whether `trans` +is 'N' or 'T'. When `uplo` is 'U' the upper triangle of `C` is +updated ('L' for lower triangle). Returns `C`. +""" +Base.LinAlg.BLAS.syrk! + +doc""" + syrk(uplo, trans, alpha, A) + +Returns either the upper triangle or the lower triangle, according +to `uplo` ('U' or 'L'), of `alpha*A*A.'` or `alpha*A.'*A`, +according to `trans` ('N' or 'T'). +""" +Base.LinAlg.BLAS.syrk + +doc""" + her!(uplo, alpha, x, A) + +Methods for complex arrays only. Rank-1 update of the Hermitian +matrix `A` with vector `x` as `alpha*x*x' + A`. When +lower triangle). Returns `A`. +""" +Base.LinAlg.BLAS.her! + +doc""" + herk!(uplo, trans, alpha, A, beta, C) + +Methods for complex arrays only. Rank-k update of the Hermitian +matrix `C` as `alpha*A*A' + beta*C` or `alpha*A'*A + beta*C` +according to whether `trans` is 'N' or 'T'. When `uplo` is 'U' +the upper triangle of `C` is updated ('L' for lower triangle). +Returns `C`. +""" +Base.LinAlg.BLAS.herk! + +doc""" + herk(uplo, trans, alpha, A) + +Methods for complex arrays only. Returns either the upper triangle +or the lower triangle, according to `uplo` ('U' or 'L'), of +""" +Base.LinAlg.BLAS.herk + +doc""" + gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) + +Update vector `y` as `alpha*A*x + beta*y` or `alpha*A'*x + +beta*y` according to `trans` ('N' or 'T'). The matrix `A` is +a general band matrix of dimension `m` by `size(A,2)` with +updated `y`. +""" +Base.LinAlg.BLAS.gbmv! + +doc""" + gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + +Returns `alpha*A*x` or `alpha*A'*x` according to `trans` ('N' +or 'T'). The matrix `A` is a general band matrix of dimension +diagonals. +""" +Base.LinAlg.BLAS.gbmv + +doc""" + sbmv!(uplo, k, alpha, A, x, beta, y) + +Update vector `y` as `alpha*A*x + beta*y` where `A` is a a +symmetric band matrix of order `size(A,2)` with `k` super- +diagonals stored in the argument `A`. The storage layout for +http://www.netlib.org/lapack/explore-html/. +Returns the updated `y`. +""" +Base.LinAlg.BLAS.sbmv! + +doc""" + sbmv(uplo, k, alpha, A, x) + +Returns `alpha*A*x` where `A` is a symmetric band matrix of +order `size(A,2)` with `k` super-diagonals stored in the +argument `A`. +""" +Base.LinAlg.BLAS.sbmv + +doc""" + sbmv(uplo, k, A, x) + +Returns `A*x` where `A` is a symmetric band matrix of order +""" +Base.LinAlg.BLAS.sbmv + +doc""" + gemm!(tA, tB, alpha, A, B, beta, C) + +Update `C` as `alpha*A*B + beta*C` or the other three variants +according to `tA` (transpose `A`) and `tB`. Returns the +updated `C`. +""" +Base.LinAlg.BLAS.gemm! + +doc""" + gemm(tA, tB, alpha, A, B) + +Returns `alpha*A*B` or the other three variants according to +""" +Base.LinAlg.BLAS.gemm + +doc""" + gemm(tA, tB, A, B) + +Returns `A*B` or the other three variants according to `tA` +""" +Base.LinAlg.BLAS.gemm + +doc""" + gemv!(tA, alpha, A, x, beta, y) + +Update the vector `y` as `alpha*A*x + beta*y` or `alpha*A'x + +beta*y` according to `tA` (transpose `A`). Returns the updated +""" +Base.LinAlg.BLAS.gemv! + +doc""" + gemv(tA, alpha, A, x) + +Returns `alpha*A*x` or `alpha*A'x` according to `tA` +""" +Base.LinAlg.BLAS.gemv + +doc""" + gemv(tA, A, x) + +Returns `A*x` or `A'x` according to `tA` (transpose `A`). +""" +Base.LinAlg.BLAS.gemv + +doc""" + symm!(side, ul, alpha, A, B, beta, C) + +Update `C` as `alpha*A*B + beta*C` or `alpha*B*A + beta*C` +according to `side`. `A` is assumed to be symmetric. Only the +""" +Base.LinAlg.BLAS.symm! + +doc""" + symm(side, ul, alpha, A, B) + +Returns `alpha*A*B` or `alpha*B*A` according to `side`. `A` +is assumed to be symmetric. Only the `ul` triangle of `A` is +used. +""" +Base.LinAlg.BLAS.symm + +doc""" + symm(side, ul, A, B) + +Returns `A*B` or `B*A` according to `side`. `A` is assumed +to be symmetric. Only the `ul` triangle of `A` is used. +""" +Base.LinAlg.BLAS.symm + +doc""" + symm(tA, tB, alpha, A, B) + +Returns `alpha*A*B` or the other three variants according to +""" +Base.LinAlg.BLAS.symm + +doc""" + symv!(ul, alpha, A, x, beta, y) + +Update the vector `y` as `alpha*A*x + beta*y`. `A` is assumed +to be symmetric. Only the `ul` triangle of `A` is used. +Returns the updated `y`. +""" +Base.LinAlg.BLAS.symv! + +doc""" + symv(ul, alpha, A, x) + +Returns `alpha*A*x`. `A` is assumed to be symmetric. Only the +""" +Base.LinAlg.BLAS.symv + +doc""" + symv(ul, A, x) + +Returns `A*x`. `A` is assumed to be symmetric. Only the +""" +Base.LinAlg.BLAS.symv + +doc""" + trmm!(side, ul, tA, dA, alpha, A, B) + +Update `B` as `alpha*A*B` or one of the other three variants +determined by `side` (A on left or right) and `tA` (transpose +A). Only the `ul` triangle of `A` is used. `dA` indicates if +Returns the updated `B`. +""" +Base.LinAlg.BLAS.trmm! + +doc""" + trmm(side, ul, tA, dA, alpha, A, B) + +Returns `alpha*A*B` or one of the other three variants determined +by `side` (A on left or right) and `tA` (transpose A). Only the +unit-triangular (the diagonal is assumed to be all ones). +""" +Base.LinAlg.BLAS.trmm + +doc""" + trsm!(side, ul, tA, dA, alpha, A, B) + +Overwrite `B` with the solution to `A*X = alpha*B` or one of +the other three variants determined by `side` (A on left or right +of `X`) and `tA` (transpose A). Only the `ul` triangle of +diagonal is assumed to be all ones). Returns the updated `B`. +""" +Base.LinAlg.BLAS.trsm! + +doc""" + trsm(side, ul, tA, dA, alpha, A, B) + +Returns the solution to `A*X = alpha*B` or one of the other three +variants determined by `side` (A on left or right of `X`) and +assumed to be all ones). +""" +Base.LinAlg.BLAS.trsm + +doc""" + trmv!(side, ul, tA, dA, alpha, A, b) + +Update `b` as `alpha*A*b` or one of the other three variants +determined by `side` (A on left or right) and `tA` (transpose +A). Only the `ul` triangle of `A` is used. `dA` indicates if +Returns the updated `b`. +""" +Base.LinAlg.BLAS.trmv! + +doc""" + trmv(side, ul, tA, dA, alpha, A, b) + +Returns `alpha*A*b` or one of the other three variants determined +by `side` (A on left or right) and `tA` (transpose A). Only the +unit-triangular (the diagonal is assumed to be all ones). +""" +Base.LinAlg.BLAS.trmv + +doc""" + trsv!(ul, tA, dA, A, b) + +Overwrite `b` with the solution to `A*x = b` or one of the +other two variants determined by `tA` (transpose A) and `ul` +triangular (the diagonal is assumed to be all ones). Returns the +updated `b`. +""" +Base.LinAlg.BLAS.trsv! + +doc""" + trsv(ul, tA, dA, A, b) + +Returns the solution to `A*x = b` or one of the other two +variants determined by `tA` (transpose A) and `ul` (triangle of +diagonal is assumed to be all ones). +""" +Base.LinAlg.BLAS.trsv + +doc""" + blas_set_num_threads(n) + +Set the number of threads the BLAS library should use. +""" +Base.LinAlg.BLAS.blas_set_num_threads + +doc""" + I + +An object of type `UniformScaling`, representing an identity +matrix of any size. +""" +Base.LinAlg.BLAS.I + +doc""" + -(x) + +Unary minus operator. +""" +- + +doc""" + +(x, y...) + +Addition operator. `x+y+z+...` calls this function with all +arguments, i.e. `+(x, y, z, ...)`. +""" ++ + +doc""" + -(x, y) + +Subtraction operator. +""" +- + +doc""" + *(x, y...) + +Multiplication operator. `x*y*z*...` calls this function with all +arguments, i.e. `*(x, y, z, ...)`. +""" +Base.(:(*)) + +doc""" + /(x, y) + +Right division operator: multiplication of `x` by the inverse of +arguments. +""" +Base.(:(/)) + +doc""" + \(x, y) + +Left division operator: multiplication of `y` by the inverse of +arguments. +""" +Base.(:(\)) + +doc""" + ^(x, y) + +Exponentiation operator. +""" +Base.(:(^)) + +doc""" + .+(x, y) + +Element-wise addition operator. +""" +Base.(:(.+)) + +doc""" + .-(x, y) + +Element-wise subtraction operator. +""" +Base.(:(.-)) + +doc""" + .*(x, y) + +Element-wise multiplication operator. +""" +Base.(:(.*)) + +doc""" + ./(x, y) + +Element-wise right division operator. +""" +Base.(:(./)) + +doc""" + .\(x, y) + +Element-wise left division operator. +""" +Base.(:(.\)) + +doc""" + .^(x, y) + +Element-wise exponentiation operator. +""" +Base.(:(.^)) + +doc""" + fma(x, y, z) + +Computes `x*y+z` without rounding the intermediate result +algorithms. See `muladd`. +""" +fma + +doc""" + muladd(x, y, z) + +Combined multiply-add, computes `x*y+z` in an efficient manner. +This may on some systems be equivalent to `x*y+z`, or to +""" +muladd + +doc""" + div(x, y) + +The quotient from Euclidean division. Computes `x/y`, truncated +to an integer. +""" +div + +doc""" + fld(x, y) + +Largest integer less than or equal to `x/y`. +""" +fld + +doc""" + cld(x, y) + +Smallest integer larger than or equal to `x/y`. +""" +cld + +doc""" + mod(x, y) + +Modulus after division, returning in the range [0,``y``), if `y` +is positive, or (`y`,0] if `y` is negative. +""" +mod + +doc""" + mod2pi(x) + +Modulus after division by 2pi, returning in the range [0,2pi). +This function computes a floating point representation of the +modulus after division by numerically exact 2pi, and is therefore +not exactly the same as mod(x,2pi), which would compute the modulus +of x relative to division by the floating-point number 2pi. +""" +mod2pi + +doc""" + rem(x, y) + +Remainder from Euclidean division, returning a value of the same +sign as``x``, and smaller in magnitude than `y`. This value is +always exact. +""" +rem + +doc""" + divrem(x, y) + +The quotient and remainder from Euclidean division. Equivalent to +""" +divrem + +doc""" + fldmod(x, y) + +The floored quotient and modulus after division. Equivalent to +""" +fldmod + +doc""" + mod1(x, m) + +Modulus after division, returning in the range (0,m] +""" +mod1 + +doc""" + rem1(x, m) + +Remainder after division, returning in the range (0,m] +""" +rem1 + +doc""" + //(num, den) + +Divide two integers or rational numbers, giving a `Rational` +result. +""" +Base.(:(//)) + +doc""" + rationalize([Type=Int], x; tol=eps(x)) + +Approximate floating point number `x` as a Rational number with +components of the given integer type. The result will differ from +""" +rationalize + +doc""" + num(x) + +Numerator of the rational representation of `x` +""" +num + +doc""" + den(x) + +Denominator of the rational representation of `x` +""" +den + +doc""" + <<(x, n) + +Left bit shift operator. +""" +Base.(:(<<)) + +doc""" + >>(x, n) + +Right bit shift operator, preserving the sign of `x`. +""" +Base.(:(>>)) + +doc""" + >>>(x, n) + +Unsigned right bit shift operator. +""" +Base.(:(>>>)) + +doc""" + :(start[, step], stop) + +Range operator. `a:b` constructs a range from `a` to `b` with +a step size of 1, and `a:s:b` is similar but uses a step size of +also used in indexing to select whole dimensions. +""" +:(:) + +doc""" + colon(start[, step], stop) + +Called by `:` syntax for constructing ranges. +""" +colon + +doc""" + range(start[, step], length) + +Construct a range by length, given a starting value and optional +step (defaults to 1). +""" +range + +doc""" + ==(x, y) + +Generic equality operator, giving a single `Bool` result. Falls +back to `===`. Should be implemented for all types with a notion +of equality, based on the abstract value that an instance +represents. For example, all numeric types are compared by numeric +value, ignoring type. Strings are compared as sequences of +characters, ignoring encoding. +Follows IEEE semantics for floating-point numbers. +Collections should generally implement `==` by calling `==` +recursively on all contents. +New numeric types should implement this function for two arguments +of the new type, and handle comparison to other types via promotion +rules where possible. +""" +Base.(:(==)) + +doc""" + !=(x, y) + +Not-equals comparison operator. Always gives the opposite answer as +the fallback definition `!=(x,y) = !(x==y)` instead. +""" +Base.(:(!=)) + +doc""" + ===(x, y) + +See the `is()` operator +""" +Base.(:(===)) + +doc""" + !==(x, y) + +Equivalent to `!is(x, y)` +""" +Base.(:(!==)) + +doc""" + <(x, y) + +Less-than comparison operator. New numeric types should implement +this function for two arguments of the new type. Because of the +behavior of floating-point NaN values, `<` implements a partial +order. Types with a canonical partial order should implement `<`, +and types with a canonical total order should implement `isless`. +""" +Base.(:(<)) + +doc""" + <=(x, y) + +Less-than-or-equals comparison operator. +""" +Base.(:(<=)) + +doc""" + >(x, y) + +Greater-than comparison operator. Generally, new types should +implement `<` instead of this function, and rely on the fallback +definition `>(x,y) = y)) + +doc""" + >=(x, y) + +Greater-than-or-equals comparison operator. +""" +Base.(:(>=)) + +doc""" + .==(x, y) + +Element-wise equality comparison operator. +""" +Base.(:(.==)) + +doc""" + .!=(x, y) + +Element-wise not-equals comparison operator. +""" +Base.(:(.!=)) + +doc""" + .<(x, y) + +Element-wise less-than comparison operator. +""" +Base.(:(.<)) + +doc""" + .<=(x, y) + +Element-wise less-than-or-equals comparison operator. +""" +Base.(:(.<=)) + +doc""" + .>(x, y) + +Element-wise greater-than comparison operator. +""" +Base.(:(.>)) + +doc""" + .>=(x, y) + +Element-wise greater-than-or-equals comparison operator. +""" +Base.(:(.>=)) + +doc""" + cmp(x, y) + +Return -1, 0, or 1 depending on whether `x` is less than, equal +to, or greater than `y`, respectively. Uses the total order +implemented by `isless`. For floating-point numbers, uses `<` +but throws an error for unordered arguments. +""" +cmp + +doc""" + ~(x) + +Bitwise not +""" +~ + +doc""" + &(x, y) + +Bitwise and +""" +& + +doc""" + |(x, y) + +Bitwise or +""" +Base.(:(|)) + +doc""" + \$(x, y) + +Bitwise exclusive or +""" +$ + +doc""" + !(x) + +Boolean not +""" +! + +doc""" + A_ldiv_Bc(a, b) + +Matrix operator A \ B^H +""" +A_ldiv_Bc + +doc""" + A_ldiv_Bt(a, b) + +Matrix operator A \ B^T +""" +A_ldiv_Bt + +doc""" + A_mul_B!(Y, A, B) -> Y + +Calculates the matrix-matrix or matrix-vector product *A B* and +stores the result in *Y*, overwriting the existing value of *Y*. +""" +A_mul_B! + +doc""" + A_mul_Bc(...) + +Matrix operator A B^H +""" +A_mul_Bc + +doc""" + A_mul_Bt(...) + +Matrix operator A B^T +""" +A_mul_Bt + +doc""" + A_rdiv_Bc(...) + +Matrix operator A / B^H +""" +A_rdiv_Bc + +doc""" + A_rdiv_Bt(a, b) + +Matrix operator A / B^T +""" +A_rdiv_Bt + +doc""" + Ac_ldiv_B(...) + +Matrix operator A^H \ B +""" +Ac_ldiv_B + +doc""" + Ac_ldiv_Bc(...) + +Matrix operator A^H \ B^H +""" +Ac_ldiv_Bc + +doc""" + Ac_mul_B(...) + +Matrix operator A^H B +""" +Ac_mul_B + +doc""" + Ac_mul_Bc(...) + +Matrix operator A^H B^H +""" +Ac_mul_Bc + +doc""" + Ac_rdiv_B(a, b) + +Matrix operator A^H / B +""" +Ac_rdiv_B + +doc""" + Ac_rdiv_Bc(a, b) + +Matrix operator A^H / B^H +""" +Ac_rdiv_Bc + +doc""" + At_ldiv_B(...) + +Matrix operator A^T \ B +""" +At_ldiv_B + +doc""" + At_ldiv_Bt(...) + +Matrix operator A^T \ B^T +""" +At_ldiv_Bt + +doc""" + At_mul_B(...) + +Matrix operator A^T B +""" +At_mul_B + +doc""" + At_mul_Bt(...) + +Matrix operator A^T B^T +""" +At_mul_Bt + +doc""" + At_rdiv_B(a, b) + +Matrix operator A^T / B +""" +At_rdiv_B + +doc""" + At_rdiv_Bt(a, b) + +Matrix operator A^T / B^T +""" +At_rdiv_Bt + +doc""" + isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + +Inexact equality comparison - behaves slightly different depending +on types of input args: +For default tolerance arguments, `maxeps = max(eps(abs(x)), +eps(abs(y)))`. +""" +isapprox + +doc""" + sin(x) + +Compute sine of `x`, where `x` is in radians +""" +sin + +doc""" + cos(x) + +Compute cosine of `x`, where `x` is in radians +""" +cos + +doc""" + tan(x) + +Compute tangent of `x`, where `x` is in radians +""" +tan + +doc""" + sind(x) + +Compute sine of `x`, where `x` is in degrees +""" +sind + +doc""" + cosd(x) + +Compute cosine of `x`, where `x` is in degrees +""" +cosd + +doc""" + tand(x) + +Compute tangent of `x`, where `x` is in degrees +""" +tand + +doc""" + sinpi(x) + +Compute \sin(\pi x) more accurately than `sin(pi*x)`, +especially for large `x`. +""" +sinpi + +doc""" + cospi(x) + +Compute \cos(\pi x) more accurately than `cos(pi*x)`, +especially for large `x`. +""" +cospi + +doc""" + sinh(x) + +Compute hyperbolic sine of `x` +""" +sinh + +doc""" + cosh(x) + +Compute hyperbolic cosine of `x` +""" +cosh + +doc""" + tanh(x) + +Compute hyperbolic tangent of `x` +""" +tanh + +doc""" + asin(x) + +Compute the inverse sine of `x`, where the output is in radians +""" +asin + +doc""" + acos(x) + +Compute the inverse cosine of `x`, where the output is in radians +""" +acos + +doc""" + atan(x) + +Compute the inverse tangent of `x`, where the output is in +radians +""" +atan + +doc""" + atan2(y, x) + +Compute the inverse tangent of `y/x`, using the signs of both +""" +atan2 + +doc""" + asind(x) + +Compute the inverse sine of `x`, where the output is in degrees +""" +asind + +doc""" + acosd(x) + +Compute the inverse cosine of `x`, where the output is in degrees +""" +acosd + +doc""" + atand(x) + +Compute the inverse tangent of `x`, where the output is in +degrees +""" +atand + +doc""" + sec(x) + +Compute the secant of `x`, where `x` is in radians +""" +sec + +doc""" + csc(x) + +Compute the cosecant of `x`, where `x` is in radians +""" +csc + +doc""" + cot(x) + +Compute the cotangent of `x`, where `x` is in radians +""" +cot + +doc""" + secd(x) + +Compute the secant of `x`, where `x` is in degrees +""" +secd + +doc""" + cscd(x) + +Compute the cosecant of `x`, where `x` is in degrees +""" +cscd + +doc""" + cotd(x) + +Compute the cotangent of `x`, where `x` is in degrees +""" +cotd + +doc""" + asec(x) + +Compute the inverse secant of `x`, where the output is in radians +""" +asec + +doc""" + acsc(x) + +Compute the inverse cosecant of `x`, where the output is in +radians +""" +acsc + +doc""" + acot(x) + +Compute the inverse cotangent of `x`, where the output is in +radians +""" +acot + +doc""" + asecd(x) + +Compute the inverse secant of `x`, where the output is in degrees +""" +asecd + +doc""" + acscd(x) + +Compute the inverse cosecant of `x`, where the output is in +degrees +""" +acscd + +doc""" + acotd(x) + +Compute the inverse cotangent of `x`, where the output is in +degrees +""" +acotd + +doc""" + sech(x) + +Compute the hyperbolic secant of `x` +""" +sech + +doc""" + csch(x) + +Compute the hyperbolic cosecant of `x` +""" +csch + +doc""" + coth(x) + +Compute the hyperbolic cotangent of `x` +""" +coth + +doc""" + asinh(x) + +Compute the inverse hyperbolic sine of `x` +""" +asinh + +doc""" + acosh(x) + +Compute the inverse hyperbolic cosine of `x` +""" +acosh + +doc""" + atanh(x) + +Compute the inverse hyperbolic tangent of `x` +""" +atanh + +doc""" + asech(x) + +Compute the inverse hyperbolic secant of `x` +""" +asech + +doc""" + acsch(x) + +Compute the inverse hyperbolic cosecant of `x` +""" +acsch + +doc""" + acoth(x) + +Compute the inverse hyperbolic cotangent of `x` +""" +acoth + +doc""" + sinc(x) + +Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. +""" +sinc + +doc""" + cosc(x) + +Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq +0, and 0 if x = 0. This is the derivative of `sinc(x)`. +""" +cosc + +doc""" + deg2rad(x) + +Convert `x` from degrees to radians +""" +deg2rad + +doc""" + rad2deg(x) + +Convert `x` from radians to degrees +""" +rad2deg + +doc""" + hypot(x, y) + +Compute the \sqrt{x^2+y^2} avoiding overflow and underflow +""" +hypot + +doc""" + log(x) + +Compute the natural logarithm of `x`. Throws `DomainError` for +negative `Real` arguments. Use complex negative arguments to +obtain complex results. +There is an experimental variant in the `Base.Math.JuliaLibm` +module, which is typically faster and more accurate. +""" +log + +doc""" + log(b, x) + +Compute the base `b` logarithm of `x`. Throws `DomainError` +for negative `Real` arguments. +""" +log + +doc""" + log2(x) + +Compute the logarithm of `x` to base 2. Throws `DomainError` +for negative `Real` arguments. +""" +log2 + +doc""" + log10(x) + +Compute the logarithm of `x` to base 10. Throws `DomainError` +for negative `Real` arguments. +""" +log10 + +doc""" + log1p(x) + +Accurate natural logarithm of `1+x`. Throws `DomainError` for +There is an experimental variant in the `Base.Math.JuliaLibm` +module, which is typically faster and more accurate. +""" +log1p + +doc""" + frexp(val) + +Return `(x,exp)` such that `x` has a magnitude in the interval +""" +frexp + +doc""" + exp(x) + +Compute e^x +""" +exp + +doc""" + exp2(x) + +Compute 2^x +""" +exp2 + +doc""" + exp10(x) + +Compute 10^x +""" +exp10 + +doc""" + ldexp(x, n) + +Compute x \times 2^n +""" +ldexp + +doc""" + modf(x) + +Return a tuple (fpart,ipart) of the fractional and integral parts +of a number. Both parts have the same sign as the argument. +""" +modf + +doc""" + expm1(x) + +Accurately compute e^x-1 +""" +expm1 + +doc""" + round([T], x[, digits[, base]][, r::RoundingMode]) + +default rounding mode (see `get_rounding()`), returning a value +of the same type as `x`. By default (`RoundNearest`), this will +round to the nearest integer, with ties (fractional values of 0.5) +being rounded to the even integer. +The optional `RoundingMode` argument will change how the number +gets rounded. +representable. +the decimal place (or before if negative). `round(x, digits, +base)` rounds using a base other than 10. +Note: Rounding to specified digits in bases other than 2 can be +""" +round + +doc""" + RoundingMode + +A type which controls rounding behavior. Currently supported +rounding modes are: +""" +RoundingMode + +doc""" + RoundNearest + +The default rounding mode. Rounds to the nearest integer, with ties +integer. +""" +RoundNearest + +doc""" + RoundNearestTiesAway + +Rounds to nearest integer, with ties rounded away from zero (C/C++ +""" +RoundNearestTiesAway + +doc""" + RoundNearestTiesUp + +Rounds to nearest integer, with ties rounded toward positive +infinity (Java/JavaScript `round()` behaviour). +""" +RoundNearestTiesUp + +doc""" + RoundToZero + +""" +RoundToZero + +doc""" + RoundUp + +""" +RoundUp + +doc""" + RoundDown + +""" +RoundDown + +doc""" + round(z, RoundingModeReal, RoundingModeImaginary) + +Returns the nearest integral value of the same type as the complex- +valued `z` to `z`, breaking ties using the specified +the real components while the second is used for rounding the +imaginary components. +""" +round + +doc""" + ceil([T], x[, digits[, base]]) + +""" +ceil + +doc""" + floor([T], x[, digits[, base]]) + +""" +floor + +doc""" + trunc([T], x[, digits[, base]]) + +""" +trunc + +doc""" + unsafe_trunc(T, x) + +value is not representable by `T`, an arbitrary value will be +returned. +""" +unsafe_trunc + +doc""" + signif(x, digits[, base]) + +Rounds (in the sense of `round`) `x` so that there are +representation, default 10. E.g., `signif(123.456, 2)` is +""" +signif + +doc""" + min(x, y, ...) + +Return the minimum of the arguments. Operates elementwise over +arrays. +""" +min + +doc""" + max(x, y, ...) + +Return the maximum of the arguments. Operates elementwise over +arrays. +""" +max + +doc""" + minmax(x, y) + +Return `(min(x,y), max(x,y))`. See also: `extrema()` that +returns `(minimum(x), maximum(x))` +""" +minmax + +doc""" + clamp(x, lo, hi) + +Return x if `lo <= x <= hi`. If `x < lo`, return `lo`. If `x +Operates elementwise over `x` if it is an array. +""" +clamp + +doc""" + abs(x) + +Absolute value of `x` +""" +abs + +doc""" + abs2(x) + +Squared absolute value of `x` +""" +abs2 + +doc""" + copysign(x, y) + +Return `x` such that it has the same sign as `y` +""" +copysign + +doc""" + sign(x) + +Return `+1` if `x` is positive, `0` if `x == 0`, and `-1` +if `x` is negative. +""" +sign + +doc""" + signbit(x) + +Returns `true` if the value of the sign of `x` is negative, +otherwise `false`. +""" +signbit + +doc""" + flipsign(x, y) + +Return `x` with its sign flipped if `y` is negative. For +example `abs(x) = flipsign(x,x)`. +""" +flipsign + +doc""" + sqrt(x) + +Return \sqrt{x}. Throws `DomainError` for negative `Real` +arguments. Use complex negative arguments instead. The prefix +operator `√` is equivalent to `sqrt`. +""" +sqrt + +doc""" + isqrt(n) + +Integer square root: the largest integer `m` such that `m*m <= +n`. +""" +isqrt + +doc""" + cbrt(x) + +Return x^{1/3}. The prefix operator `∛` is equivalent to +""" +cbrt + +doc""" + erf(x) + +Compute the error function of `x`, defined by +""" +erf + +doc""" + erfc(x) + +Compute the complementary error function of `x`, defined by 1 - +""" +erfc + +doc""" + erfcx(x) + +Compute the scaled complementary error function of `x`, defined +by e^{x^2} \operatorname{erfc}(x). Note also that +""" +erfcx + +doc""" + erfi(x) + +Compute the imaginary error function of `x`, defined by -i +""" +erfi + +doc""" + dawson(x) + +Compute the Dawson function (scaled imaginary error function) of +""" +dawson + +doc""" + erfinv(x) + +Compute the inverse error function of a real `x`, defined by +""" +erfinv + +doc""" + erfcinv(x) + +Compute the inverse error complementary function of a real `x`, +defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. +""" +erfcinv + +doc""" + real(z) + +Return the real part of the complex number `z` +""" +real + +doc""" + imag(z) + +Return the imaginary part of the complex number `z` +""" +imag + +doc""" + reim(z) + +Return both the real and imaginary parts of the complex number +""" +reim + +doc""" + conj(z) + +Compute the complex conjugate of a complex number `z` +""" +conj + +doc""" + angle(z) + +Compute the phase angle in radians of a complex number `z` +""" +angle + +doc""" + cis(z) + +Return \exp(iz). +""" +cis + +doc""" + binomial(n, k) + +Number of ways to choose `k` out of `n` items +""" +binomial + +doc""" + factorial(n) + +Factorial of `n`. If `n` is an `Integer`, the factorial is +computed as an integer (promoted to at least 64 bits). Note that +this may overflow if `n` is not small, but you can use +precision. If `n` is not an `Integer`, `factorial(n)` is +equivalent to `gamma(n+1)`. +""" +factorial + +doc""" + factorial(n, k) + +Compute `factorial(n)/factorial(k)` +""" +factorial + +doc""" + factor(n) -> Dict + +Compute the prime factorization of an integer `n`. Returns a +dictionary. The keys of the dictionary correspond to the factors, +and hence are of the same type as `n`. The value associated with +each key indicates the number of times the factor appears in the +factorization. +""" +factor + +doc""" + gcd(x, y) + +Greatest common (positive) divisor (or zero if x and y are both +zero). +""" +gcd + +doc""" + lcm(x, y) + +Least common (non-negative) multiple. +""" +lcm + +doc""" + gcdx(x, y) + +Computes the greatest common (positive) divisor of `x` and `y` +and their Bézout coefficients, i.e. the integer coefficients `u` +and `v` that satisfy ux+vy = d = gcd(x,y). +Note: Bézout coefficients are *not* uniquely defined. `gcdx` +""" +gcdx + +doc""" + ispow2(n) -> Bool + +Test whether `n` is a power of two +""" +ispow2 + +doc""" + nextpow2(n) + +The smallest power of two not less than `n`. Returns 0 for +""" +nextpow2 + +doc""" + prevpow2(n) + +The largest power of two not greater than `n`. Returns 0 for +""" +prevpow2 + +doc""" + nextpow(a, x) + +The smallest `a^n` not less than `x`, where `n` is a non- +negative integer. `a` must be greater than 1, and `x` must be +greater than 0. +""" +nextpow + +doc""" + prevpow(a, x) + +The largest `a^n` not greater than `x`, where `n` is a non- +negative integer. `a` must be greater than 1, and `x` must not +be less than 1. +""" +prevpow + +doc""" + nextprod([k_1, k_2, ...], n) + +Next integer not less than `n` that can be written as \prod +k_i^{p_i} for integers p_1, p_2, etc. +""" +nextprod + +doc""" + prevprod([k_1, k_2, ...], n) + +Previous integer not greater than `n` that can be written as +""" +prevprod + +doc""" + invmod(x, m) + +Take the inverse of `x` modulo `m`: `y` such that xy = 1 +""" +invmod + +doc""" + powermod(x, p, m) + +Compute x^p \pmod m +""" +powermod + +doc""" + gamma(x) + +Compute the gamma function of `x` +""" +gamma + +doc""" + lgamma(x) + +Compute the logarithm of the absolute value of `gamma()` for +logarithm of `gamma(x)`. +""" +lgamma + +doc""" + lfact(x) + +Compute the logarithmic factorial of `x` +""" +lfact + +doc""" + digamma(x) + +Compute the digamma function of `x` (the logarithmic derivative +of `gamma(x)`) +""" +digamma + +doc""" + invdigamma(x) + +Compute the inverse digamma function of `x`. +""" +invdigamma + +doc""" + trigamma(x) + +Compute the trigamma function of `x` (the logarithmic second +derivative of `gamma(x)`) +""" +trigamma + +doc""" + polygamma(m, x) + +Compute the polygamma function of order `m` of argument `x` +""" +polygamma + +doc""" + airy(k, x) + +kth derivative of the Airy function \operatorname{Ai}(x). +""" +airy + +doc""" + airyai(x) + +Airy function \operatorname{Ai}(x). +""" +airyai + +doc""" + airyprime(x) + +Airy function derivative \operatorname{Ai}'(x). +""" +airyprime + +doc""" + airyaiprime(x) + +Airy function derivative \operatorname{Ai}'(x). +""" +airyaiprime + +doc""" + airybi(x) + +Airy function \operatorname{Bi}(x). +""" +airybi + +doc""" + airybiprime(x) + +Airy function derivative \operatorname{Bi}'(x). +""" +airybiprime + +doc""" + airyx(k, x) + +scaled kth derivative of the Airy function, return +k == 1`, and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} +k == 3`. +""" +airyx + +doc""" + besselj0(x) + +Bessel function of the first kind of order 0, J_0(x). +""" +besselj0 + +doc""" + besselj1(x) + +Bessel function of the first kind of order 1, J_1(x). +""" +besselj1 + +doc""" + besselj(nu, x) + +Bessel function of the first kind of order `nu`, J_\nu(x). +""" +besselj + +doc""" + besseljx(nu, x) + +Scaled Bessel function of the first kind of order `nu`, J_\nu(x) +e^{- | \operatorname{Im}(x) |}. +""" +besseljx + +doc""" + bessely0(x) + +Bessel function of the second kind of order 0, Y_0(x). +""" +bessely0 + +doc""" + bessely1(x) + +Bessel function of the second kind of order 1, Y_1(x). +""" +bessely1 + +doc""" + bessely(nu, x) + +Bessel function of the second kind of order `nu`, Y_\nu(x). +""" +bessely + +doc""" + besselyx(nu, x) + +Scaled Bessel function of the second kind of order `nu`, +Y_\nu(x) e^{- | \operatorname{Im}(x) |}. +""" +besselyx + +doc""" + hankelh1(nu, x) + +Bessel function of the third kind of order `nu`, H^{(1)}_\nu(x). +""" +hankelh1 + +doc""" + hankelh1x(nu, x) + +Scaled Bessel function of the third kind of order `nu`, +H^{(1)}_\nu(x) e^{-x i}. +""" +hankelh1x + +doc""" + hankelh2(nu, x) + +Bessel function of the third kind of order `nu`, H^{(2)}_\nu(x). +""" +hankelh2 + +doc""" + hankelh2x(nu, x) + +Scaled Bessel function of the third kind of order `nu`, +H^{(2)}_\nu(x) e^{x i}. +""" +hankelh2x + +doc""" + besselh(nu, k, x) + +Bessel function of the third kind of order `nu` (Hankel +function). `k` is either 1 or 2, selecting `hankelh1` or +""" +besselh + +doc""" + besseli(nu, x) + +Modified Bessel function of the first kind of order `nu`, +I_\nu(x). +""" +besseli + +doc""" + besselix(nu, x) + +Scaled modified Bessel function of the first kind of order `nu`, +I_\nu(x) e^{- | \operatorname{Re}(x) |}. +""" +besselix + +doc""" + besselk(nu, x) + +Modified Bessel function of the second kind of order `nu`, +K_\nu(x). +""" +besselk + +doc""" + besselkx(nu, x) + +Scaled modified Bessel function of the second kind of order `nu`, +K_\nu(x) e^x. +""" +besselkx + +doc""" + beta(x, y) + +Euler integral of the first kind \operatorname{B}(x,y) = +""" +beta + +doc""" + lbeta(x, y) + +Natural logarithm of the absolute value of the beta function +""" +lbeta + +doc""" + eta(x) + +Dirichlet eta function \eta(s) = +""" +eta + +doc""" + zeta(s) + +Riemann zeta function \zeta(s). +""" +zeta + +doc""" + zeta(s, z) + +Hurwitz zeta function \zeta(s, z). (This is equivalent to the +Riemann zeta function \zeta(s) for the case of `z=1`.) +""" +zeta + +doc""" + ndigits(n, b) + +Compute the number of digits in number `n` written in base `b`. +""" +ndigits + +doc""" + widemul(x, y) + +Multiply `x` and `y`, giving the result as a larger type. +""" +widemul + +doc""" + @evalpoly(z, c...) + +Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients +ascending order by power of `z`. This macro expands to efficient +inline code that uses either Horner's method or, for complex `z`, +a more efficient Goertzel-like algorithm. +""" +@evalpoly + +doc""" + mean(v[, region]) + +Compute the mean of whole array `v`, or optionally along the +dimensions in `region`. Note: Julia does not ignore `NaN` +values in the computation. For applications requiring the handling +of missing data, the `DataArray` package is recommended. +""" +mean + +doc""" + mean!(r, v) + +Compute the mean of `v` over the singleton dimensions of `r`, +and write results to `r`. +""" +mean! + +doc""" + std(v[, region]) + +Compute the sample standard deviation of a vector or array `v`, +optionally along dimensions in `region`. The algorithm returns an +estimator of the generative distribution's standard deviation under +the assumption that each entry of `v` is an IID drawn from that +generative distribution. This computation is equivalent to +calculating `sqrt(sum((v - mean(v)).^2) / (length(v) - 1))`. +Note: Julia does not ignore `NaN` values in the computation. For +applications requiring the handling of missing data, the +""" +std + +doc""" + stdm(v, m) + +Compute the sample standard deviation of a vector `v` with known +mean `m`. Note: Julia does not ignore `NaN` values in the +computation. +""" +stdm + +doc""" + var(v[, region]) + +Compute the sample variance of a vector or array `v`, optionally +along dimensions in `region`. The algorithm will return an +estimator of the generative distribution's variance under the +assumption that each entry of `v` is an IID drawn from that +generative distribution. This computation is equivalent to +calculating `sum((v - mean(v)).^2) / (length(v) - 1)`. Note: +Julia does not ignore `NaN` values in the computation. For +applications requiring the handling of missing data, the +""" +var + +doc""" + varm(v, m) + +Compute the sample variance of a vector `v` with known mean +computation. +""" +varm + +doc""" + middle(x) + +Compute the middle of a scalar value, which is equivalent to `x` +itself, but of the type of `middle(x, x)` for consistency. +""" +middle + +doc""" + middle(x, y) + +Compute the middle of two reals `x` and `y`, which is +equivalent in both value and type to computing their mean (`(x + +y) / 2`). +""" +middle + +doc""" + middle(range) + +Compute the middle of a range, which consists in computing the mean +of its extrema. Since a range is sorted, the mean is performed with +the first and last element. +""" +middle + +doc""" + middle(array) + +Compute the middle of an array, which consists in finding its +extrema and then computing their mean. +""" +middle + +doc""" + median(v) + +Compute the median of a vector `v`. `NaN` is returned if the +data contains any `NaN` values. For applications requiring the +handling of missing data, the `DataArrays` package is +recommended. +""" +median + +doc""" + median!(v) + +Like `median`, but may overwrite the input vector. +""" +median! + +doc""" + hist(v[, n]) -> e, counts + +Compute the histogram of `v`, optionally using approximately +to the edges of the bins, and `counts` containing the number of +elements of `v` in each bin. Note: Julia does not ignore `NaN` +values in the computation. +""" +hist + +doc""" + hist(v, e) -> e, counts + +Compute the histogram of `v` using a vector/range `e` as the +edges for the bins. The result will be a vector of length +satisfies `sum(e[i] .< v .<= e[i+1])`. Note: Julia does not +ignore `NaN` values in the computation. +""" +hist + +doc""" + hist!(counts, v, e) -> e, counts + +Compute the histogram of `v`, using a vector/range `e` as the +edges for the bins. This function writes the resultant counts to a +pre-allocated array `counts`. +""" +hist! + +doc""" + hist2d(M, e1, e2) -> (edge1, edge2, counts) + +Compute a `2d histogram` of a set of N points specified by N-by-2 +matrix `M`. Arguments `e1` and `e2` are bins for each +dimension, specified either as integer bin counts or vectors of bin +edges. The result is a tuple of `edge1` (the bin edges used in +the first dimension), `edge2` (the bin edges used in the second +dimension), and `counts`, a histogram matrix of size +""" +hist2d + +doc""" + hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + +Compute a `2d histogram` with respect to the bins delimited by +the edges given in `e1` and `e2`. This function writes the +results to a pre-allocated array `counts`. +""" +hist2d! + +doc""" + histrange(v, n) + +Compute *nice* bin ranges for the edges of a histogram of `v`, +using approximately `n` bins. The resulting step sizes will be 1, +2 or 5 multiplied by a power of 10. Note: Julia does not ignore +""" +histrange + +doc""" + midpoints(e) + +Compute the midpoints of the bins with edges `e`. The result is a +vector/range of length `length(e) - 1`. Note: Julia does not +ignore `NaN` values in the computation. +""" +midpoints + +doc""" + quantile(v, p) + +Compute the quantiles of a vector `v` at a specified set of +probability values `p`. Note: Julia does not ignore `NaN` +values in the computation. +""" +quantile + +doc""" + quantile(v, p) + +Compute the quantile of a vector `v` at the probability `p`. +Note: Julia does not ignore `NaN` values in the computation. +""" +quantile + +doc""" + quantile!(v, p) + +Like `quantile`, but overwrites the input vector. +""" +quantile! + +doc""" + cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + +Compute the Pearson covariance between the vector(s) in `v1` and +This function accepts three keyword arguments: +The size of the result depends on the size of `v1` and `v2`. +When both `v1` and `v2` are vectors, it returns the covariance +between them as a scalar. When either one is a matrix, it returns a +covariance matrix of size `(n1, n2)`, where `n1` and `n2` are +the numbers of slices in `v1` and `v2`, which depend on the +setting of `vardim`. +Note: `v2` can be omitted, which indicates `v2 = v1`. +""" +cov + +doc""" + cor(v1[, v2][, vardim=1, mean=nothing]) + +Compute the Pearson correlation between the vector(s) in `v1` and +Users can use the keyword argument `vardim` to specify the +variable dimension, and `mean` to supply pre-computed mean +values. +""" +cor + +doc""" + fft(A[, dims]) + +Performs a multidimensional FFT of the array `A`. The optional +an integer, range, tuple, or array) to transform along. Most +efficient if the size of `A` along the transformed dimensions is +a product of small primes; see `nextprod()`. See also +A one-dimensional FFT computes the one-dimensional discrete Fourier +transform (DFT) as defined by +A multidimensional FFT simply performs this operation along each +transformed dimension of `A`. +Higher performance is usually possible with multi-threading. Use +processors. +""" +fft + +doc""" + fft!(A[, dims]) + +Same as `fft()`, but operates in-place on `A`, which must be an +array of complex floating-point numbers. +""" +fft! + +doc""" + ifft(A[, dims]) + +Multidimensional inverse FFT. +A one-dimensional inverse FFT computes +A multidimensional inverse FFT simply performs this operation along +each transformed dimension of `A`. +""" +ifft + +doc""" + ifft!(A[, dims]) + +Same as `ifft()`, but operates in-place on `A`. +""" +ifft! + +doc""" + bfft(A[, dims]) + +Similar to `ifft()`, but computes an unnormalized inverse +sizes of the transformed dimensions in order to obtain the inverse. +scaling step, which in some applications can be combined with other +computational steps elsewhere.) +""" +bfft + +doc""" + bfft!(A[, dims]) + +Same as `bfft()`, but operates in-place on `A`. +""" +bfft! + +doc""" + plan_fft(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized FFT along given dimensions (`dims`) of +arrays matching the shape and type of `A`. (The first two +arguments have the same meaning as for `fft()`.) Returns a +function `plan(A)` that computes `fft(A, dims)` quickly. +The `flags` argument is a bitwise-or of FFTW planner flags, +defaulting to `FFTW.ESTIMATE`. e.g. passing `FFTW.MEASURE` or +benchmarking different possible FFT algorithms and picking the +fastest one; see the FFTW manual for more information on planner +flags. The optional `timelimit` argument specifies a rough upper +bound on the allowed planning time, in seconds. Passing +that operates in-place on its argument (which must be an array of +complex floating-point numbers). `plan_ifft()` and so on are +similar but produce plans that perform the equivalent of the +inverse transforms `ifft()` and so on. +""" +plan_fft + +doc""" + plan_ifft(A[, dims[, flags[, timelimit]]]) + +Same as `plan_fft()`, but produces a plan that performs inverse +transforms `ifft()`. +""" +plan_ifft + +doc""" + plan_bfft(A[, dims[, flags[, timelimit]]]) + +Same as `plan_fft()`, but produces a plan that performs an +unnormalized backwards transform `bfft()`. +""" +plan_bfft + +doc""" + plan_fft!(A[, dims[, flags[, timelimit]]]) + +Same as `plan_fft()`, but operates in-place on `A`. +""" +plan_fft! + +doc""" + plan_ifft!(A[, dims[, flags[, timelimit]]]) + +Same as `plan_ifft()`, but operates in-place on `A`. +""" +plan_ifft! + +doc""" + plan_bfft!(A[, dims[, flags[, timelimit]]]) + +Same as `plan_bfft()`, but operates in-place on `A`. +""" +plan_bfft! + +doc""" + rfft(A[, dims]) + +Multidimensional FFT of a real array A, exploiting the fact that +the transform has conjugate symmetry in order to save roughly half +the computational time and storage costs compared with `fft()`. +If `A` has size `(n_1, ..., n_d)`, the result has size +The optional `dims` argument specifies an iterable subset of one +or more dimensions of `A` to transform, similar to `fft()`. +Instead of (roughly) halving the first dimension of `A` in the +result, the `dims[1]` dimension is (roughly) halved in the same +way. +""" +rfft + +doc""" + irfft(A, d[, dims]) + +Inverse of `rfft()`: for a complex array `A`, gives the +corresponding real array whose FFT yields `A` in the first half. +As for `rfft()`, `dims` is an optional subset of dimensions to +transform, defaulting to `1:ndims(A)`. +floor(size(A,dims[1])/2)+1`. (This parameter cannot be inferred +from `size(A)` due to the possibility of rounding by the +""" +irfft + +doc""" + brfft(A, d[, dims]) + +Similar to `irfft()` but computes an unnormalized inverse +transform (similar to `bfft()`), which must be divided by the +product of the sizes of the transformed dimensions (of the real +output array) in order to obtain the inverse transform. +""" +brfft + +doc""" + plan_rfft(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized real-input FFT, similar to `plan_fft()` +except for `rfft()` instead of `fft()`. The first two +arguments, and the size of the transformed result, are the same as +for `rfft()`. +""" +plan_rfft + +doc""" + plan_brfft(A, d[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized real-input unnormalized transform, similar to +first two arguments and the size of the transformed result, are the +same as for `brfft()`. +""" +plan_brfft + +doc""" + plan_irfft(A, d[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized inverse real-input FFT, similar to +respectively. The first three arguments have the same meaning as +for `irfft()`. +""" +plan_irfft + +doc""" + dct(A[, dims]) + +Performs a multidimensional type-II discrete cosine transform (DCT) +of the array `A`, using the unitary normalization of the DCT. The +optional `dims` argument specifies an iterable subset of +dimensions (e.g. an integer, range, tuple, or array) to transform +along. Most efficient if the size of `A` along the transformed +dimensions is a product of small primes; see `nextprod()`. See +also `plan_dct()` for even greater efficiency. +""" +dct + +doc""" + dct!(A[, dims]) + +Same as `dct!()`, except that it operates in-place on `A`, +which must be an array of real or complex floating-point values. +""" +dct! + +doc""" + idct(A[, dims]) + +Computes the multidimensional inverse discrete cosine transform +unitary normalization). The optional `dims` argument specifies an +iterable subset of dimensions (e.g. an integer, range, tuple, or +array) to transform along. Most efficient if the size of `A` +along the transformed dimensions is a product of small primes; see +efficiency. +""" +idct + +doc""" + idct!(A[, dims]) + +Same as `idct!()`, but operates in-place on `A`. +""" +idct! + +doc""" + plan_dct(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized discrete cosine transform (DCT), similar to +The first two arguments have the same meaning as for `dct()`. +""" +plan_dct + +doc""" + plan_dct!(A[, dims[, flags[, timelimit]]]) + +Same as `plan_dct()`, but operates in-place on `A`. +""" +plan_dct! + +doc""" + plan_idct(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized inverse discrete cosine transform (DCT), +similar to `plan_fft()` except producing a function that computes +""" +plan_idct + +doc""" + plan_idct!(A[, dims[, flags[, timelimit]]]) + +Same as `plan_idct()`, but operates in-place on `A`. +""" +plan_idct! + +doc""" + fftshift(x) + +Swap the first and second halves of each dimension of `x`. +""" +fftshift + +doc""" + fftshift(x, dim) + +Swap the first and second halves of the given dimension of array +""" +fftshift + +doc""" + ifftshift(x[, dim]) + +Undoes the effect of `fftshift`. +""" +ifftshift + +doc""" + filt(b, a, x[, si]) + +Apply filter described by vectors `a` and `b` to vector `x`, +with an optional initial filter state vector `si` (defaults to +zeros). +""" +filt + +doc""" + filt!(out, b, a, x[, si]) + +Same as `filt()` but writes the result into the `out` argument, +which may alias the input `x` to modify it in-place. +""" +filt! + +doc""" + deconv(b, a) + +Construct vector `c` such that `b = conv(a,c) + r`. Equivalent +to polynomial division. +""" +deconv + +doc""" + conv(u, v) + +Convolution of two vectors. Uses FFT algorithm. +""" +conv + +doc""" + conv2(u, v, A) + +2-D convolution of the matrix `A` with the 2-D separable kernel +generated by the vectors `u` and `v`. Uses 2-D FFT algorithm +""" +conv2 + +doc""" + conv2(B, A) + +2-D convolution of the matrix `B` with the matrix `A`. Uses +2-D FFT algorithm +""" +conv2 + +doc""" + xcorr(u, v) + +Compute the cross-correlation of two vectors. +""" +xcorr + +doc""" + r2r(A, kind[, dims]) + +Performs a multidimensional real-input/real-output (r2r) transform +of type `kind` of the array `A`, as defined in the FFTW manual. +types (`FFTW.REDFT00`, `FFTW.REDFT01`, `FFTW.REDFT10`, or +Hartley transform (`FFTW.DHT`). The `kind` argument may be an +array or tuple in order to specify different transform types along +the different dimensions of `A`; `kind[end]` is used for any +unspecified dimensions. See the FFTW manual for precise +definitions of these transform types, at http://www.fftw.org/doc. +The optional `dims` argument specifies an iterable subset of +dimensions (e.g. an integer, range, tuple, or array) to transform +along. `kind[i]` is then the transform type for `dims[i]`, with +See also `plan_r2r()` to pre-plan optimized r2r transforms. +""" +Base.FFTW.r2r + +doc""" + r2r!(A, kind[, dims]) + +Same as `r2r()`, but operates in-place on `A`, which must be an +array of real or complex floating-point numbers. +""" +Base.FFTW.r2r! + +doc""" + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized r2r transform, similar to `Base.plan_fft()` +except that the transforms (and the first three arguments) +correspond to `r2r()` and `r2r!()`, respectively. +""" +Base.FFTW.plan_r2r + +doc""" + plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + +Similar to `Base.plan_fft()`, but corresponds to `r2r!()`. +""" +Base.FFTW.plan_r2r! + +doc""" + quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + +Numerically integrate the function `f(x)` from `a` to `b`, +and optionally over additional intervals `b` to `c` and so on. +Keyword options include a relative error tolerance `reltol` +absolute error tolerance `abstol` (defaults to 0), a maximum +number of function evaluations `maxevals` (defaults to `10^7`), +and the `order` of the integration rule (defaults to 7). +Returns a pair `(I,E)` of the estimated integral `I` and an +estimated upper bound on the absolute error `E`. If `maxevals` +is not exceeded then `E <= max(abstol, reltol*norm(I))` will +hold. (Note that it is useful to specify a positive `abstol` in +cases where `norm(I)` may be zero.) +The endpoints `a` etcetera can also be complex (in which case the +integral is performed over straight-line segments in the complex +plane). If the endpoints are `BigFloat`, then the integration +will be performed in `BigFloat` precision as well (note: it is +advisable to increase the integration `order` in rough proportion +to the precision, for smooth integrands). More generally, the +precision is set by the precision of the integration endpoints +The integrand `f(x)` can return any numeric scalar, vector, or +matrix type, or in fact any type supporting `+`, `-`, +multiplication by real values, and a `norm` (i.e., any normed +vector space). Alternatively, a different norm can be specified by +passing a *norm*-like function as the *norm* keyword argument +multi-dimensional integration (cubature), there are many different +algorithms (often much better than simple nested 1d integrals) and +the optimal choice tends to be very problem-dependent. See the +Julia external-package listing for available algorithms for +multidimensional integration or other specialized tasks (such as +integrals of highly oscillatory or singular functions).] +The algorithm is an adaptive Gauss-Kronrod integration technique: +the integral in each interval is estimated using a Kronrod rule +Gauss rule (`order` points). The interval with the largest +error is then subdivided into two intervals and the process is +repeated until the desired error tolerance is achieved. +These quadrature rules work best for smooth functions within each +interval, so if your function has a known discontinuity or other +singularity, it is best to subdivide your interval to put the +singularity at an endpoint. For example, if `f` has a +discontinuity at `x=0.7` and you want to integrate from 0 to 1, +you should use `quadgk(f, 0,0.7,1)` to subdivide the interval at +the point of discontinuity. The integrand is never evaluated +exactly at the endpoints of the intervals, so it is possible to +integrate functions that diverge at the endpoints as long as the +singularity is integrable (for example, a `log(x)` or +For real-valued endpoints, the starting and/or ending points may be +infinite. (A coordinate transformation is performed internally to +map the infinite interval to a finite one.) +""" +quadgk + +doc""" + bin(n[, pad]) + +Convert an integer to a binary string, optionally specifying a +number of digits to pad to. +""" +bin + +doc""" + hex(n[, pad]) + +Convert an integer to a hexadecimal string, optionally specifying a +number of digits to pad to. +""" +hex + +doc""" + dec(n[, pad]) + +Convert an integer to a decimal string, optionally specifying a +number of digits to pad to. +""" +dec + +doc""" + oct(n[, pad]) + +Convert an integer to an octal string, optionally specifying a +number of digits to pad to. +""" +oct + +doc""" + base(base, n[, pad]) + +Convert an integer to a string in the given base, optionally +specifying a number of digits to pad to. The base can be specified +as either an integer, or as a `UInt8` array of character values +to use as digit symbols. +""" +base + +doc""" + digits(n[, base][, pad]) + +Returns an array of the digits of `n` in the given base, +optionally padded with zeros to a specified size. More significant +digits are at higher indexes, such that `n == +sum([digits[k]*base^(k-1) for k=1:length(digits)])`. +""" +digits + +doc""" + digits!(array, n[, base]) + +Fills an array of the digits of `n` in the given base. More +significant digits are at higher indexes. If the array length is +insufficient, the least significant digits are filled up to the +array length. If the array length is excessive, the excess portion +is filled with zeros. +""" +digits! + +doc""" + bits(n) + +A string giving the literal bit representation of a number. +""" +bits + +doc""" + parse(type, str[, base]) + +Parse a string as a number. If the type is an integer type, then a +base can be specified (the default is 10). If the type is a +floating point type, the string is parsed as a decimal floating +point number. If the string does not contain a valid number, an +error is raised. +""" +parse + +doc""" + tryparse(type, str[, base]) + +Like `parse`, but returns a `Nullable` of the requested type. +The result will be null if the string does not contain a valid +number. +""" +tryparse + +doc""" + big(x) + +Convert a number to a maximum precision representation (typically +some pitfalls with floating-point numbers. +""" +big + +doc""" + signed(x) + +Convert a number to a signed integer. If the argument is unsigned, +it is reinterpreted as signed without checking for overflow. +""" +signed + +doc""" + unsigned(x) -> Unsigned + +Convert a number to an unsigned integer. If the argument is signed, +it is reinterpreted as unsigned without checking for negative +values. +""" +unsigned + +doc""" + float(x) + +Convert a number, array, or string to a `FloatingPoint` data +type. For numeric data, the smallest suitable `FloatingPoint` +type is used. Converts strings to `Float64`. +""" +float + +doc""" + significand(x) + +Extract the significand(s) (a.k.a. mantissa), in binary +representation, of a floating-point number or array. If `x` is a +non-zero finite number, than the result will be a number of the +same type on the interval [1,2). Otherwise `x` is returned. +""" +significand + +doc""" + exponent(x) -> Int + +Get the exponent of a normalized floating-point number. +""" +exponent + +doc""" + complex(r[, i]) + +Convert real numbers or arrays to complex. `i` defaults to zero. +""" +complex + +doc""" + bswap(n) + +Byte-swap an integer +""" +bswap + +doc""" + num2hex(f) + +Get a hexadecimal string of the binary representation of a floating +point number +""" +num2hex + +doc""" + hex2num(str) + +Convert a hexadecimal string to the floating point number it +represents +""" +hex2num + +doc""" + hex2bytes(s::ASCIIString) + +Convert an arbitrarily long hexadecimal string to its binary +representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. +""" +hex2bytes + +doc""" + bytes2hex(bin_arr::Array{UInt8, 1}) + +Convert an array of bytes to its hexadecimal representation. All +characters are in lower-case. Returns an ASCIIString. +""" +bytes2hex + +doc""" + one(x) + +Get the multiplicative identity element for the type of x (x can +also specify the type itself). For matrices, returns an identity +matrix of the appropriate size and type. +""" +one + +doc""" + zero(x) + +Get the additive identity element for the type of x (x can also +specify the type itself). +""" +zero + +doc""" + pi + +The constant pi +""" +pi + +doc""" + im + +The imaginary unit +""" +im + +doc""" + e + +The constant e +""" +e + +doc""" + catalan + +Catalan's constant +""" +catalan + +doc""" + γ + +Euler's constant +""" +γ + +doc""" + φ + +The golden ratio +""" +φ + +doc""" + Inf + +Positive infinity of type Float64 +""" +Inf + +doc""" + Inf32 + +Positive infinity of type Float32 +""" +Inf32 + +doc""" + Inf16 + +Positive infinity of type Float16 +""" +Inf16 + +doc""" + NaN + +A not-a-number value of type Float64 +""" +NaN + +doc""" + NaN32 + +A not-a-number value of type Float32 +""" +NaN32 + +doc""" + NaN16 + +A not-a-number value of type Float16 +""" +NaN16 + +doc""" + issubnormal(f) -> Bool + +Test whether a floating point number is subnormal +""" +issubnormal + +doc""" + isfinite(f) -> Bool + +Test whether a number is finite +""" +isfinite + +doc""" + isinf(f) -> Bool + +Test whether a number is infinite +""" +isinf + +doc""" + isnan(f) -> Bool + +Test whether a floating point number is not a number (NaN) +""" +isnan + +doc""" + inf(f) + +Returns positive infinity of the floating point type `f` or of +the same floating point type as `f` +""" +inf + +doc""" + nan(f) + +Returns NaN (not-a-number) of the floating point type `f` or of +the same floating point type as `f` +""" +nan + +doc""" + nextfloat(f) + +Get the next floating point number in lexicographic order +""" +nextfloat + +doc""" + prevfloat(f) -> FloatingPoint + +Get the previous floating point number in lexicographic order +""" +prevfloat + +doc""" + isinteger(x) -> Bool + +Test whether `x` or all its elements are numerically equal to +some integer +""" +isinteger + +doc""" + isreal(x) -> Bool + +Test whether `x` or all its elements are numerically equal to +some real number +""" +isreal + +doc""" + Float32(x[, mode::RoundingMode]) + +Create a Float32 from `x`. If `x` is not exactly representable +then `mode` determines how `x` is rounded. +See `get_rounding` for available rounding modes. +""" +Float32 + +doc""" + Float64(x[, mode::RoundingMode]) + +Create a Float64 from `x`. If `x` is not exactly representable +then `mode` determines how `x` is rounded. +See `get_rounding` for available rounding modes. +""" +Float64 + +doc""" + BigInt(x) + +Create an arbitrary precision integer. `x` may be an `Int` (or +anything that can be converted to an `Int`). The usual +mathematical operators are defined for this type, and results are +promoted to a `BigInt`. +Instances can be constructed from strings via `parse()`, or using +the `big` string literal. +""" +BigInt + +doc""" + BigFloat(x) + +Create an arbitrary precision floating point number. `x` may be +an `Integer`, a `Float64` or a `BigInt`. The usual +mathematical operators are defined for this type, and results are +promoted to a `BigFloat`. +Note that because decimal literals are converted to floating point +numbers when parsed, `BigFloat(2.1)` may not yield what you +expect. You may instead prefer to initialize constants from strings +via `parse()`, or using the `big` string literal. +""" +BigFloat + +doc""" + get_rounding(T) + +Get the current floating point rounding mode for type `T`, +controlling the rounding of basic arithmetic functions (`+()`, +Valid modes are `RoundNearest`, `RoundToZero`, `RoundUp`, +""" +get_rounding + +doc""" + set_rounding(T, mode) + +Set the rounding mode of floating point type `T`, controlling the +rounding of basic arithmetic functions (`+()`, `-()`, `*()`, +Note that this may affect other types, for instance changing the +rounding mode of `Float64` will change the rounding mode of +""" +set_rounding + +doc""" + with_rounding(f::Function, T, mode) + +Change the rounding mode of floating point type `T` for the +duration of `f`. It is logically equivalent to: +See `get_rounding` for available rounding modes. +""" +with_rounding + +doc""" + count_ones(x::Integer) -> Integer + +Number of ones in the binary representation of `x`. +""" +count_ones + +doc""" + count_zeros(x::Integer) -> Integer + +Number of zeros in the binary representation of `x`. +""" +count_zeros + +doc""" + leading_zeros(x::Integer) -> Integer + +Number of zeros leading the binary representation of `x`. +""" +leading_zeros + +doc""" + leading_ones(x::Integer) -> Integer + +Number of ones leading the binary representation of `x`. +""" +leading_ones + +doc""" + trailing_zeros(x::Integer) -> Integer + +Number of zeros trailing the binary representation of `x`. +""" +trailing_zeros + +doc""" + trailing_ones(x::Integer) -> Integer + +Number of ones trailing the binary representation of `x`. +""" +trailing_ones + +doc""" + isprime(x::Integer) -> Bool + +Returns `true` if `x` is prime, and `false` otherwise. +""" +isprime + +doc""" + isprime(x::BigInt[, reps = 25]) -> Bool + +Probabilistic primality test. Returns `true` if `x` is prime; +and `false` if `x` is not prime with high probability. The +false positive rate is about `0.25^reps`. `reps = 25` is +considered safe for cryptographic applications (Knuth, +Seminumerical Algorithms). +""" +isprime + +doc""" + primes(n) + +Returns a collection of the prime numbers <= `n`. +""" +primes + +doc""" + isodd(x::Integer) -> Bool + +Returns `true` if `x` is odd (that is, not divisible by 2), and +""" +isodd + +doc""" + iseven(x::Integer) -> Bool + +Returns `true` is `x` is even (that is, divisible by 2), and +""" +iseven + +doc""" + precision(num::FloatingPoint) + +Get the precision of a floating point number, as defined by the +effective number of bits in the mantissa. +""" +precision + +doc""" + get_bigfloat_precision() + +Get the precision (in bits) currently used for BigFloat arithmetic. +""" +get_bigfloat_precision + +doc""" + set_bigfloat_precision(x::Int64) + +Set the precision (in bits) to be used to BigFloat arithmetic. +""" +set_bigfloat_precision + +doc""" + with_bigfloat_precision(f::Function, precision::Integer) + +Change the BigFloat arithmetic precision (in bits) for the duration +of `f`. It is logically equivalent to: +""" +with_bigfloat_precision + +doc""" + srand([rng][, seed]) + +Reseed the random number generator. If a `seed` is provided, the +RNG will give a reproducible sequence of numbers, otherwise Julia +will get entropy from the system. For `MersenneTwister`, the +integers or a filename, in which case the seed is read from a file. +""" +srand + +doc""" + MersenneTwister([seed]) + +Create a `MersenneTwister` RNG object. Different RNG objects can +have their own seeds, which may be useful for generating different +streams of random numbers. +""" +MersenneTwister + +doc""" + RandomDevice() + +Create a `RandomDevice` RNG object. Two such objects will always +generate different streams of random numbers. +""" +RandomDevice + +doc""" + rand([rng][, S][, dims...]) + +Pick a random element or array of random elements from the set of +values specified by `S`; `S` can be +""" +rand + +doc""" + rand!([rng], A[, coll]) + +Populate the array A with random values. If the indexable +collection `coll` is specified, the values are picked randomly +from `coll`. This is equivalent to `copy!(A, rand(rng, coll, +size(A)))` or `copy!(A, rand(rng, eltype(A), size(A)))` but +without allocating a new array. +""" +rand! + +doc""" + bitrand([rng][, dims...]) + +Generate a `BitArray` of random boolean values. +""" +bitrand + +doc""" + randn([rng][, dims...]) + +Generate a normally-distributed random number with mean 0 and +standard deviation 1. Optionally generate an array of normally- +distributed random numbers. +""" +randn + +doc""" + randn!([rng], A::Array{Float64, N}) + +Fill the array A with normally-distributed (mean 0, standard +deviation 1) random numbers. Also see the rand function. +""" +randn! + +doc""" + randexp([rng][, dims...]) + +Generate a random number according to the exponential distribution +with scale 1. Optionally generate an array of such random numbers. +""" +randexp + +doc""" + randexp!([rng], A::Array{Float64, N}) + +Fill the array A with random numbers following the exponential +distribution (with scale 1). +""" +randexp! + +doc""" + Task(func) + +Create a `Task` (i.e. thread, or coroutine) to execute the given +function (which must be callable with no arguments). The task exits +when this function returns. +""" +Task + +doc""" + yieldto(task, arg = nothing) + +Switch to the given task. The first time a task is switched to, the +task's function is called with no arguments. On subsequent +switches, `arg` is returned from the task's last call to +considering states or scheduling in any way. Its use is +discouraged. +""" +yieldto + +doc""" + current_task() + +Get the currently running Task. +""" +current_task + +doc""" + istaskdone(task) -> Bool + +Tell whether a task has exited. +""" +istaskdone + +doc""" + istaskstarted(task) -> Bool + +Tell whether a task has started executing. +""" +istaskstarted + +doc""" + consume(task, values...) + +Receive the next value passed to `produce` by the specified task. +Additional arguments may be passed, to be returned from the last +""" +consume + +doc""" + produce(value) + +Send the given value to the last `consume` call, switching to the +consumer task. If the next `consume` call passes any values, they +are returned by `produce`. +""" +produce + +doc""" + yield() + +Switch to the scheduler to allow another scheduled task to run. A +task that calls this function is still runnable, and will be +restarted immediately if there are no other runnable tasks. +""" +yield + +doc""" + task_local_storage(symbol) + +Look up the value of a symbol in the current task's task-local +storage. +""" +task_local_storage + +doc""" + task_local_storage(symbol, value) + +Assign a value to a symbol in the current task's task-local +storage. +""" +task_local_storage + +doc""" + task_local_storage(body, symbol, value) + +Call the function `body` with a modified task-local storage, in +which `value` is assigned to `symbol`; the previous value of +emulating dynamic scoping. +""" +task_local_storage + +doc""" + Condition() + +Create an edge-triggered event source that tasks can wait for. +Tasks that call `wait` on a `Condition` are suspended and +queued. Tasks are woken up when `notify` is later called on the +time `notify` is called can be woken up. For level-triggered +notifications, you must keep extra state to keep track of whether a +notification has happened. The `RemoteRef` type does this, and so +can be used for level-triggered events. +""" +Condition + +doc""" + notify(condition, val=nothing; all=true, error=false) + +Wake up tasks waiting for a condition, passing them `val`. If +otherwise only one is. If `error` is true, the passed value is +raised as an exception in the woken tasks. +""" +notify + +doc""" + schedule(t::Task, [val]; error=false) + +Add a task to the scheduler's queue. This causes the task to run +constantly when the system is otherwise idle, unless the task +performs a blocking operation such as `wait`. +If a second argument is provided, it will be passed to the task +task. +""" +schedule + +doc""" + @schedule() + +Wrap an expression in a Task and add it to the scheduler's queue. +""" +@schedule + +doc""" + @task() + +Wrap an expression in a Task without executing it, and return the +Task. This only creates a task, and does not run it. +""" +@task + +doc""" + sleep(seconds) + +Block the current task for a specified number of seconds. The +minimum sleep time is 1 millisecond or input of `0.001`. +""" +sleep + +doc""" + ReentrantLock() + +Creates a reentrant lock. The same task can acquire the lock as +many times as required. Each lock must be matched with an unlock. +""" +ReentrantLock + +doc""" + lock(l::ReentrantLock) + +Associates `l` with the current task. If `l` is already locked +by a different task, waits for it to become available. The same +task can acquire the lock multiple times. Each `lock` must be +matched by an `unlock` +""" +lock + +doc""" + unlock(l::ReentrantLock) + +Releases ownership of the lock by the current task. If the lock had +been acquired before, it just decrements an internal counter and +returns immediately. +""" +unlock + +doc""" + addprocs(n::Integer; exeflags=``) -> List of process identifiers + +Launches workers using the in-built `LocalManager` which only +launches workers on the local host. This can be used to take +advantage of multiple cores. `addprocs(4)` will add 4 processes +on the local machine. +""" +addprocs + +doc""" + addprocs() -> List of process identifiers + +Equivalent to `addprocs(CPU_CORES)` +""" +addprocs + +doc""" + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + +Add processes on remote machines via SSH. Requires julia to be +installed in the same location on each node, or to be available via +a shared file system. +started for each specification. +A machine specification is either a string `machine_spec` or a +tuple - `(machine_spec, count)` +to the standard ssh port. If `[bind_addr[:port]]` is specified, +other workers will connect to this worker at the specified +host. If specified as `:auto` it will launch as many workers as +the number of cores on the specific host. +Keyword arguments: +to the worker from the master process. +connected to in parallel at a host. Defaults to 10. +to the host's current directory (as found by *pwd()*) +may be. +Environment variables : +If the master process fails to establish a connection with a newly +launched worker within 60.0 seconds, the worker treats it a fatal +situation and terminates. This timeout can be controlled via +environment variable `JULIA_WORKER_TIMEOUT`. The value of +number of seconds a newly launched worker waits for connection +establishment. +""" +addprocs + +doc""" + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + +Launches worker processes via the specified cluster manager. +For example Beowulf clusters are supported via a custom cluster +manager implemented in package `ClusterManagers`. +The number of seconds a newly launched worker waits for connection +establishment from the master can be specified via variable +Relevant only when using TCP/IP as transport. +""" +addprocs + +doc""" + nprocs() + +Get the number of available processes. +""" +nprocs + +doc""" + nworkers() + +Get the number of available worker processes. This is one less than +nprocs(). Equal to nprocs() if nprocs() == 1. +""" +nworkers + +doc""" + procs() + +Returns a list of all process identifiers. +""" +procs + +doc""" + workers() + +Returns a list of all worker process identifiers. +""" +workers + +doc""" + rmprocs(pids...) + +Removes the specified workers. +""" +rmprocs + +doc""" + interrupt([pids...]) + +Interrupt the current executing task on the specified workers. This +is equivalent to pressing Ctrl-C on the local machine. If no +arguments are given, all workers are interrupted. +""" +interrupt + +doc""" + myid() + +Get the id of the current process. +""" +myid + +doc""" + pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + +Transform collections `lsts` by applying `f` to each element in +parallel. If `nprocs() > 1`, the calling process will be +dedicated to assigning tasks. All other available processes will be +used as parallel workers, or on the processes specified by +If `err_retry` is true, it retries a failed application of `f` +on a different worker. If `err_stop` is true, it takes precedence +over the value of `err_retry` and `pmap` stops execution on the +first error. +""" +pmap + +doc""" + remotecall(id, func, args...) + +Call a function asynchronously on the given arguments on the +specified process. Returns a `RemoteRef`. +""" +remotecall + +doc""" + wait([x]) + +Block the current task until some event occurs, depending on the +type of the argument: +If no argument is passed, the task blocks for an undefined period. +If the task's state is set to `:waiting`, it can only be +restarted by an explicit call to `schedule` or `yieldto`. If +the task's state is `:runnable`, it might be restarted +unpredictably. +Often `wait` is called within a `while` loop to ensure a +waited-for condition is met before proceeding. +""" +wait + +doc""" + fetch(RemoteRef) + +Wait for and get the value of a remote reference. +""" +fetch + +doc""" + remotecall_wait(id, func, args...) + +Perform `wait(remotecall(...))` in one message. +""" +remotecall_wait + +doc""" + remotecall_fetch(id, func, args...) + +Perform `fetch(remotecall(...))` in one message. +""" +remotecall_fetch + +doc""" + put!(RemoteRef, value) + +Store a value to a remote reference. Implements `shared queue of +length 1` semantics: if a value is already present, blocks until +the value is removed with `take!`. Returns its first argument. +""" +put! + +doc""" + take!(RemoteRef) + +Fetch the value of a remote reference, removing it so that the +reference is empty again. +""" +take! + +doc""" + isready(r::RemoteRef) + +Determine whether a `RemoteRef` has a value stored to it. Note +that this function can cause race conditions, since by the time you +receive its result it may no longer be true. It is recommended that +this function only be used on a `RemoteRef` that is assigned +once. +If the argument `RemoteRef` is owned by a different node, this +call will block to wait for the answer. It is recommended to wait +for `r` in a separate task instead, or to use a local +""" +isready + +doc""" + RemoteRef() + +Make an uninitialized remote reference on the local machine. +""" +RemoteRef + +doc""" + RemoteRef(n) + +Make an uninitialized remote reference on process `n`. +""" +RemoteRef + +doc""" + timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + +Waits till `testcb` returns `true` or for `secs`` seconds, +whichever is earlier. `testcb` is polled every `pollint` +seconds. +""" +timedwait + +doc""" + @spawn() + +Execute an expression on an automatically-chosen process, returning +a `RemoteRef` to the result. +""" +@spawn + +doc""" + @spawnat() + +Accepts two arguments, `p` and an expression, and runs the +expression asynchronously on process `p`, returning a +""" +@spawnat + +doc""" + @fetch() + +Equivalent to `fetch(@spawn expr)`. +""" +@fetch + +doc""" + @fetchfrom() + +Equivalent to `fetch(@spawnat p expr)`. +""" +@fetchfrom + +doc""" + @async() + +Schedule an expression to run on the local machine, also adding it +to the set of items that the nearest enclosing `@sync` waits for. +""" +@async + +doc""" + @sync() + +Wait until all dynamically-enclosed uses of `@async`, `@spawn`, +""" +@sync + +doc""" + @parallel() + +A parallel for loop of the form +The specified range is partitioned and locally executed across all +workers. In case an optional reducer function is specified, +reduction on the calling process. +Note that without a reducer function, @parallel executes +asynchronously, i.e. it spawns independent tasks on all available +workers and returns immediately without waiting for completion. To +wait for completion, prefix the call with `@sync`, like +""" +@parallel + +doc""" + SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + +Construct a SharedArray of a bitstype `T` and size `dims` +across the processes specified by `pids` - all of which have to +be on the same host. +If `pids` is left unspecified, the shared array will be mapped +across all processes on the current host, including the master. +But, `localindexes` and `indexpids` will only refer to worker +processes. This facilitates work distribution code to use workers +for actual computation with the master process acting as a driver. +If an `init` function of the type `initfn(S::SharedArray)` is +specified, it is called on all the participating workers. +""" +SharedArray + +doc""" + procs(S::SharedArray) + +Get the vector of processes that have mapped the shared array +""" +procs + +doc""" + sdata(S::SharedArray) + +Returns the actual `Array` object backing `S` +""" +sdata + +doc""" + indexpids(S::SharedArray) + +Returns the index of the current worker into the `pids` vector, +i.e., the list of workers mapping the SharedArray +""" +indexpids + +doc""" + launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + +Implemented by cluster managers. For every Julia worker launched by +this function, it should append a `WorkerConfig` entry to +once all workers, requested by `manager` have been launched. +was called with. +""" +launch + +doc""" + manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + +Implemented by cluster managers. It is called on the master +process, during a worker's lifetime, with appropriate `op` +values: +""" +manage + +doc""" + kill(manager::FooManager, pid::Int, config::WorkerConfig) + +Implemented by cluster managers. It is called on the master +process, by `rmprocs`. It should cause the remote worker +specified by `pid` to exit. +""" +kill + +doc""" + init_worker(manager::FooManager) + +Called by cluster managers implementing custom transports. It +initializes a newly launched process as a worker. Command line +argument `--worker` has the effect of initializing a process as a +worker using TCP/IP sockets for transport. +""" +init_worker + +doc""" + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + +Implemented by cluster managers using custom transports. It should +establish a logical connection to worker with id `pid`, specified +by `config` and return a pair of `AsyncStream` objects. +Messages from `pid` to current process will be read off +messages are delivered and received completely and in order. +socket connections in-between workers. +""" +connect + +doc""" + Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + +Called by cluster managers using custom transports. It should be +called when the custom transport implementation receives the first +message from a remote worker. The custom transport must manage a +logical connection to the remote worker and provide two AsyncStream +objects, one for incoming messages and the other for messages +addressed to the remote worker. +""" +Base + +doc""" + dir() -> AbstractString + +Returns the absolute path of the package directory. This defaults +to `joinpath(homedir(),`.julia`,`v\$(VERSION.major).\$(VERSION +syntax). If the `JULIA_PKGDIR` environment variable is set, then +that path is used in the returned value as `joinpath(ENV[`JULIA_ +PKGDIR`],`v\$(VERSION.major).\$(VERSION.minor)`)`. If +whatever the current working directory is. +""" +Base.Pkg.dir + +doc""" + dir(names...) -> AbstractString + +Equivalent to `normpath(Pkg.dir(),names...)` – i.e. it appends +path components to the package directory and normalizes the +resulting path. In particular, `Pkg.dir(pkg)` returns the path to +the package `pkg`. +""" +Base.Pkg.dir + +doc""" + init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) + +Initialize `Pkg.dir()` as a package directory. This will be done +automatically when the `JULIA_PKGDIR` is not set and +clones a local METADATA git repository from the site and branch +specified by its arguments, which are typically not provided. +Explicit (non-default) arguments can be used to support a custom +METADATA setup. +""" +Base.Pkg.init + +doc""" + resolve() + +Determines an optimal, consistent set of package versions to +install or upgrade to. The optimal set of package versions is based +on the contents of `Pkg.dir(`REQUIRE`)` and the state of +installed packages in `Pkg.dir()`, Packages that are no longer +required are moved into `Pkg.dir(`.trash`)`. +""" +Base.Pkg.resolve + +doc""" + edit() + +Opens `Pkg.dir(`REQUIRE`)` in the editor specified by the +command returns, it runs `Pkg.resolve()` to determine and install +a new optimal set of installed package versions. +""" +Base.Pkg.edit + +doc""" + add(pkg, vers...) + +Add a requirement entry for `pkg` to `Pkg.dir(`REQUIRE`)` and +call `Pkg.resolve()`. If `vers` are given, they must be +intervals for `pkg`. +""" +Base.Pkg.add + +doc""" + rm(pkg) + +Remove all requirement entries for `pkg` from +""" +Base.Pkg.rm + +doc""" + clone(url[, pkg]) + +Clone a package directly from the git URL `url`. The package does +not need to be a registered in `Pkg.dir(`METADATA`)`. The +package repo is cloned by the name `pkg` if provided; if not +provided, `pkg` is determined automatically from `url`. +""" +Base.Pkg.clone + +doc""" + clone(pkg) + +If `pkg` has a URL registered in `Pkg.dir(`METADATA`)`, clone +it from that URL on the default branch. The package does not need +to have any registered versions. +""" +Base.Pkg.clone + +doc""" + available() -> Vector{ASCIIString} + +Returns the names of available packages. +""" +Base.Pkg.available + +doc""" + available(pkg) -> Vector{VersionNumber} + +Returns the version numbers available for package `pkg`. +""" +Base.Pkg.available + +doc""" + installed() -> Dict{ASCIIString,VersionNumber} + +Returns a dictionary mapping installed package names to the +installed version number of each package. +""" +Base.Pkg.installed + +doc""" + installed(pkg) -> Void | VersionNumber + +If `pkg` is installed, return the installed version number, +otherwise return `nothing`. +""" +Base.Pkg.installed + +doc""" + status() + +Prints out a summary of what packages are installed and what +version and state they're in. +""" +Base.Pkg.status + +doc""" + update() + +Update package the metadata repo – kept in +safely be pulled from their origin; then call `Pkg.resolve()` to +determine a new optimal set of packages versions. +""" +Base.Pkg.update + +doc""" + checkout(pkg[, branch="master"]) + +Checkout the `Pkg.dir(pkg)` repo to the branch `branch`. +Defaults to checking out the `master` branch. To go back to using +the newest compatible released version, use `Pkg.free(pkg)` +""" +Base.Pkg.checkout + +doc""" + pin(pkg) + +Pin `pkg` at the current version. To go back to using the newest +compatible released version, use `Pkg.free(pkg)` +""" +Base.Pkg.pin + +doc""" + pin(pkg, version) + +Pin `pkg` at registered version `version`. +""" +Base.Pkg.pin + +doc""" + free(pkg) + +Free the package `pkg` to be managed by the package manager +again. It calls `Pkg.resolve()` to determine optimal package +versions after. This is an inverse for both `Pkg.checkout` and +You can also supply an iterable collection of package names, e.g., +once. +""" +Base.Pkg.free + +doc""" + build() + +Run the build scripts for all installed packages in depth-first +recursive order. +""" +Base.Pkg.build + +doc""" + build(pkgs...) + +Run the build script in `deps/build.jl` for each package in +order. This is called automatically by `Pkg.resolve()` on all +installed or updated packages. +""" +Base.Pkg.build + +doc""" + generate(pkg, license) + +Generate a new package named `pkg` with one of these license +keys: ``MIT``, ``BSD`` or ``ASL``. If you want to make +a package with a different license, you can edit it afterwards. +Generate creates a git repo at `Pkg.dir(pkg)` for the package and +inside it `LICENSE.md`, `README.md`, the julia entrypoint +""" +Base.Pkg.generate + +doc""" + register(pkg[, url]) + +Register `pkg` at the git URL `url`, defaulting to the +configured origin URL of the git repo `Pkg.dir(pkg)`. +""" +Base.Pkg.register + +doc""" + tag(pkg[, ver[, commit]]) + +Tag `commit` as version `ver` of package `pkg` and create a +version entry in `METADATA`. If not provided, `commit` defaults +to the current commit of the `pkg` repo. If `ver` is one of the +symbols `:patch`, `:minor`, `:major` the next patch, minor or +major version is used. If `ver` is not provided, it defaults to +""" +Base.Pkg.tag + +doc""" + publish() + +For each new package version tagged in `METADATA` not already +published, make sure that the tagged package commits have been +pushed to the repo at the registered URL for the package and if +they all have, open a pull request to `METADATA`. +""" +Base.Pkg.publish + +doc""" + test() + +Run the tests for all installed packages ensuring that each +package's test dependencies are installed for the duration of the +test. A package is tested by running its `test/runtests.jl` file +and test dependencies are specified in `test/REQUIRE`. +""" +Base.Pkg.test + +doc""" + test(pkgs...) + +Run the tests for each package in `pkgs` ensuring that each +package's test dependencies are installed for the duration of the +test. A package is tested by running its `test/runtests.jl` file +and test dependencies are specified in `test/REQUIRE`. +""" +Base.Pkg.test + +doc""" + @profile() + +periodic backtraces. These are appended to an internal buffer of +backtraces. +""" +@profile + +doc""" + clear() + +Clear any existing backtraces from the internal buffer. +""" +Base.Profile.clear + +doc""" + print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + +Prints profiling results to `io` (by default, `STDOUT`). If you +do not supply a `data` vector, the internal buffer of accumulated +backtraces will be used. `format` can be `:tree` or `:flat`. +If `C==true`, backtraces from C and Fortran code are shown. +the same line of code. `cols` controls the width of the display. +""" +Base.Profile.print + +doc""" + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + +Prints profiling results to `io`. This variant is used to examine +results exported by a previous call to `retrieve()`. Supply the +vector `data` of backtraces and a dictionary `lidict` of line +information. +""" +Base.Profile.print + +doc""" + init(; n::Integer, delay::Float64) + +Configure the `delay` between backtraces (measured in seconds), +and the number `n` of instruction pointers that may be stored. +Each instruction pointer corresponds to a single line of code; +backtraces generally consist of a long list of instruction +pointers. Default settings can be obtained by calling this function +with no arguments, and each can be set independently using keywords +or in the order `(n, delay)`. +""" +Base.Profile.init + +doc""" + fetch() -> data + +Returns a reference to the internal buffer of backtraces. Note that +subsequent operations, like `clear()`, can affect `data` unless +you first make a copy. Note that the values in `data` have +meaning only on this machine in the current session, because it +depends on the exact memory addresses used in JIT-compiling. This +function is primarily for internal use; `retrieve()` may be a +better choice for most users. +""" +Base.Profile.fetch + +doc""" + retrieve() -> data, lidict + +set of all backtraces (`data`) and a dictionary that maps the +values that store the file name, function name, and line number. +This function allows you to save profiling results for future +analysis. +""" +Base.Profile.retrieve + +doc""" + callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} + +Given a previous profiling run, determine who called a particular +function. Supplying the filename (and optionally, range of line +numbers over which the function is defined) allows you to +disambiguate an overloaded method. The returned value is a vector +containing a count of the number of calls and line information +about the caller. One can optionally supply backtrace data +obtained from `retrieve()`; otherwise, the current internal +profile buffer is used. +""" +Base.Profile.callers + +doc""" + clear_malloc_data() + +Clears any stored memory allocation data when running julia with ` +force JIT-compilation), then call `clear_malloc_data()`. Then +execute your command(s) again, quit Julia, and examine the +resulting `*.mem` files. +""" +Base.Profile.clear_malloc_data + +doc""" + sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the vector `v` in place. `QuickSort` is used by default +for numeric arrays while `MergeSort` is used for other arrays. +You can specify an algorithm to use via the `alg` keyword (see +Sorting Algorithms for available algorithms). The `by` keyword +lets you provide a function that will be applied to each element +before comparison; the `lt` keyword allows providing a custom +order. These options are independent and can be used together in +all possible combinations: if both `by` and `lt` are specified, +the `lt` function is applied to the result of the `by` +function; `rev=true` reverses whatever ordering specified via the +""" +sort! + +doc""" + sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + +Variant of `sort!` that returns a sorted copy of `v` leaving +""" +sort + +doc""" + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort a multidimensional array `A` along the given dimension. +""" +sort + +doc""" + sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + +Return a permutation vector of indices of `v` that puts it in +sorted order. Specify `alg` to choose a particular sorting +algorithm (see Sorting Algorithms). `MergeSort` is used by +default, and since it is stable, the resulting permutation will be +the lexicographically first one that puts the input array into +sorted order – i.e. indices of equal elements appear in ascending +order. If you choose a non-stable sorting algorithm such as +order may be returned. The order is specified using the same +keywords as `sort!`. +See also `sortperm!()` +""" +sortperm + +doc""" + sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + +Like `sortperm`, but accepts a preallocated index vector `ix`. +If `initialized` is `false` (the default), ix is initialized to +contain the values `1:length(v)`. +See also `sortperm()` +""" +sortperm! + +doc""" + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the rows of matrix `A` lexicographically. +""" +sortrows + +doc""" + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the columns of matrix `A` lexicographically. +""" +sortcols + +doc""" + issorted(v, [by=,] [lt=,] [rev=false]) + +Test whether a vector is in sorted order. The `by`, `lt` and +as they do for `sort`. +""" +issorted + +doc""" + searchsorted(a, x, [by=,] [lt=,] [rev=false]) + +Returns the range of indices of `a` which compare as equal to +order. Returns an empty range located at the insertion point if +""" +searchsorted + +doc""" + searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + +Returns the index of the first value in `a` greater than or equal +to `x`, according to the specified order. Returns `length(a)+1` +if `x` is greater than all values in `a`. +""" +searchsortedfirst + +doc""" + searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + +Returns the index of the last value in `a` less than or equal to +less than all values in `a`. +""" +searchsortedlast + +doc""" + select!(v, k, [by=,] [lt=,] [rev=false]) + +Partially sort the vector `v` in place, according to the order +specified by `by`, `lt` and `rev` so that the value at index +the position where it would appear if the array were fully sorted +via a non-stable algorithm. If `k` is a single index, that value +is returned; if `k` is a range, an array of values at those +indices is returned. Note that `select!` does not fully sort the +input array. +""" +select! + +doc""" + select(v, k, [by=,] [lt=,] [rev=false]) + +Variant of `select!` which copies `v` before partially sorting +it, thereby returning the same thing as `select!` but leaving +""" +select + +doc""" + length(s) + +The number of characters in string `s`. +""" +length + +doc""" + sizeof(s::AbstractString) + +The number of bytes in string `s`. +""" +sizeof + +doc""" + *(s, t) + +Concatenate strings. The `*` operator is an alias to this +function. +""" +Base.(:(*)) + +doc""" + ^(s, n) + +Repeat `n` times the string `s`. The `^` operator is an alias +to this function. +""" +Base.(:(^)) + +doc""" + string(xs...) + +Create a string from any values using the `print` function. +""" +string + +doc""" + repr(x) + +Create a string from any value using the `showall` function. +""" +repr + +doc""" + bytestring(::Ptr{UInt8}[, length]) + +Create a string from the address of a C (0-terminated) string +encoded in ASCII or UTF-8. A copy is made; the ptr can be safely +freed. If `length` is specified, the string does not have to be +0-terminated. +""" +bytestring + +doc""" + bytestring(s) + +Convert a string to a contiguous byte array representation +appropriate for passing it to C functions. The string will be +encoded as either ASCII or UTF-8. +""" +bytestring + +doc""" + ascii(::Array{UInt8, 1}) + +Create an ASCII string from a byte array. +""" +ascii + +doc""" + ascii(s) + +Convert a string to a contiguous ASCII string (all characters must +be valid ASCII characters). +""" +ascii + +doc""" + ascii(::Ptr{UInt8}[, length]) + +Create an ASCII string from the address of a C (0-terminated) +string encoded in ASCII. A copy is made; the ptr can be safely +freed. If `length` is specified, the string does not have to be +0-terminated. +""" +ascii + +doc""" + utf8(::Array{UInt8, 1}) + +Create a UTF-8 string from a byte array. +""" +utf8 + +doc""" + utf8(::Ptr{UInt8}[, length]) + +Create a UTF-8 string from the address of a C (0-terminated) string +encoded in UTF-8. A copy is made; the ptr can be safely freed. If +0-terminated. +""" +utf8 + +doc""" + utf8(s) + +Convert a string to a contiguous UTF-8 string (all characters must +be valid UTF-8 characters). +""" +utf8 + +doc""" + normalize_string(s, normalform::Symbol) + +Normalize the string `s` according to one of the four `normal +forms` of the Unicode standard: `normalform` can be `:NFC`, +composition) and D (canonical decomposition) convert different +visually identical representations of the same abstract string into +a single canonical form, with form C being more compact. Normal +forms KC and KD additionally canonicalize `compatibility +equivalents`: they convert characters that are abstractly similar +but visually distinct into a single canonical choice (e.g. they +expand ligatures into the individual characters), with form KC +being more compact. +Alternatively, finer control and additional transformations may be +be obtained by calling *normalize_string(s; keywords...)*, where +any number of the following boolean keywords options (which all +default to `false` except for `compose`) are specified: +For example, NFKC corresponds to the options `compose=true, +compat=true, stable=true`. +""" +normalize_string + +doc""" + graphemes(s) -> iterator over substrings of s + +Returns an iterator over substrings of `s` that correspond to the +extended graphemes in the string, as defined by Unicode UAX #29. +even though they may contain more than one codepoint; for example a +letter combined with an accent mark is a single grapheme.) +""" +graphemes + +doc""" + isvalid(value) -> Bool + +Returns true if the given value is valid for its type, which +currently can be one of `Char`, `ASCIIString`, `UTF8String`, +""" +isvalid + +doc""" + isvalid(T, value) -> Bool + +Returns true if the given value is valid for that type. Types +currently can be `Char`, `ASCIIString`, `UTF8String`, +type `Char` or `UInt32` Values for `ASCIIString` and +for `UTF32String` can be `UTF32String`, `Vector{Char}` or +""" +isvalid + +doc""" + is_assigned_char(c) -> Bool + +Returns true if the given char or integer is an assigned Unicode +code point. +""" +is_assigned_char + +doc""" + ismatch(r::Regex, s::AbstractString) -> Bool + +Test whether a string contains a match of the given regular +expression. +""" +ismatch + +doc""" + match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + +Search for the first match of the regular expression `r` in `s` +and return a RegexMatch object containing the match, or nothing if +the match failed. The matching substring can be retrieved by +accessing `m.match` and the captured sequences can be retrieved +by accessing `m.captures` The optional `idx` argument specifies +an index at which to start the search. +""" +match + +doc""" + eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + +Search for all matches of a the regular expression `r` in `s` +and return a iterator over the matches. If overlap is true, the +matching sequences are allowed to overlap indices in the original +string, otherwise they must be from distinct character ranges. +""" +eachmatch + +doc""" + matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + +Return a vector of the matching substrings from eachmatch. +""" +matchall + +doc""" + lpad(string, n, p) + +Make a string at least `n` columns wide when printed, by padding +on the left with copies of `p`. +""" +lpad + +doc""" + rpad(string, n, p) + +Make a string at least `n` columns wide when printed, by padding +on the right with copies of `p`. +""" +rpad + +doc""" + search(string, chars[, start]) + +Search for the first occurrence of the given characters within the +given string. The second argument may be a single character, a +vector or a set of characters, a string, or a regular expression +such as ASCII or UTF-8 strings). The third argument optionally +specifies a starting index. The return value is a range of indexes +where the matching sequence is found, such that `s[search(s,x)] == +x`: +""" +search + +doc""" + rsearch(string, chars[, start]) + +Similar to `search`, but returning the last occurrence of the +given characters within the given string, searching in reverse from +""" +rsearch + +doc""" + searchindex(string, substring[, start]) + +Similar to `search`, but return only the start index at which the +substring is found, or 0 if it is not. +""" +searchindex + +doc""" + rsearchindex(string, substring[, start]) + +Similar to `rsearch`, but return only the start index at which +the substring is found, or 0 if it is not. +""" +rsearchindex + +doc""" + contains(haystack, needle) + +Determine whether the second argument is a substring of the first. +""" +contains + +doc""" + replace(string, pat, r[, n]) + +Search for the given pattern `pat`, and replace each occurrence +with `r`. If `n` is provided, replace at most `n` +occurrences. As with search, the second argument may be a single +character, a vector or a set of characters, a string, or a regular +expression. If `r` is a function, each occurrence is replaced +with `r(s)` where `s` is the matched substring. +""" +replace + +doc""" + split(string, [chars]; limit=0, keep=true) + +Return an array of substrings by splitting the given string on +occurrences of the given character delimiters, which may be +specified in any of the formats allowed by `search`'s second +argument (i.e. a single character, collection of characters, +string, or regular expression). If `chars` is omitted, it +defaults to the set of all space characters, and `keep` is taken +to be false. The two keyword arguments are optional: they are are a +maximum size for the result and a flag determining whether empty +fields should be kept in the result. +""" +split + +doc""" + rsplit(string, [chars]; limit=0, keep=true) + +Similar to `split`, but starting from the end of the string. +""" +rsplit + +doc""" + strip(string[, chars]) + +Return `string` with any leading and trailing whitespace removed. +If `chars` (a character, or vector or set of characters) is +provided, instead remove characters contained in it. +""" +strip + +doc""" + lstrip(string[, chars]) + +Return `string` with any leading whitespace removed. If `chars` +remove characters contained in it. +""" +lstrip + +doc""" + rstrip(string[, chars]) + +Return `string` with any trailing whitespace removed. If +provided, instead remove characters contained in it. +""" +rstrip + +doc""" + startswith(string, prefix | chars) + +Returns `true` if `string` starts with `prefix`. If the +second argument is a vector or set of characters, tests whether the +first character of `string` belongs to that set. +""" +startswith + +doc""" + endswith(string, suffix | chars) + +Returns `true` if `string` ends with `suffix`. If the second +argument is a vector or set of characters, tests whether the last +character of `string` belongs to that set. +""" +endswith + +doc""" + uppercase(string) + +Returns `string` with all characters converted to uppercase. +""" +uppercase + +doc""" + lowercase(string) + +Returns `string` with all characters converted to lowercase. +""" +lowercase + +doc""" + ucfirst(string) + +Returns `string` with the first character converted to uppercase. +""" +ucfirst + +doc""" + lcfirst(string) + +Returns `string` with the first character converted to lowercase. +""" +lcfirst + +doc""" + join(strings, delim[, last]) + +Join an array of `strings` into a single string, inserting the +given delimiter between adjacent strings. If `last` is given, it +will be used instead of `delim` between the last two strings. For +example, `join([`apples`, `bananas`, `pineapples`], `, `, +convertible to strings via `print(io::IOBuffer, x)`. +""" +join + +doc""" + chop(string) + +Remove the last character from a string +""" +chop + +doc""" + chomp(string) + +Remove a trailing newline from a string +""" +chomp + +doc""" + ind2chr(string, i) + +Convert a byte index to a character index +""" +ind2chr + +doc""" + chr2ind(string, i) + +Convert a character index to a byte index +""" +chr2ind + +doc""" + isvalid(str, i) + +Tells whether index `i` is valid for the given string +""" +isvalid + +doc""" + nextind(str, i) + +Get the next valid string index after `i`. Returns a value +greater than `endof(str)` at or after the end of the string. +""" +nextind + +doc""" + prevind(str, i) + +Get the previous valid string index before `i`. Returns a value +less than `1` at the beginning of the string. +""" +prevind + +doc""" + randstring([rng], len=8) + +Create a random ASCII string of length `len`, consisting of +upper- and lower-case letters and the digits 0-9. The optional +Numbers*. +""" +randstring + +doc""" + charwidth(c) + +Gives the number of columns needed to print a character. +""" +charwidth + +doc""" + strwidth(s) + +Gives the number of columns needed to print a string. +""" +strwidth + +doc""" + isalnum(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is alphanumeric, or whether this is true +for all elements of a string. A character is classified as +alphabetic if it belongs to the Unicode general category Letter or +Number, i.e. a character whose category code begins with 'L' or +""" +isalnum + +doc""" + isalpha(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is alphabetic, or whether this is true +for all elements of a string. A character is classified as +alphabetic if it belongs to the Unicode general category Letter, +i.e. a character whose category code begins with 'L'. +""" +isalpha + +doc""" + isascii(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character belongs to the ASCII character set, or +whether this is true for all elements of a string. +""" +isascii + +doc""" + iscntrl(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a control character, or whether this +is true for all elements of a string. Control characters are the +non-printing characters of the Latin-1 subset of Unicode. +""" +iscntrl + +doc""" + isdigit(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a numeric digit (0-9), or whether this +is true for all elements of a string. +""" +isdigit + +doc""" + isgraph(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is printable, and not a space, or whether +this is true for all elements of a string. Any character that +would cause a printer to use ink should be classified with +isgraph(c)==true. +""" +isgraph + +doc""" + islower(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a lowercase letter, or whether this is +true for all elements of a string. A character is classified as +lowercase if it belongs to Unicode category Ll, Letter: Lowercase. +""" +islower + +doc""" + isnumber(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is numeric, or whether this is true for +all elements of a string. A character is classified as numeric if +it belongs to the Unicode general category Number, i.e. a character +whose category code begins with 'N'. +""" +isnumber + +doc""" + isprint(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is printable, including spaces, but not a +control character. For strings, tests whether this is true for all +elements of the string. +""" +isprint + +doc""" + ispunct(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character belongs to the Unicode general category +Punctuation, i.e. a character whose category code begins with 'P'. +For strings, tests whether this is true for all elements of the +string. +""" +ispunct + +doc""" + isspace(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is any whitespace character. Includes +ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', +Latin-1 character U+0085, and characters in Unicode category Zs. +For strings, tests whether this is true for all elements of the +string. +""" +isspace + +doc""" + isupper(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is an uppercase letter, or whether this +is true for all elements of a string. A character is classified +as uppercase if it belongs to Unicode category Lu, Letter: +Uppercase, or Lt, Letter: Titlecase. +""" +isupper + +doc""" + isxdigit(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a valid hexadecimal digit, or whether +this is true for all elements of a string. +""" +isxdigit + +doc""" + symbol(x...) -> Symbol + +Create a `Symbol` by concatenating the string representations of +the arguments together. +""" +symbol + +doc""" + escape_string(str::AbstractString) -> AbstractString + +General escaping of traditional C and Unicode escape sequences. See +""" +escape_string + +doc""" + unescape_string(s::AbstractString) -> AbstractString + +General unescaping of traditional C and Unicode escape sequences. +Reverse of `escape_string()`. See also `print_unescaped()`. +""" +unescape_string + +doc""" + utf16(s) + +Create a UTF-16 string from a byte array, array of `UInt16`, or +any other string type. (Data must be valid UTF-16. Conversions of +byte arrays check for a byte-order marker in the first two bytes, +and do not include it in the resulting string.) +Note that the resulting `UTF16String` data is terminated by the +NUL codepoint (16-bit zero), which is not treated as a character in +the string (so that it is mostly invisible in Julia); this allows +the string to be passed directly to external functions requiring +NUL-terminated data. This NUL is appended automatically by the +can instead use *UTF16String(A)`* to construct the string without +making a copy of the data and treating the NUL as a terminator +rather than as part of the string. +""" +utf16 + +doc""" + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + +Create a string from the address of a NUL-terminated UTF-16 string. +A copy is made; the pointer can be safely freed. If `length` is +specified, the string does not have to be NUL-terminated. +""" +utf16 + +doc""" + utf32(s) + +Create a UTF-32 string from a byte array, array of `Char` or +check for a byte-order marker in the first four bytes, and do not +include it in the resulting string.) +Note that the resulting `UTF32String` data is terminated by the +NUL codepoint (32-bit zero), which is not treated as a character in +the string (so that it is mostly invisible in Julia); this allows +the string to be passed directly to external functions requiring +NUL-terminated data. This NUL is appended automatically by the +then you can instead use *UTF32String(A)`* to construct the string +without making a copy of the data and treating the NUL as a +terminator rather than as part of the string. +""" +utf32 + +doc""" + utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) + +Create a string from the address of a NUL-terminated UTF-32 string. +A copy is made; the pointer can be safely freed. If `length` is +specified, the string does not have to be NUL-terminated. +""" +utf32 + +doc""" + wstring(s) + +This is a synonym for either `utf32(s)` or `utf16(s)`, +depending on whether `Cwchar_t` is 32 or 16 bits, respectively. +The synonym `WString` for `UTF32String` or `UTF16String` is +also provided. +""" +wstring + +doc""" + runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) + +Run the Julia unit tests listed in `tests`, which can be either a +string or an array of strings, using `numcores` processors. (not +exported) +""" +runtests + +doc""" + @test(ex) + +Test the expression `ex` and calls the current handler to handle +the result. +""" +Base.Test.@test + +doc""" + @test_throws(extype, ex) + +Test that the expression `ex` throws an exception of type +""" +Base.Test.@test_throws + +doc""" + @test_approx_eq(a, b) + +Test two floating point numbers `a` and `b` for equality taking +in account small numerical errors. +""" +Base.Test.@test_approx_eq + +doc""" + @test_approx_eq_eps(a, b, tol) + +Test two floating point numbers `a` and `b` for equality taking +in account a margin of tolerance given by `tol`. +""" +Base.Test.@test_approx_eq_eps + +doc""" + with_handler(f, handler) + +Run the function `f` using the `handler` as the handler. +""" +Base.Test.with_handler - @doc doc""" - ```rst - iseven(x::Integer) -> Bool - - Returns "true" is "x" is even (that is, divisible by 2), and - "false" otherwise. - - julia> iseven(9) - false - - julia> iseven(10) - true - ``` - """ iseven - - @doc doc""" - ```rst - precision(num::FloatingPoint) - - Get the precision of a floating point number, as defined by the - effective number of bits in the mantissa. - ``` - """ precision - - @doc doc""" - ```rst - get_bigfloat_precision() - - Get the precision (in bits) currently used for BigFloat arithmetic. - ``` - """ get_bigfloat_precision - - @doc doc""" - ```rst - set_bigfloat_precision(x::Int64) - - Set the precision (in bits) to be used to BigFloat arithmetic. - ``` - """ set_bigfloat_precision - - @doc doc""" - ```rst - with_bigfloat_precision(f::Function, precision::Integer) - - Change the BigFloat arithmetic precision (in bits) for the duration - of "f". It is logically equivalent to: - - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) - ``` - """ with_bigfloat_precision - - @doc doc""" - ```rst - srand([rng][, seed]) - - Reseed the random number generator. If a "seed" is provided, the - RNG will give a reproducible sequence of numbers, otherwise Julia - will get entropy from the system. For "MersenneTwister", the - "seed" may be a non-negative integer, a vector of "UInt32" - integers or a filename, in which case the seed is read from a file. - "RandomDevice" does not support seeding. - ``` - """ srand - - @doc doc""" - ```rst - MersenneTwister([seed]) - - Create a "MersenneTwister" RNG object. Different RNG objects can - have their own seeds, which may be useful for generating different - streams of random numbers. - ``` - """ MersenneTwister - - @doc doc""" - ```rst - RandomDevice() - - Create a "RandomDevice" RNG object. Two such objects will always - generate different streams of random numbers. - ``` - """ RandomDevice - - @doc doc""" - ```rst - rand([rng][, S][, dims...]) - - Pick a random element or array of random elements from the set of - values specified by "S"; "S" can be - - * an indexable collection (for example "1:n" or - "['x','y','z']"), or - - * a type: the set of values to pick from is then equivalent to - "typemin(S):typemax(S)" for integers (this is not applicable to - "BigInt"), and to [0,1) for floating point numbers; - - "S" defaults to "Float64". - ``` - """ rand - - @doc doc""" - ```rst - rand!([rng], A[, coll]) - - Populate the array A with random values. If the indexable - collection "coll" is specified, the values are picked randomly - from "coll". This is equivalent to "copy!(A, rand(rng, coll, - size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but - without allocating a new array. - ``` - """ rand! - - @doc doc""" - ```rst - bitrand([rng][, dims...]) - - Generate a "BitArray" of random boolean values. - ``` - """ bitrand - - @doc doc""" - ```rst - randn([rng][, dims...]) - - Generate a normally-distributed random number with mean 0 and - standard deviation 1. Optionally generate an array of normally- - distributed random numbers. - ``` - """ randn - - @doc doc""" - ```rst - randn!([rng], A::Array{Float64, N}) - - Fill the array A with normally-distributed (mean 0, standard - deviation 1) random numbers. Also see the rand function. - ``` - """ randn! - - @doc doc""" - ```rst - randexp([rng][, dims...]) - - Generate a random number according to the exponential distribution - with scale 1. Optionally generate an array of such random numbers. - ``` - """ randexp - - @doc doc""" - ```rst - randexp!([rng], A::Array{Float64, N}) - - Fill the array A with random numbers following the exponential - distribution (with scale 1). - ``` - """ randexp! - - @doc doc""" - ```rst - Task(func) - - Create a "Task" (i.e. thread, or coroutine) to execute the given - function (which must be callable with no arguments). The task exits - when this function returns. - ``` - """ Task - - @doc doc""" - ```rst - yieldto(task, arg = nothing) - - Switch to the given task. The first time a task is switched to, the - task's function is called with no arguments. On subsequent - switches, "arg" is returned from the task's last call to - "yieldto". This is a low-level call that only switches tasks, not - considering states or scheduling in any way. Its use is - discouraged. - ``` - """ yieldto - - @doc doc""" - ```rst - current_task() - - Get the currently running Task. - ``` - """ current_task - - @doc doc""" - ```rst - istaskdone(task) -> Bool - - Tell whether a task has exited. - ``` - """ istaskdone - - @doc doc""" - ```rst - istaskstarted(task) -> Bool - - Tell whether a task has started executing. - ``` - """ istaskstarted - - @doc doc""" - ```rst - consume(task, values...) - - Receive the next value passed to "produce" by the specified task. - Additional arguments may be passed, to be returned from the last - "produce" call in the producer. - ``` - """ consume - - @doc doc""" - ```rst - produce(value) - - Send the given value to the last "consume" call, switching to the - consumer task. If the next "consume" call passes any values, they - are returned by "produce". - ``` - """ produce - - @doc doc""" - ```rst - yield() - - Switch to the scheduler to allow another scheduled task to run. A - task that calls this function is still runnable, and will be - restarted immediately if there are no other runnable tasks. - ``` - """ yield - - @doc doc""" - ```rst - task_local_storage(symbol) - - Look up the value of a symbol in the current task's task-local - storage. - ``` - """ task_local_storage - - @doc doc""" - ```rst - task_local_storage(symbol, value) - - Assign a value to a symbol in the current task's task-local - storage. - ``` - """ task_local_storage - - @doc doc""" - ```rst - task_local_storage(body, symbol, value) - - Call the function "body" with a modified task-local storage, in - which "value" is assigned to "symbol"; the previous value of - "symbol", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. - ``` - """ task_local_storage - - @doc doc""" - ```rst - Condition() - - Create an edge-triggered event source that tasks can wait for. - Tasks that call "wait" on a "Condition" are suspended and - queued. Tasks are woken up when "notify" is later called on the - "Condition". Edge triggering means that only tasks waiting at the - time "notify" is called can be woken up. For level-triggered - notifications, you must keep extra state to keep track of whether a - notification has happened. The "RemoteRef" type does this, and so - can be used for level-triggered events. - ``` - """ Condition - - @doc doc""" - ```rst - notify(condition, val=nothing; all=true, error=false) - - Wake up tasks waiting for a condition, passing them "val". If - "all" is true (the default), all waiting tasks are woken, - otherwise only one is. If "error" is true, the passed value is - raised as an exception in the woken tasks. - ``` - """ notify - - @doc doc""" - ```rst - schedule(t::Task, [val]; error=false) - - Add a task to the scheduler's queue. This causes the task to run - constantly when the system is otherwise idle, unless the task - performs a blocking operation such as "wait". - - If a second argument is provided, it will be passed to the task - (via the return value of "yieldto") when it runs again. If - "error" is true, the value is raised as an exception in the woken - task. - ``` - """ schedule - - @doc doc""" - ```rst - @schedule() - - Wrap an expression in a Task and add it to the scheduler's queue. - ``` - """ @schedule - - @doc doc""" - ```rst - @task() - - Wrap an expression in a Task without executing it, and return the - Task. This only creates a task, and does not run it. - ``` - """ @task - - @doc doc""" - ```rst - sleep(seconds) - - Block the current task for a specified number of seconds. The - minimum sleep time is 1 millisecond or input of "0.001". - ``` - """ sleep - - @doc doc""" - ```rst - ReentrantLock() - - Creates a reentrant lock. The same task can acquire the lock as - many times as required. Each lock must be matched with an unlock. - ``` - """ ReentrantLock - - @doc doc""" - ```rst - lock(l::ReentrantLock) - - Associates "l" with the current task. If "l" is already locked - by a different task, waits for it to become available. The same - task can acquire the lock multiple times. Each "lock" must be - matched by an "unlock" - ``` - """ lock - - @doc doc""" - ```rst - unlock(l::ReentrantLock) - - Releases ownership of the lock by the current task. If the lock had - been acquired before, it just decrements an internal counter and - returns immediately. - ``` - """ unlock - - @doc doc""" - ```rst - addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built "LocalManager" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. "addprocs(4)" will add 4 processes - on the local machine. - ``` - """ addprocs - - @doc doc""" - ```rst - addprocs() -> List of process identifiers - - Equivalent to "addprocs(CPU_CORES)" - ``` - """ addprocs - - @doc doc""" - ```rst - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - "machines" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string "machine_spec" or a - tuple - "(machine_spec, count)" - - "machine_spec" is a string of the form "[user@]host[:port] - [bind_addr[:port]]". "user" defaults to current user, "port" - to the standard ssh port. If "[bind_addr[:port]]" is specified, - other workers will connect to this worker at the specified - "bind_addr" and "port". - - "count" is the number of workers to be launched on the specified - host. If specified as ":auto" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: - - "tunnel" : if "true" then SSH tunneling will be used to connect - to the worker from the master process. - - "sshflags" : specifies additional ssh options, e.g. - "sshflags=`-i /home/foo/bar.pem`" . - - "max_parallel" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. - - "dir" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) - - "exename" : name of the julia executable. Defaults to - "\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case - may be. - - "exeflags" : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable "JULIA_WORKER_TIMEOUT". The value of - "JULIA_WORKER_TIMEOUT" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. - ``` - """ addprocs - - @doc doc""" - ```rst - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster - manager implemented in package "ClusterManagers". - - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - "JULIA_WORKER_TIMEOUT" in the worker process's environment. - Relevant only when using TCP/IP as transport. - ``` - """ addprocs - - @doc doc""" - ```rst - nprocs() - - Get the number of available processes. - ``` - """ nprocs - @doc doc""" - ```rst - nworkers() - - Get the number of available worker processes. This is one less than - nprocs(). Equal to nprocs() if nprocs() == 1. - ``` - """ nworkers - - @doc doc""" - ```rst - procs() - - Returns a list of all process identifiers. - ``` - """ procs - - @doc doc""" - ```rst - workers() - - Returns a list of all worker process identifiers. - ``` - """ workers - - @doc doc""" - ```rst - rmprocs(pids...) - - Removes the specified workers. - ``` - """ rmprocs - - @doc doc""" - ```rst - interrupt([pids...]) - - Interrupt the current executing task on the specified workers. This - is equivalent to pressing Ctrl-C on the local machine. If no - arguments are given, all workers are interrupted. - ``` - """ interrupt - - @doc doc""" - ```rst - myid() - - Get the id of the current process. - ``` - """ myid - - @doc doc""" - ```rst - pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - - Transform collections "lsts" by applying "f" to each element in - parallel. If "nprocs() > 1", the calling process will be - dedicated to assigning tasks. All other available processes will be - used as parallel workers, or on the processes specified by - "pids". - - If "err_retry" is true, it retries a failed application of "f" - on a different worker. If "err_stop" is true, it takes precedence - over the value of "err_retry" and "pmap" stops execution on the - first error. - ``` - """ pmap - - @doc doc""" - ```rst - remotecall(id, func, args...) - - Call a function asynchronously on the given arguments on the - specified process. Returns a "RemoteRef". - ``` - """ remotecall - - @doc doc""" - ```rst - wait([x]) - - Block the current task until some event occurs, depending on the - type of the argument: - - * "RemoteRef": Wait for a value to become available for the - specified remote reference. - - * "Condition": Wait for "notify" on a condition. - - * "Process": Wait for a process or process chain to exit. The - "exitcode" field of a process can be used to determine success - or failure. - - * "Task": Wait for a "Task" to finish, returning its result - value. If the task fails with an exception, the exception is - propagated (re-thrown in the task that called "wait"). - - * "RawFD": Wait for changes on a file descriptor (see *poll_fd* - for keyword arguments and return code) - - If no argument is passed, the task blocks for an undefined period. - If the task's state is set to ":waiting", it can only be - restarted by an explicit call to "schedule" or "yieldto". If - the task's state is ":runnable", it might be restarted - unpredictably. - - Often "wait" is called within a "while" loop to ensure a - waited-for condition is met before proceeding. - ``` - """ wait - - @doc doc""" - ```rst - fetch(RemoteRef) - - Wait for and get the value of a remote reference. - ``` - """ fetch - - @doc doc""" - ```rst - remotecall_wait(id, func, args...) - - Perform "wait(remotecall(...))" in one message. - ``` - """ remotecall_wait - - @doc doc""" - ```rst - remotecall_fetch(id, func, args...) - - Perform "fetch(remotecall(...))" in one message. - ``` - """ remotecall_fetch - - @doc doc""" - ```rst - put!(RemoteRef, value) - - Store a value to a remote reference. Implements "shared queue of - length 1" semantics: if a value is already present, blocks until - the value is removed with "take!". Returns its first argument. - ``` - """ put! - - @doc doc""" - ```rst - take!(RemoteRef) - - Fetch the value of a remote reference, removing it so that the - reference is empty again. - ``` - """ take! - - @doc doc""" - ```rst - isready(r::RemoteRef) - - Determine whether a "RemoteRef" has a value stored to it. Note - that this function can cause race conditions, since by the time you - receive its result it may no longer be true. It is recommended that - this function only be used on a "RemoteRef" that is assigned - once. - - If the argument "RemoteRef" is owned by a different node, this - call will block to wait for the answer. It is recommended to wait - for "r" in a separate task instead, or to use a local - "RemoteRef" as a proxy: - - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block - ``` - """ isready - - @doc doc""" - ```rst - RemoteRef() - - Make an uninitialized remote reference on the local machine. - ``` - """ RemoteRef - - @doc doc""" - ```rst - RemoteRef(n) - - Make an uninitialized remote reference on process "n". - ``` - """ RemoteRef - - @doc doc""" - ```rst - timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - - Waits till "testcb" returns "true" or for "secs`" seconds, - whichever is earlier. "testcb" is polled every "pollint" - seconds. - ``` - """ timedwait - - @doc doc""" - ```rst - @spawn() - - Execute an expression on an automatically-chosen process, returning - a "RemoteRef" to the result. - ``` - """ @spawn - - @doc doc""" - ```rst - @spawnat() - - Accepts two arguments, "p" and an expression, and runs the - expression asynchronously on process "p", returning a - "RemoteRef" to the result. - ``` - """ @spawnat - - @doc doc""" - ```rst - @fetch() - - Equivalent to "fetch(@spawn expr)". - ``` - """ @fetch - - @doc doc""" - ```rst - @fetchfrom() - - Equivalent to "fetch(@spawnat p expr)". - ``` - """ @fetchfrom - - @doc doc""" - ```rst - @async() - - Schedule an expression to run on the local machine, also adding it - to the set of items that the nearest enclosing "@sync" waits for. - ``` - """ @async - - @doc doc""" - ```rst - @sync() - - Wait until all dynamically-enclosed uses of "@async", "@spawn", - "@spawnat" and "@parallel" are complete. - ``` - """ @sync - - @doc doc""" - ```rst - @parallel() - - A parallel for loop of the form - - @parallel [reducer] for var = range - body - end - - The specified range is partitioned and locally executed across all - workers. In case an optional reducer function is specified, - @parallel performs local reductions on each worker with a final - reduction on the calling process. - - Note that without a reducer function, @parallel executes - asynchronously, i.e. it spawns independent tasks on all available - workers and returns immediately without waiting for completion. To - wait for completion, prefix the call with "@sync", like - - @sync @parallel for var = range - body - end - ``` - """ @parallel - - @doc doc""" - ```rst - SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - - Construct a SharedArray of a bitstype "T" and size "dims" - across the processes specified by "pids" - all of which have to - be on the same host. - - If "pids" is left unspecified, the shared array will be mapped - across all processes on the current host, including the master. - But, "localindexes" and "indexpids" will only refer to worker - processes. This facilitates work distribution code to use workers - for actual computation with the master process acting as a driver. - - If an "init" function of the type "initfn(S::SharedArray)" is - specified, it is called on all the participating workers. - ``` - """ SharedArray - - @doc doc""" - ```rst - procs(S::SharedArray) - - Get the vector of processes that have mapped the shared array - ``` - """ procs - - @doc doc""" - ```rst - sdata(S::SharedArray) - - Returns the actual "Array" object backing "S" - ``` - """ sdata - - @doc doc""" - ```rst - indexpids(S::SharedArray) - - Returns the index of the current worker into the "pids" vector, - i.e., the list of workers mapping the SharedArray - ``` - """ indexpids - - @doc doc""" - ```rst - launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - - Implemented by cluster managers. For every Julia worker launched by - this function, it should append a "WorkerConfig" entry to - "launched" and notify "launch_ntfy". The function MUST exit - once all workers, requested by "manager" have been launched. - "params" is a dictionary of all keyword arguments "addprocs" - was called with. - ``` - """ launch - - @doc doc""" - ```rst - manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - - Implemented by cluster managers. It is called on the master - process, during a worker's lifetime, with appropriate "op" - values: - - * with ":register"/":deregister" when a worker is added / - removed from the Julia worker pool. - - * with ":interrupt" when "interrupt(workers)" is called. - The "ClusterManager" should signal the appropriate worker - with an interrupt signal. - - * with ":finalize" for cleanup purposes. - ``` - """ manage - - @doc doc""" - ```rst - kill(manager::FooManager, pid::Int, config::WorkerConfig) - - Implemented by cluster managers. It is called on the master - process, by "rmprocs". It should cause the remote worker - specified by "pid" to exit. - "Base.kill(manager::ClusterManager.....)" executes a remote - "exit()" on "pid" - ``` - """ kill - - @doc doc""" - ```rst - init_worker(manager::FooManager) - - Called by cluster managers implementing custom transports. It - initializes a newly launched process as a worker. Command line - argument "--worker" has the effect of initializing a process as a - worker using TCP/IP sockets for transport. - ``` - """ init_worker - - @doc doc""" - ```rst - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id "pid", specified - by "config" and return a pair of "AsyncStream" objects. - Messages from "pid" to current process will be read off - "instrm", while messages to be sent to "pid" will be written to - "outstrm". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - "Base.connect(manager::ClusterManager.....)" sets up TCP/IP - socket connections in-between workers. - ``` - """ connect - - @doc doc""" - ```rst - Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) - - Called by cluster managers using custom transports. It should be - called when the custom transport implementation receives the first - message from a remote worker. The custom transport must manage a - logical connection to the remote worker and provide two AsyncStream - objects, one for incoming messages and the other for messages - addressed to the remote worker. - ``` - """ Base - - @doc doc""" - ```rst - dir() -> AbstractString - - Returns the absolute path of the package directory. This defaults - to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION - .minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell - syntax). If the "JULIA_PKGDIR" environment variable is set, then - that path is used in the returned value as "joinpath(ENV["JULIA_ - PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If - "JULIA_PKGDIR" is a relative path, it is interpreted relative to - whatever the current working directory is. - ``` - """ Base.Pkg.dir - - @doc doc""" - ```rst - dir(names...) -> AbstractString - - Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, "Pkg.dir(pkg)" returns the path to - the package "pkg". - ``` - """ Base.Pkg.dir - - @doc doc""" - ```rst - init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - - Initialize "Pkg.dir()" as a package directory. This will be done - automatically when the "JULIA_PKGDIR" is not set and - "Pkg.dir()" uses its default value. As part of this process, - clones a local METADATA git repository from the site and branch - specified by its arguments, which are typically not provided. - Explicit (non-default) arguments can be used to support a custom - METADATA setup. - ``` - """ Base.Pkg.init - - @doc doc""" - ```rst - resolve() - - Determines an optimal, consistent set of package versions to - install or upgrade to. The optimal set of package versions is based - on the contents of "Pkg.dir("REQUIRE")" and the state of - installed packages in "Pkg.dir()", Packages that are no longer - required are moved into "Pkg.dir(".trash")". - ``` - """ Base.Pkg.resolve - - @doc doc""" - ```rst - edit() - - Opens "Pkg.dir("REQUIRE")" in the editor specified by the - "VISUAL" or "EDITOR" environment variables; when the editor - command returns, it runs "Pkg.resolve()" to determine and install - a new optimal set of installed package versions. - ``` - """ Base.Pkg.edit - - @doc doc""" - ```rst - add(pkg, vers...) - - Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and - call "Pkg.resolve()". If "vers" are given, they must be - "VersionNumber" objects and they specify acceptable version - intervals for "pkg". - ``` - """ Base.Pkg.add - - @doc doc""" - ```rst - rm(pkg) - - Remove all requirement entries for "pkg" from - "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". - ``` - """ Base.Pkg.rm - - @doc doc""" - ```rst - clone(url[, pkg]) - - Clone a package directly from the git URL "url". The package does - not need to be a registered in "Pkg.dir("METADATA")". The - package repo is cloned by the name "pkg" if provided; if not - provided, "pkg" is determined automatically from "url". - ``` - """ Base.Pkg.clone - - @doc doc""" - ```rst - clone(pkg) - - If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone - it from that URL on the default branch. The package does not need - to have any registered versions. - ``` - """ Base.Pkg.clone - - @doc doc""" - ```rst - available() -> Vector{ASCIIString} - - Returns the names of available packages. - ``` - """ Base.Pkg.available - - @doc doc""" - ```rst - available(pkg) -> Vector{VersionNumber} - - Returns the version numbers available for package "pkg". - ``` - """ Base.Pkg.available - - @doc doc""" - ```rst - installed() -> Dict{ASCIIString,VersionNumber} - - Returns a dictionary mapping installed package names to the - installed version number of each package. - ``` - """ Base.Pkg.installed - - @doc doc""" - ```rst - installed(pkg) -> Void | VersionNumber - - If "pkg" is installed, return the installed version number, - otherwise return "nothing". - ``` - """ Base.Pkg.installed - - @doc doc""" - ```rst - status() - - Prints out a summary of what packages are installed and what - version and state they're in. - ``` - """ Base.Pkg.status - - @doc doc""" - ```rst - update() - - Update package the metadata repo – kept in - "Pkg.dir("METADATA")" – then update any fixed packages that can - safely be pulled from their origin; then call "Pkg.resolve()" to - determine a new optimal set of packages versions. - ``` - """ Base.Pkg.update - - @doc doc""" - ```rst - checkout(pkg[, branch="master"]) - - Checkout the "Pkg.dir(pkg)" repo to the branch "branch". - Defaults to checking out the "master" branch. To go back to using - the newest compatible released version, use "Pkg.free(pkg)" - ``` - """ Base.Pkg.checkout - - @doc doc""" - ```rst - pin(pkg) - - Pin "pkg" at the current version. To go back to using the newest - compatible released version, use "Pkg.free(pkg)" - ``` - """ Base.Pkg.pin - - @doc doc""" - ```rst - pin(pkg, version) - - Pin "pkg" at registered version "version". - ``` - """ Base.Pkg.pin - - @doc doc""" - ```rst - free(pkg) - - Free the package "pkg" to be managed by the package manager - again. It calls "Pkg.resolve()" to determine optimal package - versions after. This is an inverse for both "Pkg.checkout" and - "Pkg.pin". - - You can also supply an iterable collection of package names, e.g., - "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at - once. - ``` - """ Base.Pkg.free - - @doc doc""" - ```rst - build() - - Run the build scripts for all installed packages in depth-first - recursive order. - ``` - """ Base.Pkg.build - - @doc doc""" - ```rst - build(pkgs...) - - Run the build script in "deps/build.jl" for each package in - "pkgs" and all of their dependencies in depth-first recursive - order. This is called automatically by "Pkg.resolve()" on all - installed or updated packages. - ``` - """ Base.Pkg.build - - @doc doc""" - ```rst - generate(pkg, license) - - Generate a new package named "pkg" with one of these license - keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make - a package with a different license, you can edit it afterwards. - Generate creates a git repo at "Pkg.dir(pkg)" for the package and - inside it "LICENSE.md", "README.md", the julia entrypoint - "\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". - ``` - """ Base.Pkg.generate - - @doc doc""" - ```rst - register(pkg[, url]) - - Register "pkg" at the git URL "url", defaulting to the - configured origin URL of the git repo "Pkg.dir(pkg)". - ``` - """ Base.Pkg.register - - @doc doc""" - ```rst - tag(pkg[, ver[, commit]]) - - Tag "commit" as version "ver" of package "pkg" and create a - version entry in "METADATA". If not provided, "commit" defaults - to the current commit of the "pkg" repo. If "ver" is one of the - symbols ":patch", ":minor", ":major" the next patch, minor or - major version is used. If "ver" is not provided, it defaults to - ":patch". - ``` - """ Base.Pkg.tag - - @doc doc""" - ```rst - publish() - - For each new package version tagged in "METADATA" not already - published, make sure that the tagged package commits have been - pushed to the repo at the registered URL for the package and if - they all have, open a pull request to "METADATA". - ``` - """ Base.Pkg.publish - - @doc doc""" - ```rst - test() - - Run the tests for all installed packages ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its "test/runtests.jl" file - and test dependencies are specified in "test/REQUIRE". - ``` - """ Base.Pkg.test - - @doc doc""" - ```rst - test(pkgs...) - - Run the tests for each package in "pkgs" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its "test/runtests.jl" file - and test dependencies are specified in "test/REQUIRE". - ``` - """ Base.Pkg.test - - @doc doc""" - ```rst - @profile() - - "@profile " runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. - ``` - """ @profile - - @doc doc""" - ```rst - clear() - - Clear any existing backtraces from the internal buffer. - ``` - """ Base.Profile.clear - - @doc doc""" - ```rst - print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) - - Prints profiling results to "io" (by default, "STDOUT"). If you - do not supply a "data" vector, the internal buffer of accumulated - backtraces will be used. "format" can be ":tree" or ":flat". - If "C==true", backtraces from C and Fortran code are shown. - "combine==true" merges instruction pointers that correspond to - the same line of code. "cols" controls the width of the display. - ``` - """ Base.Profile.print - - @doc doc""" - ```rst - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - - Prints profiling results to "io". This variant is used to examine - results exported by a previous call to "retrieve()". Supply the - vector "data" of backtraces and a dictionary "lidict" of line - information. - ``` - """ Base.Profile.print - - @doc doc""" - ```rst - init(; n::Integer, delay::Float64) - - Configure the "delay" between backtraces (measured in seconds), - and the number "n" of instruction pointers that may be stored. - Each instruction pointer corresponds to a single line of code; - backtraces generally consist of a long list of instruction - pointers. Default settings can be obtained by calling this function - with no arguments, and each can be set independently using keywords - or in the order "(n, delay)". - ``` - """ Base.Profile.init - - @doc doc""" - ```rst - fetch() -> data - - Returns a reference to the internal buffer of backtraces. Note that - subsequent operations, like "clear()", can affect "data" unless - you first make a copy. Note that the values in "data" have - meaning only on this machine in the current session, because it - depends on the exact memory addresses used in JIT-compiling. This - function is primarily for internal use; "retrieve()" may be a - better choice for most users. - ``` - """ Base.Profile.fetch - - @doc doc""" - ```rst - retrieve() -> data, lidict - - "Exports" profiling results in a portable format, returning the - set of all backtraces ("data") and a dictionary that maps the - (session-specific) instruction pointers in "data" to "LineInfo" - values that store the file name, function name, and line number. - This function allows you to save profiling results for future - analysis. - ``` - """ Base.Profile.retrieve - - @doc doc""" - ```rst - callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - - Given a previous profiling run, determine who called a particular - function. Supplying the filename (and optionally, range of line - numbers over which the function is defined) allows you to - disambiguate an overloaded method. The returned value is a vector - containing a count of the number of calls and line information - about the caller. One can optionally supply backtrace data - obtained from "retrieve()"; otherwise, the current internal - profile buffer is used. - ``` - """ Base.Profile.callers - - @doc doc""" - ```rst - clear_malloc_data() - - Clears any stored memory allocation data when running julia with " - --track-allocation". Execute the command(s) you want to test (to - force JIT-compilation), then call "clear_malloc_data()". Then - execute your command(s) again, quit Julia, and examine the - resulting "*.mem" files. - ``` - """ Base.Profile.clear_malloc_data - - @doc doc""" - ```rst - sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the vector "v" in place. "QuickSort" is used by default - for numeric arrays while "MergeSort" is used for other arrays. - You can specify an algorithm to use via the "alg" keyword (see - Sorting Algorithms for available algorithms). The "by" keyword - lets you provide a function that will be applied to each element - before comparison; the "lt" keyword allows providing a custom - "less than" function; use "rev=true" to reverse the sorting - order. These options are independent and can be used together in - all possible combinations: if both "by" and "lt" are specified, - the "lt" function is applied to the result of the "by" - function; "rev=true" reverses whatever ordering specified via the - "by" and "lt" keywords. - ``` - """ sort! - - @doc doc""" - ```rst - sort(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Variant of "sort!" that returns a sorted copy of "v" leaving - "v" itself unmodified. - ``` - """ sort - - @doc doc""" - ```rst - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort a multidimensional array "A" along the given dimension. - ``` - """ sort - - @doc doc""" - ```rst - sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Return a permutation vector of indices of "v" that puts it in - sorted order. Specify "alg" to choose a particular sorting - algorithm (see Sorting Algorithms). "MergeSort" is used by - default, and since it is stable, the resulting permutation will be - the lexicographically first one that puts the input array into - sorted order – i.e. indices of equal elements appear in ascending - order. If you choose a non-stable sorting algorithm such as - "QuickSort", a different permutation that puts the array into - order may be returned. The order is specified using the same - keywords as "sort!". - - See also "sortperm!()" - ``` - """ sortperm - - @doc doc""" - ```rst - sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - - Like "sortperm", but accepts a preallocated index vector "ix". - If "initialized" is "false" (the default), ix is initialized to - contain the values "1:length(v)". - - See also "sortperm()" - ``` - """ sortperm! - - @doc doc""" - ```rst - sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the rows of matrix "A" lexicographically. - ``` - """ sortrows - - @doc doc""" - ```rst - sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the columns of matrix "A" lexicographically. - ``` - """ sortcols - - @doc doc""" - ```rst - issorted(v, [by=,] [lt=,] [rev=false]) - - Test whether a vector is in sorted order. The "by", "lt" and - "rev" keywords modify what order is considered to be sorted just - as they do for "sort". - ``` - """ issorted - - @doc doc""" - ```rst - searchsorted(a, x, [by=,] [lt=,] [rev=false]) - - Returns the range of indices of "a" which compare as equal to - "x" according to the order specified by the "by", "lt" and - "rev" keywords, assuming that "a" is already sorted in that - order. Returns an empty range located at the insertion point if - "a" does not contain values equal to "x". - ``` - """ searchsorted - - @doc doc""" - ```rst - searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - - Returns the index of the first value in "a" greater than or equal - to "x", according to the specified order. Returns "length(a)+1" - if "x" is greater than all values in "a". - ``` - """ searchsortedfirst - - @doc doc""" - ```rst - searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - - Returns the index of the last value in "a" less than or equal to - "x", according to the specified order. Returns "0" if "x" is - less than all values in "a". - ``` - """ searchsortedlast - - @doc doc""" - ```rst - select!(v, k, [by=,] [lt=,] [rev=false]) - - Partially sort the vector "v" in place, according to the order - specified by "by", "lt" and "rev" so that the value at index - "k" (or range of adjacent values if "k" is a range) occurs at - the position where it would appear if the array were fully sorted - via a non-stable algorithm. If "k" is a single index, that value - is returned; if "k" is a range, an array of values at those - indices is returned. Note that "select!" does not fully sort the - input array. - ``` - """ select! - - @doc doc""" - ```rst - select(v, k, [by=,] [lt=,] [rev=false]) - - Variant of "select!" which copies "v" before partially sorting - it, thereby returning the same thing as "select!" but leaving - "v" unmodified. - ``` - """ select - - @doc doc""" - ```rst - length(s) - - The number of characters in string "s". - ``` - """ length - - @doc doc""" - ```rst - sizeof(s::AbstractString) - - The number of bytes in string "s". - ``` - """ sizeof - - @doc doc""" - ```rst - *(s, t) - - Concatenate strings. The "*" operator is an alias to this - function. - - julia> "Hello " * "world" - "Hello world" - ``` - """ Base.(:(*)) - - @doc doc""" - ```rst - ^(s, n) - - Repeat "n" times the string "s". The "^" operator is an alias - to this function. - - julia> "Test "^3 - "Test Test Test " - ``` - """ Base.(:(^)) - - @doc doc""" - ```rst - string(xs...) - - Create a string from any values using the "print" function. - ``` - """ string - - @doc doc""" - ```rst - repr(x) - - Create a string from any value using the "showall" function. - ``` - """ repr - - @doc doc""" - ```rst - bytestring(::Ptr{UInt8}[, length]) - - Create a string from the address of a C (0-terminated) string - encoded in ASCII or UTF-8. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. - ``` - """ bytestring - - @doc doc""" - ```rst - bytestring(s) - - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. - ``` - """ bytestring - - @doc doc""" - ```rst - ascii(::Array{UInt8, 1}) - - Create an ASCII string from a byte array. - ``` - """ ascii - - @doc doc""" - ```rst - ascii(s) - - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). - ``` - """ ascii - - @doc doc""" - ```rst - ascii(::Ptr{UInt8}[, length]) - - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. - ``` - """ ascii - - @doc doc""" - ```rst - utf8(::Array{UInt8, 1}) - - Create a UTF-8 string from a byte array. - ``` - """ utf8 - - @doc doc""" - ```rst - utf8(::Ptr{UInt8}[, length]) - - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - "length" is specified, the string does not have to be - 0-terminated. - ``` - """ utf8 - - @doc doc""" - ```rst - utf8(s) - - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). - ``` - """ utf8 - - @doc doc""" - ```rst - normalize_string(s, normalform::Symbol) - - Normalize the string "s" according to one of the four "normal - forms" of the Unicode standard: "normalform" can be ":NFC", - ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical - composition) and D (canonical decomposition) convert different - visually identical representations of the same abstract string into - a single canonical form, with form C being more compact. Normal - forms KC and KD additionally canonicalize "compatibility - equivalents": they convert characters that are abstractly similar - but visually distinct into a single canonical choice (e.g. they - expand ligatures into the individual characters), with form KC - being more compact. - - Alternatively, finer control and additional transformations may be - be obtained by calling *normalize_string(s; keywords...)*, where - any number of the following boolean keywords options (which all - default to "false" except for "compose") are specified: - - * "compose=false": do not perform canonical composition - - * "decompose=true": do canonical decomposition instead of - canonical composition ("compose=true" is ignored if present) - - * "compat=true": compatibility equivalents are canonicalized - - * "casefold=true": perform Unicode case folding, e.g. for case- - insensitive string comparison - - * "newline2lf=true", "newline2ls=true", or - "newline2ps=true": convert various newline sequences (LF, CRLF, - CR, NEL) into a linefeed (LF), line-separation (LS), or - paragraph-separation (PS) character, respectively - - * "stripmark=true": strip diacritical marks (e.g. accents) - - * "stripignore=true": strip Unicode's "default ignorable" - characters (e.g. the soft hyphen or the left-to-right marker) - - * "stripcc=true": strip control characters; horizontal tabs and - form feeds are converted to spaces; newlines are also converted - to spaces unless a newline-conversion flag was specified - - * "rejectna=true": throw an error if unassigned code points are - found - - * "stable=true": enforce Unicode Versioning Stability - - For example, NFKC corresponds to the options "compose=true, - compat=true, stable=true". - ``` - """ normalize_string - - @doc doc""" - ```rst - graphemes(s) -> iterator over substrings of s - - Returns an iterator over substrings of "s" that correspond to the - extended graphemes in the string, as defined by Unicode UAX #29. - (Roughly, these are what users would perceive as single characters, - even though they may contain more than one codepoint; for example a - letter combined with an accent mark is a single grapheme.) - ``` - """ graphemes - - @doc doc""" - ```rst - isvalid(value) -> Bool - - Returns true if the given value is valid for its type, which - currently can be one of "Char", "ASCIIString", "UTF8String", - "UTF16String", or "UTF32String" - ``` - """ isvalid - - @doc doc""" - ```rst - isvalid(T, value) -> Bool - - Returns true if the given value is valid for that type. Types - currently can be "Char", "ASCIIString", "UTF8String", - "UTF16String", or "UTF32String" Values for "Char" can be of - type "Char" or "UInt32" Values for "ASCIIString" and - "UTF8String" can be of that type, or "Vector{UInt8}" Values for - "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values - for "UTF32String" can be "UTF32String", "Vector{Char}" or - "Vector{UInt32}" - ``` - """ isvalid - - @doc doc""" - ```rst - is_assigned_char(c) -> Bool - - Returns true if the given char or integer is an assigned Unicode - code point. - ``` - """ is_assigned_char - - @doc doc""" - ```rst - ismatch(r::Regex, s::AbstractString) -> Bool - - Test whether a string contains a match of the given regular - expression. - ``` - """ ismatch - - @doc doc""" - ```rst - match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - - Search for the first match of the regular expression "r" in "s" - and return a RegexMatch object containing the match, or nothing if - the match failed. The matching substring can be retrieved by - accessing "m.match" and the captured sequences can be retrieved - by accessing "m.captures" The optional "idx" argument specifies - an index at which to start the search. - ``` - """ match - - @doc doc""" - ```rst - eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - - Search for all matches of a the regular expression "r" in "s" - and return a iterator over the matches. If overlap is true, the - matching sequences are allowed to overlap indices in the original - string, otherwise they must be from distinct character ranges. - ``` - """ eachmatch - - @doc doc""" - ```rst - matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - - Return a vector of the matching substrings from eachmatch. - ``` - """ matchall - - @doc doc""" - ```rst - lpad(string, n, p) - - Make a string at least "n" columns wide when printed, by padding - on the left with copies of "p". - ``` - """ lpad - - @doc doc""" - ```rst - rpad(string, n, p) - - Make a string at least "n" columns wide when printed, by padding - on the right with copies of "p". - ``` - """ rpad - - @doc doc""" - ```rst - search(string, chars[, start]) - - Search for the first occurrence of the given characters within the - given string. The second argument may be a single character, a - vector or a set of characters, a string, or a regular expression - (though regular expressions are only allowed on contiguous strings, - such as ASCII or UTF-8 strings). The third argument optionally - specifies a starting index. The return value is a range of indexes - where the matching sequence is found, such that "s[search(s,x)] == - x": - - "search(string, "substring")" = "start:end" such that - "string[start:end] == "substring"", or "0:-1" if unmatched. - - "search(string, 'c')" = "index" such that - "string[index] == 'c'", or "0" if unmatched. - ``` - """ search - - @doc doc""" - ```rst - rsearch(string, chars[, start]) - - Similar to "search", but returning the last occurrence of the - given characters within the given string, searching in reverse from - "start". - ``` - """ rsearch - - @doc doc""" - ```rst - searchindex(string, substring[, start]) - - Similar to "search", but return only the start index at which the - substring is found, or 0 if it is not. - ``` - """ searchindex - - @doc doc""" - ```rst - rsearchindex(string, substring[, start]) - - Similar to "rsearch", but return only the start index at which - the substring is found, or 0 if it is not. - ``` - """ rsearchindex - - @doc doc""" - ```rst - contains(haystack, needle) - - Determine whether the second argument is a substring of the first. - ``` - """ contains - - @doc doc""" - ```rst - replace(string, pat, r[, n]) - - Search for the given pattern "pat", and replace each occurrence - with "r". If "n" is provided, replace at most "n" - occurrences. As with search, the second argument may be a single - character, a vector or a set of characters, a string, or a regular - expression. If "r" is a function, each occurrence is replaced - with "r(s)" where "s" is the matched substring. - ``` - """ replace - - @doc doc""" - ```rst - split(string, [chars]; limit=0, keep=true) - - Return an array of substrings by splitting the given string on - occurrences of the given character delimiters, which may be - specified in any of the formats allowed by "search"'s second - argument (i.e. a single character, collection of characters, - string, or regular expression). If "chars" is omitted, it - defaults to the set of all space characters, and "keep" is taken - to be false. The two keyword arguments are optional: they are are a - maximum size for the result and a flag determining whether empty - fields should be kept in the result. - ``` - """ split - - @doc doc""" - ```rst - rsplit(string, [chars]; limit=0, keep=true) - - Similar to "split", but starting from the end of the string. - ``` - """ rsplit - - @doc doc""" - ```rst - strip(string[, chars]) - - Return "string" with any leading and trailing whitespace removed. - If "chars" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. - ``` - """ strip - - @doc doc""" - ```rst - lstrip(string[, chars]) - - Return "string" with any leading whitespace removed. If "chars" - (a character, or vector or set of characters) is provided, instead - remove characters contained in it. - ``` - """ lstrip - - @doc doc""" - ```rst - rstrip(string[, chars]) - - Return "string" with any trailing whitespace removed. If - "chars" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. - ``` - """ rstrip - - @doc doc""" - ```rst - startswith(string, prefix | chars) - - Returns "true" if "string" starts with "prefix". If the - second argument is a vector or set of characters, tests whether the - first character of "string" belongs to that set. - ``` - """ startswith - - @doc doc""" - ```rst - endswith(string, suffix | chars) - - Returns "true" if "string" ends with "suffix". If the second - argument is a vector or set of characters, tests whether the last - character of "string" belongs to that set. - ``` - """ endswith - - @doc doc""" - ```rst - uppercase(string) - - Returns "string" with all characters converted to uppercase. - ``` - """ uppercase - - @doc doc""" - ```rst - lowercase(string) - - Returns "string" with all characters converted to lowercase. - ``` - """ lowercase - - @doc doc""" - ```rst - ucfirst(string) - - Returns "string" with the first character converted to uppercase. - ``` - """ ucfirst - - @doc doc""" - ```rst - lcfirst(string) - - Returns "string" with the first character converted to lowercase. - ``` - """ lcfirst - - @doc doc""" - ```rst - join(strings, delim[, last]) - - Join an array of "strings" into a single string, inserting the - given delimiter between adjacent strings. If "last" is given, it - will be used instead of "delim" between the last two strings. For - example, "join(["apples", "bananas", "pineapples"], ", ", - " and ") == "apples, bananas and pineapples"". - - "strings" can be any iterable over elements "x" which are - convertible to strings via "print(io::IOBuffer, x)". - ``` - """ join - - @doc doc""" - ```rst - chop(string) - - Remove the last character from a string - ``` - """ chop - - @doc doc""" - ```rst - chomp(string) - - Remove a trailing newline from a string - ``` - """ chomp - - @doc doc""" - ```rst - ind2chr(string, i) - - Convert a byte index to a character index - ``` - """ ind2chr - - @doc doc""" - ```rst - chr2ind(string, i) - - Convert a character index to a byte index - ``` - """ chr2ind - - @doc doc""" - ```rst - isvalid(str, i) - - Tells whether index "i" is valid for the given string - ``` - """ isvalid - - @doc doc""" - ```rst - nextind(str, i) - - Get the next valid string index after "i". Returns a value - greater than "endof(str)" at or after the end of the string. - ``` - """ nextind - - @doc doc""" - ```rst - prevind(str, i) - - Get the previous valid string index before "i". Returns a value - less than "1" at the beginning of the string. - ``` - """ prevind - - @doc doc""" - ```rst - randstring([rng], len=8) - - Create a random ASCII string of length "len", consisting of - upper- and lower-case letters and the digits 0-9. The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. - ``` - """ randstring - - @doc doc""" - ```rst - charwidth(c) - - Gives the number of columns needed to print a character. - ``` - """ charwidth - - @doc doc""" - ```rst - strwidth(s) - - Gives the number of columns needed to print a string. - ``` - """ strwidth - - @doc doc""" - ```rst - isalnum(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is alphanumeric, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter or - Number, i.e. a character whose category code begins with 'L' or - 'N'. - ``` - """ isalnum - - @doc doc""" - ```rst - isalpha(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is alphabetic, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter, - i.e. a character whose category code begins with 'L'. - ``` - """ isalpha - - @doc doc""" - ```rst - isascii(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character belongs to the ASCII character set, or - whether this is true for all elements of a string. - ``` - """ isascii - - @doc doc""" - ```rst - iscntrl(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a control character, or whether this - is true for all elements of a string. Control characters are the - non-printing characters of the Latin-1 subset of Unicode. - ``` - """ iscntrl - - @doc doc""" - ```rst - isdigit(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a numeric digit (0-9), or whether this - is true for all elements of a string. - ``` - """ isdigit - - @doc doc""" - ```rst - isgraph(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is printable, and not a space, or whether - this is true for all elements of a string. Any character that - would cause a printer to use ink should be classified with - isgraph(c)==true. - ``` - """ isgraph - - @doc doc""" - ```rst - islower(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a lowercase letter, or whether this is - true for all elements of a string. A character is classified as - lowercase if it belongs to Unicode category Ll, Letter: Lowercase. - ``` - """ islower - - @doc doc""" - ```rst - isnumber(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is numeric, or whether this is true for - all elements of a string. A character is classified as numeric if - it belongs to the Unicode general category Number, i.e. a character - whose category code begins with 'N'. - ``` - """ isnumber - - @doc doc""" - ```rst - isprint(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is printable, including spaces, but not a - control character. For strings, tests whether this is true for all - elements of the string. - ``` - """ isprint - - @doc doc""" - ```rst - ispunct(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character belongs to the Unicode general category - Punctuation, i.e. a character whose category code begins with 'P'. - For strings, tests whether this is true for all elements of the - string. - ``` - """ ispunct - - @doc doc""" - ```rst - isspace(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is any whitespace character. Includes - ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', - Latin-1 character U+0085, and characters in Unicode category Zs. - For strings, tests whether this is true for all elements of the - string. - ``` - """ isspace - - @doc doc""" - ```rst - isupper(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is an uppercase letter, or whether this - is true for all elements of a string. A character is classified - as uppercase if it belongs to Unicode category Lu, Letter: - Uppercase, or Lt, Letter: Titlecase. - ``` - """ isupper - - @doc doc""" - ```rst - isxdigit(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a valid hexadecimal digit, or whether - this is true for all elements of a string. - ``` - """ isxdigit - - @doc doc""" - ```rst - symbol(x...) -> Symbol - - Create a "Symbol" by concatenating the string representations of - the arguments together. - ``` - """ symbol - - @doc doc""" - ```rst - escape_string(str::AbstractString) -> AbstractString - - General escaping of traditional C and Unicode escape sequences. See - "print_escaped()" for more general escaping. - ``` - """ escape_string - - @doc doc""" - ```rst - unescape_string(s::AbstractString) -> AbstractString - - General unescaping of traditional C and Unicode escape sequences. - Reverse of "escape_string()". See also "print_unescaped()". - ``` - """ unescape_string - - @doc doc""" - ```rst - utf16(s) - - Create a UTF-16 string from a byte array, array of "UInt16", or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) - - Note that the resulting "UTF16String" data is terminated by the - NUL codepoint (16-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf16(s)* conversion function. If you have a "UInt16" array - "A" that is already NUL-terminated valid UTF-16 data, then you - can instead use *UTF16String(A)`* to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. - ``` - """ utf16 - - @doc doc""" - ```rst - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If "length" is - specified, the string does not have to be NUL-terminated. - ``` - """ utf16 - - @doc doc""" - ```rst - utf32(s) - - Create a UTF-32 string from a byte array, array of "Char" or - "UInt32", or any other string type. (Conversions of byte arrays - check for a byte-order marker in the first four bytes, and do not - include it in the resulting string.) - - Note that the resulting "UTF32String" data is terminated by the - NUL codepoint (32-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf32(s)* conversion function. If you have a "Char" or - "UInt32" array "A" that is already NUL-terminated UTF-32 data, - then you can instead use *UTF32String(A)`* to construct the string - without making a copy of the data and treating the NUL as a - terminator rather than as part of the string. - ``` - """ utf32 - - @doc doc""" - ```rst - utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) - - Create a string from the address of a NUL-terminated UTF-32 string. - A copy is made; the pointer can be safely freed. If "length" is - specified, the string does not have to be NUL-terminated. - ``` - """ utf32 - - @doc doc""" - ```rst - wstring(s) - - This is a synonym for either "utf32(s)" or "utf16(s)", - depending on whether "Cwchar_t" is 32 or 16 bits, respectively. - The synonym "WString" for "UTF32String" or "UTF16String" is - also provided. - ``` - """ wstring - - @doc doc""" - ```rst - runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) - - Run the Julia unit tests listed in "tests", which can be either a - string or an array of strings, using "numcores" processors. (not - exported) - ``` - """ runtests - - @doc doc""" - ```rst - @test(ex) - - Test the expression "ex" and calls the current handler to handle - the result. - ``` - """ Base.Test.@test - - @doc doc""" - ```rst - @test_throws(extype, ex) - - Test that the expression "ex" throws an exception of type - "extype" and calls the current handler to handle the result. - ``` - """ Base.Test.@test_throws - - @doc doc""" - ```rst - @test_approx_eq(a, b) - - Test two floating point numbers "a" and "b" for equality taking - in account small numerical errors. - ``` - """ Base.Test.@test_approx_eq - - @doc doc""" - ```rst - @test_approx_eq_eps(a, b, tol) - - Test two floating point numbers "a" and "b" for equality taking - in account a margin of tolerance given by "tol". - ``` - """ Base.Test.@test_approx_eq_eps - - @doc doc""" - ```rst - with_handler(f, handler) - - Run the function "f" using the "handler" as the handler. - ``` - """ Base.Test.with_handler From a392a04b874fd2d4c24353ef1628f5c45f9190a2 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 17:33:02 -0400 Subject: [PATCH 08/27] remove rst special casing --- doc/genstdlib.jl | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl index 73e9a824e3b52..854054056d3b8 100644 --- a/doc/genstdlib.jl +++ b/doc/genstdlib.jl @@ -2,13 +2,6 @@ using .Markdown cd(dirname(@__FILE__)) -isrst(md) = - length(md.content) == 1 && - isa(md.content[1], Markdown.Code) && - md.content[1].language == "rst" - -rst(md) = isrst(md) ? join(split(md.content[1].code, "\n")[3:end], "\n") : Markdown.rst(md) - isop(func) = ismatch(r"[^\w@!.]|^!$", func) ident(mod, x) = "$mod.$(isop(x) ? "(:($x))" : x)" @@ -42,7 +35,7 @@ function translate(file) doccing = true println(io, l) println(io) - println(io, rst(getdoc(mod, func))) + println(io, Markdown.rst(getdoc(mod, func))) println(io) elseif doccing && (startswith(l, " ") || ismatch(r"^\s*$", l)) else @@ -53,7 +46,7 @@ function translate(file) end end -println("\nConveting stdlib/\n") +println("\nConverting stdlib/\n") for file in readdir("stdlib") translate("stdlib/$file") From 70a360adb672729283be147749d6cb911bbcdf1d Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 17:38:20 -0400 Subject: [PATCH 09/27] print with a prefix --- doc/genstdlib.jl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl index 854054056d3b8..fb2696bc7a3db 100644 --- a/doc/genstdlib.jl +++ b/doc/genstdlib.jl @@ -35,7 +35,9 @@ function translate(file) doccing = true println(io, l) println(io) - println(io, Markdown.rst(getdoc(mod, func))) + for l in split(Markdown.rst(getdoc(mod, func)), "\n") + println(io, " ", l) + end println(io) elseif doccing && (startswith(l, " ") || ismatch(r"^\s*$", l)) else From 6e865a5ebd1c62d198505235ea0dab7487997dbc Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 17:40:58 -0400 Subject: [PATCH 10/27] first conversion from doc->rst --- doc/stdlib/arrays.rst | 1071 ++++++++++++++---- doc/stdlib/base.rst | 1331 ++++++++++++++++------ doc/stdlib/c.rst | 205 ++-- doc/stdlib/collections.rst | 1327 +++++++++++++--------- doc/stdlib/dates.rst | 478 +++++--- doc/stdlib/file.rst | 391 +++++-- doc/stdlib/io-network.rst | 951 +++++++++++----- doc/stdlib/libc.rst | 102 +- doc/stdlib/libdl.rst | 51 +- doc/stdlib/linalg.rst | 1379 ++++++++++++++--------- doc/stdlib/math.rst | 2181 ++++++++++++++++++++++++++---------- doc/stdlib/numbers.rst | 522 ++++++--- doc/stdlib/parallel.rst | 529 +++++---- doc/stdlib/pkg.rst | 207 +++- doc/stdlib/profile.rst | 102 +- doc/stdlib/sort.rst | 120 +- doc/stdlib/strings.rst | 546 ++++++--- doc/stdlib/test.rst | 43 +- 18 files changed, 7983 insertions(+), 3553 deletions(-) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 33614d302674f..ead0d7d5ec3f1 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -9,57 +9,48 @@ Basic functions .. function:: ndims(A) -> Integer + :: + + ndims(A) -> Integer + Returns the number of dimensions of A + .. function:: size(A, [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 = rand(2,3,4); - - julia> size(A, 2) - 3 - - julia> size(A,3,2) - (4,3) + :: + + size(A[, 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.: + .. function:: iseltype(A,T) + :: + + iseltype(A, T) + Tests whether A or its elements are of type T + .. function:: length(A) -> Integer - Returns the number of elements in A + :: + + length(s) + + The number of characters in string ``s``. + .. function:: 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 (like ``Array``), this is simply the range ``1: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 non-integer indices). - - Example for a sparse 2-d array:: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 + :: + + 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 (like ``Array``), this is simply the range ``1:length(A)``. For other array types, this returns a specialized Cartesian range to efficiently index into the array with indices specified for every dimension. Example for a sparse 2-d array: + If you supply more than one ``AbstractArray`` argument, ``eachindex`` will create an iterable object that is fast for all arguments (a @@ -78,119 +69,240 @@ largest range along each dimension. .. function:: countnz(A) + :: + + countnz(A) + Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use ``nnz``, which returns the number of stored values. + .. function:: conj!(A) + :: + + conj!(A) + Convert an array to its complex conjugate in-place + .. function:: stride(A, k) + :: + + stride(A, k) + Returns the distance in memory (in number of elements) between adjacent elements in dimension k + .. function:: strides(A) + :: + + strides(A) + Returns a tuple of the memory strides in each dimension + .. function:: ind2sub(dims, index) -> subscripts - Returns a tuple of subscripts into an array with dimensions ``dims``, corresponding to the linear index ``index`` - - **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 index ``index`` + .. function:: ind2sub(a, index) -> subscripts + :: + + ind2sub(a, index) -> subscripts + Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` + .. function:: sub2ind(dims, i, j, k...) -> index + :: + + sub2ind(dims, i, j, k...) -> index + The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts + Constructors ------------ .. function:: Array(dims) - ``Array{T}(dims)`` constructs an uninitialized dense array with element type ``T``. - ``dims`` may be a tuple or a series of integer arguments. - The syntax ``Array(T, dims)`` is also available, but deprecated. + :: + + Array(dims) + + element type ``T``. ``dims`` may be a tuple or a series of integer arguments. The syntax ``Array(T, dims)`` is also available, but deprecated. + .. function:: getindex(type[, elements...]) - Construct a 1-d array of the specified type. This is usually called with the syntax ``Type[]``. Element values can be specified using ``Type[a,b,c,...]``. + :: + + 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, ...)``. + .. function:: cell(dims) - Construct an uninitialized cell array (heterogeneous array). ``dims`` can be either a tuple or a series of integer arguments. + :: + + cell(dims) + + Construct an uninitialized cell array (heterogeneous array). + + .. function:: 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. + .. function:: zeros(A) + :: + + zeros(A) + Create an array of all zeros with the same element type and shape as A. + .. function:: 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. + .. function:: ones(A) + :: + + ones(A) + Create an array of all ones with the same element type and shape as A. + .. function:: trues(dims) + :: + + trues(dims) + Create a ``BitArray`` with all values set to true + .. function:: falses(dims) + :: + + falses(dims) + Create a ``BitArray`` with all values set to false + .. function:: fill(x, dims) - Create an array filled with the value ``x``. - For example, ``fill(1.0, (10,10))`` returns a 10x10 array of floats, with each - element initialized to 1.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 evaluating ``Foo()`` once. + :: + + fill(x, dims) + + Create an array filled with the value ``x``. For example, element initialized to 1.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 evaluating ``Foo()`` once. + .. function:: fill!(A, x) - Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. - ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating ``Foo()`` once. + :: + + fill!(A, x) + + Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating + .. function:: reshape(A, dims) + :: + + reshape(A, dims) + Create an array with the same data as the given array, but with different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. + .. function:: similar(array, element_type, dims) - Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ``AbstractArray`` objects which are not real containers (like ranges), this function returns a standard ``Array`` to allow operating on elements. + :: + + similar(array, element_type, dims) + + Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ranges), this function returns a standard ``Array`` to allow operating on elements. + .. function:: reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, ``reinterpret(Float32, UInt32(7))`` interprets the 4 bytes corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. + :: + + reinterpret(type, A) + + Change the type-interpretation of a block of memory. For example, corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. + .. function:: eye(n) - n-by-n identity matrix + :: + + eye(A) + + Constructs an identity matrix of the same dimensions and type as + .. function:: eye(m, n) - m-by-n identity matrix + :: + + eye(A) + + Constructs an identity matrix of the same dimensions and type as + .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. + :: + + eye(A) + + Constructs an identity matrix of the same dimensions and type as + .. function:: linspace(start, stop, n=100) + :: + + linspace(start, stop, n=100) + Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. + .. function:: logspace(start, stop, n=50) - Construct a vector of ``n`` logarithmically spaced numbers from ``10^start`` to ``10^stop``. + :: + + logspace(start, stop, n=50) + + Construct a vector of ``n`` logarithmically spaced numbers from + Mathematical operators and functions ------------------------------------ @@ -199,489 +311,861 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) - Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results ``f(as...)`` for each position. + :: + + broadcast(f, As...) + + Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results + .. function:: broadcast!(f, dest, As...) - Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. - Note that ``dest`` is only used to store the result, and does not supply arguments to - ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform - ``A[:] = broadcast(f, A, B)``. + :: + + broadcast!(f, dest, As...) + + Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. Note that ``dest`` is only used to store the result, and does not supply arguments to ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform + .. function:: bitbroadcast(f, As...) + :: + + bitbroadcast(f, As...) + Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. + .. function:: broadcast_function(f) - Returns a function ``broadcast_f`` such that ``broadcast_function(f)(As...) === broadcast(f, As...)``. Most useful in the form ``const broadcast_f = broadcast_function(f)``. + :: + + broadcast_function(f) + + Returns a function ``broadcast_f`` such that useful in the form ``const broadcast_f = broadcast_function(f)``. + .. function:: broadcast!_function(f) + :: + + broadcast!_function(f) + Like ``broadcast_function``, but for ``broadcast!``. + Indexing, Assignment, and Concatenation --------------------------------------- .. function:: getindex(A, inds...) - Returns a subset of array ``A`` as specified by ``inds``, where each ``ind`` may be an ``Int``, a ``Range``, or a ``Vector``. See the manual section on :ref:`array indexing ` for details. + :: + + 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, ...)``. + .. function:: sub(A, inds...) - Like :func:`getindex`, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling :func:`getindex` or :func:`setindex!` on the returned :obj:`SubArray` computes the indices to the parent array on the fly without checking bounds. + :: + + sub(A, inds...) + + Like ``getindex()``, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling computes the indices to the parent array on the fly without checking bounds. + .. function:: parent(A) - Returns the "parent array" of an array view type (e.g., SubArray), or the array itself if it is not a view + :: + + parent(A) + + Returns the ``parent array`` of an array view type (e.g., SubArray), or the array itself if it is not a view + .. function:: parentindexes(A) + :: + + parentindexes(A) + From an array view ``A``, returns the corresponding indexes in the parent + .. function:: slicedim(A, d, i) + :: + + slicedim(A, d, i) + Return all the data of ``A`` where the index for dimension ``d`` equals ``i``. Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``. + .. function:: slice(A, inds...) - Returns a view of array ``A`` with the given indices like :func:`sub`, but drops all dimensions indexed with scalars. + :: + + slice(A, inds...) + + Returns a view of array ``A`` with the given indices like + .. function:: setindex!(A, X, inds...) - Store values from array ``X`` within some subset of ``A`` as specified by ``inds``. + :: + + 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, ...)``. + .. function:: broadcast_getindex(A, inds...) + :: + + broadcast_getindex(A, inds...) + Broadcasts the ``inds`` arrays to a common size like ``broadcast``, and returns an array of the results ``A[ks...]``, where ``ks`` goes over the positions in the broadcast. + .. function:: broadcast_setindex!(A, X, inds...) + :: + + broadcast_setindex!(A, X, inds...) + Broadcasts the ``X`` and ``inds`` arrays to a common size and stores the value from each position in ``X`` at the indices given by the same positions in ``inds``. + .. function:: cat(dims, A...) - Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If ``dims`` is an iterable containing several dimensions, this allows to construct block diagonal matrices and their higher-dimensional 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 with `matrices[1]`, `matrices[2]`, ... as diagonal blocks and matching zero blocks away from the diagonal. + :: + + cat(dims, A...) + + Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. + .. function:: vcat(A...) + :: + + vcat(A...) + Concatenate along dimension 1 + .. function:: hcat(A...) + :: + + hcat(A...) + Concatenate along dimension 2 + .. function:: 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. - For example, ``[a b;c d e]`` calls ``hvcat((2,3),a,b,c,d,e)``. - - If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. + :: + + 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. For example, If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. + .. function:: flipdim(A, d) + :: + + flipdim(A, d) + Reverse ``A`` in dimension ``d``. + .. function:: circshift(A,shifts) + :: + + circshift(A, shifts) + Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. + .. function:: find(A) - Return a vector of the linear indexes of the non-zeros in ``A`` - (determined by ``A[i]!=0``). A common use of this is to convert a - boolean array to an array of indexes of the ``true`` - elements. + :: + + find(f, A) + + Return a vector of the linear indexes of ``A`` where ``f`` returns true. + .. function:: find(f,A) + :: + + find(f, A) + Return a vector of the linear indexes of ``A`` where ``f`` returns true. + .. function:: findn(A) + :: + + findn(A) + Return a vector of indexes for each dimension giving the locations of the non-zeros in ``A`` (determined by ``A[i]!=0``). + .. function:: findnz(A) - Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and - column indexes of the non-zero values in matrix ``A``, and ``V`` is - a vector of the non-zero values. + :: + + findnz(A) + + Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and column indexes of the non-zero values in matrix ``A``, and ``V`` is a vector of the non-zero values. + .. function:: findfirst(A) - Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + :: + + findfirst(predicate, A) + + Return the index of the first element of ``A`` for which + .. function:: findfirst(A,v) - Return the index of the first element equal to ``v`` in ``A``. + :: + + findfirst(predicate, A) + + Return the index of the first element of ``A`` for which + .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which ``predicate`` returns true. + :: + + findfirst(predicate, A) + + Return the index of the first element of ``A`` for which + .. function:: findlast(A) - Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + :: + + findlast(predicate, A) + + Return the index of the last element of ``A`` for which + .. function:: findlast(A, v) - Return the index of the last element equal to ``v`` in ``A``. + :: + + findlast(predicate, A) + + Return the index of the last element of ``A`` for which + .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which ``predicate`` returns true. + :: + + findlast(predicate, A) + + Return the index of the last element of ``A`` for which + .. function:: findnext(A, i) - Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + :: + + findnext(A, v, i) + + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + .. function:: findnext(predicate, A, i) - Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + :: + + findnext(A, v, i) + + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + :: + + findnext(A, v, i) + + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + .. function:: findprev(A, i) - Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + :: + + findprev(A, v, i) + + Find the previous index <= ``i`` of an element of ``A`` equal to + .. function:: findprev(predicate, A, i) - Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + :: + + findprev(A, v, i) + + Find the previous index <= ``i`` of an element of ``A`` equal to + .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + :: + + findprev(A, v, i) + + Find the previous index <= ``i`` of an element of ``A`` equal to + .. function:: permutedims(A, perm) + :: + + permutedims(A, perm) + Permute the dimensions of array ``A``. ``perm`` is a vector specifying a permutation of length ``ndims(A)``. This is a generalization of transpose for multi-dimensional arrays. Transpose is equivalent to ``permutedims(A, [2,1])``. + .. function:: ipermutedims(A, perm) - Like :func:`permutedims`, except the inverse of the given permutation is applied. + :: + + ipermutedims(A, perm) + + Like ``permutedims()``, except the inverse of the given permutation is applied. + .. function:: permutedims!(dest, src, perm) - Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have ``size(dest) == size(src)[perm]`` and is completely overwritten. No in-place permutation is supported and unexpected results will happen if `src` and `dest` have overlapping memory regions. + :: + + permutedims!(dest, src, perm) + + Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + .. function:: squeeze(A, dims) - Remove the dimensions specified by ``dims`` from array ``A``. Elements of - ``dims`` must be unique and within the range ``1:ndims(A)``. + :: + + squeeze(A, dims) + + Remove the dimensions specified by ``dims`` from array ``A``. Elements of ``dims`` must be unique and within the range + .. function:: vec(Array) -> Vector + :: + + vec(Array) -> Vector + Vectorize an array using column-major convention. + .. function:: promote_shape(s1, s2) - Check two array shapes for compatibility, allowing trailing singleton dimensions, - and return whichever shape has more dimensions. + :: + + promote_shape(s1, s2) + + Check two array shapes for compatibility, allowing trailing singleton dimensions, and return whichever shape has more dimensions. + .. function:: checkbounds(array, indexes...) + :: + + checkbounds(array, indexes...) + Throw an error if the specified indexes are not in bounds for the given array. + .. function:: randsubseq(A, p) -> Vector - Return a vector consisting of a random subsequence of the given array ``A``, - where each element of ``A`` is included (in order) with independent - probability ``p``. (Complexity is linear in ``p*length(A)``, so this - function is efficient even if ``p`` is small and ``A`` is large.) Technically, - this process is known as "Bernoulli sampling" of ``A``. + :: + + randsubseq(A, p) -> Vector + + Return a vector consisting of a random subsequence of the given array ``A``, where each element of ``A`` is included (in order) with independent probability ``p``. (Complexity is linear in small and ``A`` is large.) Technically, this process is known as + .. function:: randsubseq!(S, A, p) - Like ``randsubseq``, but the results are stored in ``S`` (which is - resized as needed). - + :: + + randsubseq!(S, A, p) + + Like ``randsubseq``, but the results are stored in ``S`` (which is resized as needed). + Array functions --------------- .. function:: cumprod(A, [dim]) - Cumulative product along a dimension ``dim`` (defaults to 1). - See also :func:`cumprod!` to use a preallocated output array, - both for performance and to control the precision of the - output (e.g. to avoid overflow). + :: + + cumprod(A[, dim]) + + Cumulative product along a dimension ``dim`` (defaults to 1). See also ``cumprod!()`` to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). + .. function:: cumprod!(B, A, [dim]) - Cumulative product of ``A`` along a dimension, storing the result in ``B``. - The dimension defaults to 1. + :: + + cumprod!(B, A[, dim]) + + Cumulative product of ``A`` along a dimension, storing the result in ``B``. The dimension defaults to 1. + .. function:: cumsum(A, [dim]) - Cumulative sum along a dimension ``dim`` (defaults to 1). - See also :func:`cumsum!` to use a preallocated output array, - both for performance and to control the precision of the - output (e.g. to avoid overflow). + :: + + cumsum(A[, dim]) + + Cumulative sum along a dimension ``dim`` (defaults to 1). See also performance and to control the precision of the output (e.g. to avoid overflow). + .. function:: cumsum!(B, A, [dim]) - Cumulative sum of ``A`` along a dimension, storing the result in ``B``. - The dimension defaults to 1. + :: + + cumsum!(B, A[, dim]) + + Cumulative sum of ``A`` along a dimension, storing the result in + .. function:: cumsum_kbn(A, [dim]) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. - The dimension defaults to 1. + :: + + cumsum_kbn(A[, dim]) + + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1. + .. function:: cummin(A, [dim]) - Cumulative minimum along a dimension. - The dimension defaults to 1. + :: + + cummin(A[, dim]) + + Cumulative minimum along a dimension. The dimension defaults to 1. + .. function:: cummax(A, [dim]) - Cumulative maximum along a dimension. - The dimension defaults to 1. + :: + + cummax(A[, dim]) + + Cumulative maximum along a dimension. The dimension defaults to 1. + .. function:: diff(A, [dim]) + :: + + diff(A[, dim]) + Finite difference operator of matrix or vector. + .. function:: gradient(F, [h]) - Compute differences along vector ``F``, using ``h`` as the spacing between points. - The default spacing is one. + :: + + gradient(F[, h]) + + Compute differences along vector ``F``, using ``h`` as the spacing between points. The default spacing is one. + .. function:: rot180(A) - Rotate matrix ``A`` 180 degrees. + :: + + rot180(A, k) + + Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. + .. function:: rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. - If ``k`` is even, this is equivalent to a ``copy``. + :: + + rot180(A, k) + + Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. + .. function:: rotl90(A) - Rotate matrix ``A`` left 90 degrees. + :: + + rotl90(A, k) + + Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. + .. function:: rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` - is zero or a multiple of four, this is equivalent to a ``copy``. + :: + + rotl90(A, k) + + Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. + .. function:: rotr90(A) - Rotate matrix ``A`` right 90 degrees. + :: + + rotr90(A, k) + + Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. + .. function:: rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` - is zero or a multiple of four, this is equivalent to a ``copy``. + :: + + rotr90(A, k) + + Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. + .. function:: reducedim(f, A, dims[, initial]) - Reduce 2-argument function ``f`` along dimensions of ``A``. ``dims`` is a - vector specifying the dimensions to reduce, and ``initial`` is the initial - value to use in the reductions. For `+`, `*`, `max` and `min` the `initial` - argument is optional. - - The associativity of the reduction is implementation-dependent; if you - need a particular associativity, e.g. left-to-right, you should write - your own loop. See documentation for ``reduce``. + :: + + reducedim(f, A, dims[, initial]) + + Reduce 2-argument function ``f`` along dimensions of ``A``. The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for ``reduce``. + .. function:: mapreducedim(f, op, A, dims[, initial]) - Evaluates to the same as `reducedim(op, map(f, A), dims, f(initial))`, but - is generally faster because the intermediate array is avoided. + :: + + mapreducedim(f, op, A, dims[, initial]) + + Evaluates to the same as *reducedim(op, map(f, A), dims, f(initial))*, but is generally faster because the intermediate array is avoided. + .. function:: mapslices(f, A, dims) - Transform the given dimensions of array ``A`` using function ``f``. ``f`` - is called on each slice of ``A`` of the form ``A[...,:,...,:,...]``. - ``dims`` is an integer vector specifying where the colons go in this - expression. The results are concatenated along the remaining dimensions. - For example, if ``dims`` is ``[1,2]`` and A is 4-dimensional, ``f`` is - called on ``A[:,:,i,j]`` for all ``i`` and ``j``. + :: + + mapslices(f, A, dims) + + Transform the given dimensions of array ``A`` using function ``f``. where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if + .. function:: sum_kbn(A) - Returns the sum of all array elements, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. + :: + + sum_kbn(A) + + Returns the sum of all array elements, using the Kahan-Babuska- Neumaier compensated summation algorithm for additional accuracy. + .. function:: cartesianmap(f, dims) - Given a ``dims`` tuple of integers ``(m, n, ...)``, call ``f`` on all combinations of - integers in the ranges ``1:m``, ``1:n``, etc. - - .. doctest:: - - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 + :: + + cartesianmap(f, dims) + + Given a ``dims`` tuple of integers ``(m, n, ...)``, call ``f`` on all combinations of integers in the ranges ``1:m``, ``1:n``, etc. + Combinatorics ------------- .. function:: nthperm(v, k) - Compute the kth lexicographic permutation of a vector. + :: + + nthperm(p) + + Return the ``k`` that generated permutation ``p``. Note that + .. function:: nthperm(p) - Return the ``k`` that generated permutation ``p``. - Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``. + :: + + nthperm(p) + + Return the ``k`` that generated permutation ``p``. Note that + .. function:: nthperm!(v, k) - In-place version of :func:`nthperm`. + :: + + nthperm!(v, k) + + In-place version of ``nthperm()``. + .. function:: randperm([rng,] n) - Construct a random permutation of length ``n``. The optional ``rng`` argument - specifies a random number generator, see :ref:`Random Numbers `. + :: + + randperm([rng], n) + + Construct a random permutation of length ``n``. The optional Numbers*. + .. function:: invperm(v) + :: + + invperm(v) + Return the inverse permutation of v. + .. function:: isperm(v) -> Bool + :: + + isperm(v) -> Bool + Returns true if v is a valid permutation. + .. function:: permute!(v, p) - Permute vector ``v`` in-place, according to permutation ``p``. No - checking is done to verify that ``p`` is a permutation. - - To return a new permutation, use ``v[p]``. Note that this is - generally faster than ``permute!(v,p)`` for large vectors. + :: + + permute!(v, p) + + Permute vector ``v`` in-place, according to permutation ``p``. No checking is done to verify that ``p`` is a permutation. To return a new permutation, use ``v[p]``. Note that this is generally faster than ``permute!(v,p)`` for large vectors. + .. function:: ipermute!(v, p) + :: + + ipermute!(v, p) + Like permute!, but the inverse of the given permutation is applied. + .. function:: randcycle([rng,] n) - Construct a random cyclic permutation of length ``n``. The optional ``rng`` - argument specifies a random number generator, see :ref:`Random Numbers - `. + :: + + randcycle([rng], n) + + Construct a random cyclic permutation of length ``n``. The optional Numbers*. + .. function:: shuffle([rng,] v) - Return a randomly permuted copy of ``v``. The optional ``rng`` argument - specifies a random number generator, see :ref:`Random Numbers - `. + :: + + shuffle([rng], v) + + Return a randomly permuted copy of ``v``. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. + .. function:: shuffle!([rng,] v) - In-place version of :func:`shuffle`. + :: + + shuffle!([rng], v) + + In-place version of ``shuffle()``. + .. function:: reverse(v [, start=1 [, stop=length(v) ]] ) + :: + + reverse(v[, start=1[, stop=length(v)]]) + Return a copy of ``v`` reversed from start to stop. + .. function:: reverseind(v, i) - Given an index ``i`` in ``reverse(v)``, return the corresponding - index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``. - (This can be nontrivial in the case where ``v`` is a Unicode string.) + :: + + reverseind(v, i) + + Given an index ``i`` in ``reverse(v)``, return the corresponding index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``. string.) + .. function:: reverse!(v [, start=1 [, stop=length(v) ]]) -> v - In-place version of :func:`reverse`. + :: + + reverse!(v[, start=1[, stop=length(v)]]) -> v + + In-place version of ``reverse()``. + .. function:: combinations(array, n) - Generate all combinations of ``n`` elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - ``collect(combinations(array,n))`` to get an array of all combinations. + :: + + combinations(array, n) + + Generate all combinations of ``n`` elements from an indexable object. Because the number of combinations can be very large, this function returns an iterator object. Use combinations. + .. function:: permutations(array) - Generate all permutations of an indexable object. Because the - number of permutations can be very large, this function returns an - iterator object. Use ``collect(permutations(array))`` to get an array - of all permutations. + :: + + permutations(array) + + Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use ``collect(permutations(array))`` to get an array of all permutations. + .. function:: partitions(n) - Generate all integer arrays that sum to ``n``. Because the number of - partitions can be very large, this function returns an iterator - object. Use ``collect(partitions(n))`` to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n))``. + :: + + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. + .. function:: partitions(n, m) - Generate all arrays of ``m`` integers that sum to ``n``. Because - the number of partitions can be very large, this function returns an - iterator object. Use ``collect(partitions(n,m))`` to get an array of - all partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n,m))``. + :: + + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. + .. function:: partitions(array) - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - ``collect(partitions(array))`` to get an array of all partitions. - The number of partitions to generate can be efficiently - computed using ``length(partitions(array))``. + :: + + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. + .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into exactly m - subsets, represented as arrays of arrays. Because the number of - partitions can be very large, this function returns an iterator object. - Use ``collect(partitions(array,m))`` to get an array of all partitions. - The number of partitions into m subsets is equal to the Stirling number - of the second kind and can be efficiently computed using - ``length(partitions(array,m))``. + :: + + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. + BitArrays --------- .. function:: bitpack(A::AbstractArray{T,N}) -> BitArray + :: + + bitpack(A::AbstractArray{T, N}) -> BitArray + Converts a numeric array to a packed boolean array + .. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} + :: + + bitunpack(B::BitArray{N}) -> Array{Bool,N} + Converts a packed boolean array to an array of booleans + .. function:: flipbits!(B::BitArray{N}) -> BitArray{N} - Performs a bitwise not operation on B. See :ref:`~ operator <~>`. + :: + + flipbits!(B::BitArray{N}) -> BitArray{N} + + Performs a bitwise not operation on B. See *~ operator*. + .. function:: rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on ``src`` and put the result into ``dest``. + :: + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on B. + .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + :: + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a left rotation operation on B. + .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} + :: + + rol(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a left rotation operation. + .. function:: ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on ``src`` and put the result into ``dest``. + :: + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on B. + .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + :: + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a right rotation operation on B. + .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} + :: + + ror(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a right rotation operation. + .. _stdlib-sparse: @@ -692,92 +1176,181 @@ Sparse matrices support much of the same set of operations as dense matrices. Th .. function:: sparse(I,J,V,[m,n,combine]) - Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``. The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. + :: + + sparse(A) + + Convert an AbstractMatrix ``A`` into a sparse matrix. + .. function:: sparsevec(I, V, [m, combine]) - Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + :: + + sparsevec(A) + + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + .. function:: sparsevec(D::Dict, [m]) - Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + :: + + sparsevec(A) + + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + .. function:: issparse(S) + :: + + issparse(S) + Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. + .. function:: sparse(A) + :: + + sparse(A) + Convert an AbstractMatrix ``A`` into a sparse matrix. + .. function:: sparsevec(A) + :: + + sparsevec(A) + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + .. function:: full(S) - Convert a sparse matrix ``S`` into a dense matrix. + :: + + full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. + .. function:: nnz(A) + :: + + nnz(A) + Returns the number of stored (filled) elements in a sparse matrix. + .. function:: spzeros(m,n) + :: + + spzeros(m, n) + Create a sparse matrix of size ``m x n``. This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. + .. function:: spones(S) + :: + + spones(S) + Create a sparse matrix with the same structure as that of ``S``, but with every nonzero element having the value ``1.0``. + .. function:: speye(type,m[,n]) + :: + + speye(type, m[, n]) + Create a sparse identity matrix of specified type of size ``m x m``. In case ``n`` is supplied, create a sparse identity matrix of size ``m x n``. + .. function:: spdiagm(B, d[, m, n]) - Construct a sparse diagonal matrix. ``B`` is a tuple of vectors containing the diagonals and ``d`` is a tuple containing the positions of the diagonals. In the case the input contains only one diagonaly, ``B`` can be a vector (instead of a tuple) and ``d`` can be the diagonal position (instead of a tuple), defaulting to 0 (diagonal). Optionally, ``m`` and ``n`` specify the size of the resulting sparse matrix. + :: + + spdiagm(B, d[, m, n]) + + Construct a sparse diagonal matrix. ``B`` is a tuple of vectors containing the diagonals and ``d`` is a tuple containing the positions of the diagonals. In the case the input contains only one diagonaly, ``B`` can be a vector (instead of a tuple) and ``d`` can be the diagonal position (instead of a tuple), defaulting to 0 resulting sparse matrix. + .. function:: sprand([rng,] m,n,p [,rfn]) - Create a random ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by ``p`` (and hence the mean density of nonzeros is also exactly ``p``). Nonzero values are sampled from the distribution specified by ``rfn``. The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers `. + :: + + sprand([rng], m, n, p[, rfn]) + + Create a random ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by by ``rfn``. The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. + .. function:: sprandn(m,n,p) - Create a random ``m`` by ``n`` sparse matrix with the specified (independent) probability ``p`` of any entry being nonzero, where nonzero values are sampled from the normal distribution. + :: + + sprandn(m, n, p) + + Create a random ``m`` by ``n`` sparse matrix with the specified nonzero values are sampled from the normal distribution. + .. function:: sprandbool(m,n,p) - Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being ``true``. + :: + + sprandbool(m, n, p) + + Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being + .. function:: etree(A[, post]) + :: + + etree(A[, post]) + Compute the elimination tree of a symmetric sparse matrix ``A`` from ``triu(A)`` and, optionally, its post-ordering permutation. + .. function:: symperm(A, p) + :: + + symperm(A, p) + Return the symmetric permutation of A, which is ``A[p,p]``. A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. + .. function:: nonzeros(A) - Return a vector of the structural nonzero values in sparse matrix ``A``. This includes zeros that are explicitly stored in the sparse matrix. The returned vector points directly to the internal nonzero storage of ``A``, and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``. + :: + + nonzeros(A) + + Return a vector of the structural nonzero values in sparse matrix matrix. The returned vector points directly to the internal nonzero storage of ``A``, and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``. + .. function:: rowvals(A) + :: + + rowvals(A) + Return a vector of the row indices of ``A``, and any modifications to the returned vector will mutate ``A`` as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See ``nonzeros(A)`` and ``nzrange(A, col)``. + .. function:: nzrange(A, col) - Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with ``nonzeros(A)`` and ``rowvals(A)``, 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 + :: + + nzrange(A, col) + + Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with ``nonzeros(A)`` and matrix + + diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index e7ead054d2064..743019e3bf5ed 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -22,79 +22,165 @@ Getting Around .. function:: exit([code]) + :: + + exit([code]) + Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. + .. function:: quit() - Quit the program indicating that the processes completed successfully. This function calls ``exit(0)`` (see :func:`exit`). + :: + + quit() + + Quit the program indicating that the processes completed successfully. This function calls ``exit(0)`` (see ``exit()``). + .. function:: atexit(f) + :: + + atexit(f) + Register a zero-argument function to be called at exit. + .. function:: atreplinit(f) - Register a one-argument function to be called before the REPL interface is initialized in interactive sessions; this is useful to customize the interface. The argument of ``f`` is the REPL object. - This function should be called from within the ``.juliarc.jl`` initialization file. + :: + + atreplinit(f) + + Register a one-argument function to be called before the REPL interface is initialized in interactive sessions; this is useful to customize the interface. The argument of ``f`` is the REPL object. This function should be called from within the ``.juliarc.jl`` initialization file. + .. function:: isinteractive() -> Bool + :: + + isinteractive() -> Bool + Determine whether Julia is running an interactive session. + .. function:: whos([Module,] [pattern::Regex]) - Print information about exported global variables in a module, optionally restricted - to those matching ``pattern``. + :: + + whos([Module,] [pattern::Regex]) + + Print information about exported global variables in a module, optionally restricted to those matching ``pattern``. + .. function:: edit(file::AbstractString, [line]) - Edit a file optionally providing a line number to edit at. Returns to the julia prompt when you quit the editor. + :: + + edit(function[, types]) + + Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. + .. function:: edit(function, [types]) + :: + + edit(function[, types]) + Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. + .. function:: @edit + :: + + @edit() + Evaluates the arguments to the function call, determines their types, and calls the ``edit`` function on the resulting expression + .. function:: less(file::AbstractString, [line]) - Show a file using the default pager, optionally providing a starting line number. Returns to the julia prompt when you quit the pager. + :: + + less(function[, types]) + + Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. + .. function:: less(function, [types]) + :: + + less(function[, types]) + Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. + .. function:: @less + :: + + @less() + Evaluates the arguments to the function call, determines their types, and calls the ``less`` function on the resulting expression + .. function:: clipboard(x) - Send a printed form of ``x`` to the operating system clipboard ("copy"). + :: + + clipboard() -> AbstractString + + Return a string with the contents of the operating system clipboard + .. function:: clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard ("paste"). + :: + + clipboard() -> AbstractString + + Return a string with the contents of the operating system clipboard + .. function:: require(file::AbstractString...) - Load source files once, in the context of the ``Main`` module, on every active node, searching standard locations for files. ``require`` is considered a top-level operation, so it sets the current ``include`` path but does not use it to search for files (see help for ``include``). This function is typically used to load library code, and is implicitly called by ``using`` to load packages. - - When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``, then tries paths in the global array ``LOAD_PATH``. + :: + + require(file::AbstractString...) + + Load source files once, in the context of the ``Main`` module, on every active node, searching standard locations for files. current ``include`` path but does not use it to search for files library code, and is implicitly called by ``using`` to load packages. When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``, then tries paths in the global array ``LOAD_PATH``. + .. function:: reload(file::AbstractString) + :: + + reload(file::AbstractString) + Like ``require``, except forces loading of files regardless of whether they have been loaded before. Typically used when interactively developing libraries. + .. function:: include(path::AbstractString) + :: + + include("file.jl") + Evaluate the contents of a source file in the current context. During including, a task-local include path is set to the directory containing the file. Nested calls to ``include`` will search relative to that path. All paths refer to files on node 1 when running in parallel, and files will be fetched from node 1. This function is typically used to load source interactively, or to combine files in packages that are broken into multiple source files. + .. function:: include_string(code::AbstractString) + :: + + include_string(code::AbstractString) + Like ``include``, except reads code from the given string rather than from a file. Since there is no file path involved, no path processing or fetching from node 1 is done. + .. function:: help(name) @@ -106,55 +192,75 @@ Getting Around .. function:: which(f, types) - Returns the method of ``f`` (a ``Method`` object) that would be called for arguments of the given types. - - If ``types`` is an abstract type, then the method that would be called by ``invoke`` - is returned. + :: + + which(symbol) + + Return the module in which the binding for the variable referenced by ``symbol`` was created. + .. function:: which(symbol) - Return the module in which the binding for the variable referenced - by ``symbol`` was created. + :: + + which(symbol) + + Return the module in which the binding for the variable referenced by ``symbol`` was created. + .. function:: @which - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the ``Method`` object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the ``which`` function. + :: + + @which() + + Applied to a function call, it evaluates the arguments to the specified function call, and returns the ``Method`` object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the ``which`` function. + .. function:: methods(f, [types]) - Returns the method table for ``f``. - - If ``types`` is specified, returns an array of methods whose types match. + :: + + methods(f[, types]) + + Returns the method table for ``f``. If ``types`` is specified, returns an array of methods whose types match. + .. function:: methodswith(typ[, module or function][, showparents]) - Return an array of methods with an argument of type ``typ``. If optional - ``showparents`` is ``true``, also return arguments with a parent type - of ``typ``, excluding type ``Any``. - - The optional second argument restricts the search to a particular module - or function. + :: + + methodswith(typ[, module or function][, showparents]) + + Return an array of methods with an argument of type ``typ``. If optional ``showparents`` is ``true``, also return arguments with a parent type of ``typ``, excluding type ``Any``. The optional second argument restricts the search to a particular module or function. + .. function:: @show + :: + + @show() + Show an expression and result, returning the result + .. function:: versioninfo([verbose::Bool]) - Print information about the version of Julia in use. If the ``verbose`` argument - is true, detailed system information is shown as well. + :: + + versioninfo([verbose::Bool]) + + Print information about the version of Julia in use. If the as well. + .. function:: workspace() - Replace the top-level module (``Main``) with a new one, providing a clean workspace. - The previous ``Main`` module is made available as ``LastMain``. A previously-loaded - package can be accessed using a statement such as ``using LastMain.Package``. - - This function should only be used interactively. + :: + + workspace() + + Replace the top-level module (``Main``) with a new one, providing a clean workspace. The previous ``Main`` module is made available as statement such as ``using LastMain.Package``. This function should only be used interactively. + .. data:: ans @@ -165,296 +271,412 @@ All Objects ----------- .. function:: is(x, y) -> Bool - ===(x,y) -> Bool - ≡(x,y) -> Bool - Determine whether ``x`` and ``y`` are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called ``egal``. + :: + + ===(x, y) + + See the ``is()`` operator + .. function:: isa(x, type) -> Bool + :: + + isa(x, type) -> Bool + Determine whether ``x`` is of the given ``type``. + .. function:: isequal(x, y) - Similar to ``==``, except treats all floating-point ``NaN`` values as equal to each other, - and treats ``-0.0`` as unequal to ``0.0``. - The default implementation of ``isequal`` calls ``==``, so if you have a type that doesn't have these floating-point subtleties then you probably only need to define ``==``. - - ``isequal`` is the comparison function used by hash tables (``Dict``). - ``isequal(x,y)`` must imply that ``hash(x) == hash(y)``. - - This typically means that if you define your own ``==`` function then you must define a corresponding ``hash`` (and vice versa). Collections typically implement ``isequal`` by calling ``isequal`` recursively on - all contents. - - Scalar types generally do not need to implement ``isequal`` separate from ``==``, unless they - represent floating-point numbers amenable to a more efficient implementation - than that provided as a generic fallback (based on ``isnan``, ``signbit``, and ``==``). + :: + + isequal(x, y) + + Similar to ``==``, except treats all floating-point ``NaN`` values as equal to each other, and treats ``-0.0`` as unequal to ``0.0``. The default implementation of ``isequal`` calls ``==``, so if you have a type that doesn't have these floating-point subtleties then you probably only need to define ``==``. hash(y)``. This typically means that if you define your own `==`` function then you must define a corresponding ``hash`` (and vice versa). Collections typically implement ``isequal`` by calling ``isequal`` recursively on all contents. Scalar types generally do not need to implement ``isequal`` separate from ``==``, unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on ``isnan``, ``signbit``, and ``==``). + .. function:: isless(x, y) - Test whether ``x`` is less than ``y``, according to a canonical total order. - Values that are normally unordered, such as ``NaN``, are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``. Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as ``NaN``. + :: + + isless(x, y) + + Test whether ``x`` is less than ``y``, according to a canonical total order. Values that are normally unordered, such as ``NaN``, are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``. Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as + .. function:: ifelse(condition::Bool, x, y) - Return ``x`` if ``condition`` is true, otherwise return ``y``. This - differs from ``?`` or ``if`` in that it is an ordinary function, so - all the arguments are evaluated first. In some cases, using - ``ifelse`` instead of an ``if`` statement can eliminate the branch - in generated code and provide higher performance in tight loops. + :: + + ifelse(condition::Bool, x, y) + + Return ``x`` if ``condition`` is true, otherwise return ``y``. This differs from ``?`` or ``if`` in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using in generated code and provide higher performance in tight loops. + .. function:: lexcmp(x, y) - Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``, respectively. - This function should be defined for lexicographically comparable types, and ``lexless`` will call ``lexcmp`` by default. + :: + + lexcmp(x, y) + + Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than lexicographically comparable types, and ``lexless`` will call + .. function:: lexless(x, y) + :: + + lexless(x, y) + Determine whether ``x`` is lexicographically less than ``y``. + .. function:: typeof(x) + :: + + typeof(x) + Get the concrete type of ``x``. + .. function:: tuple(xs...) + :: + + tuple(xs...) + Construct a tuple of the given objects. + .. function:: ntuple(f::Function, n) + :: + + ntuple(f::Function, n) + Create a tuple of length ``n``, computing each element as ``f(i)``, where ``i`` is the index of the element. + .. function:: object_id(x) + :: + + object_id(x) + Get a unique integer id for ``x``. ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``. + .. function:: hash(x[, h]) - Compute an integer hash code such that ``isequal(x,y)`` implies ``hash(x)==hash(y)``. - The optional second argument ``h`` is a hash code to be mixed with the result. - - New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``) to guarantee the property mentioned above. + :: + + hash(x[, h]) + + Compute an integer hash code such that ``isequal(x,y)`` implies code to be mixed with the result. New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``) to guarantee the property mentioned above. + .. function:: finalizer(x, function) + :: + + finalizer(x, function) + Register a function ``f(x)`` to be called when there are no program-accessible references to ``x``. The behavior of this function is unpredictable if ``x`` is of a bits type. + .. function:: finalize(x) + :: + + finalize(x) + Immediately run finalizers registered for object ``x``. + .. function:: copy(x) + :: + + copy(x) + Create a shallow copy of ``x``: the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. + .. function:: deepcopy(x) - Create a deep copy of ``x``: everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling `deepcopy` on an object should generally have the same effect as serializing and then deserializing it. - - As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. - - While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` (which shouldn't otherwise be used), where ``T`` is the type to be specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``, and the ``dict`` variable should be updated as appropriate before returning. + :: + + deepcopy(x) + + Create a deep copy of ``x``: everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling *deepcopy* on an object should generally have the same effect as serializing and then deserializing it. As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``, and the ``dict`` variable should be updated as appropriate before returning. + .. function:: isdefined([object,] index | symbol) - Tests whether an assignable location is defined. The arguments can be an - array and index, a composite object and field name (as a symbol), or a - module and a symbol. - With a single symbol argument, tests whether a global variable with that - name is defined in ``current_module()``. + :: + + isdefined([object], index | symbol) + + Tests whether an assignable location is defined. The arguments can be an array and index, a composite object and field name (as a symbol), or a module and a symbol. With a single symbol argument, tests whether a global variable with that name is defined in + .. function:: convert(T, x) - Convert ``x`` to a value of type ``T``. - - If ``T`` is an ``Integer`` type, an :exc:`InexactError` will be raised if - ``x`` is not representable by ``T``, for example if ``x`` is not - integer-valued, or is outside the range supported by ``T``. - - .. doctest:: - - julia> convert(Int, 3.0) - 3 - - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 - - If ``T`` is a :obj:`FloatingPoint` or :obj:`Rational` type, then it will return - the closest value to ``x`` representable by ``T``. - - .. doctest:: - - julia> x = 1/3 - 0.3333333333333333 - - julia> convert(Float32, x) - 0.33333334f0 - - julia> convert(Rational{Int32}, x) - 1//3 - - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 + :: + + convert(T, x) + + Convert ``x`` to a value of type ``T``. If ``T`` is an ``Integer`` type, an ``InexactError`` will be raised if ``x`` is not representable by ``T``, for example if ``x`` is not integer-valued, or is outside the range supported by ``T``. If ``T`` is a ``FloatingPoint`` or ``Rational`` type, then it will return the closest value to ``x`` representable by ``T``. + .. function:: promote(xs...) + :: + + promote(xs...) + Convert all arguments to their common promotion type (if any), and return them all (as a tuple). + .. function:: oftype(x, y) + :: + + oftype(x, y) + Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``). + .. function:: widen(type | x) - If the argument is a type, return a "larger" type (for numeric types, this will be - a type with at least as much range and precision as the argument, and usually more). - Otherwise the argument ``x`` is converted to ``widen(typeof(x))``. - - .. doctest:: - - julia> widen(Int32) - Int64 - - .. doctest:: - - julia> widen(1.5f0) - 1.5 + :: + + widen(type | x) + + If the argument is a type, return a ``larger`` type (for numeric types, this will be a type with at least as much range and precision as the argument, and usually more). Otherwise the argument ``x`` is converted to ``widen(typeof(x))``. + .. function:: identity(x) + :: + + identity(x) + The identity function. Returns its argument. + Types ----- .. function:: super(T::DataType) + :: + + super(T::DataType) + Return the supertype of DataType T + .. function:: issubtype(type1, type2) - True if and only if all values of ``type1`` are also of ``type2``. Can also be written using the ``<:`` infix operator as ``type1 <: type2``. + :: + + <:(T1, T2) + + Subtype operator, equivalent to ``issubtype(T1,T2)``. + .. function:: <:(T1, T2) + :: + + <:(T1, T2) + Subtype operator, equivalent to ``issubtype(T1,T2)``. + .. function:: subtypes(T::DataType) + :: + + subtypes(T::DataType) + Return a list of immediate subtypes of DataType T. Note that all currently loaded subtypes are included, including those not visible in the current module. + .. function:: typemin(type) + :: + + typemin(type) + The lowest value representable by the given (real) numeric type. + .. function:: typemax(type) + :: + + typemax(type) + The highest value representable by the given (real) numeric type. + .. function:: realmin(type) + :: + + realmin(type) + The smallest in absolute value non-subnormal value representable by the given floating-point type + .. function:: realmax(type) + :: + + realmax(type) + The highest finite value representable by the given floating-point type + .. function:: maxintfloat(type) - The largest integer losslessly representable by the given floating-point type + :: + + maxintfloat(type) + + The largest integer losslessly representable by the given floating- point type + .. function:: sizeof(type) - Size, in bytes, of the canonical binary representation of the given type, if any. + :: + + sizeof(s::AbstractString) + + The number of bytes in string ``s``. + .. function:: eps([type]) - The distance between 1.0 and the next larger representable floating-point value of ``type``. Only floating-point types are sensible arguments. If ``type`` is omitted, then ``eps(Float64)`` is returned. + :: + + eps(::DateTime) -> Millisecond + + Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + .. function:: eps(x) - The distance between ``x`` and the next larger representable floating-point value of the same type as ``x``. + :: + + eps(::DateTime) -> Millisecond + + Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + .. function:: promote_type(type1, type2) - Determine a type big enough to hold values of each argument type without loss, whenever possible. In some cases, where no type exists to which both types can be promoted losslessly, some loss is tolerated; for example, ``promote_type(Int64,Float64)`` returns ``Float64`` even though strictly, not all ``Int64`` values can be represented exactly as ``Float64`` values. + :: + + promote_type(type1, type2) + + Determine a type big enough to hold values of each argument type without loss, whenever possible. In some cases, where no type exists to which both types can be promoted losslessly, some loss is tolerated; for example, ``promote_type(Int64,Float64)`` returns represented exactly as ``Float64`` values. + .. function:: promote_rule(type1, type2) - Specifies what type should be used by ``promote`` when given values of types - ``type1`` and ``type2``. This function should not be called directly, but - should have definitions added to it for new types as appropriate. + :: + + promote_rule(type1, type2) + + Specifies what type should be used by ``promote`` when given values of types ``type1`` and ``type2``. This function should not be called directly, but should have definitions added to it for new types as appropriate. + .. function:: getfield(value, name::Symbol) - Extract a named field from a value of composite type. The syntax ``a.b`` calls - ``getfield(a, :b)``, and the syntax ``a.(b)`` calls ``getfield(a, b)``. + :: + + getfield(value, name::Symbol) + + Extract a named field from a value of composite type. The syntax + .. function:: setfield!(value, name::Symbol, x) - Assign ``x`` to a named field in ``value`` of composite type. - The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``, and the syntax ``a.(b) = c`` - calls ``setfield!(a, b, c)``. + :: + + setfield!(value, name::Symbol, x) + + Assign ``x`` to a named field in ``value`` of composite type. The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``, and the syntax + .. function:: fieldoffsets(type) - The byte offset of each field of a type relative to the data start. For example, we could use it - in the following manner to summarize information about a struct type: - - .. doctest:: - - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; - - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) + :: + + fieldoffsets(type) + + The byte offset of each field of a type relative to the data start. For example, we could use it in the following manner to summarize information about a struct type: + .. function:: fieldtype(type, name::Symbol | index::Int) + :: + + fieldtype(type, name::Symbol | index::Int) + Determine the declared type of a field (specified by name or index) in a composite type. + .. function:: isimmutable(v) - True if value ``v`` is immutable. See :ref:`man-immutable-composite-types` for a discussion of immutability. - Note that this function works on values, so if you give it a type, it will tell you that a value of ``DataType`` is mutable. + :: + + isimmutable(v) + + True if value ``v`` is immutable. See *Immutable Composite Types* for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of + .. function:: isbits(T) - True if ``T`` is a "plain data" type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as ``UInt8``, ``Float64``, and ``Complex{Float64}``. - - .. doctest:: - - julia> isbits(Complex{Float64}) - true - - julia> isbits(Complex) - false + :: + + isbits(T) + + True if ``T`` is a ``plain data`` type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as ``UInt8``, ``Float64``, and + .. function:: isleaftype(T) - Determine whether ``T`` is a concrete type that can have instances, meaning - its only subtypes are itself and ``None`` (but ``T`` itself is not - ``None``). + :: + + isleaftype(T) + + Determine whether ``T`` is a concrete type that can have instances, meaning its only subtypes are itself and ``None`` (but ``T`` itself is not ``None``). + .. function:: typejoin(T, S) + :: + + typejoin(T, S) + Compute a type that contains both ``T`` and ``S``. + .. function:: typeintersect(T, S) + :: + + typeintersect(T, S) + Compute a type that contains the intersection of ``T`` and ``S``. Usually this will be the smallest such type or one close to it. + .. function:: Val{c} @@ -480,129 +702,195 @@ Types .. function:: instances(T::Type) - Return a collection of all instances of the given type, if applicable. - Mostly used for enumerated types (see ``@enum``). + :: + + instances(T::Type) + + Return a collection of all instances of the given type, if applicable. Mostly used for enumerated types (see ``@enum``). + Generic Functions ----------------- .. function:: method_exists(f, Tuple type) -> Bool - Determine whether the given generic function has a method matching the given :obj:`Tuple` of argument types. - - .. doctest:: - - julia> method_exists(length, Tuple{Array}) - true + :: + + method_exists(f, Tuple type) -> Bool + + Determine whether the given generic function has a method matching the given ``Tuple`` of argument types. + .. function:: applicable(f, args...) -> Bool + :: + + applicable(f, args...) -> Bool + Determine whether the given generic function has a method applicable to the given arguments. - - .. doctest:: - - julia> function f(x, y) - x + y - end; - - julia> applicable(f, 1) - false - - julia> applicable(f, 1, 2) - true + .. function:: invoke(f, (types...), args...) + :: + + invoke(f, (types...), args...) + Invoke a method for the given generic function matching the specified types (as a tuple), on the specified arguments. The arguments must be compatible with the specified types. This allows invoking a method other than the most specific matching method, which is useful when the behavior of a more general definition is explicitly needed (often as part of the implementation of a more specific method of the same function). + .. function:: |>(x, f) + :: + + |>(x, f) + Applies a function to the preceding argument. This allows for easy function chaining. - - .. doctest:: - - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 + .. function:: call(x, args...) - If ``x`` is not a ``Function``, then ``x(args...)`` is equivalent to - ``call(x, args...)``. This means that function-like behavior can be - added to any type by defining new ``call`` methods. + :: + + call(x, args...) + + If ``x`` is not a ``Function``, then ``x(args...)`` is equivalent to ``call(x, args...)``. This means that function-like behavior can be added to any type by defining new ``call`` methods. + Syntax ------ .. function:: eval([m::Module], expr::Expr) - Evaluate an expression in the given module and return the result. - Every module (except those defined with ``baremodule``) has its own 1-argument definition - of ``eval``, which evaluates expressions in that module. + :: + + eval([m::Module], expr::Expr) + + Evaluate an expression in the given module and return the result. Every module (except those defined with ``baremodule``) has its own 1-argument definition of ``eval``, which evaluates expressions in that module. + .. function:: @eval + :: + + @eval() + Evaluate an expression and return the value. + .. function:: evalfile(path::AbstractString) + :: + + evalfile(path::AbstractString) + Load the file using ``include``, evaluate all expressions, and return the value of the last one. + .. function:: esc(e::ANY) - Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the :ref:`man-macros` - section of the Metaprogramming chapter of the manual for more details and examples. + :: + + esc(e::ANY) + + Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the *Macros* section of the Metaprogramming chapter of the manual for more details and examples. + .. function:: gensym([tag]) + :: + + gensym([tag]) + Generates a symbol which will not conflict with other variable names. + .. function:: @gensym - Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym("x"); y = gensym("y")``. + :: + + @gensym() + + Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym(``x``); y = gensym(``y``)``. + .. function:: parse(str, start; greedy=true, raise=true) - Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + :: + + parse(type, str[, base]) + + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. + .. function:: parse(str; raise=true) - Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. - + :: + + parse(type, str[, base]) + + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. + Nullables --------- .. function:: Nullable(x) - Wrap value ``x`` in an object of type ``Nullable``, which indicates whether a value is present. - ``Nullable(x)`` yields a non-empty wrapper, and ``Nullable{T}()`` yields an empty instance - of a wrapper that might contain a value of type ``T``. + :: + + Nullable(x) + + Wrap value ``x`` in an object of type ``Nullable``, which indicates whether a value is present. ``Nullable(x)`` yields a non-empty wrapper, and ``Nullable{T}()`` yields an empty instance of a wrapper that might contain a value of type ``T``. + .. function:: get(x) - Attempt to access the value of the ``Nullable`` object, ``x``. Returns the - value if it is present; otherwise, throws a ``NullException``. + :: + + 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: + .. function:: get(x, y) - Attempt to access the value of the ``Nullable{T}`` object, ``x``. Returns - the value if it is present; otherwise, returns ``convert(T, y)``. + :: + + 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: + .. function:: isnull(x) + :: + + isnull(x) + Is the ``Nullable`` object ``x`` null, i.e. missing a value? - + System ------ .. function:: run(command) - Run a command object, constructed with backticks. Throws an error if anything goes wrong, including the process exiting with a non-zero status. + :: + + run(command) + + Run a command object, constructed with backticks. Throws an error if anything goes wrong, including the process exiting with a non- zero status. + .. function:: spawn(command) - Run a command object asynchronously, returning the resulting ``Process`` object. + :: + + spawn(command) + + Run a command object asynchronously, returning the resulting + .. data:: DevNull @@ -611,36 +899,57 @@ System .. function:: success(command) + :: + + success(command) + Run a command object, constructed with backticks, and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started. + .. function:: process_running(p::Process) + :: + + process_running(p::Process) + Determine whether a process is currently running. + .. function:: process_exited(p::Process) + :: + + process_exited(p::Process) + Determine whether a process has exited. + .. function:: kill(p::Process, signum=SIGTERM) - Send a signal to a process. The default is to terminate the process. + :: + + kill(manager::FooManager, pid::Int, config::WorkerConfig) + + Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. + .. function:: open(command, mode::AbstractString="r", stdio=DevNull) - Start running ``command`` asynchronously, and return a tuple - ``(stream,process)``. If ``mode`` is ``"r"``, then ``stream`` - reads from the process's standard output and ``stdio`` optionally - specifies the process's standard input stream. If ``mode`` is - ``"w"``, then ``stream`` writes to the process's standard input - and ``stdio`` optionally specifies the process's standard output - stream. + :: + + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + .. function:: open(f::Function, command, mode::AbstractString="r", stdio=DevNull) - Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` - on the resulting read or write stream, then closes the stream - and waits for the process to complete. Returns the value returned - by ``f``. + :: + + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + .. function:: Sys.set_process_title(title::AbstractString) @@ -652,121 +961,192 @@ System .. function:: readandwrite(command) - Starts running a command asynchronously, and returns a tuple (stdout,stdin,process) of the output stream and input stream of the process, and the process object itself. + :: + + readandwrite(command) + + Starts running a command asynchronously, and returns a tuple process, and the process object itself. + .. function:: ignorestatus(command) - Mark a command object so that running it will not throw an error if the - result code is non-zero. + :: + + ignorestatus(command) + + Mark a command object so that running it will not throw an error if the result code is non-zero. + .. function:: detach(command) - Mark a command object so that it will be run in a new process group, - allowing it to outlive the julia process, and not have Ctrl-C interrupts - passed to it. + :: + + detach(command) + + Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. + .. function:: setenv(command, env; dir=working_dir) - Set environment variables to use when running the given - command. ``env`` is either a dictionary mapping strings to strings, - an array of strings of the form ``"var=val"``, or zero or more - ``"var"=>val`` pair arguments. In order to modify (rather than - replace) the existing environment, create ``env`` by ``copy(ENV)`` - and then setting ``env["var"]=val`` as desired, or use ``withenv``. - - The ``dir`` keyword argument can be used to specify a working - directory for the command. + :: + + setenv(command, env; dir=working_dir) + + Set environment variables to use when running the given command. of strings of the form ``var=val``, or zero or more replace) the existing environment, create ``env`` by ``copy(ENV)`` and then setting ``env[``var``]=val`` as desired, or use The ``dir`` keyword argument can be used to specify a working directory for the command. + .. function:: withenv(f::Function, kv::Pair...) - Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``"var"=>val`` arguments ``kv``. ``withenv`` is generally used via the ``withenv(kv...) do ... end`` syntax. A value of ``nothing`` can be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. + :: + + withenv(f::Function, kv::Pair...) + + Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``var``=>val`` arguments ``kv``. ``withenv`` is generally used via the be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. + .. function:: pipe(from, to, ...) - Create a pipeline from a data source to a destination. The source and destination can - be commands, I/O streams, strings, or results of other ``pipe`` calls. At least one - argument must be a command. Strings refer to filenames. - When called with more than two arguments, they are chained together from left to right. - For example ``pipe(a,b,c)`` is equivalent to ``pipe(pipe(a,b),c)``. This provides a more - concise way to specify multi-stage pipelines. - - **Examples**: - * ``run(pipe(`ls`, `grep xyz`))`` - * ``run(pipe(`ls`, "out.txt"))`` - * ``run(pipe("out.txt", `grep xyz`))`` + :: + + pipe(command; stdin, stdout, stderr, append=false) + + Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. + .. function:: pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given ``command``. Keyword arguments specify which of - the command's streams should be redirected. ``append`` controls whether file output - appends to the file. - This is a more general version of the 2-argument ``pipe`` function. - ``pipe(from, to)`` is equivalent to ``pipe(from, stdout=to)`` when ``from`` is a - command, and to ``pipe(to, stdin=from)`` when ``from`` is another kind of - data source. - - **Examples**: - * ``run(pipe(`dothings`, stdout="out.txt", stderr="errs.txt"))`` - * ``run(pipe(`update`, stdout="log.txt", append=true))`` + :: + + pipe(command; stdin, stdout, stderr, append=false) + + Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. + .. function:: gethostname() -> AbstractString + :: + + gethostname() -> AbstractString + Get the local machine's host name. + .. function:: getipaddr() -> AbstractString - Get the IP address of the local machine, as a string of the form "x.x.x.x". + :: + + getipaddr() -> AbstractString + + Get the IP address of the local machine, as a string of the form + .. function:: getpid() -> Int32 + :: + + getpid() -> Int32 + Get julia's process ID. + .. function:: time() - Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. + :: + + time(t::TmStruct) + + Converts a ``TmStruct`` struct to a number of seconds since the epoch. + .. function:: time_ns() + :: + + time_ns() + Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. + .. function:: tic() - Set a timer to be read by the next call to :func:`toc` or :func:`toq`. The macro call ``@time expr`` can also be used to time evaluation. + :: + + tic() + + Set a timer to be read by the next call to ``toc()`` or ``toq()``. The macro call ``@time expr`` can also be used to time evaluation. + .. function:: toc() - Print and return the time elapsed since the last :func:`tic`. + :: + + toc() + + Print and return the time elapsed since the last ``tic()``. + .. function:: toq() - Return, but do not print, the time elapsed since the last :func:`tic`. + :: + + toq() + + Return, but do not print, the time elapsed since the last + .. function:: @time + :: + + @time() + A macro to execute an expression, printing the time it took to execute, the number of allocations, and the total number of bytes its execution caused to be allocated, before returning the value of the expression. + .. function:: @timev + :: + + @timev() + This is a verbose version of the ``@time`` macro, it first prints the same information as ``@time``, then any non-zero memory allocation counters, and then returns the value of the expression. + .. function:: @timed + :: + + @timed() + A macro to execute an expression, and return the value of the expression, elapsed time, total bytes allocated, garbage collection time, and an object with various memory allocation counters. + .. function:: @elapsed + :: + + @elapsed() + A macro to evaluate an expression, discarding the resulting value, instead returning the number of seconds it took to execute as a floating-point number. + .. function:: @allocated - A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. - Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, - however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the ``@time`` macros, - which do not try to adjust for the effects of compilation. + :: + + @allocated() + + A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the ``@time`` macros, which do not try to adjust for the effects of compilation. + .. function:: EnvHash() -> EnvHash + :: + + EnvHash() -> EnvHash + A singleton of this type provides a hash table interface to environment variables. + .. data:: ENV @@ -774,54 +1154,96 @@ System .. function:: @unix - Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation - for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + :: + + @unix() + + Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. function:: @osx - Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations - in the Calling C and Fortran Code section of the manual. + :: + + @osx() + + Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. function:: @linux - Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations - in the Calling C and Fortran Code section of the manual. + :: + + @linux() + + Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. function:: @windows - Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations - in the Calling C and Fortran Code section of the manual. - + :: + + @windows() + + Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + Errors ------ .. function:: error(message::AbstractString) + :: + + error(message::AbstractString) + Raise an ``ErrorException`` with the given message + .. function:: throw(e) + :: + + throw(e) + Throw an object as an exception + .. function:: rethrow([e]) - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - ``catch`` block). + :: + + rethrow([e]) + + Throw an object without changing the current exception backtrace. The default argument is the current exception (if called within a + .. function:: backtrace() + :: + + backtrace() + Get a backtrace object for the current program point. + .. function:: catch_backtrace() - Get the backtrace of the current exception, for use within ``catch`` - blocks. + :: + + catch_backtrace() + + Get the backtrace of the current exception, for use within + .. function:: assert(cond) + :: + + assert(cond) + Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. + .. function:: @assert cond [text] @@ -829,243 +1251,496 @@ Errors .. function:: ArgumentError(msg) + :: + + ArgumentError(msg) + The parameters to a function call do not match a valid signature. + .. function:: AssertionError([msg]) + :: + + AssertionError([msg]) + The asserted condition did not evalutate to ``true``. + .. function:: BoundsError([a],[i]) - An indexing operation into an array, ``a``, tried to access an out-of-bounds element, ``i``. + :: + + BoundsError([a][, i]) + + An indexing operation into an array, ``a``, tried to access an out- of-bounds element, ``i``. + .. function:: DimensionMismatch([msg]) + :: + + DimensionMismatch([msg]) + The objects called do not have matching dimensionality. + .. function:: DivideError() + :: + + DivideError() + Integer division was attempted with a denominator value of 0. + .. function:: DomainError() + :: + + DomainError() + The arguments to a function or constructor are outside the valid domain. + .. function:: EOFError() + :: + + EOFError() + No more data was available to read from a file or stream. + .. function:: ErrorException(msg) - Generic error type. The error message, in the `.msg` field, may provide more specific details. + :: + + ErrorException(msg) + + Generic error type. The error message, in the *.msg* field, may provide more specific details. + .. function:: InexactError() + :: + + InexactError() + Type conversion cannot be done exactly. + .. function:: InterruptException() + :: + + InterruptException() + The process was stopped by a terminal interrupt (CTRL+C). + .. function:: KeyError(key) + :: + + KeyError(key) + An indexing operation into an ``Associative`` (``Dict``) or ``Set`` like object tried to access or delete a non-existent element. + .. function:: LoadError(file::AbstractString, line::Int, error) - An error occurred while `including`, `requiring`, or `using` a file. The error specifics should be available in the `.error` field. + :: + + LoadError(file::AbstractString, line::Int, error) + + An error occurred while *including*, *requiring*, or *using* a file. The error specifics should be available in the *.error* field. + .. function:: MethodError(f, args) + :: + + MethodError(f, args) + A method with the required type signature does not exist in the given generic function. + .. function:: NullException() + :: + + NullException() + An attempted access to a ``Nullable`` with no defined value. + .. function:: OutOfMemoryError() + :: + + OutOfMemoryError() + An operation allocated too much memory for either the system or the garbage collector to handle properly. + .. function:: ReadOnlyMemoryError() + :: + + ReadOnlyMemoryError() + An operation tried to write to memory that is read-only. + .. function:: OverflowError() + :: + + OverflowError() + The result of an expression is too large for the specified type and will cause a wraparound. + .. function:: ParseError(msg) - The expression passed to the `parse` function could not be interpreted as a valid Julia expression. + :: + + ParseError(msg) + + The expression passed to the *parse* function could not be interpreted as a valid Julia expression. + .. function:: ProcessExitedException() + :: + + ProcessExitedException() + After a client Julia process has exited, further attempts to reference the dead child will throw this exception. + .. function:: StackOverflowError() + :: + + StackOverflowError() + The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. + .. function:: SystemError(prefix::AbstractString, [errnum::Int32]) + :: + + SystemError(prefix::AbstractString[, errnum::Int32]) + A system call failed with an error code (in the ``errno`` global variable). + .. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) + :: + + TypeError(func::Symbol, context::AbstractString, expected::Type, got) + A type assertion failure, or calling an intrinsic function with an incorrect argument type. + .. function:: UndefRefError() + :: + + UndefRefError() + The item or field is not defined for the given object. + .. function:: UndefVarError(var::Symbol) + :: + + UndefVarError(var::Symbol) + A symbol in the current scope is not defined. + Events ------ .. function:: Timer(callback::Function, delay, repeat=0) - Create a timer to call the given callback function. - The callback is passed one argument, the timer object itself. - The callback will be invoked after the specified initial delay, - and then repeating with the given ``repeat`` interval. - If ``repeat`` is ``0``, the timer is only triggered once. - Times are in seconds. - A timer is stopped and has its resources freed by calling ``close`` on it. + :: + + Timer(delay, repeat=0) + + Create a timer that wakes up tasks waiting for it (by calling + .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling ``wait`` on - the timer object) at a specified interval. + :: + + Timer(delay, repeat=0) + + Create a timer that wakes up tasks waiting for it (by calling + Reflection ---------- .. function:: module_name(m::Module) -> Symbol + :: + + module_name(m::Module) -> Symbol + Get the name of a module as a symbol. + .. function:: module_parent(m::Module) -> Module + :: + + module_parent(m::Module) -> Module + Get a module's enclosing module. ``Main`` is its own parent. + .. function:: current_module() -> Module - Get the *dynamically* current module, which is the module code is currently being - read from. In general, this is not the same as the module containing the call to - this function. + :: + + current_module() -> Module + + Get the *dynamically* current module, which is the module code is currently being read from. In general, this is not the same as the module containing the call to this function. + .. function:: fullname(m::Module) - Get the fully-qualified name of a module as a tuple of symbols. For example, - ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and ``fullname(Main)`` gives ``()``. + :: + + fullname(m::Module) + + Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and + .. function:: names(x::Module[, all=false[, imported=false]]) - Get an array of the names exported by a module, with optionally more module - globals according to the additional parameters. + :: + + names(x::Module[, all=false[, imported=false]]) + + Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. + .. function:: nfields(x::DataType) -> Int + :: + + nfields(x::DataType) -> Int + Get the number of fields of a data type. + .. function:: fieldnames(x::DataType) + :: + + fieldnames(x::DataType) + Get an array of the fields of a data type. + .. function:: isconst([m::Module], s::Symbol) -> Bool - Determine whether a global is declared ``const`` in a given module. - The default module argument is ``current_module()``. + :: + + isconst([m::Module], s::Symbol) -> Bool + + Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``. + .. function:: isgeneric(f::Function) -> Bool + :: + + isgeneric(f::Function) -> Bool + Determine whether a function is generic. + .. function:: function_name(f::Function) -> Symbol + :: + + function_name(f::Function) -> Symbol + Get the name of a generic function as a symbol, or ``:anonymous``. + .. function:: function_module(f::Function, types) -> Module + :: + + function_module(f::Function, types) -> Module + Determine the module containing a given definition of a generic function. + .. function:: functionloc(f::Function, types) + :: + + functionloc(m::Method) + Returns a tuple ``(filename,line)`` giving the location of a method definition. + .. function:: functionloc(m::Method) + :: + + functionloc(m::Method) + Returns a tuple ``(filename,line)`` giving the location of a method definition. + Internals --------- .. function:: gc() + :: + + gc() + Perform garbage collection. This should not generally be used. + .. function:: gc_enable(on::Bool) - Control whether garbage collection is enabled using a boolean argument (true for - enabled, false for disabled). - Returns previous GC state. - Disabling garbage collection should be used only with extreme caution, - as it can cause memory use to grow without bound. + :: + + gc_enable(on::Bool) + + Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Returns previous GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. + .. function:: macroexpand(x) + :: + + macroexpand(x) + Takes the expression x and returns an equivalent expression with all macros removed (expanded). + .. function:: expand(x) + :: + + expand(x) + Takes the expression x and returns an equivalent expression in lowered form + .. function:: code_lowered(f, types) + :: + + code_lowered(f, types) + Returns an array of lowered ASTs for the methods matching the given generic function and type signature. + .. function:: @code_lowered - Evaluates the arguments to the function call, determines their types, and calls :func:`code_lowered` on the resulting expression + :: + + @code_lowered() + + Evaluates the arguments to the function call, determines their types, and calls ``code_lowered()`` on the resulting expression + .. function:: code_typed(f, types; optimize=true) + :: + + code_typed(f, types; optimize=true) + Returns an array of lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The keyword argument ``optimize`` controls whether additional optimizations, such as inlining, are also applied. + .. function:: @code_typed - Evaluates the arguments to the function call, determines their types, and calls :func:`code_typed` on the resulting expression + :: + + @code_typed() + + Evaluates the arguments to the function call, determines their types, and calls ``code_typed()`` on the resulting expression + .. function:: code_warntype(f, types) - Displays lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The ASTs are annotated in such a way as to cause "non-leaf" types to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability. Not all non-leaf types are particularly problematic for performance, so the results need to be used judiciously. See :ref:`man-code-warntype` for more information. + :: + + code_warntype(f, types) + + Displays lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The ASTs are annotated in such a way as to cause ``non-leaf`` types to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability. Not all non-leaf types are particularly problematic for performance, so the results need to be used judiciously. See *@code_warntype* for more information. + .. function:: @code_warntype - Evaluates the arguments to the function call, determines their types, and calls :func:`code_warntype` on the resulting expression + :: + + @code_warntype() + + Evaluates the arguments to the function call, determines their types, and calls ``code_warntype()`` on the resulting expression + .. function:: code_llvm(f, types) - Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to :const:`STDOUT`. - - All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. + :: + + code_llvm(f, types) + + Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to ``STDOUT``. All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. + .. function:: @code_llvm - Evaluates the arguments to the function call, determines their types, and calls :func:`code_llvm` on the resulting expression + :: + + @code_llvm() + + Evaluates the arguments to the function call, determines their types, and calls ``code_llvm()`` on the resulting expression + .. function:: code_native(f, types) + :: + + code_native(f, types) + Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. + .. function:: @code_native - Evaluates the arguments to the function call, determines their types, and calls :func:`code_native` on the resulting expression + :: + + @code_native() + + Evaluates the arguments to the function call, determines their types, and calls ``code_native()`` on the resulting expression + .. function:: precompile(f,args::Tuple{Vararg{Any}}) - Compile the given function ``f`` for the argument tuple (of types) ``args``, but do not execute it. + :: + + precompile(f, args::Tuple{Vararg{Any}}) + + Compile the given function ``f`` for the argument tuple (of types) + + diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index 2d24a41c6bb43..e2c3e2b0019ce 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -6,154 +6,165 @@ .. function:: ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - Call function in C-exported shared library, specified by ``(function name, library)`` tuple, - where each component is an AbstractString or :Symbol. - - Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. - Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. - - Each ``ArgumentValue`` to the ``ccall`` will be converted to the corresponding ``ArgumentType``, - by automatic insertion of calls to ``unsafe_convert(ArgumentType, cconvert(ArgumentType, ArgumentValue))``. - (see also the documentation for each of these functions for further details). - In most cases, this simply results in a call to ``convert(ArgumentType, ArgumentValue)`` + :: + + ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) + + Call function in C-exported shared library, specified by AbstractString or :Symbol. Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. Each ``ArgumentValue`` to the ``ccall`` will be converted to the corresponding ``ArgumentType``, by automatic insertion of calls to ArgumentValue))``. (see also the documentation for each of these functions for further details). In most cases, this simply results in a call to `convert(ArgumentType, ArgumentValue)`` + .. function:: cglobal((symbol, library) [, type=Void]) - Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ``ccall``. Returns a ``Ptr{Type}``, defaulting to ``Ptr{Void}`` if no Type argument is supplied. The values can be read or written by ``unsafe_load`` or ``unsafe_store!``, respectively. + :: + + cglobal((symbol, library)[, type=Void]) + + Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ``ccall``. Returns a supplied. The values can be read or written by ``unsafe_load`` or + .. function:: cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - Generate C-callable function pointer from Julia function. Type annotation of the return value in the - callback function is a must for situations where Julia cannot infer the return type automatically. - - For example:: - - function foo() - # body - - retval::Float64 - end - - bar = cfunction(foo, Float64, ()) + :: + + cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + + Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically. For example: + .. function:: unsafe_convert(T,x) - Convert "x" to a value of type "T" - - In cases where ``convert`` would need to take a Julia object and turn it into a ``Ptr``, - this function should be used to define and perform that conversion. - - Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. - Accordingly, the argument ``x`` to this function should never be an expression, - only a variable name or field reference. - For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. - - The ``unsafe`` prefix on this function indicates that using the result of this function - after the ``x`` argument to this function is no longer accessible to the program may cause - undefined behavior, including program corruption or segfaults, at any later time. + :: + + unsafe_convert(T, x) + + Convert ``x`` to a value of type ``T`` In cases where ``convert`` would need to take a Julia object and turn it into a ``Ptr``, this function should be used to define and perform that conversion. Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. Accordingly, the argument ``x`` to this function should never be an expression, only a variable name or field reference. For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. The ``unsafe`` prefix on this function indicates that using the result of this function after the ``x`` argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time. + .. function:: cconvert(T,x) - Convert "x" to a value of type "T", typically by calling ``convert(T,x)`` - - In cases where "x" cannot be safely converted to "T", unlike ``convert``, - ``cconvert`` may return an object of a type different from "T", - which however is suitable for ``unsafe_convert`` to handle. - - Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``. + :: + + cconvert(T, x) + + Convert ``x`` to a value of type ``T``, typically by calling In cases where ``x`` cannot be safely converted to ``T``, unlike from ``T``, which however is suitable for ``unsafe_convert`` to handle. Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``. + .. function:: unsafe_load(p::Ptr{T},i::Integer) - Load a value of type ``T`` from the address of the ith element (1-indexed) - starting at ``p``. This is equivalent to the C expression ``p[i-1]``. - - The ``unsafe`` prefix on this function indicates that no validation is - performed on the pointer ``p`` to ensure that it is valid. Incorrect usage - may segfault your program or return garbage answers, in the same manner as - C. + :: + + unsafe_load(p::Ptr{T}, i::Integer) + + Load a value of type ``T`` from the address of the ith element expression ``p[i-1]``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C. + .. function:: unsafe_store!(p::Ptr{T},x,i::Integer) - Store a value of type ``T`` to the address of the ith element (1-indexed) - starting at ``p``. This is equivalent to the C expression ``p[i-1] = x``. - - The ``unsafe`` prefix on this function indicates that no validation is performed - on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt - or segfault your program, in the same manner as C. + :: + + unsafe_store!(p::Ptr{T}, x, i::Integer) + + Store a value of type ``T`` to the address of the ith element expression ``p[i-1] = x``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. + .. function:: unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - Copy ``N`` elements from a source pointer to a destination, with no checking. The - size of an element is determined by the type of the pointers. - - The ``unsafe`` prefix on this function indicates that no validation is performed - on the pointers ``dest`` and ``src`` to ensure that they are valid. - Incorrect usage may corrupt or segfault your program, in the same manner as C. + :: + + unsafe_copy!(dest::Array, do, src::Array, so, N) + + Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. + .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` - in the source and ``do`` in the destination (1-indexed). - - The ``unsafe`` prefix on this function indicates that no validation is performed - to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault - your program, in the same manner as C. + :: + + unsafe_copy!(dest::Array, do, src::Array, so, N) + + Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. + .. function:: copy!(dest, src) - Copy all elements from collection ``src`` to array ``dest``. Returns ``dest``. + :: + + copy!(dest, do, src, so, N) + + Copy ``N`` elements from collection ``src`` starting at offset + .. function:: copy!(dest, do, src, so, N) - Copy ``N`` elements from collection ``src`` starting at offset ``so``, to - array ``dest`` starting at offset ``do``. Returns ``dest``. + :: + + copy!(dest, do, src, so, N) + + Copy ``N`` elements from collection ``src`` starting at offset + .. function:: pointer(array [, index]) - Get the native address of an array or string element. Be careful to - ensure that a julia reference to ``a`` exists as long as this - pointer will be used. This function is "unsafe" like ``unsafe_convert``. - - Calling ``Ref(array[, index])`` is generally preferable to this function. + :: + + pointer(array[, index]) + + Get the native address of an array or string element. Be careful to ensure that a julia reference to ``a`` exists as long as this pointer will be used. This function is ``unsafe`` like Calling ``Ref(array[, index])`` is generally preferable to this function. + .. function:: pointer_to_array(pointer, dims[, take_ownership::Bool]) - Wrap a native pointer as a Julia Array object. The pointer element type determines - the array element type. ``own`` optionally specifies whether Julia should take - ownership of the memory, calling ``free`` on the pointer when the array is no - longer referenced. + :: + + pointer_to_array(pointer, dims[, take_ownership::Bool]) + + Wrap a native pointer as a Julia Array object. The pointer element type determines the array element type. ``own`` optionally specifies whether Julia should take ownership of the memory, calling ``free`` on the pointer when the array is no longer referenced. + .. function:: pointer_from_objref(object_instance) - Get the memory address of a Julia object as a ``Ptr``. The existence of the resulting - ``Ptr`` will not protect the object from garbage collection, so you must ensure - that the object remains referenced for the whole time that the ``Ptr`` will be used. + :: + + pointer_from_objref(object_instance) + + Get the memory address of a Julia object as a ``Ptr``. The existence of the resulting ``Ptr`` will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that the ``Ptr`` will be used. + .. function:: unsafe_pointer_to_objref(p::Ptr) - Convert a ``Ptr`` to an object reference. Assumes the pointer refers to a - valid heap-allocated Julia object. If this is not the case, undefined behavior - results, hence this function is considered "unsafe" and should be used with care. + :: + + unsafe_pointer_to_objref(p::Ptr) + + Convert a ``Ptr`` to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined behavior results, hence this function is considered + .. function:: disable_sigint(f::Function) - Disable Ctrl-C handler during execution of a function, for calling - external code that is not interrupt safe. Intended to be called using ``do`` - block syntax as follows:: - - disable_sigint() do - # interrupt-unsafe code - ... - end + :: + + disable_sigint(f::Function) + + Disable Ctrl-C handler during execution of a function, for calling external code that is not interrupt safe. Intended to be called using ``do`` block syntax as follows: + .. function:: reenable_sigint(f::Function) - Re-enable Ctrl-C handler during execution of a function. Temporarily - reverses the effect of ``disable_sigint``. + :: + + reenable_sigint(f::Function) + + Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of ``disable_sigint``. + .. function:: systemerror(sysfunc, iftrue) - Raises a ``SystemError`` for ``errno`` with the descriptive string ``sysfunc`` if ``bool`` is true + :: + + systemerror(sysfunc, iftrue) + + Raises a ``SystemError`` for ``errno`` with the descriptive string + .. data:: Ptr{T} diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index ef9bb1de368cf..8d685ef990d38 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -26,61 +26,102 @@ The ``state`` object may be anything, and should be chosen appropriately for eac .. function:: start(iter) -> state + :: + + start(iter) -> state + Get initial iteration state for an iterable object + .. function:: done(iter, state) -> Bool + :: + + done(iter, state) -> Bool + Test whether we are done iterating + .. function:: next(iter, state) -> item, state + :: + + next(iter, state) -> item, state + For a given iterable object and iteration state, return the current item and the next iteration state + .. function:: zip(iters...) - For a set of iterable objects, returns an iterable of tuples, where the ``i``\ th tuple contains the ``i``\ th component of each input iterable. - - Note that :func:`zip` is its own inverse: ``collect(zip(zip(a...)...)) == collect(a)``. + :: + + zip(iters...) + + For a set of iterable objects, returns an iterable of tuples, where the ``i``th tuple contains the ``i``th component of each input iterable. Note that ``zip()`` is its own inverse: + .. function:: enumerate(iter) - An iterator that yields ``(i, x)`` where ``i`` is an index starting at 1, and ``x`` is the ``i``\ th value from the given iterator. It's useful when you need not only the values ``x`` over which you are iterating, but also the index ``i`` of the iterations. - - .. doctest:: - - julia> a = ["a", "b", "c"]; - - julia> for (index, value) in enumerate(a) - println("$index $value") - end - 1 a - 2 b - 3 c + :: + + enumerate(iter) + + An iterator that yields ``(i, x)`` where ``i`` is an index starting at 1, and ``x`` is the ``i``th value from the given iterator. It's useful when you need not only the values ``x`` over which you are iterating, but also the index ``i`` of the iterations. + .. function:: rest(iter, state) + :: + + rest(iter, state) + An iterator that yields the same elements as ``iter``, but starting at the given ``state``. + .. function:: countfrom(start=1, step=1) + :: + + countfrom(start=1, step=1) + An iterator that counts forever, starting at ``start`` and incrementing by ``step``. + .. function:: take(iter, n) - An iterator that generates at most the first ``n`` elements of ``iter``. + :: + + take(iter, n) + + An iterator that generates at most the first ``n`` elements of + .. function:: drop(iter, n) - An iterator that generates all but the first ``n`` elements of ``iter``. + :: + + drop(iter, n) + + An iterator that generates all but the first ``n`` elements of + .. function:: cycle(iter) + :: + + cycle(iter) + An iterator that cycles through ``iter`` forever. + .. function:: repeated(x[, n::Int]) - An iterator that generates the value ``x`` forever. If ``n`` is specified, generates - ``x`` that many times (equivalent to ``take(repeated(x), n)``). + :: + + repeated(x[, n::Int]) + + An iterator that generates the value ``x`` forever. If ``n`` is specified, generates ``x`` that many times (equivalent to + Fully implemented by: @@ -104,32 +145,39 @@ General Collections .. function:: isempty(collection) -> Bool + :: + + isempty(collection) -> Bool + Determine whether a collection is empty (has no elements). - - .. doctest:: - - julia> isempty([]) - true - - julia> isempty([1 2 3]) - false + .. function:: empty!(collection) -> collection + :: + + empty!(collection) -> collection + Remove all elements from a ``collection``. + .. function:: length(collection) -> Integer - For ordered, indexable collections, the maximum index ``i`` for which ``getindex(collection, i)`` is valid. For unordered collections, the number of elements. + :: + + length(s) + + The number of characters in string ``s``. + .. function:: endof(collection) -> Integer + :: + + endof(collection) -> Integer + Returns the last index of the collection. - - .. doctest:: - - julia> endof([1,2,4]) - 3 + Fully implemented by: @@ -148,417 +196,646 @@ Iterable Collections -------------------- .. 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 :obj:`Set`\ s - check whether the item :func:`isequal` to one of the elements. :obj:`Dict`\ s look for - ``(key,value)`` pairs, and the key is compared using :func:`isequal`. To test - for the presence of a key in a dictionary, use :func:`haskey` or - ``k in keys(dict)``. + + :: + + in(item, collection) -> Bool + + Determine whether an item is in the given collection, in the sense that it is ``==`` to one of the values generated by iterating over the collection. Some collections need a slightly different definition; for example ``Set``s check whether the item To test for the presence of a key in a dictionary, use ``haskey()`` or ``k in keys(dict)``. + .. 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 ``(key,value)`` tuple type. - 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. + :: + + 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 ``(key,value)`` tuple type. The definition that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types. + .. 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``. + :: + + 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``. + .. function:: findin(a, b) + :: + + findin(a, b) + Returns the indices of elements in collection ``a`` that appear in collection ``b`` + .. function:: 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``. + :: + + 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``. + .. function:: 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. + :: + + 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``. + .. function:: 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``. + :: + + 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``. + .. function:: foldl(op, v0, itr) - Like :func:`reduce`, but with guaranteed left associativity. ``v0`` - will be used exactly once. + :: + + 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 + .. function:: 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)``). + :: + + 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 + .. function:: foldr(op, v0, itr) - Like :func:`reduce`, but with guaranteed right associativity. ``v0`` - will be used exactly once. + :: + + 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 + .. function:: 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)``). + :: + + 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 + .. function:: maximum(itr) - Returns the largest element in a collection. + :: + + maximum(A, dims) + + Compute the maximum value of an array over the given dimensions. + .. function:: maximum(A, dims) + :: + + maximum(A, dims) + Compute the maximum value of an array over the given dimensions. + .. function:: maximum!(r, A) - Compute the maximum value of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + :: + + maximum!(r, A) + + Compute the maximum value of ``A`` over the singleton dimensions of + .. function:: minimum(itr) - Returns the smallest element in a collection. + :: + + minimum(A, dims) + + Compute the minimum value of an array over the given dimensions. + .. function:: minimum(A, dims) + :: + + minimum(A, dims) + Compute the minimum value of an array over the given dimensions. + .. function:: minimum!(r, A) - Compute the minimum value of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + :: + + minimum!(r, A) + + Compute the minimum value of ``A`` over the singleton dimensions of + .. function:: extrema(itr) - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. + :: + + extrema(itr) + + Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. + .. function:: indmax(itr) -> Integer + :: + + indmax(itr) -> Integer + Returns the index of the maximum element in a collection. + .. function:: indmin(itr) -> Integer + :: + + indmin(itr) -> Integer + Returns the index of the minimum element in a collection. + .. function:: findmax(itr) -> (x, index) - Returns the maximum element and its index. + :: + + findmax(A, dims) -> (maxval, index) + + For an array input, returns the value and index of the maximum over the given dimensions. + .. function:: findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over - the given dimensions. + :: + + findmax(A, dims) -> (maxval, index) + + For an array input, returns the value and index of the maximum over the given dimensions. + .. function:: findmin(itr) -> (x, index) - Returns the minimum element and its index. + :: + + findmin(A, dims) -> (minval, index) + + For an array input, returns the value and index of the minimum over the given dimensions. + .. function:: findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over - the given dimensions. + :: + + findmin(A, dims) -> (minval, index) + + For an array input, returns the value and index of the minimum over the given dimensions. + .. function:: maxabs(itr) - Compute the maximum absolute value of a collection of values. + :: + + maxabs(A, dims) + + Compute the maximum absolute values over given dimensions. + .. function:: maxabs(A, dims) + :: + + maxabs(A, dims) + Compute the maximum absolute values over given dimensions. + .. function:: maxabs!(r, A) - Compute the maximum absolute values over the singleton dimensions of ``r``, - and write values to ``r``. + :: + + maxabs!(r, A) + + Compute the maximum absolute values over the singleton dimensions of ``r``, and write values to ``r``. + .. function:: minabs(itr) - Compute the minimum absolute value of a collection of values. + :: + + minabs(A, dims) + + Compute the minimum absolute values over given dimensions. + .. function:: minabs(A, dims) + :: + + minabs(A, dims) + Compute the minimum absolute values over given dimensions. + .. function:: minabs!(r, A) - Compute the minimum absolute values over the singleton dimensions of ``r``, - and write values to ``r``. + :: + + minabs!(r, A) + + Compute the minimum absolute values over the singleton dimensions of ``r``, and write values to ``r``. + .. function:: sum(itr) - Returns the sum of all elements in a collection. + :: + + sum(f, itr) + + Sum the results of calling function ``f`` on each element of + .. function:: sum(A, dims) - Sum elements of an array over the given dimensions. + :: + + sum(f, itr) + + Sum the results of calling function ``f`` on each element of + .. function:: sum!(r, A) - Sum elements of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + :: + + sum!(r, A) + + Sum elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. + .. function:: sum(f, itr) - Sum the results of calling function ``f`` on each element of ``itr``. + :: + + sum(f, itr) + + Sum the results of calling function ``f`` on each element of + .. function:: sumabs(itr) - Sum absolute values of all elements in a collection. This is - equivalent to `sum(abs(itr))` but faster. + :: + + sumabs(A, dims) + + Sum absolute values of elements of an array over the given dimensions. + .. function:: sumabs(A, dims) - Sum absolute values of elements of an array over the given - dimensions. + :: + + sumabs(A, dims) + + Sum absolute values of elements of an array over the given dimensions. + .. function:: sumabs!(r, A) - Sum absolute values of elements of ``A`` over the singleton - dimensions of ``r``, and write results to ``r``. + :: + + sumabs!(r, A) + + Sum absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. + .. function:: sumabs2(itr) - Sum squared absolute values of all elements in a collection. This - is equivalent to `sum(abs2(itr))` but faster. + :: + + sumabs2(A, dims) + + Sum squared absolute values of elements of an array over the given dimensions. + .. function:: sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. + :: + + sumabs2(A, dims) + + Sum squared absolute values of elements of an array over the given dimensions. + .. function:: sumabs2!(r, A) - Sum squared absolute values of elements of ``A`` over the singleton - dimensions of ``r``, and write results to ``r``. + :: + + sumabs2!(r, A) + + Sum squared absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. + .. function:: prod(itr) - Returns the product of all elements of a collection. + :: + + prod(A, dims) + + Multiply elements of an array over the given dimensions. + .. function:: prod(A, dims) + :: + + prod(A, dims) + Multiply elements of an array over the given dimensions. + .. function:: prod!(r, A) - Multiply elements of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + :: + + prod!(r, A) + + Multiply elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. + .. function:: any(itr) -> Bool - Test whether any elements of a boolean collection are true. + :: + + any(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for any elements of + .. function:: any(A, dims) - Test whether any values along the given dimensions of an array are true. + :: + + any(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for any elements of + .. function:: any!(r, A) - Test whether any values in ``A`` along the singleton dimensions of ``r`` are true, - and write results to ``r``. + :: + + any!(r, A) + + Test whether any values in ``A`` along the singleton dimensions of + .. function:: all(itr) -> Bool - Test whether all elements of a boolean collection are true. + :: + + all(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for all elements of + .. function:: all(A, dims) - Test whether all values along the given dimensions of an array are true. + :: + + all(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for all elements of + .. function:: all!(r, A) - Test whether all values in ``A`` along the singleton dimensions of ``r`` are true, - and write results to ``r``. + :: + + all!(r, A) + + Test whether all values in ``A`` along the singleton dimensions of + .. function:: count(p, itr) -> Integer + :: + + count(p, itr) -> Integer + Count the number of elements in ``itr`` for which predicate ``p`` returns true. + .. function:: any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of ``itr``. + :: + + any(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for any elements of + .. function:: all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of ``itr``. - - .. doctest:: - - julia> all(i->(4<=i<=6), [4,5,6]) - true + :: + + all(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for all elements of + .. function:: map(f, c...) -> collection - Transform collection ``c`` by applying ``f`` to each element. - For multiple collection arguments, apply ``f`` elementwise. - - .. doctest:: - - 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 + :: + + map(f, c...) -> collection + + Transform collection ``c`` by applying ``f`` to each element. For multiple collection arguments, apply ``f`` elementwise. + .. function:: map!(function, collection) - In-place version of :func:`map`. + :: + + 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. + .. function:: map!(function, destination, collection...) - Like :func:`map`, but stores the result in ``destination`` rather than a - new collection. ``destination`` must be at least as large as the first - collection. + :: + + 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. + .. function:: 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. - - :func:`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 - :func:`reduce` and :func:`map`. - - .. doctest:: - - 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 :func:`mapfoldl` or :func:`mapfoldr` instead for guaranteed - left or right associativity and invocation of ``f`` for every value. + :: + + mapreduce(f, op, itr) + + Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). + .. function:: mapreduce(f, op, itr) - Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used - with empty collections (see ``reduce(op, itr)``). + :: + + mapreduce(f, op, itr) + + Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). + .. function:: mapfoldl(f, op, v0, itr) - Like :func:`mapreduce`, but with guaranteed left associativity. ``v0`` - will be used exactly once. + :: + + mapfoldl(f, op, itr) + + Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). + .. function:: 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)``). + :: + + mapfoldl(f, op, itr) + + Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). + .. function:: mapfoldr(f, op, v0, itr) - Like :func:`mapreduce`, but with guaranteed right associativity. ``v0`` - will be used exactly once. + :: + + mapfoldr(f, op, itr) + + Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). + .. function:: 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)``). + :: + + mapfoldr(f, op, itr) + + Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). + .. function:: first(coll) - Get the first element of an iterable collection. Returns the start point of a :obj:`Range` - even if it is empty. + :: + + first(coll) + + Get the first element of an iterable collection. Returns the start point of a ``Range`` even if it is empty. + .. 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 :func:`endof` to get the last index. - Returns the end point of a :obj:`Range` even if it is empty. + :: + + 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. + .. function:: step(r) - Get the step size of a :obj:`Range` object. + :: + + step(r) + + Get the step size of a ``Range`` object. + .. function:: collect(collection) - Return an array of all items in a collection. For associative collections, returns (key, value) tuples. + :: + + collect(element_type, collection) + + Return an array of type ``Array{element_type,1}`` of all items in a collection. + .. function:: collect(element_type, collection) + :: + + collect(element_type, collection) + Return an array of type ``Array{element_type,1}`` of all items in a collection. + .. function:: issubset(a, b) - ⊆(A,S) -> Bool - ⊈(A,S) -> Bool - ⊊(A,S) -> Bool - Determine whether every element of ``a`` is also in ``b``, using :func:`in`. + :: + + issubset(A, S) -> Bool + + True if A is a subset of or equal to S. + .. 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). + :: + + filter(function, collection) + + Return a copy of ``collection``, removing elements for which passed two arguments (key and value). + .. 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). - + :: + + filter!(function, collection) + + Update ``collection``, removing elements for which ``function`` is false. For associative collections, the function is passed two arguments (key and value). + Indexable Collections --------------------- .. function:: 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, ...)``. + :: + + 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, ...)``. + .. function:: 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, ...)``. + :: + + 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, ...)``. + Fully implemented by: @@ -597,116 +874,135 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: 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 :obj:`Dict` whose key-value pairs - are taken from 2-tuples ``(key,value)`` generated by the argument. - - .. doctest:: - - julia> Dict([("A", 1), ("B", 2)]) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 - - Alternatively, a sequence of pair arguments may be passed. - - .. doctest:: - - julia> Dict("A"=>1, "B"=>2) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 + :: + + Dict([itr]) + + 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. Alternatively, a sequence of pair arguments may be passed. + .. function:: haskey(collection, key) -> Bool + :: + + haskey(collection, key) -> Bool + Determine whether a collection has a mapping for a given key. + .. function:: 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. + :: + + 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: + .. 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 :func:`get!` to also store the default value in the dictionary. + :: + + 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: + - This is intended to be called using ``do`` block syntax:: - - get(dict, key) do - # default value calculated here time() end .. function:: 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``. + :: + + 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: + .. function:: 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!(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 .. function:: getkey(collection, key, default) - Return the key matching argument ``key`` if one exists in ``collection``, otherwise return ``default``. + :: + + getkey(collection, key, default) + + Return the key matching argument ``key`` if one exists in + .. function:: delete!(collection, key) + :: + + delete!(collection, key) + Delete the mapping for the given key in a collection, and return the collection. + .. function:: 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. + :: + + pop!(collection) -> item + + Remove the last item in ``collection`` and return it. + .. function:: keys(collection) - Return an iterator over all keys in a collection. ``collect(keys(d))`` returns an array of keys. + :: + + keys(collection) + + Return an iterator over all keys in a collection. + .. function:: values(collection) - Return an iterator over all values in a collection. ``collect(values(d))`` returns an array of values. + :: + + values(collection) + + Return an iterator over all values in a collection. + .. function:: merge(collection, others...) - 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. - - .. doctest:: - - julia> a = Dict("foo" => 0.0, "bar" => 42.0) - Dict{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 - - julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "bar" => 4711 - "baz" => 17 - - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 - - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 + :: + + merge(collection, others...) + + 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. + .. function:: merge!(collection, others...) + :: + + merge!(collection, others...) + Update collection with pairs from the other collections + .. function:: sizehint!(s, n) + :: + + sizehint!(s, n) + Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. + Fully implemented by: @@ -727,70 +1023,138 @@ Set-Like Collections .. function:: Set([itr]) - Construct a :obj:`Set` of the values generated by the given iterable object, or an empty set. - Should be used instead of :obj:`IntSet` for sparse integer sets, or for sets of arbitrary objects. + :: + + 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. + .. function:: IntSet([itr]) - Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use :obj:`Set` instead. + :: + + IntSet([itr]) + + Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use ``Set`` instead. + .. function:: union(s1,s2...) - ∪(s1,s2) + :: + + union(s1, s2...) + Construct the union of two or more sets. Maintains order with arrays. + .. function:: union!(s, iterable) + :: + + union!(s, iterable) + Union each element of ``iterable`` into set ``s`` in-place. + .. function:: intersect(s1,s2...) - ∩(s1,s2) + :: + + intersect(s1, s2...) + Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. + .. function:: setdiff(s1,s2) - Construct the set of elements in ``s1`` but not ``s2``. 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. + :: + + setdiff(s1, s2) + + Construct the set of elements in ``s1`` but not ``s2``. Maintains order with arrays. Note that both arguments must be collections, and both will be iterated over. In particular, + .. function:: setdiff!(s, iterable) + :: + + setdiff!(s, iterable) + Remove each element of ``iterable`` from set ``s`` in-place. + .. function:: symdiff(s1,s2...) + :: + + symdiff(s1, s2...) + Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. + .. function:: symdiff!(s, n) - The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + :: + + symdiff!(s1, s2) + + Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + .. function:: symdiff!(s, itr) - For each element in ``itr``, destructively toggle its inclusion in set ``s``. + :: + + symdiff!(s1, s2) + + Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + .. function:: symdiff!(s1, s2) + :: + + symdiff!(s1, s2) + Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + .. function:: complement(s) - Returns the set-complement of :obj:`IntSet` ``s``. + :: + + complement(s) + + Returns the set-complement of ``IntSet`` ``s``. + .. function:: complement!(s) - Mutates :obj:`IntSet` ``s`` into its set-complement. + :: + + complement!(s) + + Mutates ``IntSet`` ``s`` into its set-complement. + .. function:: intersect!(s1, s2) - Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of ``s2``. + :: + + intersect!(s1, s2) + + Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of + .. function:: issubset(A, S) -> Bool - ⊆(A,S) -> Bool + :: + + issubset(A, S) -> Bool + True if A is a subset of or equal to S. + Fully implemented by: @@ -806,280 +1170,111 @@ Dequeues .. function:: push!(collection, items...) -> collection - Insert one or more ``items`` at the end of ``collection``. - - .. doctest:: - - julia> push!([1, 2, 3], 4, 5, 6) - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 - - Use :func:`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])``. + :: + + push!(collection, items...) -> collection + + Insert one or more ``items`` at the end of ``collection``. Use ``append!()`` to add all the elements of another collection to to ``append!([1, 2, 3], [4, 5, 6])``. + .. function:: pop!(collection) -> item + :: + + pop!(collection) -> item + Remove the last item in ``collection`` and return it. - - .. doctest:: - - 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 + .. function:: unshift!(collection, items...) -> collection + :: + + unshift!(collection, items...) -> collection + Insert one or more ``items`` at the beginning of ``collection``. - - .. doctest:: - - julia> unshift!([1, 2, 3, 4], 5, 6) - 6-element Array{Int64,1}: - 5 - 6 - 1 - 2 - 3 - 4 + .. function:: shift!(collection) -> item + :: + + shift!(collection) -> item + Remove the first ``item`` from ``collection``. - - .. doctest:: - - 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 + .. function:: insert!(collection, index, item) + :: + + insert!(collection, index, item) + Insert an ``item`` into ``collection`` at the given ``index``. - ``index`` is the index of ``item`` in the resulting ``collection``. - - .. doctest:: - - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 + .. function:: deleteat!(collection, index) - Remove the item at the given ``index`` and return the modified ``collection``. - Subsequent items are shifted to fill the resulting gap. - - .. doctest:: - - julia> deleteat!([6, 5, 4, 3, 2, 1], 2) - 5-element Array{Int64,1}: - 6 - 4 - 3 - 2 - 1 + :: + + deleteat!(collection, itr) + + Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. + .. function:: deleteat!(collection, itr) - Remove the items at the indices given by ``itr``, and return the modified ``collection``. - Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. - - .. doctest:: - - julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5) - 3-element Array{Int64,1}: - 5 - 3 - 1 - - .. doctest:: - - julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 + :: + + deleteat!(collection, itr) + + Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. + .. function:: splice!(collection, index, [replacement]) -> item - Remove the item at the given index, and return the removed item. Subsequent items - are shifted down to fill the resulting gap. If specified, replacement values from - an ordered collection will be spliced in place of the removed item. - - .. doctest:: - - 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!(collection, range[, replacement]) -> items + + Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. + .. function:: splice!(collection, range, [replacement]) -> items - Remove items in the specified index range, and return a collection containing the - removed items. Subsequent items are shifted down 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)``. - - .. doctest:: - - 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 + :: + + splice!(collection, range[, replacement]) -> items + + Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. + .. function:: resize!(collection, n) -> collection - Resize ``collection`` 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. - - .. doctest:: - - julia> resize!([6, 5, 4, 3, 2, 1], 3) - 3-element Array{Int64,1}: - 6 - 5 - 4 - - .. code-block:: julia - - julia> resize!([6, 5, 4, 3, 2, 1], 8) - 8-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 - 0 - 0 + :: + + resize!(collection, n) -> collection + + Resize ``collection`` 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. + .. function:: append!(collection, collection2) -> collection. - Add the elements of ``collection2`` to the end of ``collection``. - - .. doctest:: - - julia> append!([1],[2,3]) - 3-element Array{Int64,1}: - 1 - 2 - 3 - - .. doctest:: - - julia> append!([1, 2, 3], [4, 5, 6]) - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 - - Use :func:`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)``. + :: + + append!(collection, collection2) -> collection. + + Add the elements of ``collection2`` to the end of ``collection``. 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)``. + .. function:: prepend!(collection, items) -> collection - Insert the elements of ``items`` to the beginning of ``collection``. - - .. doctest:: - - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 + :: + + prepend!(collection, items) -> collection + + Insert the elements of ``items`` to the beginning of + Fully implemented by: @@ -1098,21 +1293,39 @@ changed efficiently. .. function:: PriorityQueue(K, V, [ord]) - Construct a new :obj:`PriorityQueue`, with keys of type ``K`` and values/priorites of - type ``V``. If an order is not given, the priority queue is min-ordered using - the default comparison for ``V``. + :: + + PriorityQueue(K, V[, ord]) + + Construct a new ``PriorityQueue``, with keys of type ``K`` and values/priorites of type ``V``. If an order is not given, the priority queue is min-ordered using the default comparison for + .. function:: enqueue!(pq, k, v) - Insert the a key ``k`` into a priority queue ``pq`` with priority ``v``. + :: + + enqueue!(pq, k, v) + + Insert the a key ``k`` into a priority queue ``pq`` with priority + .. function:: dequeue!(pq) + :: + + dequeue!(pq) + Remove and return the lowest priority key from a priority queue. + .. function:: peek(pq) + :: + + peek(pq) + Return the lowest priority key from a priority queue without removing that key from the queue. + :obj:`PriorityQueue` also behaves similarly to a :obj:`Dict` in that keys can be inserted and priorities accessed or changed using indexing notation. @@ -1146,26 +1359,46 @@ is used, so that elements popped from the heap are given in ascending order. .. function:: heapify(v, [ord]) - Return a new vector in binary heap order, optionally using the given - ordering. + :: + + heapify(v[, ord]) + + Return a new vector in binary heap order, optionally using the given ordering. + .. function:: heapify!(v, [ord]) - In-place :func:`heapify`. + :: + + heapify!(v[, ord]) + + In-place ``heapify()``. + .. function:: isheap(v, [ord]) + :: + + isheap(v[, ord]) + Return true iff an array is heap-ordered according to the given order. + .. function:: heappush!(v, x, [ord]) - Given a binary heap-ordered array, push a new element ``x``, preserving the heap - property. For efficiency, this function does not check that the array is - indeed heap-ordered. + :: + + heappush!(v, x[, ord]) + + Given a binary heap-ordered array, push a new element ``x``, preserving the heap property. For efficiency, this function does not check that the array is indeed heap-ordered. + .. function:: heappop!(v, [ord]) - Given a binary heap-ordered array, remove and return the lowest ordered - element. For efficiency, this function does not check that the array is - indeed heap-ordered. + :: + + heappop!(v[, ord]) + + Given a binary heap-ordered array, remove and return the lowest ordered element. For efficiency, this function does not check that the array is indeed heap-ordered. + diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index 0d0cbc54c4d10..24a7de2709efc 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -49,53 +49,48 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(y, [m, d, h, mi, s, ms]) -> DateTime - Construct a DateTime type by parts. Arguments must be convertible to - ``Int64``. + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(periods::Period...) -> DateTime - Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. - DateTime parts not provided will default to the value of ``Dates.default(period)``. + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - Create a DateTime through the adjuster API. The starting point will be constructed from the - provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` - is never satisfied). + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(dt::Date) -> DateTime - Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond - parts of the new ``DateTime`` are assumed to be zero. + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime - Construct a DateTime type by parsing the ``dt`` date string following the pattern given in - the ``format`` string. The following codes can be used for constructing format strings: - - =============== ========= =============================================================== - Code Matches Comment - --------------- --------- --------------------------------------------------------------- - ``y`` 1996, 96 Returns year of 1996, 0096 - ``m`` 1, 01 Matches 1 or 2-digit months - ``u`` Jan Matches abbreviated months according to the ``locale`` keyword - ``U`` January Matches full month names according to the ``locale`` keyword - ``d`` 1, 01 Matches 1 or 2-digit days - ``H`` 00 Matches hours - ``M`` 00 Matches minutes - ``S`` 00 Matches seconds - ``s`` .500 Matches milliseconds - ``e`` Mon, Tues Matches abbreviated days of the week - ``E`` Monday Matches full name days of the week - ``yyyymmdd`` 19960101 Matches fixed-width year, month, and day - =============== ========= =============================================================== - - All characters not listed above are treated as delimiters between date and time slots. - So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string - like "y-m-dTH:M:S.s". + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: Dates.DateFormat(format::AbstractString) -> DateFormat @@ -103,230 +98,397 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + :: + + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(period::Period...) -> Date - Constuct a Date type by ``Period`` type parts. Arguments may be in any order. - Date parts not provided will default to the value of ``Dates.default(period)``. + :: + + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be constructed from the - provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` - is never satisfied). + :: + + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(dt::DateTime) -> Date - Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond - parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + :: + + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a ``dt`` date string following the pattern given in - the ``format`` string. Follows the same conventions as ``DateTime`` above. + :: + + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date + :: + + Date(dt::AbstractString, df::DateFormat) -> Date + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: now() -> DateTime - Returns a DateTime corresponding to the user's system - time including the system timezone locale. + :: + + now(::Type{UTC}) -> DateTime + + Returns a DateTime corresponding to the user's system time as UTC/GMT. + .. function:: now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system - time as UTC/GMT. + :: + + now(::Type{UTC}) -> DateTime + + Returns a DateTime corresponding to the user's system time as UTC/GMT. + .. function:: eps(::DateTime) -> Millisecond - eps(::Date) -> Day + :: + + eps(::DateTime) -> Millisecond + Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + Accessor Functions ~~~~~~~~~~~~~~~~~~ .. function:: year(dt::TimeType) -> Int64 - month(dt::TimeType) -> Int64 - week(dt::TimeType) -> Int64 - day(dt::TimeType) -> Int64 - hour(dt::TimeType) -> Int64 - minute(dt::TimeType) -> Int64 - second(dt::TimeType) -> Int64 - millisecond(dt::TimeType) -> Int64 + :: + + year(dt::TimeType) -> Int64 + Return the field part of a Date or DateTime as an ``Int64``. + .. function:: Year(dt::TimeType) -> Year - Month(dt::TimeType) -> Month - Week(dt::TimeType) -> Week - Day(dt::TimeType) -> Day - Hour(dt::TimeType) -> Hour - Minute(dt::TimeType) -> Minute - Second(dt::TimeType) -> Second - Millisecond(dt::TimeType) -> Millisecond - Return the field part of a Date or DateTime as a ``Period`` type. + :: + + Year(v) + + Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. + .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) - Simultaneously return the year and month parts of a Date or DateTime. + :: + + yearmonth(dt::TimeType) -> (Int64, Int64) + + Simultaneously return the year and month parts of a Date or DateTime. + .. function:: monthday(dt::TimeType) -> (Int64, Int64) - Simultaneously return the month and day parts of a Date or DateTime. + :: + + monthday(dt::TimeType) -> (Int64, Int64) + + Simultaneously return the month and day parts of a Date or DateTime. + .. function:: yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - Simultaneously return the year, month, and day parts of a Date or DateTime. + :: + + yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + + Simultaneously return the year, month, and day parts of a Date or DateTime. + Query Functions ~~~~~~~~~~~~~~~ .. function:: dayname(dt::TimeType; locale="english") -> AbstractString - Return the full day name corresponding to the day of the week - of the Date or DateTime in the given ``locale``. + :: + + dayname(dt::TimeType; locale="english") -> AbstractString + + Return the full day name corresponding to the day of the week of the Date or DateTime in the given ``locale``. + .. function:: dayabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated name corresponding to the day of the week - of the Date or DateTime in the given ``locale``. + :: + + dayabbr(dt::TimeType; locale="english") -> AbstractString + + Return the abbreviated name corresponding to the day of the week of the Date or DateTime in the given ``locale``. + .. function:: dayofweek(dt::TimeType) -> Int64 - Returns the day of the week as an ``Int64`` with ``1 = Monday, 2 = Tuesday, etc.``. + :: + + dayofweek(dt::TimeType) -> Int64 + + Returns the day of the week as an ``Int64`` with ``1 = Monday, 2 = Tuesday, etc.``. + .. function:: dayofweekofmonth(dt::TimeType) -> Int - For the day of week of ``dt``, returns which number it is in ``dt``'s month. - So if the day of the week of ``dt`` is Monday, then ``1 = First Monday of the month, - 2 = Second Monday of the month, etc.`` In the range 1:5. + :: + + dayofweekofmonth(dt::TimeType) -> Int + + For the day of week of ``dt``, returns which number it is in etc.` In the range 1:5. + .. function:: daysofweekinmonth(dt::TimeType) -> Int - For the day of week of ``dt``, returns the total number of that day of the week - in ``dt``'s month. Returns 4 or 5. Useful in temporal expressions for specifying - the last day of a week in a month by including ``dayofweekofmonth(dt) == daysofweekinmonth(dt)`` - in the adjuster function. + :: + + daysofweekinmonth(dt::TimeType) -> Int + + For the day of week of ``dt``, returns the total number of that day of the week in ``dt``'s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by including ``dayofweekofmonth(dt) == daysofweekinmonth(dt)`` in the adjuster function. + .. function:: monthname(dt::TimeType; locale="english") -> AbstractString + :: + + monthname(dt::TimeType; locale="english") -> AbstractString + Return the full name of the month of the Date or DateTime in the given ``locale``. + .. function:: monthabbr(dt::TimeType; locale="english") -> AbstractString + :: + + monthabbr(dt::TimeType; locale="english") -> AbstractString + Return the abbreviated month name of the Date or DateTime in the given ``locale``. + .. function:: daysinmonth(dt::TimeType) -> Int - Returns the number of days in the month of ``dt``. Value will be 28, 29, 30, or 31. + :: + + daysinmonth(dt::TimeType) -> Int + + Returns the number of days in the month of ``dt``. Value will be 28, 29, 30, or 31. + .. function:: isleapyear(dt::TimeType) -> Bool - Returns true if the year of ``dt`` is a leap year. + :: + + isleapyear(dt::TimeType) -> Bool + + Returns true if the year of ``dt`` is a leap year. + .. function:: dayofyear(dt::TimeType) -> Int - Returns the day of the year for ``dt`` with January 1st being day 1. + :: + + dayofyear(dt::TimeType) -> Int + + Returns the day of the year for ``dt`` with January 1st being day 1. + .. function:: daysinyear(dt::TimeType) -> Int - Returns 366 if the year of ``dt`` is a leap year, otherwise returns 365. + :: + + daysinyear(dt::TimeType) -> Int + + Returns 366 if the year of ``dt`` is a leap year, otherwise returns 365. + .. function:: quarterofyear(dt::TimeType) -> Int - Returns the quarter that ``dt`` resides in. Range of value is 1:4. + :: + + quarterofyear(dt::TimeType) -> Int + + Returns the quarter that ``dt`` resides in. Range of value is 1:4. + .. function:: dayofquarter(dt::TimeType) -> Int - Returns the day of the current quarter of ``dt``. Range of value is 1:92. + :: + + dayofquarter(dt::TimeType) -> Int + + Returns the day of the current quarter of ``dt``. Range of value is 1:92. + Adjuster Functions ~~~~~~~~~~~~~~~~~~ .. function:: trunc(dt::TimeType, ::Type{Period}) -> TimeType - Truncates the value of ``dt`` according to the provided ``Period`` type. - E.g. if ``dt`` is ``1996-01-01T12:30:00``, then ``trunc(dt,Day) == 1996-01-01T00:00:00``. + :: + + trunc([T], x[, digits[, base]]) + .. function:: firstdayofweek(dt::TimeType) -> TimeType - Adjusts ``dt`` to the Monday of its week. + :: + + firstdayofweek(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the Monday of its week. + .. function:: lastdayofweek(dt::TimeType) -> TimeType - Adjusts ``dt`` to the Sunday of its week. + :: + + lastdayofweek(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the Sunday of its week. + .. function:: firstdayofmonth(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its month. + :: + + firstdayofmonth(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the first day of its month. + .. function:: lastdayofmonth(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its month. + :: + + lastdayofmonth(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the last day of its month. + .. function:: firstdayofyear(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its year. + :: + + firstdayofyear(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the first day of its year. + .. function:: lastdayofyear(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its year. + :: + + lastdayofyear(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the last day of its year. + .. function:: firstdayofquarter(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its quarter. + :: + + firstdayofquarter(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the first day of its quarter. + .. function:: lastdayofquarter(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its quarter. + :: + + lastdayofquarter(dt::TimeType) -> TimeType + + Adjusts ``dt`` to the last day of its quarter. + .. function:: tonext(dt::TimeType,dow::Int;same::Bool=false) -> TimeType - Adjusts ``dt`` to the next day of week corresponding to ``dow`` with - ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current - ``dt`` to be considered as the next ``dow``, allowing for no adjustment to occur. + :: + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. + .. function:: toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType - Adjusts ``dt`` to the previous day of week corresponding to ``dow`` with - ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current - ``dt`` to be considered as the previous ``dow``, allowing for no adjustment to occur. + :: + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. + .. function:: tofirst(dt::TimeType,dow::Int;of=Month) -> TimeType - Adjusts ``dt`` to the first ``dow`` of its month. Alternatively, ``of=Year`` - will adjust to the first ``dow`` of the year. + :: + + tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + + Adjusts ``dt`` to the first ``dow`` of its month. Alternatively, + .. function:: tolast(dt::TimeType,dow::Int;of=Month) -> TimeType - Adjusts ``dt`` to the last ``dow`` of its month. Alternatively, ``of=Year`` - will adjust to the last ``dow`` of the year. + :: + + tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + + Adjusts ``dt`` to the last ``dow`` of its month. Alternatively, + .. function:: tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until - ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. - ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment - process terminate when ``func`` returns false instead of true. + :: + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. + .. function:: toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until - ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. - ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment - process terminate when ``func`` returns false instead of true. + :: + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. + .. function:: recur{T<:TimeType}(func::Function,dr::StepRange{T};negate=false,limit=10000) -> Vector{T} @@ -340,60 +502,88 @@ Periods ~~~~~~~ .. function:: Year(v) - Month(v) - Week(v) - Day(v) - Hour(v) - Minute(v) - Second(v) - Millisecond(v) - Construct a ``Period`` type with the given ``v`` value. - Input must be losslessly convertible to an ``Int64``. + :: + + Year(v) + + Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. + .. function:: default(p::Period) -> Period - Returns a sensible "default" value for the input Period by returning - ``one(p)`` for Year, Month, and Day, and ``zero(p)`` for Hour, Minute, - Second, and Millisecond. + :: + + default(p::Period) -> Period + + Returns a sensible ``default`` value for the input Period by returning ``one(p)`` for Year, Month, and Day, and ``zero(p)`` for Hour, Minute, Second, and Millisecond. + Conversion Functions ~~~~~~~~~~~~~~~~~~~~ .. function:: today() -> Date - Returns the date portion of ``now()``. + :: + + today() -> Date + + Returns the date portion of ``now()``. + .. function:: unix2datetime(x) -> DateTime - Takes the number of seconds since unix epoch ``1970-01-01T00:00:00`` - and converts to the corresponding DateTime. + :: + + unix2datetime(x) -> DateTime + + Takes the number of seconds since unix epoch + .. function:: datetime2unix(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of seconds since - the unix epoch as a ``Float64``. + :: + + datetime2unix(dt::DateTime) -> Float64 + + Takes the given DateTime and returns the number of seconds since the unix epoch as a ``Float64``. + .. function:: julian2datetime(julian_days) -> DateTime + :: + + julian2datetime(julian_days) -> DateTime + Takes the number of Julian calendar days since epoch - ``-4713-11-24T12:00:00`` and returns the corresponding DateTime. + .. function:: datetime2julian(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of Julian calendar days - since the julian epoch as a ``Float64``. + :: + + datetime2julian(dt::DateTime) -> Float64 + + Takes the given DateTime and returns the number of Julian calendar days since the julian epoch as a ``Float64``. + .. function:: rata2datetime(days) -> DateTime - Takes the number of Rata Die days since epoch ``0000-12-31T00:00:00`` - and returns the corresponding DateTime. + :: + + rata2datetime(days) -> DateTime + + Takes the number of Rata Die days since epoch + .. function:: datetime2rata(dt::TimeType) -> Int64 - Returns the number of Rata Die days since epoch from the - given Date or DateTime. - + :: + + datetime2rata(dt::TimeType) -> Int64 + + Returns the number of Rata Die days since epoch from the given Date or DateTime. + Constants ~~~~~~~~~ diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index f53e41b6e3162..f8d06def9cc77 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -7,285 +7,514 @@ .. function:: pwd() -> AbstractString + :: + + pwd() -> AbstractString + Get the current working directory. + .. function:: cd(dir::AbstractString) - Set the current working directory. + :: + + cd(f[, dir]) + + Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. + .. function:: cd(f, [dir]) + :: + + cd(f[, dir]) + Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. + .. function:: readdir([dir]) -> Vector{ByteString} - Returns the files and directories in the directory `dir` (or the current working directory if not given). + :: + + readdir([dir]) -> Vector{ByteString} + + Returns the files and directories in the directory *dir* (or the current working directory if not given). + .. function:: mkdir(path, [mode]) - Make a new directory with name ``path`` and permissions ``mode``. - ``mode`` defaults to 0o777, modified by the current file creation mask. + :: + + mkdir(path[, mode]) + + Make a new directory with name ``path`` and permissions ``mode``. mask. + .. function:: mkpath(path, [mode]) - Create all directories in the given ``path``, with permissions ``mode``. - ``mode`` defaults to 0o777, modified by the current file creation mask. + :: + + mkpath(path[, mode]) + + Create all directories in the given ``path``, with permissions creation mask. + .. function:: symlink(target, link) - Creates a symbolic link to ``target`` with the name ``link``. - - .. note:: - - This function raises an error under operating systems that do not support - soft symbolic links, such as Windows XP. + :: + + symlink(target, link) + + Creates a symbolic link to ``target`` with the name ``link``. Note: This function raises an error under operating systems that + .. function:: readlink(path) -> AbstractString + :: + + readlink(path) -> AbstractString + Returns the value of a symbolic link ``path``. + .. function:: chmod(path, mode) - Change the permissions mode of ``path`` to ``mode``. Only integer ``mode``\ s - (e.g. 0o777) are currently supported. + :: + + chmod(path, mode) + + Change the permissions mode of ``path`` to ``mode``. Only integer + .. function:: stat(file) + :: + + stat(file) + Returns a structure whose fields contain information about the file. The fields of the structure are: - - ========= ====================================================================== - size The size (in bytes) of the file - device ID of the device that contains the file - inode The inode number of the file - mode The protection mode of the file - nlink The number of hard links to the file - uid The user id of the owner of the file - gid The group id of the file owner - rdev If this file refers to a device, the ID of the device it refers to - blksize The file-system preferred block size for the file - blocks The number of such blocks allocated - mtime Unix timestamp of when the file was last modified - ctime Unix timestamp of when the file was created - ========= ====================================================================== + .. function:: lstat(file) + :: + + lstat(file) + Like stat, but for symbolic links gets the info for the link itself rather than the file it refers to. This function must be called on a file path rather than a file object or a file descriptor. + .. function:: ctime(file) + :: + + ctime(file) + Equivalent to stat(file).ctime + .. function:: mtime(file) + :: + + mtime(file) + Equivalent to stat(file).mtime + .. function:: filemode(file) + :: + + filemode(file) + Equivalent to stat(file).mode + .. function:: filesize(path...) + :: + + filesize(path...) + Equivalent to stat(file).size + .. function:: uperm(file) - Gets the permissions of the owner of the file as a bitfield of - - ==== ===================== - 01 Execute Permission - 02 Write Permission - 04 Read Permission - ==== ===================== - - For allowed arguments, see ``stat``. + :: + + uperm(file) + + Gets the permissions of the owner of the file as a bitfield of For allowed arguments, see ``stat``. + .. function:: gperm(file) + :: + + gperm(file) + Like uperm but gets the permissions of the group owning the file + .. function:: operm(file) - Like uperm but gets the permissions for people who neither own the file nor are a - member of the group owning the file + :: + + operm(file) + + Like uperm but gets the permissions for people who neither own the file nor are a member of the group owning the file + .. function:: cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - Copy the file, link, or directory from *src* to *dest*. - \"remove_destination=true\" will first remove an existing `dst`. - - If `follow_symlinks=false`, and src is a symbolic link, dst will be created as a symbolic link. - If `follow_symlinks=true` and src is a symbolic link, dst will be a copy of the file or directory - `src` refers to. + :: + + cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + + Copy the file, link, or directory from *src* to *dest*. If *follow_symlinks=false*, and src is a symbolic link, dst will be created as a symbolic link. If *follow_symlinks=true* and src is a symbolic link, dst will be a copy of the file or directory *src* refers to. + .. function:: download(url,[localfile]) - Download a file from the given url, optionally renaming it to the given local file name. - Note that this function relies on the availability of external tools such as ``curl``, - ``wget`` or ``fetch`` to download the file and is provided for convenience. For production - use or situations in which more options are need, please use a package that provides the - desired functionality instead. + :: + + download(url[, localfile]) + + Download a file from the given url, optionally renaming it to the given local file name. Note that this function relies on the availability of external tools such as ``curl``, ``wget`` or production use or situations in which more options are need, please use a package that provides the desired functionality instead. + .. function:: mv(src::AbstractString,dst::AbstractString; remove_destination::Bool=false) + :: + + mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + Move the file, link, or directory from *src* to *dest*. - \"remove_destination=true\" will first remove an existing `dst`. + .. function:: rm(path::AbstractString; recursive=false) - Delete the file, link, or empty directory at the given path. If ``recursive=true`` is - passed and the path is a directory, then all contents are removed recursively. + :: + + rm(path::AbstractString; recursive=false) + + Delete the file, link, or empty directory at the given path. If contents are removed recursively. + .. function:: touch(path::AbstractString) + :: + + touch(path::AbstractString) + Update the last-modified timestamp on a file to the current time. + .. function:: tempname() + :: + + tempname() + Generate a unique temporary file path. + .. function:: tempdir() + :: + + tempdir() + Obtain the path of a temporary directory (possibly shared with other processes). + .. function:: mktemp([parent=tempdir()]) - Returns ``(path, io)``, where ``path`` is the path of a new temporary file - in ``parent`` and ``io`` is an open file object for this path. + :: + + mktemp([parent=tempdir()]) + + Returns ``(path, io)``, where ``path`` is the path of a new temporary file in ``parent`` and ``io`` is an open file object for this path. + .. function:: mktempdir([parent=tempdir()]) + :: + + mktempdir([parent=tempdir()]) + Create a temporary directory in the ``parent`` directory and return its path. + .. function:: isblockdev(path) -> Bool + :: + + isblockdev(path) -> Bool + Returns ``true`` if ``path`` is a block device, ``false`` otherwise. + .. function:: ischardev(path) -> Bool + :: + + ischardev(path) -> Bool + Returns ``true`` if ``path`` is a character device, ``false`` otherwise. + .. function:: isdir(path) -> Bool + :: + + isdir(path) -> Bool + Returns ``true`` if ``path`` is a directory, ``false`` otherwise. + .. function:: isexecutable(path) -> Bool - Returns ``true`` if the current user has permission to execute ``path``, - ``false`` otherwise. + :: + + isexecutable(path) -> Bool + + Returns ``true`` if the current user has permission to execute + .. function:: isfifo(path) -> Bool + :: + + isfifo(path) -> Bool + Returns ``true`` if ``path`` is a FIFO, ``false`` otherwise. + .. function:: isfile(path) -> Bool + :: + + isfile(path) -> Bool + Returns ``true`` if ``path`` is a regular file, ``false`` otherwise. + .. function:: islink(path) -> Bool + :: + + islink(path) -> Bool + Returns ``true`` if ``path`` is a symbolic link, ``false`` otherwise. + .. function:: ismount(path) -> Bool + :: + + ismount(path) -> Bool + Returns ``true`` if ``path`` is a mount point, ``false`` otherwise. + .. function:: ispath(path) -> Bool + :: + + ispath(path) -> Bool + Returns ``true`` if ``path`` is a valid filesystem path, ``false`` otherwise. + .. function:: isreadable(path) -> Bool - Returns ``true`` if the current user has permission to read ``path``, - ``false`` otherwise. + :: + + isreadable(path) -> Bool + + Returns ``true`` if the current user has permission to read + .. function:: issetgid(path) -> Bool + :: + + issetgid(path) -> Bool + Returns ``true`` if ``path`` has the setgid flag set, ``false`` otherwise. + .. function:: issetuid(path) -> Bool + :: + + issetuid(path) -> Bool + Returns ``true`` if ``path`` has the setuid flag set, ``false`` otherwise. + .. function:: issocket(path) -> Bool + :: + + issocket(path) -> Bool + Returns ``true`` if ``path`` is a socket, ``false`` otherwise. + .. function:: issticky(path) -> Bool + :: + + issticky(path) -> Bool + Returns ``true`` if ``path`` has the sticky bit set, ``false`` otherwise. + .. function:: iswritable(path) -> Bool - Returns ``true`` if the current user has permission to write to ``path``, - ``false`` otherwise. + :: + + iswritable(path) -> Bool + + Returns ``true`` if the current user has permission to write to + .. function:: homedir() -> AbstractString + :: + + homedir() -> AbstractString + Return the current user's home directory. + .. function:: dirname(path::AbstractString) -> AbstractString + :: + + dirname(path::AbstractString) -> AbstractString + Get the directory part of a path. + .. function:: basename(path::AbstractString) -> AbstractString + :: + + basename(path::AbstractString) -> AbstractString + Get the file name part of a path. + .. function:: @__FILE__() -> AbstractString - ``@__FILE__`` expands to a string with the absolute path and file name of the script being run. - Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e ``. + :: + + @__FILE__() -> AbstractString + + name of the script being run. Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e ``. + .. function:: isabspath(path::AbstractString) -> Bool + :: + + isabspath(path::AbstractString) -> Bool + Determines whether a path is absolute (begins at the root directory). + .. function:: isdirpath(path::AbstractString) -> Bool + :: + + isdirpath(path::AbstractString) -> Bool + Determines whether a path refers to a directory (for example, ends with a path separator). + .. function:: joinpath(parts...) -> AbstractString - Join path components into a full path. If some argument is an absolute - path, then prior components are dropped. + :: + + joinpath(parts...) -> AbstractString + + Join path components into a full path. If some argument is an absolute path, then prior components are dropped. + .. function:: abspath(path::AbstractString) -> AbstractString - Convert a path to an absolute path by adding the current directory if - necessary. + :: + + abspath(path::AbstractString) -> AbstractString + + Convert a path to an absolute path by adding the current directory if necessary. + .. function:: normpath(path::AbstractString) -> AbstractString - Normalize a path, removing "." and ".." entries. + :: + + normpath(path::AbstractString) -> AbstractString + + Normalize a path, removing ``.`` and ``..`` entries. + .. function:: realpath(path::AbstractString) -> AbstractString - Canonicalize a path by expanding symbolic links and removing "." and ".." entries. + :: + + realpath(path::AbstractString) -> AbstractString + + Canonicalize a path by expanding symbolic links and removing ``.`` and ``..`` entries. + .. function:: relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - Return a relative filepath to path either from the current directory or from an optional - start directory. - This is a path computation: the filesystem is not accessed to confirm the existence or - nature of path or startpath. + :: + + relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString + + Return a relative filepath to path either from the current directory or from an optional start directory. This is a path computation: the filesystem is not accessed to confirm the existence or nature of path or startpath. + .. function:: expanduser(path::AbstractString) -> AbstractString - On Unix systems, replace a tilde character at the start of a path with the - current user's home directory. + :: + + expanduser(path::AbstractString) -> AbstractString + + On Unix systems, replace a tilde character at the start of a path with the current user's home directory. + .. function:: splitdir(path::AbstractString) -> (AbstractString,AbstractString) + :: + + splitdir(path::AbstractString) -> (AbstractString, AbstractString) + Split a path into a tuple of the directory name and file name. + .. function:: splitdrive(path::AbstractString) -> (AbstractString,AbstractString) - On Windows, split a path into the drive letter part and the path part. On Unix - systems, the first component is always the empty string. + :: + + splitdrive(path::AbstractString) -> (AbstractString, AbstractString) + + On Windows, split a path into the drive letter part and the path part. On Unix systems, the first component is always the empty string. + .. function:: splitext(path::AbstractString) -> (AbstractString,AbstractString) - If the last component of a path contains a dot, split the path into everything - before the dot and everything including and after the dot. Otherwise, return - a tuple of the argument unmodified and the empty string. + :: + + splitext(path::AbstractString) -> (AbstractString, AbstractString) + + If the last component of a path contains a dot, split the path into everything before the dot and everything including and after the dot. Otherwise, return a tuple of the argument unmodified and the empty string. + + diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index e7c32ec862adf..26bb221bd7cbe 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -21,423 +21,744 @@ General I/O .. function:: open(file_name, [read, write, create, truncate, append]) -> IOStream - Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + :: + + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + .. function:: open(file_name, [mode]) -> IOStream - Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: - - ==== ================================= - r read - r+ read, write - w write, create, truncate - w+ read, write, create, truncate - a write, create, append - a+ read, write, create, append - ==== ================================= - + :: + + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + .. function:: open(f::function, args...) + :: + + open(f::function, args...) + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - - **Example**: ``open(readall, "file.txt")`` + .. function:: IOBuffer() -> IOBuffer - Create an in-memory I/O stream. + :: + + IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer(size::Int) - Create a fixed size IOBuffer. The buffer will not grow dynamically. + :: + + IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer(string) - Create a read-only IOBuffer on the data underlying the given string + :: + + IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer([data,],[readable,writable,[maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, - they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable - but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + :: + + IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: takebuf_array(b::IOBuffer) + :: + + takebuf_array(b::IOBuffer) + Obtain the contents of an ``IOBuffer`` as an array, without copying. Afterwards, the IOBuffer is reset to its initial state. + .. function:: takebuf_string(b::IOBuffer) + :: + + takebuf_string(b::IOBuffer) + Obtain the contents of an ``IOBuffer`` as a string, without copying. Afterwards, the IOBuffer is reset to its initial state. + .. function:: fdio([name::AbstractString, ]fd::Integer[, own::Bool]) -> IOStream - Create an ``IOStream`` object from an integer file descriptor. If ``own`` is true, closing this object will close the underlying descriptor. By default, an ``IOStream`` is closed when it is garbage collected. ``name`` allows you to associate the descriptor with a named file. + :: + + fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + + Create an ``IOStream`` object from an integer file descriptor. If descriptor. By default, an ``IOStream`` is closed when it is garbage collected. ``name`` allows you to associate the descriptor with a named file. + .. function:: flush(stream) + :: + + flush(stream) + Commit all currently buffered writes to the given stream. + .. function:: close(stream) + :: + + close(stream) + Close an I/O stream. Performs a ``flush`` first. + .. function:: write(stream, x) + :: + + write(stream, x) + Write the canonical binary representation of a value to the given stream. + .. function:: read(stream, type) - Read a value of the given type from a stream, in canonical binary representation. + :: + + read(stream, type, dims) + + Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. + .. function:: read(stream, type, dims) + :: + + read(stream, type, dims) + Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. + .. function:: read!(stream, array::Array) + :: + + read!(stream, array::Array) + Read binary data from a stream, filling in the argument ``array``. + .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - Read at most ``nb`` bytes from the stream into ``b``, returning the - number of bytes read (increasing the size of ``b`` as needed). + :: + + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + + Read at most ``nb`` bytes from the stream into ``b``, returning the number of bytes read (increasing the size of ``b`` as needed). + .. function:: readbytes(stream, nb=typemax(Int)) + :: + + readbytes(stream, nb=typemax(Int)) + Read at most ``nb`` bytes from the stream, returning a - ``Vector{UInt8}`` of the bytes read. + .. function:: position(s) + :: + + position(s) + Get the current position of a stream. + .. function:: seek(s, pos) + :: + + seek(s, pos) + Seek a stream to the given position. + .. function:: seekstart(s) + :: + + seekstart(s) + Seek a stream to its beginning. + .. function:: seekend(s) + :: + + seekend(s) + Seek a stream to its end. + .. function:: skip(s, offset) + :: + + skip(s, offset) + Seek a stream relative to the current position. + .. function:: mark(s) - Add a mark at the current position of stream ``s``. Returns the marked position. - - See also :func:`unmark`, :func:`reset`, :func:`ismarked` + :: + + mark(s) + + Add a mark at the current position of stream ``s``. Returns the marked position. See also ``unmark()``, ``reset()``, ``ismarked()`` + .. function:: unmark(s) - Remove a mark from stream ``s``. - Returns ``true`` if the stream was marked, ``false`` otherwise. - - See also :func:`mark`, :func:`reset`, :func:`ismarked` + :: + + unmark(s) + + Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. See also ``mark()``, ``reset()``, ``ismarked()`` + .. function:: reset(s) - Reset a stream ``s`` to a previously marked position, and remove the mark. - Returns the previously marked position. - Throws an error if the stream is not marked. - - See also :func:`mark`, :func:`unmark`, :func:`ismarked` + :: + + reset(s) + + Reset a stream ``s`` to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked. See also ``mark()``, ``unmark()``, ``ismarked()`` + .. function:: ismarked(s) - Returns true if stream ``s`` is marked. - - See also :func:`mark`, :func:`unmark`, :func:`reset` + :: + + ismarked(s) + + Returns true if stream ``s`` is marked. See also ``mark()``, ``unmark()``, ``reset()`` + .. function:: eof(stream) -> Bool - Tests whether an I/O stream is at end-of-file. If the stream is not yet - exhausted, this function will block to wait for more data if necessary, and - then return ``false``. Therefore it is always safe to read one byte after - seeing ``eof`` return ``false``. ``eof`` will return ``false`` as long - as buffered data is still available, even if the remote end of a - connection is closed. + :: + + eof(stream) -> Bool + + Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return ``false``. Therefore it is always safe to read one byte after seeing ``eof`` return ``false``. ``eof`` will return ``false`` as long as buffered data is still available, even if the remote end of a connection is closed. + .. function:: isreadonly(stream) -> Bool + :: + + isreadonly(stream) -> Bool + Determine whether a stream is read-only. + .. function:: isopen(stream) -> Bool - Determine whether a stream is open (i.e. has not been closed yet). - If the connection has been closed remotely (in case of e.g. a socket), - ``isopen`` will return ``false`` even though buffered data may still be - available. Use ``eof`` to check if necessary. + :: + + isopen(stream) -> Bool + + Determine whether a stream is open (i.e. has not been closed yet). If the connection has been closed remotely (in case of e.g. a socket), ``isopen`` will return ``false`` even though buffered data may still be available. Use ``eof`` to check if necessary. + .. function:: serialize(stream, value) - Write an arbitrary value to a stream in an opaque format, such that it can - be read back by ``deserialize``. The read-back value will be as identical as - possible to the original. In general, this process will not work if the - reading and writing are done by different versions of Julia, or - an instance of Julia with a different system image. + :: + + serialize(stream, value) + + Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``. The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. + .. function:: deserialize(stream) + :: + + deserialize(stream) + Read a value written by ``serialize``. + .. function:: print_escaped(io, str::AbstractString, esc::AbstractString) + :: + + print_escaped(io, str::AbstractString, esc::AbstractString) + General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). + .. function:: print_unescaped(io, s::AbstractString) - General unescaping of traditional C and Unicode escape sequences. Reverse of :func:`print_escaped`. + :: + + print_unescaped(io, s::AbstractString) + + General unescaping of traditional C and Unicode escape sequences. Reverse of ``print_escaped()``. + .. function:: print_joined(io, items, delim, [last]) + :: + + print_joined(io, items, delim[, last]) + Print elements of ``items`` to ``io`` with ``delim`` between them. If ``last`` is specified, it is used as the final delimiter instead of ``delim``. + .. function:: print_shortest(io, x) + :: + + print_shortest(io, x) + Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number ``x``, ensuring that it would parse to the exact same number. + .. function:: fd(stream) - Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous `File`'s and `IOStream`'s - not to any of the asynchronous streams. + :: + + fd(stream) + + Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. + .. function:: redirect_stdout() - Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) - representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The - wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be - replaced elsewhere. + :: + + redirect_stdout(stream) + + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + .. function:: redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that `stream` must be a TTY, a Pipe or a - TcpSocket. + :: + + redirect_stdout(stream) + + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + .. function:: redirect_stderr([stream]) + :: + + redirect_stderr([stream]) + Like redirect_stdout, but for STDERR + .. function:: redirect_stdin([stream]) - Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read - from STDIN, may be written to wr. + :: + + redirect_stdin([stream]) + + Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read from STDIN, may be written to wr. + .. function:: readchomp(x) + :: + + readchomp(x) + Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). + .. function:: truncate(file,n) - Resize the file or buffer given by the first argument to exactly `n` bytes, filling previously unallocated space with '\\0' - if the file or buffer is grown + :: + + truncate(file, n) + + Resize the file or buffer given by the first argument to exactly file or buffer is grown + .. function:: skipchars(stream, predicate; linecomment::Char) - Advance the stream until before the first character for which ``predicate`` returns false. For example ``skipchars(stream, isspace)`` will skip all whitespace. If keyword argument ``linecomment`` is specified, characters from that character through the end of a line will also be skipped. + :: + + skipchars(stream, predicate; linecomment::Char) + + Advance the stream until before the first character for which isspace)` will skip all whitespace. If keyword argument through the end of a line will also be skipped. + .. function:: countlines(io,[eol::Char]) - Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than '\\n' are supported by passing them as the second argument. + :: + + countlines(io[, eol::Char]) + + Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first argument. EOL markers other than '\n' are supported by passing them as the second argument. + .. function:: PipeBuffer() - An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. + :: + + PipeBuffer(data::Vector{UInt8}[, maxsize]) + + Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. + .. function:: PipeBuffer(data::Vector{UInt8},[maxsize]) + :: + + PipeBuffer(data::Vector{UInt8}[, maxsize]) + Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. + .. function:: readavailable(stream) + :: + + readavailable(stream) + Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``. - + Text I/O -------- .. function:: show(x) - Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. - The representation used by ``show`` generally includes Julia-specific formatting and type information. + :: + + show(x) + + Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. The representation used by ``show`` generally includes Julia-specific formatting and type information. + .. function:: showcompact(x) - Show a more compact representation of a value. This is used for printing - array elements. If a new type has a different compact representation, it - should overload ``showcompact(io, x)`` where the first argument is a stream. + :: + + showcompact(x) + + Show a more compact representation of a value. This is used for printing array elements. If a new type has a different compact representation, it should overload ``showcompact(io, x)`` where the first argument is a stream. + .. function:: showall(x) + :: + + showall(x) + Similar to ``show``, except shows all elements of arrays. + .. function:: summary(x) - Return a string giving a brief description of a value. By default returns - ``string(typeof(x))``. For arrays, returns strings like "2x2 Float64 Array". + :: + + summary(x) + + Return a string giving a brief description of a value. By default returns ``string(typeof(x))``. For arrays, returns strings like + .. function:: print(x) - Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call ``show``. - The representation used by ``print`` includes minimal formatting and tries to avoid Julia-specific details. + :: + + print(x) + + Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call formatting and tries to avoid Julia-specific details. + .. function:: println(x) - Print (using :func:`print`) ``x`` followed by a newline. + :: + + println(x) + + Print (using ``print()``) ``x`` followed by a newline. + .. function:: print_with_color(color::Symbol, [io], strings...) - Print strings in a color specified as a symbol, for example ``:red`` or ``:blue``. + :: + + print_with_color(color::Symbol[, io], strings...) + + Print strings in a color specified as a symbol, for example + .. function:: info(msg) + :: + + info(msg) + Display an informational message. + .. function:: warn(msg) + :: + + warn(msg) + Display a warning. + .. function:: @printf([io::IOStream], "%Fmt", args...) + :: + + @printf([io::IOStream], "%Fmt", args...) + Print arg(s) using C ``printf()`` style format specification string. Optionally, an IOStream may be passed as the first argument to redirect output. + .. function:: @sprintf("%Fmt", args...) + :: + + @sprintf("%Fmt", args...) + Return ``@printf`` formatted output as string. + .. function:: sprint(f::Function, args...) - Call the given function with an I/O stream and the supplied extra arguments. - Everything written to this I/O stream is returned as a string. + :: + + sprint(f::Function, args...) + + Call the given function with an I/O stream and the supplied extra arguments. Everything written to this I/O stream is returned as a string. + .. function:: showerror(io, e) + :: + + showerror(io, e) + Show a descriptive representation of an exception object. + .. function:: dump(x) + :: + + dump(x) + Show all user-visible structure of a value. + .. function:: xdump(x) + :: + + xdump(x) + Show all structure of a value, including all fields of objects. + .. function:: readall(stream::IO) - Read the entire contents of an I/O stream as a string. + :: + + readall(filename::AbstractString) + + Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. + .. function:: readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. - Equivalent to ``open(readall, filename)``. + :: + + readall(filename::AbstractString) + + Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. + .. function:: readline(stream=STDIN) - Read a single line of text, including a trailing newline character (if one is reached before the end of the input), from the given ``stream`` (defaults to ``STDIN``), + :: + + readline(stream=STDIN) + + Read a single line of text, including a trailing newline character + .. function:: readuntil(stream, delim) + :: + + readuntil(stream, delim) + Read a string, up to and including the given delimiter byte. + .. function:: readlines(stream) + :: + + readlines(stream) + Read all lines as an array. + .. function:: eachline(stream) + :: + + eachline(stream) + Create an iterable object that will yield each line from a stream. + .. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. - - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. - - Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. - - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. - - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. - - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. - - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. - - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. + :: + + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, delim::Char, eol::Char; options...) - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + :: + + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, delim::Char, T::Type; options...) - The end of line delimiter is taken as ``\n``. + :: + + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, delim::Char; options...) - The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + :: + + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, T::Type; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + :: + + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) + :: + + readdlm(source; options...) + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: writedlm(f, A, delim='\\t') - Write ``A`` (a vector, matrix or an iterable collection of iterable rows) as text to ``f`` (either a filename string or an ``IO`` stream) using the given delimeter ``delim`` (which defaults to tab, but can be any printable Julia object, typically a ``Char`` or ``AbstractString``). - - For example, two vectors ``x`` and ``y`` of the same length can - be written as two columns of tab-delimited text to ``f`` by - either ``writedlm(f, [x y])`` or by ``writedlm(f, zip(x, y))``. + :: + + writedlm(f, A, delim='\t') + + Write ``A`` (a vector, matrix or an iterable collection of iterable rows) as text to ``f`` (either a filename string or an ``IO`` stream) using the given delimeter ``delim`` (which defaults to tab, but can be any printable Julia object, typically a ``Char`` or For example, two vectors ``x`` and ``y`` of the same length can be written as two columns of tab-delimited text to ``f`` by either + .. function:: readcsv(source, [T::Type]; options...) + :: + + readcsv(source, [T::Type]; options...) + Equivalent to ``readdlm`` with ``delim`` set to comma. + .. function:: writecsv(filename, A) + :: + + writecsv(filename, A) + Equivalent to ``writedlm`` with ``delim`` set to comma. + .. function:: Base64EncodePipe(ostream) - Returns a new write-only I/O stream, which converts any bytes written - to it into base64-encoded ASCII bytes written to ``ostream``. Calling - ``close`` on the ``Base64Pipe`` stream is necessary to complete the - encoding (but does not close ``ostream``). + :: + + Base64EncodePipe(ostream) + + Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to necessary to complete the encoding (but does not close + .. function:: Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded data - read from ``istream``. + :: + + Base64DecodePipe(istream) + + Returns a new read-only I/O stream, which decodes base64-encoded data read from ``istream``. + .. function:: base64encode(writefunc, args...) - base64encode(args...) - Given a ``write``-like function ``writefunc``, which takes an I/O - stream as its first argument, ``base64(writefunc, args...)`` - calls ``writefunc`` to write ``args...`` to a base64-encoded string, - and returns the string. ``base64(args...)`` is equivalent to - ``base64(write, args...)``: it converts its arguments into bytes - using the standard ``write`` functions and returns the base64-encoded - string. + :: + + base64encode(writefunc, args...) + + Given a ``write``-like function ``writefunc``, which takes an I/O stream as its first argument, ``base64(writefunc, args...)`` calls returns the string. ``base64(args...)`` is equivalent to using the standard ``write`` functions and returns the base64-encoded string. + .. function:: base64decode(string) - Decodes the base64-encoded ``string`` and returns a ``Vector{UInt8}`` - of the decoded bytes. + :: + + base64decode(string) + + Decodes the base64-encoded ``string`` and returns a + Multimedia I/O -------------- @@ -461,98 +782,67 @@ displays may be enabled by loading external modules or by using graphical Julia environments (such as the IPython-based IJulia notebook). .. function:: display(x) - display(d::Display, x) - display(mime, x) - display(d::Display, mime, x) - - Display ``x`` using the topmost applicable display in the display stack, - typically using the richest supported multimedia output for ``x``, with - plain-text ``STDOUT`` output as a fallback. The ``display(d, x)`` variant - attempts to display ``x`` on the given display ``d`` only, throwing - a ``MethodError`` if ``d`` cannot display objects of this type. - - There are also two variants with a ``mime`` argument (a MIME type - string, such as ``"image/png"``), which attempt to display ``x`` using the - requested MIME type *only*, throwing a ``MethodError`` if this type - is not supported by either the display(s) or by ``x``. With these - variants, one can also supply the "raw" data in the requested MIME - type by passing ``x::AbstractString`` (for MIME types with text-based storage, - such as text/html or application/postscript) or ``x::Vector{UInt8}`` - (for binary MIME types). + + :: + + display(x) + + Display ``x`` using the topmost applicable display in the display stack, typically using the richest supported multimedia output for display ``d`` only, throwing a ``MethodError`` if ``d`` cannot display objects of this type. There are also two variants with a ``mime`` argument (a MIME type string, such as ``image/png``), which attempt to display ``x`` using the requested MIME type *only*, throwing a ``MethodError`` if this type is not supported by either the display(s) or by ``x``. With these variants, one can also supply the ``raw`` data in the requested MIME type by passing ``x::AbstractString`` (for MIME types with text-based storage, such as text/html or application/postscript) or ``x::Vector{UInt8}`` (for binary MIME types). + .. function:: redisplay(x) - redisplay(d::Display, x) - redisplay(mime, x) - redisplay(d::Display, mime, x) - By default, the ``redisplay`` functions simply call ``display``. However, - some display backends may override ``redisplay`` to modify an existing - display of ``x`` (if any). Using ``redisplay`` is also a hint to the - backend that ``x`` may be redisplayed several times, and the backend - may choose to defer the display until (for example) the next interactive - prompt. + :: + + redisplay(x) + + By default, the ``redisplay`` functions simply call ``display``. However, some display backends may override ``redisplay`` to modify an existing display of ``x`` (if any). Using ``redisplay`` is also a hint to the backend that ``x`` may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt. + .. function:: displayable(mime) -> Bool - displayable(d::Display, mime) -> Bool - Returns a boolean value indicating whether the given ``mime`` type (string) - is displayable by any of the displays in the current display stack, or - specifically by the display ``d`` in the second variant. + :: + + displayable(mime) -> Bool + + Returns a boolean value indicating whether the given ``mime`` type display stack, or specifically by the display ``d`` in the second variant. + .. function:: writemime(stream, mime, x) - The ``display`` functions ultimately call ``writemime`` in order to - write an object ``x`` as a given ``mime`` type to a given I/O - ``stream`` (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - ``T``, it is only necessary to define a new ``writemime`` method for - ``T``, via: ``writemime(stream, ::MIME"mime", x::T) = ...``, where - ``mime`` is a MIME-type string and the function body calls - ``write`` (or similar) to write that representation of ``x`` to - ``stream``. (Note that the ``MIME""`` notation only supports literal - strings; to construct ``MIME`` types in a more flexible manner use - ``MIME{symbol("")}``.) - - For example, if you define a ``MyImage`` type and know how to write - it to a PNG file, you could define a function ``writemime(stream, - ::MIME"image/png", x::MyImage) = ...``` to allow your images to - be displayed on any PNG-capable ``Display`` (such as IJulia). - As usual, be sure to ``import Base.writemime`` in order to add - new methods to the built-in Julia function ``writemime``. - - Technically, the ``MIME"mime"`` macro defines a singleton type for - the given ``mime`` string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. + :: + + writemime(stream, mime, x) + + The ``display`` functions ultimately call ``writemime`` in order to write an object ``x`` as a given ``mime`` type to a given I/O provide a rich multimedia representation of a user-defined type for ``T``, via: ``writemime(stream, ::MIME``mime``, x::T) = ...``, where ``mime`` is a MIME-type string and the function body calls literal strings; to construct ``MIME`` types in a more flexible manner use ``MIME{symbol(``)}``.) For example, if you define a ``MyImage`` type and know how to write it to a PNG file, you could define a function ``writemime(stream, be displayed on any PNG-capable `Display`` (such as IJulia). As usual, be sure to ``import Base.writemime`` in order to add new methods to the built-in Julia function ``writemime``. Technically, the ``MIME``mime`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. + .. function:: mimewritable(mime, x) - Returns a boolean value indicating whether or not the object ``x`` - can be written as the given ``mime`` type. (By default, this - is determined automatically by the existence of the corresponding - ``writemime`` function for ``typeof(x)``.) + :: + + mimewritable(mime, x) + + Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding + .. function:: reprmime(mime, x) - Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the - representation of ``x`` in the requested ``mime`` type, as written - by ``writemime`` (throwing a ``MethodError`` if no appropriate - ``writemime`` is available). An ``AbstractString`` is returned for MIME - types with textual representations (such as ``"text/html"`` or - ``"application/postscript"``), whereas binary data is returned as - ``Vector{UInt8}``. (The function ``istext(mime)`` returns whether - or not Julia treats a given ``mime`` type as text.) - - As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) - or a ``Vector{UInt8}`` (for binary MIME types), the ``reprmime`` function - assumes that ``x`` is already in the requested ``mime`` format and - simply returns ``x``. + :: + + reprmime(mime, x) + + Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the representation of ``x`` in the requested ``mime`` type, as written by ``writemime`` (throwing a ``MethodError`` if no appropriate MIME types with textual representations (such as ``text/html`` or ``application/postscript``), whereas binary data is returned as ``Vector{UInt8}``. (The function ``istext(mime)`` returns whether or not Julia treats a given ``mime`` type as text.) As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) or a ``Vector{UInt8}`` (for binary MIME types), the requested ``mime`` format and simply returns ``x``. + .. function:: stringmime(mime, x) - Returns an ``AbstractString`` containing the representation of ``x`` in the - requested ``mime`` type. This is similar to ``reprmime`` except - that binary data is base64-encoded as an ASCII string. + :: + + stringmime(mime, x) + + Returns an ``AbstractString`` containing the representation of string. + As mentioned above, one can also define new display backends. For example, a module that can display PNG images in a window can register @@ -582,184 +872,279 @@ stack with: .. function:: pushdisplay(d::Display) - Pushes a new display ``d`` on top of the global display-backend - stack. Calling ``display(x)`` or ``display(mime, x)`` will display - ``x`` on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a ``MethodError``). + :: + + pushdisplay(d::Display) + + Pushes a new display ``d`` on top of the global display-backend stack. Calling ``display(x)`` or ``display(mime, x)`` will display topmost backend that does not throw a ``MethodError``). + .. function:: popdisplay() - popdisplay(d::Display) - Pop the topmost backend off of the display-backend stack, or the - topmost copy of ``d`` in the second variant. + :: + + popdisplay() + + Pop the topmost backend off of the display-backend stack, or the topmost copy of ``d`` in the second variant. + .. function:: TextDisplay(stream) - Returns a ``TextDisplay <: Display``, which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same - as the way an object is printed in the Julia REPL.) + :: + + TextDisplay(stream) + + Returns a ``TextDisplay <: Display``, which can display any object as the text/plain MIME type (only), writing the text representation to the given I/O stream. (The text representation is the same as the way an object is printed in the Julia REPL.) + .. function:: istext(m::MIME) + :: + + istext(m::MIME) + Determine whether a MIME type is text data. + Memory-mapped I/O ----------------- .. function:: mmap_array(type, dims, stream, [offset]) - Create an ``Array`` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory. - - The type determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). - - ``dims`` is a tuple specifying the size of the array. - - The file is passed via the stream argument. When you initialize the stream, use ``"r"`` for a "read-only" array, and ``"w+"`` to create a new array used to write values to disk. - - Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position. - - For example, the following code:: - - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open("/tmp/mmap.bin", "w+") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) - - # Test by reading it back in - s = open("/tmp/mmap.bin") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) - - creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. - - A more portable file would need to encode the word size---32 bit or 64 bit---and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). + :: + + mmap_array(type, dims, stream[, offset]) + + Create an ``Array`` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory. The type determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). The file is passed via the stream argument. When you initialize the stream, use ``r`` for a ``read-only`` array, and ``w+`` to create a new array used to write values to disk. Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position. For example, the following code: creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. A more portable file would need to encode the word size–-32 bit or 64 bit–-and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 + .. function:: mmap_bitarray([type,] dims, stream, [offset]) - Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as :func:`mmap_array`, but the byte representation is different. The ``type`` parameter is optional, and must be ``Bool`` if given. - - **Example**: ``B = mmap_bitarray((25,30000), s)`` - - This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. + :: + + mmap_bitarray([type], dims, stream[, offset]) + + Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as ``mmap_array()``, but the byte representation is different. The ``type`` parameter is optional, and must be ``Bool`` if given. This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. + .. function:: msync(array) - Forces synchronization between the in-memory version of a memory-mapped ``Array`` or ``BitArray`` and the on-disk version. + :: + + msync(ptr, len[, flags]) + + Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + Network I/O ----------- .. function:: connect([host],port) -> TcpSocket - Connect to the host ``host`` on port ``port`` + :: + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. + .. function:: connect(path) -> Pipe - Connect to the Named Pipe/Domain Socket at ``path`` + :: + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. + .. function:: listen([addr,]port) -> TcpServer - Listen on port on the address specified by ``addr``. By default this listens on localhost only. - To listen on all interfaces pass, ``IPv4(0)`` or ``IPv6(0)`` as appropriate. + :: + + listen(path) -> PipeServer + + Listens on/Creates a Named Pipe/Domain Socket + .. function:: listen(path) -> PipeServer + :: + + listen(path) -> PipeServer + Listens on/Creates a Named Pipe/Domain Socket + .. function:: getaddrinfo(host) + :: + + getaddrinfo(host) + Gets the IP address of the ``host`` (may have to do a DNS lookup) + .. function:: parseip(addr) + :: + + parseip(addr) + Parse a string specifying an IPv4 or IPv6 ip address. + .. function:: IPv4(host::Integer) -> IPv4 + :: + + IPv4(host::Integer) -> IPv4 + Returns IPv4 object from ip address formatted as Integer + .. function:: IPv6(host::Integer) -> IPv6 + :: + + IPv6(host::Integer) -> IPv6 + Returns IPv6 object from ip address formatted as Integer + .. function:: nb_available(stream) + :: + + nb_available(stream) + Returns the number of bytes available for reading before a read from this stream or buffer will block. + .. function:: accept(server[,client]) - Accepts a connection on the given server and returns a connection to the client. An uninitialized client - stream may be provided, in which case it will be used instead of creating a new stream. + :: + + accept(server[, client]) + + Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. + .. function:: listenany(port_hint) -> (UInt16,TcpServer) - Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server - was created on and the server itself. + :: + + listenany(port_hint) -> (UInt16, TcpServer) + + Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server was created on and the server itself. + .. function:: watch_file(cb=false, s; poll=false) - Watch file or directory ``s`` and run callback ``cb`` when ``s`` is modified. The ``poll`` parameter specifies whether to use file system event monitoring or polling. The callback function ``cb`` should accept 3 arguments: ``(filename, events, status)`` where ``filename`` is the name of file that was modified, ``events`` is an object with boolean fields ``changed`` and ``renamed`` when using file system event monitoring, or ``readable`` and ``writable`` when using polling, and ``status`` is always 0. Pass ``false`` for ``cb`` to not use a callback function. + :: + + watch_file(cb=false, s; poll=false) + + Watch file or directory ``s`` and run callback ``cb`` when ``s`` is modified. The ``poll`` parameter specifies whether to use file system event monitoring or polling. The callback function ``cb`` should accept 3 arguments: ``(filename, events, status)`` where an object with boolean fields ``changed`` and ``renamed`` when using file system event monitoring, or ``readable`` and + .. function:: poll_fd(fd, seconds::Real; readable=false, writable=false) - Poll a file descriptor fd for changes in the read or write availability and with a timeout given by the second argument. - If the timeout is not needed, use ``wait(fd)`` instead. The keyword arguments determine which of read and/or write status - should be monitored and at least one of them needs to be set to true. - The returned value is an object with boolean fields ``readable``, ``writable``, and - ``timedout``, giving the result of the polling. + :: + + poll_fd(fd, seconds::Real; readable=false, writable=false) + + Poll a file descriptor fd for changes in the read or write availability and with a timeout given by the second argument. If the timeout is not needed, use ``wait(fd)`` instead. The keyword arguments determine which of read and/or write status should be monitored and at least one of them needs to be set to true. The returned value is an object with boolean fields ``readable``, + .. function:: poll_file(s, interval_seconds::Real, seconds::Real) - Monitor a file for changes by polling every `interval_seconds` seconds for `seconds` seconds. A return value of true indicates - the file changed, a return value of false indicates a timeout. + :: + + poll_file(s, interval_seconds::Real, seconds::Real) + + Monitor a file for changes by polling every *interval_seconds* seconds for *seconds* seconds. A return value of true indicates the file changed, a return value of false indicates a timeout. + .. function:: bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - Bind ``socket`` to the given ``host:port``. Note that `0.0.0.0` will listen on all devices. + :: + + bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + + Bind ``socket`` to the given ``host:port``. Note that *0.0.0.0* will listen on all devices. + .. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) + :: + + send(socket::UDPSocket, host::IPv4, port::Integer, msg) + Send ``msg`` over ``socket to ``host:port``. + .. function:: recv(socket::UDPSocket) + :: + + recv(socket::UDPSocket) + Read a UDP packet from the specified socket, and return the bytes received. This call blocks. + .. function:: recvfrom(socket::UDPSocket) -> (address, data) - Read a UDP packet from the specified socket, returning a tuple of (address, data), where address will be either IPv4 or IPv6 as appropriate. + :: + + recvfrom(socket::UDPSocket) -> (address, data) + + Read a UDP packet from the specified socket, returning a tuple of appropriate. + .. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + :: + + setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + Set UDP socket options. ``multicast_loop``: loopback for multicast packets (default: true). ``multicast_ttl``: TTL for multicast packets. ``enable_broadcast``: flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). ``ttl``: Time-to-live of packets sent on the socket. + .. function:: ntoh(x) - Converts the endianness of a value from Network byte order (big-endian) to - that used by the Host. + :: + + ntoh(x) + + Converts the endianness of a value from Network byte order (big- endian) to that used by the Host. + .. function:: hton(x) - Converts the endianness of a value from that used by the Host to Network - byte order (big-endian). + :: + + hton(x) + + Converts the endianness of a value from that used by the Host to Network byte order (big-endian). + .. function:: ltoh(x) - Converts the endianness of a value from Little-endian to that used by the - Host. + :: + + ltoh(x) + + Converts the endianness of a value from Little-endian to that used by the Host. + .. function:: htol(x) - Converts the endianness of a value from that used by the Host to - Little-endian. + :: + + htol(x) + + Converts the endianness of a value from that used by the Host to Little-endian. + .. data:: ENDIAN_BOM diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index 12d8a6f33d562..623436fc64773 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -6,64 +6,111 @@ .. function:: malloc(size::Integer) -> Ptr{Void} + :: + + malloc(size::Integer) -> Ptr{Void} + Call ``malloc`` from the C standard library. + .. function:: calloc(num::Integer, size::Integer) -> Ptr{Void} + :: + + calloc(num::Integer, size::Integer) -> Ptr{Void} + Call ``calloc`` from the C standard library. + .. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void} - Call ``realloc`` from the C standard library. - - See warning in the documentation for ``free`` regarding only using this on memory originally obtained from ``malloc``. + :: + + realloc(addr::Ptr, size::Integer) -> Ptr{Void} + + Call ``realloc`` from the C standard library. See warning in the documentation for ``free`` regarding only using this on memory originally obtained from ``malloc``. + .. function:: free(addr::Ptr) - Call ``free`` from the C standard library. Only use this on memory obtained from ``malloc``, - not on pointers retrieved from other C libraries. - ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library, - to avoid assertion failures if multiple ``libc`` libraries exist on the system. + :: + + free(addr::Ptr) + + Call ``free`` from the C standard library. Only use this on memory obtained from ``malloc``, not on pointers retrieved from other C libraries. ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library, to avoid assertion failures if multiple ``libc`` libraries exist on the system. + .. function:: errno([code]) - Get the value of the C library's ``errno``. If an argument is specified, it is - used to set the value of ``errno``. - - The value of ``errno`` is only valid immediately after a ``ccall`` to a C - library routine that sets it. Specifically, you cannot call ``errno`` at the next - prompt in a REPL, because lots of code is executed between prompts. + :: + + errno([code]) + + Get the value of the C library's ``errno``. If an argument is specified, it is used to set the value of ``errno``. The value of ``errno`` is only valid immediately after a ``ccall`` to a C library routine that sets it. Specifically, you cannot call executed between prompts. + .. function:: strerror(n) + :: + + strerror(n) + Convert a system call error code to a descriptive string + .. function:: time(t::TmStruct) + :: + + time(t::TmStruct) + Converts a ``TmStruct`` struct to a number of seconds since the epoch. + .. function:: strftime([format], time) - Convert time, given as a number of seconds since the epoch or a ``TmStruct``, to a formatted string using the given format. Supported formats are the same as those in the standard C library. + :: + + strftime([format], time) + + Convert time, given as a number of seconds since the epoch or a Supported formats are the same as those in the standard C library. + .. function:: strptime([format], timestr) - Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the ``isdst`` field should be filled in manually. Setting it to ``-1`` will tell the C library to use the current system settings to determine the timezone. + :: + + strptime([format], timestr) + + Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the will tell the C library to use the current system settings to determine the timezone. + .. function:: TmStruct([seconds]) - Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, ``year``, ``wday``, ``yday``, and ``isdst``. + :: + + TmStruct([seconds]) + + Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, + .. function:: flush_cstdio() - Flushes the C ``stdout`` and ``stderr`` streams (which may have been - written to by external C code). + :: + + flush_cstdio() + + Flushes the C ``stdout`` and ``stderr`` streams (which may have been written to by external C code). + .. function:: msync(ptr, len, [flags]) - Forces synchronization of the :func:`mmap`\ ped memory region from ``ptr`` to ``ptr+len``. Flags defaults to ``MS_SYNC``, but can be a combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. - - You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + :: + + msync(ptr, len[, flags]) + + Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + .. data:: MS_ASYNC @@ -79,8 +126,19 @@ .. function:: mmap(len, prot, flags, fd, offset) + :: + + mmap(len, prot, flags, fd, offset) + Low-level interface to the ``mmap`` system call. See the man page. + .. function:: munmap(pointer, len) - Low-level interface for unmapping memory (see the man page). With :func:`mmap_array` you do not need to call this directly; the memory is unmapped for you when the array goes out of scope. + :: + + munmap(pointer, len) + + Low-level interface for unmapping memory (see the man page). With is unmapped for you when the array goes out of scope. + + diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index 5620978db9d49..569944ebc789c 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -6,23 +6,21 @@ .. function:: dlopen(libfile::AbstractString [, flags::Integer]) - Load a shared library, returning an opaque handle. - - The optional flags argument is a bitwise-or of zero or more of - ``RTLD_LOCAL``, ``RTLD_GLOBAL``, ``RTLD_LAZY``, ``RTLD_NOW``, ``RTLD_NODELETE``, - ``RTLD_NOLOAD``, ``RTLD_DEEPBIND``, and ``RTLD_FIRST``. These are converted to - the corresponding flags of the POSIX (and/or GNU libc and/or MacOS) - dlopen command, if possible, or are ignored if the specified - functionality is not available on the current platform. The - default is ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL``. An important usage - of these flags, on POSIX platforms, is to specify - ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL`` in order for the library's - symbols to be available for usage in other shared libraries, in - situations where there are dependencies between shared libraries. + :: + + dlopen(libfile::AbstractString[, flags::Integer]) + + Load a shared library, returning an opaque handle. The optional flags argument is a bitwise-or of zero or more of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default is these flags, on POSIX platforms, is to specify symbols to be available for usage in other shared libraries, in situations where there are dependencies between shared libraries. + .. function:: dlopen_e(libfile::AbstractString [, flags::Integer]) - Similar to :func:`dlopen`, except returns a ``NULL`` pointer instead of raising errors. + :: + + dlopen_e(libfile::AbstractString[, flags::Integer]) + + Similar to ``dlopen()``, except returns a ``NULL`` pointer instead of raising errors. + .. data:: RTLD_DEEPBIND @@ -58,22 +56,39 @@ .. function:: dlsym(handle, sym) + :: + + dlsym(handle, sym) + Look up a symbol from a shared library handle, return callable function pointer on success. + .. function:: dlsym_e(handle, sym) + :: + + dlsym_e(handle, sym) + Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. + .. function:: dlclose(handle) + :: + + dlclose(handle) + Close shared library referenced by handle. + .. function:: find_library(names, locations) - Searches for the first library in ``names`` in the paths in the ``locations`` list, ``DL_LOAD_PATH``, or system - library paths (in that order) which can successfully be dlopen'd. On success, the return value will be one of - the names (potentially prefixed by one of the paths in locations). This string can be assigned to a ``global const`` - and used as the library name in future ``ccall``'s. On failure, it returns the empty string. + :: + + find_library(names, locations) + + Searches for the first library in ``names`` in the paths in the that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a + .. data:: DL_LOAD_PATH diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 1cc362630a066..081bf84f7e7f6 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -14,9 +14,13 @@ Standard Functions Linear algebra functions in Julia are largely implemented by calling functions from `LAPACK `_. Sparse factorizations call functions from `SuiteSparse `_. .. function:: *(A, B) - :noindex: - Matrix multiplication + :: + + *(s, t) + + Concatenate strings. The ``*`` operator is an alias to this function. + .. function:: \\(A, B) :noindex: @@ -26,545 +30,728 @@ Linear algebra functions in Julia are largely implemented by calling functions f When ``A`` is sparse, a similar polyalgorithm is used. For indefinite matrices, the LDLt factorization does not use pivoting during the numerical factorization and therefore the procedure can fail even for invertible matrices. .. function:: dot(x, y) - ⋅(x,y) + :: + + dot(x, y) + Compute the dot product. For complex vectors, the first vector is conjugated. + .. function:: vecdot(x, y) - For any iterable containers ``x`` and ``y`` (including arrays of - any dimension) of numbers (or any element type for which ``dot`` is - defined), compute the Euclidean dot product (the sum of - ``dot(x[i],y[i])``) as if they were vectors. + :: + + vecdot(x, y) + + For any iterable containers ``x`` and ``y`` (including arrays of any dimension) of numbers (or any element type for which ``dot`` is defined), compute the Euclidean dot product (the sum of + .. function:: cross(x, y) - ×(x,y) + :: + + cross(x, y) + Compute the cross product of two 3-vectors. + .. function:: factorize(A) - Compute a convenient factorization (including LU, Cholesky, Bunch-Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: ``A=factorize(A); x=A\\b; y=A\\C``. + :: + + factorize(A) + + Compute a convenient factorization (including LU, Cholesky, Bunch- Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: + .. function:: full(F) + :: + + full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. + + Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. .. function:: lu(A) -> L, U, p + :: + + lu(A) -> L, U, p + Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. + .. function:: lufact(A [,pivot=Val{true}]) -> F - Compute the LU factorization of ``A``. The return type of ``F`` depends on the type of ``A``. In most cases, if ``A`` is a subtype ``S`` of AbstractMatrix with an element type ``T``` supporting ``+``, ``-``, ``*`` and ``/`` the return type is ``LU{T,S{T}}``. If pivoting is chosen (default) the element type should also support ``abs`` and ``<``. When ``A`` is sparse and have element of type ``Float32``, ``Float64``, ``Complex{Float32}``, or ``Complex{Float64}`` the return type is ``UmfpackLU``. Some examples are shown in the table below. - - ======================= ========================= ======================================== - Type of input ``A`` Type of output ``F`` Relationship between ``F`` and ``A`` - ----------------------- ------------------------- ---------------------------------------- - :func:`Matrix` ``LU`` ``F[:L]*F[:U] == A[F[:p], :]`` - :func:`Tridiagonal` ``LU{T,Tridiagonal{T}}`` N/A - :func:`SparseMatrixCSC` ``UmfpackLU`` ``F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]`` - ======================= ========================= ======================================== - - The individual components of the factorization ``F`` can be accessed by indexing: - - =========== ======================================= ====== ======================== ============= - Component Description ``LU`` ``LU{T,Tridiagonal{T}}`` ``UmfpackLU`` - ----------- --------------------------------------- ------ ------------------------ ------------- - ``F[:L]`` ``L`` (lower triangular) part of ``LU`` ✓ ✓ - ``F[:U]`` ``U`` (upper triangular) part of ``LU`` ✓ ✓ - ``F[:p]`` (right) permutation ``Vector`` ✓ ✓ - ``F[:P]`` (right) permutation ``Matrix`` ✓ - ``F[:q]`` left permutation ``Vector`` ✓ - ``F[:Rs]`` ``Vector`` of scaling factors ✓ - ``F[:(:)]`` ``(L,U,p,q,Rs)`` components ✓ - =========== ======================================= ====== ======================== ============= - - ================== ====== ======================== ============= - Supported function ``LU`` ``LU{T,Tridiagonal{T}}`` ``UmfpackLU`` - ------------------ ------ ------------------------ ------------- - ``/`` ✓ - ``\`` ✓ ✓ ✓ - ``cond`` ✓ ✓ - ``det`` ✓ ✓ ✓ - ``logdet`` ✓ ✓ - ``logabsdet`` ✓ ✓ - ``size`` ✓ ✓ - ================== ====== ======================== ============= + :: + + lufact(A[, pivot=Val{true}]) -> F + + Compute the LU factorization of ``A``. The return type of ``F`` depends on the type of ``A``. In most cases, if ``A`` is a subtype pivoting is chosen (default) the element type should also support examples are shown in the table below. The individual components of the factorization ``F`` can be accessed by indexing: + .. function:: lufact!(A) -> LU - ``lufact!`` is the same as :func:`lufact`, but saves space by overwriting the input A, instead of creating a copy. For sparse ``A`` the ``nzval`` field is not overwritten but the index fields, ``colptr`` and ``rowval`` are decremented in place, converting from 1-based indices to 0-based indices. + :: + + lufact!(A) -> LU + + overwriting the input A, instead of creating a copy. For sparse 1-based indices to 0-based indices. + .. function:: chol(A, [LU]) -> F - Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` (Upper), ``F`` is of type ``UpperTriangular`` and ``A = F'*F``. If ``LU`` is ``Val{:L}`` (Lower), ``F`` is of type ``LowerTriangular`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. + :: + + chol(A[, LU]) -> F + + Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. + .. function:: cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix ``A`` and return either a ``Cholesky`` if ``pivot==Val{false}`` or ``CholeskyPivoted`` if ``pivot==Val{true}``. ``LU`` may be ``:L`` for using the lower part or ``:U`` for the upper part. The default is to use ``:U``. The triangular matrix can be obtained from the factorization ``F`` with: ``F[:L]`` and ``F[:U]``. The following functions are available for ``Cholesky`` objects: ``size``, ``\``, ``inv``, ``det``. For ``CholeskyPivoted`` there is also defined a ``rank``. If ``pivot==Val{false}`` a ``PosDefException`` exception is thrown in case the matrix is not positive definite. The argument ``tol`` determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. + :: + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite - matrix ``A``. A fill-reducing permutation is used. ``F = - cholfact(A)`` is most frequently used to solve systems of equations - with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` - are defined for ``F``. You can also extract individual factors - from ``F``, using ``F[:L]``. However, since pivoting is on by - default, the factorization is internally represented as ``A == - P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` - without accounting for ``P`` will give incorrect answers. To - include the effects of permutation, it's typically preferable to - extact "combined" factors like ``PtL = F[:PtL]`` (the equivalent of - ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). - - Setting optional ``shift`` keyword argument computes the factorization - of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, - it should be a permutation of `1:size(A,1)` giving the ordering to use - (instead of CHOLMOD's default AMD ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + :: + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - ``cholfact!`` is the same as :func:`cholfact`, but saves space by overwriting the input ``A``, instead of creating a copy. ``cholfact!`` can also reuse the symbolic factorization from a different matrix ``F`` with the same structure when used as: ``cholfact!(F::CholmodFactor, A)``. + :: + + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + overwriting the input ``A``, instead of creating a copy. different matrix ``F`` with the same structure when used as: + .. function:: ldltfact(A) -> LDLtFactorization - Compute a factorization of a positive definite matrix ``A`` such that ``A=L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector with non-negative elements. + :: + + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix ``A``. A fill-reducing permutation is used. ``F = - ldltfact(A)`` is most frequently used to solve systems of equations - with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` - are defined for ``F``. You can also extract individual factors from - ``F``, using ``F[:L]``. However, since pivoting is on by default, - the factorization is internally represented as ``A == P'*L*D*L'*P`` - with a permutation matrix ``P``; using just ``L`` without - accounting for ``P`` will give incorrect answers. To include the - effects of permutation, it's typically preferable to extact - "combined" factors like ``PtL = F[:PtL]`` (the equivalent of - ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). The - complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, - :DU, :PtLD, :DUP``. - - Setting optional ``shift`` keyword argument computes the factorization - of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, - it should be a permutation of `1:size(A,1)` giving the ordering to use - (instead of CHOLMOD's default AMD ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + :: + + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] - Compute the (pivoted) QR factorization of ``A`` such that either ``A = Q*R`` or ``A[:,p] = Q*R``. Also see ``qrfact``. The default is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. + :: + + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + + Compute the (pivoted) QR factorization of ``A`` such that either is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. + .. function:: qrfact(A [,pivot=Val{false}]) -> F - Computes the QR factorization of ``A``. The return type of ``F`` depends on the element type of ``A`` and whether pivoting is specified (with ``pivot==Val{true}``). - - ================ ================= ============== ===================================== - Return type ``eltype(A)`` ``pivot`` Relationship between ``F`` and ``A`` - ---------------- ----------------- -------------- ------------------------------------- - ``QR`` not ``BlasFloat`` either ``A==F[:Q]*F[:R]`` - ``QRCompactWY`` ``BlasFloat`` ``Val{false}`` ``A==F[:Q]*F[:R]`` - ``QRPivoted`` ``BlasFloat`` ``Val{true}`` ``A[:,F[:p]]==F[:Q]*F[:R]`` - ================ ================= ============== ===================================== - - ``BlasFloat`` refers to any of: ``Float32``, ``Float64``, ``Complex64`` or ``Complex128``. - - The individual components of the factorization ``F`` can be accessed by indexing: - - =========== ============================================= ================== ===================== ================== - Component Description ``QR`` ``QRCompactWY`` ``QRPivoted`` - ----------- --------------------------------------------- ------------------ --------------------- ------------------ - ``F[:Q]`` ``Q`` (orthogonal/unitary) part of ``QR`` ✓ (``QRPackedQ``) ✓ (``QRCompactWYQ``) ✓ (``QRPackedQ``) - ``F[:R]`` ``R`` (upper right triangular) part of ``QR`` ✓ ✓ ✓ - ``F[:p]`` pivot ``Vector`` ✓ - ``F[:P]`` (pivot) permutation ``Matrix`` ✓ - =========== ============================================= ================== ===================== ================== - - The following functions are available for the ``QR`` objects: ``size``, ``\``. When ``A`` is rectangular, ``\`` will return a least squares solution and if the solution is not unique, the one with smallest norm is returned. - - Multiplication with respect to either thin or full ``Q`` is allowed, i.e. both ``F[:Q]*F[:R]`` and ``F[:Q]*A`` are supported. A ``Q`` matrix can be converted into a regular matrix with :func:`full` which has a named argument ``thin``. - - .. note:: - - ``qrfact`` returns multiple types because LAPACK uses several representations that minimize the memory storage requirements of products of Householder elementary reflectors, so that the ``Q`` and ``R`` matrices can be stored compactly rather as two separate dense matrices. - - The data contained in ``QR`` or ``QRPivoted`` can be used to construct the ``QRPackedQ`` type, which is a compact representation of the rotation matrix: - - .. math:: - - Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) - - where :math:`\tau_i` is the scale factor and :math:`v_i` is the projection vector associated with the :math:`i^{th}` Householder elementary reflector. - - The data contained in ``QRCompactWY`` can be used to construct the ``QRCompactWYQ`` type, which is a compact representation of the rotation matrix - - .. math:: - - Q = I + Y T Y^T - - where ``Y`` is :math:`m \times r` lower trapezoidal and ``T`` is :math:`r \times r` upper triangular. The *compact WY* representation [Schreiber1989]_ is not to be confused with the older, *WY* representation [Bischof1987]_. (The LAPACK documentation uses ``V`` in lieu of ``Y``.) - - .. [Bischof1987] C Bischof and C Van Loan, The WY representation for products of Householder matrices, SIAM J Sci Stat Comput 8 (1987), s2-s13. doi:10.1137/0908009 - .. [Schreiber1989] R Schreiber and C Van Loan, A storage-efficient WY representation for products of Householder transformations, SIAM J Sci Stat Comput 10 (1989), 53-57. doi:10.1137/0910005 + :: + + qrfact(A) -> SPQR.Factorization + + Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. + .. function:: qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix ``A``. A fill-reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. + :: + + qrfact(A) -> SPQR.Factorization + + Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. + .. function:: qrfact!(A [,pivot=Val{false}]) - ``qrfact!`` is the same as :func:`qrfact` when A is a subtype of ``StridedMatrix``, but saves space by overwriting the input ``A``, instead of creating a copy. + :: + + qrfact!(A[, pivot=Val{false}]) + + instead of creating a copy. + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` - object, i.e. in the compact WY format [Bischof1987]_, to a dense matrix. - - Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the - columns that span the rows of ``R`` in the QR factorization that are zero. - The resulting matrix is the ``Q`` in a thin QR factorization (sometimes - called the reduced QR factorization). If ``false``, returns a ``Q`` that - spans all rows of ``R`` in its corresponding QR factorization. + :: + + full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. + .. function:: bkfact(A) -> BunchKaufman - Compute the Bunch-Kaufman [Bunch1977]_ factorization of a real symmetric or complex Hermitian matrix ``A`` and return a ``BunchKaufman`` object. The following functions are available for ``BunchKaufman`` objects: ``size``, ``\``, ``inv``, ``issym``, ``ishermitian``. + :: + + bkfact(A) -> BunchKaufman + + Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix ``A`` and return a + .. [Bunch1977] J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. `url `_. .. function:: bkfact!(A) -> BunchKaufman - ``bkfact!`` is the same as :func:`bkfact`, but saves space by overwriting the input ``A``, instead of creating a copy. + :: + + bkfact!(A) -> BunchKaufman + + overwriting the input ``A``, instead of creating a copy. + .. function:: sqrtm(A) - Compute the matrix square root of ``A``. If ``B = sqrtm(A)``, then ``B*B == A`` within roundoff error. - - ``sqrtm`` uses a polyalgorithm, computing the matrix square root using Schur factorizations (:func:`schurfact`) unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition (:func:`eigfact`). In the latter situation for positive definite matrices, the matrix square root has ``Real`` elements, otherwise it has ``Complex`` elements. + :: + + sqrtm(A) + + Compute the matrix square root of ``A``. If ``B = sqrtm(A)``, then using Schur factorizations (``schurfact()``) unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition (``eigfact()``). In the latter situation for positive definite matrices, the matrix square root has ``Real`` elements, otherwise it has ``Complex`` elements. + .. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - Computes eigenvalues and eigenvectors of ``A``. See :func:`eigfact` for - details on the ``balance`` keyword argument. - - .. doctest:: - - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) - - ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the - factorization to a tuple; where possible, using :func:`eigfact` is - recommended. + :: + + eig(A, B) -> D, V + + Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. + .. function:: eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. - - ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the - factorization to a tuple; where possible, using :func:`eigfact` is - recommended. + :: + + eig(A, B) -> D, V + + Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. + .. function:: eigvals(A,[irange,][vl,][vu]) - Returns the eigenvalues of ``A``. If ``A`` is :class:`Symmetric`, - :class:`Hermitian` or :class:`SymTridiagonal`, it is possible to calculate - only a subset of the eigenvalues by specifying either a :class:`UnitRange` - ``irange`` covering indices of the sorted eigenvalues, or a pair ``vl`` and - ``vu`` for the lower and upper boundaries of the eigenvalues. - - For general non-symmetric matrices it is possible to specify how the matrix - is balanced before the eigenvector calculation. The option ``permute=true`` - permutes the matrix to become closer to upper triangular, and ``scale=true`` - scales the matrix by its diagonal elements to make rows and columns more - equal in norm. The default is ``true`` for both options. + :: + + eigvals(A,[irange,][vl,][vu]) + + Returns the eigenvalues of ``A``. If ``A`` is ``Symmetric``, only a subset of the eigenvalues by specifying either a eigenvalues, or a pair ``vl`` and ``vu`` for the lower and upper boundaries of the eigenvalues. For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option ``permute=true`` permutes the matrix to become closer to upper triangular, and ``scale=true`` scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is ``true`` for both options. + .. function:: eigmax(A) + :: + + eigmax(A) + Returns the largest eigenvalue of ``A``. + .. function:: eigmin(A) + :: + + eigmin(A) + Returns the smallest eigenvalue of ``A``. + .. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - Returns a matrix ``M`` whose columns are the eigenvectors of ``A``. - (The ``k``\ th eigenvector can be obtained from the slice ``M[:, k]``.) - The ``permute`` and ``scale`` keywords are the same as for :func:`eigfact`. - - For :class:`SymTridiagonal` matrices, if the optional vector of eigenvalues - ``eigvals`` is specified, returns the specific corresponding eigenvectors. + :: + + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + + Returns a matrix ``M`` whose columns are the eigenvectors of ``A``. k]``.) The `permute`` and ``scale`` keywords are the same as for For ``SymTridiagonal`` matrices, if the optional vector of eigenvalues ``eigvals`` is specified, returns the specific corresponding eigenvectors. + .. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - Computes the eigenvalue decomposition of ``A``, returning an ``Eigen`` - factorization object ``F`` which contains the eigenvalues in ``F[:values]`` - and the eigenvectors in the columns of the matrix ``F[:vectors]``. - (The ``k``\ th eigenvector can be obtained from the slice ``F[:vectors][:, k]``.) - - The following functions are available for ``Eigen`` objects: ``inv``, - ``det``. - - If ``A`` is :class:`Symmetric`, :class:`Hermitian` or :class:`SymTridiagonal`, - it is possible to calculate only a subset of the eigenvalues by specifying - either a :class:`UnitRange` ``irange`` covering indices of the sorted - eigenvalues or a pair ``vl`` and ``vu`` for the lower and upper boundaries - of the eigenvalues. - - For general nonsymmetric matrices it is possible to specify how the matrix - is balanced before the eigenvector calculation. The option ``permute=true`` - permutes the matrix to become closer to upper triangular, and ``scale=true`` - scales the matrix by its diagonal elements to make rows and columns more - equal in norm. The default is ``true`` for both options. + :: + + eigfact(A, B) -> GeneralizedEigen + + Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) + .. function:: eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of ``A`` and ``B``, - returning a ``GeneralizedEigen`` factorization object ``F`` which contains - the generalized eigenvalues in ``F[:values]`` and the generalized - eigenvectors in the columns of the matrix ``F[:vectors]``. (The ``k``\ th - generalized eigenvector can be obtained from the slice ``F[:vectors][:, - k]``.) + :: + + eigfact(A, B) -> GeneralizedEigen + + Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) + .. function:: eigfact!(A, [B]) - Same as :func:`eigfact`, but saves space by overwriting the input ``A`` (and - ``B``), instead of creating a copy. + :: + + eigfact!(A[, B]) + + Same as ``eigfact()``, but saves space by overwriting the input + .. function:: hessfact(A) - Compute the Hessenberg decomposition of ``A`` and return a ``Hessenberg`` object. If ``F`` is the factorization object, the unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``. When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with :func:`full`. + :: + + hessfact(A) + + Compute the Hessenberg decomposition of ``A`` and return a unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``. When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with ``full()``. + .. function:: hessfact!(A) - ``hessfact!`` is the same as :func:`hessfact`, but saves space by overwriting the input A, instead of creating a copy. + :: + + hessfact!(A) + + overwriting the input A, instead of creating a copy. + .. function:: schurfact(A) -> Schur - Computes the Schur factorization of the matrix ``A``. The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``. The eigenvalues of ``A`` can be obtained with ``F[:values]``. + :: + + schurfact(A, B) -> GeneralizedSchur + + Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and + .. function:: schurfact!(A) - Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See :func:`schurfact` + :: + + schurfact!(A) + + Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See ``schurfact()`` + .. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] - See :func:`schurfact` + :: + + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + + See ``schurfact()`` + .. function:: ordschur(Q, T, select) -> Schur - Reorders the Schur factorization of a real matrix ``A=Q*T*Q'`` according to the logical array ``select`` returning a Schur object ``F``. The selected eigenvalues appear in the leading diagonal of ``F[:Schur]`` and the the corresponding leading columns of ``F[:vectors]`` form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via ``select``. + :: + + ordschur(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. + .. function:: ordschur!(Q, T, select) -> Schur - Reorders the Schur factorization of a real matrix ``A=Q*T*Q'``, overwriting ``Q`` and ``T`` in the process. See :func:`ordschur` + :: + + ordschur!(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See + .. function:: ordschur(S, select) -> Schur - Reorders the Schur factorization ``S`` of type ``Schur``. + :: + + ordschur(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. + .. function:: ordschur!(S, select) -> Schur - Reorders the Schur factorization ``S`` of type ``Schur``, overwriting ``S`` in the process. See :func:`ordschur` + :: + + ordschur!(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See + .. function:: schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``, the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``. The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``. + :: + + schurfact(A, B) -> GeneralizedSchur + + Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and + .. function:: schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See :func:`schurfact` + :: + + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + + See ``schurfact()`` + .. function:: ordschur(S, T, Q, Z, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a matrix ``(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})`` according to the logical array ``select`` and returns a GeneralizedSchur object ``GS``. The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that ``(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}`` still holds and the generalized eigenvalues of ``A`` and ``B`` can still be obtained with ``GS[:alpha]./GS[:beta]``. + :: + + ordschur(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. + .. function:: ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a matrix by overwriting the matrices ``(S, T, Q, Z)`` in the process. See :func:`ordschur`. + :: + + ordschur!(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See + .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See :func:`ordschur`. + :: + + ordschur(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. + .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See :func:`ordschur`. + :: + + ordschur!(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See + .. function:: svdfact(A, [thin=true]) -> SVD - Compute the Singular Value Decomposition (SVD) of ``A`` and return an ``SVD`` object. ``U``, ``S``, ``V`` and ``Vt`` can be obtained from the factorization ``F`` with ``F[:U]``, ``F[:S]``, ``F[:V]`` and ``F[:Vt]``, such that ``A = U*diagm(S)*Vt``. If ``thin`` is ``true``, an economy mode decomposition is returned. The algorithm produces ``Vt`` and hence ``Vt`` is more efficient to extract than ``V``. The default is to produce a thin decomposition. + :: + + svdfact(A, B) -> GeneralizedSVD + + Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. + .. function:: svdfact!(A, [thin=true]) -> SVD - ``svdfact!`` is the same as :func:`svdfact`, but saves space by overwriting the input A, instead of creating a copy. If ``thin`` is ``true``, an economy mode decomposition is returned. The default is to produce a thin decomposition. + :: + + svdfact!(A[, thin=true]) -> SVD + + overwriting the input A, instead of creating a copy. If ``thin`` is to produce a thin decomposition. + .. function:: svd(A, [thin=true]) -> U, S, V - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. Computes the SVD of A, returning ``U``, vector ``S``, and ``V`` such that ``A == U*diagm(S)*V'``. If ``thin`` is ``true``, an economy mode decomposition is returned. The default is to produce a thin decomposition. + :: + + svd(A, B) -> U, V, Q, D1, D2, R0 + + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. + .. function:: svdvals(A) - Returns the singular values of ``A``. + :: + + svdvals(A, B) + + Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + .. function:: svdvals!(A) + :: + + svdvals!(A) + Returns the singular values of ``A``, while saving space by overwriting the input. + .. function:: svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a ``GeneralizedSVD`` Factorization object ``F``, such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``. + :: + + svdfact(A, B) -> GeneralizedSVD + + Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. + .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``, returning ``U``, ``V``, ``Q``, ``D1``, ``D2``, and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. + :: + + svd(A, B) -> U, V, Q, D1, D2, R0 + + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. + .. function:: svdvals(A, B) + :: + + svdvals(A, B) + Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + .. function:: triu(M) - Upper triangle of a matrix. + :: + + triu(M, k) + + Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. + .. function:: triu(M, k) - Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal. + :: + + triu(M, k) + + Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. + .. function:: triu!(M) - Upper triangle of a matrix, overwriting ``M`` in the process. + :: + + triu!(M, k) + + Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. + .. function:: triu!(M, k) - Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. + :: + + triu!(M, k) + + Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. + .. function:: tril(M) - Lower triangle of a matrix. + :: + + tril(M, k) + + Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. + .. function:: tril(M, k) - Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal. + :: + + tril(M, k) + + Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. + .. function:: tril!(M) - Lower triangle of a matrix, overwriting ``M`` in the process. + :: + + tril!(M, k) + + Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. + .. function:: tril!(M, k) - Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal, overwriting ``M`` in the process. + :: + + tril!(M, k) + + Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. + .. function:: diagind(M[, k]) - A ``Range`` giving the indices of the ``k``\ th diagonal of the matrix ``M``. + :: + + diagind(M[, k]) + + A ``Range`` giving the indices of the ``k``th diagonal of the matrix ``M``. + .. function:: diag(M[, k]) - The ``k``\ th diagonal of a matrix, as a vector. Use ``diagm`` to construct a diagonal matrix. + :: + + diag(M[, k]) + + The ``k``th diagonal of a matrix, as a vector. Use ``diagm`` to construct a diagonal matrix. + .. function:: diagm(v[, k]) - Construct a diagonal matrix and place ``v`` on the ``k``\ th diagonal. + :: + + diagm(v[, k]) + + Construct a diagonal matrix and place ``v`` on the ``k``th diagonal. + .. function:: scale(A, b) -.. function:: scale(b, A) - Scale an array ``A`` by a scalar ``b``, returning a new array. + :: + + scale(b, A) + + Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. + - If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` - scales each column ``i`` of ``A`` by ``b[i]`` (similar to - ``A*diagm(b)``), while ``scale(b,A)`` scales each row ``i`` of - ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), returning a new array. +.. function:: scale(b, A) - Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or - ``b .* A``, due to the use of BLAS. + :: + + scale(b, A) + + Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. + .. function:: scale!(A, b) -.. function:: scale!(b, A) - Scale an array ``A`` by a scalar ``b``, similar to :func:`scale` but - overwriting ``A`` in-place. + :: + + scale!(b, A) + + Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. + + +.. function:: scale!(b, A) - If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` - scales each column ``i`` of ``A`` by ``b[i]`` (similar to - ``A*diagm(b)``), while ``scale!(b,A)`` scales each row ``i`` of - ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), again operating in-place - on ``A``. + :: + + scale!(b, A) + + Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. + .. function:: Tridiagonal(dl, d, du) - Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type ``Tridiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with :func:`full`. + :: + + Tridiagonal(dl, d, du) + + Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. + .. function:: Bidiagonal(dv, ev, isupper) - Constructs an upper (``isupper=true``) or lower (``isupper=false``) bidiagonal matrix - using the given diagonal (``dv``) and off-diagonal (``ev``) vectors. The result is of type ``Bidiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with :func:`full`. + :: + + Bidiagonal(dv, ev, isupper) + + Constructs an upper (``isupper=true``) or lower (``isupper=false``) bidiagonal matrix using the given diagonal (``dv``) and off- diagonal (``ev``) vectors. The result is of type ``Bidiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with ``full()``. + .. function:: SymTridiagonal(d, du) - Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type ``SymTridiagonal`` and provides efficient specialized eigensolvers, but may be converted into a regular matrix with :func:`full`. + :: + + SymTridiagonal(d, du) + + Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. + .. function:: rank(M) + :: + + rank(M) + Compute the rank of a matrix. + .. function:: norm(A, [p]) - Compute the ``p``-norm of a vector or the operator norm of a matrix ``A``, defaulting to the ``p=2``-norm. - - For vectors, ``p`` can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, ``norm(A, Inf)`` returns the largest value in ``abs(A)``, whereas ``norm(A, -Inf)`` returns the smallest. - - For matrices, valid values of ``p`` are ``1``, ``2``, or ``Inf``. (Note that for sparse matrices, ``p=2`` is currently not implemented.) Use :func:`vecnorm` to compute the Frobenius norm. + :: + + norm(A[, p]) + + Compute the ``p``-norm of a vector or the operator norm of a matrix For vectors, ``p`` can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, ``norm(A, Inf)`` returns the largest value in For matrices, valid values of ``p`` are ``1``, ``2``, or ``Inf``. implemented.) Use ``vecnorm()`` to compute the Frobenius norm. + .. function:: vecnorm(A, [p]) - For any iterable container ``A`` (including arrays of any - dimension) of numbers (or any element type for which ``norm`` is - defined), compute the ``p``-norm (defaulting to ``p=2``) as if - ``A`` were a vector of the corresponding length. - - For example, if ``A`` is a matrix and ``p=2``, then this is equivalent - to the Frobenius norm. + :: + + vecnorm(A[, p]) + + For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``-norm (defaulting to ``p=2``) as if For example, if ``A`` is a matrix and ``p=2``, then this is equivalent to the Frobenius norm. + .. function:: cond(M, [p]) - Condition number of the matrix ``M``, computed using the operator ``p``-norm. Valid values for ``p`` are ``1``, ``2`` (default), or ``Inf``. + :: + + cond(M[, p]) + + Condition number of the matrix ``M``, computed using the operator + .. function:: condskeel(M, [x, p]) - .. math:: - \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert \left\vert M^{-1} \right\vert \right\Vert_p \\ - \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert \left\vert M^{-1} \right\vert \left\vert x \right\vert \right\Vert_p - - Skeel condition number :math:`\kappa_S` of the matrix ``M``, optionally with respect to the vector ``x``, as computed using the operator ``p``-norm. ``p`` is ``Inf`` by default, if not provided. Valid values for ``p`` are ``1``, ``2``, or ``Inf``. - - This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. + :: + + condskeel(M[, x, p]) + + Skeel condition number \kappa_S of the matrix ``M``, optionally with respect to the vector ``x``, as computed using the operator values for ``p`` are ``1``, ``2``, or ``Inf``. This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. + .. function:: trace(M) + :: + + trace(M) + Matrix trace + .. function:: det(M) + :: + + det(M) + Matrix determinant + .. function:: logdet(M) + :: + + logdet(M) + Log of matrix determinant. Equivalent to ``log(det(M))``, but may provide increased accuracy and/or speed. + .. function:: logabsdet(M) @@ -572,199 +759,237 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: inv(M) + :: + + inv(M) + Matrix inverse + .. function:: pinv(M[, tol]) - Computes the Moore-Penrose pseudoinverse. - - For matrices ``M`` with floating point elements, it is convenient to compute - the pseudoinverse by inverting only singular values above a given threshold, - ``tol``. - - The optimal choice of ``tol`` varies both with the value of ``M`` - and the intended application of the pseudoinverse. The default value of - ``tol`` is ``eps(real(float(one(eltype(M)))))*maximum(size(A))``, - which is essentially machine epsilon for the real part of a matrix element - multiplied by the larger matrix dimension. - For inverting dense ill-conditioned matrices in a least-squares sense, - ``tol = sqrt(eps(real(float(one(eltype(M))))))`` is recommended. - - For more information, see [8859]_, [B96]_, [S84]_, [KY88]_. - - .. [8859] Issue 8859, "Fix least squares", https://github.com/JuliaLang/julia/pull/8859 - .. [B96] Åke Björck, "Numerical Methods for Least Squares Problems", - SIAM Press, Philadelphia, 1996, "Other Titles in Applied Mathematics", Vol. 51. - `doi:10.1137/1.9781611971484 `_ - .. [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - `doi:10.1137/0905030 `_ - .. [KY88] Konstantinos Konstantinides and Kung Yao, "Statistical analysis - of effective singular values in matrix rank determination", IEEE - Transactions on Acoustics, Speech and Signal Processing, 36(5), 1988, - 757-763. - `doi:10.1109/29.1585 `_ + :: + + pinv(M[, tol]) + + Computes the Moore-Penrose pseudoinverse. For matrices ``M`` with floating point elements, it is convenient to compute the pseudoinverse by inverting only singular values above a given threshold, ``tol``. The optimal choice of ``tol`` varies both with the value of ``M`` and the intended application of the pseudoinverse. The default value of ``tol`` is essentially machine epsilon for the real part of a matrix element multiplied by the larger matrix dimension. For inverting dense ill- conditioned matrices in a least-squares sense, ``tol = sqrt(eps(real(float(one(eltype(M))))))`` is recommended. For more information, see [8859], [B96], [S84], [KY88]. + .. function:: nullspace(M) + :: + + nullspace(M) + Basis for nullspace of ``M``. + .. function:: repmat(A, n, m) + :: + + repmat(A, n, m) + Construct a matrix by repeating the given matrix ``n`` times in dimension 1 and ``m`` times in dimension 2. + .. function:: repeat(A, inner = Int[], outer = Int[]) + :: + + repeat(A, inner = Int[], outer = Int[]) + Construct an array by repeating the entries of ``A``. The i-th element of ``inner`` specifies the number of times that the individual entries of the i-th dimension of ``A`` should be repeated. The i-th element of ``outer`` specifies the number of times that a slice along the i-th dimension of ``A`` should be repeated. + .. function:: kron(A, B) + :: + + kron(A, B) + Kronecker tensor product of two vectors or two matrices. + .. function:: blkdiag(A...) + :: + + blkdiag(A...) + Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. + .. function:: linreg(x, y) -> [a; b] - Linear Regression. Returns ``a`` and ``b`` such that ``a+b*x`` is the closest line to the given points ``(x,y)``. In other words, this function determines parameters ``[a, b]`` that minimize the squared error between ``y`` and ``a+b*x``. - - **Example**:: - - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, "o") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + :: + + linreg(x, y, w) + + Weighted least-squares linear regression. + .. function:: linreg(x, y, w) + :: + + linreg(x, y, w) + Weighted least-squares linear regression. + .. function:: expm(A) + :: + + expm(A) + Matrix exponential. + .. function:: lyap(A, C) - Computes the solution ``X`` to the continuous Lyapunov equation ``AX + XA' + C = 0``, where no eigenvalue of ``A`` has a zero real part and no two eigenvalues are negative complex conjugates of each other. + :: + + lyap(A, C) + + Computes the solution ``X`` to the continuous Lyapunov equation part and no two eigenvalues are negative complex conjugates of each other. + .. function:: sylvester(A, B, C) - Computes the solution ``X`` to the Sylvester equation ``AX + XB + C = 0``, where ``A``, ``B`` and ``C`` have compatible dimensions and ``A`` and ``-B`` have no eigenvalues with equal real part. + :: + + sylvester(A, B, C) + + Computes the solution ``X`` to the Sylvester equation `AX + XB + C + .. function:: issym(A) -> Bool + :: + + issym(A) -> Bool + Test whether a matrix is symmetric. + .. function:: isposdef(A) -> Bool + :: + + isposdef(A) -> Bool + Test whether a matrix is positive definite. + .. function:: isposdef!(A) -> Bool + :: + + isposdef!(A) -> Bool + Test whether a matrix is positive definite, overwriting ``A`` in the processes. + .. function:: istril(A) -> Bool + :: + + istril(A) -> Bool + Test whether a matrix is lower triangular. + .. function:: istriu(A) -> Bool + :: + + istriu(A) -> Bool + Test whether a matrix is upper triangular. + .. function:: isdiag(A) -> Bool + :: + + isdiag(A) -> Bool + Test whether a matrix is diagonal. + .. function:: ishermitian(A) -> Bool + :: + + ishermitian(A) -> Bool + Test whether a matrix is Hermitian. + .. function:: transpose(A) + :: + + transpose(A) + The transposition operator (``.'``). + .. function:: transpose!(dest,src) - Transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if `src` and `dest` have overlapping memory regions. + :: + + transpose!(dest, src) + + Transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + .. function:: ctranspose(A) + :: + + ctranspose(A) + The conjugate transposition operator (``'``). + .. function:: ctranspose!(dest,src) - Conjugate transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if `src` and `dest` have overlapping memory regions. + :: + + ctranspose!(dest, src) + + Conjugate transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + .. function:: eigs(A, [B,]; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0,))) -> (d,[v,],nconv,niter,nmult,resid) - Computes eigenvalues ``d`` of ``A`` using Lanczos or Arnoldi iterations for - real symmetric or general nonsymmetric matrices respectively. If ``B`` is - provided, the generalized eigenproblem is solved. - - The following keyword arguments are supported: - * ``nev``: Number of eigenvalues - * ``ncv``: Number of Krylov vectors used in the computation; should satisfy - ``nev+1 <= ncv <= n`` for real symmetric problems and ``nev+2 <= ncv <= n`` - for other problems, where ``n`` is the size of the input matrix ``A``. - The default is ``ncv = max(20,2*nev+1)``. - Note that these restrictions limit the input matrix ``A`` to be of - dimension at least 2. - * ``which``: type of eigenvalues to compute. See the note below. - - ========= ====================================================================================================================== - ``which`` type of eigenvalues - --------- ---------------------------------------------------------------------------------------------------------------------- - ``:LM`` eigenvalues of largest magnitude (default) - ``:SM`` eigenvalues of smallest magnitude - ``:LR`` eigenvalues of largest real part - ``:SR`` eigenvalues of smallest real part - ``:LI`` eigenvalues of largest imaginary part (nonsymmetric or complex ``A`` only) - ``:SI`` eigenvalues of smallest imaginary part (nonsymmetric or complex ``A`` only) - ``:BE`` compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric ``A`` only) - ========= ====================================================================================================================== - - * ``tol``: tolerance (:math:`tol \le 0.0` defaults to ``DLAMCH('EPS')``) - * ``maxiter``: Maximum number of iterations (default = 300) - * ``sigma``: Specifies the level shift used in inverse iteration. If ``nothing`` (default), defaults to ordinary (forward) iterations. Otherwise, find eigenvalues close to ``sigma`` using shift and invert iterations. - * ``ritzvec``: Returns the Ritz vectors ``v`` (eigenvectors) if ``true`` - * ``v0``: starting vector from which to start the iterations - - ``eigs`` returns the ``nev`` requested eigenvalues in ``d``, the corresponding Ritz vectors ``v`` (only if ``ritzvec=true``), the number of converged eigenvalues ``nconv``, the number of iterations ``niter`` and the number of matrix vector multiplications ``nmult``, as well as the final residual vector ``resid``. - - .. note:: The ``sigma`` and ``which`` keywords interact: the description of eigenvalues searched for by ``which`` do _not_ necessarily refer to the eigenvalues of ``A``, but rather the linear operator constructed by the specification of the iteration mode implied by ``sigma``. - - =============== ================================== ================================== - ``sigma`` iteration mode ``which`` refers to eigenvalues of - --------------- ---------------------------------- ---------------------------------- - ``nothing`` ordinary (forward) :math:`A` - real or complex inverse with level shift ``sigma`` :math:`(A - \sigma I )^{-1}` - =============== ================================== ================================== + :: + + eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) + + Computes eigenvalues ``d`` of ``A`` using Lanczos or Arnoldi iterations for real symmetric or general nonsymmetric matrices respectively. If ``B`` is provided, the generalized eigenproblem is solved. The following keyword arguments are supported: corresponding Ritz vectors ``v`` (only if ``ritzvec=true``), the number of converged eigenvalues ``nconv``, the number of iterations Note: The ``sigma`` and ``which`` keywords interact: the + .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - ``svds`` computes largest singular values ``s`` of ``A`` using Lanczos or Arnoldi iterations. - Uses :func:`eigs` underneath. - - Inputs are: - * ``A``: Linear operator. It can either subtype of ``AbstractArray`` (e.g., sparse matrix) or duck typed. For duck typing ``A`` has to support ``size(A)``, ``eltype(A)``, ``A * vector`` and ``A' * vector``. - * ``nsv``: Number of singular values. - * ``ritzvec``: Whether to return the left and right singular vectors ``left_sv`` and ``right_sv``, default is ``true``. If ``false`` the singular vectors are omitted from the output. - * ``tol``: tolerance, see :func:`eigs`. - * ``maxiter``: Maximum number of iterations, see :func:`eigs`. - - **Example**:: - - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) + :: + + svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + + Lanczos or Arnoldi iterations. Uses ``eigs()`` underneath. Inputs are: + .. function:: peakflops(n; parallel=false) - ``peakflops`` computes the peak flop rate of the computer by using double precision :func:`Base.LinAlg.BLAS.gemm!`. By default, if no arguments are specified, it multiplies a matrix of size ``n x n``, where ``n = 2000``. If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with ``blas_set_num_threads(n)``. - - If the keyword argument ``parallel`` is set to ``true``, ``peakflops`` is run in parallel on all the worker processors. The flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument ``n`` still refers to the size of the problem that is solved on each processor. + :: + + peakflops(n; parallel=false) + + double precision ``Base.LinAlg.BLAS.gemm!()``. By default, if no arguments are specified, it multiplies a matrix of size ``n x n``, where ``n = 2000``. If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with ``blas_set_num_threads(n)``. If the keyword argument ``parallel`` is set to ``true``, flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument ``n`` still refers to the size of the problem that is solved on each processor. + BLAS Functions -------------- @@ -782,260 +1007,390 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: dot(n, X, incx, Y, incy) - Dot product of two vectors consisting of ``n`` elements of array - ``X`` with stride ``incx`` and ``n`` elements of array ``Y`` with - stride ``incy``. + :: + + dot(n, X, incx, Y, incy) + + Dot product of two vectors consisting of ``n`` elements of array stride ``incy``. + .. function:: dotu(n, X, incx, Y, incy) + :: + + dotu(n, X, incx, Y, incy) + Dot function for two complex vectors. + .. function:: dotc(n, X, incx, U, incy) + :: + + dotc(n, X, incx, U, incy) + Dot function for two complex vectors conjugating the first vector. + .. function:: blascopy!(n, X, incx, Y, incy) + :: + + blascopy!(n, X, incx, Y, incy) + Copy ``n`` elements of array ``X`` with stride ``incx`` to array - ``Y`` with stride ``incy``. Returns ``Y``. + .. function:: nrm2(n, X, incx) - 2-norm of a vector consisting of ``n`` elements of array ``X`` with - stride ``incx``. + :: + + nrm2(n, X, incx) + + 2-norm of a vector consisting of ``n`` elements of array ``X`` with stride ``incx``. + .. function:: asum(n, X, incx) - sum of the absolute values of the first ``n`` elements of array ``X`` with - stride ``incx``. + :: + + asum(n, X, incx) + + sum of the absolute values of the first ``n`` elements of array + .. function:: axpy!(a, X, Y) + :: + + axpy!(a, X, Y) + Overwrite ``Y`` with ``a*X + Y``. Returns ``Y``. + .. function:: scal!(n, a, X, incx) + :: + + scal!(n, a, X, incx) + Overwrite ``X`` with ``a*X``. Returns ``X``. + .. function:: scal(n, a, X, incx) + :: + + scal(n, a, X, incx) + Returns ``a*X``. + .. function:: ger!(alpha, x, y, A) - Rank-1 update of the matrix ``A`` with vectors ``x`` and - ``y`` as ``alpha*x*y' + A``. + :: + + ger!(alpha, x, y, A) + + Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as + .. function:: syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix ``A`` with vector - ``x`` as ``alpha*x*x.' + A``. When ``uplo`` is 'U' the - upper triangle of ``A`` is updated ('L' for lower triangle). - Returns ``A``. + :: + + syr!(uplo, alpha, x, A) + + Rank-1 update of the symmetric matrix ``A`` with vector ``x`` as + .. function:: syrk!(uplo, trans, alpha, A, beta, C) - Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + - beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` - is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is - updated ('L' for lower triangle). Returns ``C``. + :: + + syrk!(uplo, trans, alpha, A, beta, C) + + Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. + .. function:: syrk(uplo, trans, alpha, A) - Returns either the upper triangle or the lower triangle, according - to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``, - according to ``trans`` ('N' or 'T'). + :: + + syrk(uplo, trans, alpha, A) + + Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``, according to ``trans`` ('N' or 'T'). + .. function:: her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian - matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When - ``uplo`` is 'U' the upper triangle of ``A`` is updated - ('L' for lower triangle). Returns ``A``. + :: + + her!(uplo, alpha, x, A) + + Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When lower triangle). Returns ``A``. + .. function:: herk!(uplo, trans, alpha, A, beta, C) - Methods for complex arrays only. Rank-k update of the Hermitian - matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` - according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' - the upper triangle of ``C`` is updated ('L' for lower triangle). - Returns ``C``. + :: + + herk!(uplo, trans, alpha, A, beta, C) + + Methods for complex arrays only. Rank-k update of the Hermitian matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. + .. function:: herk(uplo, trans, alpha, A) - Methods for complex arrays only. Returns either the upper triangle - or the lower triangle, according to ``uplo`` ('U' or 'L'), of - ``alpha*A*A'`` or ``alpha*A'*A``, according to ``trans`` ('N' or 'T'). + :: + + herk(uplo, trans, alpha, A) + + Methods for complex arrays only. Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of + .. function:: gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - Update vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'*x + - beta*y`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is - a general band matrix of dimension ``m`` by ``size(A,2)`` with - ``kl`` sub-diagonals and ``ku`` super-diagonals. Returns the - updated ``y``. + :: + + gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) + + Update vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'*x + beta*y`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension ``m`` by ``size(A,2)`` with updated ``y``. + .. function:: gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - Returns ``alpha*A*x`` or ``alpha*A'*x`` according to ``trans`` ('N' - or 'T'). The matrix ``A`` is a general band matrix of dimension - ``m`` by ``size(A,2)`` with ``kl`` sub-diagonals and - ``ku`` super-diagonals. + :: + + gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + + Returns ``alpha*A*x`` or ``alpha*A'*x`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension diagonals. + .. function:: sbmv!(uplo, k, alpha, A, x, beta, y) - Update vector ``y`` as ``alpha*A*x + beta*y`` where ``A`` is a - a symmetric band matrix of order ``size(A,2)`` with - ``k`` super-diagonals stored in the argument ``A``. The storage - layout for ``A`` is described the reference BLAS module, level-2 - BLAS at http://www.netlib.org/lapack/explore-html/. - - Returns the updated ``y``. + :: + + sbmv!(uplo, k, alpha, A, x, beta, y) + + Update vector ``y`` as ``alpha*A*x + beta*y`` where ``A`` is a a symmetric band matrix of order ``size(A,2)`` with ``k`` super- diagonals stored in the argument ``A``. The storage layout for http://www.netlib.org/lapack/explore-html/. Returns the updated ``y``. + .. function:: sbmv(uplo, k, alpha, A, x) - Returns ``alpha*A*x`` where ``A`` is a symmetric band matrix of - order ``size(A,2)`` with ``k`` super-diagonals stored in the - argument ``A``. + :: + + sbmv(uplo, k, A, x) + + Returns ``A*x`` where ``A`` is a symmetric band matrix of order + .. function:: sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of - order ``size(A,2)`` with ``k`` super-diagonals stored in the - argument ``A``. + :: + + sbmv(uplo, k, A, x) + + Returns ``A*x`` where ``A`` is a symmetric band matrix of order + .. function:: gemm!(tA, tB, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. Returns the - updated ``C``. + :: + + gemm!(tA, tB, alpha, A, B, beta, C) + + Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. Returns the updated ``C``. + .. function:: gemm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + :: + + gemm(tA, tB, A, B) + + Returns ``A*B`` or the other three variants according to ``tA`` + .. function:: gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + :: + + gemm(tA, tB, A, B) + + Returns ``A*B`` or the other three variants according to ``tA`` + .. function:: gemv!(tA, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y`` or - ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``). - Returns the updated ``y``. + :: + + gemv!(tA, alpha, A, x, beta, y) + + Update the vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``). Returns the updated + .. function:: gemv(tA, alpha, A, x) - Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` - (transpose ``A``). + :: + + gemv(tA, A, x) + + Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). + .. function:: gemv(tA, A, x) + :: + + gemv(tA, A, x) + Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). + .. function:: symm!(side, ul, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` - according to ``side``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. Returns the updated ``C``. + :: + + symm!(side, ul, alpha, A, B, beta, C) + + Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` according to ``side``. ``A`` is assumed to be symmetric. Only the + .. function:: symm(side, ul, alpha, A, B) - Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``. - ``A`` is assumed to be symmetric. Only the ``ul`` triangle of - ``A`` is used. + :: + + symm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants according to + .. function:: symm(side, ul, A, B) - Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed - to be symmetric. Only the ``ul`` triangle of ``A`` is used. + :: + + symm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants according to + .. function:: symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + :: + + symm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants according to + .. function:: symv!(ul, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y``. ``A`` is assumed - to be symmetric. Only the ``ul`` triangle of ``A`` is used. - Returns the updated ``y``. + :: + + symv!(ul, alpha, A, x, beta, y) + + Update the vector ``y`` as ``alpha*A*x + beta*y``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. Returns the updated ``y``. + .. function:: symv(ul, alpha, A, x) - Returns ``alpha*A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + :: + + symv(ul, A, x) + + Returns ``A*x``. ``A`` is assumed to be symmetric. Only the + .. function:: symv(ul, A, x) + :: + + symv(ul, A, x) + Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + .. function:: trmm!(side, ul, tA, dA, alpha, A, B) - Update ``B`` as ``alpha*A*B`` or one of the other three variants - determined by ``side`` (A on left or right) and ``tA`` (transpose A). - Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if - ``A`` is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated ``B``. + :: + + trmm!(side, ul, tA, dA, alpha, A, B) + + Update ``B`` as ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``B``. + .. function:: trmm(side, ul, tA, dA, alpha, A, B) - Returns ``alpha*A*B`` or one of the other three variants - determined by ``side`` (A on left or right) and ``tA`` (transpose A). - Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if - ``A`` is unit-triangular (the diagonal is assumed to be all ones). + :: + + trmm(side, ul, tA, dA, alpha, A, B) + + Returns ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). + .. function:: trsm!(side, ul, tA, dA, alpha, A, B) - Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of - the other three variants determined by ``side`` (A on left or - right of ``X``) and ``tA`` (transpose A). Only the ``ul`` triangle - of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular - (the diagonal is assumed to be all ones). Returns the updated ``B``. + :: + + trsm!(side, ul, tA, dA, alpha, A, B) + + Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and ``tA`` (transpose A). Only the ``ul`` triangle of diagonal is assumed to be all ones). Returns the updated ``B``. + .. function:: trsm(side, ul, tA, dA, alpha, A, B) - Returns the solution to ``A*X = alpha*B`` or one of - the other three variants determined by ``side`` (A on left or - right of ``X``) and ``tA`` (transpose A). Only the ``ul`` triangle - of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular - (the diagonal is assumed to be all ones). + :: + + trsm(side, ul, tA, dA, alpha, A, B) + + Returns the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and assumed to be all ones). + .. function:: trmv!(side, ul, tA, dA, alpha, A, b) - Update ``b`` as ``alpha*A*b`` or one of the other three variants - determined by ``side`` (A on left or right) and ``tA`` (transpose A). - Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if - ``A`` is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated ``b``. + :: + + trmv!(side, ul, tA, dA, alpha, A, b) + + Update ``b`` as ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``b``. + .. function:: trmv(side, ul, tA, dA, alpha, A, b) - Returns ``alpha*A*b`` or one of the other three variants - determined by ``side`` (A on left or right) and ``tA`` (transpose A). - Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if - ``A`` is unit-triangular (the diagonal is assumed to be all ones). + :: + + trmv(side, ul, tA, dA, alpha, A, b) + + Returns ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). + .. function:: trsv!(ul, tA, dA, A, b) - Overwrite ``b`` with the solution to ``A*x = b`` or one of the other two - variants determined by ``tA`` (transpose A) and ``ul`` (triangle of ``A`` - used). ``dA`` indicates if ``A`` is unit-triangular (the diagonal is assumed - to be all ones). Returns the updated ``b``. + :: + + trsv!(ul, tA, dA, A, b) + + Overwrite ``b`` with the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` triangular (the diagonal is assumed to be all ones). Returns the updated ``b``. + .. function:: trsv(ul, tA, dA, A, b) - Returns the solution to ``A*x = b`` or one of the other two variants - determined by ``tA`` (transpose A) and ``ul`` (triangle of ``A`` is used.) - ``dA`` indicates if ``A`` is unit-triangular (the diagonal is assumed to be - all ones). + :: + + trsv(ul, tA, dA, A, b) + + Returns the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` (triangle of diagonal is assumed to be all ones). + .. function:: blas_set_num_threads(n) + :: + + blas_set_num_threads(n) + Set the number of threads the BLAS library should use. + .. data:: I diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index 4dea80104eb4f..ff47749a1a9ec 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -11,30 +11,52 @@ Mathematical Operators .. function:: -(x) - Unary minus operator. + :: + + -(x, y) + + Subtraction operator. + .. _+: .. function:: +(x, y...) - Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. - ``+(x, y, z, ...)``. + :: + + +(x, y...) + + Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. ``+(x, y, z, ...)``. + .. _-: .. function:: -(x, y) + :: + + -(x, y) + Subtraction operator. + .. _*: .. function:: *(x, y...) - Multiplication operator. ``x*y*z*...`` calls this function with all arguments, i.e. - ``*(x, y, z, ...)``. + :: + + *(s, t) + + Concatenate strings. The ``*`` operator is an alias to this function. + .. _/: .. function:: /(x, y) - Right division operator: multiplication of ``x`` by the inverse of ``y`` on the right. - Gives floating-point results for integer arguments. + :: + + /(x, y) + + Right division operator: multiplication of ``x`` by the inverse of arguments. + .. _\\: .. function:: \\(x, y) @@ -45,27 +67,52 @@ Mathematical Operators .. _^: .. function:: ^(x, y) - Exponentiation operator. + :: + + ^(s, n) + + Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. + .. _.+: .. function:: .+(x, y) + :: + + .+(x, y) + Element-wise addition operator. + .. _.-: .. function:: .-(x, y) + :: + + .-(x, y) + Element-wise subtraction operator. + .. _.*: .. function:: .*(x, y) + :: + + .*(x, y) + Element-wise multiplication operator. + .. _./: .. function:: ./(x, y) + :: + + ./(x, y) + Element-wise right division operator. + .. _.\\: .. function:: .\\(x, y) @@ -75,103 +122,187 @@ Mathematical Operators .. _.^: .. function:: .^(x, y) + :: + + .^(x, y) + Element-wise exponentiation operator. + .. function:: fma(x, y, z) - Computes ``x*y+z`` without rounding the intermediate result - ``x*y``. On some systems this is significantly more expensive than - ``x*y+z``. ``fma`` is used to improve accuracy in certain - algorithms. See ``muladd``. + :: + + fma(x, y, z) + + Computes ``x*y+z`` without rounding the intermediate result algorithms. See ``muladd``. + .. function:: muladd(x, y, z) - Combined multiply-add, computes ``x*y+z`` in an efficient manner. - This may on some systems be equivalent to ``x*y+z``, or to - ``fma(x,y,z)``. ``muladd`` is used to improve performance. See - ``fma``. + :: + + muladd(x, y, z) + + Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``, or to + .. function:: div(x, y) - ÷(x, y) + :: + + div(x, y) + The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. + .. function:: fld(x, y) + :: + + fld(x, y) + Largest integer less than or equal to ``x/y``. + .. function:: cld(x, y) + :: + + cld(x, y) + Smallest integer larger than or equal to ``x/y``. + .. function:: mod(x, y) - Modulus after division, returning in the range [0,``y``), if ``y`` is - positive, or (``y``,0] if ``y`` is negative. + :: + + mod(x, y) + + Modulus after division, returning in the range [0,``y``), if ``y`` is positive, or (``y``,0] if ``y`` is negative. + .. function:: mod2pi(x) - Modulus after division by 2pi, returning in the range [0,2pi). - - This function computes a floating point representation of the modulus after - division by numerically exact 2pi, and is therefore not exactly the same as - mod(x,2pi), which would compute the modulus of x relative to division by the - floating-point number 2pi. + :: + + mod2pi(x) + + Modulus after division by 2pi, returning in the range [0,2pi). This function computes a floating point representation of the modulus after division by numerically exact 2pi, and is therefore not exactly the same as mod(x,2pi), which would compute the modulus of x relative to division by the floating-point number 2pi. + .. function:: rem(x, y) - %(x, y) - Remainder from Euclidean division, returning a value of the same sign - as``x``, and smaller in magnitude than ``y``. This value is always exact. + :: + + rem(x, y) + + Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than ``y``. This value is always exact. + .. function:: divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to ``(x÷y, x%y)``. + :: + + divrem(x, y) + + The quotient and remainder from Euclidean division. Equivalent to + .. function:: fldmod(x, y) - The floored quotient and modulus after division. Equivalent to ``(fld(x,y), mod(x,y))``. + :: + + fldmod(x, y) + + The floored quotient and modulus after division. Equivalent to + .. function:: mod1(x,m) + :: + + mod1(x, m) + Modulus after division, returning in the range (0,m] + .. function:: rem1(x,m) + :: + + rem1(x, m) + Remainder after division, returning in the range (0,m] + .. _//: .. function:: //(num, den) + :: + + //(num, den) + Divide two integers or rational numbers, giving a ``Rational`` result. + .. function:: rationalize([Type=Int,] x; tol=eps(x)) - Approximate floating point number ``x`` as a Rational number with components of the given - integer type. The result will differ from ``x`` by no more than ``tol``. + :: + + rationalize([Type=Int], x; tol=eps(x)) + + Approximate floating point number ``x`` as a Rational number with components of the given integer type. The result will differ from + .. function:: num(x) + :: + + num(x) + Numerator of the rational representation of ``x`` + .. function:: den(x) + :: + + den(x) + Denominator of the rational representation of ``x`` + .. _<<: .. function:: <<(x, n) + :: + + <<(x, n) + Left bit shift operator. + .. _>>: .. function:: >>(x, n) + :: + + >>(x, n) + Right bit shift operator, preserving the sign of ``x``. + .. _>>>: .. function:: >>>(x, n) + :: + + >>>(x, n) + Unsigned right bit shift operator. + .. _\:: .. function:: \:(start, [step], stop) @@ -183,138 +314,220 @@ Mathematical Operators .. function:: colon(start, [step], stop) + :: + + colon(start[, step], stop) + Called by ``:`` syntax for constructing ranges. + .. function:: range(start, [step], length) + :: + + range(start[, step], length) + Construct a range by length, given a starting value and optional step (defaults to 1). + .. _==: .. function:: ==(x, y) - Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``. - Should be implemented for all types with a notion of equality, based - on the abstract value that an instance represents. For example, all numeric types are compared - by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring - encoding. - - Follows IEEE semantics for floating-point numbers. - - Collections should generally implement ``==`` by calling ``==`` recursively on all contents. - - New numeric types should implement this function for two arguments of the new type, and handle - comparison to other types via promotion rules where possible. + :: + + ==(x, y) + + Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``. Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. Follows IEEE semantics for floating-point numbers. Collections should generally implement ``==`` by calling ``==`` recursively on all contents. New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible. + .. _!=: .. function:: !=(x, y) - ≠(x,y) - Not-equals comparison operator. Always gives the opposite answer as ``==``. - New types should generally not implement this, and rely on the fallback - definition ``!=(x,y) = !(x==y)`` instead. + :: + + !=(x, y) + + Not-equals comparison operator. Always gives the opposite answer as the fallback definition ``!=(x,y) = !(x==y)`` instead. + .. _===: .. function:: ===(x, y) - ≡(x,y) - See the :func:`is` operator + :: + + ===(x, y) + + See the ``is()`` operator + .. _!==: .. function:: !==(x, y) - ≢(x,y) + :: + + !==(x, y) + Equivalent to ``!is(x, y)`` + .. _<: .. function:: <(x, y) - Less-than comparison operator. New numeric types should implement this function - for two arguments of the new type. - Because of the behavior of floating-point NaN values, ``<`` implements a - partial order. Types with a canonical partial order should implement ``<``, and - types with a canonical total order should implement ``isless``. + :: + + <(x, y) + + Less-than comparison operator. New numeric types should implement this function for two arguments of the new type. Because of the behavior of floating-point NaN values, ``<`` implements a partial order. Types with a canonical partial order should implement ``<``, and types with a canonical total order should implement ``isless``. + .. _<=: .. function:: <=(x, y) - ≤(x,y) + :: + + <=(x, y) + Less-than-or-equals comparison operator. + .. _>: .. function:: >(x, y) - Greater-than comparison operator. Generally, new types should implement ``<`` - instead of this function, and rely on the fallback definition ``>(x,y) = y(x, y) + + Greater-than comparison operator. Generally, new types should implement ``<`` instead of this function, and rely on the fallback definition ``>(x,y) = y=: .. function:: >=(x, y) - ≥(x,y) + :: + + >=(x, y) + Greater-than-or-equals comparison operator. + .. _.==: .. function:: .==(x, y) + :: + + .==(x, y) + Element-wise equality comparison operator. + .. _.!=: .. function:: .!=(x, y) - .≠(x,y) + :: + + .!=(x, y) + Element-wise not-equals comparison operator. + .. _.<: .. function:: .<(x, y) + :: + + .<(x, y) + Element-wise less-than comparison operator. + .. _.<=: .. function:: .<=(x, y) - .≤(x,y) + :: + + .<=(x, y) + Element-wise less-than-or-equals comparison operator. + .. _.>: .. function:: .>(x, y) + :: + + .>(x, y) + Element-wise greater-than comparison operator. + .. _.>=: .. function:: .>=(x, y) - .≥(x,y) + :: + + .>=(x, y) + Element-wise greater-than-or-equals comparison operator. + .. function:: cmp(x,y) - Return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater - than ``y``, respectively. Uses the total order implemented by ``isless``. For - floating-point numbers, uses ``<`` but throws an error for unordered arguments. + :: + + cmp(x, y) + + Return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``, respectively. Uses the total order implemented by ``isless``. For floating-point numbers, uses ``<`` but throws an error for unordered arguments. + .. _~: .. function:: ~(x) + :: + + ~(x) + Bitwise not + .. _&: .. function:: &(x, y) + :: + + &(x, y) + Bitwise and + .. _|: .. function:: |(x, y) + :: + + |(x, y) + Bitwise or + .. _$: .. function:: $(x, y) + :: + + \$(x, y) + Bitwise exclusive or + .. _!: .. function:: !(x) + :: + + !(x) + Boolean not + .. _&&: .. function:: x && y @@ -328,371 +541,699 @@ Mathematical Operators .. function:: A_ldiv_Bc(a,b) - Matrix operator A \\ B\ :sup:`H` + :: + + A_ldiv_Bc(a, b) + + Matrix operator A \ B^H + .. function:: A_ldiv_Bt(a,b) - Matrix operator A \\ B\ :sup:`T` + :: + + A_ldiv_Bt(a, b) + + Matrix operator A \ B^T + .. function:: A_mul_B!(Y, A, B) -> Y - - Calculates the matrix-matrix or matrix-vector product *A B* and stores the - result in *Y*, overwriting the existing value of *Y*. - - .. doctest:: - - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); - - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 + :: + + A_mul_B!(Y, A, B) -> Y + + Calculates the matrix-matrix or matrix-vector product *A B* and stores the result in *Y*, overwriting the existing value of *Y*. + .. function:: A_mul_Bc(...) - Matrix operator A B\ :sup:`H` + :: + + A_mul_Bc(...) + + Matrix operator A B^H + .. function:: A_mul_Bt(...) - Matrix operator A B\ :sup:`T` + :: + + A_mul_Bt(...) + + Matrix operator A B^T + .. function:: A_rdiv_Bc(...) - Matrix operator A / B\ :sup:`H` + :: + + A_rdiv_Bc(...) + + Matrix operator A / B^H + .. function:: A_rdiv_Bt(a,b) - Matrix operator A / B\ :sup:`T` + :: + + A_rdiv_Bt(a, b) + + Matrix operator A / B^T + .. function:: Ac_ldiv_B(...) - Matrix operator A\ :sup:`H` \\ B + :: + + Ac_ldiv_B(...) + + Matrix operator A^H \ B + .. function:: Ac_ldiv_Bc(...) - Matrix operator A\ :sup:`H` \\ B\ :sup:`H` + :: + + Ac_ldiv_Bc(...) + + Matrix operator A^H \ B^H + .. function:: Ac_mul_B(...) - Matrix operator A\ :sup:`H` B + :: + + Ac_mul_B(...) + + Matrix operator A^H B + .. function:: Ac_mul_Bc(...) - Matrix operator A\ :sup:`H` B\ :sup:`H` + :: + + Ac_mul_Bc(...) + + Matrix operator A^H B^H + .. function:: Ac_rdiv_B(a,b) - Matrix operator A\ :sup:`H` / B + :: + + Ac_rdiv_B(a, b) + + Matrix operator A^H / B + .. function:: Ac_rdiv_Bc(a,b) - Matrix operator A\ :sup:`H` / B\ :sup:`H` + :: + + Ac_rdiv_Bc(a, b) + + Matrix operator A^H / B^H + .. function:: At_ldiv_B(...) - Matrix operator A\ :sup:`T` \\ B + :: + + At_ldiv_B(...) + + Matrix operator A^T \ B + .. function:: At_ldiv_Bt(...) - Matrix operator A\ :sup:`T` \\ B\ :sup:`T` + :: + + At_ldiv_Bt(...) + + Matrix operator A^T \ B^T + .. function:: At_mul_B(...) - Matrix operator A\ :sup:`T` B + :: + + At_mul_B(...) + + Matrix operator A^T B + .. function:: At_mul_Bt(...) - Matrix operator A\ :sup:`T` B\ :sup:`T` + :: + + At_mul_Bt(...) + + Matrix operator A^T B^T + .. function:: At_rdiv_B(a,b) - Matrix operator A\ :sup:`T` / B + :: + + At_rdiv_B(a, b) + + Matrix operator A^T / B + .. function:: At_rdiv_Bt(a,b) - Matrix operator A\ :sup:`T` / B\ :sup:`T` - + :: + + At_rdiv_Bt(a, b) + + Matrix operator A^T / B^T + Mathematical Functions ---------------------- .. function:: isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - Inexact equality comparison - behaves slightly different depending on types of input args: - - * For ``FloatingPoint`` numbers, ``isapprox`` returns ``true`` if ``abs(x-y) <= atol + rtol*max(abs(x), abs(y))``. - - * For ``Integer`` and ``Rational`` numbers, ``isapprox`` returns ``true`` if ``abs(x-y) <= atol``. The `rtol` argument is ignored. If one of ``x`` and ``y`` is ``FloatingPoint``, the other is promoted, and the method above is called instead. - - * For ``Complex`` numbers, the distance in the complex plane is compared, using the same criterion as above. - - For default tolerance arguments, ``maxeps = max(eps(abs(x)), eps(abs(y)))``. + :: + + isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + + Inexact equality comparison - behaves slightly different depending on types of input args: For default tolerance arguments, ``maxeps = max(eps(abs(x)), eps(abs(y)))``. + .. function:: sin(x) + :: + + sin(x) + Compute sine of ``x``, where ``x`` is in radians + .. function:: cos(x) + :: + + cos(x) + Compute cosine of ``x``, where ``x`` is in radians + .. function:: tan(x) + :: + + tan(x) + Compute tangent of ``x``, where ``x`` is in radians + .. function:: sind(x) + :: + + sind(x) + Compute sine of ``x``, where ``x`` is in degrees + .. function:: cosd(x) + :: + + cosd(x) + Compute cosine of ``x``, where ``x`` is in degrees + .. function:: tand(x) + :: + + tand(x) + Compute tangent of ``x``, where ``x`` is in degrees + .. function:: sinpi(x) - Compute :math:`\sin(\pi x)` more accurately than ``sin(pi*x)``, especially for large ``x``. + :: + + sinpi(x) + + Compute \sin(\pi x) more accurately than ``sin(pi*x)``, especially for large ``x``. + .. function:: cospi(x) - Compute :math:`\cos(\pi x)` more accurately than ``cos(pi*x)``, especially for large ``x``. + :: + + cospi(x) + + Compute \cos(\pi x) more accurately than ``cos(pi*x)``, especially for large ``x``. + .. function:: sinh(x) + :: + + sinh(x) + Compute hyperbolic sine of ``x`` + .. function:: cosh(x) + :: + + cosh(x) + Compute hyperbolic cosine of ``x`` + .. function:: tanh(x) + :: + + tanh(x) + Compute hyperbolic tangent of ``x`` + .. function:: asin(x) + :: + + asin(x) + Compute the inverse sine of ``x``, where the output is in radians + .. function:: acos(x) + :: + + acos(x) + Compute the inverse cosine of ``x``, where the output is in radians + .. function:: atan(x) + :: + + atan(x) + Compute the inverse tangent of ``x``, where the output is in radians + .. function:: atan2(y, x) - Compute the inverse tangent of ``y/x``, using the signs of both ``x`` and ``y`` to determine the quadrant of the return value. + :: + + atan2(y, x) + + Compute the inverse tangent of ``y/x``, using the signs of both + .. function:: asind(x) + :: + + asind(x) + Compute the inverse sine of ``x``, where the output is in degrees + .. function:: acosd(x) + :: + + acosd(x) + Compute the inverse cosine of ``x``, where the output is in degrees + .. function:: atand(x) + :: + + atand(x) + Compute the inverse tangent of ``x``, where the output is in degrees + .. function:: sec(x) + :: + + sec(x) + Compute the secant of ``x``, where ``x`` is in radians + .. function:: csc(x) + :: + + csc(x) + Compute the cosecant of ``x``, where ``x`` is in radians + .. function:: cot(x) + :: + + cot(x) + Compute the cotangent of ``x``, where ``x`` is in radians + .. function:: secd(x) + :: + + secd(x) + Compute the secant of ``x``, where ``x`` is in degrees + .. function:: cscd(x) + :: + + cscd(x) + Compute the cosecant of ``x``, where ``x`` is in degrees + .. function:: cotd(x) + :: + + cotd(x) + Compute the cotangent of ``x``, where ``x`` is in degrees + .. function:: asec(x) + :: + + asec(x) + Compute the inverse secant of ``x``, where the output is in radians + .. function:: acsc(x) + :: + + acsc(x) + Compute the inverse cosecant of ``x``, where the output is in radians + .. function:: acot(x) + :: + + acot(x) + Compute the inverse cotangent of ``x``, where the output is in radians + .. function:: asecd(x) + :: + + asecd(x) + Compute the inverse secant of ``x``, where the output is in degrees + .. function:: acscd(x) + :: + + acscd(x) + Compute the inverse cosecant of ``x``, where the output is in degrees + .. function:: acotd(x) + :: + + acotd(x) + Compute the inverse cotangent of ``x``, where the output is in degrees + .. function:: sech(x) + :: + + sech(x) + Compute the hyperbolic secant of ``x`` + .. function:: csch(x) + :: + + csch(x) + Compute the hyperbolic cosecant of ``x`` + .. function:: coth(x) + :: + + coth(x) + Compute the hyperbolic cotangent of ``x`` + .. function:: asinh(x) + :: + + asinh(x) + Compute the inverse hyperbolic sine of ``x`` + .. function:: acosh(x) + :: + + acosh(x) + Compute the inverse hyperbolic cosine of ``x`` + .. function:: atanh(x) + :: + + atanh(x) + Compute the inverse hyperbolic tangent of ``x`` + .. function:: asech(x) + :: + + asech(x) + Compute the inverse hyperbolic secant of ``x`` + .. function:: acsch(x) + :: + + acsch(x) + Compute the inverse hyperbolic cosecant of ``x`` + .. function:: acoth(x) + :: + + acoth(x) + Compute the inverse hyperbolic cotangent of ``x`` + .. function:: sinc(x) - Compute :math:`\sin(\pi x) / (\pi x)` if :math:`x \neq 0`, and :math:`1` if :math:`x = 0`. + :: + + sinc(x) + + Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. + .. function:: cosc(x) - Compute :math:`\cos(\pi x) / x - \sin(\pi x) / (\pi x^2)` if :math:`x \neq 0`, and :math:`0` - if :math:`x = 0`. This is the derivative of ``sinc(x)``. + :: + + cosc(x) + + Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq 0, and 0 if x = 0. This is the derivative of ``sinc(x)``. + .. function:: deg2rad(x) + :: + + deg2rad(x) + Convert ``x`` from degrees to radians + .. function:: rad2deg(x) + :: + + rad2deg(x) + Convert ``x`` from radians to degrees + .. function:: hypot(x, y) - Compute the :math:`\sqrt{x^2+y^2}` avoiding overflow and underflow + :: + + hypot(x, y) + + Compute the \sqrt{x^2+y^2} avoiding overflow and underflow + .. function:: log(x) - Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative - ``Real`` arguments. Use complex negative arguments to obtain complex - results. - - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. + :: + + log(b, x) + + Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. + .. function:: log(b,x) + :: + + log(b, x) + Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. + .. function:: log2(x) + :: + + log2(x) + Compute the logarithm of ``x`` to base 2. Throws ``DomainError`` for negative ``Real`` arguments. + .. function:: log10(x) + :: + + log10(x) + Compute the logarithm of ``x`` to base 10. Throws ``DomainError`` for negative ``Real`` arguments. + .. function:: log1p(x) - Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for ``Real`` arguments less than -1. - - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. + :: + + log1p(x) + + Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. + .. function:: frexp(val) - Return ``(x,exp)`` such that ``x`` has a magnitude in the interval ``[1/2, 1)`` or 0, - and val = :math:`x \times 2^{exp}`. + :: + + frexp(val) + + Return ``(x,exp)`` such that ``x`` has a magnitude in the interval + .. function:: exp(x) - Compute :math:`e^x` + :: + + exp(x) + + Compute e^x + .. function:: exp2(x) - Compute :math:`2^x` + :: + + exp2(x) + + Compute 2^x + .. function:: exp10(x) - Compute :math:`10^x` + :: + + exp10(x) + + Compute 10^x + .. function:: ldexp(x, n) - Compute :math:`x \times 2^n` + :: + + ldexp(x, n) + + Compute x \times 2^n + .. function:: modf(x) - Return a tuple (fpart,ipart) of the fractional and integral parts of a - number. Both parts have the same sign as the argument. + :: + + modf(x) + + Return a tuple (fpart,ipart) of the fractional and integral parts of a number. Both parts have the same sign as the argument. + .. function:: expm1(x) - Accurately compute :math:`e^x-1` + :: + + expm1(x) + + Accurately compute e^x-1 + .. function:: round([T,] x, [digits, [base]], [r::RoundingMode]) - ``round(x)`` rounds ``x`` to an integer value according to the default - rounding mode (see :func:`get_rounding`), returning a value of the same type as - ``x``. By default (:obj:`RoundNearest`), this will round to the nearest - integer, with ties (fractional values of 0.5) being rounded to the even - integer. - - .. doctest:: - - julia> round(1.7) - 2.0 - - julia> round(1.5) - 2.0 - - julia> round(2.5) - 2.0 - - The optional :obj:`RoundingMode` argument will change how the number gets rounded. - - ``round(T, x, [r::RoundingMode])`` converts the result to type ``T``, throwing an - :exc:`InexactError` if the value is not representable. - - ``round(x, digits)`` rounds to the specified number of digits after the - decimal place (or before if negative). ``round(x, digits, base)`` rounds - using a base other than 10. - - .. doctest:: + :: + + round(z, RoundingModeReal, RoundingModeImaginary) + + Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. + julia> round(pi, 2) 3.14 @@ -761,592 +1302,999 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex-valued - ``z`` to ``z``, breaking ties using the specified :obj:`RoundingMode`\ s. - The first :obj:`RoundingMode` is used for rounding the real components while - the second is used for rounding the imaginary components. + :: + + round(z, RoundingModeReal, RoundingModeImaginary) + + Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. + .. function:: ceil([T,] x, [digits, [base]]) - ``ceil(x)`` returns the nearest integral value of the same type as ``x`` - that is greater than or equal to ``x``. - - ``ceil(T, x)`` converts the result to type ``T``, throwing an - ``InexactError`` if the value is not representable. - - ``digits`` and ``base`` work as for :func:`round`. + :: + + ceil([T], x[, digits[, base]]) + .. function:: floor([T,] x, [digits, [base]]) - ``floor(x)`` returns the nearest integral value of the same type as ``x`` - that is less than or equal to ``x``. - - ``floor(T, x)`` converts the result to type ``T``, throwing an - ``InexactError`` if the value is not representable. - - ``digits`` and ``base`` work as for :func:`round`. + :: + + floor([T], x[, digits[, base]]) + .. function:: trunc([T,] x, [digits, [base]]) - ``trunc(x)`` returns the nearest integral value of the same type as ``x`` whose absolute - value is less than or equal to ``x``. - - ``trunc(T, x)`` converts the result to type ``T``, throwing an - ``InexactError`` if the value is not representable. - - ``digits`` and ``base`` work as for :func:`round`. + :: + + trunc([T], x[, digits[, base]]) + .. function:: unsafe_trunc(T, x) - ``unsafe_trunc(T, x)`` returns the nearest integral value of type ``T`` whose absolute - value is less than or equal to ``x``. If the value is not representable by - ``T``, an arbitrary value will be returned. + :: + + unsafe_trunc(T, x) + + value is not representable by ``T``, an arbitrary value will be returned. + .. function:: signif(x, digits, [base]) - Rounds (in the sense of ``round``) ``x`` so that there are ``digits`` significant digits, under a base ``base`` representation, default 10. E.g., ``signif(123.456, 2)`` is ``120.0``, and ``signif(357.913, 4, 2)`` is ``352.0``. + :: + + signif(x, digits[, base]) + + Rounds (in the sense of ``round``) ``x`` so that there are representation, default 10. E.g., ``signif(123.456, 2)`` is + .. function:: min(x, y, ...) + :: + + min(x, y, ...) + Return the minimum of the arguments. Operates elementwise over arrays. + .. function:: max(x, y, ...) + :: + + max(x, y, ...) + Return the maximum of the arguments. Operates elementwise over arrays. + .. function:: minmax(x, y) - Return ``(min(x,y), max(x,y))``. - See also: :func:`extrema` that returns ``(minimum(x), maximum(x))`` + :: + + minmax(x, y) + + Return ``(min(x,y), max(x,y))``. See also: ``extrema()`` that returns ``(minimum(x), maximum(x))`` + .. function:: clamp(x, lo, hi) - Return x if ``lo <= x <= hi``. If ``x < lo``, return ``lo``. If ``x > hi``, return ``hi``. Arguments are promoted to a common type. Operates elementwise over ``x`` if it is an array. + :: + + clamp(x, lo, hi) + + Return x if ``lo <= x <= hi``. If ``x < lo``, return ``lo``. If ``x Operates elementwise over `x`` if it is an array. + .. function:: abs(x) + :: + + abs(x) + Absolute value of ``x`` + .. function:: abs2(x) + :: + + abs2(x) + Squared absolute value of ``x`` + .. function:: copysign(x, y) + :: + + copysign(x, y) + Return ``x`` such that it has the same sign as ``y`` + .. function:: sign(x) + :: + + sign(x) + Return ``+1`` if ``x`` is positive, ``0`` if ``x == 0``, and ``-1`` if ``x`` is negative. + .. function:: signbit(x) + :: + + signbit(x) + Returns ``true`` if the value of the sign of ``x`` is negative, otherwise ``false``. + .. function:: flipsign(x, y) + :: + + flipsign(x, y) + Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``. + .. function:: sqrt(x) - Return :math:`\sqrt{x}`. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. The prefix operator ``√`` is equivalent to ``sqrt``. + :: + + sqrt(x) + + Return \sqrt{x}. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. The prefix operator ``√`` is equivalent to ``sqrt``. + .. function:: isqrt(n) + :: + + isqrt(n) + Integer square root: the largest integer ``m`` such that ``m*m <= n``. + .. function:: cbrt(x) - Return :math:`x^{1/3}`. The prefix operator ``∛`` is equivalent to ``cbrt``. + :: + + cbrt(x) + + Return x^{1/3}. The prefix operator ``∛`` is equivalent to + .. function:: erf(x) + :: + + erf(x) + Compute the error function of ``x``, defined by - :math:`\frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt` - for arbitrary complex ``x``. + .. function:: erfc(x) - Compute the complementary error function of ``x``, - defined by :math:`1 - \operatorname{erf}(x)`. + :: + + erfc(x) + + Compute the complementary error function of ``x``, defined by 1 - + .. function:: erfcx(x) - Compute the scaled complementary error function of ``x``, - defined by :math:`e^{x^2} \operatorname{erfc}(x)`. Note - also that :math:`\operatorname{erfcx}(-ix)` computes the - Faddeeva function :math:`w(x)`. + :: + + erfcx(x) + + Compute the scaled complementary error function of ``x``, defined by e^{x^2} \operatorname{erfc}(x). Note also that + .. function:: erfi(x) - Compute the imaginary error function of ``x``, - defined by :math:`-i \operatorname{erf}(ix)`. + :: + + erfi(x) + + Compute the imaginary error function of ``x``, defined by -i + .. function:: dawson(x) - Compute the Dawson function (scaled imaginary error function) of ``x``, - defined by :math:`\frac{\sqrt{\pi}}{2} e^{-x^2} \operatorname{erfi}(x)`. + :: + + dawson(x) + + Compute the Dawson function (scaled imaginary error function) of + .. function:: erfinv(x) - Compute the inverse error function of a real ``x``, - defined by :math:`\operatorname{erf}(\operatorname{erfinv}(x)) = x`. + :: + + erfinv(x) + + Compute the inverse error function of a real ``x``, defined by + .. function:: erfcinv(x) - Compute the inverse error complementary function of a real ``x``, - defined by :math:`\operatorname{erfc}(\operatorname{erfcinv}(x)) = x`. + :: + + erfcinv(x) + + Compute the inverse error complementary function of a real ``x``, defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. + .. function:: real(z) + :: + + real(z) + Return the real part of the complex number ``z`` + .. function:: imag(z) + :: + + imag(z) + Return the imaginary part of the complex number ``z`` + .. function:: reim(z) - Return both the real and imaginary parts of the complex number ``z`` + :: + + reim(z) + + Return both the real and imaginary parts of the complex number + .. function:: conj(z) + :: + + conj(z) + Compute the complex conjugate of a complex number ``z`` + .. function:: angle(z) + :: + + angle(z) + Compute the phase angle in radians of a complex number ``z`` + .. function:: cis(z) - Return :math:`\exp(iz)`. + :: + + cis(z) + + Return \exp(iz). + .. function:: binomial(n,k) + :: + + binomial(n, k) + Number of ways to choose ``k`` out of ``n`` items + .. function:: factorial(n) - Factorial of ``n``. If ``n`` is an :obj:`Integer`, the factorial - is computed as an integer (promoted to at least 64 bits). Note - that this may overflow if ``n`` is not small, but you can use - ``factorial(big(n))`` to compute the result exactly in arbitrary - precision. If ``n`` is not an ``Integer``, ``factorial(n)`` is - equivalent to :func:`gamma(n+1) `. + :: + + factorial(n, k) + + Compute ``factorial(n)/factorial(k)`` + .. function:: factorial(n,k) + :: + + factorial(n, k) + Compute ``factorial(n)/factorial(k)`` + .. function:: factor(n) -> Dict + :: + + factor(n) -> Dict + Compute the prime factorization of an integer ``n``. Returns a dictionary. The keys of the dictionary correspond to the factors, and hence are of the same type as ``n``. The value associated with each key indicates the number of times the factor appears in the factorization. - - .. doctest:: - - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 + .. function:: gcd(x,y) + :: + + gcd(x, y) + Greatest common (positive) divisor (or zero if x and y are both zero). + .. function:: lcm(x,y) + :: + + lcm(x, y) + Least common (non-negative) multiple. + .. function:: gcdx(x,y) - Computes the greatest common (positive) divisor of ``x`` and ``y`` and their Bézout coefficients, i.e. the integer coefficients ``u`` and ``v`` that satisfy :math:`ux+vy = d = gcd(x,y)`. - - .. doctest:: - - julia> gcdx(12, 42) - (6,-3,1) - - .. doctest:: - - julia> gcdx(240, 46) - (2,-9,47) - - .. note:: - - Bézout coefficients are *not* uniquely defined. ``gcdx`` returns the minimal Bézout coefficients that are computed by the extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, Algorithm X.) These coefficients ``u`` and ``v`` are minimal in the sense that :math:`|u| < |\frac y d` and :math:`|v| < |\frac x d`. Furthermore, the signs of ``u`` and ``v`` are chosen so that ``d`` is positive. + :: + + gcdx(x, y) + + Computes the greatest common (positive) divisor of ``x`` and ``y`` and their Bézout coefficients, i.e. the integer coefficients ``u`` and ``v`` that satisfy ux+vy = d = gcd(x,y). Note: Bézout coefficients are *not* uniquely defined. ``gcdx`` + .. function:: ispow2(n) -> Bool + :: + + ispow2(n) -> Bool + Test whether ``n`` is a power of two + .. function:: nextpow2(n) - The smallest power of two not less than ``n``. Returns 0 for ``n==0``, and returns - ``-nextpow2(-n)`` for negative arguments. + :: + + nextpow2(n) + + The smallest power of two not less than ``n``. Returns 0 for + .. function:: prevpow2(n) - The largest power of two not greater than ``n``. Returns 0 for ``n==0``, and returns - ``-prevpow2(-n)`` for negative arguments. + :: + + prevpow2(n) + + The largest power of two not greater than ``n``. Returns 0 for + .. function:: nextpow(a, x) - The smallest ``a^n`` not less than ``x``, where ``n`` is a non-negative integer. - ``a`` must be greater than 1, and ``x`` must be greater than 0. + :: + + nextpow(a, x) + + The smallest ``a^n`` not less than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must be greater than 0. + .. function:: prevpow(a, x) - The largest ``a^n`` not greater than ``x``, where ``n`` is a non-negative integer. - ``a`` must be greater than 1, and ``x`` must not be less than 1. + :: + + prevpow(a, x) + + The largest ``a^n`` not greater than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must not be less than 1. + .. function:: nextprod([k_1,k_2,...], n) - Next integer not less than ``n`` that can be written as :math:`\prod k_i^{p_i}` for integers :math:`p_1`, :math:`p_2`, etc. + :: + + nextprod([k_1, k_2, ...], n) + + Next integer not less than ``n`` that can be written as \prod k_i^{p_i} for integers p_1, p_2, etc. + .. function:: prevprod([k_1,k_2,...], n) - Previous integer not greater than ``n`` that can be written as :math:`\prod k_i^{p_i}` for integers :math:`p_1`, :math:`p_2`, etc. + :: + + prevprod([k_1, k_2, ...], n) + + Previous integer not greater than ``n`` that can be written as + .. function:: invmod(x,m) - Take the inverse of ``x`` modulo ``m``: ``y`` such that :math:`xy = 1 \pmod m` + :: + + invmod(x, m) + + Take the inverse of ``x`` modulo ``m``: ``y`` such that xy = 1 + .. function:: powermod(x, p, m) - Compute :math:`x^p \pmod m` + :: + + powermod(x, p, m) + + Compute x^p \pmod m + .. function:: gamma(x) + :: + + gamma(x) + Compute the gamma function of ``x`` + .. function:: lgamma(x) - Compute the logarithm of the absolute value of :func:`gamma` for - :obj:`Real` ``x``, while for :obj:`Complex` ``x`` it computes the - logarithm of ``gamma(x)``. + :: + + lgamma(x) + + Compute the logarithm of the absolute value of ``gamma()`` for logarithm of ``gamma(x)``. + .. function:: lfact(x) + :: + + lfact(x) + Compute the logarithmic factorial of ``x`` + .. function:: digamma(x) + :: + + digamma(x) + Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(x)``) + .. function:: invdigamma(x) + :: + + invdigamma(x) + Compute the inverse digamma function of ``x``. + .. function:: trigamma(x) + :: + + trigamma(x) + Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``) + .. function:: polygamma(m, x) - Compute the polygamma function of order ``m`` of argument ``x`` (the ``(m+1)th`` derivative of the logarithm of ``gamma(x)``) + :: + + polygamma(m, x) + + Compute the polygamma function of order ``m`` of argument ``x`` + .. function:: airy(k,x) - kth derivative of the Airy function :math:`\operatorname{Ai}(x)`. + :: + + airy(k, x) + + kth derivative of the Airy function \operatorname{Ai}(x). + .. function:: airyai(x) - Airy function :math:`\operatorname{Ai}(x)`. + :: + + airyai(x) + + Airy function \operatorname{Ai}(x). + .. function:: airyprime(x) - Airy function derivative :math:`\operatorname{Ai}'(x)`. + :: + + airyprime(x) + + Airy function derivative \operatorname{Ai}'(x). + .. function:: airyaiprime(x) - Airy function derivative :math:`\operatorname{Ai}'(x)`. + :: + + airyaiprime(x) + + Airy function derivative \operatorname{Ai}'(x). + .. function:: airybi(x) - Airy function :math:`\operatorname{Bi}(x)`. + :: + + airybi(x) + + Airy function \operatorname{Bi}(x). + .. function:: airybiprime(x) - Airy function derivative :math:`\operatorname{Bi}'(x)`. + :: + + airybiprime(x) + + Airy function derivative \operatorname{Bi}'(x). + .. function:: airyx(k,x) - scaled kth derivative of the Airy function, return :math:`\operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}}` for ``k == 0 || k == 1``, and :math:`\operatorname{Ai}(x) e^{- \left| \operatorname{Re} \left( \frac{2}{3} x \sqrt{x} \right) \right|}` for ``k == 2 || k == 3``. + :: + + airyx(k, x) + + scaled kth derivative of the Airy function, return k == 1``, and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} k == 3``. + .. function:: besselj0(x) - Bessel function of the first kind of order 0, :math:`J_0(x)`. + :: + + besselj0(x) + + Bessel function of the first kind of order 0, J_0(x). + .. function:: besselj1(x) - Bessel function of the first kind of order 1, :math:`J_1(x)`. + :: + + besselj1(x) + + Bessel function of the first kind of order 1, J_1(x). + .. function:: besselj(nu, x) - Bessel function of the first kind of order ``nu``, :math:`J_\nu(x)`. + :: + + besselj(nu, x) + + Bessel function of the first kind of order ``nu``, J_\nu(x). + .. function:: besseljx(nu, x) - Scaled Bessel function of the first kind of order ``nu``, :math:`J_\nu(x) e^{- | \operatorname{Im}(x) |}`. + :: + + besseljx(nu, x) + + Scaled Bessel function of the first kind of order ``nu``, J_\nu(x) e^{- | \operatorname{Im}(x) |}. + .. function:: bessely0(x) - Bessel function of the second kind of order 0, :math:`Y_0(x)`. + :: + + bessely0(x) + + Bessel function of the second kind of order 0, Y_0(x). + .. function:: bessely1(x) - Bessel function of the second kind of order 1, :math:`Y_1(x)`. + :: + + bessely1(x) + + Bessel function of the second kind of order 1, Y_1(x). + .. function:: bessely(nu, x) - Bessel function of the second kind of order ``nu``, :math:`Y_\nu(x)`. + :: + + bessely(nu, x) + + Bessel function of the second kind of order ``nu``, Y_\nu(x). + .. function:: besselyx(nu, x) - Scaled Bessel function of the second kind of order ``nu``, :math:`Y_\nu(x) e^{- | \operatorname{Im}(x) |}`. + :: + + besselyx(nu, x) + + Scaled Bessel function of the second kind of order ``nu``, Y_\nu(x) e^{- | \operatorname{Im}(x) |}. + .. function:: hankelh1(nu, x) - Bessel function of the third kind of order ``nu``, :math:`H^{(1)}_\nu(x)`. + :: + + hankelh1(nu, x) + + Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x). + .. function:: hankelh1x(nu, x) - Scaled Bessel function of the third kind of order ``nu``, :math:`H^{(1)}_\nu(x) e^{-x i}`. + :: + + hankelh1x(nu, x) + + Scaled Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x) e^{-x i}. + .. function:: hankelh2(nu, x) - Bessel function of the third kind of order ``nu``, :math:`H^{(2)}_\nu(x)`. + :: + + hankelh2(nu, x) + + Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x). + .. function:: hankelh2x(nu, x) - Scaled Bessel function of the third kind of order ``nu``, :math:`H^{(2)}_\nu(x) e^{x i}`. + :: + + hankelh2x(nu, x) + + Scaled Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x) e^{x i}. + .. function:: besselh(nu, k, x) - Bessel function of the third kind of order ``nu`` (Hankel function). - ``k`` is either 1 or 2, selecting ``hankelh1`` or ``hankelh2``, respectively. + :: + + besselh(nu, k, x) + + Bessel function of the third kind of order ``nu`` (Hankel function). ``k`` is either 1 or 2, selecting ``hankelh1`` or + .. function:: besseli(nu, x) - Modified Bessel function of the first kind of order ``nu``, :math:`I_\nu(x)`. + :: + + besseli(nu, x) + + Modified Bessel function of the first kind of order ``nu``, I_\nu(x). + .. function:: besselix(nu, x) - Scaled modified Bessel function of the first kind of order ``nu``, :math:`I_\nu(x) e^{- | \operatorname{Re}(x) |}`. + :: + + besselix(nu, x) + + Scaled modified Bessel function of the first kind of order ``nu``, I_\nu(x) e^{- | \operatorname{Re}(x) |}. + .. function:: besselk(nu, x) - Modified Bessel function of the second kind of order ``nu``, :math:`K_\nu(x)`. + :: + + besselk(nu, x) + + Modified Bessel function of the second kind of order ``nu``, K_\nu(x). + .. function:: besselkx(nu, x) - Scaled modified Bessel function of the second kind of order ``nu``, :math:`K_\nu(x) e^x`. + :: + + besselkx(nu, x) + + Scaled modified Bessel function of the second kind of order ``nu``, K_\nu(x) e^x. + .. function:: beta(x, y) - Euler integral of the first kind :math:`\operatorname{B}(x,y) = \Gamma(x)\Gamma(y)/\Gamma(x+y)`. + :: + + beta(x, y) + + Euler integral of the first kind \operatorname{B}(x,y) = + .. function:: lbeta(x, y) - Natural logarithm of the absolute value of the beta function :math:`\log(|\operatorname{B}(x,y)|)`. + :: + + lbeta(x, y) + + Natural logarithm of the absolute value of the beta function + .. function:: eta(x) - Dirichlet eta function :math:`\eta(s) = \sum^\infty_{n=1}(-)^{n-1}/n^{s}`. + :: + + eta(x) + + Dirichlet eta function \eta(s) = + .. function:: zeta(s) - Riemann zeta function :math:`\zeta(s)`. + :: + + zeta(s, z) + + Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) + .. function:: zeta(s, z) - Hurwitz zeta function :math:`\zeta(s, z)`. (This is equivalent to - the Riemann zeta function :math:`\zeta(s)` for the case of ``z=1``.) + :: + + zeta(s, z) + + Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) + .. function:: ndigits(n, b) + :: + + ndigits(n, b) + Compute the number of digits in number ``n`` written in base ``b``. + .. function:: widemul(x, y) + :: + + widemul(x, y) + Multiply ``x`` and ``y``, giving the result as a larger type. + .. function:: @evalpoly(z, c...) - Evaluate the polynomial :math:`\sum_k c[k] z^{k-1}` for the - coefficients ``c[1]``, ``c[2]``, ...; that is, the coefficients are - given in ascending order by power of ``z``. This macro expands to - efficient inline code that uses either Horner's method or, for - complex ``z``, a more efficient Goertzel-like algorithm. + :: + + @evalpoly(z, c...) + + Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients ascending order by power of ``z``. This macro expands to efficient inline code that uses either Horner's method or, for complex ``z``, a more efficient Goertzel-like algorithm. + Statistics ---------- .. function:: mean(v[, region]) - Compute the mean of whole array ``v``, or optionally along the dimensions in ``region``. - Note: Julia does not ignore ``NaN`` values in the computation. - For applications requiring the handling of missing data, the ``DataArray`` - package is recommended. + :: + + mean(v[, region]) + + Compute the mean of whole array ``v``, or optionally along the dimensions in ``region``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. + .. function:: mean!(r, v) + :: + + mean!(r, v) + Compute the mean of ``v`` over the singleton dimensions of ``r``, and write results to ``r``. + .. function:: std(v[, region]) - Compute the sample standard deviation of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``. - Note: Julia does not ignore ``NaN`` values in the computation. - For applications requiring the handling of missing data, the ``DataArray`` - package is recommended. + :: + + std(v[, region]) + + Compute the sample standard deviation of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the + .. function:: stdm(v, m) - Compute the sample standard deviation of a vector ``v`` with known mean ``m``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + stdm(v, m) + + Compute the sample standard deviation of a vector ``v`` with known mean ``m``. Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: var(v[, region]) - Compute the sample variance of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``. - Note: Julia does not ignore ``NaN`` values in the computation. - For applications requiring the handling of missing data, the ``DataArray`` - package is recommended. + :: + + var(v[, region]) + + Compute the sample variance of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the + .. function:: varm(v, m) - Compute the sample variance of a vector ``v`` with known mean ``m``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + varm(v, m) + + Compute the sample variance of a vector ``v`` with known mean computation. + .. function:: middle(x) - Compute the middle of a scalar value, which is equivalent to ``x`` itself, - but of the type of ``middle(x, x)`` for consistency. + :: + + middle(array) + + Compute the middle of an array, which consists in finding its extrema and then computing their mean. + .. function:: middle(x, y) - Compute the middle of two reals ``x`` and ``y``, which is equivalent - in both value and type to computing their mean (``(x + y) / 2``). + :: + + middle(array) + + Compute the middle of an array, which consists in finding its extrema and then computing their mean. + .. function:: middle(range) - Compute the middle of a range, which consists in computing the mean of its extrema. - Since a range is sorted, the mean is performed with the first and last element. + :: + + middle(array) + + Compute the middle of an array, which consists in finding its extrema and then computing their mean. + .. function:: middle(array) - Compute the middle of an array, which consists in finding its extrema and - then computing their mean. + :: + + middle(array) + + Compute the middle of an array, which consists in finding its extrema and then computing their mean. + .. function:: median(v) - Compute the median of a vector ``v``. ``NaN`` is returned if the data - contains any ``NaN`` values. For applications requiring the handling of - missing data, the ``DataArrays`` package is recommended. + :: + + median(v) + + Compute the median of a vector ``v``. ``NaN`` is returned if the data contains any ``NaN`` values. For applications requiring the handling of missing data, the ``DataArrays`` package is recommended. + .. function:: median!(v) + :: + + median!(v) + Like ``median``, but may overwrite the input vector. + .. function:: hist(v[, n]) -> e, counts - Compute the histogram of ``v``, optionally using approximately ``n`` - bins. The return values are a range ``e``, which correspond to the - edges of the bins, and ``counts`` containing the number of elements of - ``v`` in each bin. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + hist(v, e) -> e, counts + + Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: hist(v, e) -> e, counts - Compute the histogram of ``v`` using a vector/range ``e`` as the edges for - the bins. The result will be a vector of length ``length(e) - 1``, such that the - element at location ``i`` satisfies ``sum(e[i] .< v .<= e[i+1])``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + hist(v, e) -> e, counts + + Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: hist!(counts, v, e) -> e, counts - Compute the histogram of ``v``, using a vector/range ``e`` as the edges for the bins. - This function writes the resultant counts to a pre-allocated array ``counts``. + :: + + hist!(counts, v, e) -> e, counts + + Compute the histogram of ``v``, using a vector/range ``e`` as the edges for the bins. This function writes the resultant counts to a pre-allocated array ``counts``. + .. function:: hist2d(M, e1, e2) -> (edge1, edge2, counts) - Compute a "2d histogram" of a set of N points specified by N-by-2 matrix ``M``. - Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as - integer bin counts or vectors of bin edges. The result is a tuple of - ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges - used in the second dimension), and ``counts``, a histogram matrix of size - ``(length(edge1)-1, length(edge2)-1)``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + hist2d(M, e1, e2) -> (edge1, edge2, counts) + + Compute a ``2d histogram`` of a set of N points specified by N-by-2 matrix ``M``. Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as integer bin counts or vectors of bin edges. The result is a tuple of ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges used in the second dimension), and ``counts``, a histogram matrix of size + .. function:: hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - Compute a "2d histogram" with respect to the bins delimited by the edges given - in ``e1`` and ``e2``. This function writes the results to a pre-allocated - array ``counts``. + :: + + hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + + Compute a ``2d histogram`` with respect to the bins delimited by the edges given in ``e1`` and ``e2``. This function writes the results to a pre-allocated array ``counts``. + .. function:: histrange(v, n) - Compute *nice* bin ranges for the edges of a histogram of ``v``, using - approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 - multiplied by a power of 10. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + histrange(v, n) + + Compute *nice* bin ranges for the edges of a histogram of ``v``, using approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 multiplied by a power of 10. Note: Julia does not ignore + .. function:: midpoints(e) - Compute the midpoints of the bins with edges ``e``. The result is a - vector/range of length ``length(e) - 1``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + midpoints(e) + + Compute the midpoints of the bins with edges ``e``. The result is a vector/range of length ``length(e) - 1``. Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: quantile(v, p) - Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + quantile(v, p) + + Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: quantile(v, p) - Compute the quantile of a vector ``v`` at the probability ``p``. - Note: Julia does not ignore ``NaN`` values in the computation. + :: + + quantile(v, p) + + Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: quantile!(v, p) + :: + + quantile!(v, p) + Like ``quantile``, but overwrites the input vector. + .. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - Compute the Pearson covariance between the vector(s) in ``v1`` and ``v2``. - Here, ``v1`` and ``v2`` can be either vectors or matrices. - - This function accepts three keyword arguments: - - - ``vardim``: the dimension of variables. When ``vardim = 1``, variables - are considered in columns while observations in rows; when ``vardim = 2``, - variables are in rows while observations in columns. By default, it is - set to ``1``. - - - ``corrected``: whether to apply Bessel's correction (divide by ``n-1`` - instead of ``n``). By default, it is set to ``true``. - - - ``mean``: allow users to supply mean values that are known. By default, - it is set to ``nothing``, which indicates that the mean(s) are unknown, - and the function will compute the mean. Users can use ``mean=0`` to - indicate that the input data are centered, and hence there's no need to - subtract the mean. - - The size of the result depends on the size of ``v1`` and ``v2``. When both - ``v1`` and ``v2`` are vectors, it returns the covariance between them as a - scalar. When either one is a matrix, it returns a covariance matrix of size - ``(n1, n2)``, where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and - ``v2``, which depend on the setting of ``vardim``. - - Note: ``v2`` can be omitted, which indicates ``v2 = v1``. - + :: + + cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + + Compute the Pearson covariance between the vector(s) in ``v1`` and This function accepts three keyword arguments: The size of the result depends on the size of ``v1`` and ``v2``. When both ``v1`` and ``v2`` are vectors, it returns the covariance between them as a scalar. When either one is a matrix, it returns a covariance matrix of size ``(n1, n2)``, where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and ``v2``, which depend on the setting of ``vardim``. Note: ``v2`` can be omitted, which indicates ``v2 = v1``. + .. function:: cor(v1[, v2][, vardim=1, mean=nothing]) - Compute the Pearson correlation between the vector(s) in ``v1`` and ``v2``. - - Users can use the keyword argument ``vardim`` to specify the variable - dimension, and ``mean`` to supply pre-computed mean values. - + :: + + cor(v1[, v2][, vardim=1, mean=nothing]) + + Compute the Pearson correlation between the vector(s) in ``v1`` and Users can use the keyword argument ``vardim`` to specify the variable dimension, and ``mean`` to supply pre-computed mean values. + Signal Processing ----------------- @@ -1359,258 +2307,327 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: fft(A [, dims]) - Performs a multidimensional FFT of the array ``A``. The optional ``dims`` - argument specifies an iterable subset of dimensions (e.g. an integer, - range, tuple, or array) to transform along. Most efficient if the - size of ``A`` along the transformed dimensions is a product of small - primes; see :func:`nextprod`. See also :func:`plan_fft` for even - greater efficiency. - - A one-dimensional FFT computes the one-dimensional discrete Fourier - transform (DFT) as defined by - - .. math:: - - \operatorname{DFT}(A)[k] = \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(-i\frac{2\pi (n-1)(k-1)}{\operatorname{length}(A)} \right) - A[n]. - - A multidimensional FFT simply performs this operation along each transformed - dimension of ``A``. - - Higher performance is usually possible with multi-threading. Use - `FFTW.set_num_threads(np)` to use `np` threads, if you have `np` - processors. + :: + + fft(A[, dims]) + + Performs a multidimensional FFT of the array ``A``. The optional an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also A one-dimensional FFT computes the one-dimensional discrete Fourier transform (DFT) as defined by A multidimensional FFT simply performs this operation along each transformed dimension of ``A``. Higher performance is usually possible with multi-threading. Use processors. + .. function:: fft!(A [, dims]) - Same as :func:`fft`, but operates in-place on ``A``, - which must be an array of complex floating-point numbers. + :: + + fft!(A[, dims]) + + Same as ``fft()``, but operates in-place on ``A``, which must be an array of complex floating-point numbers. + .. function:: ifft(A [, dims]) - Multidimensional inverse FFT. - - A one-dimensional inverse FFT computes - - .. math:: - - \operatorname{IDFT}(A)[k] = \frac{1}{\operatorname{length}(A)} - \sum_{n=1}^{\operatorname{length}(A)} \exp\left(+i\frac{2\pi (n-1)(k-1)} - {\operatorname{length}(A)} \right) A[n]. - - A multidimensional inverse FFT simply performs this operation along each - transformed dimension of ``A``. + :: + + ifft(A[, dims]) + + Multidimensional inverse FFT. A one-dimensional inverse FFT computes A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``. + .. function:: ifft!(A [, dims]) - Same as :func:`ifft`, but operates in-place on ``A``. + :: + + ifft!(A[, dims]) + + Same as ``ifft()``, but operates in-place on ``A``. + .. function:: bfft(A [, dims]) - Similar to :func:`ifft`, but computes an unnormalized inverse (backward) - transform, which must be divided by the product of the sizes of the - transformed dimensions in order to obtain the inverse. (This is slightly - more efficient than :func:`ifft` because it omits a scaling step, which in - some applications can be combined with other computational steps elsewhere.) - - .. math:: - - \operatorname{BDFT}(A)[k] = \operatorname{length}(A) \operatorname{IDFT}(A)[k] + :: + + bfft(A[, dims]) + + Similar to ``ifft()``, but computes an unnormalized inverse sizes of the transformed dimensions in order to obtain the inverse. scaling step, which in some applications can be combined with other computational steps elsewhere.) + .. function:: bfft!(A [, dims]) - Same as :func:`bfft`, but operates in-place on ``A``. + :: + + bfft!(A[, dims]) + + Same as ``bfft()``, but operates in-place on ``A``. + .. function:: plan_fft(A [, dims [, flags [, timelimit]]]) - Pre-plan an optimized FFT along given dimensions (``dims``) of arrays - matching the shape and type of ``A``. (The first two arguments have - the same meaning as for :func:`fft`.) Returns a function ``plan(A)`` - that computes ``fft(A, dims)`` quickly. - - The ``flags`` argument is a bitwise-or of FFTW planner flags, defaulting - to ``FFTW.ESTIMATE``. e.g. passing ``FFTW.MEASURE`` or ``FFTW.PATIENT`` - will instead spend several seconds (or more) benchmarking different - possible FFT algorithms and picking the fastest one; see the FFTW manual - for more information on planner flags. The optional ``timelimit`` argument - specifies a rough upper bound on the allowed planning time, in seconds. - Passing ``FFTW.MEASURE`` or ``FFTW.PATIENT`` may cause the input array ``A`` - to be overwritten with zeros during plan creation. - - :func:`plan_fft!` is the same as :func:`plan_fft` but creates a plan - that operates in-place on its argument (which must be an array of - complex floating-point numbers). :func:`plan_ifft` and so on - are similar but produce plans that perform the equivalent of - the inverse transforms :func:`ifft` and so on. + :: + + plan_fft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized FFT along given dimensions (``dims``) of arrays matching the shape and type of ``A``. (The first two arguments have the same meaning as for ``fft()``.) Returns a function ``plan(A)`` that computes ``fft(A, dims)`` quickly. The ``flags`` argument is a bitwise-or of FFTW planner flags, defaulting to ``FFTW.ESTIMATE``. e.g. passing ``FFTW.MEASURE`` or benchmarking different possible FFT algorithms and picking the fastest one; see the FFTW manual for more information on planner flags. The optional ``timelimit`` argument specifies a rough upper bound on the allowed planning time, in seconds. Passing that operates in-place on its argument (which must be an array of complex floating-point numbers). ``plan_ifft()`` and so on are similar but produce plans that perform the equivalent of the inverse transforms ``ifft()`` and so on. + .. function:: plan_ifft(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_fft`, but produces a plan that performs inverse transforms - :func:`ifft`. + :: + + plan_ifft(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_fft()``, but produces a plan that performs inverse transforms ``ifft()``. + .. function:: plan_bfft(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_fft`, but produces a plan that performs an unnormalized - backwards transform :func:`bfft`. + :: + + plan_bfft(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_fft()``, but produces a plan that performs an unnormalized backwards transform ``bfft()``. + .. function:: plan_fft!(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_fft`, but operates in-place on ``A``. + :: + + plan_fft!(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_fft()``, but operates in-place on ``A``. + .. function:: plan_ifft!(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_ifft`, but operates in-place on ``A``. + :: + + plan_ifft!(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_ifft()``, but operates in-place on ``A``. + .. function:: plan_bfft!(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_bfft`, but operates in-place on ``A``. + :: + + plan_bfft!(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_bfft()``, but operates in-place on ``A``. + .. function:: rfft(A [, dims]) - Multidimensional FFT of a real array A, exploiting the fact that - the transform has conjugate symmetry in order to save roughly half - the computational time and storage costs compared with :func:`fft`. - If ``A`` has size ``(n_1, ..., n_d)``, the result has size - ``(floor(n_1/2)+1, ..., n_d)``. - - The optional ``dims`` argument specifies an iterable subset of one or - more dimensions of ``A`` to transform, similar to :func:`fft`. Instead - of (roughly) halving the first dimension of ``A`` in the result, the - ``dims[1]`` dimension is (roughly) halved in the same way. + :: + + rfft(A[, dims]) + + Multidimensional FFT of a real array A, exploiting the fact that the transform has conjugate symmetry in order to save roughly half the computational time and storage costs compared with ``fft()``. If ``A`` has size ``(n_1, ..., n_d)``, the result has size The optional ``dims`` argument specifies an iterable subset of one or more dimensions of ``A`` to transform, similar to ``fft()``. Instead of (roughly) halving the first dimension of ``A`` in the result, the ``dims[1]`` dimension is (roughly) halved in the same way. + .. function:: irfft(A, d [, dims]) - Inverse of :func:`rfft`: for a complex array ``A``, gives the - corresponding real array whose FFT yields ``A`` in the first half. - As for :func:`rfft`, ``dims`` is an optional subset of dimensions - to transform, defaulting to ``1:ndims(A)``. - - ``d`` is the length of the transformed real array along the ``dims[1]`` - dimension, which must satisfy ``d == floor(size(A,dims[1])/2)+1``. - (This parameter cannot be inferred from ``size(A)`` due to the - possibility of rounding by the ``floor`` function here.) + :: + + irfft(A, d[, dims]) + + Inverse of ``rfft()``: for a complex array ``A``, gives the corresponding real array whose FFT yields ``A`` in the first half. As for ``rfft()``, ``dims`` is an optional subset of dimensions to transform, defaulting to ``1:ndims(A)``. floor(size(A,dims[1])/2)+1``. (This parameter cannot be inferred from `size(A)`` due to the possibility of rounding by the + .. function:: brfft(A, d [, dims]) - Similar to :func:`irfft` but computes an unnormalized inverse transform - (similar to :func:`bfft`), which must be divided by the product - of the sizes of the transformed dimensions (of the real output array) - in order to obtain the inverse transform. + :: + + brfft(A, d[, dims]) + + Similar to ``irfft()`` but computes an unnormalized inverse transform (similar to ``bfft()``), which must be divided by the product of the sizes of the transformed dimensions (of the real output array) in order to obtain the inverse transform. + .. function:: plan_rfft(A [, dims [, flags [, timelimit]]]) - Pre-plan an optimized real-input FFT, similar to :func:`plan_fft` - except for :func:`rfft` instead of :func:`fft`. The first two - arguments, and the size of the transformed result, are the same as - for :func:`rfft`. + :: + + plan_rfft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized real-input FFT, similar to ``plan_fft()`` except for ``rfft()`` instead of ``fft()``. The first two arguments, and the size of the transformed result, are the same as for ``rfft()``. + .. function:: plan_brfft(A, d [, dims [, flags [, timelimit]]]) - Pre-plan an optimized real-input unnormalized transform, similar to - :func:`plan_rfft` except for :func:`brfft` instead of :func:`rfft`. - The first two arguments and the size of the transformed result, are - the same as for :func:`brfft`. + :: + + plan_brfft(A, d[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized real-input unnormalized transform, similar to first two arguments and the size of the transformed result, are the same as for ``brfft()``. + .. function:: plan_irfft(A, d [, dims [, flags [, timelimit]]]) - Pre-plan an optimized inverse real-input FFT, similar to :func:`plan_rfft` - except for :func:`irfft` and :func:`brfft`, respectively. The first - three arguments have the same meaning as for :func:`irfft`. + :: + + plan_irfft(A, d[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized inverse real-input FFT, similar to respectively. The first three arguments have the same meaning as for ``irfft()``. + .. function:: dct(A [, dims]) - Performs a multidimensional type-II discrete cosine transform (DCT) - of the array ``A``, using the unitary normalization of the DCT. - The optional ``dims`` argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of ``A`` along the transformed - dimensions is a product of small primes; see :func:`nextprod`. See - also :func:`plan_dct` for even greater efficiency. + :: + + dct(A[, dims]) + + Performs a multidimensional type-II discrete cosine transform (DCT) of the array ``A``, using the unitary normalization of the DCT. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also ``plan_dct()`` for even greater efficiency. + .. function:: dct!(A [, dims]) - Same as :func:`dct!`, except that it operates in-place - on ``A``, which must be an array of real or complex floating-point - values. + :: + + dct!(A[, dims]) + + Same as ``dct!()``, except that it operates in-place on ``A``, which must be an array of real or complex floating-point values. + .. function:: idct(A [, dims]) - Computes the multidimensional inverse discrete cosine transform (DCT) - of the array ``A`` (technically, a type-III DCT with the unitary - normalization). - The optional ``dims`` argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of ``A`` along the transformed - dimensions is a product of small primes; see :func:`nextprod`. See - also :func:`plan_idct` for even greater efficiency. + :: + + idct(A[, dims]) + + Computes the multidimensional inverse discrete cosine transform unitary normalization). The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see efficiency. + .. function:: idct!(A [, dims]) - Same as :func:`idct!`, but operates in-place on ``A``. + :: + + idct!(A[, dims]) + + Same as ``idct!()``, but operates in-place on ``A``. + .. function:: plan_dct(A [, dims [, flags [, timelimit]]]) - Pre-plan an optimized discrete cosine transform (DCT), similar to - :func:`plan_fft` except producing a function that computes :func:`dct`. - The first two arguments have the same meaning as for :func:`dct`. + :: + + plan_dct(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized discrete cosine transform (DCT), similar to The first two arguments have the same meaning as for ``dct()``. + .. function:: plan_dct!(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_dct`, but operates in-place on ``A``. + :: + + plan_dct!(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_dct()``, but operates in-place on ``A``. + .. function:: plan_idct(A [, dims [, flags [, timelimit]]]) - Pre-plan an optimized inverse discrete cosine transform (DCT), similar to - :func:`plan_fft` except producing a function that computes :func:`idct`. - The first two arguments have the same meaning as for :func:`idct`. + :: + + plan_idct(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized inverse discrete cosine transform (DCT), similar to ``plan_fft()`` except producing a function that computes + .. function:: plan_idct!(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_idct`, but operates in-place on ``A``. + :: + + plan_idct!(A[, dims[, flags[, timelimit]]]) + + Same as ``plan_idct()``, but operates in-place on ``A``. + .. function:: fftshift(x) - Swap the first and second halves of each dimension of ``x``. + :: + + fftshift(x, dim) + + Swap the first and second halves of the given dimension of array + .. function:: fftshift(x,dim) - Swap the first and second halves of the given dimension of array ``x``. + :: + + fftshift(x, dim) + + Swap the first and second halves of the given dimension of array + .. function:: ifftshift(x, [dim]) + :: + + ifftshift(x[, dim]) + Undoes the effect of ``fftshift``. + .. function:: filt(b, a, x, [si]) - Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an - optional initial filter state vector ``si`` (defaults to zeros). + :: + + filt(b, a, x[, si]) + + Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an optional initial filter state vector ``si`` (defaults to zeros). + .. function:: filt!(out, b, a, x, [si]) - Same as :func:`filt` but writes the result into the ``out`` argument, - which may alias the input ``x`` to modify it in-place. + :: + + filt!(out, b, a, x[, si]) + + Same as ``filt()`` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. + .. function:: deconv(b,a) + :: + + deconv(b, a) + Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. + .. function:: conv(u,v) + :: + + conv(u, v) + Convolution of two vectors. Uses FFT algorithm. + .. function:: conv2(u,v,A) - 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by - the vectors ``u`` and ``v``. Uses 2-D FFT algorithm + :: + + conv2(B, A) + + 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm + .. function:: conv2(B,A) + :: + + conv2(B, A) + 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm + .. function:: xcorr(u,v) + :: + + xcorr(u, v) + Compute the cross-correlation of two vectors. + The following functions are defined within the ``Base.FFTW`` module. @@ -1618,44 +2635,41 @@ The following functions are defined within the ``Base.FFTW`` module. .. function:: r2r(A, kind [, dims]) - Performs a multidimensional real-input/real-output (r2r) transform - of type ``kind`` of the array ``A``, as defined in the FFTW manual. - ``kind`` specifies either a discrete cosine transform of various types - (``FFTW.REDFT00``, ``FFTW.REDFT01``, ``FFTW.REDFT10``, or - ``FFTW.REDFT11``), a discrete sine transform of various types - (``FFTW.RODFT00``, ``FFTW.RODFT01``, ``FFTW.RODFT10``, or - ``FFTW.RODFT11``), a real-input DFT with halfcomplex-format output - (``FFTW.R2HC`` and its inverse ``FFTW.HC2R``), or a discrete - Hartley transform (``FFTW.DHT``). The ``kind`` argument may be - an array or tuple in order to specify different transform types - along the different dimensions of ``A``; ``kind[end]`` is used - for any unspecified dimensions. See the FFTW manual for precise - definitions of these transform types, at http://www.fftw.org/doc. - - The optional ``dims`` argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. ``kind[i]`` is then the transform type for ``dims[i]``, - with ``kind[end]`` being used for ``i > length(kind)``. - - See also :func:`plan_r2r` to pre-plan optimized r2r transforms. + :: + + r2r(A, kind[, dims]) + + Performs a multidimensional real-input/real-output (r2r) transform of type ``kind`` of the array ``A``, as defined in the FFTW manual. types (``FFTW.REDFT00``, ``FFTW.REDFT01``, ``FFTW.REDFT10``, or Hartley transform (``FFTW.DHT``). The ``kind`` argument may be an array or tuple in order to specify different transform types along the different dimensions of ``A``; ``kind[end]`` is used for any unspecified dimensions. See the FFTW manual for precise definitions of these transform types, at http://www.fftw.org/doc. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. ``kind[i]`` is then the transform type for ``dims[i]``, with See also ``plan_r2r()`` to pre-plan optimized r2r transforms. + .. function:: r2r!(A, kind [, dims]) - Same as :func:`r2r`, but operates in-place on ``A``, which must be - an array of real or complex floating-point numbers. + :: + + r2r!(A, kind[, dims]) + + Same as ``r2r()``, but operates in-place on ``A``, which must be an array of real or complex floating-point numbers. + .. function:: plan_r2r(A, kind [, dims [, flags [, timelimit]]]) - Pre-plan an optimized r2r transform, similar to :func:`Base.plan_fft` - except that the transforms (and the first three arguments) - correspond to :func:`r2r` and :func:`r2r!`, respectively. + :: + + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized r2r transform, similar to ``Base.plan_fft()`` except that the transforms (and the first three arguments) correspond to ``r2r()`` and ``r2r!()``, respectively. + .. function:: plan_r2r!(A, kind [, dims [, flags [, timelimit]]]) - Similar to :func:`Base.plan_fft`, but corresponds to :func:`r2r!`. + :: + + plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + + Similar to ``Base.plan_fft()``, but corresponds to ``r2r!()``. + .. currentmodule:: Base - Numerical Integration --------------------- @@ -1665,61 +2679,10 @@ some built-in integration support in Julia. .. function:: quadgk(f, a,b,c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - Numerically integrate the function ``f(x)`` from ``a`` to ``b``, - and optionally over additional intervals ``b`` to ``c`` and so on. - Keyword options include a relative error tolerance ``reltol`` (defaults - to ``sqrt(eps)`` in the precision of the endpoints), an absolute error - tolerance ``abstol`` (defaults to 0), a maximum number of function - evaluations ``maxevals`` (defaults to ``10^7``), and the ``order`` - of the integration rule (defaults to 7). - - Returns a pair ``(I,E)`` of the estimated integral ``I`` and an - estimated upper bound on the absolute error ``E``. If ``maxevals`` - is not exceeded then ``E <= max(abstol, reltol*norm(I))`` will hold. - (Note that it is useful to specify a positive ``abstol`` in cases where - ``norm(I)`` may be zero.) - - The endpoints ``a`` etcetera can also be complex (in which case the - integral is performed over straight-line segments in the complex - plane). If the endpoints are ``BigFloat``, then the integration - will be performed in ``BigFloat`` precision as well (note: it is - advisable to increase the integration ``order`` in rough proportion - to the precision, for smooth integrands). More generally, the - precision is set by the precision of the integration endpoints - (promoted to floating-point types). - - The integrand ``f(x)`` can return any numeric scalar, vector, or matrix - type, or in fact any type supporting ``+``, ``-``, multiplication - by real values, and a ``norm`` (i.e., any normed vector space). - Alternatively, a different norm can be specified by passing a `norm`-like - function as the `norm` keyword argument (which defaults to `vecnorm`). - - [Only one-dimensional integrals are provided by this function. For - multi-dimensional integration (cubature), there are many different - algorithms (often much better than simple nested 1d integrals) - and the optimal choice tends to be very problem-dependent. See - the Julia external-package listing for available algorithms for - multidimensional integration or other specialized tasks (such as - integrals of highly oscillatory or singular functions).] - - The algorithm is an adaptive Gauss-Kronrod integration technique: - the integral in each interval is estimated using a Kronrod rule - (``2*order+1`` points) and the error is estimated using an embedded - Gauss rule (``order`` points). The interval with the largest - error is then subdivided into two intervals and the process is repeated - until the desired error tolerance is achieved. - - These quadrature rules work best for smooth functions within each - interval, so if your function has a known discontinuity or other - singularity, it is best to subdivide your interval to put the - singularity at an endpoint. For example, if ``f`` has a discontinuity - at ``x=0.7`` and you want to integrate from 0 to 1, you should use - ``quadgk(f, 0,0.7,1)`` to subdivide the interval at the point of - discontinuity. The integrand is never evaluated exactly at the endpoints - of the intervals, so it is possible to integrate functions that diverge - at the endpoints as long as the singularity is integrable (for example, - a ``log(x)`` or ``1/sqrt(x)`` singularity). - - For real-valued endpoints, the starting and/or ending points may be - infinite. (A coordinate transformation is performed internally to - map the infinite interval to a finite one.) + :: + + quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + + Numerically integrate the function ``f(x)`` from ``a`` to ``b``, and optionally over additional intervals ``b`` to ``c`` and so on. Keyword options include a relative error tolerance ``reltol`` absolute error tolerance ``abstol`` (defaults to 0), a maximum number of function evaluations ``maxevals`` (defaults to ``10^7``), and the ``order`` of the integration rule (defaults to 7). Returns a pair ``(I,E)`` of the estimated integral ``I`` and an estimated upper bound on the absolute error ``E``. If ``maxevals`` is not exceeded then ``E <= max(abstol, reltol*norm(I))`` will hold. (Note that it is useful to specify a positive ``abstol`` in cases where ``norm(I)`` may be zero.) The endpoints ``a`` etcetera can also be complex (in which case the integral is performed over straight-line segments in the complex plane). If the endpoints are ``BigFloat``, then the integration will be performed in ``BigFloat`` precision as well (note: it is advisable to increase the integration ``order`` in rough proportion to the precision, for smooth integrands). More generally, the precision is set by the precision of the integration endpoints The integrand ``f(x)`` can return any numeric scalar, vector, or matrix type, or in fact any type supporting ``+``, ``-``, multiplication by real values, and a ``norm`` (i.e., any normed vector space). Alternatively, a different norm can be specified by passing a *norm*-like function as the *norm* keyword argument multi-dimensional integration (cubature), there are many different algorithms (often much better than simple nested 1d integrals) and the optimal choice tends to be very problem-dependent. See the Julia external-package listing for available algorithms for multidimensional integration or other specialized tasks (such as integrals of highly oscillatory or singular functions).] The algorithm is an adaptive Gauss-Kronrod integration technique: the integral in each interval is estimated using a Kronrod rule Gauss rule (``order`` points). The interval with the largest error is then subdivided into two intervals and the process is repeated until the desired error tolerance is achieved. These quadrature rules work best for smooth functions within each interval, so if your function has a known discontinuity or other singularity, it is best to subdivide your interval to put the singularity at an endpoint. For example, if ``f`` has a discontinuity at ``x=0.7`` and you want to integrate from 0 to 1, you should use ``quadgk(f, 0,0.7,1)`` to subdivide the interval at the point of discontinuity. The integrand is never evaluated exactly at the endpoints of the intervals, so it is possible to integrate functions that diverge at the endpoints as long as the singularity is integrable (for example, a ``log(x)`` or For real-valued endpoints, the starting and/or ending points may be infinite. (A coordinate transformation is performed internally to map the infinite interval to a finite one.) + + diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 026d3e62f2f72..f74e014bed0e7 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -14,120 +14,222 @@ Data Formats .. function:: bin(n, [pad]) + :: + + bin(n[, pad]) + Convert an integer to a binary string, optionally specifying a number of digits to pad to. + .. function:: hex(n, [pad]) + :: + + hex(n[, pad]) + Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. + .. function:: dec(n, [pad]) + :: + + dec(n[, pad]) + Convert an integer to a decimal string, optionally specifying a number of digits to pad to. + .. function:: oct(n, [pad]) + :: + + oct(n[, pad]) + Convert an integer to an octal string, optionally specifying a number of digits to pad to. + .. function:: base(base, n, [pad]) + :: + + base(base, n[, pad]) + Convert an integer to a string in the given base, optionally specifying a number of digits to pad to. The base can be specified as either an integer, or as a ``UInt8`` array of character values to use as digit symbols. + .. function:: digits(n, [base], [pad]) - Returns an array of the digits of ``n`` in the given base, optionally padded with - zeros to a specified size. More significant digits are at higher indexes, such - that ``n == sum([digits[k]*base^(k-1) for k=1:length(digits)])``. + :: + + digits(n[, base][, pad]) + + Returns an array of the digits of ``n`` in the given base, optionally padded with zeros to a specified size. More significant digits are at higher indexes, such that ``n == sum([digits[k]*base^(k-1) for k=1:length(digits)])``. + .. function:: digits!(array, n, [base]) - Fills an array of the digits of ``n`` in the given base. More significant digits are at higher indexes. - If the array length is insufficient, the least significant digits are filled up to the array length. - If the array length is excessive, the excess portion is filled with zeros. + :: + + digits!(array, n[, base]) + + Fills an array of the digits of ``n`` in the given base. More significant digits are at higher indexes. If the array length is insufficient, the least significant digits are filled up to the array length. If the array length is excessive, the excess portion is filled with zeros. + .. function:: bits(n) + :: + + bits(n) + A string giving the literal bit representation of a number. + .. function:: parse(type, str, [base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. - If the string does not contain a valid number, an error is raised. + :: + + parse(type, str[, base]) + + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. + .. function:: tryparse(type, str, [base]) - Like ``parse``, but returns a ``Nullable`` of the requested type. - The result will be null if the string does not contain a valid number. + :: + + tryparse(type, str[, base]) + + Like ``parse``, but returns a ``Nullable`` of the requested type. The result will be null if the string does not contain a valid number. + .. function:: big(x) - Convert a number to a maximum precision representation (typically ``BigInt`` or ``BigFloat``). See ``BigFloat`` for information about some pitfalls with floating-point numbers. + :: + + big(x) + + Convert a number to a maximum precision representation (typically some pitfalls with floating-point numbers. + .. function:: signed(x) + :: + + signed(x) + Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. + .. function:: unsigned(x) -> Unsigned + :: + + unsigned(x) -> Unsigned + Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as unsigned without checking for negative values. + .. function:: float(x) + :: + + float(x) + Convert a number, array, or string to a ``FloatingPoint`` data type. For numeric data, the smallest suitable ``FloatingPoint`` type is used. Converts strings to ``Float64``. + .. function:: significand(x) - Extract the significand(s) (a.k.a. mantissa), in binary representation, of - a floating-point number or array. If ``x`` is a non-zero finite number, - than the result will be a number of the same type on the interval - [1,2). Otherwise ``x`` is returned. - - .. doctest:: - - julia> significand(15.2)/15.2 - 0.125 - - julia> significand(15.2)*8 - 15.2 + :: + + significand(x) + + Extract the significand(s) (a.k.a. mantissa), in binary representation, of a floating-point number or array. If ``x`` is a non-zero finite number, than the result will be a number of the same type on the interval [1,2). Otherwise ``x`` is returned. + .. function:: exponent(x) -> Int + :: + + exponent(x) -> Int + Get the exponent of a normalized floating-point number. + .. function:: complex(r, [i]) + :: + + complex(r[, i]) + Convert real numbers or arrays to complex. ``i`` defaults to zero. + .. function:: bswap(n) + :: + + bswap(n) + Byte-swap an integer + .. function:: num2hex(f) + :: + + num2hex(f) + Get a hexadecimal string of the binary representation of a floating point number + .. function:: hex2num(str) + :: + + hex2num(str) + Convert a hexadecimal string to the floating point number it represents + .. function:: hex2bytes(s::ASCIIString) + :: + + hex2bytes(s::ASCIIString) + Convert an arbitrarily long hexadecimal string to its binary representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. + .. function:: bytes2hex(bin_arr::Array{UInt8, 1}) + :: + + bytes2hex(bin_arr::Array{UInt8, 1}) + Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. - + General Number Functions and Constants -------------------------------------- .. function:: one(x) + :: + + one(x) + Get the multiplicative identity element for the type of x (x can also specify the type itself). For matrices, returns an identity matrix of the appropriate size and type. + .. function:: zero(x) + :: + + zero(x) + Get the additive identity element for the type of x (x can also specify the type itself). + .. data:: pi π @@ -183,238 +285,258 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool + :: + + issubnormal(f) -> Bool + Test whether a floating point number is subnormal + .. function:: isfinite(f) -> Bool + :: + + isfinite(f) -> Bool + Test whether a number is finite + .. function:: isinf(f) -> Bool + :: + + isinf(f) -> Bool + Test whether a number is infinite + .. function:: isnan(f) -> Bool + :: + + isnan(f) -> Bool + Test whether a floating point number is not a number (NaN) + .. function:: inf(f) + :: + + inf(f) + Returns positive infinity of the floating point type ``f`` or of the same floating point type as ``f`` + .. function:: nan(f) + :: + + nan(f) + Returns NaN (not-a-number) of the floating point type ``f`` or of the same floating point type as ``f`` + .. function:: nextfloat(f) + :: + + nextfloat(f) + Get the next floating point number in lexicographic order + .. function:: prevfloat(f) -> FloatingPoint + :: + + prevfloat(f) -> FloatingPoint + Get the previous floating point number in lexicographic order + .. function:: isinteger(x) -> Bool + :: + + isinteger(x) -> Bool + Test whether ``x`` or all its elements are numerically equal to some integer + .. function:: isreal(x) -> Bool + :: + + isreal(x) -> Bool + Test whether ``x`` or all its elements are numerically equal to some real number + .. function:: Float32(x [, mode::RoundingMode]) - Create a Float32 from ``x``. If ``x`` is not exactly representable then - ``mode`` determines how ``x`` is rounded. - - .. doctest:: - - julia> Float32(1/3, RoundDown) - 0.3333333f0 - - julia> Float32(1/3, RoundUp) - 0.33333334f0 - - See ``get_rounding`` for available rounding modes. + :: + + Float32(x[, mode::RoundingMode]) + + Create a Float32 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. + .. function:: Float64(x [, mode::RoundingMode]) - Create a Float64 from ``x``. If ``x`` is not exactly representable then - ``mode`` determines how ``x`` is rounded. - - .. doctest:: - - julia> Float64(pi, RoundDown) - 3.141592653589793 - - julia> Float64(pi, RoundUp) - 3.1415926535897936 - - See ``get_rounding`` for available rounding modes. + :: + + Float64(x[, mode::RoundingMode]) + + Create a Float64 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. + .. function:: BigInt(x) - Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything - that can be converted to an ``Int``). The usual mathematical operators are - defined for this type, and results are promoted to a ``BigInt``. - - Instances can be constructed from strings via :func:`parse`, or using the - ``big`` string literal. + :: + + BigInt(x) + + Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``). The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. Instances can be constructed from strings via ``parse()``, or using the ``big`` string literal. + .. function:: BigFloat(x) - Create an arbitrary precision floating point number. ``x`` may be - an ``Integer``, a ``Float64`` or a ``BigInt``. The - usual mathematical operators are defined for this type, and results - are promoted to a ``BigFloat``. - - Note that because decimal literals are converted to floating point numbers - when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead - prefer to initialize constants from strings via :func:`parse`, or using the - ``big`` string literal. - - .. doctest:: - julia> BigFloat(2.1) - 2.100000000000000088817841970012523233890533447265625e+00 with 256 bits of precision - - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision - + :: + + BigFloat(x) + + Create an arbitrary precision floating point number. ``x`` may be an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results are promoted to a ``BigFloat``. Note that because decimal literals are converted to floating point numbers when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead prefer to initialize constants from strings via ``parse()``, or using the ``big`` string literal. + .. function:: get_rounding(T) - Get the current floating point rounding mode for type ``T``, controlling - the rounding of basic arithmetic functions (:func:`+`, :func:`-`, - :func:`*`, :func:`/` and :func:`sqrt`) and type conversion. - - Valid modes are ``RoundNearest``, ``RoundToZero``, ``RoundUp``, - ``RoundDown``, and ``RoundFromZero`` (``BigFloat`` only). + :: + + get_rounding(T) + + Get the current floating point rounding mode for type ``T``, controlling the rounding of basic arithmetic functions (``+()``, Valid modes are ``RoundNearest``, ``RoundToZero``, ``RoundUp``, + .. function:: set_rounding(T, mode) - Set the rounding mode of floating point type ``T``, controlling the - rounding of basic arithmetic functions (:func:`+`, :func:`-`, :func:`*`, - :func:`/` and :func:`sqrt`) and type conversion. - - Note that this may affect other types, for instance changing the rounding - mode of ``Float64`` will change the rounding mode of ``Float32``. See - ``get_rounding`` for available modes + :: + + set_rounding(T, mode) + + Set the rounding mode of floating point type ``T``, controlling the rounding of basic arithmetic functions (``+()``, ``-()``, ``*()``, Note that this may affect other types, for instance changing the rounding mode of ``Float64`` will change the rounding mode of + .. function:: with_rounding(f::Function, T, mode) - Change the rounding mode of floating point type ``T`` for the duration of ``f``. It is logically equivalent to:: - - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) - - See ``get_rounding`` for available rounding modes. + :: + + with_rounding(f::Function, T, mode) + + Change the rounding mode of floating point type ``T`` for the duration of ``f``. It is logically equivalent to: See ``get_rounding`` for available rounding modes. + Integers ~~~~~~~~ .. function:: count_ones(x::Integer) -> Integer + :: + + count_ones(x::Integer) -> Integer + Number of ones in the binary representation of ``x``. - - .. doctest:: - - julia> count_ones(7) - 3 + .. function:: count_zeros(x::Integer) -> Integer + :: + + count_zeros(x::Integer) -> Integer + Number of zeros in the binary representation of ``x``. - - .. doctest:: - - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 + .. function:: leading_zeros(x::Integer) -> Integer + :: + + leading_zeros(x::Integer) -> Integer + Number of zeros leading the binary representation of ``x``. - - .. doctest:: - - julia> leading_zeros(Int32(1)) - 31 + .. function:: leading_ones(x::Integer) -> Integer + :: + + leading_ones(x::Integer) -> Integer + Number of ones leading the binary representation of ``x``. - - .. doctest:: - - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 + .. function:: trailing_zeros(x::Integer) -> Integer + :: + + trailing_zeros(x::Integer) -> Integer + Number of zeros trailing the binary representation of ``x``. - - .. doctest:: - - julia> trailing_zeros(2) - 1 + .. function:: trailing_ones(x::Integer) -> Integer + :: + + trailing_ones(x::Integer) -> Integer + Number of ones trailing the binary representation of ``x``. - - .. doctest:: - - julia> trailing_ones(3) - 2 + .. function:: isprime(x::Integer) -> Bool - Returns ``true`` if ``x`` is prime, and ``false`` otherwise. - - .. doctest:: - - julia> isprime(3) - true + :: + + isprime(x::BigInt[, reps = 25]) -> Bool + + Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + .. function:: isprime(x::BigInt, [reps = 25]) -> Bool - Probabilistic primality test. Returns ``true`` if ``x`` is prime; and - ``false`` if ``x`` is not prime with high probability. The false positive - rate is about ``0.25^reps``. ``reps = 25`` is considered safe for - cryptographic applications (Knuth, Seminumerical Algorithms). - - .. doctest:: - - julia> isprime(big(3)) - true + :: + + isprime(x::BigInt[, reps = 25]) -> Bool + + Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + .. function:: primes(n) + :: + + primes(n) + Returns a collection of the prime numbers <= ``n``. + .. function:: isodd(x::Integer) -> Bool - Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and ``false`` otherwise. - - .. doctest:: - - julia> isodd(9) - true - - julia> isodd(10) - false + :: + + isodd(x::Integer) -> Bool + + Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and + .. function:: iseven(x::Integer) -> Bool - Returns ``true`` is ``x`` is even (that is, divisible by 2), and ``false`` otherwise. - - .. doctest:: - - julia> iseven(9) - false - - julia> iseven(10) - true + :: + + iseven(x::Integer) -> Bool + + Returns ``true`` is ``x`` is even (that is, divisible by 2), and + BigFloats --------- @@ -422,24 +544,39 @@ The `BigFloat` type implements arbitrary-precision floating-point arithmetic usi .. function:: precision(num::FloatingPoint) + :: + + precision(num::FloatingPoint) + Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. + .. function:: get_bigfloat_precision() + :: + + get_bigfloat_precision() + Get the precision (in bits) currently used for BigFloat arithmetic. + .. function:: set_bigfloat_precision(x::Int64) + :: + + set_bigfloat_precision(x::Int64) + Set the precision (in bits) to be used to BigFloat arithmetic. + .. function:: with_bigfloat_precision(f::Function,precision::Integer) - Change the BigFloat arithmetic precision (in bits) for the duration of ``f``. It is logically equivalent to:: - - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) + :: + + with_bigfloat_precision(f::Function, precision::Integer) + + Change the BigFloat arithmetic precision (in bits) for the duration of ``f``. It is logically equivalent to: + .. _random-numbers: @@ -462,48 +599,91 @@ As ``BigInt`` represents unbounded integers, the interval must be specified (e.g .. function:: srand([rng], [seed]) - Reseed the random number generator. If a ``seed`` is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. - For ``MersenneTwister``, the ``seed`` may be a non-negative integer, a vector of ``UInt32`` integers or a filename, in which case the seed is read from a file. - ``RandomDevice`` does not support seeding. + :: + + srand([rng][, seed]) + + Reseed the random number generator. If a ``seed`` is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. For ``MersenneTwister``, the integers or a filename, in which case the seed is read from a file. + .. function:: MersenneTwister([seed]) + :: + + MersenneTwister([seed]) + Create a ``MersenneTwister`` RNG object. Different RNG objects can have their own seeds, which may be useful for generating different streams of random numbers. + .. function:: RandomDevice() + :: + + RandomDevice() + Create a ``RandomDevice`` RNG object. Two such objects will always generate different streams of random numbers. + .. function:: rand([rng], [S], [dims...]) + :: + + rand([rng][, S][, dims...]) + Pick a random element or array of random elements from the set of values specified by ``S``; ``S`` can be - - * an indexable collection (for example ``1:n`` or ``['x','y','z']``), or - - * a type: the set of values to pick from is then equivalent to ``typemin(S):typemax(S)`` for integers (this is not applicable to ``BigInt``), and to [0,1) for floating point numbers; - - ``S`` defaults to ``Float64``. + .. function:: rand!([rng], A, [coll]) + :: + + rand!([rng], A[, coll]) + Populate the array A with random values. If the indexable collection ``coll`` is specified, the values are picked randomly from ``coll``. This is equivalent to ``copy!(A, rand(rng, coll, size(A)))`` or ``copy!(A, rand(rng, eltype(A), size(A)))`` but without allocating a new array. + .. function:: bitrand([rng], [dims...]) + :: + + bitrand([rng][, dims...]) + Generate a ``BitArray`` of random boolean values. + .. function:: randn([rng], [dims...]) - Generate a normally-distributed random number with mean 0 and standard deviation 1. Optionally generate an array of normally-distributed random numbers. + :: + + randn([rng][, dims...]) + + Generate a normally-distributed random number with mean 0 and standard deviation 1. Optionally generate an array of normally- distributed random numbers. + .. function:: randn!([rng], A::Array{Float64,N}) + :: + + randn!([rng], A::Array{Float64, N}) + Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand function. + .. function:: randexp([rng], [dims...]) + :: + + randexp([rng][, dims...]) + Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. + .. function:: randexp!([rng], A::Array{Float64,N}) + :: + + randexp!([rng], A::Array{Float64, N}) + Fill the array A with random numbers following the exponential distribution (with scale 1). + + diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 32e9e7bcdbfcc..89b22a59e4409 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -9,367 +9,495 @@ Tasks .. function:: Task(func) + :: + + Task(func) + Create a ``Task`` (i.e. thread, or coroutine) to execute the given function (which must be callable with no arguments). The task exits when this function returns. + .. function:: yieldto(task, arg = nothing) - Switch to the given task. The first time a task is switched to, the task's function is called with no arguments. On subsequent switches, ``arg`` is returned from the task's last call to ``yieldto``. This is a low-level call that only switches tasks, not considering states or scheduling in any way. Its use is discouraged. + :: + + yieldto(task, arg = nothing) + + Switch to the given task. The first time a task is switched to, the task's function is called with no arguments. On subsequent switches, ``arg`` is returned from the task's last call to considering states or scheduling in any way. Its use is discouraged. + .. function:: current_task() + :: + + current_task() + Get the currently running Task. + .. function:: istaskdone(task) -> Bool + :: + + istaskdone(task) -> Bool + Tell whether a task has exited. + .. function:: istaskstarted(task) -> Bool + :: + + istaskstarted(task) -> Bool + Tell whether a task has started executing. + .. function:: consume(task, values...) - Receive the next value passed to ``produce`` by the specified task. - Additional arguments may be passed, to be returned from the last ``produce`` call - in the producer. + :: + + consume(task, values...) + + Receive the next value passed to ``produce`` by the specified task. Additional arguments may be passed, to be returned from the last + .. function:: produce(value) - Send the given value to the last ``consume`` call, switching to the consumer task. - If the next ``consume`` call passes any values, they are returned by ``produce``. + :: + + produce(value) + + Send the given value to the last ``consume`` call, switching to the consumer task. If the next ``consume`` call passes any values, they are returned by ``produce``. + .. function:: yield() + :: + + yield() + Switch to the scheduler to allow another scheduled task to run. A task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. + .. function:: task_local_storage(symbol) - Look up the value of a symbol in the current task's task-local storage. + :: + + task_local_storage(body, symbol, value) + + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. + .. function:: task_local_storage(symbol, value) - Assign a value to a symbol in the current task's task-local storage. + :: + + task_local_storage(body, symbol, value) + + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. + .. function:: task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which - ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or - lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + :: + + task_local_storage(body, symbol, value) + + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. + .. function:: Condition() - Create an edge-triggered event source that tasks can wait for. Tasks - that call ``wait`` on a ``Condition`` are suspended and queued. - Tasks are woken up when ``notify`` is later called on the ``Condition``. - Edge triggering means that only tasks waiting at the time ``notify`` is - called can be woken up. For level-triggered notifications, you must - keep extra state to keep track of whether a notification has happened. - The ``RemoteRef`` type does this, and so can be used for level-triggered - events. + :: + + Condition() + + Create an edge-triggered event source that tasks can wait for. Tasks that call ``wait`` on a ``Condition`` are suspended and queued. Tasks are woken up when ``notify`` is later called on the time ``notify`` is called can be woken up. For level-triggered notifications, you must keep extra state to keep track of whether a notification has happened. The ``RemoteRef`` type does this, and so can be used for level-triggered events. + .. function:: notify(condition, val=nothing; all=true, error=false) - Wake up tasks waiting for a condition, passing them ``val``. - If ``all`` is true (the default), all waiting tasks are woken, otherwise - only one is. If ``error`` is true, the passed value is raised as an - exception in the woken tasks. + :: + + notify(condition, val=nothing; all=true, error=false) + + Wake up tasks waiting for a condition, passing them ``val``. If otherwise only one is. If ``error`` is true, the passed value is raised as an exception in the woken tasks. + .. function:: schedule(t::Task, [val]; error=false) - Add a task to the scheduler's queue. This causes the task to run constantly - when the system is otherwise idle, unless the task performs a blocking - operation such as ``wait``. - - If a second argument is provided, it will be passed to the task (via the - return value of ``yieldto``) when it runs again. If ``error`` is true, - the value is raised as an exception in the woken task. + :: + + schedule(t::Task, [val]; error=false) + + Add a task to the scheduler's queue. This causes the task to run constantly when the system is otherwise idle, unless the task performs a blocking operation such as ``wait``. If a second argument is provided, it will be passed to the task task. + .. function:: @schedule + :: + + @schedule() + Wrap an expression in a Task and add it to the scheduler's queue. + .. function:: @task - Wrap an expression in a Task without executing it, and return the Task. This - only creates a task, and does not run it. + :: + + @task() + + Wrap an expression in a Task without executing it, and return the Task. This only creates a task, and does not run it. + .. function:: sleep(seconds) - Block the current task for a specified number of seconds. The minimum sleep - time is 1 millisecond or input of ``0.001``. + :: + + sleep(seconds) + + Block the current task for a specified number of seconds. The minimum sleep time is 1 millisecond or input of ``0.001``. + .. function:: ReentrantLock() - Creates a reentrant lock. The same task can acquire the lock as many times - as required. Each lock must be matched with an unlock. + :: + + ReentrantLock() + + Creates a reentrant lock. The same task can acquire the lock as many times as required. Each lock must be matched with an unlock. + .. function:: lock(l::ReentrantLock) - Associates ``l`` with the current task. If ``l`` is already locked by a different - task, waits for it to become available. The same task can acquire the lock multiple - times. Each "lock" must be matched by an "unlock" + :: + + lock(l::ReentrantLock) + + Associates ``l`` with the current task. If ``l`` is already locked by a different task, waits for it to become available. The same task can acquire the lock multiple times. Each ``lock`` must be matched by an ``unlock`` + .. function:: unlock(l::ReentrantLock) - Releases ownership of the lock by the current task. If the lock had been acquired before, - it just decrements an internal counter and returns immediately. - + :: + + unlock(l::ReentrantLock) + + Releases ownership of the lock by the current task. If the lock had been acquired before, it just decrements an internal counter and returns immediately. + General Parallel Computing Support ---------------------------------- .. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers - Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. - This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + .. function:: addprocs() -> List of process identifiers - Equivalent to ``addprocs(CPU_CORES)`` + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + .. function:: addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - Add processes on remote machines via SSH. - Requires julia to be installed in the same location on each node, or to be available via a shared file system. - - ``machines`` is a vector of machine specifications. Worker are started for each specification. - - A machine specification is either a string ``machine_spec`` or a tuple - ``(machine_spec, count)`` - - ``machine_spec`` is a string of the form ``[user@]host[:port] [bind_addr[:port]]``. ``user`` defaults - to current user, ``port`` to the standard ssh port. If ``[bind_addr[:port]]`` is specified, other - workers will connect to this worker at the specified ``bind_addr`` and ``port``. - - ``count`` is the number of workers to be launched on the specified host. If specified as ``:auto`` - it will launch as many workers as the number of cores on the specific host. - - - Keyword arguments: - - ``tunnel`` : if ``true`` then SSH tunneling will be used to connect to the worker from the master process. - - ``sshflags`` : specifies additional ssh options, e.g. :literal:`sshflags=\`-i /home/foo/bar.pem\`` . - - ``max_parallel`` : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. - - ``dir`` : specifies the working directory on the workers. Defaults to the host's current directory (as found by `pwd()`) - - ``exename`` : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. - - ``exeflags`` : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, - the worker treats it a fatal situation and terminates. This timeout can be controlled via environment - variable ``JULIA_WORKER_TIMEOUT``. The value of ``JULIA_WORKER_TIMEOUT`` on the master process, specifies - the number of seconds a newly launched worker waits for connection establishment. - + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster manager implemented - in package ``ClusterManagers``. - - The number of seconds a newly launched worker waits for connection establishment from the master can be - specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when - using TCP/IP as transport. - + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + .. function:: nprocs() + :: + + nprocs() + Get the number of available processes. + .. function:: nworkers() + :: + + nworkers() + Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. + .. function:: procs() - Returns a list of all process identifiers. + :: + + procs(S::SharedArray) + + Get the vector of processes that have mapped the shared array + .. function:: workers() + :: + + workers() + Returns a list of all worker process identifiers. + .. function:: rmprocs(pids...) + :: + + rmprocs(pids...) + Removes the specified workers. + .. function:: interrupt([pids...]) - Interrupt the current executing task on the specified workers. This is - equivalent to pressing Ctrl-C on the local machine. If no arguments are given, - all workers are interrupted. + :: + + interrupt([pids...]) + + Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted. + .. function:: myid() + :: + + myid() + Get the id of the current process. + .. function:: pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - Transform collections ``lsts`` by applying ``f`` to each element in parallel. - If ``nprocs() > 1``, the calling process will be dedicated to assigning tasks. - All other available processes will be used as parallel workers, or on the processes specified by ``pids``. - - If ``err_retry`` is true, it retries a failed application of ``f`` on a different worker. - If ``err_stop`` is true, it takes precedence over the value of ``err_retry`` and ``pmap`` stops execution on the first error. - + :: + + pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + + Transform collections ``lsts`` by applying ``f`` to each element in parallel. If ``nprocs() > 1``, the calling process will be dedicated to assigning tasks. All other available processes will be used as parallel workers, or on the processes specified by If ``err_retry`` is true, it retries a failed application of ``f`` on a different worker. If ``err_stop`` is true, it takes precedence over the value of ``err_retry`` and ``pmap`` stops execution on the first error. + .. function:: remotecall(id, func, args...) + :: + + remotecall(id, func, args...) + Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. + .. function:: wait([x]) - Block the current task until some event occurs, depending on the type - of the argument: - - * ``RemoteRef``: Wait for a value to become available for the specified remote reference. - - * ``Condition``: Wait for ``notify`` on a condition. - - * ``Process``: Wait for a process or process chain to exit. The ``exitcode`` field of a process can be used to determine success or failure. - - * ``Task``: Wait for a ``Task`` to finish, returning its result value. If the task fails with an exception, the exception is propagated (re-thrown in the task that called ``wait``). - - * ``RawFD``: Wait for changes on a file descriptor (see `poll_fd` for keyword arguments and return code) - - If no argument is passed, the task blocks for an undefined period. If the task's - state is set to ``:waiting``, it can only be restarted by an explicit call to - ``schedule`` or ``yieldto``. If the task's state is ``:runnable``, it might be - restarted unpredictably. - - Often ``wait`` is called within a ``while`` loop to ensure a waited-for condition - is met before proceeding. + :: + + wait([x]) + + Block the current task until some event occurs, depending on the type of the argument: If no argument is passed, the task blocks for an undefined period. If the task's state is set to ``:waiting``, it can only be restarted by an explicit call to ``schedule`` or ``yieldto``. If the task's state is ``:runnable``, it might be restarted unpredictably. Often ``wait`` is called within a ``while`` loop to ensure a waited-for condition is met before proceeding. + .. function:: fetch(RemoteRef) + :: + + fetch(RemoteRef) + Wait for and get the value of a remote reference. + .. function:: remotecall_wait(id, func, args...) + :: + + remotecall_wait(id, func, args...) + Perform ``wait(remotecall(...))`` in one message. + .. function:: remotecall_fetch(id, func, args...) + :: + + remotecall_fetch(id, func, args...) + Perform ``fetch(remotecall(...))`` in one message. + .. function:: put!(RemoteRef, value) - Store a value to a remote reference. Implements "shared queue of length 1" semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. + :: + + put!(RemoteRef, value) + + Store a value to a remote reference. Implements ``shared queue of length 1`` semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. + .. function:: take!(RemoteRef) + :: + + take!(RemoteRef) + Fetch the value of a remote reference, removing it so that the reference is empty again. + .. function:: isready(r::RemoteRef) - Determine whether a ``RemoteRef`` has a value stored to it. Note that this function - can cause race conditions, since by the time you receive its result it may - no longer be true. It is recommended that this function only be used on a - ``RemoteRef`` that is assigned once. - - If the argument ``RemoteRef`` is owned by a different node, this call will block to - wait for the answer. It is recommended to wait for ``r`` in a separate task instead, - or to use a local ``RemoteRef`` as a proxy:: - - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block + :: + + isready(r::RemoteRef) + + Determine whether a ``RemoteRef`` has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. It is recommended that this function only be used on a ``RemoteRef`` that is assigned once. If the argument ``RemoteRef`` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for ``r`` in a separate task instead, or to use a local + .. function:: RemoteRef() - Make an uninitialized remote reference on the local machine. + :: + + RemoteRef(n) + + Make an uninitialized remote reference on process ``n``. + .. function:: RemoteRef(n) + :: + + RemoteRef(n) + Make an uninitialized remote reference on process ``n``. + .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - Waits till ``testcb`` returns ``true`` or for ``secs``` seconds, whichever is earlier. - ``testcb`` is polled every ``pollint`` seconds. + :: + + timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + + Waits till ``testcb`` returns ``true`` or for ``secs`` seconds, whichever is earlier. `testcb`` is polled every ``pollint`` seconds. + .. function:: @spawn - Execute an expression on an automatically-chosen process, returning a - ``RemoteRef`` to the result. + :: + + @spawn() + + Execute an expression on an automatically-chosen process, returning a ``RemoteRef`` to the result. + .. function:: @spawnat - Accepts two arguments, ``p`` and an expression, and runs the expression - asynchronously on process ``p``, returning a ``RemoteRef`` to the result. + :: + + @spawnat() + + Accepts two arguments, ``p`` and an expression, and runs the expression asynchronously on process ``p``, returning a + .. function:: @fetch + :: + + @fetch() + Equivalent to ``fetch(@spawn expr)``. + .. function:: @fetchfrom + :: + + @fetchfrom() + Equivalent to ``fetch(@spawnat p expr)``. + .. function:: @async - Schedule an expression to run on the local machine, also adding it to the - set of items that the nearest enclosing ``@sync`` waits for. + :: + + @async() + + Schedule an expression to run on the local machine, also adding it to the set of items that the nearest enclosing ``@sync`` waits for. + .. function:: @sync + :: + + @sync() + Wait until all dynamically-enclosed uses of ``@async``, ``@spawn``, - ``@spawnat`` and ``@parallel`` are complete. + .. function:: @parallel - A parallel for loop of the form :: - - @parallel [reducer] for var = range - body - end - - The specified range is partitioned and locally executed across all workers. - In case an optional reducer function is specified, @parallel performs local - reductions on each worker with a final reduction on the calling process. - - Note that without a reducer function, @parallel executes asynchronously, - i.e. it spawns independent tasks on all available workers and returns - immediately without waiting for completion. To wait for completion, prefix - the call with ``@sync``, like :: - - @sync @parallel for var = range - body - end + :: + + @parallel() + + A parallel for loop of the form The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, reduction on the calling process. Note that without a reducer function, @parallel executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with ``@sync``, like + Shared Arrays (Experimental, UNIX-only feature) ----------------------------------------------- .. function:: SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - Construct a SharedArray of a bitstype ``T`` and size ``dims`` across the processes - specified by ``pids`` - all of which have to be on the same host. - - If ``pids`` is left unspecified, the shared array will be mapped across all processes - on the current host, including the master. But, ``localindexes`` and ``indexpids`` - will only refer to worker processes. This facilitates work distribution code to use - workers for actual computation with the master process acting as a driver. - - If an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, - it is called on all the participating workers. + :: + + SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + + Construct a SharedArray of a bitstype ``T`` and size ``dims`` across the processes specified by ``pids`` - all of which have to be on the same host. If ``pids`` is left unspecified, the shared array will be mapped across all processes on the current host, including the master. But, ``localindexes`` and ``indexpids`` will only refer to worker processes. This facilitates work distribution code to use workers for actual computation with the master process acting as a driver. If an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, it is called on all the participating workers. + .. function:: procs(S::SharedArray) + :: + + procs(S::SharedArray) + Get the vector of processes that have mapped the shared array + .. function:: sdata(S::SharedArray) + :: + + sdata(S::SharedArray) + Returns the actual ``Array`` object backing ``S`` + .. function:: indexpids(S::SharedArray) - Returns the index of the current worker into the ``pids`` vector, i.e., the list of workers mapping - the SharedArray + :: + + indexpids(S::SharedArray) + + Returns the index of the current worker into the ``pids`` vector, i.e., the list of workers mapping the SharedArray + Cluster Manager Interface ------------------------- @@ -380,41 +508,48 @@ Cluster Manager Interface .. function:: launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - Implemented by cluster managers. For every Julia worker launched by this function, it should append a ``WorkerConfig`` entry - to ``launched`` and notify ``launch_ntfy``. The function MUST exit once all workers, requested by ``manager`` have been launched. - ``params`` is a dictionary of all keyword arguments ``addprocs`` was called with. + :: + + launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + + Implemented by cluster managers. For every Julia worker launched by this function, it should append a ``WorkerConfig`` entry to once all workers, requested by ``manager`` have been launched. was called with. + .. function:: manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - Implemented by cluster managers. It is called on the master process, during a worker's lifetime, - with appropriate ``op`` values: - - - with ``:register``/``:deregister`` when a worker is added / removed - from the Julia worker pool. - - with ``:interrupt`` when ``interrupt(workers)`` is called. The - :class:`ClusterManager` should signal the appropriate worker with an - interrupt signal. - - with ``:finalize`` for cleanup purposes. + :: + + manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + + Implemented by cluster managers. It is called on the master process, during a worker's lifetime, with appropriate ``op`` values: + .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified - by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` + :: + + kill(manager::FooManager, pid::Int, config::WorkerConfig) + + Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. + .. function:: init_worker(manager::FooManager) - Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. - Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets - for transport. + :: + + init_worker(manager::FooManager) + + Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets for transport. + .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, - specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read - off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation - must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` - sets up TCP/IP socket connections in-between workers. - + :: + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. + .. function:: Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index 585ff66ec8796..d1bcf1e8b74b0 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -9,139 +9,244 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, .. function:: dir() -> AbstractString - Returns the absolute path of the package directory. - This defaults to ``joinpath(homedir(),".julia","v$(VERSION.major).$(VERSION.minor)")`` on all platforms - (i.e. ``~/.julia/v0.4`` in UNIX shell syntax). If the ``JULIA_PKGDIR`` environment variable is set, then - that path is used in the returned value as ``joinpath(ENV["JULIA_PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")``. - If ``JULIA_PKGDIR`` is a relative path, it is interpreted relative to whatever the current working directory is. + :: + + dir(names...) -> AbstractString + + Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. + .. function:: dir(names...) -> AbstractString - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. - In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. + :: + + dir(names...) -> AbstractString + + Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. + .. function:: init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - Initialize ``Pkg.dir()`` as a package directory. - This will be done automatically when the ``JULIA_PKGDIR`` is not set and ``Pkg.dir()`` uses its default value. - As part of this process, clones a local METADATA git repository from the site and branch specified by its arguments, which - are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. + :: + + init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) + + Initialize ``Pkg.dir()`` as a package directory. This will be done automatically when the ``JULIA_PKGDIR`` is not set and clones a local METADATA git repository from the site and branch specified by its arguments, which are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. + .. function:: resolve() - Determines an optimal, consistent set of package versions to install or upgrade to. - The optimal set of package versions is based on the contents of ``Pkg.dir("REQUIRE")`` and the state of installed packages in ``Pkg.dir()``, - Packages that are no longer required are moved into ``Pkg.dir(".trash")``. + :: + + resolve() + + Determines an optimal, consistent set of package versions to install or upgrade to. The optimal set of package versions is based on the contents of ``Pkg.dir(``REQUIRE``)`` and the state of installed packages in ``Pkg.dir()``, Packages that are no longer required are moved into ``Pkg.dir(``.trash``)``. + .. function:: edit() - Opens ``Pkg.dir("REQUIRE")`` in the editor specified by the ``VISUAL`` or ``EDITOR`` environment variables; - when the editor command returns, it runs ``Pkg.resolve()`` to determine and install a new optimal set of installed package versions. + :: + + edit() + + Opens ``Pkg.dir(``REQUIRE``)`` in the editor specified by the command returns, it runs ``Pkg.resolve()`` to determine and install a new optimal set of installed package versions. + .. function:: add(pkg, vers...) - Add a requirement entry for ``pkg`` to ``Pkg.dir("REQUIRE")`` and call ``Pkg.resolve()``. - If ``vers`` are given, they must be ``VersionNumber`` objects and they specify acceptable version intervals for ``pkg``. + :: + + add(pkg, vers...) + + Add a requirement entry for ``pkg`` to ``Pkg.dir(``REQUIRE``)`` and call ``Pkg.resolve()``. If ``vers`` are given, they must be intervals for ``pkg``. + .. function:: rm(pkg) - Remove all requirement entries for ``pkg`` from ``Pkg.dir("REQUIRE")`` and call ``Pkg.resolve()``. + :: + + rm(pkg) + + Remove all requirement entries for ``pkg`` from + .. function:: clone(url, [pkg]) - Clone a package directly from the git URL ``url``. - The package does not need to be a registered in ``Pkg.dir("METADATA")``. - The package repo is cloned by the name ``pkg`` if provided; - if not provided, ``pkg`` is determined automatically from ``url``. + :: + + clone(pkg) + + If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. + .. function:: clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``, clone it from that URL on the default branch. - The package does not need to have any registered versions. + :: + + clone(pkg) + + If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. + .. function:: available() -> Vector{ASCIIString} - Returns the names of available packages. + :: + + available(pkg) -> Vector{VersionNumber} + + Returns the version numbers available for package ``pkg``. + .. function:: available(pkg) -> Vector{VersionNumber} + :: + + available(pkg) -> Vector{VersionNumber} + Returns the version numbers available for package ``pkg``. + .. function:: installed() -> Dict{ASCIIString,VersionNumber} - Returns a dictionary mapping installed package names to the installed version number of each package. + :: + + installed(pkg) -> Void | VersionNumber + + If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. + .. function:: installed(pkg) -> Void | VersionNumber + :: + + installed(pkg) -> Void | VersionNumber + If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. + .. function:: status() + :: + + status() + Prints out a summary of what packages are installed and what version and state they're in. + .. function:: update() - Update package the metadata repo – kept in ``Pkg.dir("METADATA")`` – then update any fixed packages that can safely be pulled from their origin; - then call ``Pkg.resolve()`` to determine a new optimal set of packages versions. + :: + + update() + + Update package the metadata repo – kept in safely be pulled from their origin; then call ``Pkg.resolve()`` to determine a new optimal set of packages versions. + .. function:: checkout(pkg, [branch="master"]) - Checkout the ``Pkg.dir(pkg)`` repo to the branch ``branch``. - Defaults to checking out the "master" branch. - To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` + :: + + checkout(pkg[, branch="master"]) + + Checkout the ``Pkg.dir(pkg)`` repo to the branch ``branch``. Defaults to checking out the ``master`` branch. To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` + .. function:: pin(pkg) - Pin ``pkg`` at the current version. - To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` + :: + + pin(pkg, version) + + Pin ``pkg`` at registered version ``version``. + .. function:: pin(pkg, version) + :: + + pin(pkg, version) + Pin ``pkg`` at registered version ``version``. + .. function:: free(pkg) - Free the package ``pkg`` to be managed by the package manager again. - It calls ``Pkg.resolve()`` to determine optimal package versions after. - This is an inverse for both ``Pkg.checkout`` and ``Pkg.pin``. - - You can also supply an iterable collection of package names, e.g., - ``Pkg.free(("Pkg1", "Pkg2"))`` to free multiple packages at once. + :: + + free(pkg) + + Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and You can also supply an iterable collection of package names, e.g., once. + .. function:: build() - Run the build scripts for all installed packages in depth-first recursive order. + :: + + build(pkgs...) + + Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. + .. function:: build(pkgs...) - Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. - This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. + :: + + build(pkgs...) + + Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. + .. function:: generate(pkg,license) - Generate a new package named ``pkg`` with one of these license keys: ``"MIT"``, ``"BSD"`` or ``"ASL"``. - If you want to make a package with a different license, you can edit it afterwards. - Generate creates a git repo at ``Pkg.dir(pkg)`` for the package and inside it ``LICENSE.md``, ``README.md``, the julia entrypoint ``$pkg/src/$pkg.jl``, and a travis test file, ``.travis.yml``. + :: + + generate(pkg, license) + + Generate a new package named ``pkg`` with one of these license keys: ``MIT``, ``BSD`` or ``ASL``. If you want to make a package with a different license, you can edit it afterwards. Generate creates a git repo at ``Pkg.dir(pkg)`` for the package and inside it ``LICENSE.md``, ``README.md``, the julia entrypoint + .. function:: register(pkg, [url]) + :: + + register(pkg[, url]) + Register ``pkg`` at the git URL ``url``, defaulting to the configured origin URL of the git repo ``Pkg.dir(pkg)``. + .. function:: tag(pkg, [ver, [commit]]) - Tag ``commit`` as version ``ver`` of package ``pkg`` and create a version entry in ``METADATA``. - If not provided, ``commit`` defaults to the current commit of the ``pkg`` repo. - If ``ver`` is one of the symbols ``:patch``, ``:minor``, ``:major`` the next patch, minor or major version is used. - If ``ver`` is not provided, it defaults to ``:patch``. + :: + + tag(pkg[, ver[, commit]]) + + Tag ``commit`` as version ``ver`` of package ``pkg`` and create a version entry in ``METADATA``. If not provided, ``commit`` defaults to the current commit of the ``pkg`` repo. If ``ver`` is one of the symbols ``:patch``, ``:minor``, ``:major`` the next patch, minor or major version is used. If ``ver`` is not provided, it defaults to + .. function:: publish() + :: + + publish() + For each new package version tagged in ``METADATA`` not already published, make sure that the tagged package commits have been pushed to the repo at the registered URL for the package and if they all have, open a pull request to ``METADATA``. + .. function:: test() - Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + :: + + test(pkgs...) + + Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + .. function:: test(pkgs...) + :: + + test(pkgs...) + Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + + diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 1ab214c5efdb1..60b010eb02a4e 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -10,79 +10,85 @@ .. function:: @profile - ``@profile `` runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. + :: + + @profile() + + periodic backtraces. These are appended to an internal buffer of backtraces. + .. currentmodule:: Base.Profile - The methods in :mod:`Base.Profile` are not exported and need to be called e.g. as ``Profile.print()``. .. function:: clear() + :: + + clear() + Clear any existing backtraces from the internal buffer. + .. function:: print([io::IO = STDOUT,] [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) - Prints profiling results to ``io`` (by default, ``STDOUT``). If you - do not supply a ``data`` vector, the internal buffer of accumulated - backtraces will be used. ``format`` can be ``:tree`` or - ``:flat``. If ``C==true``, backtraces from C and Fortran code are - shown. ``combine==true`` merges instruction pointers that - correspond to the same line of code. ``cols`` controls the width - of the display. + :: + + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + + Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. + .. function:: print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to ``io``. This variant is used to examine - results exported by a previous call to :func:`retrieve`. - Supply the vector ``data`` of backtraces and a dictionary - ``lidict`` of line information. + :: + + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + + Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. + .. function:: init(; n::Integer, delay::Float64) - Configure the ``delay`` between backtraces (measured in seconds), - and the number ``n`` of instruction pointers that may be - stored. Each instruction pointer corresponds to a single line of - code; backtraces generally consist of a long list of instruction - pointers. Default settings can be obtained by calling this function - with no arguments, and each can be set independently using keywords - or in the order ``(n, delay)``. + :: + + init(; n::Integer, delay::Float64) + + Configure the ``delay`` between backtraces (measured in seconds), and the number ``n`` of instruction pointers that may be stored. Each instruction pointer corresponds to a single line of code; backtraces generally consist of a long list of instruction pointers. Default settings can be obtained by calling this function with no arguments, and each can be set independently using keywords or in the order ``(n, delay)``. + .. function:: fetch() -> data - Returns a reference to the internal buffer of backtraces. Note that - subsequent operations, like :func:`clear`, can affect - ``data`` unless you first make a copy. Note that the values in - ``data`` have meaning only on this machine in the current session, - because it depends on the exact memory addresses used in - JIT-compiling. This function is primarily for internal use; - :func:`retrieve` may be a better choice for most users. + :: + + fetch() -> data + + Returns a reference to the internal buffer of backtraces. Note that subsequent operations, like ``clear()``, can affect ``data`` unless you first make a copy. Note that the values in ``data`` have meaning only on this machine in the current session, because it depends on the exact memory addresses used in JIT-compiling. This function is primarily for internal use; ``retrieve()`` may be a better choice for most users. + .. function:: retrieve() -> data, lidict - "Exports" profiling results in a portable format, returning the set - of all backtraces (``data``) and a dictionary that maps the - (session-specific) instruction pointers in ``data`` to ``LineInfo`` - values that store the file name, function name, and line - number. This function allows you to save profiling results for - future analysis. + :: + + retrieve() -> data, lidict + + set of all backtraces (``data``) and a dictionary that maps the values that store the file name, function name, and line number. This function allows you to save profiling results for future analysis. + .. function:: callers(funcname, [data, lidict], [filename=], [linerange=]) -> Vector{Tuple{count, linfo}} - Given a previous profiling run, determine who called a particular - function. Supplying the filename (and optionally, range of line - numbers over which the function is defined) allows you to - disambiguate an overloaded method. The returned value is a vector - containing a count of the number of calls and line information - about the caller. One can optionally supply backtrace data - obtained from :func:`retrieve`; otherwise, the current internal profile - buffer is used. + :: + + callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} + + Given a previous profiling run, determine who called a particular function. Supplying the filename (and optionally, range of line numbers over which the function is defined) allows you to disambiguate an overloaded method. The returned value is a vector containing a count of the number of calls and line information about the caller. One can optionally supply backtrace data obtained from ``retrieve()``; otherwise, the current internal profile buffer is used. + .. function:: clear_malloc_data() - Clears any stored memory allocation data when running julia with - ``--track-allocation``. Execute the command(s) you want to test - (to force JIT-compilation), then call :func:`clear_malloc_data`. - Then execute your command(s) again, quit Julia, and examine the - resulting ``*.mem`` files. + :: + + clear_malloc_data() + + Clears any stored memory allocation data when running julia with ` force JIT-compilation), then call ``clear_malloc_data()``. Then execute your command(s) again, quit Julia, and examine the resulting ``*.mem`` files. + + diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index c216d3e3a6b5e..6d63982e9f15e 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -119,93 +119,123 @@ Sorting Functions .. function:: sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the vector ``v`` in place. ``QuickSort`` is used by default for numeric arrays - while ``MergeSort`` is used for other arrays. You can specify an algorithm to use via - the ``alg`` keyword (see `Sorting Algorithms`_ for available algorithms). The ``by`` - keyword lets you provide a function that will be applied to each element before - comparison; the ``lt`` keyword allows providing a custom "less than" function; use - ``rev=true`` to reverse the sorting order. These options are independent and can be - used together in all possible combinations: if both ``by`` and ``lt`` are specified, - the ``lt`` function is applied to the result of the ``by`` function; ``rev=true`` - reverses whatever ordering specified via the ``by`` and ``lt`` keywords. + :: + + sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the vector ``v`` in place. ``QuickSort`` is used by default for numeric arrays while ``MergeSort`` is used for other arrays. You can specify an algorithm to use via the ``alg`` keyword (see Sorting Algorithms for available algorithms). The ``by`` keyword lets you provide a function that will be applied to each element before comparison; the ``lt`` keyword allows providing a custom order. These options are independent and can be used together in all possible combinations: if both ``by`` and ``lt`` are specified, the ``lt`` function is applied to the result of the ``by`` function; ``rev=true`` reverses whatever ordering specified via the + .. function:: sort(v, [alg=,] [by=,] [lt=,] [rev=false]) - Variant of ``sort!`` that returns a sorted copy of ``v`` leaving ``v`` itself unmodified. + :: + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort a multidimensional array ``A`` along the given dimension. + .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + :: + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + Sort a multidimensional array ``A`` along the given dimension. + .. function:: sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - Return a permutation vector of indices of ``v`` that puts it in sorted order. - Specify ``alg`` to choose a particular sorting algorithm (see `Sorting Algorithms`_). - ``MergeSort`` is used by default, and since it is stable, the resulting permutation - will be the lexicographically first one that puts the input array into sorted order – - i.e. indices of equal elements appear in ascending order. If you choose a non-stable - sorting algorithm such as ``QuickSort``, a different permutation that puts the array - into order may be returned. The order is specified using the same keywords as ``sort!``. - - See also :func:`sortperm!` + :: + + sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Return a permutation vector of indices of ``v`` that puts it in sorted order. Specify ``alg`` to choose a particular sorting algorithm (see Sorting Algorithms). ``MergeSort`` is used by default, and since it is stable, the resulting permutation will be the lexicographically first one that puts the input array into sorted order – i.e. indices of equal elements appear in ascending order. If you choose a non-stable sorting algorithm such as order may be returned. The order is specified using the same keywords as ``sort!``. See also ``sortperm!()`` + .. function:: sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - Like ``sortperm``, but accepts a preallocated index vector ``ix``. If ``initialized`` is ``false`` - (the default), ix is initialized to contain the values ``1:length(v)``. - - See also :func:`sortperm` + :: + + sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + + Like ``sortperm``, but accepts a preallocated index vector ``ix``. If ``initialized`` is ``false`` (the default), ix is initialized to contain the values ``1:length(v)``. See also ``sortperm()`` + .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + :: + + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + Sort the rows of matrix ``A`` lexicographically. + .. function:: sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + :: + + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + Sort the columns of matrix ``A`` lexicographically. - + Order-Related Functions ----------------------- .. function:: issorted(v, [by=,] [lt=,] [rev=false]) - Test whether a vector is in sorted order. The ``by``, ``lt`` and ``rev`` - keywords modify what order is considered to be sorted just as they do for ``sort``. + :: + + issorted(v, [by=,] [lt=,] [rev=false]) + + Test whether a vector is in sorted order. The ``by``, ``lt`` and as they do for ``sort``. + .. function:: searchsorted(a, x, [by=,] [lt=,] [rev=false]) - Returns the range of indices of ``a`` which compare as equal to ``x`` according to the - order specified by the ``by``, ``lt`` and ``rev`` keywords, assuming that ``a`` is - already sorted in that order. Returns an empty range located at the insertion point if - ``a`` does not contain values equal to ``x``. + :: + + searchsorted(a, x, [by=,] [lt=,] [rev=false]) + + Returns the range of indices of ``a`` which compare as equal to order. Returns an empty range located at the insertion point if + .. function:: searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the first value in ``a`` greater than or equal to ``x``, - according to the specified order. Returns ``length(a)+1`` if ``x`` is greater - than all values in ``a``. + :: + + searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + + Returns the index of the first value in ``a`` greater than or equal to ``x``, according to the specified order. Returns ``length(a)+1`` if ``x`` is greater than all values in ``a``. + .. function:: searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the last value in ``a`` less than or equal to ``x``, - according to the specified order. Returns ``0`` if ``x`` is less than all - values in ``a``. + :: + + searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + + Returns the index of the last value in ``a`` less than or equal to less than all values in ``a``. + .. function:: select!(v, k, [by=,] [lt=,] [rev=false]) - Partially sort the vector ``v`` in place, according to the order specified by ``by``, - ``lt`` and ``rev`` so that the value at index ``k`` (or range of adjacent values if - ``k`` is a range) occurs at the position where it would appear if the array were - fully sorted via a non-stable algorithm. If ``k`` is a single index, that value - is returned; if ``k`` is a range, an array of values at those indices is returned. - Note that ``select!`` does not fully sort the input array. + :: + + select!(v, k, [by=,] [lt=,] [rev=false]) + + Partially sort the vector ``v`` in place, according to the order specified by ``by``, ``lt`` and ``rev`` so that the value at index the position where it would appear if the array were fully sorted via a non-stable algorithm. If ``k`` is a single index, that value is returned; if ``k`` is a range, an array of values at those indices is returned. Note that ``select!`` does not fully sort the input array. + .. function:: select(v, k, [by=,] [lt=,] [rev=false]) - Variant of ``select!`` which copies ``v`` before partially sorting it, thereby - returning the same thing as ``select!`` but leaving ``v`` unmodified. - + :: + + select(v, k, [by=,] [lt=,] [rev=false]) + + Variant of ``select!`` which copies ``v`` before partially sorting it, thereby returning the same thing as ``select!`` but leaving + Sorting Algorithms ------------------ diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index 4cba2c7179790..04e11ea903f81 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,408 +6,670 @@ .. function:: length(s) + :: + + length(s) + The number of characters in string ``s``. + .. function:: sizeof(s::AbstractString) + :: + + sizeof(s::AbstractString) + The number of bytes in string ``s``. + .. function:: *(s, t) + :: + + *(s, t) + Concatenate strings. The ``*`` operator is an alias to this function. - - .. doctest:: + julia> "Hello " * "world" "Hello world" .. function:: ^(s, n) + :: + + ^(s, n) + Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. - - .. doctest:: - - julia> "Test "^3 - "Test Test Test " + .. function:: string(xs...) + :: + + string(xs...) + Create a string from any values using the ``print`` function. + .. function:: repr(x) + :: + + repr(x) + Create a string from any value using the ``showall`` function. + .. function:: bytestring(::Ptr{UInt8}, [length]) - Create a string from the address of a C (0-terminated) string encoded in ASCII or UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + :: + + bytestring(s) + + Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. + .. function:: bytestring(s) + :: + + bytestring(s) + Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. + .. function:: ascii(::Array{UInt8,1}) - Create an ASCII string from a byte array. + :: + + ascii(::Ptr{UInt8}[, length]) + + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + .. function:: ascii(s) - Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + :: + + ascii(::Ptr{UInt8}[, length]) + + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + .. function:: ascii(::Ptr{UInt8}, [length]) + :: + + ascii(::Ptr{UInt8}[, length]) + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + .. function:: utf8(::Array{UInt8,1}) - Create a UTF-8 string from a byte array. + :: + + utf8(s) + + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: utf8(::Ptr{UInt8}, [length]) - Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + :: + + utf8(s) + + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: utf8(s) + :: + + utf8(s) + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: normalize_string(s, normalform::Symbol) - Normalize the string ``s`` according to one of the four "normal - forms" of the Unicode standard: ``normalform`` can be ``:NFC``, - ``:NFD``, ``:NFKC``, or ``:NFKD``. Normal forms C (canonical - composition) and D (canonical decomposition) convert different - visually identical representations of the same abstract string into - a single canonical form, with form C being more compact. Normal - forms KC and KD additionally canonicalize "compatibility - equivalents": they convert characters that are abstractly similar - but visually distinct into a single canonical choice (e.g. they expand - ligatures into the individual characters), with form KC being more compact. - - Alternatively, finer control and additional transformations may be - be obtained by calling `normalize_string(s; keywords...)`, where - any number of the following boolean keywords options (which all default - to ``false`` except for ``compose``) are specified: - - * ``compose=false``: do not perform canonical composition - * ``decompose=true``: do canonical decomposition instead of canonical composition (``compose=true`` is ignored if present) - * ``compat=true``: compatibility equivalents are canonicalized - * ``casefold=true``: perform Unicode case folding, e.g. for case-insensitive string comparison - * ``newline2lf=true``, ``newline2ls=true``, or ``newline2ps=true``: convert various newline sequences (LF, CRLF, CR, NEL) into a linefeed (LF), line-separation (LS), or paragraph-separation (PS) character, respectively - * ``stripmark=true``: strip diacritical marks (e.g. accents) - * ``stripignore=true``: strip Unicode's "default ignorable" characters (e.g. the soft hyphen or the left-to-right marker) - * ``stripcc=true``: strip control characters; horizontal tabs and form feeds are converted to spaces; newlines are also converted to spaces unless a newline-conversion flag was specified - * ``rejectna=true``: throw an error if unassigned code points are found - * ``stable=true``: enforce Unicode Versioning Stability - - For example, NFKC corresponds to the options ``compose=true, compat=true, stable=true``. + :: + + normalize_string(s, normalform::Symbol) + + Normalize the string ``s`` according to one of the four ``normal forms`` of the Unicode standard: ``normalform`` can be ``:NFC``, composition) and D (canonical decomposition) convert different visually identical representations of the same abstract string into a single canonical form, with form C being more compact. Normal forms KC and KD additionally canonicalize ``compatibility equivalents``: they convert characters that are abstractly similar but visually distinct into a single canonical choice (e.g. they expand ligatures into the individual characters), with form KC being more compact. Alternatively, finer control and additional transformations may be be obtained by calling *normalize_string(s; keywords...)*, where any number of the following boolean keywords options (which all default to ``false`` except for ``compose``) are specified: For example, NFKC corresponds to the options ``compose=true, compat=true, stable=true``. + .. function:: graphemes(s) -> iterator over substrings of s - Returns an iterator over substrings of ``s`` that correspond to - the extended graphemes in the string, as defined by Unicode UAX #29. - (Roughly, these are what users would perceive as single characters, - even though they may contain more than one codepoint; for example - a letter combined with an accent mark is a single grapheme.) + :: + + graphemes(s) -> iterator over substrings of s + + Returns an iterator over substrings of ``s`` that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) + .. function:: isvalid(value) -> Bool - Returns true if the given value is valid for its type, - which currently can be one of ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + :: + + isvalid(str, i) + + Tells whether index ``i`` is valid for the given string + .. function:: isvalid(T, value) -> Bool - Returns true if the given value is valid for that type. - Types currently can be ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` - Values for ``Char`` can be of type ``Char`` or ``UInt32`` - Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` - Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` - Values for ``UTF32String`` can be ``UTF32String``, ``Vector{Char}`` or ``Vector{UInt32}`` + :: + + isvalid(str, i) + + Tells whether index ``i`` is valid for the given string + .. function:: is_assigned_char(c) -> Bool + :: + + is_assigned_char(c) -> Bool + Returns true if the given char or integer is an assigned Unicode code point. + .. function:: ismatch(r::Regex, s::AbstractString) -> Bool + :: + + ismatch(r::Regex, s::AbstractString) -> Bool + Test whether a string contains a match of the given regular expression. + .. function:: match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + :: + + match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + Search for the first match of the regular expression ``r`` in ``s`` and return a RegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessing ``m.match`` and the captured sequences can be retrieved by accessing ``m.captures`` The optional ``idx`` argument specifies an index at which to start the search. + .. function:: eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + :: + + eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + Search for all matches of a the regular expression ``r`` in ``s`` and return a iterator over the matches. If overlap is true, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges. + .. function:: matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + :: + + matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + Return a vector of the matching substrings from eachmatch. + .. function:: lpad(string, n, p) + :: + + lpad(string, n, p) + Make a string at least ``n`` columns wide when printed, by padding on the left with copies of ``p``. + .. function:: rpad(string, n, p) + :: + + rpad(string, n, p) + Make a string at least ``n`` columns wide when printed, by padding on the right with copies of ``p``. + .. function:: search(string, chars, [start]) - Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression (though regular expressions are only allowed on contiguous strings, such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that ``s[search(s,x)] == x``: - - ``search(string, "substring")`` = ``start:end`` such that ``string[start:end] == "substring"``, or ``0:-1`` if unmatched. - - ``search(string, 'c')`` = ``index`` such that ``string[index] == 'c'``, or ``0`` if unmatched. + :: + + search(string, chars[, start]) + + Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that ``s[search(s,x)] == x``: + .. function:: rsearch(string, chars, [start]) - Similar to ``search``, but returning the last occurrence of the given characters within the given string, searching in reverse from ``start``. + :: + + rsearch(string, chars[, start]) + + Similar to ``search``, but returning the last occurrence of the given characters within the given string, searching in reverse from + .. function:: searchindex(string, substring, [start]) + :: + + searchindex(string, substring[, start]) + Similar to ``search``, but return only the start index at which the substring is found, or 0 if it is not. + .. function:: rsearchindex(string, substring, [start]) + :: + + rsearchindex(string, substring[, start]) + Similar to ``rsearch``, but return only the start index at which the substring is found, or 0 if it is not. + .. function:: contains(haystack, needle) + :: + + contains(haystack, needle) + Determine whether the second argument is a substring of the first. + .. function:: replace(string, pat, r[, n]) + :: + + replace(string, pat, r[, n]) + Search for the given pattern ``pat``, and replace each occurrence with ``r``. If ``n`` is provided, replace at most ``n`` occurrences. As with search, the second argument may be a single character, a vector or a set of characters, a string, or a regular expression. If ``r`` is a function, each occurrence is replaced with ``r(s)`` where ``s`` is the matched substring. + .. function:: split(string, [chars]; limit=0, keep=true) + :: + + split(string, [chars]; limit=0, keep=true) + Return an array of substrings by splitting the given string on occurrences of the given character delimiters, which may be specified in any of the formats allowed by ``search``'s second argument (i.e. a single character, collection of characters, string, or regular expression). If ``chars`` is omitted, it defaults to the set of all space characters, and ``keep`` is taken to be false. The two keyword arguments are optional: they are are a maximum size for the result and a flag determining whether empty fields should be kept in the result. + .. function:: rsplit(string, [chars]; limit=0, keep=true) + :: + + rsplit(string, [chars]; limit=0, keep=true) + Similar to ``split``, but starting from the end of the string. + .. function:: strip(string, [chars]) + :: + + strip(string[, chars]) + Return ``string`` with any leading and trailing whitespace removed. If ``chars`` (a character, or vector or set of characters) is provided, instead remove characters contained in it. + .. function:: lstrip(string, [chars]) - Return ``string`` with any leading whitespace removed. If ``chars`` (a character, or vector or set of characters) is provided, instead remove characters contained in it. + :: + + lstrip(string[, chars]) + + Return ``string`` with any leading whitespace removed. If ``chars`` remove characters contained in it. + .. function:: rstrip(string, [chars]) - Return ``string`` with any trailing whitespace removed. If ``chars`` (a character, or vector or set of characters) is provided, instead remove characters contained in it. + :: + + rstrip(string[, chars]) + + Return ``string`` with any trailing whitespace removed. If provided, instead remove characters contained in it. + .. function:: startswith(string, prefix | chars) + :: + + startswith(string, prefix | chars) + Returns ``true`` if ``string`` starts with ``prefix``. If the second argument is a vector or set of characters, tests whether the first character of ``string`` belongs to that set. + .. function:: endswith(string, suffix | chars) + :: + + endswith(string, suffix | chars) + Returns ``true`` if ``string`` ends with ``suffix``. If the second argument is a vector or set of characters, tests whether the last character of ``string`` belongs to that set. + .. function:: uppercase(string) + :: + + uppercase(string) + Returns ``string`` with all characters converted to uppercase. + .. function:: lowercase(string) + :: + + lowercase(string) + Returns ``string`` with all characters converted to lowercase. + .. function:: ucfirst(string) + :: + + ucfirst(string) + Returns ``string`` with the first character converted to uppercase. + .. function:: lcfirst(string) + :: + + lcfirst(string) + Returns ``string`` with the first character converted to lowercase. + .. function:: join(strings, delim, [last]) - Join an array of ``strings`` into a single string, inserting the given delimiter between adjacent strings. - If ``last`` is given, it will be used instead of ``delim`` between the last two strings. - For example, ``join(["apples", "bananas", "pineapples"], ", ", " and ") == "apples, bananas and pineapples"``. - - ``strings`` can be any iterable over elements ``x`` which are convertible to strings via ``print(io::IOBuffer, x)``. + :: + + join(strings, delim[, last]) + + Join an array of ``strings`` into a single string, inserting the given delimiter between adjacent strings. If ``last`` is given, it will be used instead of ``delim`` between the last two strings. For example, ``join([``apples``, `bananas``, ``pineapples``], ``, `, convertible to strings via `print(io::IOBuffer, x)``. + .. function:: chop(string) + :: + + chop(string) + Remove the last character from a string + .. function:: chomp(string) + :: + + chomp(string) + Remove a trailing newline from a string + .. function:: ind2chr(string, i) + :: + + ind2chr(string, i) + Convert a byte index to a character index + .. function:: chr2ind(string, i) + :: + + chr2ind(string, i) + Convert a character index to a byte index + .. function:: isvalid(str, i) + :: + + isvalid(str, i) + Tells whether index ``i`` is valid for the given string + .. function:: nextind(str, i) - Get the next valid string index after ``i``. Returns a value greater than ``endof(str)`` - at or after the end of the string. + :: + + nextind(str, i) + + Get the next valid string index after ``i``. Returns a value greater than ``endof(str)`` at or after the end of the string. + .. function:: prevind(str, i) - Get the previous valid string index before ``i``. Returns a value less than ``1`` at - the beginning of the string. + :: + + prevind(str, i) + + Get the previous valid string index before ``i``. Returns a value less than ``1`` at the beginning of the string. + .. function:: randstring([rng,] len=8) - Create a random ASCII string of length ``len``, consisting of upper- and - lower-case letters and the digits 0-9. The optional ``rng`` argument - specifies a random number generator, see :ref:`Random Numbers `. + :: + + randstring([rng], len=8) + + Create a random ASCII string of length ``len``, consisting of upper- and lower-case letters and the digits 0-9. The optional Numbers*. + .. function:: charwidth(c) + :: + + charwidth(c) + Gives the number of columns needed to print a character. + .. function:: strwidth(s) + :: + + strwidth(s) + Gives the number of columns needed to print a string. + .. function:: isalnum(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is alphanumeric, or whether this - is true for all elements of a string. A character is classified as alphabetic - if it belongs to the Unicode general category Letter or Number, i.e. a character whose - category code begins with 'L' or 'N'. + :: + + isalnum(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is alphanumeric, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter or Number, i.e. a character whose category code begins with 'L' or + .. function:: isalpha(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is alphabetic, or whether this - is true for all elements of a string. A character is classified as alphabetic - if it belongs to the Unicode general category Letter, i.e. a character whose - category code begins with 'L'. + :: + + isalpha(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is alphabetic, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'. + .. function:: isascii(c::Union{Char,AbstractString}) -> Bool - Tests whether a character belongs to the ASCII character set, or whether this - is true for all elements of a string. + :: + + isascii(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character belongs to the ASCII character set, or whether this is true for all elements of a string. + .. function:: iscntrl(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is a control character, or whether this - is true for all elements of a string. Control characters are the - non-printing characters of the Latin-1 subset of Unicode. + :: + + iscntrl(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a control character, or whether this is true for all elements of a string. Control characters are the non-printing characters of the Latin-1 subset of Unicode. + .. function:: isdigit(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is a numeric digit (0-9), or whether this - is true for all elements of a string. + :: + + isdigit(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a numeric digit (0-9), or whether this is true for all elements of a string. + .. function:: isgraph(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is printable, and not a space, or whether this - is true for all elements of a string. Any character that would cause a printer - to use ink should be classified with isgraph(c)==true. + :: + + isgraph(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is printable, and not a space, or whether this is true for all elements of a string. Any character that would cause a printer to use ink should be classified with isgraph(c)==true. + .. function:: islower(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is a lowercase letter, or whether this - is true for all elements of a string. A character is classified as lowercase - if it belongs to Unicode category Ll, Letter: Lowercase. + :: + + islower(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a lowercase letter, or whether this is true for all elements of a string. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase. + .. function:: isnumber(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is numeric, or whether this - is true for all elements of a string. A character is classified as numeric - if it belongs to the Unicode general category Number, i.e. a character whose - category code begins with 'N'. + :: + + isnumber(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is numeric, or whether this is true for all elements of a string. A character is classified as numeric if it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'. + .. function:: isprint(c::Union{Char,AbstractString}) -> Bool + :: + + isprint(c::Union{Char, AbstractString}) -> Bool + Tests whether a character is printable, including spaces, but not a control character. For strings, tests whether this is true for all elements of the string. + .. function:: ispunct(c::Union{Char,AbstractString}) -> Bool + :: + + ispunct(c::Union{Char, AbstractString}) -> Bool + Tests whether a character belongs to the Unicode general category Punctuation, i.e. a character whose category code begins with 'P'. For strings, tests whether this is true for all elements of the string. + .. function:: isspace(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is any whitespace character. Includes ASCII characters '\\t', '\\n', '\\v', '\\f', '\\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs. For strings, tests whether this is true for all elements of the string. + :: + + isspace(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is any whitespace character. Includes ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs. For strings, tests whether this is true for all elements of the string. + .. function:: isupper(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is an uppercase letter, or whether this - is true for all elements of a string. A character is classified as uppercase - if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. + :: + + isupper(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is an uppercase letter, or whether this is true for all elements of a string. A character is classified as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. + .. function:: isxdigit(c::Union{Char,AbstractString}) -> Bool - Tests whether a character is a valid hexadecimal digit, or whether this - is true for all elements of a string. + :: + + isxdigit(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a valid hexadecimal digit, or whether this is true for all elements of a string. + .. function:: symbol(x...) -> Symbol + :: + + symbol(x...) -> Symbol + Create a ``Symbol`` by concatenating the string representations of the arguments together. + .. function:: escape_string(str::AbstractString) -> AbstractString - General escaping of traditional C and Unicode escape sequences. See :func:`print_escaped` for more general escaping. + :: + + escape_string(str::AbstractString) -> AbstractString + + General escaping of traditional C and Unicode escape sequences. See + .. function:: unescape_string(s::AbstractString) -> AbstractString - General unescaping of traditional C and Unicode escape sequences. Reverse of :func:`escape_string`. See also :func:`print_unescaped`. + :: + + unescape_string(s::AbstractString) -> AbstractString + + General unescaping of traditional C and Unicode escape sequences. Reverse of ``escape_string()``. See also ``print_unescaped()``. + .. function:: utf16(s) - Create a UTF-16 string from a byte array, array of ``UInt16``, or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) - - Note that the resulting ``UTF16String`` data is terminated by the NUL - codepoint (16-bit zero), which is not treated as a character in the - string (so that it is mostly invisible in Julia); this allows the - string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - `utf16(s)` conversion function. If you have a ``UInt16`` array - ``A`` that is already NUL-terminated valid UTF-16 data, then you - can instead use `UTF16String(A)`` to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. + :: + + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + + Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. + .. function:: utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) + :: + + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. + .. function:: utf32(s) - Create a UTF-32 string from a byte array, array of ``Char`` or ``UInt32``, or - any other string type. (Conversions of byte arrays check for a - byte-order marker in the first four bytes, and do not include it in - the resulting string.) - - Note that the resulting ``UTF32String`` data is terminated by the NUL - codepoint (32-bit zero), which is not treated as a character in the - string (so that it is mostly invisible in Julia); this allows the - string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - `utf32(s)` conversion function. If you have a ``Char`` or ``UInt32`` array - ``A`` that is already NUL-terminated UTF-32 data, then you - can instead use `UTF32String(A)`` to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. + :: + + wstring(s) + + This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. + .. function:: utf32(::Union{Ptr{Char},Ptr{UInt32},Ptr{Int32}} [, length]) - Create a string from the address of a NUL-terminated UTF-32 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. + :: + + wstring(s) + + This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. + .. function:: wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, - depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. - The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` - is also provided. - + :: + + wstring(s) + + This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. + diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst index c73055418d13b..e7cd69d6333a9 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -14,12 +14,14 @@ binary install, you can run the test suite using ``Base.runtests()``. .. function:: runtests([tests=["all"] [, numcores=iceil(CPU_CORES/2) ]]) - Run the Julia unit tests listed in ``tests``, which can be either a - string or an array of strings, using ``numcores`` processors. (not exported) - + :: + + runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) + + Run the Julia unit tests listed in ``tests``, which can be either a string or an array of strings, using ``numcores`` processors. (not exported) + .. module:: Base.Test - Test Framework -------------- @@ -133,26 +135,49 @@ Macros .. function:: @test(ex) + :: + + @test(ex) + Test the expression ``ex`` and calls the current handler to handle the result. + .. function:: @test_throws(extype, ex) - Test that the expression ``ex`` throws an exception of type ``extype`` and calls the current handler to handle the result. + :: + + @test_throws(extype, ex) + + Test that the expression ``ex`` throws an exception of type + .. function:: @test_approx_eq(a, b) - Test two floating point numbers ``a`` and ``b`` for equality taking in account - small numerical errors. + :: + + @test_approx_eq(a, b) + + Test two floating point numbers ``a`` and ``b`` for equality taking in account small numerical errors. + .. function:: @test_approx_eq_eps(a, b, tol) - Test two floating point numbers ``a`` and ``b`` for equality taking in account - a margin of tolerance given by ``tol``. + :: + + @test_approx_eq_eps(a, b, tol) + + Test two floating point numbers ``a`` and ``b`` for equality taking in account a margin of tolerance given by ``tol``. + Functions --------- .. function:: with_handler(f, handler) + :: + + with_handler(f, handler) + Run the function ``f`` using the ``handler`` as the handler. + From 5e375cd314d3341cea949eab2eaf099a524b0e0d Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 17:46:47 -0400 Subject: [PATCH 11/27] RST's handling of quotes is seriously weird --- base/docs/helpdb.jl | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index 952a01ea82c9e..08a5d6742b44a 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -2159,7 +2159,7 @@ doc""" setenv(command, env; dir=working_dir) Set environment variables to use when running the given command. -of strings of the form ``var=val``, or zero or more +of strings of the form `var=val`, or zero or more replace) the existing environment, create `env` by `copy(ENV)` and then setting `env[`var`]=val` as desired, or use The `dir` keyword argument can be used to specify a working @@ -2171,7 +2171,7 @@ doc""" withenv(f::Function, kv::Pair...) Execute `f()` in an environment that is temporarily modified (not -replaced as in `setenv`) by zero or more ``var`=>val` +replaced as in `setenv`) by zero or more `var`=>val` arguments `kv`. `withenv` is generally used via the be used to temporarily unset an environment variable (if it is set). When `withenv` returns, the original environment has been @@ -4472,8 +4472,8 @@ doc""" Construct a date formatting object that can be passed repeatedly for parsing similarly formatted date strings. `format` is a -format string in the form described above (e.g. ``yyyy-mm- -dd``). +format string in the form described above (e.g. `yyyy-mm- +dd`). """ Dates.Dates @@ -5934,7 +5934,7 @@ is large, and is only read once and not written to. If `ignore_invalid_chars` is `true`, bytes in `source` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. -If `quotes` is `true`, column enclosed within double-quote (``) +If `quotes` is `true`, column enclosed within double-quote `"` characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. @@ -6058,7 +6058,7 @@ stack, typically using the richest supported multimedia output for display `d` only, throwing a `MethodError` if `d` cannot display objects of this type. There are also two variants with a `mime` argument (a MIME type -string, such as ``image/png``), which attempt to display `x` +string, such as `image/png`), which attempt to display `x` using the requested MIME type *only*, throwing a `MethodError` if this type is not supported by either the display(s) or by `x`. With these variants, one can also supply the `raw` data in the @@ -6096,16 +6096,16 @@ doc""" The `display` functions ultimately call `writemime` in order to write an object `x` as a given `mime` type to a given I/O provide a rich multimedia representation of a user-defined type -for `T`, via: `writemime(stream, ::MIME`mime`, x::T) = ...`, +for `T`, via: `writemime(stream, ::MIME"mime", x::T) = ...`, where `mime` is a MIME-type string and the function body calls literal strings; to construct `MIME` types in a more flexible -manner use `MIME{symbol(``)}`.) +manner use `MIME{symbol("")}`.) For example, if you define a `MyImage` type and know how to write it to a PNG file, you could define a function `writemime(stream, be displayed on any PNG-capable `Display` (such as IJulia). As usual, be sure to `import Base.writemime` in order to add new methods to the built-in Julia function `writemime`. -Technically, the `MIME`mime`` macro defines a singleton type +Technically, the `MIME"mime"` macro defines a singleton type for the given `mime` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. @@ -6127,8 +6127,8 @@ doc""" Returns an `AbstractString` or `Vector{UInt8}` containing the representation of `x` in the requested `mime` type, as written by `writemime` (throwing a `MethodError` if no appropriate -MIME types with textual representations (such as ``text/html`` -or ``application/postscript``), whereas binary data is returned +MIME types with textual representations (such as `text/html` +or `application/postscript`), whereas binary data is returned as `Vector{UInt8}`. (The function `istext(mime)` returns whether or not Julia treats a given `mime` type as text.) As a special case, if `x` is an `AbstractString` (for textual @@ -6190,7 +6190,7 @@ Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). The file is passed via the stream argument. When you initialize -the stream, use ``r`` for a `read-only` array, and ``w+`` +the stream, use `r` for a `read-only` array, and `w+` to create a new array used to write values to disk. Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for @@ -6352,7 +6352,7 @@ bind doc""" send(socket::UDPSocket, host::IPv4, port::Integer, msg) -Send `msg` over `socket to ``host:port`. +Send `msg` over `socket to `host:port`. """ send @@ -7169,8 +7169,8 @@ doc""" Reorders the Generalized Schur factorization of a matrix `(A, B) = and returns a GeneralizedSchur object `GS`. The selected -eigenvalues appear in the leading diagonal of both``(GS[:S], -GS[:T])`` and the left and right unitary/orthogonal Schur vectors +eigenvalues appear in the leading diagonal of both`(GS[:S], +GS[:T])` and the left and right unitary/orthogonal Schur vectors are also reordered such that `(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}` still holds and the generalized eigenvalues of """ @@ -8219,7 +8219,7 @@ cld doc""" mod(x, y) -Modulus after division, returning in the range [0,``y``), if `y` +Modulus after division, returning in the range [0,`y`), if `y` is positive, or (`y`,0] if `y` is negative. """ mod @@ -8239,7 +8239,7 @@ doc""" rem(x, y) Remainder from Euclidean division, returning a value of the same -sign as``x``, and smaller in magnitude than `y`. This value is +sign as`x`, and smaller in magnitude than `y`. This value is always exact. """ rem @@ -11245,7 +11245,7 @@ returns immediately. unlock doc""" - addprocs(n::Integer; exeflags=``) -> List of process identifiers + addprocs(n::Integer; exeflags="") -> List of process identifiers Launches workers using the in-built `LocalManager` which only launches workers on the local host. This can be used to take @@ -11262,7 +11262,7 @@ Equivalent to `addprocs(CPU_CORES)` addprocs doc""" - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + addprocs(machines; tunnel=false, sshflags=`, max_parallel=10, exeflags=`) -> List of process identifiers Add processes on remote machines via SSH. Requires julia to be installed in the same location on each node, or to be available via @@ -11459,7 +11459,7 @@ RemoteRef doc""" timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) -Waits till `testcb` returns `true` or for `secs`` seconds, +Waits till `testcb` returns `true` or for `secs` seconds, whichever is earlier. `testcb` is polled every `pollint` seconds. """ @@ -11816,7 +11816,7 @@ doc""" generate(pkg, license) Generate a new package named `pkg` with one of these license -keys: ``MIT``, ``BSD`` or ``ASL``. If you want to make +keys: `MIT`, `BSD` or `ASL`. If you want to make a package with a different license, you can edit it afterwards. Generate creates a git repo at `Pkg.dir(pkg)` for the package and inside it `LICENSE.md`, `README.md`, the julia entrypoint From 362ac82c3e104abc2382e04d9731d082ba817ed7 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 18:22:47 -0400 Subject: [PATCH 12/27] handle signatures better --- doc/genstdlib.jl | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl index fb2696bc7a3db..a5c1d502186f5 100644 --- a/doc/genstdlib.jl +++ b/doc/genstdlib.jl @@ -1,4 +1,5 @@ using .Markdown +using Base.Markdown: MD cd(dirname(@__FILE__)) @@ -8,6 +9,22 @@ ident(mod, x) = "$mod.$(isop(x) ? "(:($x))" : x)" getdoc(mod, x) = try eval(parse("@doc $(ident(mod, x))")) catch e end +flat_content(md) = md +flat_content(xs::Vector) = reduce((xs, x) -> vcat(xs,flat_content(x)), [], xs) +flat_content(md::MD) = flat_content(md.content) +flatten(md::MD) = MD(flat_content(md)) + +issig(md) = isa(md, Markdown.Code) && length(split(md.code, "\n")) == 1 + +function splitsig(md) + md = flatten(md) + sig = nothing + if !isempty(md.content) && issig(md.content[1]) + sig = shift!(md.content) + end + return md, sig +end + function translate(file) @assert isfile(file) ls = split(readall(file), "\n")[1:end-1] @@ -24,18 +41,20 @@ function translate(file) func = match(r".. function:: (@?[^\(\s\{]+)", l) func == nothing && (warn("bad function $l"); continue) func = func.captures[1] + doc = getdoc(mod, func) - if getdoc(mod, func) == nothing + if doc == nothing info("no docs for $(ident(mod, func))") println(io, l) doccing = false continue end + doc, sig = splitsig(doc) doccing = true - println(io, l) + println(io, sig == nothing ? l : ".. function:: $(sig.code)") println(io) - for l in split(Markdown.rst(getdoc(mod, func)), "\n") + for l in split(Markdown.rst(doc), "\n") println(io, " ", l) end println(io) From a079cd22349e9ff62de114b6f512b7071c65bac3 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 18:23:05 -0400 Subject: [PATCH 13/27] get rid of those pesky signatures --- doc/stdlib/arrays.rst | 692 ++----------------- doc/stdlib/base.rst | 826 ++--------------------- doc/stdlib/c.rst | 88 +-- doc/stdlib/collections.rst | 630 ++---------------- doc/stdlib/dates.rst | 265 +------- doc/stdlib/file.rst | 246 +------ doc/stdlib/io-network.rst | 540 +-------------- doc/stdlib/libc.rst | 58 +- doc/stdlib/libdl.rst | 28 +- doc/stdlib/linalg.rst | 690 ++----------------- doc/stdlib/math.rst | 1285 +++--------------------------------- doc/stdlib/numbers.rst | 310 +-------- doc/stdlib/parallel.rst | 270 +------- doc/stdlib/pkg.rst | 130 +--- doc/stdlib/profile.rst | 44 +- doc/stdlib/sort.rst | 54 +- doc/stdlib/strings.rst | 364 +--------- doc/stdlib/test.rst | 26 +- 18 files changed, 437 insertions(+), 6109 deletions(-) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index ead0d7d5ec3f1..ac37b479c02a8 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -9,46 +9,26 @@ Basic functions .. function:: ndims(A) -> Integer - :: - - ndims(A) -> Integer - Returns the number of dimensions of A -.. function:: size(A, [dim...]) +.. function:: size(A[, dim...]) - :: - - size(A[, 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.: -.. function:: iseltype(A,T) +.. function:: iseltype(A, T) - :: - - iseltype(A, T) - Tests whether A or its elements are of type T -.. function:: length(A) -> Integer +.. function:: length(s) - :: - - length(s) - The number of characters in string ``s``. .. function:: eachindex(A...) - :: - - 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 (like ``Array``), this is simply the range ``1:length(A)``. For other array types, this returns a specialized Cartesian range to efficiently index into the array with indices specified for every dimension. Example for a sparse 2-d array: @@ -69,64 +49,36 @@ largest range along each dimension. .. function:: countnz(A) - :: - - countnz(A) - Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use ``nnz``, which returns the number of stored values. .. function:: conj!(A) - :: - - conj!(A) - Convert an array to its complex conjugate in-place .. function:: stride(A, k) - :: - - stride(A, k) - Returns the distance in memory (in number of elements) between adjacent elements in dimension k .. function:: strides(A) - :: - - strides(A) - Returns a tuple of the memory strides in each dimension -.. function:: ind2sub(dims, index) -> subscripts +.. function:: ind2sub(a, index) -> subscripts - :: - - ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` .. function:: ind2sub(a, index) -> subscripts - :: - - ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` .. function:: sub2ind(dims, i, j, k...) -> index - :: - - sub2ind(dims, i, j, k...) -> index - The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts @@ -135,172 +87,96 @@ Constructors .. function:: Array(dims) - :: - - Array(dims) - element type ``T``. ``dims`` may be a tuple or a series of integer arguments. The syntax ``Array(T, dims)`` is also available, but deprecated. -.. function:: getindex(type[, elements...]) +.. function:: getindex(collection, key...) - :: - - 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, ...)``. .. function:: cell(dims) - :: - - cell(dims) - Construct an uninitialized cell array (heterogeneous array). -.. function:: zeros(type, dims) +.. function:: zeros(A) - :: - - zeros(A) - Create an array of all zeros with the same element type and shape as A. .. function:: zeros(A) - :: - - zeros(A) - Create an array of all zeros with the same element type and shape as A. -.. function:: ones(type, dims) +.. function:: ones(A) - :: - - ones(A) - Create an array of all ones with the same element type and shape as A. .. function:: ones(A) - :: - - ones(A) - Create an array of all ones with the same element type and shape as A. .. function:: trues(dims) - :: - - trues(dims) - Create a ``BitArray`` with all values set to true .. function:: falses(dims) - :: - - falses(dims) - Create a ``BitArray`` with all values set to false .. function:: fill(x, dims) - :: - - fill(x, dims) - Create an array filled with the value ``x``. For example, element initialized to 1.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 evaluating ``Foo()`` once. .. function:: fill!(A, x) - :: - - fill!(A, x) - Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating .. function:: reshape(A, dims) - :: - - reshape(A, dims) - Create an array with the same data as the given array, but with different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. .. function:: similar(array, element_type, dims) - :: - - similar(array, element_type, dims) - Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ranges), this function returns a standard ``Array`` to allow operating on elements. .. function:: reinterpret(type, A) - :: - - reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. -.. function:: eye(n) +.. function:: eye(A) - :: - - eye(A) - Constructs an identity matrix of the same dimensions and type as -.. function:: eye(m, n) +.. function:: eye(A) - :: - - eye(A) - Constructs an identity matrix of the same dimensions and type as .. function:: eye(A) - :: - - eye(A) - Constructs an identity matrix of the same dimensions and type as .. function:: linspace(start, stop, n=100) - :: - - linspace(start, stop, n=100) - Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. .. function:: logspace(start, stop, n=50) - :: - - logspace(start, stop, n=50) - Construct a vector of ``n`` logarithmically spaced numbers from @@ -311,859 +187,483 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) - :: - - broadcast(f, As...) - Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results .. function:: broadcast!(f, dest, As...) - :: - - broadcast!(f, dest, As...) - Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. Note that ``dest`` is only used to store the result, and does not supply arguments to ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform .. function:: bitbroadcast(f, As...) - :: - - bitbroadcast(f, As...) - Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. .. function:: broadcast_function(f) - :: - - broadcast_function(f) - Returns a function ``broadcast_f`` such that useful in the form ``const broadcast_f = broadcast_function(f)``. .. function:: broadcast!_function(f) - :: - - broadcast!_function(f) - Like ``broadcast_function``, but for ``broadcast!``. Indexing, Assignment, and Concatenation --------------------------------------- -.. function:: getindex(A, inds...) +.. function:: getindex(collection, key...) - :: - - 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, ...)``. .. function:: sub(A, inds...) - :: - - sub(A, inds...) - Like ``getindex()``, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling computes the indices to the parent array on the fly without checking bounds. .. function:: parent(A) - :: - - parent(A) - Returns the ``parent array`` of an array view type (e.g., SubArray), or the array itself if it is not a view .. function:: parentindexes(A) - :: - - parentindexes(A) - From an array view ``A``, returns the corresponding indexes in the parent .. function:: slicedim(A, d, i) - :: - - slicedim(A, d, i) - Return all the data of ``A`` where the index for dimension ``d`` equals ``i``. Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``. .. function:: slice(A, inds...) - :: - - slice(A, inds...) - Returns a view of array ``A`` with the given indices like -.. function:: setindex!(A, X, inds...) +.. function:: setindex!(collection, value, key...) - :: - - 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, ...)``. .. function:: broadcast_getindex(A, inds...) - :: - - broadcast_getindex(A, inds...) - Broadcasts the ``inds`` arrays to a common size like ``broadcast``, and returns an array of the results ``A[ks...]``, where ``ks`` goes over the positions in the broadcast. .. function:: broadcast_setindex!(A, X, inds...) - :: - - broadcast_setindex!(A, X, inds...) - Broadcasts the ``X`` and ``inds`` arrays to a common size and stores the value from each position in ``X`` at the indices given by the same positions in ``inds``. .. function:: cat(dims, A...) - :: - - cat(dims, A...) - Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. .. function:: vcat(A...) - :: - - vcat(A...) - Concatenate along dimension 1 .. function:: hcat(A...) - :: - - hcat(A...) - Concatenate along dimension 2 .. function:: hvcat(rows::Tuple{Vararg{Int}}, values...) - :: - - 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. For example, If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. .. function:: flipdim(A, d) - :: - - flipdim(A, d) - Reverse ``A`` in dimension ``d``. -.. function:: circshift(A,shifts) +.. function:: circshift(A, shifts) - :: - - circshift(A, shifts) - Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. -.. function:: find(A) +.. function:: find(f, A) - :: - - find(f, A) - Return a vector of the linear indexes of ``A`` where ``f`` returns true. -.. function:: find(f,A) +.. function:: find(f, A) - :: - - find(f, A) - Return a vector of the linear indexes of ``A`` where ``f`` returns true. .. function:: findn(A) - :: - - findn(A) - Return a vector of indexes for each dimension giving the locations of the non-zeros in ``A`` (determined by ``A[i]!=0``). .. function:: findnz(A) - :: - - findnz(A) - Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and column indexes of the non-zero values in matrix ``A``, and ``V`` is a vector of the non-zero values. -.. function:: findfirst(A) +.. function:: findfirst(predicate, A) - :: - - findfirst(predicate, A) - Return the index of the first element of ``A`` for which -.. function:: findfirst(A,v) +.. function:: findfirst(predicate, A) - :: - - findfirst(predicate, A) - Return the index of the first element of ``A`` for which .. function:: findfirst(predicate, A) - :: - - findfirst(predicate, A) - Return the index of the first element of ``A`` for which -.. function:: findlast(A) +.. function:: findlast(predicate, A) - :: - - findlast(predicate, A) - Return the index of the last element of ``A`` for which -.. function:: findlast(A, v) +.. function:: findlast(predicate, A) - :: - - findlast(predicate, A) - Return the index of the last element of ``A`` for which .. function:: findlast(predicate, A) - :: - - findlast(predicate, A) - Return the index of the last element of ``A`` for which -.. function:: findnext(A, i) +.. function:: findnext(A, v, i) - :: - - findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` -.. function:: findnext(predicate, A, i) +.. function:: findnext(A, v, i) - :: - - findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` .. function:: findnext(A, v, i) - :: - - findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` -.. function:: findprev(A, i) +.. function:: findprev(A, v, i) - :: - - findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to -.. function:: findprev(predicate, A, i) +.. function:: findprev(A, v, i) - :: - - findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to .. function:: findprev(A, v, i) - :: - - findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to .. function:: permutedims(A, perm) - :: - - permutedims(A, perm) - Permute the dimensions of array ``A``. ``perm`` is a vector specifying a permutation of length ``ndims(A)``. This is a generalization of transpose for multi-dimensional arrays. Transpose is equivalent to ``permutedims(A, [2,1])``. .. function:: ipermutedims(A, perm) - :: - - ipermutedims(A, perm) - Like ``permutedims()``, except the inverse of the given permutation is applied. .. function:: permutedims!(dest, src, perm) - :: - - permutedims!(dest, src, perm) - Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. .. function:: squeeze(A, dims) - :: - - squeeze(A, dims) - Remove the dimensions specified by ``dims`` from array ``A``. Elements of ``dims`` must be unique and within the range .. function:: vec(Array) -> Vector - :: - - vec(Array) -> Vector - Vectorize an array using column-major convention. .. function:: promote_shape(s1, s2) - :: - - promote_shape(s1, s2) - Check two array shapes for compatibility, allowing trailing singleton dimensions, and return whichever shape has more dimensions. .. function:: checkbounds(array, indexes...) - :: - - checkbounds(array, indexes...) - Throw an error if the specified indexes are not in bounds for the given array. .. function:: randsubseq(A, p) -> Vector - :: - - randsubseq(A, p) -> Vector - Return a vector consisting of a random subsequence of the given array ``A``, where each element of ``A`` is included (in order) with independent probability ``p``. (Complexity is linear in small and ``A`` is large.) Technically, this process is known as .. function:: randsubseq!(S, A, p) - :: - - randsubseq!(S, A, p) - Like ``randsubseq``, but the results are stored in ``S`` (which is resized as needed). Array functions --------------- -.. function:: cumprod(A, [dim]) +.. function:: cumprod(A[, dim]) - :: - - cumprod(A[, dim]) - Cumulative product along a dimension ``dim`` (defaults to 1). See also ``cumprod!()`` to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). -.. function:: cumprod!(B, A, [dim]) +.. function:: cumprod!(B, A[, dim]) - :: - - cumprod!(B, A[, dim]) - Cumulative product of ``A`` along a dimension, storing the result in ``B``. The dimension defaults to 1. -.. function:: cumsum(A, [dim]) +.. function:: cumsum(A[, dim]) - :: - - cumsum(A[, dim]) - Cumulative sum along a dimension ``dim`` (defaults to 1). See also performance and to control the precision of the output (e.g. to avoid overflow). -.. function:: cumsum!(B, A, [dim]) +.. function:: cumsum!(B, A[, dim]) - :: - - cumsum!(B, A[, dim]) - Cumulative sum of ``A`` along a dimension, storing the result in -.. function:: cumsum_kbn(A, [dim]) +.. function:: cumsum_kbn(A[, dim]) - :: - - cumsum_kbn(A[, dim]) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1. -.. function:: cummin(A, [dim]) +.. function:: cummin(A[, dim]) - :: - - cummin(A[, dim]) - Cumulative minimum along a dimension. The dimension defaults to 1. -.. function:: cummax(A, [dim]) +.. function:: cummax(A[, dim]) - :: - - cummax(A[, dim]) - Cumulative maximum along a dimension. The dimension defaults to 1. -.. function:: diff(A, [dim]) +.. function:: diff(A[, dim]) - :: - - diff(A[, dim]) - Finite difference operator of matrix or vector. -.. function:: gradient(F, [h]) +.. function:: gradient(F[, h]) - :: - - gradient(F[, h]) - Compute differences along vector ``F``, using ``h`` as the spacing between points. The default spacing is one. -.. function:: rot180(A) +.. function:: rot180(A, k) - :: - - rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. .. function:: rot180(A, k) - :: - - rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. -.. function:: rotl90(A) +.. function:: rotl90(A, k) - :: - - rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. .. function:: rotl90(A, k) - :: - - rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. -.. function:: rotr90(A) +.. function:: rotr90(A, k) - :: - - rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. .. function:: rotr90(A, k) - :: - - rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. .. function:: reducedim(f, A, dims[, initial]) - :: - - reducedim(f, A, dims[, initial]) - Reduce 2-argument function ``f`` along dimensions of ``A``. The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for ``reduce``. .. function:: mapreducedim(f, op, A, dims[, initial]) - :: - - mapreducedim(f, op, A, dims[, initial]) - Evaluates to the same as *reducedim(op, map(f, A), dims, f(initial))*, but is generally faster because the intermediate array is avoided. .. function:: mapslices(f, A, dims) - :: - - mapslices(f, A, dims) - Transform the given dimensions of array ``A`` using function ``f``. where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if .. function:: sum_kbn(A) - :: - - sum_kbn(A) - Returns the sum of all array elements, using the Kahan-Babuska- Neumaier compensated summation algorithm for additional accuracy. .. function:: cartesianmap(f, dims) - :: - - cartesianmap(f, dims) - Given a ``dims`` tuple of integers ``(m, n, ...)``, call ``f`` on all combinations of integers in the ranges ``1:m``, ``1:n``, etc. Combinatorics ------------- -.. function:: nthperm(v, k) +.. function:: nthperm(p) - :: - - nthperm(p) - Return the ``k`` that generated permutation ``p``. Note that .. function:: nthperm(p) - :: - - nthperm(p) - Return the ``k`` that generated permutation ``p``. Note that .. function:: nthperm!(v, k) - :: - - nthperm!(v, k) - In-place version of ``nthperm()``. -.. function:: randperm([rng,] n) +.. function:: randperm([rng], n) - :: - - randperm([rng], n) - Construct a random permutation of length ``n``. The optional Numbers*. .. function:: invperm(v) - :: - - invperm(v) - Return the inverse permutation of v. .. function:: isperm(v) -> Bool - :: - - isperm(v) -> Bool - Returns true if v is a valid permutation. .. function:: permute!(v, p) - :: - - permute!(v, p) - Permute vector ``v`` in-place, according to permutation ``p``. No checking is done to verify that ``p`` is a permutation. To return a new permutation, use ``v[p]``. Note that this is generally faster than ``permute!(v,p)`` for large vectors. .. function:: ipermute!(v, p) - :: - - ipermute!(v, p) - Like permute!, but the inverse of the given permutation is applied. -.. function:: randcycle([rng,] n) +.. function:: randcycle([rng], n) - :: - - randcycle([rng], n) - Construct a random cyclic permutation of length ``n``. The optional Numbers*. -.. function:: shuffle([rng,] v) +.. function:: shuffle([rng], v) - :: - - shuffle([rng], v) - Return a randomly permuted copy of ``v``. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. -.. function:: shuffle!([rng,] v) +.. function:: shuffle!([rng], v) - :: - - shuffle!([rng], v) - In-place version of ``shuffle()``. -.. function:: reverse(v [, start=1 [, stop=length(v) ]] ) +.. function:: reverse(v[, start=1[, stop=length(v)]]) - :: - - reverse(v[, start=1[, stop=length(v)]]) - Return a copy of ``v`` reversed from start to stop. .. function:: reverseind(v, i) - :: - - reverseind(v, i) - Given an index ``i`` in ``reverse(v)``, return the corresponding index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``. string.) -.. function:: reverse!(v [, start=1 [, stop=length(v) ]]) -> v +.. function:: reverse!(v[, start=1[, stop=length(v)]]) -> v - :: - - reverse!(v[, start=1[, stop=length(v)]]) -> v - In-place version of ``reverse()``. .. function:: combinations(array, n) - :: - - combinations(array, n) - Generate all combinations of ``n`` elements from an indexable object. Because the number of combinations can be very large, this function returns an iterator object. Use combinations. .. function:: permutations(array) - :: - - permutations(array) - Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use ``collect(permutations(array))`` to get an array of all permutations. -.. function:: partitions(n) +.. function:: partitions(array, m) - :: - - partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. -.. function:: partitions(n, m) +.. function:: partitions(array, m) - :: - - partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. -.. function:: partitions(array) +.. function:: partitions(array, m) - :: - - partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. .. function:: partitions(array, m) - :: - - partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. BitArrays --------- -.. function:: bitpack(A::AbstractArray{T,N}) -> BitArray +.. function:: bitpack(A::AbstractArray{T, N}) -> BitArray - :: - - bitpack(A::AbstractArray{T, N}) -> BitArray - Converts a numeric array to a packed boolean array .. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} - :: - - bitunpack(B::BitArray{N}) -> Array{Bool,N} - Converts a packed boolean array to an array of booleans .. function:: flipbits!(B::BitArray{N}) -> BitArray{N} - :: - - flipbits!(B::BitArray{N}) -> BitArray{N} - Performs a bitwise not operation on B. See *~ operator*. -.. function:: rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - :: - - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - :: - - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} - :: - - rol(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation. -.. function:: ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - :: - - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - :: - - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} - :: - - ror(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation. @@ -1174,183 +674,103 @@ Sparse Matrices Sparse matrices support much of the same set of operations as dense matrices. The following functions are specific to sparse matrices. -.. function:: sparse(I,J,V,[m,n,combine]) +.. function:: sparse(A) - :: - - sparse(A) - Convert an AbstractMatrix ``A`` into a sparse matrix. -.. function:: sparsevec(I, V, [m, combine]) +.. function:: sparsevec(A) - :: - - sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. -.. function:: sparsevec(D::Dict, [m]) +.. function:: sparsevec(A) - :: - - sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. .. function:: issparse(S) - :: - - issparse(S) - Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. .. function:: sparse(A) - :: - - sparse(A) - Convert an AbstractMatrix ``A`` into a sparse matrix. .. function:: sparsevec(A) - :: - - sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. -.. function:: full(S) +.. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - :: - - full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. .. function:: nnz(A) - :: - - nnz(A) - Returns the number of stored (filled) elements in a sparse matrix. -.. function:: spzeros(m,n) +.. function:: spzeros(m, n) - :: - - spzeros(m, n) - Create a sparse matrix of size ``m x n``. This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. .. function:: spones(S) - :: - - spones(S) - Create a sparse matrix with the same structure as that of ``S``, but with every nonzero element having the value ``1.0``. -.. function:: speye(type,m[,n]) +.. function:: speye(type, m[, n]) - :: - - speye(type, m[, n]) - Create a sparse identity matrix of specified type of size ``m x m``. In case ``n`` is supplied, create a sparse identity matrix of size ``m x n``. .. function:: spdiagm(B, d[, m, n]) - :: - - spdiagm(B, d[, m, n]) - Construct a sparse diagonal matrix. ``B`` is a tuple of vectors containing the diagonals and ``d`` is a tuple containing the positions of the diagonals. In the case the input contains only one diagonaly, ``B`` can be a vector (instead of a tuple) and ``d`` can be the diagonal position (instead of a tuple), defaulting to 0 resulting sparse matrix. -.. function:: sprand([rng,] m,n,p [,rfn]) +.. function:: sprand([rng], m, n, p[, rfn]) - :: - - sprand([rng], m, n, p[, rfn]) - Create a random ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by by ``rfn``. The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. -.. function:: sprandn(m,n,p) +.. function:: sprandn(m, n, p) - :: - - sprandn(m, n, p) - Create a random ``m`` by ``n`` sparse matrix with the specified nonzero values are sampled from the normal distribution. -.. function:: sprandbool(m,n,p) +.. function:: sprandbool(m, n, p) - :: - - sprandbool(m, n, p) - Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being .. function:: etree(A[, post]) - :: - - etree(A[, post]) - Compute the elimination tree of a symmetric sparse matrix ``A`` from ``triu(A)`` and, optionally, its post-ordering permutation. .. function:: symperm(A, p) - :: - - symperm(A, p) - Return the symmetric permutation of A, which is ``A[p,p]``. A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. .. function:: nonzeros(A) - :: - - nonzeros(A) - Return a vector of the structural nonzero values in sparse matrix matrix. The returned vector points directly to the internal nonzero storage of ``A``, and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``. .. function:: rowvals(A) - :: - - rowvals(A) - Return a vector of the row indices of ``A``, and any modifications to the returned vector will mutate ``A`` as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See ``nonzeros(A)`` and ``nzrange(A, col)``. .. function:: nzrange(A, col) - :: - - nzrange(A, col) - Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with ``nonzeros(A)`` and matrix diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 743019e3bf5ed..80546bcec5d31 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -22,163 +22,91 @@ Getting Around .. function:: exit([code]) - :: - - exit([code]) - Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. .. function:: quit() - :: - - quit() - Quit the program indicating that the processes completed successfully. This function calls ``exit(0)`` (see ``exit()``). .. function:: atexit(f) - :: - - atexit(f) - Register a zero-argument function to be called at exit. .. function:: atreplinit(f) - :: - - atreplinit(f) - Register a one-argument function to be called before the REPL interface is initialized in interactive sessions; this is useful to customize the interface. The argument of ``f`` is the REPL object. This function should be called from within the ``.juliarc.jl`` initialization file. .. function:: isinteractive() -> Bool - :: - - isinteractive() -> Bool - Determine whether Julia is running an interactive session. .. function:: whos([Module,] [pattern::Regex]) - :: - - whos([Module,] [pattern::Regex]) - Print information about exported global variables in a module, optionally restricted to those matching ``pattern``. -.. function:: edit(file::AbstractString, [line]) +.. function:: edit(function[, types]) - :: - - edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. -.. function:: edit(function, [types]) +.. function:: edit(function[, types]) - :: - - edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. -.. function:: @edit +.. function:: @edit() - :: - - @edit() - Evaluates the arguments to the function call, determines their types, and calls the ``edit`` function on the resulting expression -.. function:: less(file::AbstractString, [line]) +.. function:: less(function[, types]) - :: - - less(function[, types]) - Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. -.. function:: less(function, [types]) +.. function:: less(function[, types]) - :: - - less(function[, types]) - Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. -.. function:: @less +.. function:: @less() - :: - - @less() - Evaluates the arguments to the function call, determines their types, and calls the ``less`` function on the resulting expression -.. function:: clipboard(x) +.. function:: clipboard() -> AbstractString - :: - - clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard .. function:: clipboard() -> AbstractString - :: - - clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard .. function:: require(file::AbstractString...) - :: - - require(file::AbstractString...) - Load source files once, in the context of the ``Main`` module, on every active node, searching standard locations for files. current ``include`` path but does not use it to search for files library code, and is implicitly called by ``using`` to load packages. When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``, then tries paths in the global array ``LOAD_PATH``. .. function:: reload(file::AbstractString) - :: - - reload(file::AbstractString) - Like ``require``, except forces loading of files regardless of whether they have been loaded before. Typically used when interactively developing libraries. -.. function:: include(path::AbstractString) +.. function:: include("file.jl") - :: - - include("file.jl") - Evaluate the contents of a source file in the current context. During including, a task-local include path is set to the directory containing the file. Nested calls to ``include`` will search relative to that path. All paths refer to files on node 1 when running in parallel, and files will be fetched from node 1. This function is typically used to load source interactively, or to combine files in packages that are broken into multiple source files. .. function:: include_string(code::AbstractString) - :: - - include_string(code::AbstractString) - Like ``include``, except reads code from the given string rather than from a file. Since there is no file path involved, no path processing or fetching from node 1 is done. @@ -190,75 +118,43 @@ Getting Around Search documentation for functions related to ``string``. -.. function:: which(f, types) +.. function:: which(symbol) - :: - - which(symbol) - Return the module in which the binding for the variable referenced by ``symbol`` was created. .. function:: which(symbol) - :: - - which(symbol) - Return the module in which the binding for the variable referenced by ``symbol`` was created. -.. function:: @which +.. function:: @which() - :: - - @which() - Applied to a function call, it evaluates the arguments to the specified function call, and returns the ``Method`` object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the ``which`` function. -.. function:: methods(f, [types]) +.. function:: methods(f[, types]) - :: - - methods(f[, types]) - Returns the method table for ``f``. If ``types`` is specified, returns an array of methods whose types match. .. function:: methodswith(typ[, module or function][, showparents]) - :: - - methodswith(typ[, module or function][, showparents]) - Return an array of methods with an argument of type ``typ``. If optional ``showparents`` is ``true``, also return arguments with a parent type of ``typ``, excluding type ``Any``. The optional second argument restricts the search to a particular module or function. -.. function:: @show +.. function:: @show() - :: - - @show() - Show an expression and result, returning the result .. function:: versioninfo([verbose::Bool]) - :: - - versioninfo([verbose::Bool]) - Print information about the version of Julia in use. If the as well. .. function:: workspace() - :: - - workspace() - Replace the top-level module (``Main``) with a new one, providing a clean workspace. The previous ``Main`` module is made available as statement such as ``using LastMain.Package``. This function should only be used interactively. @@ -270,201 +166,113 @@ Getting Around All Objects ----------- -.. function:: is(x, y) -> Bool +.. function:: ===(x, y) - :: - - ===(x, y) - See the ``is()`` operator .. function:: isa(x, type) -> Bool - :: - - isa(x, type) -> Bool - Determine whether ``x`` is of the given ``type``. .. function:: isequal(x, y) - :: - - isequal(x, y) - Similar to ``==``, except treats all floating-point ``NaN`` values as equal to each other, and treats ``-0.0`` as unequal to ``0.0``. The default implementation of ``isequal`` calls ``==``, so if you have a type that doesn't have these floating-point subtleties then you probably only need to define ``==``. hash(y)``. This typically means that if you define your own `==`` function then you must define a corresponding ``hash`` (and vice versa). Collections typically implement ``isequal`` by calling ``isequal`` recursively on all contents. Scalar types generally do not need to implement ``isequal`` separate from ``==``, unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on ``isnan``, ``signbit``, and ``==``). .. function:: isless(x, y) - :: - - isless(x, y) - Test whether ``x`` is less than ``y``, according to a canonical total order. Values that are normally unordered, such as ``NaN``, are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``. Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as .. function:: ifelse(condition::Bool, x, y) - :: - - ifelse(condition::Bool, x, y) - Return ``x`` if ``condition`` is true, otherwise return ``y``. This differs from ``?`` or ``if`` in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using in generated code and provide higher performance in tight loops. .. function:: lexcmp(x, y) - :: - - lexcmp(x, y) - Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than lexicographically comparable types, and ``lexless`` will call .. function:: lexless(x, y) - :: - - lexless(x, y) - Determine whether ``x`` is lexicographically less than ``y``. .. function:: typeof(x) - :: - - typeof(x) - Get the concrete type of ``x``. .. function:: tuple(xs...) - :: - - tuple(xs...) - Construct a tuple of the given objects. .. function:: ntuple(f::Function, n) - :: - - ntuple(f::Function, n) - Create a tuple of length ``n``, computing each element as ``f(i)``, where ``i`` is the index of the element. .. function:: object_id(x) - :: - - object_id(x) - Get a unique integer id for ``x``. ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``. .. function:: hash(x[, h]) - :: - - hash(x[, h]) - Compute an integer hash code such that ``isequal(x,y)`` implies code to be mixed with the result. New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``) to guarantee the property mentioned above. .. function:: finalizer(x, function) - :: - - finalizer(x, function) - Register a function ``f(x)`` to be called when there are no program-accessible references to ``x``. The behavior of this function is unpredictable if ``x`` is of a bits type. .. function:: finalize(x) - :: - - finalize(x) - Immediately run finalizers registered for object ``x``. .. function:: copy(x) - :: - - copy(x) - Create a shallow copy of ``x``: the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. .. function:: deepcopy(x) - :: - - deepcopy(x) - Create a deep copy of ``x``: everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling *deepcopy* on an object should generally have the same effect as serializing and then deserializing it. As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``, and the ``dict`` variable should be updated as appropriate before returning. -.. function:: isdefined([object,] index | symbol) +.. function:: isdefined([object], index | symbol) - :: - - isdefined([object], index | symbol) - Tests whether an assignable location is defined. The arguments can be an array and index, a composite object and field name (as a symbol), or a module and a symbol. With a single symbol argument, tests whether a global variable with that name is defined in .. function:: convert(T, x) - :: - - convert(T, x) - Convert ``x`` to a value of type ``T``. If ``T`` is an ``Integer`` type, an ``InexactError`` will be raised if ``x`` is not representable by ``T``, for example if ``x`` is not integer-valued, or is outside the range supported by ``T``. If ``T`` is a ``FloatingPoint`` or ``Rational`` type, then it will return the closest value to ``x`` representable by ``T``. .. function:: promote(xs...) - :: - - promote(xs...) - Convert all arguments to their common promotion type (if any), and return them all (as a tuple). .. function:: oftype(x, y) - :: - - oftype(x, y) - Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``). .. function:: widen(type | x) - :: - - widen(type | x) - If the argument is a type, return a ``larger`` type (for numeric types, this will be a type with at least as much range and precision as the argument, and usually more). Otherwise the argument ``x`` is converted to ``widen(typeof(x))``. .. function:: identity(x) - :: - - identity(x) - The identity function. Returns its argument. @@ -473,208 +281,116 @@ Types .. function:: super(T::DataType) - :: - - super(T::DataType) - Return the supertype of DataType T -.. function:: issubtype(type1, type2) +.. function:: <:(T1, T2) - :: - - <:(T1, T2) - Subtype operator, equivalent to ``issubtype(T1,T2)``. .. function:: <:(T1, T2) - :: - - <:(T1, T2) - Subtype operator, equivalent to ``issubtype(T1,T2)``. .. function:: subtypes(T::DataType) - :: - - subtypes(T::DataType) - Return a list of immediate subtypes of DataType T. Note that all currently loaded subtypes are included, including those not visible in the current module. .. function:: typemin(type) - :: - - typemin(type) - The lowest value representable by the given (real) numeric type. .. function:: typemax(type) - :: - - typemax(type) - The highest value representable by the given (real) numeric type. .. function:: realmin(type) - :: - - realmin(type) - The smallest in absolute value non-subnormal value representable by the given floating-point type .. function:: realmax(type) - :: - - realmax(type) - The highest finite value representable by the given floating-point type .. function:: maxintfloat(type) - :: - - maxintfloat(type) - The largest integer losslessly representable by the given floating- point type -.. function:: sizeof(type) +.. function:: sizeof(s::AbstractString) - :: - - sizeof(s::AbstractString) - The number of bytes in string ``s``. -.. function:: eps([type]) +.. function:: eps(::DateTime) -> Millisecond - :: - - eps(::DateTime) -> Millisecond - Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. -.. function:: eps(x) +.. function:: eps(::DateTime) -> Millisecond - :: - - eps(::DateTime) -> Millisecond - Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. .. function:: promote_type(type1, type2) - :: - - promote_type(type1, type2) - Determine a type big enough to hold values of each argument type without loss, whenever possible. In some cases, where no type exists to which both types can be promoted losslessly, some loss is tolerated; for example, ``promote_type(Int64,Float64)`` returns represented exactly as ``Float64`` values. .. function:: promote_rule(type1, type2) - :: - - promote_rule(type1, type2) - Specifies what type should be used by ``promote`` when given values of types ``type1`` and ``type2``. This function should not be called directly, but should have definitions added to it for new types as appropriate. .. function:: getfield(value, name::Symbol) - :: - - getfield(value, name::Symbol) - Extract a named field from a value of composite type. The syntax .. function:: setfield!(value, name::Symbol, x) - :: - - setfield!(value, name::Symbol, x) - Assign ``x`` to a named field in ``value`` of composite type. The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``, and the syntax .. function:: fieldoffsets(type) - :: - - fieldoffsets(type) - The byte offset of each field of a type relative to the data start. For example, we could use it in the following manner to summarize information about a struct type: .. function:: fieldtype(type, name::Symbol | index::Int) - :: - - fieldtype(type, name::Symbol | index::Int) - Determine the declared type of a field (specified by name or index) in a composite type. .. function:: isimmutable(v) - :: - - isimmutable(v) - True if value ``v`` is immutable. See *Immutable Composite Types* for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of .. function:: isbits(T) - :: - - isbits(T) - True if ``T`` is a ``plain data`` type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as ``UInt8``, ``Float64``, and .. function:: isleaftype(T) - :: - - isleaftype(T) - Determine whether ``T`` is a concrete type that can have instances, meaning its only subtypes are itself and ``None`` (but ``T`` itself is not ``None``). .. function:: typejoin(T, S) - :: - - typejoin(T, S) - Compute a type that contains both ``T`` and ``S``. .. function:: typeintersect(T, S) - :: - - typeintersect(T, S) - Compute a type that contains the intersection of ``T`` and ``S``. Usually this will be the smallest such type or one close to it. @@ -702,10 +418,6 @@ Types .. function:: instances(T::Type) - :: - - instances(T::Type) - Return a collection of all instances of the given type, if applicable. Mostly used for enumerated types (see ``@enum``). @@ -714,46 +426,26 @@ Generic Functions .. function:: method_exists(f, Tuple type) -> Bool - :: - - method_exists(f, Tuple type) -> Bool - Determine whether the given generic function has a method matching the given ``Tuple`` of argument types. .. function:: applicable(f, args...) -> Bool - :: - - applicable(f, args...) -> Bool - Determine whether the given generic function has a method applicable to the given arguments. .. function:: invoke(f, (types...), args...) - :: - - invoke(f, (types...), args...) - Invoke a method for the given generic function matching the specified types (as a tuple), on the specified arguments. The arguments must be compatible with the specified types. This allows invoking a method other than the most specific matching method, which is useful when the behavior of a more general definition is explicitly needed (often as part of the implementation of a more specific method of the same function). .. function:: |>(x, f) - :: - - |>(x, f) - Applies a function to the preceding argument. This allows for easy function chaining. .. function:: call(x, args...) - :: - - call(x, args...) - If ``x`` is not a ``Function``, then ``x(args...)`` is equivalent to ``call(x, args...)``. This means that function-like behavior can be added to any type by defining new ``call`` methods. @@ -762,73 +454,41 @@ Syntax .. function:: eval([m::Module], expr::Expr) - :: - - eval([m::Module], expr::Expr) - Evaluate an expression in the given module and return the result. Every module (except those defined with ``baremodule``) has its own 1-argument definition of ``eval``, which evaluates expressions in that module. -.. function:: @eval +.. function:: @eval() - :: - - @eval() - Evaluate an expression and return the value. .. function:: evalfile(path::AbstractString) - :: - - evalfile(path::AbstractString) - Load the file using ``include``, evaluate all expressions, and return the value of the last one. .. function:: esc(e::ANY) - :: - - esc(e::ANY) - Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the *Macros* section of the Metaprogramming chapter of the manual for more details and examples. .. function:: gensym([tag]) - :: - - gensym([tag]) - Generates a symbol which will not conflict with other variable names. -.. function:: @gensym +.. function:: @gensym() - :: - - @gensym() - Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym(``x``); y = gensym(``y``)``. -.. function:: parse(str, start; greedy=true, raise=true) +.. function:: parse(type, str[, base]) - :: - - parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. -.. function:: parse(str; raise=true) +.. function:: parse(type, str[, base]) - :: - - parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. @@ -837,37 +497,21 @@ Nullables .. function:: Nullable(x) - :: - - Nullable(x) - Wrap value ``x`` in an object of type ``Nullable``, which indicates whether a value is present. ``Nullable(x)`` yields a non-empty wrapper, and ``Nullable{T}()`` yields an empty instance of a wrapper that might contain a value of type ``T``. -.. function:: get(x) +.. function:: get(f::Function, collection, key) - :: - - 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: -.. function:: get(x, y) +.. function:: get(f::Function, collection, key) - :: - - 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: .. function:: isnull(x) - :: - - isnull(x) - Is the ``Nullable`` object ``x`` null, i.e. missing a value? @@ -876,19 +520,11 @@ System .. function:: run(command) - :: - - run(command) - Run a command object, constructed with backticks. Throws an error if anything goes wrong, including the process exiting with a non- zero status. .. function:: spawn(command) - :: - - spawn(command) - Run a command object asynchronously, returning the resulting @@ -899,55 +535,31 @@ System .. function:: success(command) - :: - - success(command) - Run a command object, constructed with backticks, and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started. .. function:: process_running(p::Process) - :: - - process_running(p::Process) - Determine whether a process is currently running. .. function:: process_exited(p::Process) - :: - - process_exited(p::Process) - Determine whether a process has exited. -.. function:: kill(p::Process, signum=SIGTERM) +.. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - :: - - kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. -.. function:: open(command, mode::AbstractString="r", stdio=DevNull) +.. function:: open(f::function, args...) - :: - - open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. -.. function:: open(f::Function, command, mode::AbstractString="r", stdio=DevNull) +.. function:: open(f::function, args...) - :: - - open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. @@ -961,190 +573,106 @@ System .. function:: readandwrite(command) - :: - - readandwrite(command) - Starts running a command asynchronously, and returns a tuple process, and the process object itself. .. function:: ignorestatus(command) - :: - - ignorestatus(command) - Mark a command object so that running it will not throw an error if the result code is non-zero. .. function:: detach(command) - :: - - detach(command) - Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. .. function:: setenv(command, env; dir=working_dir) - :: - - setenv(command, env; dir=working_dir) - Set environment variables to use when running the given command. of strings of the form ``var=val``, or zero or more replace) the existing environment, create ``env`` by ``copy(ENV)`` and then setting ``env[``var``]=val`` as desired, or use The ``dir`` keyword argument can be used to specify a working directory for the command. .. function:: withenv(f::Function, kv::Pair...) - :: - - withenv(f::Function, kv::Pair...) - - Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``var``=>val`` arguments ``kv``. ``withenv`` is generally used via the be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. + Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``var``=>val` arguments ``kv``. ``withenv`` is generally used via the be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. -.. function:: pipe(from, to, ...) +.. function:: pipe(command; stdin, stdout, stderr, append=false) - :: - - pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. .. function:: pipe(command; stdin, stdout, stderr, append=false) - :: - - pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. .. function:: gethostname() -> AbstractString - :: - - gethostname() -> AbstractString - Get the local machine's host name. .. function:: getipaddr() -> AbstractString - :: - - getipaddr() -> AbstractString - Get the IP address of the local machine, as a string of the form .. function:: getpid() -> Int32 - :: - - getpid() -> Int32 - Get julia's process ID. -.. function:: time() +.. function:: time(t::TmStruct) - :: - - time(t::TmStruct) - Converts a ``TmStruct`` struct to a number of seconds since the epoch. .. function:: time_ns() - :: - - time_ns() - Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. .. function:: tic() - :: - - tic() - Set a timer to be read by the next call to ``toc()`` or ``toq()``. The macro call ``@time expr`` can also be used to time evaluation. .. function:: toc() - :: - - toc() - Print and return the time elapsed since the last ``tic()``. .. function:: toq() - :: - - toq() - Return, but do not print, the time elapsed since the last -.. function:: @time +.. function:: @time() - :: - - @time() - A macro to execute an expression, printing the time it took to execute, the number of allocations, and the total number of bytes its execution caused to be allocated, before returning the value of the expression. -.. function:: @timev +.. function:: @timev() - :: - - @timev() - This is a verbose version of the ``@time`` macro, it first prints the same information as ``@time``, then any non-zero memory allocation counters, and then returns the value of the expression. -.. function:: @timed +.. function:: @timed() - :: - - @timed() - A macro to execute an expression, and return the value of the expression, elapsed time, total bytes allocated, garbage collection time, and an object with various memory allocation counters. -.. function:: @elapsed +.. function:: @elapsed() - :: - - @elapsed() - A macro to evaluate an expression, discarding the resulting value, instead returning the number of seconds it took to execute as a floating-point number. -.. function:: @allocated +.. function:: @allocated() - :: - - @allocated() - A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the ``@time`` macros, which do not try to adjust for the effects of compilation. .. function:: EnvHash() -> EnvHash - :: - - EnvHash() -> EnvHash - A singleton of this type provides a hash table interface to environment variables. @@ -1152,39 +680,23 @@ System Reference to the singleton ``EnvHash``, providing a dictionary interface to system environment variables. -.. function:: @unix +.. function:: @unix() - :: - - @unix() - Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. -.. function:: @osx +.. function:: @osx() - :: - - @osx() - Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. -.. function:: @linux +.. function:: @linux() - :: - - @linux() - Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. -.. function:: @windows +.. function:: @windows() - :: - - @windows() - Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. @@ -1193,55 +705,31 @@ Errors .. function:: error(message::AbstractString) - :: - - error(message::AbstractString) - Raise an ``ErrorException`` with the given message .. function:: throw(e) - :: - - throw(e) - Throw an object as an exception .. function:: rethrow([e]) - :: - - rethrow([e]) - Throw an object without changing the current exception backtrace. The default argument is the current exception (if called within a .. function:: backtrace() - :: - - backtrace() - Get a backtrace object for the current program point. .. function:: catch_backtrace() - :: - - catch_backtrace() - Get the backtrace of the current exception, for use within .. function:: assert(cond) - :: - - assert(cond) - Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. @@ -1251,238 +739,134 @@ Errors .. function:: ArgumentError(msg) - :: - - ArgumentError(msg) - The parameters to a function call do not match a valid signature. .. function:: AssertionError([msg]) - :: - - AssertionError([msg]) - The asserted condition did not evalutate to ``true``. -.. function:: BoundsError([a],[i]) +.. function:: BoundsError([a][, i]) - :: - - BoundsError([a][, i]) - An indexing operation into an array, ``a``, tried to access an out- of-bounds element, ``i``. .. function:: DimensionMismatch([msg]) - :: - - DimensionMismatch([msg]) - The objects called do not have matching dimensionality. .. function:: DivideError() - :: - - DivideError() - Integer division was attempted with a denominator value of 0. .. function:: DomainError() - :: - - DomainError() - The arguments to a function or constructor are outside the valid domain. .. function:: EOFError() - :: - - EOFError() - No more data was available to read from a file or stream. .. function:: ErrorException(msg) - :: - - ErrorException(msg) - Generic error type. The error message, in the *.msg* field, may provide more specific details. .. function:: InexactError() - :: - - InexactError() - Type conversion cannot be done exactly. .. function:: InterruptException() - :: - - InterruptException() - The process was stopped by a terminal interrupt (CTRL+C). .. function:: KeyError(key) - :: - - KeyError(key) - An indexing operation into an ``Associative`` (``Dict``) or ``Set`` like object tried to access or delete a non-existent element. .. function:: LoadError(file::AbstractString, line::Int, error) - :: - - LoadError(file::AbstractString, line::Int, error) - An error occurred while *including*, *requiring*, or *using* a file. The error specifics should be available in the *.error* field. .. function:: MethodError(f, args) - :: - - MethodError(f, args) - A method with the required type signature does not exist in the given generic function. .. function:: NullException() - :: - - NullException() - An attempted access to a ``Nullable`` with no defined value. .. function:: OutOfMemoryError() - :: - - OutOfMemoryError() - An operation allocated too much memory for either the system or the garbage collector to handle properly. .. function:: ReadOnlyMemoryError() - :: - - ReadOnlyMemoryError() - An operation tried to write to memory that is read-only. .. function:: OverflowError() - :: - - OverflowError() - The result of an expression is too large for the specified type and will cause a wraparound. .. function:: ParseError(msg) - :: - - ParseError(msg) - The expression passed to the *parse* function could not be interpreted as a valid Julia expression. .. function:: ProcessExitedException() - :: - - ProcessExitedException() - After a client Julia process has exited, further attempts to reference the dead child will throw this exception. .. function:: StackOverflowError() - :: - - StackOverflowError() - The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. -.. function:: SystemError(prefix::AbstractString, [errnum::Int32]) +.. function:: SystemError(prefix::AbstractString[, errnum::Int32]) - :: - - SystemError(prefix::AbstractString[, errnum::Int32]) - A system call failed with an error code (in the ``errno`` global variable). .. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) - :: - - TypeError(func::Symbol, context::AbstractString, expected::Type, got) - A type assertion failure, or calling an intrinsic function with an incorrect argument type. .. function:: UndefRefError() - :: - - UndefRefError() - The item or field is not defined for the given object. .. function:: UndefVarError(var::Symbol) - :: - - UndefVarError(var::Symbol) - A symbol in the current scope is not defined. Events ------ -.. function:: Timer(callback::Function, delay, repeat=0) +.. function:: Timer(delay, repeat=0) - :: - - Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling .. function:: Timer(delay, repeat=0) - :: - - Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling @@ -1491,118 +875,66 @@ Reflection .. function:: module_name(m::Module) -> Symbol - :: - - module_name(m::Module) -> Symbol - Get the name of a module as a symbol. .. function:: module_parent(m::Module) -> Module - :: - - module_parent(m::Module) -> Module - Get a module's enclosing module. ``Main`` is its own parent. .. function:: current_module() -> Module - :: - - current_module() -> Module - Get the *dynamically* current module, which is the module code is currently being read from. In general, this is not the same as the module containing the call to this function. .. function:: fullname(m::Module) - :: - - fullname(m::Module) - Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and .. function:: names(x::Module[, all=false[, imported=false]]) - :: - - names(x::Module[, all=false[, imported=false]]) - Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. .. function:: nfields(x::DataType) -> Int - :: - - nfields(x::DataType) -> Int - Get the number of fields of a data type. .. function:: fieldnames(x::DataType) - :: - - fieldnames(x::DataType) - Get an array of the fields of a data type. .. function:: isconst([m::Module], s::Symbol) -> Bool - :: - - isconst([m::Module], s::Symbol) -> Bool - Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``. .. function:: isgeneric(f::Function) -> Bool - :: - - isgeneric(f::Function) -> Bool - Determine whether a function is generic. .. function:: function_name(f::Function) -> Symbol - :: - - function_name(f::Function) -> Symbol - Get the name of a generic function as a symbol, or ``:anonymous``. .. function:: function_module(f::Function, types) -> Module - :: - - function_module(f::Function, types) -> Module - Determine the module containing a given definition of a generic function. -.. function:: functionloc(f::Function, types) +.. function:: functionloc(m::Method) - :: - - functionloc(m::Method) - Returns a tuple ``(filename,line)`` giving the location of a method definition. .. function:: functionloc(m::Method) - :: - - functionloc(m::Method) - Returns a tuple ``(filename,line)`` giving the location of a method definition. @@ -1611,136 +943,76 @@ Internals .. function:: gc() - :: - - gc() - Perform garbage collection. This should not generally be used. .. function:: gc_enable(on::Bool) - :: - - gc_enable(on::Bool) - Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Returns previous GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. .. function:: macroexpand(x) - :: - - macroexpand(x) - Takes the expression x and returns an equivalent expression with all macros removed (expanded). .. function:: expand(x) - :: - - expand(x) - Takes the expression x and returns an equivalent expression in lowered form .. function:: code_lowered(f, types) - :: - - code_lowered(f, types) - Returns an array of lowered ASTs for the methods matching the given generic function and type signature. -.. function:: @code_lowered +.. function:: @code_lowered() - :: - - @code_lowered() - Evaluates the arguments to the function call, determines their types, and calls ``code_lowered()`` on the resulting expression .. function:: code_typed(f, types; optimize=true) - :: - - code_typed(f, types; optimize=true) - Returns an array of lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The keyword argument ``optimize`` controls whether additional optimizations, such as inlining, are also applied. -.. function:: @code_typed +.. function:: @code_typed() - :: - - @code_typed() - Evaluates the arguments to the function call, determines their types, and calls ``code_typed()`` on the resulting expression .. function:: code_warntype(f, types) - :: - - code_warntype(f, types) - Displays lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The ASTs are annotated in such a way as to cause ``non-leaf`` types to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability. Not all non-leaf types are particularly problematic for performance, so the results need to be used judiciously. See *@code_warntype* for more information. -.. function:: @code_warntype +.. function:: @code_warntype() - :: - - @code_warntype() - Evaluates the arguments to the function call, determines their types, and calls ``code_warntype()`` on the resulting expression .. function:: code_llvm(f, types) - :: - - code_llvm(f, types) - Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to ``STDOUT``. All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. -.. function:: @code_llvm +.. function:: @code_llvm() - :: - - @code_llvm() - Evaluates the arguments to the function call, determines their types, and calls ``code_llvm()`` on the resulting expression .. function:: code_native(f, types) - :: - - code_native(f, types) - Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. -.. function:: @code_native +.. function:: @code_native() - :: - - @code_native() - Evaluates the arguments to the function call, determines their types, and calls ``code_native()`` on the resulting expression -.. function:: precompile(f,args::Tuple{Vararg{Any}}) +.. function:: precompile(f, args::Tuple{Vararg{Any}}) - :: - - precompile(f, args::Tuple{Vararg{Any}}) - Compile the given function ``f`` for the argument tuple (of types) diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index e2c3e2b0019ce..5b67f29eb50ec 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -6,163 +6,91 @@ .. function:: ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - :: - - ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - Call function in C-exported shared library, specified by AbstractString or :Symbol. Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. Each ``ArgumentValue`` to the ``ccall`` will be converted to the corresponding ``ArgumentType``, by automatic insertion of calls to ArgumentValue))``. (see also the documentation for each of these functions for further details). In most cases, this simply results in a call to `convert(ArgumentType, ArgumentValue)`` -.. function:: cglobal((symbol, library) [, type=Void]) +.. function:: cglobal((symbol, library)[, type=Void]) - :: - - cglobal((symbol, library)[, type=Void]) - Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ``ccall``. Returns a supplied. The values can be read or written by ``unsafe_load`` or .. function:: cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - :: - - cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically. For example: -.. function:: unsafe_convert(T,x) +.. function:: unsafe_convert(T, x) - :: - - unsafe_convert(T, x) - Convert ``x`` to a value of type ``T`` In cases where ``convert`` would need to take a Julia object and turn it into a ``Ptr``, this function should be used to define and perform that conversion. Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. Accordingly, the argument ``x`` to this function should never be an expression, only a variable name or field reference. For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. The ``unsafe`` prefix on this function indicates that using the result of this function after the ``x`` argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time. -.. function:: cconvert(T,x) +.. function:: cconvert(T, x) - :: - - cconvert(T, x) - Convert ``x`` to a value of type ``T``, typically by calling In cases where ``x`` cannot be safely converted to ``T``, unlike from ``T``, which however is suitable for ``unsafe_convert`` to handle. Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``. -.. function:: unsafe_load(p::Ptr{T},i::Integer) +.. function:: unsafe_load(p::Ptr{T}, i::Integer) - :: - - unsafe_load(p::Ptr{T}, i::Integer) - Load a value of type ``T`` from the address of the ith element expression ``p[i-1]``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C. -.. function:: unsafe_store!(p::Ptr{T},x,i::Integer) +.. function:: unsafe_store!(p::Ptr{T}, x, i::Integer) - :: - - unsafe_store!(p::Ptr{T}, x, i::Integer) - Store a value of type ``T`` to the address of the ith element expression ``p[i-1] = x``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. -.. function:: unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) +.. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - :: - - unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - :: - - unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. -.. function:: copy!(dest, src) +.. function:: copy!(dest, do, src, so, N) - :: - - copy!(dest, do, src, so, N) - Copy ``N`` elements from collection ``src`` starting at offset .. function:: copy!(dest, do, src, so, N) - :: - - copy!(dest, do, src, so, N) - Copy ``N`` elements from collection ``src`` starting at offset -.. function:: pointer(array [, index]) +.. function:: pointer(array[, index]) - :: - - pointer(array[, index]) - Get the native address of an array or string element. Be careful to ensure that a julia reference to ``a`` exists as long as this pointer will be used. This function is ``unsafe`` like Calling ``Ref(array[, index])`` is generally preferable to this function. .. function:: pointer_to_array(pointer, dims[, take_ownership::Bool]) - :: - - pointer_to_array(pointer, dims[, take_ownership::Bool]) - Wrap a native pointer as a Julia Array object. The pointer element type determines the array element type. ``own`` optionally specifies whether Julia should take ownership of the memory, calling ``free`` on the pointer when the array is no longer referenced. .. function:: pointer_from_objref(object_instance) - :: - - pointer_from_objref(object_instance) - Get the memory address of a Julia object as a ``Ptr``. The existence of the resulting ``Ptr`` will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that the ``Ptr`` will be used. .. function:: unsafe_pointer_to_objref(p::Ptr) - :: - - unsafe_pointer_to_objref(p::Ptr) - Convert a ``Ptr`` to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined behavior results, hence this function is considered .. function:: disable_sigint(f::Function) - :: - - disable_sigint(f::Function) - Disable Ctrl-C handler during execution of a function, for calling external code that is not interrupt safe. Intended to be called using ``do`` block syntax as follows: .. function:: reenable_sigint(f::Function) - :: - - reenable_sigint(f::Function) - Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of ``disable_sigint``. .. function:: systemerror(sysfunc, iftrue) - :: - - systemerror(sysfunc, iftrue) - Raises a ``SystemError`` for ``errno`` with the descriptive string diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index 8d685ef990d38..a21ab57d193f7 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -26,100 +26,56 @@ The ``state`` object may be anything, and should be chosen appropriately for eac .. function:: start(iter) -> state - :: - - start(iter) -> state - Get initial iteration state for an iterable object .. function:: done(iter, state) -> Bool - :: - - done(iter, state) -> Bool - Test whether we are done iterating .. function:: next(iter, state) -> item, state - :: - - next(iter, state) -> item, state - For a given iterable object and iteration state, return the current item and the next iteration state .. function:: zip(iters...) - :: - - zip(iters...) - For a set of iterable objects, returns an iterable of tuples, where the ``i``th tuple contains the ``i``th component of each input iterable. Note that ``zip()`` is its own inverse: .. function:: enumerate(iter) - :: - - enumerate(iter) - An iterator that yields ``(i, x)`` where ``i`` is an index starting at 1, and ``x`` is the ``i``th value from the given iterator. It's useful when you need not only the values ``x`` over which you are iterating, but also the index ``i`` of the iterations. .. function:: rest(iter, state) - :: - - rest(iter, state) - An iterator that yields the same elements as ``iter``, but starting at the given ``state``. .. function:: countfrom(start=1, step=1) - :: - - countfrom(start=1, step=1) - An iterator that counts forever, starting at ``start`` and incrementing by ``step``. .. function:: take(iter, n) - :: - - take(iter, n) - An iterator that generates at most the first ``n`` elements of .. function:: drop(iter, n) - :: - - drop(iter, n) - An iterator that generates all but the first ``n`` elements of .. function:: cycle(iter) - :: - - cycle(iter) - An iterator that cycles through ``iter`` forever. .. function:: repeated(x[, n::Int]) - :: - - repeated(x[, n::Int]) - An iterator that generates the value ``x`` forever. If ``n`` is specified, generates ``x`` that many times (equivalent to @@ -145,37 +101,21 @@ General Collections .. function:: isempty(collection) -> Bool - :: - - isempty(collection) -> Bool - Determine whether a collection is empty (has no elements). .. function:: empty!(collection) -> collection - :: - - empty!(collection) -> collection - Remove all elements from a ``collection``. -.. function:: length(collection) -> Integer +.. function:: length(s) - :: - - length(s) - The number of characters in string ``s``. .. function:: endof(collection) -> Integer - :: - - endof(collection) -> Integer - Returns the last index of the collection. @@ -197,622 +137,346 @@ Iterable Collections .. function:: in(item, collection) -> Bool - :: - - in(item, collection) -> Bool - Determine whether an item is in the given collection, in the sense that it is ``==`` to one of the values generated by iterating over the collection. Some collections need a slightly different definition; for example ``Set``s check whether the item To test for the presence of a key in a dictionary, use ``haskey()`` or ``k in keys(dict)``. .. function:: eltype(type) - :: - - 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 ``(key,value)`` tuple type. The definition that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types. .. function:: indexin(a, b) - :: - - 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``. .. function:: findin(a, b) - :: - - findin(a, b) - Returns the indices of elements in collection ``a`` that appear in collection ``b`` .. function:: unique(itr[, dim]) - :: - - 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``. -.. function:: reduce(op, v0, itr) +.. function:: reduce(op, itr) - :: - - 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``. .. function:: reduce(op, itr) - :: - - 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``. -.. function:: foldl(op, v0, itr) +.. function:: foldl(op, itr) - :: - - 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 .. function:: foldl(op, itr) - :: - - 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 -.. function:: foldr(op, v0, itr) +.. function:: foldr(op, itr) - :: - - 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 .. function:: foldr(op, itr) - :: - - 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 -.. function:: maximum(itr) +.. function:: maximum(A, dims) - :: - - maximum(A, dims) - Compute the maximum value of an array over the given dimensions. .. function:: maximum(A, dims) - :: - - maximum(A, dims) - Compute the maximum value of an array over the given dimensions. .. function:: maximum!(r, A) - :: - - maximum!(r, A) - Compute the maximum value of ``A`` over the singleton dimensions of -.. function:: minimum(itr) +.. function:: minimum(A, dims) - :: - - minimum(A, dims) - Compute the minimum value of an array over the given dimensions. .. function:: minimum(A, dims) - :: - - minimum(A, dims) - Compute the minimum value of an array over the given dimensions. .. function:: minimum!(r, A) - :: - - minimum!(r, A) - Compute the minimum value of ``A`` over the singleton dimensions of .. function:: extrema(itr) - :: - - extrema(itr) - Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. .. function:: indmax(itr) -> Integer - :: - - indmax(itr) -> Integer - Returns the index of the maximum element in a collection. .. function:: indmin(itr) -> Integer - :: - - indmin(itr) -> Integer - Returns the index of the minimum element in a collection. -.. function:: findmax(itr) -> (x, index) +.. function:: findmax(A, dims) -> (maxval, index) - :: - - findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over the given dimensions. .. function:: findmax(A, dims) -> (maxval, index) - :: - - findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over the given dimensions. -.. function:: findmin(itr) -> (x, index) +.. function:: findmin(A, dims) -> (minval, index) - :: - - findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over the given dimensions. .. function:: findmin(A, dims) -> (minval, index) - :: - - findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over the given dimensions. -.. function:: maxabs(itr) +.. function:: maxabs(A, dims) - :: - - maxabs(A, dims) - Compute the maximum absolute values over given dimensions. .. function:: maxabs(A, dims) - :: - - maxabs(A, dims) - Compute the maximum absolute values over given dimensions. .. function:: maxabs!(r, A) - :: - - maxabs!(r, A) - Compute the maximum absolute values over the singleton dimensions of ``r``, and write values to ``r``. -.. function:: minabs(itr) +.. function:: minabs(A, dims) - :: - - minabs(A, dims) - Compute the minimum absolute values over given dimensions. .. function:: minabs(A, dims) - :: - - minabs(A, dims) - Compute the minimum absolute values over given dimensions. .. function:: minabs!(r, A) - :: - - minabs!(r, A) - Compute the minimum absolute values over the singleton dimensions of ``r``, and write values to ``r``. -.. function:: sum(itr) +.. function:: sum(f, itr) - :: - - sum(f, itr) - Sum the results of calling function ``f`` on each element of -.. function:: sum(A, dims) +.. function:: sum(f, itr) - :: - - sum(f, itr) - Sum the results of calling function ``f`` on each element of .. function:: sum!(r, A) - :: - - sum!(r, A) - Sum elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. .. function:: sum(f, itr) - :: - - sum(f, itr) - Sum the results of calling function ``f`` on each element of -.. function:: sumabs(itr) +.. function:: sumabs(A, dims) - :: - - sumabs(A, dims) - Sum absolute values of elements of an array over the given dimensions. .. function:: sumabs(A, dims) - :: - - sumabs(A, dims) - Sum absolute values of elements of an array over the given dimensions. .. function:: sumabs!(r, A) - :: - - sumabs!(r, A) - Sum absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. -.. function:: sumabs2(itr) +.. function:: sumabs2(A, dims) - :: - - sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given dimensions. .. function:: sumabs2(A, dims) - :: - - sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given dimensions. .. function:: sumabs2!(r, A) - :: - - sumabs2!(r, A) - Sum squared absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. -.. function:: prod(itr) +.. function:: prod(A, dims) - :: - - prod(A, dims) - Multiply elements of an array over the given dimensions. .. function:: prod(A, dims) - :: - - prod(A, dims) - Multiply elements of an array over the given dimensions. .. function:: prod!(r, A) - :: - - prod!(r, A) - Multiply elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. -.. function:: any(itr) -> Bool +.. function:: any(p, itr) -> Bool - :: - - any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of -.. function:: any(A, dims) +.. function:: any(p, itr) -> Bool - :: - - any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of .. function:: any!(r, A) - :: - - any!(r, A) - Test whether any values in ``A`` along the singleton dimensions of -.. function:: all(itr) -> Bool +.. function:: all(p, itr) -> Bool - :: - - all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of -.. function:: all(A, dims) +.. function:: all(p, itr) -> Bool - :: - - all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of .. function:: all!(r, A) - :: - - all!(r, A) - Test whether all values in ``A`` along the singleton dimensions of .. function:: count(p, itr) -> Integer - :: - - count(p, itr) -> Integer - Count the number of elements in ``itr`` for which predicate ``p`` returns true. .. function:: any(p, itr) -> Bool - :: - - any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of .. function:: all(p, itr) -> Bool - :: - - all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of .. function:: map(f, c...) -> collection - :: - - map(f, c...) -> collection - Transform collection ``c`` by applying ``f`` to each element. For multiple collection arguments, apply ``f`` elementwise. -.. function:: map!(function, collection) +.. function:: map!(function, destination, collection...) - :: - - 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. .. function:: map!(function, destination, collection...) - :: - - 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. -.. function:: mapreduce(f, op, v0, itr) +.. function:: mapreduce(f, op, itr) - :: - - mapreduce(f, op, itr) - Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). .. function:: mapreduce(f, op, itr) - :: - - mapreduce(f, op, itr) - Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). -.. function:: mapfoldl(f, op, v0, itr) +.. function:: mapfoldl(f, op, itr) - :: - - mapfoldl(f, op, itr) - Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). .. function:: mapfoldl(f, op, itr) - :: - - mapfoldl(f, op, itr) - Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). -.. function:: mapfoldr(f, op, v0, itr) +.. function:: mapfoldr(f, op, itr) - :: - - mapfoldr(f, op, itr) - Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). .. function:: mapfoldr(f, op, itr) - :: - - mapfoldr(f, op, itr) - Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). .. function:: first(coll) - :: - - first(coll) - Get the first element of an iterable collection. Returns the start point of a ``Range`` even if it is empty. .. function:: last(coll) - :: - - 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. .. function:: step(r) - :: - - step(r) - Get the step size of a ``Range`` object. -.. function:: collect(collection) +.. function:: collect(element_type, collection) - :: - - collect(element_type, collection) - Return an array of type ``Array{element_type,1}`` of all items in a collection. .. function:: collect(element_type, collection) - :: - - collect(element_type, collection) - Return an array of type ``Array{element_type,1}`` of all items in a collection. -.. function:: issubset(a, b) +.. function:: issubset(A, S) -> Bool - :: - - issubset(A, S) -> Bool - True if A is a subset of or equal to S. .. function:: filter(function, collection) - :: - - filter(function, collection) - Return a copy of ``collection``, removing elements for which passed two arguments (key and value). .. function:: filter!(function, collection) - :: - - filter!(function, collection) - Update ``collection``, removing elements for which ``function`` is false. For associative collections, the function is passed two arguments (key and value). @@ -821,19 +485,11 @@ Indexable Collections .. function:: getindex(collection, key...) - :: - - 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, ...)``. .. function:: setindex!(collection, value, key...) - :: - - 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, ...)``. @@ -874,58 +530,34 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: Dict([itr]) - :: - - Dict([itr]) - 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. Alternatively, a sequence of pair arguments may be passed. .. function:: haskey(collection, key) -> Bool - :: - - haskey(collection, key) -> Bool - Determine whether a collection has a mapping for a given key. -.. function:: get(collection, key, default) +.. function:: get(f::Function, collection, key) - :: - - 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: .. function:: get(f::Function, collection, key) - :: - - 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: time() end -.. function:: get!(collection, key, default) +.. function:: get!(f::Function, collection, key) - :: - - 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: .. function:: get!(f::Function, collection, key) - :: - - 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: @@ -934,73 +566,41 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: getkey(collection, key, default) - :: - - getkey(collection, key, default) - Return the key matching argument ``key`` if one exists in .. function:: delete!(collection, key) - :: - - delete!(collection, key) - Delete the mapping for the given key in a collection, and return the collection. -.. function:: pop!(collection, key[, default]) +.. function:: pop!(collection) -> item - :: - - pop!(collection) -> item - Remove the last item in ``collection`` and return it. .. function:: keys(collection) - :: - - keys(collection) - Return an iterator over all keys in a collection. .. function:: values(collection) - :: - - values(collection) - Return an iterator over all values in a collection. .. function:: merge(collection, others...) - :: - - merge(collection, others...) - 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. .. function:: merge!(collection, others...) - :: - - merge!(collection, others...) - Update collection with pairs from the other collections .. function:: sizehint!(s, n) - :: - - sizehint!(s, n) - Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. @@ -1023,136 +623,76 @@ Set-Like Collections .. function:: Set([itr]) - :: - - 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. .. function:: IntSet([itr]) - :: - - IntSet([itr]) - Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use ``Set`` instead. -.. function:: union(s1,s2...) +.. function:: union(s1, s2...) - :: - - union(s1, s2...) - Construct the union of two or more sets. Maintains order with arrays. .. function:: union!(s, iterable) - :: - - union!(s, iterable) - Union each element of ``iterable`` into set ``s`` in-place. -.. function:: intersect(s1,s2...) +.. function:: intersect(s1, s2...) - :: - - intersect(s1, s2...) - Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. -.. function:: setdiff(s1,s2) +.. function:: setdiff(s1, s2) - :: - - setdiff(s1, s2) - Construct the set of elements in ``s1`` but not ``s2``. Maintains order with arrays. Note that both arguments must be collections, and both will be iterated over. In particular, .. function:: setdiff!(s, iterable) - :: - - setdiff!(s, iterable) - Remove each element of ``iterable`` from set ``s`` in-place. -.. function:: symdiff(s1,s2...) +.. function:: symdiff(s1, s2...) - :: - - symdiff(s1, s2...) - Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. -.. function:: symdiff!(s, n) +.. function:: symdiff!(s1, s2) - :: - - symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. -.. function:: symdiff!(s, itr) +.. function:: symdiff!(s1, s2) - :: - - symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. .. function:: symdiff!(s1, s2) - :: - - symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. .. function:: complement(s) - :: - - complement(s) - Returns the set-complement of ``IntSet`` ``s``. .. function:: complement!(s) - :: - - complement!(s) - Mutates ``IntSet`` ``s`` into its set-complement. .. function:: intersect!(s1, s2) - :: - - intersect!(s1, s2) - Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of .. function:: issubset(A, S) -> Bool - :: - - issubset(A, S) -> Bool - True if A is a subset of or equal to S. @@ -1170,109 +710,61 @@ Dequeues .. function:: push!(collection, items...) -> collection - :: - - push!(collection, items...) -> collection - Insert one or more ``items`` at the end of ``collection``. Use ``append!()`` to add all the elements of another collection to to ``append!([1, 2, 3], [4, 5, 6])``. .. function:: pop!(collection) -> item - :: - - pop!(collection) -> item - Remove the last item in ``collection`` and return it. .. function:: unshift!(collection, items...) -> collection - :: - - unshift!(collection, items...) -> collection - Insert one or more ``items`` at the beginning of ``collection``. .. function:: shift!(collection) -> item - :: - - shift!(collection) -> item - Remove the first ``item`` from ``collection``. .. function:: insert!(collection, index, item) - :: - - insert!(collection, index, item) - Insert an ``item`` into ``collection`` at the given ``index``. -.. function:: deleteat!(collection, index) +.. function:: deleteat!(collection, itr) - :: - - deleteat!(collection, itr) - Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. .. function:: deleteat!(collection, itr) - :: - - deleteat!(collection, itr) - Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. -.. function:: splice!(collection, index, [replacement]) -> item +.. function:: splice!(collection, range[, replacement]) -> items - :: - - splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. -.. function:: splice!(collection, range, [replacement]) -> items +.. function:: splice!(collection, range[, replacement]) -> items - :: - - splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. .. function:: resize!(collection, n) -> collection - :: - - resize!(collection, n) -> collection - Resize ``collection`` 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. .. function:: append!(collection, collection2) -> collection. - :: - - append!(collection, collection2) -> collection. - Add the elements of ``collection2`` to the end of ``collection``. 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)``. .. function:: prepend!(collection, items) -> collection - :: - - prepend!(collection, items) -> collection - Insert the elements of ``items`` to the beginning of @@ -1291,39 +783,23 @@ a basic priority queue implementation allowing for arbitrary key and priority ty Multiple identical keys are not permitted, but the priority of existing keys can be changed efficiently. -.. function:: PriorityQueue(K, V, [ord]) +.. function:: PriorityQueue(K, V[, ord]) - :: - - PriorityQueue(K, V[, ord]) - Construct a new ``PriorityQueue``, with keys of type ``K`` and values/priorites of type ``V``. If an order is not given, the priority queue is min-ordered using the default comparison for .. function:: enqueue!(pq, k, v) - :: - - enqueue!(pq, k, v) - Insert the a key ``k`` into a priority queue ``pq`` with priority .. function:: dequeue!(pq) - :: - - dequeue!(pq) - Remove and return the lowest priority key from a priority queue. .. function:: peek(pq) - :: - - peek(pq) - Return the lowest priority key from a priority queue without removing that key from the queue. @@ -1357,48 +833,28 @@ lower level functions for performing binary heap operations on arrays. Each function takes an optional ordering argument. If not given, default ordering is used, so that elements popped from the heap are given in ascending order. -.. function:: heapify(v, [ord]) +.. function:: heapify(v[, ord]) - :: - - heapify(v[, ord]) - Return a new vector in binary heap order, optionally using the given ordering. -.. function:: heapify!(v, [ord]) +.. function:: heapify!(v[, ord]) - :: - - heapify!(v[, ord]) - In-place ``heapify()``. -.. function:: isheap(v, [ord]) +.. function:: isheap(v[, ord]) - :: - - isheap(v[, ord]) - Return true iff an array is heap-ordered according to the given order. -.. function:: heappush!(v, x, [ord]) +.. function:: heappush!(v, x[, ord]) - :: - - heappush!(v, x[, ord]) - Given a binary heap-ordered array, push a new element ``x``, preserving the heap property. For efficiency, this function does not check that the array is indeed heap-ordered. -.. function:: heappop!(v, [ord]) +.. function:: heappop!(v[, ord]) - :: - - heappop!(v[, ord]) - Given a binary heap-ordered array, remove and return the lowest ordered element. For efficiency, this function does not check that the array is indeed heap-ordered. diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index 24a7de2709efc..24260a383a1f0 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -47,48 +47,28 @@ to use all other ``Dates`` functions, you'll need to prefix each function call w alternatively, you could call ``using Dates`` to bring all exported functions into ``Main`` to be used without the ``Dates.`` prefix. -.. function:: DateTime(y, [m, d, h, mi, s, ms]) -> DateTime +.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - :: - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. -.. function:: DateTime(periods::Period...) -> DateTime +.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - :: - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. -.. function:: DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime +.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - :: - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. -.. function:: DateTime(dt::Date) -> DateTime +.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - :: - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. -.. function:: DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime +.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - :: - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. @@ -98,91 +78,51 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - :: - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. -.. function:: Date(y, [m, d]) -> Date +.. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - - Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. -.. function:: Date(period::Period...) -> Date +.. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - - Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. -.. function:: Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date +.. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - - Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. -.. function:: Date(dt::DateTime) -> Date +.. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - - Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. -.. function:: Date(dt::AbstractString, format::AbstractString; locale="english") -> Date +.. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - - Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - - Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. -.. function:: now() -> DateTime +.. function:: now(::Type{UTC}) -> DateTime - :: - - now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as UTC/GMT. .. function:: now(::Type{UTC}) -> DateTime - :: - - now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as UTC/GMT. .. function:: eps(::DateTime) -> Millisecond - :: - - eps(::DateTime) -> Millisecond - Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. @@ -191,46 +131,26 @@ Accessor Functions .. function:: year(dt::TimeType) -> Int64 - :: - - year(dt::TimeType) -> Int64 - Return the field part of a Date or DateTime as an ``Int64``. -.. function:: Year(dt::TimeType) -> Year +.. function:: Year(v) - :: - - Year(v) - Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) - :: - - yearmonth(dt::TimeType) -> (Int64, Int64) - Simultaneously return the year and month parts of a Date or DateTime. .. function:: monthday(dt::TimeType) -> (Int64, Int64) - :: - - monthday(dt::TimeType) -> (Int64, Int64) - Simultaneously return the month and day parts of a Date or DateTime. .. function:: yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - :: - - yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - Simultaneously return the year, month, and day parts of a Date or DateTime. @@ -239,254 +159,143 @@ Query Functions .. function:: dayname(dt::TimeType; locale="english") -> AbstractString - :: - - dayname(dt::TimeType; locale="english") -> AbstractString - Return the full day name corresponding to the day of the week of the Date or DateTime in the given ``locale``. .. function:: dayabbr(dt::TimeType; locale="english") -> AbstractString - :: - - dayabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated name corresponding to the day of the week of the Date or DateTime in the given ``locale``. .. function:: dayofweek(dt::TimeType) -> Int64 - :: - - dayofweek(dt::TimeType) -> Int64 - Returns the day of the week as an ``Int64`` with ``1 = Monday, 2 = Tuesday, etc.``. .. function:: dayofweekofmonth(dt::TimeType) -> Int - :: - - dayofweekofmonth(dt::TimeType) -> Int - For the day of week of ``dt``, returns which number it is in etc.` In the range 1:5. .. function:: daysofweekinmonth(dt::TimeType) -> Int - :: - - daysofweekinmonth(dt::TimeType) -> Int - For the day of week of ``dt``, returns the total number of that day of the week in ``dt``'s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by including ``dayofweekofmonth(dt) == daysofweekinmonth(dt)`` in the adjuster function. .. function:: monthname(dt::TimeType; locale="english") -> AbstractString - :: - - monthname(dt::TimeType; locale="english") -> AbstractString - Return the full name of the month of the Date or DateTime in the given ``locale``. .. function:: monthabbr(dt::TimeType; locale="english") -> AbstractString - :: - - monthabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated month name of the Date or DateTime in the given ``locale``. .. function:: daysinmonth(dt::TimeType) -> Int - :: - - daysinmonth(dt::TimeType) -> Int - Returns the number of days in the month of ``dt``. Value will be 28, 29, 30, or 31. .. function:: isleapyear(dt::TimeType) -> Bool - :: - - isleapyear(dt::TimeType) -> Bool - Returns true if the year of ``dt`` is a leap year. .. function:: dayofyear(dt::TimeType) -> Int - :: - - dayofyear(dt::TimeType) -> Int - Returns the day of the year for ``dt`` with January 1st being day 1. .. function:: daysinyear(dt::TimeType) -> Int - :: - - daysinyear(dt::TimeType) -> Int - Returns 366 if the year of ``dt`` is a leap year, otherwise returns 365. .. function:: quarterofyear(dt::TimeType) -> Int - :: - - quarterofyear(dt::TimeType) -> Int - Returns the quarter that ``dt`` resides in. Range of value is 1:4. .. function:: dayofquarter(dt::TimeType) -> Int - :: - - dayofquarter(dt::TimeType) -> Int - Returns the day of the current quarter of ``dt``. Range of value is 1:92. Adjuster Functions ~~~~~~~~~~~~~~~~~~ -.. function:: trunc(dt::TimeType, ::Type{Period}) -> TimeType +.. function:: trunc([T], x[, digits[, base]]) - :: - - trunc([T], x[, digits[, base]]) .. function:: firstdayofweek(dt::TimeType) -> TimeType - :: - - firstdayofweek(dt::TimeType) -> TimeType - Adjusts ``dt`` to the Monday of its week. .. function:: lastdayofweek(dt::TimeType) -> TimeType - :: - - lastdayofweek(dt::TimeType) -> TimeType - Adjusts ``dt`` to the Sunday of its week. .. function:: firstdayofmonth(dt::TimeType) -> TimeType - :: - - firstdayofmonth(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its month. .. function:: lastdayofmonth(dt::TimeType) -> TimeType - :: - - lastdayofmonth(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its month. .. function:: firstdayofyear(dt::TimeType) -> TimeType - :: - - firstdayofyear(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its year. .. function:: lastdayofyear(dt::TimeType) -> TimeType - :: - - lastdayofyear(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its year. .. function:: firstdayofquarter(dt::TimeType) -> TimeType - :: - - firstdayofquarter(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its quarter. .. function:: lastdayofquarter(dt::TimeType) -> TimeType - :: - - lastdayofquarter(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its quarter. -.. function:: tonext(dt::TimeType,dow::Int;same::Bool=false) -> TimeType +.. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - :: - - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. -.. function:: toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType +.. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - :: - - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. -.. function:: tofirst(dt::TimeType,dow::Int;of=Month) -> TimeType +.. function:: tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - :: - - tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts ``dt`` to the first ``dow`` of its month. Alternatively, -.. function:: tolast(dt::TimeType,dow::Int;of=Month) -> TimeType +.. function:: tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - :: - - tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts ``dt`` to the last ``dow`` of its month. Alternatively, -.. function:: tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType +.. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - :: - - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. -.. function:: toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType +.. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - :: - - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. @@ -503,19 +312,11 @@ Periods .. function:: Year(v) - :: - - Year(v) - Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. .. function:: default(p::Period) -> Period - :: - - default(p::Period) -> Period - Returns a sensible ``default`` value for the input Period by returning ``one(p)`` for Year, Month, and Day, and ``zero(p)`` for Hour, Minute, Second, and Millisecond. @@ -524,64 +325,36 @@ Conversion Functions .. function:: today() -> Date - :: - - today() -> Date - Returns the date portion of ``now()``. .. function:: unix2datetime(x) -> DateTime - :: - - unix2datetime(x) -> DateTime - Takes the number of seconds since unix epoch .. function:: datetime2unix(dt::DateTime) -> Float64 - :: - - datetime2unix(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of seconds since the unix epoch as a ``Float64``. .. function:: julian2datetime(julian_days) -> DateTime - :: - - julian2datetime(julian_days) -> DateTime - Takes the number of Julian calendar days since epoch .. function:: datetime2julian(dt::DateTime) -> Float64 - :: - - datetime2julian(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of Julian calendar days since the julian epoch as a ``Float64``. .. function:: rata2datetime(days) -> DateTime - :: - - rata2datetime(days) -> DateTime - Takes the number of Rata Die days since epoch .. function:: datetime2rata(dt::TimeType) -> Int64 - :: - - datetime2rata(dt::TimeType) -> Int64 - Returns the number of Rata Die days since epoch from the given Date or DateTime. diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index f8d06def9cc77..6f47724d02aef 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -7,514 +7,286 @@ .. function:: pwd() -> AbstractString - :: - - pwd() -> AbstractString - Get the current working directory. -.. function:: cd(dir::AbstractString) +.. function:: cd(f[, dir]) - :: - - cd(f[, dir]) - Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. -.. function:: cd(f, [dir]) +.. function:: cd(f[, dir]) - :: - - cd(f[, dir]) - Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. .. function:: readdir([dir]) -> Vector{ByteString} - :: - - readdir([dir]) -> Vector{ByteString} - Returns the files and directories in the directory *dir* (or the current working directory if not given). -.. function:: mkdir(path, [mode]) +.. function:: mkdir(path[, mode]) - :: - - mkdir(path[, mode]) - Make a new directory with name ``path`` and permissions ``mode``. mask. -.. function:: mkpath(path, [mode]) +.. function:: mkpath(path[, mode]) - :: - - mkpath(path[, mode]) - Create all directories in the given ``path``, with permissions creation mask. .. function:: symlink(target, link) - :: - - symlink(target, link) - Creates a symbolic link to ``target`` with the name ``link``. Note: This function raises an error under operating systems that .. function:: readlink(path) -> AbstractString - :: - - readlink(path) -> AbstractString - Returns the value of a symbolic link ``path``. .. function:: chmod(path, mode) - :: - - chmod(path, mode) - Change the permissions mode of ``path`` to ``mode``. Only integer .. function:: stat(file) - :: - - stat(file) - Returns a structure whose fields contain information about the file. The fields of the structure are: .. function:: lstat(file) - :: - - lstat(file) - Like stat, but for symbolic links gets the info for the link itself rather than the file it refers to. This function must be called on a file path rather than a file object or a file descriptor. .. function:: ctime(file) - :: - - ctime(file) - Equivalent to stat(file).ctime .. function:: mtime(file) - :: - - mtime(file) - Equivalent to stat(file).mtime .. function:: filemode(file) - :: - - filemode(file) - Equivalent to stat(file).mode .. function:: filesize(path...) - :: - - filesize(path...) - Equivalent to stat(file).size .. function:: uperm(file) - :: - - uperm(file) - Gets the permissions of the owner of the file as a bitfield of For allowed arguments, see ``stat``. .. function:: gperm(file) - :: - - gperm(file) - Like uperm but gets the permissions of the group owning the file .. function:: operm(file) - :: - - operm(file) - Like uperm but gets the permissions for people who neither own the file nor are a member of the group owning the file .. function:: cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - :: - - cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - Copy the file, link, or directory from *src* to *dest*. If *follow_symlinks=false*, and src is a symbolic link, dst will be created as a symbolic link. If *follow_symlinks=true* and src is a symbolic link, dst will be a copy of the file or directory *src* refers to. -.. function:: download(url,[localfile]) +.. function:: download(url[, localfile]) - :: - - download(url[, localfile]) - Download a file from the given url, optionally renaming it to the given local file name. Note that this function relies on the availability of external tools such as ``curl``, ``wget`` or production use or situations in which more options are need, please use a package that provides the desired functionality instead. -.. function:: mv(src::AbstractString,dst::AbstractString; remove_destination::Bool=false) +.. function:: mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - :: - - mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - Move the file, link, or directory from *src* to *dest*. .. function:: rm(path::AbstractString; recursive=false) - :: - - rm(path::AbstractString; recursive=false) - Delete the file, link, or empty directory at the given path. If contents are removed recursively. .. function:: touch(path::AbstractString) - :: - - touch(path::AbstractString) - Update the last-modified timestamp on a file to the current time. .. function:: tempname() - :: - - tempname() - Generate a unique temporary file path. .. function:: tempdir() - :: - - tempdir() - Obtain the path of a temporary directory (possibly shared with other processes). .. function:: mktemp([parent=tempdir()]) - :: - - mktemp([parent=tempdir()]) - Returns ``(path, io)``, where ``path`` is the path of a new temporary file in ``parent`` and ``io`` is an open file object for this path. .. function:: mktempdir([parent=tempdir()]) - :: - - mktempdir([parent=tempdir()]) - Create a temporary directory in the ``parent`` directory and return its path. .. function:: isblockdev(path) -> Bool - :: - - isblockdev(path) -> Bool - Returns ``true`` if ``path`` is a block device, ``false`` otherwise. .. function:: ischardev(path) -> Bool - :: - - ischardev(path) -> Bool - Returns ``true`` if ``path`` is a character device, ``false`` otherwise. .. function:: isdir(path) -> Bool - :: - - isdir(path) -> Bool - Returns ``true`` if ``path`` is a directory, ``false`` otherwise. .. function:: isexecutable(path) -> Bool - :: - - isexecutable(path) -> Bool - Returns ``true`` if the current user has permission to execute .. function:: isfifo(path) -> Bool - :: - - isfifo(path) -> Bool - Returns ``true`` if ``path`` is a FIFO, ``false`` otherwise. .. function:: isfile(path) -> Bool - :: - - isfile(path) -> Bool - Returns ``true`` if ``path`` is a regular file, ``false`` otherwise. .. function:: islink(path) -> Bool - :: - - islink(path) -> Bool - Returns ``true`` if ``path`` is a symbolic link, ``false`` otherwise. .. function:: ismount(path) -> Bool - :: - - ismount(path) -> Bool - Returns ``true`` if ``path`` is a mount point, ``false`` otherwise. .. function:: ispath(path) -> Bool - :: - - ispath(path) -> Bool - Returns ``true`` if ``path`` is a valid filesystem path, ``false`` otherwise. .. function:: isreadable(path) -> Bool - :: - - isreadable(path) -> Bool - Returns ``true`` if the current user has permission to read .. function:: issetgid(path) -> Bool - :: - - issetgid(path) -> Bool - Returns ``true`` if ``path`` has the setgid flag set, ``false`` otherwise. .. function:: issetuid(path) -> Bool - :: - - issetuid(path) -> Bool - Returns ``true`` if ``path`` has the setuid flag set, ``false`` otherwise. .. function:: issocket(path) -> Bool - :: - - issocket(path) -> Bool - Returns ``true`` if ``path`` is a socket, ``false`` otherwise. .. function:: issticky(path) -> Bool - :: - - issticky(path) -> Bool - Returns ``true`` if ``path`` has the sticky bit set, ``false`` otherwise. .. function:: iswritable(path) -> Bool - :: - - iswritable(path) -> Bool - Returns ``true`` if the current user has permission to write to .. function:: homedir() -> AbstractString - :: - - homedir() -> AbstractString - Return the current user's home directory. .. function:: dirname(path::AbstractString) -> AbstractString - :: - - dirname(path::AbstractString) -> AbstractString - Get the directory part of a path. .. function:: basename(path::AbstractString) -> AbstractString - :: - - basename(path::AbstractString) -> AbstractString - Get the file name part of a path. .. function:: @__FILE__() -> AbstractString - :: - - @__FILE__() -> AbstractString - name of the script being run. Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e ``. .. function:: isabspath(path::AbstractString) -> Bool - :: - - isabspath(path::AbstractString) -> Bool - Determines whether a path is absolute (begins at the root directory). .. function:: isdirpath(path::AbstractString) -> Bool - :: - - isdirpath(path::AbstractString) -> Bool - Determines whether a path refers to a directory (for example, ends with a path separator). .. function:: joinpath(parts...) -> AbstractString - :: - - joinpath(parts...) -> AbstractString - Join path components into a full path. If some argument is an absolute path, then prior components are dropped. .. function:: abspath(path::AbstractString) -> AbstractString - :: - - abspath(path::AbstractString) -> AbstractString - Convert a path to an absolute path by adding the current directory if necessary. .. function:: normpath(path::AbstractString) -> AbstractString - :: - - normpath(path::AbstractString) -> AbstractString - Normalize a path, removing ``.`` and ``..`` entries. .. function:: realpath(path::AbstractString) -> AbstractString - :: - - realpath(path::AbstractString) -> AbstractString - Canonicalize a path by expanding symbolic links and removing ``.`` and ``..`` entries. .. function:: relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - :: - - relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - Return a relative filepath to path either from the current directory or from an optional start directory. This is a path computation: the filesystem is not accessed to confirm the existence or nature of path or startpath. .. function:: expanduser(path::AbstractString) -> AbstractString - :: - - expanduser(path::AbstractString) -> AbstractString - On Unix systems, replace a tilde character at the start of a path with the current user's home directory. -.. function:: splitdir(path::AbstractString) -> (AbstractString,AbstractString) +.. function:: splitdir(path::AbstractString) -> (AbstractString, AbstractString) - :: - - splitdir(path::AbstractString) -> (AbstractString, AbstractString) - Split a path into a tuple of the directory name and file name. -.. function:: splitdrive(path::AbstractString) -> (AbstractString,AbstractString) +.. function:: splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - :: - - splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - On Windows, split a path into the drive letter part and the path part. On Unix systems, the first component is always the empty string. -.. function:: splitext(path::AbstractString) -> (AbstractString,AbstractString) +.. function:: splitext(path::AbstractString) -> (AbstractString, AbstractString) - :: - - splitext(path::AbstractString) -> (AbstractString, AbstractString) - If the last component of a path contains a dot, split the path into everything before the dot and everything including and after the dot. Otherwise, return a tuple of the argument unmodified and the empty string. diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 26bb221bd7cbe..422475070152f 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -19,435 +19,243 @@ General I/O Global variable referring to the standard input stream. -.. function:: open(file_name, [read, write, create, truncate, append]) -> IOStream +.. function:: open(f::function, args...) - :: - - open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. -.. function:: open(file_name, [mode]) -> IOStream +.. function:: open(f::function, args...) - :: - - open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. .. function:: open(f::function, args...) - :: - - open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. -.. function:: IOBuffer() -> IOBuffer +.. function:: IOBuffer([data][, readable, writable[, maxsize]]) - :: - - IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. -.. function:: IOBuffer(size::Int) +.. function:: IOBuffer([data][, readable, writable[, maxsize]]) - :: - - IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. -.. function:: IOBuffer(string) +.. function:: IOBuffer([data][, readable, writable[, maxsize]]) - :: - - IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. -.. function:: IOBuffer([data,],[readable,writable,[maxsize]]) +.. function:: IOBuffer([data][, readable, writable[, maxsize]]) - :: - - IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. .. function:: takebuf_array(b::IOBuffer) - :: - - takebuf_array(b::IOBuffer) - Obtain the contents of an ``IOBuffer`` as an array, without copying. Afterwards, the IOBuffer is reset to its initial state. .. function:: takebuf_string(b::IOBuffer) - :: - - takebuf_string(b::IOBuffer) - Obtain the contents of an ``IOBuffer`` as a string, without copying. Afterwards, the IOBuffer is reset to its initial state. -.. function:: fdio([name::AbstractString, ]fd::Integer[, own::Bool]) -> IOStream +.. function:: fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - :: - - fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - Create an ``IOStream`` object from an integer file descriptor. If descriptor. By default, an ``IOStream`` is closed when it is garbage collected. ``name`` allows you to associate the descriptor with a named file. .. function:: flush(stream) - :: - - flush(stream) - Commit all currently buffered writes to the given stream. .. function:: close(stream) - :: - - close(stream) - Close an I/O stream. Performs a ``flush`` first. .. function:: write(stream, x) - :: - - write(stream, x) - Write the canonical binary representation of a value to the given stream. -.. function:: read(stream, type) +.. function:: read(stream, type, dims) - :: - - read(stream, type, dims) - Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. .. function:: read(stream, type, dims) - :: - - read(stream, type, dims) - Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. .. function:: read!(stream, array::Array) - :: - - read!(stream, array::Array) - Read binary data from a stream, filling in the argument ``array``. .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - :: - - readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - Read at most ``nb`` bytes from the stream into ``b``, returning the number of bytes read (increasing the size of ``b`` as needed). .. function:: readbytes(stream, nb=typemax(Int)) - :: - - readbytes(stream, nb=typemax(Int)) - Read at most ``nb`` bytes from the stream, returning a .. function:: position(s) - :: - - position(s) - Get the current position of a stream. .. function:: seek(s, pos) - :: - - seek(s, pos) - Seek a stream to the given position. .. function:: seekstart(s) - :: - - seekstart(s) - Seek a stream to its beginning. .. function:: seekend(s) - :: - - seekend(s) - Seek a stream to its end. .. function:: skip(s, offset) - :: - - skip(s, offset) - Seek a stream relative to the current position. .. function:: mark(s) - :: - - mark(s) - Add a mark at the current position of stream ``s``. Returns the marked position. See also ``unmark()``, ``reset()``, ``ismarked()`` .. function:: unmark(s) - :: - - unmark(s) - Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. See also ``mark()``, ``reset()``, ``ismarked()`` .. function:: reset(s) - :: - - reset(s) - Reset a stream ``s`` to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked. See also ``mark()``, ``unmark()``, ``ismarked()`` .. function:: ismarked(s) - :: - - ismarked(s) - Returns true if stream ``s`` is marked. See also ``mark()``, ``unmark()``, ``reset()`` .. function:: eof(stream) -> Bool - :: - - eof(stream) -> Bool - Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return ``false``. Therefore it is always safe to read one byte after seeing ``eof`` return ``false``. ``eof`` will return ``false`` as long as buffered data is still available, even if the remote end of a connection is closed. .. function:: isreadonly(stream) -> Bool - :: - - isreadonly(stream) -> Bool - Determine whether a stream is read-only. .. function:: isopen(stream) -> Bool - :: - - isopen(stream) -> Bool - Determine whether a stream is open (i.e. has not been closed yet). If the connection has been closed remotely (in case of e.g. a socket), ``isopen`` will return ``false`` even though buffered data may still be available. Use ``eof`` to check if necessary. .. function:: serialize(stream, value) - :: - - serialize(stream, value) - Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``. The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. .. function:: deserialize(stream) - :: - - deserialize(stream) - Read a value written by ``serialize``. .. function:: print_escaped(io, str::AbstractString, esc::AbstractString) - :: - - print_escaped(io, str::AbstractString, esc::AbstractString) - General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). .. function:: print_unescaped(io, s::AbstractString) - :: - - print_unescaped(io, s::AbstractString) - General unescaping of traditional C and Unicode escape sequences. Reverse of ``print_escaped()``. -.. function:: print_joined(io, items, delim, [last]) +.. function:: print_joined(io, items, delim[, last]) - :: - - print_joined(io, items, delim[, last]) - Print elements of ``items`` to ``io`` with ``delim`` between them. If ``last`` is specified, it is used as the final delimiter instead of ``delim``. .. function:: print_shortest(io, x) - :: - - print_shortest(io, x) - Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number ``x``, ensuring that it would parse to the exact same number. .. function:: fd(stream) - :: - - fd(stream) - Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. -.. function:: redirect_stdout() +.. function:: redirect_stdout(stream) - :: - - redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. .. function:: redirect_stdout(stream) - :: - - redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. .. function:: redirect_stderr([stream]) - :: - - redirect_stderr([stream]) - Like redirect_stdout, but for STDERR .. function:: redirect_stdin([stream]) - :: - - redirect_stdin([stream]) - Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read from STDIN, may be written to wr. .. function:: readchomp(x) - :: - - readchomp(x) - Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). -.. function:: truncate(file,n) +.. function:: truncate(file, n) - :: - - truncate(file, n) - Resize the file or buffer given by the first argument to exactly file or buffer is grown .. function:: skipchars(stream, predicate; linecomment::Char) - :: - - skipchars(stream, predicate; linecomment::Char) - Advance the stream until before the first character for which isspace)` will skip all whitespace. If keyword argument through the end of a line will also be skipped. -.. function:: countlines(io,[eol::Char]) +.. function:: countlines(io[, eol::Char]) - :: - - countlines(io[, eol::Char]) - Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first argument. EOL markers other than '\n' are supported by passing them as the second argument. -.. function:: PipeBuffer() +.. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) - :: - - PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. -.. function:: PipeBuffer(data::Vector{UInt8},[maxsize]) +.. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) - :: - - PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. .. function:: readavailable(stream) - :: - - readavailable(stream) - Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``. @@ -456,307 +264,171 @@ Text I/O .. function:: show(x) - :: - - show(x) - Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. The representation used by ``show`` generally includes Julia-specific formatting and type information. .. function:: showcompact(x) - :: - - showcompact(x) - Show a more compact representation of a value. This is used for printing array elements. If a new type has a different compact representation, it should overload ``showcompact(io, x)`` where the first argument is a stream. .. function:: showall(x) - :: - - showall(x) - Similar to ``show``, except shows all elements of arrays. .. function:: summary(x) - :: - - summary(x) - Return a string giving a brief description of a value. By default returns ``string(typeof(x))``. For arrays, returns strings like .. function:: print(x) - :: - - print(x) - Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call formatting and tries to avoid Julia-specific details. .. function:: println(x) - :: - - println(x) - Print (using ``print()``) ``x`` followed by a newline. -.. function:: print_with_color(color::Symbol, [io], strings...) +.. function:: print_with_color(color::Symbol[, io], strings...) - :: - - print_with_color(color::Symbol[, io], strings...) - Print strings in a color specified as a symbol, for example .. function:: info(msg) - :: - - info(msg) - Display an informational message. .. function:: warn(msg) - :: - - warn(msg) - Display a warning. .. function:: @printf([io::IOStream], "%Fmt", args...) - :: - - @printf([io::IOStream], "%Fmt", args...) - Print arg(s) using C ``printf()`` style format specification string. Optionally, an IOStream may be passed as the first argument to redirect output. .. function:: @sprintf("%Fmt", args...) - :: - - @sprintf("%Fmt", args...) - Return ``@printf`` formatted output as string. .. function:: sprint(f::Function, args...) - :: - - sprint(f::Function, args...) - Call the given function with an I/O stream and the supplied extra arguments. Everything written to this I/O stream is returned as a string. .. function:: showerror(io, e) - :: - - showerror(io, e) - Show a descriptive representation of an exception object. .. function:: dump(x) - :: - - dump(x) - Show all user-visible structure of a value. .. function:: xdump(x) - :: - - xdump(x) - Show all structure of a value, including all fields of objects. -.. function:: readall(stream::IO) +.. function:: readall(filename::AbstractString) - :: - - readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. .. function:: readall(filename::AbstractString) - :: - - readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. .. function:: readline(stream=STDIN) - :: - - readline(stream=STDIN) - Read a single line of text, including a trailing newline character .. function:: readuntil(stream, delim) - :: - - readuntil(stream, delim) - Read a string, up to and including the given delimiter byte. .. function:: readlines(stream) - :: - - readlines(stream) - Read all lines as an array. .. function:: eachline(stream) - :: - - eachline(stream) - Create an iterable object that will yield each line from a stream. -.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') +.. function:: readdlm(source; options...) - :: - - readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source, delim::Char, eol::Char; options...) +.. function:: readdlm(source; options...) - :: - - readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source, delim::Char, T::Type; options...) +.. function:: readdlm(source; options...) - :: - - readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source, delim::Char; options...) +.. function:: readdlm(source; options...) - :: - - readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source, T::Type; options...) +.. function:: readdlm(source; options...) - :: - - readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: readdlm(source; options...) - :: - - readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: writedlm(f, A, delim='\\t') +.. function:: writedlm(f, A, delim='\t') - :: - - writedlm(f, A, delim='\t') - Write ``A`` (a vector, matrix or an iterable collection of iterable rows) as text to ``f`` (either a filename string or an ``IO`` stream) using the given delimeter ``delim`` (which defaults to tab, but can be any printable Julia object, typically a ``Char`` or For example, two vectors ``x`` and ``y`` of the same length can be written as two columns of tab-delimited text to ``f`` by either .. function:: readcsv(source, [T::Type]; options...) - :: - - readcsv(source, [T::Type]; options...) - Equivalent to ``readdlm`` with ``delim`` set to comma. .. function:: writecsv(filename, A) - :: - - writecsv(filename, A) - Equivalent to ``writedlm`` with ``delim`` set to comma. .. function:: Base64EncodePipe(ostream) - :: - - Base64EncodePipe(ostream) - Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to necessary to complete the encoding (but does not close .. function:: Base64DecodePipe(istream) - :: - - Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded data read from ``istream``. .. function:: base64encode(writefunc, args...) - :: - - base64encode(writefunc, args...) - Given a ``write``-like function ``writefunc``, which takes an I/O stream as its first argument, ``base64(writefunc, args...)`` calls returns the string. ``base64(args...)`` is equivalent to using the standard ``write`` functions and returns the base64-encoded string. .. function:: base64decode(string) - :: - - base64decode(string) - Decodes the base64-encoded ``string`` and returns a @@ -783,64 +455,36 @@ Julia environments (such as the IPython-based IJulia notebook). .. function:: display(x) - :: - - display(x) - Display ``x`` using the topmost applicable display in the display stack, typically using the richest supported multimedia output for display ``d`` only, throwing a ``MethodError`` if ``d`` cannot display objects of this type. There are also two variants with a ``mime`` argument (a MIME type string, such as ``image/png``), which attempt to display ``x`` using the requested MIME type *only*, throwing a ``MethodError`` if this type is not supported by either the display(s) or by ``x``. With these variants, one can also supply the ``raw`` data in the requested MIME type by passing ``x::AbstractString`` (for MIME types with text-based storage, such as text/html or application/postscript) or ``x::Vector{UInt8}`` (for binary MIME types). .. function:: redisplay(x) - :: - - redisplay(x) - By default, the ``redisplay`` functions simply call ``display``. However, some display backends may override ``redisplay`` to modify an existing display of ``x`` (if any). Using ``redisplay`` is also a hint to the backend that ``x`` may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt. .. function:: displayable(mime) -> Bool - :: - - displayable(mime) -> Bool - Returns a boolean value indicating whether the given ``mime`` type display stack, or specifically by the display ``d`` in the second variant. .. function:: writemime(stream, mime, x) - :: - - writemime(stream, mime, x) - - The ``display`` functions ultimately call ``writemime`` in order to write an object ``x`` as a given ``mime`` type to a given I/O provide a rich multimedia representation of a user-defined type for ``T``, via: ``writemime(stream, ::MIME``mime``, x::T) = ...``, where ``mime`` is a MIME-type string and the function body calls literal strings; to construct ``MIME`` types in a more flexible manner use ``MIME{symbol(``)}``.) For example, if you define a ``MyImage`` type and know how to write it to a PNG file, you could define a function ``writemime(stream, be displayed on any PNG-capable `Display`` (such as IJulia). As usual, be sure to ``import Base.writemime`` in order to add new methods to the built-in Julia function ``writemime``. Technically, the ``MIME``mime`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. + The ``display`` functions ultimately call ``writemime`` in order to write an object ``x`` as a given ``mime`` type to a given I/O provide a rich multimedia representation of a user-defined type for ``T``, via: ``writemime(stream, ::MIME"mime", x::T) = ...``, where ``mime`` is a MIME-type string and the function body calls literal strings; to construct ``MIME`` types in a more flexible manner use ``MIME{symbol("")}``.) For example, if you define a ``MyImage`` type and know how to write it to a PNG file, you could define a function ``writemime(stream, be displayed on any PNG-capable `Display`` (such as IJulia). As usual, be sure to ``import Base.writemime`` in order to add new methods to the built-in Julia function ``writemime``. Technically, the ``MIME"mime"`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. .. function:: mimewritable(mime, x) - :: - - mimewritable(mime, x) - Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding .. function:: reprmime(mime, x) - :: - - reprmime(mime, x) - Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the representation of ``x`` in the requested ``mime`` type, as written by ``writemime`` (throwing a ``MethodError`` if no appropriate MIME types with textual representations (such as ``text/html`` or ``application/postscript``), whereas binary data is returned as ``Vector{UInt8}``. (The function ``istext(mime)`` returns whether or not Julia treats a given ``mime`` type as text.) As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) or a ``Vector{UInt8}`` (for binary MIME types), the requested ``mime`` format and simply returns ``x``. .. function:: stringmime(mime, x) - :: - - stringmime(mime, x) - Returns an ``AbstractString`` containing the representation of string. @@ -872,277 +516,157 @@ stack with: .. function:: pushdisplay(d::Display) - :: - - pushdisplay(d::Display) - Pushes a new display ``d`` on top of the global display-backend stack. Calling ``display(x)`` or ``display(mime, x)`` will display topmost backend that does not throw a ``MethodError``). .. function:: popdisplay() - :: - - popdisplay() - Pop the topmost backend off of the display-backend stack, or the topmost copy of ``d`` in the second variant. .. function:: TextDisplay(stream) - :: - - TextDisplay(stream) - Returns a ``TextDisplay <: Display``, which can display any object as the text/plain MIME type (only), writing the text representation to the given I/O stream. (The text representation is the same as the way an object is printed in the Julia REPL.) .. function:: istext(m::MIME) - :: - - istext(m::MIME) - Determine whether a MIME type is text data. Memory-mapped I/O ----------------- -.. function:: mmap_array(type, dims, stream, [offset]) +.. function:: mmap_array(type, dims, stream[, offset]) - :: - - mmap_array(type, dims, stream[, offset]) - Create an ``Array`` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory. The type determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). The file is passed via the stream argument. When you initialize the stream, use ``r`` for a ``read-only`` array, and ``w+`` to create a new array used to write values to disk. Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position. For example, the following code: creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. A more portable file would need to encode the word size–-32 bit or 64 bit–-and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 -.. function:: mmap_bitarray([type,] dims, stream, [offset]) +.. function:: mmap_bitarray([type], dims, stream[, offset]) - :: - - mmap_bitarray([type], dims, stream[, offset]) - Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as ``mmap_array()``, but the byte representation is different. The ``type`` parameter is optional, and must be ``Bool`` if given. This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. -.. function:: msync(array) +.. function:: msync(ptr, len[, flags]) - :: - - msync(ptr, len[, flags]) - Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. Network I/O ----------- -.. function:: connect([host],port) -> TcpSocket +.. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - :: - - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. -.. function:: connect(path) -> Pipe +.. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - :: - - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. -.. function:: listen([addr,]port) -> TcpServer +.. function:: listen(path) -> PipeServer - :: - - listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket .. function:: listen(path) -> PipeServer - :: - - listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket .. function:: getaddrinfo(host) - :: - - getaddrinfo(host) - Gets the IP address of the ``host`` (may have to do a DNS lookup) .. function:: parseip(addr) - :: - - parseip(addr) - Parse a string specifying an IPv4 or IPv6 ip address. .. function:: IPv4(host::Integer) -> IPv4 - :: - - IPv4(host::Integer) -> IPv4 - Returns IPv4 object from ip address formatted as Integer .. function:: IPv6(host::Integer) -> IPv6 - :: - - IPv6(host::Integer) -> IPv6 - Returns IPv6 object from ip address formatted as Integer .. function:: nb_available(stream) - :: - - nb_available(stream) - Returns the number of bytes available for reading before a read from this stream or buffer will block. -.. function:: accept(server[,client]) +.. function:: accept(server[, client]) - :: - - accept(server[, client]) - Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. -.. function:: listenany(port_hint) -> (UInt16,TcpServer) +.. function:: listenany(port_hint) -> (UInt16, TcpServer) - :: - - listenany(port_hint) -> (UInt16, TcpServer) - Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server was created on and the server itself. .. function:: watch_file(cb=false, s; poll=false) - :: - - watch_file(cb=false, s; poll=false) - Watch file or directory ``s`` and run callback ``cb`` when ``s`` is modified. The ``poll`` parameter specifies whether to use file system event monitoring or polling. The callback function ``cb`` should accept 3 arguments: ``(filename, events, status)`` where an object with boolean fields ``changed`` and ``renamed`` when using file system event monitoring, or ``readable`` and .. function:: poll_fd(fd, seconds::Real; readable=false, writable=false) - :: - - poll_fd(fd, seconds::Real; readable=false, writable=false) - Poll a file descriptor fd for changes in the read or write availability and with a timeout given by the second argument. If the timeout is not needed, use ``wait(fd)`` instead. The keyword arguments determine which of read and/or write status should be monitored and at least one of them needs to be set to true. The returned value is an object with boolean fields ``readable``, .. function:: poll_file(s, interval_seconds::Real, seconds::Real) - :: - - poll_file(s, interval_seconds::Real, seconds::Real) - Monitor a file for changes by polling every *interval_seconds* seconds for *seconds* seconds. A return value of true indicates the file changed, a return value of false indicates a timeout. .. function:: bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - :: - - bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - Bind ``socket`` to the given ``host:port``. Note that *0.0.0.0* will listen on all devices. .. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) - :: - - send(socket::UDPSocket, host::IPv4, port::Integer, msg) - - Send ``msg`` over ``socket to ``host:port``. + Send ``msg`` over ``socket to `host:port``. .. function:: recv(socket::UDPSocket) - :: - - recv(socket::UDPSocket) - Read a UDP packet from the specified socket, and return the bytes received. This call blocks. .. function:: recvfrom(socket::UDPSocket) -> (address, data) - :: - - recvfrom(socket::UDPSocket) -> (address, data) - Read a UDP packet from the specified socket, returning a tuple of appropriate. .. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - :: - - setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - Set UDP socket options. ``multicast_loop``: loopback for multicast packets (default: true). ``multicast_ttl``: TTL for multicast packets. ``enable_broadcast``: flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). ``ttl``: Time-to-live of packets sent on the socket. .. function:: ntoh(x) - :: - - ntoh(x) - Converts the endianness of a value from Network byte order (big- endian) to that used by the Host. .. function:: hton(x) - :: - - hton(x) - Converts the endianness of a value from that used by the Host to Network byte order (big-endian). .. function:: ltoh(x) - :: - - ltoh(x) - Converts the endianness of a value from Little-endian to that used by the Host. .. function:: htol(x) - :: - - htol(x) - Converts the endianness of a value from that used by the Host to Little-endian. diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index 623436fc64773..f20e663f6e67b 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -6,109 +6,61 @@ .. function:: malloc(size::Integer) -> Ptr{Void} - :: - - malloc(size::Integer) -> Ptr{Void} - Call ``malloc`` from the C standard library. .. function:: calloc(num::Integer, size::Integer) -> Ptr{Void} - :: - - calloc(num::Integer, size::Integer) -> Ptr{Void} - Call ``calloc`` from the C standard library. .. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void} - :: - - realloc(addr::Ptr, size::Integer) -> Ptr{Void} - Call ``realloc`` from the C standard library. See warning in the documentation for ``free`` regarding only using this on memory originally obtained from ``malloc``. .. function:: free(addr::Ptr) - :: - - free(addr::Ptr) - Call ``free`` from the C standard library. Only use this on memory obtained from ``malloc``, not on pointers retrieved from other C libraries. ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library, to avoid assertion failures if multiple ``libc`` libraries exist on the system. .. function:: errno([code]) - :: - - errno([code]) - Get the value of the C library's ``errno``. If an argument is specified, it is used to set the value of ``errno``. The value of ``errno`` is only valid immediately after a ``ccall`` to a C library routine that sets it. Specifically, you cannot call executed between prompts. .. function:: strerror(n) - :: - - strerror(n) - Convert a system call error code to a descriptive string .. function:: time(t::TmStruct) - :: - - time(t::TmStruct) - Converts a ``TmStruct`` struct to a number of seconds since the epoch. .. function:: strftime([format], time) - :: - - strftime([format], time) - Convert time, given as a number of seconds since the epoch or a Supported formats are the same as those in the standard C library. .. function:: strptime([format], timestr) - :: - - strptime([format], timestr) - Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the will tell the C library to use the current system settings to determine the timezone. .. function:: TmStruct([seconds]) - :: - - TmStruct([seconds]) - Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, .. function:: flush_cstdio() - :: - - flush_cstdio() - Flushes the C ``stdout`` and ``stderr`` streams (which may have been written to by external C code). -.. function:: msync(ptr, len, [flags]) +.. function:: msync(ptr, len[, flags]) - :: - - msync(ptr, len[, flags]) - Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. @@ -126,19 +78,11 @@ .. function:: mmap(len, prot, flags, fd, offset) - :: - - mmap(len, prot, flags, fd, offset) - Low-level interface to the ``mmap`` system call. See the man page. .. function:: munmap(pointer, len) - :: - - munmap(pointer, len) - Low-level interface for unmapping memory (see the man page). With is unmapped for you when the array goes out of scope. diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index 569944ebc789c..953dd1a923247 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -4,21 +4,13 @@ Dynamic Linker **************** -.. function:: dlopen(libfile::AbstractString [, flags::Integer]) +.. function:: dlopen(libfile::AbstractString[, flags::Integer]) - :: - - dlopen(libfile::AbstractString[, flags::Integer]) - Load a shared library, returning an opaque handle. The optional flags argument is a bitwise-or of zero or more of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default is these flags, on POSIX platforms, is to specify symbols to be available for usage in other shared libraries, in situations where there are dependencies between shared libraries. -.. function:: dlopen_e(libfile::AbstractString [, flags::Integer]) +.. function:: dlopen_e(libfile::AbstractString[, flags::Integer]) - :: - - dlopen_e(libfile::AbstractString[, flags::Integer]) - Similar to ``dlopen()``, except returns a ``NULL`` pointer instead of raising errors. @@ -56,37 +48,21 @@ .. function:: dlsym(handle, sym) - :: - - dlsym(handle, sym) - Look up a symbol from a shared library handle, return callable function pointer on success. .. function:: dlsym_e(handle, sym) - :: - - dlsym_e(handle, sym) - Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. .. function:: dlclose(handle) - :: - - dlclose(handle) - Close shared library referenced by handle. .. function:: find_library(names, locations) - :: - - find_library(names, locations) - Searches for the first library in ``names`` in the paths in the that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 081bf84f7e7f6..45ba5f4683424 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -13,12 +13,8 @@ Standard Functions Linear algebra functions in Julia are largely implemented by calling functions from `LAPACK `_. Sparse factorizations call functions from `SuiteSparse `_. -.. function:: *(A, B) +.. function:: *(s, t) - :: - - *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. @@ -31,46 +27,26 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: dot(x, y) - :: - - dot(x, y) - Compute the dot product. For complex vectors, the first vector is conjugated. .. function:: vecdot(x, y) - :: - - vecdot(x, y) - For any iterable containers ``x`` and ``y`` (including arrays of any dimension) of numbers (or any element type for which ``dot`` is defined), compute the Euclidean dot product (the sum of .. function:: cross(x, y) - :: - - cross(x, y) - Compute the cross product of two 3-vectors. .. function:: factorize(A) - :: - - factorize(A) - Compute a convenient factorization (including LU, Cholesky, Bunch- Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: -.. function:: full(F) +.. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - :: - - full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. @@ -78,136 +54,76 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: lu(A) -> L, U, p - :: - - lu(A) -> L, U, p - Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. -.. function:: lufact(A [,pivot=Val{true}]) -> F +.. function:: lufact(A[, pivot=Val{true}]) -> F - :: - - lufact(A[, pivot=Val{true}]) -> F - Compute the LU factorization of ``A``. The return type of ``F`` depends on the type of ``A``. In most cases, if ``A`` is a subtype pivoting is chosen (default) the element type should also support examples are shown in the table below. The individual components of the factorization ``F`` can be accessed by indexing: .. function:: lufact!(A) -> LU - :: - - lufact!(A) -> LU - overwriting the input A, instead of creating a copy. For sparse 1-based indices to 0-based indices. -.. function:: chol(A, [LU]) -> F +.. function:: chol(A[, LU]) -> F - :: - - chol(A[, LU]) -> F - Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. -.. function:: cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky +.. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - :: - - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - :: - - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - :: - - cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - overwriting the input ``A``, instead of creating a copy. different matrix ``F`` with the same structure when used as: -.. function:: ldltfact(A) -> LDLtFactorization +.. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - :: - - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - :: - - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. -.. function:: qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] +.. function:: qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - :: - - qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - Compute the (pivoted) QR factorization of ``A`` such that either is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. -.. function:: qrfact(A [,pivot=Val{false}]) -> F +.. function:: qrfact(A) -> SPQR.Factorization - :: - - qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. .. function:: qrfact(A) -> SPQR.Factorization - :: - - qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. -.. function:: qrfact!(A [,pivot=Val{false}]) +.. function:: qrfact!(A[, pivot=Val{false}]) - :: - - qrfact!(A[, pivot=Val{false}]) - instead of creating a copy. .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - :: - - full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. .. function:: bkfact(A) -> BunchKaufman - :: - - bkfact(A) -> BunchKaufman - Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix ``A`` and return a @@ -215,541 +131,301 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: bkfact!(A) -> BunchKaufman - :: - - bkfact!(A) -> BunchKaufman - overwriting the input ``A``, instead of creating a copy. .. function:: sqrtm(A) - :: - - sqrtm(A) - Compute the matrix square root of ``A``. If ``B = sqrtm(A)``, then using Schur factorizations (``schurfact()``) unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition (``eigfact()``). In the latter situation for positive definite matrices, the matrix square root has ``Real`` elements, otherwise it has ``Complex`` elements. -.. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V +.. function:: eig(A, B) -> D, V - :: - - eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. .. function:: eig(A, B) -> D, V - :: - - eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. .. function:: eigvals(A,[irange,][vl,][vu]) - :: - - eigvals(A,[irange,][vl,][vu]) - Returns the eigenvalues of ``A``. If ``A`` is ``Symmetric``, only a subset of the eigenvalues by specifying either a eigenvalues, or a pair ``vl`` and ``vu`` for the lower and upper boundaries of the eigenvalues. For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option ``permute=true`` permutes the matrix to become closer to upper triangular, and ``scale=true`` scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is ``true`` for both options. .. function:: eigmax(A) - :: - - eigmax(A) - Returns the largest eigenvalue of ``A``. .. function:: eigmin(A) - :: - - eigmin(A) - Returns the smallest eigenvalue of ``A``. .. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - :: - - eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - Returns a matrix ``M`` whose columns are the eigenvectors of ``A``. k]``.) The `permute`` and ``scale`` keywords are the same as for For ``SymTridiagonal`` matrices, if the optional vector of eigenvalues ``eigvals`` is specified, returns the specific corresponding eigenvectors. -.. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen +.. function:: eigfact(A, B) -> GeneralizedEigen - :: - - eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) .. function:: eigfact(A, B) -> GeneralizedEigen - :: - - eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) -.. function:: eigfact!(A, [B]) +.. function:: eigfact!(A[, B]) - :: - - eigfact!(A[, B]) - Same as ``eigfact()``, but saves space by overwriting the input .. function:: hessfact(A) - :: - - hessfact(A) - Compute the Hessenberg decomposition of ``A`` and return a unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``. When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with ``full()``. .. function:: hessfact!(A) - :: - - hessfact!(A) - overwriting the input A, instead of creating a copy. -.. function:: schurfact(A) -> Schur +.. function:: schurfact(A, B) -> GeneralizedSchur - :: - - schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and .. function:: schurfact!(A) - :: - - schurfact!(A) - Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See ``schurfact()`` -.. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] +.. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - :: - - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See ``schurfact()`` -.. function:: ordschur(Q, T, select) -> Schur +.. function:: ordschur(GS, select) -> GeneralizedSchur - :: - - ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. function:: ordschur!(Q, T, select) -> Schur +.. function:: ordschur!(GS, select) -> GeneralizedSchur - :: - - ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See -.. function:: ordschur(S, select) -> Schur +.. function:: ordschur(GS, select) -> GeneralizedSchur - :: - - ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. function:: ordschur!(S, select) -> Schur +.. function:: ordschur!(GS, select) -> GeneralizedSchur - :: - - ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See .. function:: schurfact(A, B) -> GeneralizedSchur - :: - - schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and -.. function:: schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] +.. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - :: - - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See ``schurfact()`` -.. function:: ordschur(S, T, Q, Z, select) -> GeneralizedSchur +.. function:: ordschur(GS, select) -> GeneralizedSchur - :: - - ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. function:: ordschur!(S, T, Q, Z, select) -> GeneralizedSchur +.. function:: ordschur!(GS, select) -> GeneralizedSchur - :: - - ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See .. function:: ordschur(GS, select) -> GeneralizedSchur - :: - - ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. .. function:: ordschur!(GS, select) -> GeneralizedSchur - :: - - ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See -.. function:: svdfact(A, [thin=true]) -> SVD +.. function:: svdfact(A, B) -> GeneralizedSVD - :: - - svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. -.. function:: svdfact!(A, [thin=true]) -> SVD +.. function:: svdfact!(A[, thin=true]) -> SVD - :: - - svdfact!(A[, thin=true]) -> SVD - overwriting the input A, instead of creating a copy. If ``thin`` is to produce a thin decomposition. -.. function:: svd(A, [thin=true]) -> U, S, V +.. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - :: - - svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. -.. function:: svdvals(A) +.. function:: svdvals(A, B) - :: - - svdvals(A, B) - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. .. function:: svdvals!(A) - :: - - svdvals!(A) - Returns the singular values of ``A``, while saving space by overwriting the input. .. function:: svdfact(A, B) -> GeneralizedSVD - :: - - svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - :: - - svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. .. function:: svdvals(A, B) - :: - - svdvals(A, B) - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. -.. function:: triu(M) +.. function:: triu(M, k) - :: - - triu(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. .. function:: triu(M, k) - :: - - triu(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. -.. function:: triu!(M) +.. function:: triu!(M, k) - :: - - triu!(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. .. function:: triu!(M, k) - :: - - triu!(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. -.. function:: tril(M) +.. function:: tril(M, k) - :: - - tril(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. .. function:: tril(M, k) - :: - - tril(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. -.. function:: tril!(M) +.. function:: tril!(M, k) - :: - - tril!(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. .. function:: tril!(M, k) - :: - - tril!(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. .. function:: diagind(M[, k]) - :: - - diagind(M[, k]) - A ``Range`` giving the indices of the ``k``th diagonal of the matrix ``M``. .. function:: diag(M[, k]) - :: - - diag(M[, k]) - The ``k``th diagonal of a matrix, as a vector. Use ``diagm`` to construct a diagonal matrix. .. function:: diagm(v[, k]) - :: - - diagm(v[, k]) - Construct a diagonal matrix and place ``v`` on the ``k``th diagonal. -.. function:: scale(A, b) +.. function:: scale(b, A) - :: - - scale(b, A) - Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. .. function:: scale(b, A) - :: - - scale(b, A) - Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. -.. function:: scale!(A, b) +.. function:: scale!(b, A) - :: - - scale!(b, A) - Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. .. function:: scale!(b, A) - :: - - scale!(b, A) - Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. .. function:: Tridiagonal(dl, d, du) - :: - - Tridiagonal(dl, d, du) - Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. .. function:: Bidiagonal(dv, ev, isupper) - :: - - Bidiagonal(dv, ev, isupper) - Constructs an upper (``isupper=true``) or lower (``isupper=false``) bidiagonal matrix using the given diagonal (``dv``) and off- diagonal (``ev``) vectors. The result is of type ``Bidiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with ``full()``. .. function:: SymTridiagonal(d, du) - :: - - SymTridiagonal(d, du) - Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. .. function:: rank(M) - :: - - rank(M) - Compute the rank of a matrix. -.. function:: norm(A, [p]) +.. function:: norm(A[, p]) - :: - - norm(A[, p]) - Compute the ``p``-norm of a vector or the operator norm of a matrix For vectors, ``p`` can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, ``norm(A, Inf)`` returns the largest value in For matrices, valid values of ``p`` are ``1``, ``2``, or ``Inf``. implemented.) Use ``vecnorm()`` to compute the Frobenius norm. -.. function:: vecnorm(A, [p]) +.. function:: vecnorm(A[, p]) - :: - - vecnorm(A[, p]) - For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``-norm (defaulting to ``p=2``) as if For example, if ``A`` is a matrix and ``p=2``, then this is equivalent to the Frobenius norm. -.. function:: cond(M, [p]) +.. function:: cond(M[, p]) - :: - - cond(M[, p]) - Condition number of the matrix ``M``, computed using the operator -.. function:: condskeel(M, [x, p]) +.. function:: condskeel(M[, x, p]) - :: - - condskeel(M[, x, p]) - Skeel condition number \kappa_S of the matrix ``M``, optionally with respect to the vector ``x``, as computed using the operator values for ``p`` are ``1``, ``2``, or ``Inf``. This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. .. function:: trace(M) - :: - - trace(M) - Matrix trace .. function:: det(M) - :: - - det(M) - Matrix determinant .. function:: logdet(M) - :: - - logdet(M) - Log of matrix determinant. Equivalent to ``log(det(M))``, but may provide increased accuracy and/or speed. @@ -759,235 +435,131 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: inv(M) - :: - - inv(M) - Matrix inverse .. function:: pinv(M[, tol]) - :: - - pinv(M[, tol]) - Computes the Moore-Penrose pseudoinverse. For matrices ``M`` with floating point elements, it is convenient to compute the pseudoinverse by inverting only singular values above a given threshold, ``tol``. The optimal choice of ``tol`` varies both with the value of ``M`` and the intended application of the pseudoinverse. The default value of ``tol`` is essentially machine epsilon for the real part of a matrix element multiplied by the larger matrix dimension. For inverting dense ill- conditioned matrices in a least-squares sense, ``tol = sqrt(eps(real(float(one(eltype(M))))))`` is recommended. For more information, see [8859], [B96], [S84], [KY88]. .. function:: nullspace(M) - :: - - nullspace(M) - Basis for nullspace of ``M``. .. function:: repmat(A, n, m) - :: - - repmat(A, n, m) - Construct a matrix by repeating the given matrix ``n`` times in dimension 1 and ``m`` times in dimension 2. .. function:: repeat(A, inner = Int[], outer = Int[]) - :: - - repeat(A, inner = Int[], outer = Int[]) - Construct an array by repeating the entries of ``A``. The i-th element of ``inner`` specifies the number of times that the individual entries of the i-th dimension of ``A`` should be repeated. The i-th element of ``outer`` specifies the number of times that a slice along the i-th dimension of ``A`` should be repeated. .. function:: kron(A, B) - :: - - kron(A, B) - Kronecker tensor product of two vectors or two matrices. .. function:: blkdiag(A...) - :: - - blkdiag(A...) - Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. -.. function:: linreg(x, y) -> [a; b] +.. function:: linreg(x, y, w) - :: - - linreg(x, y, w) - Weighted least-squares linear regression. .. function:: linreg(x, y, w) - :: - - linreg(x, y, w) - Weighted least-squares linear regression. .. function:: expm(A) - :: - - expm(A) - Matrix exponential. .. function:: lyap(A, C) - :: - - lyap(A, C) - Computes the solution ``X`` to the continuous Lyapunov equation part and no two eigenvalues are negative complex conjugates of each other. .. function:: sylvester(A, B, C) - :: - - sylvester(A, B, C) - Computes the solution ``X`` to the Sylvester equation `AX + XB + C .. function:: issym(A) -> Bool - :: - - issym(A) -> Bool - Test whether a matrix is symmetric. .. function:: isposdef(A) -> Bool - :: - - isposdef(A) -> Bool - Test whether a matrix is positive definite. .. function:: isposdef!(A) -> Bool - :: - - isposdef!(A) -> Bool - Test whether a matrix is positive definite, overwriting ``A`` in the processes. .. function:: istril(A) -> Bool - :: - - istril(A) -> Bool - Test whether a matrix is lower triangular. .. function:: istriu(A) -> Bool - :: - - istriu(A) -> Bool - Test whether a matrix is upper triangular. .. function:: isdiag(A) -> Bool - :: - - isdiag(A) -> Bool - Test whether a matrix is diagonal. .. function:: ishermitian(A) -> Bool - :: - - ishermitian(A) -> Bool - Test whether a matrix is Hermitian. .. function:: transpose(A) - :: - - transpose(A) - The transposition operator (``.'``). -.. function:: transpose!(dest,src) +.. function:: transpose!(dest, src) - :: - - transpose!(dest, src) - Transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. .. function:: ctranspose(A) - :: - - ctranspose(A) - The conjugate transposition operator (``'``). -.. function:: ctranspose!(dest,src) +.. function:: ctranspose!(dest, src) - :: - - ctranspose!(dest, src) - Conjugate transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. -.. function:: eigs(A, [B,]; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0,))) -> (d,[v,],nconv,niter,nmult,resid) +.. function:: eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - :: - - eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - Computes eigenvalues ``d`` of ``A`` using Lanczos or Arnoldi iterations for real symmetric or general nonsymmetric matrices respectively. If ``B`` is provided, the generalized eigenproblem is solved. The following keyword arguments are supported: corresponding Ritz vectors ``v`` (only if ``ritzvec=true``), the number of converged eigenvalues ``nconv``, the number of iterations Note: The ``sigma`` and ``which`` keywords interact: the .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - :: - - svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - Lanczos or Arnoldi iterations. Uses ``eigs()`` underneath. Inputs are: .. function:: peakflops(n; parallel=false) - :: - - peakflops(n; parallel=false) - double precision ``Base.LinAlg.BLAS.gemm!()``. By default, if no arguments are specified, it multiplies a matrix of size ``n x n``, where ``n = 2000``. If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with ``blas_set_num_threads(n)``. If the keyword argument ``parallel`` is set to ``true``, flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument ``n`` still refers to the size of the problem that is solved on each processor. @@ -1007,388 +579,216 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: dot(n, X, incx, Y, incy) - :: - - dot(n, X, incx, Y, incy) - Dot product of two vectors consisting of ``n`` elements of array stride ``incy``. .. function:: dotu(n, X, incx, Y, incy) - :: - - dotu(n, X, incx, Y, incy) - Dot function for two complex vectors. .. function:: dotc(n, X, incx, U, incy) - :: - - dotc(n, X, incx, U, incy) - Dot function for two complex vectors conjugating the first vector. .. function:: blascopy!(n, X, incx, Y, incy) - :: - - blascopy!(n, X, incx, Y, incy) - Copy ``n`` elements of array ``X`` with stride ``incx`` to array .. function:: nrm2(n, X, incx) - :: - - nrm2(n, X, incx) - 2-norm of a vector consisting of ``n`` elements of array ``X`` with stride ``incx``. .. function:: asum(n, X, incx) - :: - - asum(n, X, incx) - sum of the absolute values of the first ``n`` elements of array .. function:: axpy!(a, X, Y) - :: - - axpy!(a, X, Y) - Overwrite ``Y`` with ``a*X + Y``. Returns ``Y``. .. function:: scal!(n, a, X, incx) - :: - - scal!(n, a, X, incx) - Overwrite ``X`` with ``a*X``. Returns ``X``. .. function:: scal(n, a, X, incx) - :: - - scal(n, a, X, incx) - Returns ``a*X``. .. function:: ger!(alpha, x, y, A) - :: - - ger!(alpha, x, y, A) - Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as .. function:: syr!(uplo, alpha, x, A) - :: - - syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix ``A`` with vector ``x`` as .. function:: syrk!(uplo, trans, alpha, A, beta, C) - :: - - syrk!(uplo, trans, alpha, A, beta, C) - Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. .. function:: syrk(uplo, trans, alpha, A) - :: - - syrk(uplo, trans, alpha, A) - Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``, according to ``trans`` ('N' or 'T'). .. function:: her!(uplo, alpha, x, A) - :: - - her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When lower triangle). Returns ``A``. .. function:: herk!(uplo, trans, alpha, A, beta, C) - :: - - herk!(uplo, trans, alpha, A, beta, C) - Methods for complex arrays only. Rank-k update of the Hermitian matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. .. function:: herk(uplo, trans, alpha, A) - :: - - herk(uplo, trans, alpha, A) - Methods for complex arrays only. Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of .. function:: gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - :: - - gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - Update vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'*x + beta*y`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension ``m`` by ``size(A,2)`` with updated ``y``. .. function:: gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - :: - - gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - Returns ``alpha*A*x`` or ``alpha*A'*x`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension diagonals. .. function:: sbmv!(uplo, k, alpha, A, x, beta, y) - :: - - sbmv!(uplo, k, alpha, A, x, beta, y) - Update vector ``y`` as ``alpha*A*x + beta*y`` where ``A`` is a a symmetric band matrix of order ``size(A,2)`` with ``k`` super- diagonals stored in the argument ``A``. The storage layout for http://www.netlib.org/lapack/explore-html/. Returns the updated ``y``. -.. function:: sbmv(uplo, k, alpha, A, x) +.. function:: sbmv(uplo, k, A, x) - :: - - sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of order .. function:: sbmv(uplo, k, A, x) - :: - - sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of order .. function:: gemm!(tA, tB, alpha, A, B, beta, C) - :: - - gemm!(tA, tB, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. Returns the updated ``C``. -.. function:: gemm(tA, tB, alpha, A, B) +.. function:: gemm(tA, tB, A, B) - :: - - gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants according to ``tA`` .. function:: gemm(tA, tB, A, B) - :: - - gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants according to ``tA`` .. function:: gemv!(tA, alpha, A, x, beta, y) - :: - - gemv!(tA, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``). Returns the updated -.. function:: gemv(tA, alpha, A, x) +.. function:: gemv(tA, A, x) - :: - - gemv(tA, A, x) - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). .. function:: gemv(tA, A, x) - :: - - gemv(tA, A, x) - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). .. function:: symm!(side, ul, alpha, A, B, beta, C) - :: - - symm!(side, ul, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` according to ``side``. ``A`` is assumed to be symmetric. Only the -.. function:: symm(side, ul, alpha, A, B) +.. function:: symm(tA, tB, alpha, A, B) - :: - - symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants according to -.. function:: symm(side, ul, A, B) +.. function:: symm(tA, tB, alpha, A, B) - :: - - symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants according to .. function:: symm(tA, tB, alpha, A, B) - :: - - symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants according to .. function:: symv!(ul, alpha, A, x, beta, y) - :: - - symv!(ul, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. Returns the updated ``y``. -.. function:: symv(ul, alpha, A, x) +.. function:: symv(ul, A, x) - :: - - symv(ul, A, x) - Returns ``A*x``. ``A`` is assumed to be symmetric. Only the .. function:: symv(ul, A, x) - :: - - symv(ul, A, x) - Returns ``A*x``. ``A`` is assumed to be symmetric. Only the .. function:: trmm!(side, ul, tA, dA, alpha, A, B) - :: - - trmm!(side, ul, tA, dA, alpha, A, B) - Update ``B`` as ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``B``. .. function:: trmm(side, ul, tA, dA, alpha, A, B) - :: - - trmm(side, ul, tA, dA, alpha, A, B) - Returns ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). .. function:: trsm!(side, ul, tA, dA, alpha, A, B) - :: - - trsm!(side, ul, tA, dA, alpha, A, B) - Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and ``tA`` (transpose A). Only the ``ul`` triangle of diagonal is assumed to be all ones). Returns the updated ``B``. .. function:: trsm(side, ul, tA, dA, alpha, A, B) - :: - - trsm(side, ul, tA, dA, alpha, A, B) - Returns the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and assumed to be all ones). .. function:: trmv!(side, ul, tA, dA, alpha, A, b) - :: - - trmv!(side, ul, tA, dA, alpha, A, b) - Update ``b`` as ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``b``. .. function:: trmv(side, ul, tA, dA, alpha, A, b) - :: - - trmv(side, ul, tA, dA, alpha, A, b) - Returns ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). .. function:: trsv!(ul, tA, dA, A, b) - :: - - trsv!(ul, tA, dA, A, b) - Overwrite ``b`` with the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` triangular (the diagonal is assumed to be all ones). Returns the updated ``b``. .. function:: trsv(ul, tA, dA, A, b) - :: - - trsv(ul, tA, dA, A, b) - Returns the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` (triangle of diagonal is assumed to be all ones). .. function:: blas_set_num_threads(n) - :: - - blas_set_num_threads(n) - Set the number of threads the BLAS library should use. diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index ff47749a1a9ec..e58631839972e 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -9,52 +9,32 @@ Mathematical Operators ---------------------- -.. function:: -(x) +.. function:: -(x, y) - :: - - -(x, y) - Subtraction operator. .. _+: .. function:: +(x, y...) - :: - - +(x, y...) - Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. ``+(x, y, z, ...)``. .. _-: .. function:: -(x, y) - :: - - -(x, y) - Subtraction operator. .. _*: -.. function:: *(x, y...) +.. function:: *(s, t) - :: - - *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. .. _/: .. function:: /(x, y) - :: - - /(x, y) - Right division operator: multiplication of ``x`` by the inverse of arguments. @@ -65,52 +45,32 @@ Mathematical Operators Gives floating-point results for integer arguments. .. _^: -.. function:: ^(x, y) +.. function:: ^(s, n) - :: - - ^(s, n) - Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. .. _.+: .. function:: .+(x, y) - :: - - .+(x, y) - Element-wise addition operator. .. _.-: .. function:: .-(x, y) - :: - - .-(x, y) - Element-wise subtraction operator. .. _.*: .. function:: .*(x, y) - :: - - .*(x, y) - Element-wise multiplication operator. .. _./: .. function:: ./(x, y) - :: - - ./(x, y) - Element-wise right division operator. @@ -122,185 +82,105 @@ Mathematical Operators .. _.^: .. function:: .^(x, y) - :: - - .^(x, y) - Element-wise exponentiation operator. .. function:: fma(x, y, z) - :: - - fma(x, y, z) - Computes ``x*y+z`` without rounding the intermediate result algorithms. See ``muladd``. .. function:: muladd(x, y, z) - :: - - muladd(x, y, z) - Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``, or to .. function:: div(x, y) - :: - - div(x, y) - The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. .. function:: fld(x, y) - :: - - fld(x, y) - Largest integer less than or equal to ``x/y``. .. function:: cld(x, y) - :: - - cld(x, y) - Smallest integer larger than or equal to ``x/y``. .. function:: mod(x, y) - :: - - mod(x, y) - Modulus after division, returning in the range [0,``y``), if ``y`` is positive, or (``y``,0] if ``y`` is negative. .. function:: mod2pi(x) - :: - - mod2pi(x) - Modulus after division by 2pi, returning in the range [0,2pi). This function computes a floating point representation of the modulus after division by numerically exact 2pi, and is therefore not exactly the same as mod(x,2pi), which would compute the modulus of x relative to division by the floating-point number 2pi. .. function:: rem(x, y) - :: - - rem(x, y) - Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than ``y``. This value is always exact. .. function:: divrem(x, y) - :: - - divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to .. function:: fldmod(x, y) - :: - - fldmod(x, y) - The floored quotient and modulus after division. Equivalent to -.. function:: mod1(x,m) +.. function:: mod1(x, m) - :: - - mod1(x, m) - Modulus after division, returning in the range (0,m] -.. function:: rem1(x,m) +.. function:: rem1(x, m) - :: - - rem1(x, m) - Remainder after division, returning in the range (0,m] .. _//: .. function:: //(num, den) - :: - - //(num, den) - Divide two integers or rational numbers, giving a ``Rational`` result. -.. function:: rationalize([Type=Int,] x; tol=eps(x)) +.. function:: rationalize([Type=Int], x; tol=eps(x)) - :: - - rationalize([Type=Int], x; tol=eps(x)) - Approximate floating point number ``x`` as a Rational number with components of the given integer type. The result will differ from .. function:: num(x) - :: - - num(x) - Numerator of the rational representation of ``x`` .. function:: den(x) - :: - - den(x) - Denominator of the rational representation of ``x`` .. _<<: .. function:: <<(x, n) - :: - - <<(x, n) - Left bit shift operator. .. _>>: .. function:: >>(x, n) - :: - - >>(x, n) - Right bit shift operator, preserving the sign of ``x``. .. _>>>: .. function:: >>>(x, n) - :: - - >>>(x, n) - Unsigned right bit shift operator. @@ -312,220 +192,132 @@ Mathematical Operators function ``colon``. The colon is also used in indexing to select whole dimensions. -.. function:: colon(start, [step], stop) +.. function:: colon(start[, step], stop) - :: - - colon(start[, step], stop) - Called by ``:`` syntax for constructing ranges. -.. function:: range(start, [step], length) +.. function:: range(start[, step], length) - :: - - range(start[, step], length) - Construct a range by length, given a starting value and optional step (defaults to 1). .. _==: .. function:: ==(x, y) - :: - - ==(x, y) - Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``. Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. Follows IEEE semantics for floating-point numbers. Collections should generally implement ``==`` by calling ``==`` recursively on all contents. New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible. .. _!=: .. function:: !=(x, y) - :: - - !=(x, y) - Not-equals comparison operator. Always gives the opposite answer as the fallback definition ``!=(x,y) = !(x==y)`` instead. .. _===: .. function:: ===(x, y) - :: - - ===(x, y) - See the ``is()`` operator .. _!==: .. function:: !==(x, y) - :: - - !==(x, y) - Equivalent to ``!is(x, y)`` .. _<: .. function:: <(x, y) - :: - - <(x, y) - Less-than comparison operator. New numeric types should implement this function for two arguments of the new type. Because of the behavior of floating-point NaN values, ``<`` implements a partial order. Types with a canonical partial order should implement ``<``, and types with a canonical total order should implement ``isless``. .. _<=: .. function:: <=(x, y) - :: - - <=(x, y) - Less-than-or-equals comparison operator. .. _>: .. function:: >(x, y) - :: - - >(x, y) - Greater-than comparison operator. Generally, new types should implement ``<`` instead of this function, and rely on the fallback definition ``>(x,y) = y=: .. function:: >=(x, y) - :: - - >=(x, y) - Greater-than-or-equals comparison operator. .. _.==: .. function:: .==(x, y) - :: - - .==(x, y) - Element-wise equality comparison operator. .. _.!=: .. function:: .!=(x, y) - :: - - .!=(x, y) - Element-wise not-equals comparison operator. .. _.<: .. function:: .<(x, y) - :: - - .<(x, y) - Element-wise less-than comparison operator. .. _.<=: .. function:: .<=(x, y) - :: - - .<=(x, y) - Element-wise less-than-or-equals comparison operator. .. _.>: .. function:: .>(x, y) - :: - - .>(x, y) - Element-wise greater-than comparison operator. .. _.>=: .. function:: .>=(x, y) - :: - - .>=(x, y) - Element-wise greater-than-or-equals comparison operator. -.. function:: cmp(x,y) +.. function:: cmp(x, y) - :: - - cmp(x, y) - Return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``, respectively. Uses the total order implemented by ``isless``. For floating-point numbers, uses ``<`` but throws an error for unordered arguments. .. _~: .. function:: ~(x) - :: - - ~(x) - Bitwise not .. _&: .. function:: &(x, y) - :: - - &(x, y) - Bitwise and .. _|: .. function:: |(x, y) - :: - - |(x, y) - Bitwise or .. _$: -.. function:: $(x, y) +.. function:: \$(x, y) - :: - - \$(x, y) - Bitwise exclusive or .. _!: .. function:: !(x) - :: - - !(x) - Boolean not @@ -539,174 +331,98 @@ Mathematical Operators Short-circuiting boolean or -.. function:: A_ldiv_Bc(a,b) +.. function:: A_ldiv_Bc(a, b) - :: - - A_ldiv_Bc(a, b) - Matrix operator A \ B^H -.. function:: A_ldiv_Bt(a,b) +.. function:: A_ldiv_Bt(a, b) - :: - - A_ldiv_Bt(a, b) - Matrix operator A \ B^T .. function:: A_mul_B!(Y, A, B) -> Y - :: - - A_mul_B!(Y, A, B) -> Y - Calculates the matrix-matrix or matrix-vector product *A B* and stores the result in *Y*, overwriting the existing value of *Y*. .. function:: A_mul_Bc(...) - :: - - A_mul_Bc(...) - Matrix operator A B^H .. function:: A_mul_Bt(...) - :: - - A_mul_Bt(...) - Matrix operator A B^T .. function:: A_rdiv_Bc(...) - :: - - A_rdiv_Bc(...) - Matrix operator A / B^H -.. function:: A_rdiv_Bt(a,b) +.. function:: A_rdiv_Bt(a, b) - :: - - A_rdiv_Bt(a, b) - Matrix operator A / B^T .. function:: Ac_ldiv_B(...) - :: - - Ac_ldiv_B(...) - Matrix operator A^H \ B .. function:: Ac_ldiv_Bc(...) - :: - - Ac_ldiv_Bc(...) - Matrix operator A^H \ B^H .. function:: Ac_mul_B(...) - :: - - Ac_mul_B(...) - Matrix operator A^H B .. function:: Ac_mul_Bc(...) - :: - - Ac_mul_Bc(...) - Matrix operator A^H B^H -.. function:: Ac_rdiv_B(a,b) +.. function:: Ac_rdiv_B(a, b) - :: - - Ac_rdiv_B(a, b) - Matrix operator A^H / B -.. function:: Ac_rdiv_Bc(a,b) +.. function:: Ac_rdiv_Bc(a, b) - :: - - Ac_rdiv_Bc(a, b) - Matrix operator A^H / B^H .. function:: At_ldiv_B(...) - :: - - At_ldiv_B(...) - Matrix operator A^T \ B .. function:: At_ldiv_Bt(...) - :: - - At_ldiv_Bt(...) - Matrix operator A^T \ B^T .. function:: At_mul_B(...) - :: - - At_mul_B(...) - Matrix operator A^T B .. function:: At_mul_Bt(...) - :: - - At_mul_Bt(...) - Matrix operator A^T B^T -.. function:: At_rdiv_B(a,b) +.. function:: At_rdiv_B(a, b) - :: - - At_rdiv_B(a, b) - Matrix operator A^T / B -.. function:: At_rdiv_Bt(a,b) +.. function:: At_rdiv_Bt(a, b) - :: - - At_rdiv_Bt(a, b) - Matrix operator A^T / B^T @@ -715,523 +431,291 @@ Mathematical Functions .. function:: isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - :: - - isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - Inexact equality comparison - behaves slightly different depending on types of input args: For default tolerance arguments, ``maxeps = max(eps(abs(x)), eps(abs(y)))``. .. function:: sin(x) - :: - - sin(x) - Compute sine of ``x``, where ``x`` is in radians .. function:: cos(x) - :: - - cos(x) - Compute cosine of ``x``, where ``x`` is in radians .. function:: tan(x) - :: - - tan(x) - Compute tangent of ``x``, where ``x`` is in radians .. function:: sind(x) - :: - - sind(x) - Compute sine of ``x``, where ``x`` is in degrees .. function:: cosd(x) - :: - - cosd(x) - Compute cosine of ``x``, where ``x`` is in degrees .. function:: tand(x) - :: - - tand(x) - Compute tangent of ``x``, where ``x`` is in degrees .. function:: sinpi(x) - :: - - sinpi(x) - Compute \sin(\pi x) more accurately than ``sin(pi*x)``, especially for large ``x``. .. function:: cospi(x) - :: - - cospi(x) - Compute \cos(\pi x) more accurately than ``cos(pi*x)``, especially for large ``x``. .. function:: sinh(x) - :: - - sinh(x) - Compute hyperbolic sine of ``x`` .. function:: cosh(x) - :: - - cosh(x) - Compute hyperbolic cosine of ``x`` .. function:: tanh(x) - :: - - tanh(x) - Compute hyperbolic tangent of ``x`` .. function:: asin(x) - :: - - asin(x) - Compute the inverse sine of ``x``, where the output is in radians .. function:: acos(x) - :: - - acos(x) - Compute the inverse cosine of ``x``, where the output is in radians .. function:: atan(x) - :: - - atan(x) - Compute the inverse tangent of ``x``, where the output is in radians .. function:: atan2(y, x) - :: - - atan2(y, x) - Compute the inverse tangent of ``y/x``, using the signs of both .. function:: asind(x) - :: - - asind(x) - Compute the inverse sine of ``x``, where the output is in degrees .. function:: acosd(x) - :: - - acosd(x) - Compute the inverse cosine of ``x``, where the output is in degrees .. function:: atand(x) - :: - - atand(x) - Compute the inverse tangent of ``x``, where the output is in degrees .. function:: sec(x) - :: - - sec(x) - Compute the secant of ``x``, where ``x`` is in radians .. function:: csc(x) - :: - - csc(x) - Compute the cosecant of ``x``, where ``x`` is in radians .. function:: cot(x) - :: - - cot(x) - Compute the cotangent of ``x``, where ``x`` is in radians .. function:: secd(x) - :: - - secd(x) - Compute the secant of ``x``, where ``x`` is in degrees .. function:: cscd(x) - :: - - cscd(x) - Compute the cosecant of ``x``, where ``x`` is in degrees .. function:: cotd(x) - :: - - cotd(x) - Compute the cotangent of ``x``, where ``x`` is in degrees .. function:: asec(x) - :: - - asec(x) - Compute the inverse secant of ``x``, where the output is in radians .. function:: acsc(x) - :: - - acsc(x) - Compute the inverse cosecant of ``x``, where the output is in radians .. function:: acot(x) - :: - - acot(x) - Compute the inverse cotangent of ``x``, where the output is in radians .. function:: asecd(x) - :: - - asecd(x) - Compute the inverse secant of ``x``, where the output is in degrees .. function:: acscd(x) - :: - - acscd(x) - Compute the inverse cosecant of ``x``, where the output is in degrees .. function:: acotd(x) - :: - - acotd(x) - Compute the inverse cotangent of ``x``, where the output is in degrees .. function:: sech(x) - :: - - sech(x) - Compute the hyperbolic secant of ``x`` .. function:: csch(x) - :: - - csch(x) - Compute the hyperbolic cosecant of ``x`` .. function:: coth(x) - :: - - coth(x) - Compute the hyperbolic cotangent of ``x`` .. function:: asinh(x) - :: - - asinh(x) - Compute the inverse hyperbolic sine of ``x`` .. function:: acosh(x) - :: - - acosh(x) - Compute the inverse hyperbolic cosine of ``x`` .. function:: atanh(x) - :: - - atanh(x) - Compute the inverse hyperbolic tangent of ``x`` .. function:: asech(x) - :: - - asech(x) - Compute the inverse hyperbolic secant of ``x`` .. function:: acsch(x) - :: - - acsch(x) - Compute the inverse hyperbolic cosecant of ``x`` .. function:: acoth(x) - :: - - acoth(x) - Compute the inverse hyperbolic cotangent of ``x`` .. function:: sinc(x) - :: - - sinc(x) - Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. .. function:: cosc(x) - :: - - cosc(x) - Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq 0, and 0 if x = 0. This is the derivative of ``sinc(x)``. .. function:: deg2rad(x) - :: - - deg2rad(x) - Convert ``x`` from degrees to radians .. function:: rad2deg(x) - :: - - rad2deg(x) - Convert ``x`` from radians to degrees .. function:: hypot(x, y) - :: - - hypot(x, y) - Compute the \sqrt{x^2+y^2} avoiding overflow and underflow -.. function:: log(x) +.. function:: log(b, x) - :: - - log(b, x) - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. -.. function:: log(b,x) +.. function:: log(b, x) - :: - - log(b, x) - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log2(x) - :: - - log2(x) - Compute the logarithm of ``x`` to base 2. Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log10(x) - :: - - log10(x) - Compute the logarithm of ``x`` to base 10. Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log1p(x) - :: - - log1p(x) - Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. .. function:: frexp(val) - :: - - frexp(val) - Return ``(x,exp)`` such that ``x`` has a magnitude in the interval .. function:: exp(x) - :: - - exp(x) - Compute e^x .. function:: exp2(x) - :: - - exp2(x) - Compute 2^x .. function:: exp10(x) - :: - - exp10(x) - Compute 10^x .. function:: ldexp(x, n) - :: - - ldexp(x, n) - Compute x \times 2^n .. function:: modf(x) - :: - - modf(x) - Return a tuple (fpart,ipart) of the fractional and integral parts of a number. Both parts have the same sign as the argument. .. function:: expm1(x) - :: - - expm1(x) - - Accurately compute e^x-1 + Accurately compute e^x-1 -.. function:: round([T,] x, [digits, [base]], [r::RoundingMode]) +.. function:: round(z, RoundingModeReal, RoundingModeImaginary) - :: - - round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. @@ -1302,778 +786,433 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) - :: - - round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. -.. function:: ceil([T,] x, [digits, [base]]) +.. function:: ceil([T], x[, digits[, base]]) - :: - - ceil([T], x[, digits[, base]]) -.. function:: floor([T,] x, [digits, [base]]) +.. function:: floor([T], x[, digits[, base]]) - :: - - floor([T], x[, digits[, base]]) -.. function:: trunc([T,] x, [digits, [base]]) +.. function:: trunc([T], x[, digits[, base]]) - :: - - trunc([T], x[, digits[, base]]) .. function:: unsafe_trunc(T, x) - :: - - unsafe_trunc(T, x) - value is not representable by ``T``, an arbitrary value will be returned. -.. function:: signif(x, digits, [base]) +.. function:: signif(x, digits[, base]) - :: - - signif(x, digits[, base]) - Rounds (in the sense of ``round``) ``x`` so that there are representation, default 10. E.g., ``signif(123.456, 2)`` is .. function:: min(x, y, ...) - :: - - min(x, y, ...) - Return the minimum of the arguments. Operates elementwise over arrays. .. function:: max(x, y, ...) - :: - - max(x, y, ...) - Return the maximum of the arguments. Operates elementwise over arrays. .. function:: minmax(x, y) - :: - - minmax(x, y) - Return ``(min(x,y), max(x,y))``. See also: ``extrema()`` that returns ``(minimum(x), maximum(x))`` .. function:: clamp(x, lo, hi) - :: - - clamp(x, lo, hi) - Return x if ``lo <= x <= hi``. If ``x < lo``, return ``lo``. If ``x Operates elementwise over `x`` if it is an array. .. function:: abs(x) - :: - - abs(x) - Absolute value of ``x`` .. function:: abs2(x) - :: - - abs2(x) - Squared absolute value of ``x`` .. function:: copysign(x, y) - :: - - copysign(x, y) - Return ``x`` such that it has the same sign as ``y`` .. function:: sign(x) - :: - - sign(x) - Return ``+1`` if ``x`` is positive, ``0`` if ``x == 0``, and ``-1`` if ``x`` is negative. .. function:: signbit(x) - :: - - signbit(x) - Returns ``true`` if the value of the sign of ``x`` is negative, otherwise ``false``. .. function:: flipsign(x, y) - :: - - flipsign(x, y) - Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``. .. function:: sqrt(x) - :: - - sqrt(x) - Return \sqrt{x}. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. The prefix operator ``√`` is equivalent to ``sqrt``. .. function:: isqrt(n) - :: - - isqrt(n) - Integer square root: the largest integer ``m`` such that ``m*m <= n``. .. function:: cbrt(x) - :: - - cbrt(x) - Return x^{1/3}. The prefix operator ``∛`` is equivalent to .. function:: erf(x) - :: - - erf(x) - Compute the error function of ``x``, defined by .. function:: erfc(x) - :: - - erfc(x) - Compute the complementary error function of ``x``, defined by 1 - .. function:: erfcx(x) - :: - - erfcx(x) - Compute the scaled complementary error function of ``x``, defined by e^{x^2} \operatorname{erfc}(x). Note also that .. function:: erfi(x) - :: - - erfi(x) - Compute the imaginary error function of ``x``, defined by -i .. function:: dawson(x) - :: - - dawson(x) - Compute the Dawson function (scaled imaginary error function) of .. function:: erfinv(x) - :: - - erfinv(x) - Compute the inverse error function of a real ``x``, defined by .. function:: erfcinv(x) - :: - - erfcinv(x) - Compute the inverse error complementary function of a real ``x``, defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. .. function:: real(z) - :: - - real(z) - Return the real part of the complex number ``z`` .. function:: imag(z) - :: - - imag(z) - Return the imaginary part of the complex number ``z`` .. function:: reim(z) - :: - - reim(z) - Return both the real and imaginary parts of the complex number .. function:: conj(z) - :: - - conj(z) - Compute the complex conjugate of a complex number ``z`` .. function:: angle(z) - :: - - angle(z) - Compute the phase angle in radians of a complex number ``z`` .. function:: cis(z) - :: - - cis(z) - Return \exp(iz). -.. function:: binomial(n,k) +.. function:: binomial(n, k) - :: - - binomial(n, k) - Number of ways to choose ``k`` out of ``n`` items -.. function:: factorial(n) +.. function:: factorial(n, k) - :: - - factorial(n, k) - Compute ``factorial(n)/factorial(k)`` -.. function:: factorial(n,k) +.. function:: factorial(n, k) - :: - - factorial(n, k) - Compute ``factorial(n)/factorial(k)`` .. function:: factor(n) -> Dict - :: - - factor(n) -> Dict - Compute the prime factorization of an integer ``n``. Returns a dictionary. The keys of the dictionary correspond to the factors, and hence are of the same type as ``n``. The value associated with each key indicates the number of times the factor appears in the factorization. -.. function:: gcd(x,y) +.. function:: gcd(x, y) - :: - - gcd(x, y) - Greatest common (positive) divisor (or zero if x and y are both zero). -.. function:: lcm(x,y) +.. function:: lcm(x, y) - :: - - lcm(x, y) - Least common (non-negative) multiple. -.. function:: gcdx(x,y) +.. function:: gcdx(x, y) - :: - - gcdx(x, y) - Computes the greatest common (positive) divisor of ``x`` and ``y`` and their Bézout coefficients, i.e. the integer coefficients ``u`` and ``v`` that satisfy ux+vy = d = gcd(x,y). Note: Bézout coefficients are *not* uniquely defined. ``gcdx`` .. function:: ispow2(n) -> Bool - :: - - ispow2(n) -> Bool - Test whether ``n`` is a power of two .. function:: nextpow2(n) - :: - - nextpow2(n) - The smallest power of two not less than ``n``. Returns 0 for .. function:: prevpow2(n) - :: - - prevpow2(n) - The largest power of two not greater than ``n``. Returns 0 for .. function:: nextpow(a, x) - :: - - nextpow(a, x) - The smallest ``a^n`` not less than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must be greater than 0. .. function:: prevpow(a, x) - :: - - prevpow(a, x) - The largest ``a^n`` not greater than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must not be less than 1. -.. function:: nextprod([k_1,k_2,...], n) +.. function:: nextprod([k_1, k_2, ...], n) - :: - - nextprod([k_1, k_2, ...], n) - Next integer not less than ``n`` that can be written as \prod k_i^{p_i} for integers p_1, p_2, etc. -.. function:: prevprod([k_1,k_2,...], n) +.. function:: prevprod([k_1, k_2, ...], n) - :: - - prevprod([k_1, k_2, ...], n) - Previous integer not greater than ``n`` that can be written as -.. function:: invmod(x,m) +.. function:: invmod(x, m) - :: - - invmod(x, m) - Take the inverse of ``x`` modulo ``m``: ``y`` such that xy = 1 .. function:: powermod(x, p, m) - :: - - powermod(x, p, m) - Compute x^p \pmod m .. function:: gamma(x) - :: - - gamma(x) - Compute the gamma function of ``x`` .. function:: lgamma(x) - :: - - lgamma(x) - Compute the logarithm of the absolute value of ``gamma()`` for logarithm of ``gamma(x)``. .. function:: lfact(x) - :: - - lfact(x) - Compute the logarithmic factorial of ``x`` .. function:: digamma(x) - :: - - digamma(x) - Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(x)``) .. function:: invdigamma(x) - :: - - invdigamma(x) - Compute the inverse digamma function of ``x``. .. function:: trigamma(x) - :: - - trigamma(x) - Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``) .. function:: polygamma(m, x) - :: - - polygamma(m, x) - Compute the polygamma function of order ``m`` of argument ``x`` -.. function:: airy(k,x) +.. function:: airy(k, x) - :: - - airy(k, x) - kth derivative of the Airy function \operatorname{Ai}(x). .. function:: airyai(x) - :: - - airyai(x) - Airy function \operatorname{Ai}(x). .. function:: airyprime(x) - :: - - airyprime(x) - Airy function derivative \operatorname{Ai}'(x). .. function:: airyaiprime(x) - :: - - airyaiprime(x) - Airy function derivative \operatorname{Ai}'(x). .. function:: airybi(x) - :: - - airybi(x) - Airy function \operatorname{Bi}(x). .. function:: airybiprime(x) - :: - - airybiprime(x) - Airy function derivative \operatorname{Bi}'(x). -.. function:: airyx(k,x) +.. function:: airyx(k, x) - :: - - airyx(k, x) - scaled kth derivative of the Airy function, return k == 1``, and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} k == 3``. .. function:: besselj0(x) - :: - - besselj0(x) - Bessel function of the first kind of order 0, J_0(x). .. function:: besselj1(x) - :: - - besselj1(x) - Bessel function of the first kind of order 1, J_1(x). .. function:: besselj(nu, x) - :: - - besselj(nu, x) - Bessel function of the first kind of order ``nu``, J_\nu(x). .. function:: besseljx(nu, x) - :: - - besseljx(nu, x) - Scaled Bessel function of the first kind of order ``nu``, J_\nu(x) e^{- | \operatorname{Im}(x) |}. .. function:: bessely0(x) - :: - - bessely0(x) - Bessel function of the second kind of order 0, Y_0(x). .. function:: bessely1(x) - :: - - bessely1(x) - Bessel function of the second kind of order 1, Y_1(x). .. function:: bessely(nu, x) - :: - - bessely(nu, x) - Bessel function of the second kind of order ``nu``, Y_\nu(x). .. function:: besselyx(nu, x) - :: - - besselyx(nu, x) - Scaled Bessel function of the second kind of order ``nu``, Y_\nu(x) e^{- | \operatorname{Im}(x) |}. .. function:: hankelh1(nu, x) - :: - - hankelh1(nu, x) - Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x). .. function:: hankelh1x(nu, x) - :: - - hankelh1x(nu, x) - Scaled Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x) e^{-x i}. .. function:: hankelh2(nu, x) - :: - - hankelh2(nu, x) - Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x). .. function:: hankelh2x(nu, x) - :: - - hankelh2x(nu, x) - Scaled Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x) e^{x i}. .. function:: besselh(nu, k, x) - :: - - besselh(nu, k, x) - Bessel function of the third kind of order ``nu`` (Hankel function). ``k`` is either 1 or 2, selecting ``hankelh1`` or .. function:: besseli(nu, x) - :: - - besseli(nu, x) - Modified Bessel function of the first kind of order ``nu``, I_\nu(x). .. function:: besselix(nu, x) - :: - - besselix(nu, x) - Scaled modified Bessel function of the first kind of order ``nu``, I_\nu(x) e^{- | \operatorname{Re}(x) |}. .. function:: besselk(nu, x) - :: - - besselk(nu, x) - Modified Bessel function of the second kind of order ``nu``, K_\nu(x). .. function:: besselkx(nu, x) - :: - - besselkx(nu, x) - Scaled modified Bessel function of the second kind of order ``nu``, K_\nu(x) e^x. .. function:: beta(x, y) - :: - - beta(x, y) - Euler integral of the first kind \operatorname{B}(x,y) = .. function:: lbeta(x, y) - :: - - lbeta(x, y) - Natural logarithm of the absolute value of the beta function .. function:: eta(x) - :: - - eta(x) - Dirichlet eta function \eta(s) = -.. function:: zeta(s) +.. function:: zeta(s, z) - :: - - zeta(s, z) - Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) .. function:: zeta(s, z) - :: - - zeta(s, z) - Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) .. function:: ndigits(n, b) - :: - - ndigits(n, b) - Compute the number of digits in number ``n`` written in base ``b``. .. function:: widemul(x, y) - :: - - widemul(x, y) - Multiply ``x`` and ``y``, giving the result as a larger type. .. function:: @evalpoly(z, c...) - :: - - @evalpoly(z, c...) - Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients ascending order by power of ``z``. This macro expands to efficient inline code that uses either Horner's method or, for complex ``z``, a more efficient Goertzel-like algorithm. @@ -2082,217 +1221,121 @@ Statistics .. function:: mean(v[, region]) - :: - - mean(v[, region]) - Compute the mean of whole array ``v``, or optionally along the dimensions in ``region``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. .. function:: mean!(r, v) - :: - - mean!(r, v) - Compute the mean of ``v`` over the singleton dimensions of ``r``, and write results to ``r``. .. function:: std(v[, region]) - :: - - std(v[, region]) - Compute the sample standard deviation of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the .. function:: stdm(v, m) - :: - - stdm(v, m) - Compute the sample standard deviation of a vector ``v`` with known mean ``m``. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: var(v[, region]) - :: - - var(v[, region]) - Compute the sample variance of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the .. function:: varm(v, m) - :: - - varm(v, m) - Compute the sample variance of a vector ``v`` with known mean computation. -.. function:: middle(x) +.. function:: middle(array) - :: - - middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. -.. function:: middle(x, y) +.. function:: middle(array) - :: - - middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. -.. function:: middle(range) +.. function:: middle(array) - :: - - middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. .. function:: middle(array) - :: - - middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. .. function:: median(v) - :: - - median(v) - Compute the median of a vector ``v``. ``NaN`` is returned if the data contains any ``NaN`` values. For applications requiring the handling of missing data, the ``DataArrays`` package is recommended. .. function:: median!(v) - :: - - median!(v) - Like ``median``, but may overwrite the input vector. -.. function:: hist(v[, n]) -> e, counts +.. function:: hist(v, e) -> e, counts - :: - - hist(v, e) -> e, counts - Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: hist(v, e) -> e, counts - :: - - hist(v, e) -> e, counts - Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: hist!(counts, v, e) -> e, counts - :: - - hist!(counts, v, e) -> e, counts - Compute the histogram of ``v``, using a vector/range ``e`` as the edges for the bins. This function writes the resultant counts to a pre-allocated array ``counts``. .. function:: hist2d(M, e1, e2) -> (edge1, edge2, counts) - :: - - hist2d(M, e1, e2) -> (edge1, edge2, counts) - Compute a ``2d histogram`` of a set of N points specified by N-by-2 matrix ``M``. Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as integer bin counts or vectors of bin edges. The result is a tuple of ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges used in the second dimension), and ``counts``, a histogram matrix of size .. function:: hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - :: - - hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - Compute a ``2d histogram`` with respect to the bins delimited by the edges given in ``e1`` and ``e2``. This function writes the results to a pre-allocated array ``counts``. .. function:: histrange(v, n) - :: - - histrange(v, n) - Compute *nice* bin ranges for the edges of a histogram of ``v``, using approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 multiplied by a power of 10. Note: Julia does not ignore .. function:: midpoints(e) - :: - - midpoints(e) - Compute the midpoints of the bins with edges ``e``. The result is a vector/range of length ``length(e) - 1``. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: quantile(v, p) - :: - - quantile(v, p) - Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: quantile(v, p) - :: - - quantile(v, p) - Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: quantile!(v, p) - :: - - quantile!(v, p) - Like ``quantile``, but overwrites the input vector. .. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - :: - - cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - Compute the Pearson covariance between the vector(s) in ``v1`` and This function accepts three keyword arguments: The size of the result depends on the size of ``v1`` and ``v2``. When both ``v1`` and ``v2`` are vectors, it returns the covariance between them as a scalar. When either one is a matrix, it returns a covariance matrix of size ``(n1, n2)``, where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and ``v2``, which depend on the setting of ``vardim``. Note: ``v2`` can be omitted, which indicates ``v2 = v1``. .. function:: cor(v1[, v2][, vardim=1, mean=nothing]) - :: - - cor(v1[, v2][, vardim=1, mean=nothing]) - Compute the Pearson correlation between the vector(s) in ``v1`` and Users can use the keyword argument ``vardim`` to specify the variable dimension, and ``mean`` to supply pre-computed mean values. @@ -2305,327 +1348,183 @@ implemented by calling functions from `FFTW FFTW. Higher performance may be obtained by experimenting with multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. -.. function:: fft(A [, dims]) +.. function:: fft(A[, dims]) - :: - - fft(A[, dims]) - Performs a multidimensional FFT of the array ``A``. The optional an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also A one-dimensional FFT computes the one-dimensional discrete Fourier transform (DFT) as defined by A multidimensional FFT simply performs this operation along each transformed dimension of ``A``. Higher performance is usually possible with multi-threading. Use processors. -.. function:: fft!(A [, dims]) +.. function:: fft!(A[, dims]) - :: - - fft!(A[, dims]) - Same as ``fft()``, but operates in-place on ``A``, which must be an array of complex floating-point numbers. -.. function:: ifft(A [, dims]) +.. function:: ifft(A[, dims]) - :: - - ifft(A[, dims]) - Multidimensional inverse FFT. A one-dimensional inverse FFT computes A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``. -.. function:: ifft!(A [, dims]) +.. function:: ifft!(A[, dims]) - :: - - ifft!(A[, dims]) - Same as ``ifft()``, but operates in-place on ``A``. -.. function:: bfft(A [, dims]) +.. function:: bfft(A[, dims]) - :: - - bfft(A[, dims]) - Similar to ``ifft()``, but computes an unnormalized inverse sizes of the transformed dimensions in order to obtain the inverse. scaling step, which in some applications can be combined with other computational steps elsewhere.) -.. function:: bfft!(A [, dims]) +.. function:: bfft!(A[, dims]) - :: - - bfft!(A[, dims]) - Same as ``bfft()``, but operates in-place on ``A``. -.. function:: plan_fft(A [, dims [, flags [, timelimit]]]) +.. function:: plan_fft(A[, dims[, flags[, timelimit]]]) - :: - - plan_fft(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized FFT along given dimensions (``dims``) of arrays matching the shape and type of ``A``. (The first two arguments have the same meaning as for ``fft()``.) Returns a function ``plan(A)`` that computes ``fft(A, dims)`` quickly. The ``flags`` argument is a bitwise-or of FFTW planner flags, defaulting to ``FFTW.ESTIMATE``. e.g. passing ``FFTW.MEASURE`` or benchmarking different possible FFT algorithms and picking the fastest one; see the FFTW manual for more information on planner flags. The optional ``timelimit`` argument specifies a rough upper bound on the allowed planning time, in seconds. Passing that operates in-place on its argument (which must be an array of complex floating-point numbers). ``plan_ifft()`` and so on are similar but produce plans that perform the equivalent of the inverse transforms ``ifft()`` and so on. -.. function:: plan_ifft(A [, dims [, flags [, timelimit]]]) +.. function:: plan_ifft(A[, dims[, flags[, timelimit]]]) - :: - - plan_ifft(A[, dims[, flags[, timelimit]]]) - Same as ``plan_fft()``, but produces a plan that performs inverse transforms ``ifft()``. -.. function:: plan_bfft(A [, dims [, flags [, timelimit]]]) +.. function:: plan_bfft(A[, dims[, flags[, timelimit]]]) - :: - - plan_bfft(A[, dims[, flags[, timelimit]]]) - Same as ``plan_fft()``, but produces a plan that performs an unnormalized backwards transform ``bfft()``. -.. function:: plan_fft!(A [, dims [, flags [, timelimit]]]) +.. function:: plan_fft!(A[, dims[, flags[, timelimit]]]) - :: - - plan_fft!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_fft()``, but operates in-place on ``A``. -.. function:: plan_ifft!(A [, dims [, flags [, timelimit]]]) +.. function:: plan_ifft!(A[, dims[, flags[, timelimit]]]) - :: - - plan_ifft!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_ifft()``, but operates in-place on ``A``. -.. function:: plan_bfft!(A [, dims [, flags [, timelimit]]]) +.. function:: plan_bfft!(A[, dims[, flags[, timelimit]]]) - :: - - plan_bfft!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_bfft()``, but operates in-place on ``A``. -.. function:: rfft(A [, dims]) +.. function:: rfft(A[, dims]) - :: - - rfft(A[, dims]) - Multidimensional FFT of a real array A, exploiting the fact that the transform has conjugate symmetry in order to save roughly half the computational time and storage costs compared with ``fft()``. If ``A`` has size ``(n_1, ..., n_d)``, the result has size The optional ``dims`` argument specifies an iterable subset of one or more dimensions of ``A`` to transform, similar to ``fft()``. Instead of (roughly) halving the first dimension of ``A`` in the result, the ``dims[1]`` dimension is (roughly) halved in the same way. -.. function:: irfft(A, d [, dims]) +.. function:: irfft(A, d[, dims]) - :: - - irfft(A, d[, dims]) - Inverse of ``rfft()``: for a complex array ``A``, gives the corresponding real array whose FFT yields ``A`` in the first half. As for ``rfft()``, ``dims`` is an optional subset of dimensions to transform, defaulting to ``1:ndims(A)``. floor(size(A,dims[1])/2)+1``. (This parameter cannot be inferred from `size(A)`` due to the possibility of rounding by the -.. function:: brfft(A, d [, dims]) +.. function:: brfft(A, d[, dims]) - :: - - brfft(A, d[, dims]) - Similar to ``irfft()`` but computes an unnormalized inverse transform (similar to ``bfft()``), which must be divided by the product of the sizes of the transformed dimensions (of the real output array) in order to obtain the inverse transform. -.. function:: plan_rfft(A [, dims [, flags [, timelimit]]]) +.. function:: plan_rfft(A[, dims[, flags[, timelimit]]]) - :: - - plan_rfft(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized real-input FFT, similar to ``plan_fft()`` except for ``rfft()`` instead of ``fft()``. The first two arguments, and the size of the transformed result, are the same as for ``rfft()``. -.. function:: plan_brfft(A, d [, dims [, flags [, timelimit]]]) +.. function:: plan_brfft(A, d[, dims[, flags[, timelimit]]]) - :: - - plan_brfft(A, d[, dims[, flags[, timelimit]]]) - Pre-plan an optimized real-input unnormalized transform, similar to first two arguments and the size of the transformed result, are the same as for ``brfft()``. -.. function:: plan_irfft(A, d [, dims [, flags [, timelimit]]]) +.. function:: plan_irfft(A, d[, dims[, flags[, timelimit]]]) - :: - - plan_irfft(A, d[, dims[, flags[, timelimit]]]) - Pre-plan an optimized inverse real-input FFT, similar to respectively. The first three arguments have the same meaning as for ``irfft()``. -.. function:: dct(A [, dims]) +.. function:: dct(A[, dims]) - :: - - dct(A[, dims]) - Performs a multidimensional type-II discrete cosine transform (DCT) of the array ``A``, using the unitary normalization of the DCT. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also ``plan_dct()`` for even greater efficiency. -.. function:: dct!(A [, dims]) +.. function:: dct!(A[, dims]) - :: - - dct!(A[, dims]) - Same as ``dct!()``, except that it operates in-place on ``A``, which must be an array of real or complex floating-point values. -.. function:: idct(A [, dims]) +.. function:: idct(A[, dims]) - :: - - idct(A[, dims]) - Computes the multidimensional inverse discrete cosine transform unitary normalization). The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see efficiency. -.. function:: idct!(A [, dims]) +.. function:: idct!(A[, dims]) - :: - - idct!(A[, dims]) - Same as ``idct!()``, but operates in-place on ``A``. -.. function:: plan_dct(A [, dims [, flags [, timelimit]]]) +.. function:: plan_dct(A[, dims[, flags[, timelimit]]]) - :: - - plan_dct(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized discrete cosine transform (DCT), similar to The first two arguments have the same meaning as for ``dct()``. -.. function:: plan_dct!(A [, dims [, flags [, timelimit]]]) +.. function:: plan_dct!(A[, dims[, flags[, timelimit]]]) - :: - - plan_dct!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_dct()``, but operates in-place on ``A``. -.. function:: plan_idct(A [, dims [, flags [, timelimit]]]) +.. function:: plan_idct(A[, dims[, flags[, timelimit]]]) - :: - - plan_idct(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized inverse discrete cosine transform (DCT), similar to ``plan_fft()`` except producing a function that computes -.. function:: plan_idct!(A [, dims [, flags [, timelimit]]]) +.. function:: plan_idct!(A[, dims[, flags[, timelimit]]]) - :: - - plan_idct!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_idct()``, but operates in-place on ``A``. -.. function:: fftshift(x) +.. function:: fftshift(x, dim) - :: - - fftshift(x, dim) - Swap the first and second halves of the given dimension of array -.. function:: fftshift(x,dim) +.. function:: fftshift(x, dim) - :: - - fftshift(x, dim) - Swap the first and second halves of the given dimension of array -.. function:: ifftshift(x, [dim]) +.. function:: ifftshift(x[, dim]) - :: - - ifftshift(x[, dim]) - Undoes the effect of ``fftshift``. -.. function:: filt(b, a, x, [si]) +.. function:: filt(b, a, x[, si]) - :: - - filt(b, a, x[, si]) - Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an optional initial filter state vector ``si`` (defaults to zeros). -.. function:: filt!(out, b, a, x, [si]) +.. function:: filt!(out, b, a, x[, si]) - :: - - filt!(out, b, a, x[, si]) - Same as ``filt()`` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. -.. function:: deconv(b,a) +.. function:: deconv(b, a) - :: - - deconv(b, a) - Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. -.. function:: conv(u,v) +.. function:: conv(u, v) - :: - - conv(u, v) - Convolution of two vectors. Uses FFT algorithm. -.. function:: conv2(u,v,A) +.. function:: conv2(B, A) - :: - - conv2(B, A) - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm -.. function:: conv2(B,A) +.. function:: conv2(B, A) - :: - - conv2(B, A) - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm -.. function:: xcorr(u,v) +.. function:: xcorr(u, v) - :: - - xcorr(u, v) - Compute the cross-correlation of two vectors. @@ -2633,39 +1532,23 @@ The following functions are defined within the ``Base.FFTW`` module. .. currentmodule:: Base.FFTW -.. function:: r2r(A, kind [, dims]) +.. function:: r2r(A, kind[, dims]) - :: - - r2r(A, kind[, dims]) - Performs a multidimensional real-input/real-output (r2r) transform of type ``kind`` of the array ``A``, as defined in the FFTW manual. types (``FFTW.REDFT00``, ``FFTW.REDFT01``, ``FFTW.REDFT10``, or Hartley transform (``FFTW.DHT``). The ``kind`` argument may be an array or tuple in order to specify different transform types along the different dimensions of ``A``; ``kind[end]`` is used for any unspecified dimensions. See the FFTW manual for precise definitions of these transform types, at http://www.fftw.org/doc. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. ``kind[i]`` is then the transform type for ``dims[i]``, with See also ``plan_r2r()`` to pre-plan optimized r2r transforms. -.. function:: r2r!(A, kind [, dims]) +.. function:: r2r!(A, kind[, dims]) - :: - - r2r!(A, kind[, dims]) - Same as ``r2r()``, but operates in-place on ``A``, which must be an array of real or complex floating-point numbers. -.. function:: plan_r2r(A, kind [, dims [, flags [, timelimit]]]) +.. function:: plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - :: - - plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - Pre-plan an optimized r2r transform, similar to ``Base.plan_fft()`` except that the transforms (and the first three arguments) correspond to ``r2r()`` and ``r2r!()``, respectively. -.. function:: plan_r2r!(A, kind [, dims [, flags [, timelimit]]]) +.. function:: plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) - :: - - plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) - Similar to ``Base.plan_fft()``, but corresponds to ``r2r!()``. @@ -2677,12 +1560,8 @@ Although several external packages are available for numeric integration and solution of ordinary differential equations, we also provide some built-in integration support in Julia. -.. function:: quadgk(f, a,b,c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) +.. function:: quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - :: - - quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - Numerically integrate the function ``f(x)`` from ``a`` to ``b``, and optionally over additional intervals ``b`` to ``c`` and so on. Keyword options include a relative error tolerance ``reltol`` absolute error tolerance ``abstol`` (defaults to 0), a maximum number of function evaluations ``maxevals`` (defaults to ``10^7``), and the ``order`` of the integration rule (defaults to 7). Returns a pair ``(I,E)`` of the estimated integral ``I`` and an estimated upper bound on the absolute error ``E``. If ``maxevals`` is not exceeded then ``E <= max(abstol, reltol*norm(I))`` will hold. (Note that it is useful to specify a positive ``abstol`` in cases where ``norm(I)`` may be zero.) The endpoints ``a`` etcetera can also be complex (in which case the integral is performed over straight-line segments in the complex plane). If the endpoints are ``BigFloat``, then the integration will be performed in ``BigFloat`` precision as well (note: it is advisable to increase the integration ``order`` in rough proportion to the precision, for smooth integrands). More generally, the precision is set by the precision of the integration endpoints The integrand ``f(x)`` can return any numeric scalar, vector, or matrix type, or in fact any type supporting ``+``, ``-``, multiplication by real values, and a ``norm`` (i.e., any normed vector space). Alternatively, a different norm can be specified by passing a *norm*-like function as the *norm* keyword argument multi-dimensional integration (cubature), there are many different algorithms (often much better than simple nested 1d integrals) and the optimal choice tends to be very problem-dependent. See the Julia external-package listing for available algorithms for multidimensional integration or other specialized tasks (such as integrals of highly oscillatory or singular functions).] The algorithm is an adaptive Gauss-Kronrod integration technique: the integral in each interval is estimated using a Kronrod rule Gauss rule (``order`` points). The interval with the largest error is then subdivided into two intervals and the process is repeated until the desired error tolerance is achieved. These quadrature rules work best for smooth functions within each interval, so if your function has a known discontinuity or other singularity, it is best to subdivide your interval to put the singularity at an endpoint. For example, if ``f`` has a discontinuity at ``x=0.7`` and you want to integrate from 0 to 1, you should use ``quadgk(f, 0,0.7,1)`` to subdivide the interval at the point of discontinuity. The integrand is never evaluated exactly at the endpoints of the intervals, so it is possible to integrate functions that diverge at the endpoints as long as the singularity is integrable (for example, a ``log(x)`` or For real-valued endpoints, the starting and/or ending points may be infinite. (A coordinate transformation is performed internally to map the infinite interval to a finite one.) diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index f74e014bed0e7..aac9e41d7d68f 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -12,201 +12,113 @@ Standard Numeric Types Data Formats ------------ -.. function:: bin(n, [pad]) +.. function:: bin(n[, pad]) - :: - - bin(n[, pad]) - Convert an integer to a binary string, optionally specifying a number of digits to pad to. -.. function:: hex(n, [pad]) +.. function:: hex(n[, pad]) - :: - - hex(n[, pad]) - Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. -.. function:: dec(n, [pad]) +.. function:: dec(n[, pad]) - :: - - dec(n[, pad]) - Convert an integer to a decimal string, optionally specifying a number of digits to pad to. -.. function:: oct(n, [pad]) +.. function:: oct(n[, pad]) - :: - - oct(n[, pad]) - Convert an integer to an octal string, optionally specifying a number of digits to pad to. -.. function:: base(base, n, [pad]) +.. function:: base(base, n[, pad]) - :: - - base(base, n[, pad]) - Convert an integer to a string in the given base, optionally specifying a number of digits to pad to. The base can be specified as either an integer, or as a ``UInt8`` array of character values to use as digit symbols. -.. function:: digits(n, [base], [pad]) +.. function:: digits(n[, base][, pad]) - :: - - digits(n[, base][, pad]) - Returns an array of the digits of ``n`` in the given base, optionally padded with zeros to a specified size. More significant digits are at higher indexes, such that ``n == sum([digits[k]*base^(k-1) for k=1:length(digits)])``. -.. function:: digits!(array, n, [base]) +.. function:: digits!(array, n[, base]) - :: - - digits!(array, n[, base]) - Fills an array of the digits of ``n`` in the given base. More significant digits are at higher indexes. If the array length is insufficient, the least significant digits are filled up to the array length. If the array length is excessive, the excess portion is filled with zeros. .. function:: bits(n) - :: - - bits(n) - A string giving the literal bit representation of a number. -.. function:: parse(type, str, [base]) +.. function:: parse(type, str[, base]) - :: - - parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. -.. function:: tryparse(type, str, [base]) +.. function:: tryparse(type, str[, base]) - :: - - tryparse(type, str[, base]) - Like ``parse``, but returns a ``Nullable`` of the requested type. The result will be null if the string does not contain a valid number. .. function:: big(x) - :: - - big(x) - Convert a number to a maximum precision representation (typically some pitfalls with floating-point numbers. .. function:: signed(x) - :: - - signed(x) - Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. .. function:: unsigned(x) -> Unsigned - :: - - unsigned(x) -> Unsigned - Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as unsigned without checking for negative values. .. function:: float(x) - :: - - float(x) - Convert a number, array, or string to a ``FloatingPoint`` data type. For numeric data, the smallest suitable ``FloatingPoint`` type is used. Converts strings to ``Float64``. .. function:: significand(x) - :: - - significand(x) - Extract the significand(s) (a.k.a. mantissa), in binary representation, of a floating-point number or array. If ``x`` is a non-zero finite number, than the result will be a number of the same type on the interval [1,2). Otherwise ``x`` is returned. .. function:: exponent(x) -> Int - :: - - exponent(x) -> Int - Get the exponent of a normalized floating-point number. -.. function:: complex(r, [i]) +.. function:: complex(r[, i]) - :: - - complex(r[, i]) - Convert real numbers or arrays to complex. ``i`` defaults to zero. .. function:: bswap(n) - :: - - bswap(n) - Byte-swap an integer .. function:: num2hex(f) - :: - - num2hex(f) - Get a hexadecimal string of the binary representation of a floating point number .. function:: hex2num(str) - :: - - hex2num(str) - Convert a hexadecimal string to the floating point number it represents .. function:: hex2bytes(s::ASCIIString) - :: - - hex2bytes(s::ASCIIString) - Convert an arbitrarily long hexadecimal string to its binary representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. .. function:: bytes2hex(bin_arr::Array{UInt8, 1}) - :: - - bytes2hex(bin_arr::Array{UInt8, 1}) - Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. @@ -215,19 +127,11 @@ General Number Functions and Constants .. function:: one(x) - :: - - one(x) - Get the multiplicative identity element for the type of x (x can also specify the type itself). For matrices, returns an identity matrix of the appropriate size and type. .. function:: zero(x) - :: - - zero(x) - Get the additive identity element for the type of x (x can also specify the type itself). @@ -285,154 +189,86 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool - :: - - issubnormal(f) -> Bool - Test whether a floating point number is subnormal .. function:: isfinite(f) -> Bool - :: - - isfinite(f) -> Bool - Test whether a number is finite .. function:: isinf(f) -> Bool - :: - - isinf(f) -> Bool - Test whether a number is infinite .. function:: isnan(f) -> Bool - :: - - isnan(f) -> Bool - Test whether a floating point number is not a number (NaN) .. function:: inf(f) - :: - - inf(f) - Returns positive infinity of the floating point type ``f`` or of the same floating point type as ``f`` .. function:: nan(f) - :: - - nan(f) - Returns NaN (not-a-number) of the floating point type ``f`` or of the same floating point type as ``f`` .. function:: nextfloat(f) - :: - - nextfloat(f) - Get the next floating point number in lexicographic order .. function:: prevfloat(f) -> FloatingPoint - :: - - prevfloat(f) -> FloatingPoint - Get the previous floating point number in lexicographic order .. function:: isinteger(x) -> Bool - :: - - isinteger(x) -> Bool - Test whether ``x`` or all its elements are numerically equal to some integer .. function:: isreal(x) -> Bool - :: - - isreal(x) -> Bool - Test whether ``x`` or all its elements are numerically equal to some real number -.. function:: Float32(x [, mode::RoundingMode]) +.. function:: Float32(x[, mode::RoundingMode]) - :: - - Float32(x[, mode::RoundingMode]) - Create a Float32 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. -.. function:: Float64(x [, mode::RoundingMode]) +.. function:: Float64(x[, mode::RoundingMode]) - :: - - Float64(x[, mode::RoundingMode]) - Create a Float64 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. .. function:: BigInt(x) - :: - - BigInt(x) - Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``). The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. Instances can be constructed from strings via ``parse()``, or using the ``big`` string literal. .. function:: BigFloat(x) - :: - - BigFloat(x) - Create an arbitrary precision floating point number. ``x`` may be an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results are promoted to a ``BigFloat``. Note that because decimal literals are converted to floating point numbers when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead prefer to initialize constants from strings via ``parse()``, or using the ``big`` string literal. .. function:: get_rounding(T) - :: - - get_rounding(T) - Get the current floating point rounding mode for type ``T``, controlling the rounding of basic arithmetic functions (``+()``, Valid modes are ``RoundNearest``, ``RoundToZero``, ``RoundUp``, .. function:: set_rounding(T, mode) - :: - - set_rounding(T, mode) - Set the rounding mode of floating point type ``T``, controlling the rounding of basic arithmetic functions (``+()``, ``-()``, ``*()``, Note that this may affect other types, for instance changing the rounding mode of ``Float64`` will change the rounding mode of .. function:: with_rounding(f::Function, T, mode) - :: - - with_rounding(f::Function, T, mode) - Change the rounding mode of floating point type ``T`` for the duration of ``f``. It is logically equivalent to: See ``get_rounding`` for available rounding modes. @@ -441,100 +277,56 @@ Integers .. function:: count_ones(x::Integer) -> Integer - :: - - count_ones(x::Integer) -> Integer - Number of ones in the binary representation of ``x``. .. function:: count_zeros(x::Integer) -> Integer - :: - - count_zeros(x::Integer) -> Integer - Number of zeros in the binary representation of ``x``. .. function:: leading_zeros(x::Integer) -> Integer - :: - - leading_zeros(x::Integer) -> Integer - Number of zeros leading the binary representation of ``x``. .. function:: leading_ones(x::Integer) -> Integer - :: - - leading_ones(x::Integer) -> Integer - Number of ones leading the binary representation of ``x``. .. function:: trailing_zeros(x::Integer) -> Integer - :: - - trailing_zeros(x::Integer) -> Integer - Number of zeros trailing the binary representation of ``x``. .. function:: trailing_ones(x::Integer) -> Integer - :: - - trailing_ones(x::Integer) -> Integer - Number of ones trailing the binary representation of ``x``. -.. function:: isprime(x::Integer) -> Bool +.. function:: isprime(x::BigInt[, reps = 25]) -> Bool - :: - - isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). -.. function:: isprime(x::BigInt, [reps = 25]) -> Bool +.. function:: isprime(x::BigInt[, reps = 25]) -> Bool - :: - - isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). .. function:: primes(n) - :: - - primes(n) - Returns a collection of the prime numbers <= ``n``. .. function:: isodd(x::Integer) -> Bool - :: - - isodd(x::Integer) -> Bool - Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and .. function:: iseven(x::Integer) -> Bool - :: - - iseven(x::Integer) -> Bool - Returns ``true`` is ``x`` is even (that is, divisible by 2), and @@ -544,37 +336,21 @@ The `BigFloat` type implements arbitrary-precision floating-point arithmetic usi .. function:: precision(num::FloatingPoint) - :: - - precision(num::FloatingPoint) - Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. .. function:: get_bigfloat_precision() - :: - - get_bigfloat_precision() - Get the precision (in bits) currently used for BigFloat arithmetic. .. function:: set_bigfloat_precision(x::Int64) - :: - - set_bigfloat_precision(x::Int64) - Set the precision (in bits) to be used to BigFloat arithmetic. -.. function:: with_bigfloat_precision(f::Function,precision::Integer) +.. function:: with_bigfloat_precision(f::Function, precision::Integer) - :: - - with_bigfloat_precision(f::Function, precision::Integer) - Change the BigFloat arithmetic precision (in bits) for the duration of ``f``. It is logically equivalent to: @@ -597,93 +373,53 @@ A ``MersenneTwister`` or ``RandomDevice`` RNG can generate random numbers of the (or complex numbers of those types). Random floating point numbers are generated uniformly in [0,1). As ``BigInt`` represents unbounded integers, the interval must be specified (e.g. ``rand(big(1:6))``). -.. function:: srand([rng], [seed]) +.. function:: srand([rng][, seed]) - :: - - srand([rng][, seed]) - Reseed the random number generator. If a ``seed`` is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. For ``MersenneTwister``, the integers or a filename, in which case the seed is read from a file. .. function:: MersenneTwister([seed]) - :: - - MersenneTwister([seed]) - Create a ``MersenneTwister`` RNG object. Different RNG objects can have their own seeds, which may be useful for generating different streams of random numbers. .. function:: RandomDevice() - :: - - RandomDevice() - Create a ``RandomDevice`` RNG object. Two such objects will always generate different streams of random numbers. -.. function:: rand([rng], [S], [dims...]) +.. function:: rand([rng][, S][, dims...]) - :: - - rand([rng][, S][, dims...]) - Pick a random element or array of random elements from the set of values specified by ``S``; ``S`` can be -.. function:: rand!([rng], A, [coll]) +.. function:: rand!([rng], A[, coll]) - :: - - rand!([rng], A[, coll]) - Populate the array A with random values. If the indexable collection ``coll`` is specified, the values are picked randomly from ``coll``. This is equivalent to ``copy!(A, rand(rng, coll, size(A)))`` or ``copy!(A, rand(rng, eltype(A), size(A)))`` but without allocating a new array. -.. function:: bitrand([rng], [dims...]) +.. function:: bitrand([rng][, dims...]) - :: - - bitrand([rng][, dims...]) - Generate a ``BitArray`` of random boolean values. -.. function:: randn([rng], [dims...]) +.. function:: randn([rng][, dims...]) - :: - - randn([rng][, dims...]) - Generate a normally-distributed random number with mean 0 and standard deviation 1. Optionally generate an array of normally- distributed random numbers. -.. function:: randn!([rng], A::Array{Float64,N}) +.. function:: randn!([rng], A::Array{Float64, N}) - :: - - randn!([rng], A::Array{Float64, N}) - Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand function. -.. function:: randexp([rng], [dims...]) +.. function:: randexp([rng][, dims...]) - :: - - randexp([rng][, dims...]) - Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. -.. function:: randexp!([rng], A::Array{Float64,N}) +.. function:: randexp!([rng], A::Array{Float64, N}) - :: - - randexp!([rng], A::Array{Float64, N}) - Fill the array A with random numbers following the exponential distribution (with scale 1). diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 89b22a59e4409..0b1319d7e2308 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -9,454 +9,254 @@ Tasks .. function:: Task(func) - :: - - Task(func) - Create a ``Task`` (i.e. thread, or coroutine) to execute the given function (which must be callable with no arguments). The task exits when this function returns. .. function:: yieldto(task, arg = nothing) - :: - - yieldto(task, arg = nothing) - Switch to the given task. The first time a task is switched to, the task's function is called with no arguments. On subsequent switches, ``arg`` is returned from the task's last call to considering states or scheduling in any way. Its use is discouraged. .. function:: current_task() - :: - - current_task() - Get the currently running Task. .. function:: istaskdone(task) -> Bool - :: - - istaskdone(task) -> Bool - Tell whether a task has exited. .. function:: istaskstarted(task) -> Bool - :: - - istaskstarted(task) -> Bool - Tell whether a task has started executing. .. function:: consume(task, values...) - :: - - consume(task, values...) - Receive the next value passed to ``produce`` by the specified task. Additional arguments may be passed, to be returned from the last .. function:: produce(value) - :: - - produce(value) - Send the given value to the last ``consume`` call, switching to the consumer task. If the next ``consume`` call passes any values, they are returned by ``produce``. .. function:: yield() - :: - - yield() - Switch to the scheduler to allow another scheduled task to run. A task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. -.. function:: task_local_storage(symbol) +.. function:: task_local_storage(body, symbol, value) - :: - - task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. -.. function:: task_local_storage(symbol, value) +.. function:: task_local_storage(body, symbol, value) - :: - - task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. .. function:: task_local_storage(body, symbol, value) - :: - - task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. .. function:: Condition() - :: - - Condition() - Create an edge-triggered event source that tasks can wait for. Tasks that call ``wait`` on a ``Condition`` are suspended and queued. Tasks are woken up when ``notify`` is later called on the time ``notify`` is called can be woken up. For level-triggered notifications, you must keep extra state to keep track of whether a notification has happened. The ``RemoteRef`` type does this, and so can be used for level-triggered events. .. function:: notify(condition, val=nothing; all=true, error=false) - :: - - notify(condition, val=nothing; all=true, error=false) - Wake up tasks waiting for a condition, passing them ``val``. If otherwise only one is. If ``error`` is true, the passed value is raised as an exception in the woken tasks. .. function:: schedule(t::Task, [val]; error=false) - :: - - schedule(t::Task, [val]; error=false) - Add a task to the scheduler's queue. This causes the task to run constantly when the system is otherwise idle, unless the task performs a blocking operation such as ``wait``. If a second argument is provided, it will be passed to the task task. -.. function:: @schedule +.. function:: @schedule() - :: - - @schedule() - Wrap an expression in a Task and add it to the scheduler's queue. -.. function:: @task +.. function:: @task() - :: - - @task() - Wrap an expression in a Task without executing it, and return the Task. This only creates a task, and does not run it. .. function:: sleep(seconds) - :: - - sleep(seconds) - Block the current task for a specified number of seconds. The minimum sleep time is 1 millisecond or input of ``0.001``. .. function:: ReentrantLock() - :: - - ReentrantLock() - Creates a reentrant lock. The same task can acquire the lock as many times as required. Each lock must be matched with an unlock. .. function:: lock(l::ReentrantLock) - :: - - lock(l::ReentrantLock) - Associates ``l`` with the current task. If ``l`` is already locked by a different task, waits for it to become available. The same task can acquire the lock multiple times. Each ``lock`` must be matched by an ``unlock`` .. function:: unlock(l::ReentrantLock) - :: - - unlock(l::ReentrantLock) - Releases ownership of the lock by the current task. If the lock had been acquired before, it just decrements an internal counter and returns immediately. General Parallel Computing Support ---------------------------------- -.. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers +.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - :: - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. -.. function:: addprocs() -> List of process identifiers +.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - :: - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. -.. function:: addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers +.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - :: - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - :: - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. .. function:: nprocs() - :: - - nprocs() - Get the number of available processes. .. function:: nworkers() - :: - - nworkers() - Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. -.. function:: procs() +.. function:: procs(S::SharedArray) - :: - - procs(S::SharedArray) - Get the vector of processes that have mapped the shared array .. function:: workers() - :: - - workers() - Returns a list of all worker process identifiers. .. function:: rmprocs(pids...) - :: - - rmprocs(pids...) - Removes the specified workers. .. function:: interrupt([pids...]) - :: - - interrupt([pids...]) - Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted. .. function:: myid() - :: - - myid() - Get the id of the current process. .. function:: pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - :: - - pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - Transform collections ``lsts`` by applying ``f`` to each element in parallel. If ``nprocs() > 1``, the calling process will be dedicated to assigning tasks. All other available processes will be used as parallel workers, or on the processes specified by If ``err_retry`` is true, it retries a failed application of ``f`` on a different worker. If ``err_stop`` is true, it takes precedence over the value of ``err_retry`` and ``pmap`` stops execution on the first error. .. function:: remotecall(id, func, args...) - :: - - remotecall(id, func, args...) - Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. .. function:: wait([x]) - :: - - wait([x]) - Block the current task until some event occurs, depending on the type of the argument: If no argument is passed, the task blocks for an undefined period. If the task's state is set to ``:waiting``, it can only be restarted by an explicit call to ``schedule`` or ``yieldto``. If the task's state is ``:runnable``, it might be restarted unpredictably. Often ``wait`` is called within a ``while`` loop to ensure a waited-for condition is met before proceeding. .. function:: fetch(RemoteRef) - :: - - fetch(RemoteRef) - Wait for and get the value of a remote reference. .. function:: remotecall_wait(id, func, args...) - :: - - remotecall_wait(id, func, args...) - Perform ``wait(remotecall(...))`` in one message. .. function:: remotecall_fetch(id, func, args...) - :: - - remotecall_fetch(id, func, args...) - Perform ``fetch(remotecall(...))`` in one message. .. function:: put!(RemoteRef, value) - :: - - put!(RemoteRef, value) - Store a value to a remote reference. Implements ``shared queue of length 1`` semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. .. function:: take!(RemoteRef) - :: - - take!(RemoteRef) - Fetch the value of a remote reference, removing it so that the reference is empty again. .. function:: isready(r::RemoteRef) - :: - - isready(r::RemoteRef) - Determine whether a ``RemoteRef`` has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. It is recommended that this function only be used on a ``RemoteRef`` that is assigned once. If the argument ``RemoteRef`` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for ``r`` in a separate task instead, or to use a local -.. function:: RemoteRef() +.. function:: RemoteRef(n) - :: - - RemoteRef(n) - Make an uninitialized remote reference on process ``n``. .. function:: RemoteRef(n) - :: - - RemoteRef(n) - Make an uninitialized remote reference on process ``n``. .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - :: - - timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - - Waits till ``testcb`` returns ``true`` or for ``secs`` seconds, whichever is earlier. `testcb`` is polled every ``pollint`` seconds. + Waits till ``testcb`` returns ``true`` or for ``secs`` seconds, whichever is earlier. ``testcb`` is polled every ``pollint`` seconds. -.. function:: @spawn +.. function:: @spawn() - :: - - @spawn() - Execute an expression on an automatically-chosen process, returning a ``RemoteRef`` to the result. -.. function:: @spawnat +.. function:: @spawnat() - :: - - @spawnat() - Accepts two arguments, ``p`` and an expression, and runs the expression asynchronously on process ``p``, returning a -.. function:: @fetch +.. function:: @fetch() - :: - - @fetch() - Equivalent to ``fetch(@spawn expr)``. -.. function:: @fetchfrom +.. function:: @fetchfrom() - :: - - @fetchfrom() - Equivalent to ``fetch(@spawnat p expr)``. -.. function:: @async +.. function:: @async() - :: - - @async() - Schedule an expression to run on the local machine, also adding it to the set of items that the nearest enclosing ``@sync`` waits for. -.. function:: @sync +.. function:: @sync() - :: - - @sync() - Wait until all dynamically-enclosed uses of ``@async``, ``@spawn``, -.. function:: @parallel +.. function:: @parallel() - :: - - @parallel() - A parallel for loop of the form The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, reduction on the calling process. Note that without a reducer function, @parallel executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with ``@sync``, like @@ -465,37 +265,21 @@ Shared Arrays (Experimental, UNIX-only feature) .. function:: SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - :: - - SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - Construct a SharedArray of a bitstype ``T`` and size ``dims`` across the processes specified by ``pids`` - all of which have to be on the same host. If ``pids`` is left unspecified, the shared array will be mapped across all processes on the current host, including the master. But, ``localindexes`` and ``indexpids`` will only refer to worker processes. This facilitates work distribution code to use workers for actual computation with the master process acting as a driver. If an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, it is called on all the participating workers. .. function:: procs(S::SharedArray) - :: - - procs(S::SharedArray) - Get the vector of processes that have mapped the shared array .. function:: sdata(S::SharedArray) - :: - - sdata(S::SharedArray) - Returns the actual ``Array`` object backing ``S`` .. function:: indexpids(S::SharedArray) - :: - - indexpids(S::SharedArray) - Returns the index of the current worker into the ``pids`` vector, i.e., the list of workers mapping the SharedArray @@ -508,46 +292,26 @@ Cluster Manager Interface .. function:: launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - :: - - launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - Implemented by cluster managers. For every Julia worker launched by this function, it should append a ``WorkerConfig`` entry to once all workers, requested by ``manager`` have been launched. was called with. .. function:: manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - :: - - manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - Implemented by cluster managers. It is called on the master process, during a worker's lifetime, with appropriate ``op`` values: .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - :: - - kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. .. function:: init_worker(manager::FooManager) - :: - - init_worker(manager::FooManager) - Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets for transport. .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - :: - - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index d1bcf1e8b74b0..36a41338871ce 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -7,246 +7,138 @@ All package manager functions are defined in the ``Pkg`` module. None of the ``Pkg`` module's functions are exported; to use them, you'll need to prefix each function call with an explicit ``Pkg.``, e.g. ``Pkg.status()`` or ``Pkg.dir()``. -.. function:: dir() -> AbstractString +.. function:: dir(names...) -> AbstractString - :: - - dir(names...) -> AbstractString - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. .. function:: dir(names...) -> AbstractString - :: - - dir(names...) -> AbstractString - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. .. function:: init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - :: - - init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - Initialize ``Pkg.dir()`` as a package directory. This will be done automatically when the ``JULIA_PKGDIR`` is not set and clones a local METADATA git repository from the site and branch specified by its arguments, which are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. .. function:: resolve() - :: - - resolve() - Determines an optimal, consistent set of package versions to install or upgrade to. The optimal set of package versions is based on the contents of ``Pkg.dir(``REQUIRE``)`` and the state of installed packages in ``Pkg.dir()``, Packages that are no longer required are moved into ``Pkg.dir(``.trash``)``. .. function:: edit() - :: - - edit() - Opens ``Pkg.dir(``REQUIRE``)`` in the editor specified by the command returns, it runs ``Pkg.resolve()`` to determine and install a new optimal set of installed package versions. .. function:: add(pkg, vers...) - :: - - add(pkg, vers...) - Add a requirement entry for ``pkg`` to ``Pkg.dir(``REQUIRE``)`` and call ``Pkg.resolve()``. If ``vers`` are given, they must be intervals for ``pkg``. .. function:: rm(pkg) - :: - - rm(pkg) - Remove all requirement entries for ``pkg`` from -.. function:: clone(url, [pkg]) +.. function:: clone(pkg) - :: - - clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. .. function:: clone(pkg) - :: - - clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. -.. function:: available() -> Vector{ASCIIString} +.. function:: available(pkg) -> Vector{VersionNumber} - :: - - available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package ``pkg``. .. function:: available(pkg) -> Vector{VersionNumber} - :: - - available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package ``pkg``. -.. function:: installed() -> Dict{ASCIIString,VersionNumber} +.. function:: installed(pkg) -> Void | VersionNumber - :: - - installed(pkg) -> Void | VersionNumber - If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. .. function:: installed(pkg) -> Void | VersionNumber - :: - - installed(pkg) -> Void | VersionNumber - If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. .. function:: status() - :: - - status() - Prints out a summary of what packages are installed and what version and state they're in. .. function:: update() - :: - - update() - Update package the metadata repo – kept in safely be pulled from their origin; then call ``Pkg.resolve()`` to determine a new optimal set of packages versions. -.. function:: checkout(pkg, [branch="master"]) +.. function:: checkout(pkg[, branch="master"]) - :: - - checkout(pkg[, branch="master"]) - Checkout the ``Pkg.dir(pkg)`` repo to the branch ``branch``. Defaults to checking out the ``master`` branch. To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` -.. function:: pin(pkg) +.. function:: pin(pkg, version) - :: - - pin(pkg, version) - Pin ``pkg`` at registered version ``version``. .. function:: pin(pkg, version) - :: - - pin(pkg, version) - Pin ``pkg`` at registered version ``version``. .. function:: free(pkg) - :: - - free(pkg) - Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and You can also supply an iterable collection of package names, e.g., once. -.. function:: build() +.. function:: build(pkgs...) - :: - - build(pkgs...) - Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. .. function:: build(pkgs...) - :: - - build(pkgs...) - Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. -.. function:: generate(pkg,license) +.. function:: generate(pkg, license) - :: - - generate(pkg, license) - Generate a new package named ``pkg`` with one of these license keys: ``MIT``, ``BSD`` or ``ASL``. If you want to make a package with a different license, you can edit it afterwards. Generate creates a git repo at ``Pkg.dir(pkg)`` for the package and inside it ``LICENSE.md``, ``README.md``, the julia entrypoint -.. function:: register(pkg, [url]) +.. function:: register(pkg[, url]) - :: - - register(pkg[, url]) - Register ``pkg`` at the git URL ``url``, defaulting to the configured origin URL of the git repo ``Pkg.dir(pkg)``. -.. function:: tag(pkg, [ver, [commit]]) +.. function:: tag(pkg[, ver[, commit]]) - :: - - tag(pkg[, ver[, commit]]) - Tag ``commit`` as version ``ver`` of package ``pkg`` and create a version entry in ``METADATA``. If not provided, ``commit`` defaults to the current commit of the ``pkg`` repo. If ``ver`` is one of the symbols ``:patch``, ``:minor``, ``:major`` the next patch, minor or major version is used. If ``ver`` is not provided, it defaults to .. function:: publish() - :: - - publish() - For each new package version tagged in ``METADATA`` not already published, make sure that the tagged package commits have been pushed to the repo at the registered URL for the package and if they all have, open a pull request to ``METADATA``. -.. function:: test() +.. function:: test(pkgs...) - :: - - test(pkgs...) - Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. .. function:: test(pkgs...) - :: - - test(pkgs...) - Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 60b010eb02a4e..e214e1183badf 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -8,12 +8,8 @@ .. currentmodule:: Base -.. function:: @profile +.. function:: @profile() - :: - - @profile() - periodic backtraces. These are appended to an internal buffer of backtraces. @@ -22,73 +18,41 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a .. function:: clear() - :: - - clear() - Clear any existing backtraces from the internal buffer. -.. function:: print([io::IO = STDOUT,] [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) +.. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - :: - - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. -.. function:: print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) +.. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - :: - - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. .. function:: init(; n::Integer, delay::Float64) - :: - - init(; n::Integer, delay::Float64) - Configure the ``delay`` between backtraces (measured in seconds), and the number ``n`` of instruction pointers that may be stored. Each instruction pointer corresponds to a single line of code; backtraces generally consist of a long list of instruction pointers. Default settings can be obtained by calling this function with no arguments, and each can be set independently using keywords or in the order ``(n, delay)``. .. function:: fetch() -> data - :: - - fetch() -> data - Returns a reference to the internal buffer of backtraces. Note that subsequent operations, like ``clear()``, can affect ``data`` unless you first make a copy. Note that the values in ``data`` have meaning only on this machine in the current session, because it depends on the exact memory addresses used in JIT-compiling. This function is primarily for internal use; ``retrieve()`` may be a better choice for most users. .. function:: retrieve() -> data, lidict - :: - - retrieve() -> data, lidict - set of all backtraces (``data``) and a dictionary that maps the values that store the file name, function name, and line number. This function allows you to save profiling results for future analysis. -.. function:: callers(funcname, [data, lidict], [filename=], [linerange=]) -> Vector{Tuple{count, linfo}} +.. function:: callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - :: - - callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - Given a previous profiling run, determine who called a particular function. Supplying the filename (and optionally, range of line numbers over which the function is defined) allows you to disambiguate an overloaded method. The returned value is a vector containing a count of the number of calls and line information about the caller. One can optionally supply backtrace data obtained from ``retrieve()``; otherwise, the current internal profile buffer is used. .. function:: clear_malloc_data() - :: - - clear_malloc_data() - Clears any stored memory allocation data when running julia with ` force JIT-compilation), then call ``clear_malloc_data()``. Then execute your command(s) again, quit Julia, and examine the resulting ``*.mem`` files. diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 6d63982e9f15e..8ef13f75c3302 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -119,64 +119,36 @@ Sorting Functions .. function:: sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - :: - - sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the vector ``v`` in place. ``QuickSort`` is used by default for numeric arrays while ``MergeSort`` is used for other arrays. You can specify an algorithm to use via the ``alg`` keyword (see Sorting Algorithms for available algorithms). The ``by`` keyword lets you provide a function that will be applied to each element before comparison; the ``lt`` keyword allows providing a custom order. These options are independent and can be used together in all possible combinations: if both ``by`` and ``lt`` are specified, the ``lt`` function is applied to the result of the ``by`` function; ``rev=true`` reverses whatever ordering specified via the -.. function:: sort(v, [alg=,] [by=,] [lt=,] [rev=false]) +.. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - :: - - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array ``A`` along the given dimension. .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - :: - - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array ``A`` along the given dimension. .. function:: sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - :: - - sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - Return a permutation vector of indices of ``v`` that puts it in sorted order. Specify ``alg`` to choose a particular sorting algorithm (see Sorting Algorithms). ``MergeSort`` is used by default, and since it is stable, the resulting permutation will be the lexicographically first one that puts the input array into sorted order – i.e. indices of equal elements appear in ascending order. If you choose a non-stable sorting algorithm such as order may be returned. The order is specified using the same keywords as ``sort!``. See also ``sortperm!()`` .. function:: sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - :: - - sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - Like ``sortperm``, but accepts a preallocated index vector ``ix``. If ``initialized`` is ``false`` (the default), ix is initialized to contain the values ``1:length(v)``. See also ``sortperm()`` .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - :: - - sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the rows of matrix ``A`` lexicographically. .. function:: sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - :: - - sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the columns of matrix ``A`` lexicographically. @@ -185,55 +157,31 @@ Order-Related Functions .. function:: issorted(v, [by=,] [lt=,] [rev=false]) - :: - - issorted(v, [by=,] [lt=,] [rev=false]) - Test whether a vector is in sorted order. The ``by``, ``lt`` and as they do for ``sort``. .. function:: searchsorted(a, x, [by=,] [lt=,] [rev=false]) - :: - - searchsorted(a, x, [by=,] [lt=,] [rev=false]) - Returns the range of indices of ``a`` which compare as equal to order. Returns an empty range located at the insertion point if .. function:: searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - :: - - searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the first value in ``a`` greater than or equal to ``x``, according to the specified order. Returns ``length(a)+1`` if ``x`` is greater than all values in ``a``. .. function:: searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - :: - - searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the last value in ``a`` less than or equal to less than all values in ``a``. .. function:: select!(v, k, [by=,] [lt=,] [rev=false]) - :: - - select!(v, k, [by=,] [lt=,] [rev=false]) - Partially sort the vector ``v`` in place, according to the order specified by ``by``, ``lt`` and ``rev`` so that the value at index the position where it would appear if the array were fully sorted via a non-stable algorithm. If ``k`` is a single index, that value is returned; if ``k`` is a range, an array of values at those indices is returned. Note that ``select!`` does not fully sort the input array. .. function:: select(v, k, [by=,] [lt=,] [rev=false]) - :: - - select(v, k, [by=,] [lt=,] [rev=false]) - Variant of ``select!`` which copies ``v`` before partially sorting it, thereby returning the same thing as ``select!`` but leaving diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index 04e11ea903f81..d59f309ed1257 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,28 +6,16 @@ .. function:: length(s) - :: - - length(s) - The number of characters in string ``s``. .. function:: sizeof(s::AbstractString) - :: - - sizeof(s::AbstractString) - The number of bytes in string ``s``. .. function:: *(s, t) - :: - - *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. @@ -36,640 +24,356 @@ .. function:: ^(s, n) - :: - - ^(s, n) - Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. .. function:: string(xs...) - :: - - string(xs...) - Create a string from any values using the ``print`` function. .. function:: repr(x) - :: - - repr(x) - Create a string from any value using the ``showall`` function. -.. function:: bytestring(::Ptr{UInt8}, [length]) +.. function:: bytestring(s) - :: - - bytestring(s) - Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. .. function:: bytestring(s) - :: - - bytestring(s) - Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. -.. function:: ascii(::Array{UInt8,1}) +.. function:: ascii(::Ptr{UInt8}[, length]) - :: - - ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. -.. function:: ascii(s) +.. function:: ascii(::Ptr{UInt8}[, length]) - :: - - ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. -.. function:: ascii(::Ptr{UInt8}, [length]) +.. function:: ascii(::Ptr{UInt8}[, length]) - :: - - ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. -.. function:: utf8(::Array{UInt8,1}) +.. function:: utf8(s) - :: - - utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). -.. function:: utf8(::Ptr{UInt8}, [length]) +.. function:: utf8(s) - :: - - utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). .. function:: utf8(s) - :: - - utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). .. function:: normalize_string(s, normalform::Symbol) - :: - - normalize_string(s, normalform::Symbol) - Normalize the string ``s`` according to one of the four ``normal forms`` of the Unicode standard: ``normalform`` can be ``:NFC``, composition) and D (canonical decomposition) convert different visually identical representations of the same abstract string into a single canonical form, with form C being more compact. Normal forms KC and KD additionally canonicalize ``compatibility equivalents``: they convert characters that are abstractly similar but visually distinct into a single canonical choice (e.g. they expand ligatures into the individual characters), with form KC being more compact. Alternatively, finer control and additional transformations may be be obtained by calling *normalize_string(s; keywords...)*, where any number of the following boolean keywords options (which all default to ``false`` except for ``compose``) are specified: For example, NFKC corresponds to the options ``compose=true, compat=true, stable=true``. .. function:: graphemes(s) -> iterator over substrings of s - :: - - graphemes(s) -> iterator over substrings of s - Returns an iterator over substrings of ``s`` that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) -.. function:: isvalid(value) -> Bool +.. function:: isvalid(str, i) - :: - - isvalid(str, i) - Tells whether index ``i`` is valid for the given string -.. function:: isvalid(T, value) -> Bool +.. function:: isvalid(str, i) - :: - - isvalid(str, i) - Tells whether index ``i`` is valid for the given string .. function:: is_assigned_char(c) -> Bool - :: - - is_assigned_char(c) -> Bool - Returns true if the given char or integer is an assigned Unicode code point. .. function:: ismatch(r::Regex, s::AbstractString) -> Bool - :: - - ismatch(r::Regex, s::AbstractString) -> Bool - Test whether a string contains a match of the given regular expression. .. function:: match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - :: - - match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - Search for the first match of the regular expression ``r`` in ``s`` and return a RegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessing ``m.match`` and the captured sequences can be retrieved by accessing ``m.captures`` The optional ``idx`` argument specifies an index at which to start the search. .. function:: eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - :: - - eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - Search for all matches of a the regular expression ``r`` in ``s`` and return a iterator over the matches. If overlap is true, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges. .. function:: matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - :: - - matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - Return a vector of the matching substrings from eachmatch. .. function:: lpad(string, n, p) - :: - - lpad(string, n, p) - Make a string at least ``n`` columns wide when printed, by padding on the left with copies of ``p``. .. function:: rpad(string, n, p) - :: - - rpad(string, n, p) - Make a string at least ``n`` columns wide when printed, by padding on the right with copies of ``p``. -.. function:: search(string, chars, [start]) +.. function:: search(string, chars[, start]) - :: - - search(string, chars[, start]) - Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that ``s[search(s,x)] == x``: -.. function:: rsearch(string, chars, [start]) +.. function:: rsearch(string, chars[, start]) - :: - - rsearch(string, chars[, start]) - Similar to ``search``, but returning the last occurrence of the given characters within the given string, searching in reverse from -.. function:: searchindex(string, substring, [start]) +.. function:: searchindex(string, substring[, start]) - :: - - searchindex(string, substring[, start]) - Similar to ``search``, but return only the start index at which the substring is found, or 0 if it is not. -.. function:: rsearchindex(string, substring, [start]) +.. function:: rsearchindex(string, substring[, start]) - :: - - rsearchindex(string, substring[, start]) - Similar to ``rsearch``, but return only the start index at which the substring is found, or 0 if it is not. .. function:: contains(haystack, needle) - :: - - contains(haystack, needle) - Determine whether the second argument is a substring of the first. .. function:: replace(string, pat, r[, n]) - :: - - replace(string, pat, r[, n]) - Search for the given pattern ``pat``, and replace each occurrence with ``r``. If ``n`` is provided, replace at most ``n`` occurrences. As with search, the second argument may be a single character, a vector or a set of characters, a string, or a regular expression. If ``r`` is a function, each occurrence is replaced with ``r(s)`` where ``s`` is the matched substring. .. function:: split(string, [chars]; limit=0, keep=true) - :: - - split(string, [chars]; limit=0, keep=true) - Return an array of substrings by splitting the given string on occurrences of the given character delimiters, which may be specified in any of the formats allowed by ``search``'s second argument (i.e. a single character, collection of characters, string, or regular expression). If ``chars`` is omitted, it defaults to the set of all space characters, and ``keep`` is taken to be false. The two keyword arguments are optional: they are are a maximum size for the result and a flag determining whether empty fields should be kept in the result. .. function:: rsplit(string, [chars]; limit=0, keep=true) - :: - - rsplit(string, [chars]; limit=0, keep=true) - Similar to ``split``, but starting from the end of the string. -.. function:: strip(string, [chars]) +.. function:: strip(string[, chars]) - :: - - strip(string[, chars]) - Return ``string`` with any leading and trailing whitespace removed. If ``chars`` (a character, or vector or set of characters) is provided, instead remove characters contained in it. -.. function:: lstrip(string, [chars]) +.. function:: lstrip(string[, chars]) - :: - - lstrip(string[, chars]) - Return ``string`` with any leading whitespace removed. If ``chars`` remove characters contained in it. -.. function:: rstrip(string, [chars]) +.. function:: rstrip(string[, chars]) - :: - - rstrip(string[, chars]) - Return ``string`` with any trailing whitespace removed. If provided, instead remove characters contained in it. .. function:: startswith(string, prefix | chars) - :: - - startswith(string, prefix | chars) - Returns ``true`` if ``string`` starts with ``prefix``. If the second argument is a vector or set of characters, tests whether the first character of ``string`` belongs to that set. .. function:: endswith(string, suffix | chars) - :: - - endswith(string, suffix | chars) - Returns ``true`` if ``string`` ends with ``suffix``. If the second argument is a vector or set of characters, tests whether the last character of ``string`` belongs to that set. .. function:: uppercase(string) - :: - - uppercase(string) - Returns ``string`` with all characters converted to uppercase. .. function:: lowercase(string) - :: - - lowercase(string) - Returns ``string`` with all characters converted to lowercase. .. function:: ucfirst(string) - :: - - ucfirst(string) - Returns ``string`` with the first character converted to uppercase. .. function:: lcfirst(string) - :: - - lcfirst(string) - Returns ``string`` with the first character converted to lowercase. -.. function:: join(strings, delim, [last]) +.. function:: join(strings, delim[, last]) - :: - - join(strings, delim[, last]) - Join an array of ``strings`` into a single string, inserting the given delimiter between adjacent strings. If ``last`` is given, it will be used instead of ``delim`` between the last two strings. For example, ``join([``apples``, `bananas``, ``pineapples``], ``, `, convertible to strings via `print(io::IOBuffer, x)``. .. function:: chop(string) - :: - - chop(string) - Remove the last character from a string .. function:: chomp(string) - :: - - chomp(string) - Remove a trailing newline from a string .. function:: ind2chr(string, i) - :: - - ind2chr(string, i) - Convert a byte index to a character index .. function:: chr2ind(string, i) - :: - - chr2ind(string, i) - Convert a character index to a byte index .. function:: isvalid(str, i) - :: - - isvalid(str, i) - Tells whether index ``i`` is valid for the given string .. function:: nextind(str, i) - :: - - nextind(str, i) - Get the next valid string index after ``i``. Returns a value greater than ``endof(str)`` at or after the end of the string. .. function:: prevind(str, i) - :: - - prevind(str, i) - Get the previous valid string index before ``i``. Returns a value less than ``1`` at the beginning of the string. -.. function:: randstring([rng,] len=8) +.. function:: randstring([rng], len=8) - :: - - randstring([rng], len=8) - Create a random ASCII string of length ``len``, consisting of upper- and lower-case letters and the digits 0-9. The optional Numbers*. .. function:: charwidth(c) - :: - - charwidth(c) - Gives the number of columns needed to print a character. .. function:: strwidth(s) - :: - - strwidth(s) - Gives the number of columns needed to print a string. -.. function:: isalnum(c::Union{Char,AbstractString}) -> Bool +.. function:: isalnum(c::Union{Char, AbstractString}) -> Bool - :: - - isalnum(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphanumeric, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter or Number, i.e. a character whose category code begins with 'L' or -.. function:: isalpha(c::Union{Char,AbstractString}) -> Bool +.. function:: isalpha(c::Union{Char, AbstractString}) -> Bool - :: - - isalpha(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphabetic, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'. -.. function:: isascii(c::Union{Char,AbstractString}) -> Bool +.. function:: isascii(c::Union{Char, AbstractString}) -> Bool - :: - - isascii(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the ASCII character set, or whether this is true for all elements of a string. -.. function:: iscntrl(c::Union{Char,AbstractString}) -> Bool +.. function:: iscntrl(c::Union{Char, AbstractString}) -> Bool - :: - - iscntrl(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a control character, or whether this is true for all elements of a string. Control characters are the non-printing characters of the Latin-1 subset of Unicode. -.. function:: isdigit(c::Union{Char,AbstractString}) -> Bool +.. function:: isdigit(c::Union{Char, AbstractString}) -> Bool - :: - - isdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a numeric digit (0-9), or whether this is true for all elements of a string. -.. function:: isgraph(c::Union{Char,AbstractString}) -> Bool +.. function:: isgraph(c::Union{Char, AbstractString}) -> Bool - :: - - isgraph(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, and not a space, or whether this is true for all elements of a string. Any character that would cause a printer to use ink should be classified with isgraph(c)==true. -.. function:: islower(c::Union{Char,AbstractString}) -> Bool +.. function:: islower(c::Union{Char, AbstractString}) -> Bool - :: - - islower(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a lowercase letter, or whether this is true for all elements of a string. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase. -.. function:: isnumber(c::Union{Char,AbstractString}) -> Bool +.. function:: isnumber(c::Union{Char, AbstractString}) -> Bool - :: - - isnumber(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is numeric, or whether this is true for all elements of a string. A character is classified as numeric if it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'. -.. function:: isprint(c::Union{Char,AbstractString}) -> Bool +.. function:: isprint(c::Union{Char, AbstractString}) -> Bool - :: - - isprint(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, including spaces, but not a control character. For strings, tests whether this is true for all elements of the string. -.. function:: ispunct(c::Union{Char,AbstractString}) -> Bool +.. function:: ispunct(c::Union{Char, AbstractString}) -> Bool - :: - - ispunct(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the Unicode general category Punctuation, i.e. a character whose category code begins with 'P'. For strings, tests whether this is true for all elements of the string. -.. function:: isspace(c::Union{Char,AbstractString}) -> Bool +.. function:: isspace(c::Union{Char, AbstractString}) -> Bool - :: - - isspace(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is any whitespace character. Includes ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs. For strings, tests whether this is true for all elements of the string. -.. function:: isupper(c::Union{Char,AbstractString}) -> Bool +.. function:: isupper(c::Union{Char, AbstractString}) -> Bool - :: - - isupper(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is an uppercase letter, or whether this is true for all elements of a string. A character is classified as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. -.. function:: isxdigit(c::Union{Char,AbstractString}) -> Bool +.. function:: isxdigit(c::Union{Char, AbstractString}) -> Bool - :: - - isxdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a valid hexadecimal digit, or whether this is true for all elements of a string. .. function:: symbol(x...) -> Symbol - :: - - symbol(x...) -> Symbol - Create a ``Symbol`` by concatenating the string representations of the arguments together. .. function:: escape_string(str::AbstractString) -> AbstractString - :: - - escape_string(str::AbstractString) -> AbstractString - General escaping of traditional C and Unicode escape sequences. See .. function:: unescape_string(s::AbstractString) -> AbstractString - :: - - unescape_string(s::AbstractString) -> AbstractString - General unescaping of traditional C and Unicode escape sequences. Reverse of ``escape_string()``. See also ``print_unescaped()``. -.. function:: utf16(s) +.. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - :: - - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. -.. function:: utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) +.. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - :: - - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. -.. function:: utf32(s) +.. function:: wstring(s) - :: - - wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. -.. function:: utf32(::Union{Ptr{Char},Ptr{UInt32},Ptr{Int32}} [, length]) +.. function:: wstring(s) - :: - - wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. .. function:: wstring(s) - :: - - wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst index e7cd69d6333a9..e4c89950d799c 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -12,12 +12,8 @@ binary install, you can run the test suite using ``Base.runtests()``. .. currentmodule:: Base -.. function:: runtests([tests=["all"] [, numcores=iceil(CPU_CORES/2) ]]) +.. function:: runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) - :: - - runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) - Run the Julia unit tests listed in ``tests``, which can be either a string or an array of strings, using ``numcores`` processors. (not exported) @@ -135,37 +131,21 @@ Macros .. function:: @test(ex) - :: - - @test(ex) - Test the expression ``ex`` and calls the current handler to handle the result. .. function:: @test_throws(extype, ex) - :: - - @test_throws(extype, ex) - Test that the expression ``ex`` throws an exception of type .. function:: @test_approx_eq(a, b) - :: - - @test_approx_eq(a, b) - Test two floating point numbers ``a`` and ``b`` for equality taking in account small numerical errors. .. function:: @test_approx_eq_eps(a, b, tol) - :: - - @test_approx_eq_eps(a, b, tol) - Test two floating point numbers ``a`` and ``b`` for equality taking in account a margin of tolerance given by ``tol``. @@ -174,10 +154,6 @@ Functions .. function:: with_handler(f, handler) - :: - - with_handler(f, handler) - Run the function ``f`` using the ``handler`` as the handler. From 97da3dc6222c2b6054c656da4bd258e959d3ef90 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 18:41:06 -0400 Subject: [PATCH 14/27] don't leave trailing whitespace --- doc/genstdlib.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl index a5c1d502186f5..6e656a3656237 100644 --- a/doc/genstdlib.jl +++ b/doc/genstdlib.jl @@ -55,7 +55,7 @@ function translate(file) println(io, sig == nothing ? l : ".. function:: $(sig.code)") println(io) for l in split(Markdown.rst(doc), "\n") - println(io, " ", l) + ismatch(r"^\s*$", l) ? println(io) : println(io, " ", l) end println(io) elseif doccing && (startswith(l, " ") || ismatch(r"^\s*$", l)) From af429c20021c83160d4c778043c03737128d09d5 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 18:41:17 -0400 Subject: [PATCH 15/27] get rid of those pesky whitespaces --- doc/stdlib/arrays.rst | 290 +++++++++---------- doc/stdlib/base.rst | 364 ++++++++++++------------ doc/stdlib/c.rst | 36 +-- doc/stdlib/collections.rst | 272 +++++++++--------- doc/stdlib/dates.rst | 114 ++++---- doc/stdlib/file.rst | 114 ++++---- doc/stdlib/io-network.rst | 238 ++++++++-------- doc/stdlib/libc.rst | 28 +- doc/stdlib/libdl.rst | 12 +- doc/stdlib/linalg.rst | 300 ++++++++++---------- doc/stdlib/math.rst | 562 ++++++++++++++++++------------------- doc/stdlib/numbers.rst | 132 ++++----- doc/stdlib/parallel.rst | 118 ++++---- doc/stdlib/pkg.rst | 54 ++-- doc/stdlib/profile.rst | 18 +- doc/stdlib/sort.rst | 26 +- doc/stdlib/strings.rst | 148 +++++----- doc/stdlib/test.rst | 12 +- 18 files changed, 1419 insertions(+), 1419 deletions(-) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index ac37b479c02a8..4c1f8476b7c84 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -10,27 +10,27 @@ Basic functions .. function:: ndims(A) -> Integer Returns the number of dimensions of A - + .. function:: size(A[, 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.: - + .. function:: iseltype(A, T) Tests whether A or its elements are of type T - + .. function:: length(s) The number of characters in string ``s``. - + .. function:: 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 (like ``Array``), this is simply the range ``1:length(A)``. For other array types, this returns a specialized Cartesian range to efficiently index into the array with indices specified for every dimension. Example for a sparse 2-d array: - + If you supply more than one ``AbstractArray`` argument, ``eachindex`` will create an iterable object that is fast for all arguments (a @@ -50,37 +50,37 @@ largest range along each dimension. .. function:: countnz(A) Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use ``nnz``, which returns the number of stored values. - + .. function:: conj!(A) Convert an array to its complex conjugate in-place - + .. function:: stride(A, k) Returns the distance in memory (in number of elements) between adjacent elements in dimension k - + .. function:: strides(A) Returns a tuple of the memory strides in each dimension - + .. function:: ind2sub(a, index) -> subscripts Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` - + .. function:: ind2sub(a, index) -> subscripts Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` - + .. function:: sub2ind(dims, i, j, k...) -> index The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts - + Constructors ------------ @@ -88,97 +88,97 @@ Constructors .. function:: Array(dims) element type ``T``. ``dims`` may be a tuple or a series of integer arguments. The syntax ``Array(T, dims)`` is also available, but deprecated. - + .. function:: 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, ...)``. - + .. function:: cell(dims) Construct an uninitialized cell array (heterogeneous array). - + .. function:: zeros(A) Create an array of all zeros with the same element type and shape as A. - + .. function:: zeros(A) Create an array of all zeros with the same element type and shape as A. - + .. function:: ones(A) Create an array of all ones with the same element type and shape as A. - + .. function:: ones(A) Create an array of all ones with the same element type and shape as A. - + .. function:: trues(dims) Create a ``BitArray`` with all values set to true - + .. function:: falses(dims) Create a ``BitArray`` with all values set to false - + .. function:: fill(x, dims) Create an array filled with the value ``x``. For example, element initialized to 1.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 evaluating ``Foo()`` once. - + .. function:: fill!(A, x) Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating - + .. function:: reshape(A, dims) Create an array with the same data as the given array, but with different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. - + .. function:: similar(array, element_type, dims) Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ranges), this function returns a standard ``Array`` to allow operating on elements. - + .. function:: reinterpret(type, A) Change the type-interpretation of a block of memory. For example, corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. - + .. function:: eye(A) Constructs an identity matrix of the same dimensions and type as - + .. function:: eye(A) Constructs an identity matrix of the same dimensions and type as - + .. function:: eye(A) Constructs an identity matrix of the same dimensions and type as - + .. function:: linspace(start, stop, n=100) Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. - + .. function:: logspace(start, stop, n=50) Construct a vector of ``n`` logarithmically spaced numbers from - + Mathematical operators and functions ------------------------------------ @@ -188,27 +188,27 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results - + .. function:: broadcast!(f, dest, As...) Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. Note that ``dest`` is only used to store the result, and does not supply arguments to ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform - + .. function:: bitbroadcast(f, As...) Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. - + .. function:: broadcast_function(f) Returns a function ``broadcast_f`` such that useful in the form ``const broadcast_f = broadcast_function(f)``. - + .. function:: broadcast!_function(f) Like ``broadcast_function``, but for ``broadcast!``. - + Indexing, Assignment, and Concatenation --------------------------------------- @@ -216,202 +216,202 @@ Indexing, Assignment, and Concatenation .. function:: 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, ...)``. - + .. function:: sub(A, inds...) Like ``getindex()``, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling computes the indices to the parent array on the fly without checking bounds. - + .. function:: parent(A) Returns the ``parent array`` of an array view type (e.g., SubArray), or the array itself if it is not a view - + .. function:: parentindexes(A) From an array view ``A``, returns the corresponding indexes in the parent - + .. function:: slicedim(A, d, i) Return all the data of ``A`` where the index for dimension ``d`` equals ``i``. Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``. - + .. function:: slice(A, inds...) Returns a view of array ``A`` with the given indices like - + .. function:: 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, ...)``. - + .. function:: broadcast_getindex(A, inds...) Broadcasts the ``inds`` arrays to a common size like ``broadcast``, and returns an array of the results ``A[ks...]``, where ``ks`` goes over the positions in the broadcast. - + .. function:: broadcast_setindex!(A, X, inds...) Broadcasts the ``X`` and ``inds`` arrays to a common size and stores the value from each position in ``X`` at the indices given by the same positions in ``inds``. - + .. function:: cat(dims, A...) Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. - + .. function:: vcat(A...) Concatenate along dimension 1 - + .. function:: hcat(A...) Concatenate along dimension 2 - + .. function:: 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. For example, If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. - + .. function:: flipdim(A, d) Reverse ``A`` in dimension ``d``. - + .. function:: circshift(A, shifts) Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. - + .. function:: find(f, A) Return a vector of the linear indexes of ``A`` where ``f`` returns true. - + .. function:: find(f, A) Return a vector of the linear indexes of ``A`` where ``f`` returns true. - + .. function:: findn(A) Return a vector of indexes for each dimension giving the locations of the non-zeros in ``A`` (determined by ``A[i]!=0``). - + .. function:: findnz(A) Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and column indexes of the non-zero values in matrix ``A``, and ``V`` is a vector of the non-zero values. - + .. function:: findfirst(predicate, A) Return the index of the first element of ``A`` for which - + .. function:: findfirst(predicate, A) Return the index of the first element of ``A`` for which - + .. function:: findfirst(predicate, A) Return the index of the first element of ``A`` for which - + .. function:: findlast(predicate, A) Return the index of the last element of ``A`` for which - + .. function:: findlast(predicate, A) Return the index of the last element of ``A`` for which - + .. function:: findlast(predicate, A) Return the index of the last element of ``A`` for which - + .. function:: findnext(A, v, i) Find the next index >= ``i`` of an element of ``A`` equal to ``v`` - + .. function:: findnext(A, v, i) Find the next index >= ``i`` of an element of ``A`` equal to ``v`` - + .. function:: findnext(A, v, i) Find the next index >= ``i`` of an element of ``A`` equal to ``v`` - + .. function:: findprev(A, v, i) Find the previous index <= ``i`` of an element of ``A`` equal to - + .. function:: findprev(A, v, i) Find the previous index <= ``i`` of an element of ``A`` equal to - + .. function:: findprev(A, v, i) Find the previous index <= ``i`` of an element of ``A`` equal to - + .. function:: permutedims(A, perm) Permute the dimensions of array ``A``. ``perm`` is a vector specifying a permutation of length ``ndims(A)``. This is a generalization of transpose for multi-dimensional arrays. Transpose is equivalent to ``permutedims(A, [2,1])``. - + .. function:: ipermutedims(A, perm) Like ``permutedims()``, except the inverse of the given permutation is applied. - + .. function:: permutedims!(dest, src, perm) Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. - + .. function:: squeeze(A, dims) Remove the dimensions specified by ``dims`` from array ``A``. Elements of ``dims`` must be unique and within the range - + .. function:: vec(Array) -> Vector Vectorize an array using column-major convention. - + .. function:: promote_shape(s1, s2) Check two array shapes for compatibility, allowing trailing singleton dimensions, and return whichever shape has more dimensions. - + .. function:: checkbounds(array, indexes...) Throw an error if the specified indexes are not in bounds for the given array. - + .. function:: randsubseq(A, p) -> Vector Return a vector consisting of a random subsequence of the given array ``A``, where each element of ``A`` is included (in order) with independent probability ``p``. (Complexity is linear in small and ``A`` is large.) Technically, this process is known as - + .. function:: randsubseq!(S, A, p) Like ``randsubseq``, but the results are stored in ``S`` (which is resized as needed). - + Array functions --------------- @@ -419,102 +419,102 @@ Array functions .. function:: cumprod(A[, dim]) Cumulative product along a dimension ``dim`` (defaults to 1). See also ``cumprod!()`` to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). - + .. function:: cumprod!(B, A[, dim]) Cumulative product of ``A`` along a dimension, storing the result in ``B``. The dimension defaults to 1. - + .. function:: cumsum(A[, dim]) Cumulative sum along a dimension ``dim`` (defaults to 1). See also performance and to control the precision of the output (e.g. to avoid overflow). - + .. function:: cumsum!(B, A[, dim]) Cumulative sum of ``A`` along a dimension, storing the result in - + .. function:: cumsum_kbn(A[, dim]) Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1. - + .. function:: cummin(A[, dim]) Cumulative minimum along a dimension. The dimension defaults to 1. - + .. function:: cummax(A[, dim]) Cumulative maximum along a dimension. The dimension defaults to 1. - + .. function:: diff(A[, dim]) Finite difference operator of matrix or vector. - + .. function:: gradient(F[, h]) Compute differences along vector ``F``, using ``h`` as the spacing between points. The default spacing is one. - + .. function:: rot180(A, k) Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. - + .. function:: rot180(A, k) Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. - + .. function:: rotl90(A, k) Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + .. function:: rotl90(A, k) Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + .. function:: rotr90(A, k) Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + .. function:: rotr90(A, k) Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + .. function:: reducedim(f, A, dims[, initial]) Reduce 2-argument function ``f`` along dimensions of ``A``. The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for ``reduce``. - + .. function:: mapreducedim(f, op, A, dims[, initial]) Evaluates to the same as *reducedim(op, map(f, A), dims, f(initial))*, but is generally faster because the intermediate array is avoided. - + .. function:: mapslices(f, A, dims) Transform the given dimensions of array ``A`` using function ``f``. where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if - + .. function:: sum_kbn(A) Returns the sum of all array elements, using the Kahan-Babuska- Neumaier compensated summation algorithm for additional accuracy. - + .. function:: cartesianmap(f, dims) Given a ``dims`` tuple of integers ``(m, n, ...)``, call ``f`` on all combinations of integers in the ranges ``1:m``, ``1:n``, etc. - + Combinatorics ------------- @@ -522,102 +522,102 @@ Combinatorics .. function:: nthperm(p) Return the ``k`` that generated permutation ``p``. Note that - + .. function:: nthperm(p) Return the ``k`` that generated permutation ``p``. Note that - + .. function:: nthperm!(v, k) In-place version of ``nthperm()``. - + .. function:: randperm([rng], n) Construct a random permutation of length ``n``. The optional Numbers*. - + .. function:: invperm(v) Return the inverse permutation of v. - + .. function:: isperm(v) -> Bool Returns true if v is a valid permutation. - + .. function:: permute!(v, p) Permute vector ``v`` in-place, according to permutation ``p``. No checking is done to verify that ``p`` is a permutation. To return a new permutation, use ``v[p]``. Note that this is generally faster than ``permute!(v,p)`` for large vectors. - + .. function:: ipermute!(v, p) Like permute!, but the inverse of the given permutation is applied. - + .. function:: randcycle([rng], n) Construct a random cyclic permutation of length ``n``. The optional Numbers*. - + .. function:: shuffle([rng], v) Return a randomly permuted copy of ``v``. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. - + .. function:: shuffle!([rng], v) In-place version of ``shuffle()``. - + .. function:: reverse(v[, start=1[, stop=length(v)]]) Return a copy of ``v`` reversed from start to stop. - + .. function:: reverseind(v, i) Given an index ``i`` in ``reverse(v)``, return the corresponding index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``. string.) - + .. function:: reverse!(v[, start=1[, stop=length(v)]]) -> v In-place version of ``reverse()``. - + .. function:: combinations(array, n) Generate all combinations of ``n`` elements from an indexable object. Because the number of combinations can be very large, this function returns an iterator object. Use combinations. - + .. function:: permutations(array) Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use ``collect(permutations(array))`` to get an array of all permutations. - + .. function:: partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + .. function:: partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + .. function:: partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + .. function:: partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + BitArrays --------- @@ -625,47 +625,47 @@ BitArrays .. function:: bitpack(A::AbstractArray{T, N}) -> BitArray Converts a numeric array to a packed boolean array - + .. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} Converts a packed boolean array to an array of booleans - + .. function:: flipbits!(B::BitArray{N}) -> BitArray{N} Performs a bitwise not operation on B. See *~ operator*. - + .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. - + .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. - + .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation. - + .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. - + .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. - + .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation. - + .. _stdlib-sparse: @@ -677,100 +677,100 @@ Sparse matrices support much of the same set of operations as dense matrices. Th .. function:: sparse(A) Convert an AbstractMatrix ``A`` into a sparse matrix. - + .. function:: sparsevec(A) Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. - + .. function:: sparsevec(A) Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. - + .. function:: issparse(S) Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. - + .. function:: sparse(A) Convert an AbstractMatrix ``A`` into a sparse matrix. - + .. function:: sparsevec(A) Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. - + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. - + .. function:: nnz(A) Returns the number of stored (filled) elements in a sparse matrix. - + .. function:: spzeros(m, n) Create a sparse matrix of size ``m x n``. This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. - + .. function:: spones(S) Create a sparse matrix with the same structure as that of ``S``, but with every nonzero element having the value ``1.0``. - + .. function:: speye(type, m[, n]) Create a sparse identity matrix of specified type of size ``m x m``. In case ``n`` is supplied, create a sparse identity matrix of size ``m x n``. - + .. function:: spdiagm(B, d[, m, n]) Construct a sparse diagonal matrix. ``B`` is a tuple of vectors containing the diagonals and ``d`` is a tuple containing the positions of the diagonals. In the case the input contains only one diagonaly, ``B`` can be a vector (instead of a tuple) and ``d`` can be the diagonal position (instead of a tuple), defaulting to 0 resulting sparse matrix. - + .. function:: sprand([rng], m, n, p[, rfn]) Create a random ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by by ``rfn``. The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. - + .. function:: sprandn(m, n, p) Create a random ``m`` by ``n`` sparse matrix with the specified nonzero values are sampled from the normal distribution. - + .. function:: sprandbool(m, n, p) Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being - + .. function:: etree(A[, post]) Compute the elimination tree of a symmetric sparse matrix ``A`` from ``triu(A)`` and, optionally, its post-ordering permutation. - + .. function:: symperm(A, p) Return the symmetric permutation of A, which is ``A[p,p]``. A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. - + .. function:: nonzeros(A) Return a vector of the structural nonzero values in sparse matrix matrix. The returned vector points directly to the internal nonzero storage of ``A``, and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``. - + .. function:: rowvals(A) Return a vector of the row indices of ``A``, and any modifications to the returned vector will mutate ``A`` as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See ``nonzeros(A)`` and ``nzrange(A, col)``. - + .. function:: nzrange(A, col) Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with ``nonzeros(A)`` and matrix - + diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 80546bcec5d31..864af07dea3b9 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -23,92 +23,92 @@ Getting Around .. function:: exit([code]) Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. - + .. function:: quit() Quit the program indicating that the processes completed successfully. This function calls ``exit(0)`` (see ``exit()``). - + .. function:: atexit(f) Register a zero-argument function to be called at exit. - + .. function:: atreplinit(f) Register a one-argument function to be called before the REPL interface is initialized in interactive sessions; this is useful to customize the interface. The argument of ``f`` is the REPL object. This function should be called from within the ``.juliarc.jl`` initialization file. - + .. function:: isinteractive() -> Bool Determine whether Julia is running an interactive session. - + .. function:: whos([Module,] [pattern::Regex]) Print information about exported global variables in a module, optionally restricted to those matching ``pattern``. - + .. function:: edit(function[, types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. - + .. function:: edit(function[, types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. - + .. function:: @edit() Evaluates the arguments to the function call, determines their types, and calls the ``edit`` function on the resulting expression - + .. function:: less(function[, types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. - + .. function:: less(function[, types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. - + .. function:: @less() Evaluates the arguments to the function call, determines their types, and calls the ``less`` function on the resulting expression - + .. function:: clipboard() -> AbstractString Return a string with the contents of the operating system clipboard - + .. function:: clipboard() -> AbstractString Return a string with the contents of the operating system clipboard - + .. function:: require(file::AbstractString...) Load source files once, in the context of the ``Main`` module, on every active node, searching standard locations for files. current ``include`` path but does not use it to search for files library code, and is implicitly called by ``using`` to load packages. When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``, then tries paths in the global array ``LOAD_PATH``. - + .. function:: reload(file::AbstractString) Like ``require``, except forces loading of files regardless of whether they have been loaded before. Typically used when interactively developing libraries. - + .. function:: include("file.jl") Evaluate the contents of a source file in the current context. During including, a task-local include path is set to the directory containing the file. Nested calls to ``include`` will search relative to that path. All paths refer to files on node 1 when running in parallel, and files will be fetched from node 1. This function is typically used to load source interactively, or to combine files in packages that are broken into multiple source files. - + .. function:: include_string(code::AbstractString) Like ``include``, except reads code from the given string rather than from a file. Since there is no file path involved, no path processing or fetching from node 1 is done. - + .. function:: help(name) @@ -121,42 +121,42 @@ Getting Around .. function:: which(symbol) Return the module in which the binding for the variable referenced by ``symbol`` was created. - + .. function:: which(symbol) Return the module in which the binding for the variable referenced by ``symbol`` was created. - + .. function:: @which() Applied to a function call, it evaluates the arguments to the specified function call, and returns the ``Method`` object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the ``which`` function. - + .. function:: methods(f[, types]) Returns the method table for ``f``. If ``types`` is specified, returns an array of methods whose types match. - + .. function:: methodswith(typ[, module or function][, showparents]) Return an array of methods with an argument of type ``typ``. If optional ``showparents`` is ``true``, also return arguments with a parent type of ``typ``, excluding type ``Any``. The optional second argument restricts the search to a particular module or function. - + .. function:: @show() Show an expression and result, returning the result - + .. function:: versioninfo([verbose::Bool]) Print information about the version of Julia in use. If the as well. - + .. function:: workspace() Replace the top-level module (``Main``) with a new one, providing a clean workspace. The previous ``Main`` module is made available as statement such as ``using LastMain.Package``. This function should only be used interactively. - + .. data:: ans @@ -169,112 +169,112 @@ All Objects .. function:: ===(x, y) See the ``is()`` operator - + .. function:: isa(x, type) -> Bool Determine whether ``x`` is of the given ``type``. - + .. function:: isequal(x, y) Similar to ``==``, except treats all floating-point ``NaN`` values as equal to each other, and treats ``-0.0`` as unequal to ``0.0``. The default implementation of ``isequal`` calls ``==``, so if you have a type that doesn't have these floating-point subtleties then you probably only need to define ``==``. hash(y)``. This typically means that if you define your own `==`` function then you must define a corresponding ``hash`` (and vice versa). Collections typically implement ``isequal`` by calling ``isequal`` recursively on all contents. Scalar types generally do not need to implement ``isequal`` separate from ``==``, unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on ``isnan``, ``signbit``, and ``==``). - + .. function:: isless(x, y) Test whether ``x`` is less than ``y``, according to a canonical total order. Values that are normally unordered, such as ``NaN``, are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``. Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as - + .. function:: ifelse(condition::Bool, x, y) Return ``x`` if ``condition`` is true, otherwise return ``y``. This differs from ``?`` or ``if`` in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using in generated code and provide higher performance in tight loops. - + .. function:: lexcmp(x, y) Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than lexicographically comparable types, and ``lexless`` will call - + .. function:: lexless(x, y) Determine whether ``x`` is lexicographically less than ``y``. - + .. function:: typeof(x) Get the concrete type of ``x``. - + .. function:: tuple(xs...) Construct a tuple of the given objects. - + .. function:: ntuple(f::Function, n) Create a tuple of length ``n``, computing each element as ``f(i)``, where ``i`` is the index of the element. - + .. function:: object_id(x) Get a unique integer id for ``x``. ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``. - + .. function:: hash(x[, h]) Compute an integer hash code such that ``isequal(x,y)`` implies code to be mixed with the result. New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``) to guarantee the property mentioned above. - + .. function:: finalizer(x, function) Register a function ``f(x)`` to be called when there are no program-accessible references to ``x``. The behavior of this function is unpredictable if ``x`` is of a bits type. - + .. function:: finalize(x) Immediately run finalizers registered for object ``x``. - + .. function:: copy(x) Create a shallow copy of ``x``: the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. - + .. function:: deepcopy(x) Create a deep copy of ``x``: everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling *deepcopy* on an object should generally have the same effect as serializing and then deserializing it. As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``, and the ``dict`` variable should be updated as appropriate before returning. - + .. function:: isdefined([object], index | symbol) Tests whether an assignable location is defined. The arguments can be an array and index, a composite object and field name (as a symbol), or a module and a symbol. With a single symbol argument, tests whether a global variable with that name is defined in - + .. function:: convert(T, x) Convert ``x`` to a value of type ``T``. If ``T`` is an ``Integer`` type, an ``InexactError`` will be raised if ``x`` is not representable by ``T``, for example if ``x`` is not integer-valued, or is outside the range supported by ``T``. If ``T`` is a ``FloatingPoint`` or ``Rational`` type, then it will return the closest value to ``x`` representable by ``T``. - + .. function:: promote(xs...) Convert all arguments to their common promotion type (if any), and return them all (as a tuple). - + .. function:: oftype(x, y) Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``). - + .. function:: widen(type | x) If the argument is a type, return a ``larger`` type (for numeric types, this will be a type with at least as much range and precision as the argument, and usually more). Otherwise the argument ``x`` is converted to ``widen(typeof(x))``. - + .. function:: identity(x) The identity function. Returns its argument. - + Types ----- @@ -282,117 +282,117 @@ Types .. function:: super(T::DataType) Return the supertype of DataType T - + .. function:: <:(T1, T2) Subtype operator, equivalent to ``issubtype(T1,T2)``. - + .. function:: <:(T1, T2) Subtype operator, equivalent to ``issubtype(T1,T2)``. - + .. function:: subtypes(T::DataType) Return a list of immediate subtypes of DataType T. Note that all currently loaded subtypes are included, including those not visible in the current module. - + .. function:: typemin(type) The lowest value representable by the given (real) numeric type. - + .. function:: typemax(type) The highest value representable by the given (real) numeric type. - + .. function:: realmin(type) The smallest in absolute value non-subnormal value representable by the given floating-point type - + .. function:: realmax(type) The highest finite value representable by the given floating-point type - + .. function:: maxintfloat(type) The largest integer losslessly representable by the given floating- point type - + .. function:: sizeof(s::AbstractString) The number of bytes in string ``s``. - + .. function:: eps(::DateTime) -> Millisecond Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. - + .. function:: eps(::DateTime) -> Millisecond Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. - + .. function:: promote_type(type1, type2) Determine a type big enough to hold values of each argument type without loss, whenever possible. In some cases, where no type exists to which both types can be promoted losslessly, some loss is tolerated; for example, ``promote_type(Int64,Float64)`` returns represented exactly as ``Float64`` values. - + .. function:: promote_rule(type1, type2) Specifies what type should be used by ``promote`` when given values of types ``type1`` and ``type2``. This function should not be called directly, but should have definitions added to it for new types as appropriate. - + .. function:: getfield(value, name::Symbol) Extract a named field from a value of composite type. The syntax - + .. function:: setfield!(value, name::Symbol, x) Assign ``x`` to a named field in ``value`` of composite type. The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``, and the syntax - + .. function:: fieldoffsets(type) The byte offset of each field of a type relative to the data start. For example, we could use it in the following manner to summarize information about a struct type: - + .. function:: fieldtype(type, name::Symbol | index::Int) Determine the declared type of a field (specified by name or index) in a composite type. - + .. function:: isimmutable(v) True if value ``v`` is immutable. See *Immutable Composite Types* for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of - + .. function:: isbits(T) True if ``T`` is a ``plain data`` type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as ``UInt8``, ``Float64``, and - + .. function:: isleaftype(T) Determine whether ``T`` is a concrete type that can have instances, meaning its only subtypes are itself and ``None`` (but ``T`` itself is not ``None``). - + .. function:: typejoin(T, S) Compute a type that contains both ``T`` and ``S``. - + .. function:: typeintersect(T, S) Compute a type that contains the intersection of ``T`` and ``S``. Usually this will be the smallest such type or one close to it. - + .. function:: Val{c} @@ -419,7 +419,7 @@ Types .. function:: instances(T::Type) Return a collection of all instances of the given type, if applicable. Mostly used for enumerated types (see ``@enum``). - + Generic Functions ----------------- @@ -427,27 +427,27 @@ Generic Functions .. function:: method_exists(f, Tuple type) -> Bool Determine whether the given generic function has a method matching the given ``Tuple`` of argument types. - + .. function:: applicable(f, args...) -> Bool Determine whether the given generic function has a method applicable to the given arguments. - + .. function:: invoke(f, (types...), args...) Invoke a method for the given generic function matching the specified types (as a tuple), on the specified arguments. The arguments must be compatible with the specified types. This allows invoking a method other than the most specific matching method, which is useful when the behavior of a more general definition is explicitly needed (often as part of the implementation of a more specific method of the same function). - + .. function:: |>(x, f) Applies a function to the preceding argument. This allows for easy function chaining. - + .. function:: call(x, args...) If ``x`` is not a ``Function``, then ``x(args...)`` is equivalent to ``call(x, args...)``. This means that function-like behavior can be added to any type by defining new ``call`` methods. - + Syntax ------ @@ -455,42 +455,42 @@ Syntax .. function:: eval([m::Module], expr::Expr) Evaluate an expression in the given module and return the result. Every module (except those defined with ``baremodule``) has its own 1-argument definition of ``eval``, which evaluates expressions in that module. - + .. function:: @eval() Evaluate an expression and return the value. - + .. function:: evalfile(path::AbstractString) Load the file using ``include``, evaluate all expressions, and return the value of the last one. - + .. function:: esc(e::ANY) Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the *Macros* section of the Metaprogramming chapter of the manual for more details and examples. - + .. function:: gensym([tag]) Generates a symbol which will not conflict with other variable names. - + .. function:: @gensym() Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym(``x``); y = gensym(``y``)``. - + .. function:: parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. - + .. function:: parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. - + Nullables --------- @@ -498,22 +498,22 @@ Nullables .. function:: Nullable(x) Wrap value ``x`` in an object of type ``Nullable``, which indicates whether a value is present. ``Nullable(x)`` yields a non-empty wrapper, and ``Nullable{T}()`` yields an empty instance of a wrapper that might contain a value of type ``T``. - + .. 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: - + .. 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: - + .. function:: isnull(x) Is the ``Nullable`` object ``x`` null, i.e. missing a value? - + System ------ @@ -521,12 +521,12 @@ System .. function:: run(command) Run a command object, constructed with backticks. Throws an error if anything goes wrong, including the process exiting with a non- zero status. - + .. function:: spawn(command) Run a command object asynchronously, returning the resulting - + .. data:: DevNull @@ -536,32 +536,32 @@ System .. function:: success(command) Run a command object, constructed with backticks, and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started. - + .. function:: process_running(p::Process) Determine whether a process is currently running. - + .. function:: process_exited(p::Process) Determine whether a process has exited. - + .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. - + .. function:: open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - + .. function:: open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - + .. function:: Sys.set_process_title(title::AbstractString) @@ -574,107 +574,107 @@ System .. function:: readandwrite(command) Starts running a command asynchronously, and returns a tuple process, and the process object itself. - + .. function:: ignorestatus(command) Mark a command object so that running it will not throw an error if the result code is non-zero. - + .. function:: detach(command) Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. - + .. function:: setenv(command, env; dir=working_dir) Set environment variables to use when running the given command. of strings of the form ``var=val``, or zero or more replace) the existing environment, create ``env`` by ``copy(ENV)`` and then setting ``env[``var``]=val`` as desired, or use The ``dir`` keyword argument can be used to specify a working directory for the command. - + .. function:: withenv(f::Function, kv::Pair...) Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``var``=>val` arguments ``kv``. ``withenv`` is generally used via the be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. - + .. function:: pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. - + .. function:: pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. - + .. function:: gethostname() -> AbstractString Get the local machine's host name. - + .. function:: getipaddr() -> AbstractString Get the IP address of the local machine, as a string of the form - + .. function:: getpid() -> Int32 Get julia's process ID. - + .. function:: time(t::TmStruct) Converts a ``TmStruct`` struct to a number of seconds since the epoch. - + .. function:: time_ns() Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. - + .. function:: tic() Set a timer to be read by the next call to ``toc()`` or ``toq()``. The macro call ``@time expr`` can also be used to time evaluation. - + .. function:: toc() Print and return the time elapsed since the last ``tic()``. - + .. function:: toq() Return, but do not print, the time elapsed since the last - + .. function:: @time() A macro to execute an expression, printing the time it took to execute, the number of allocations, and the total number of bytes its execution caused to be allocated, before returning the value of the expression. - + .. function:: @timev() This is a verbose version of the ``@time`` macro, it first prints the same information as ``@time``, then any non-zero memory allocation counters, and then returns the value of the expression. - + .. function:: @timed() A macro to execute an expression, and return the value of the expression, elapsed time, total bytes allocated, garbage collection time, and an object with various memory allocation counters. - + .. function:: @elapsed() A macro to evaluate an expression, discarding the resulting value, instead returning the number of seconds it took to execute as a floating-point number. - + .. function:: @allocated() A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the ``@time`` macros, which do not try to adjust for the effects of compilation. - + .. function:: EnvHash() -> EnvHash A singleton of this type provides a hash table interface to environment variables. - + .. data:: ENV @@ -683,22 +683,22 @@ System .. function:: @unix() Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + .. function:: @osx() Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + .. function:: @linux() Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + .. function:: @windows() Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + Errors ------ @@ -706,32 +706,32 @@ Errors .. function:: error(message::AbstractString) Raise an ``ErrorException`` with the given message - + .. function:: throw(e) Throw an object as an exception - + .. function:: rethrow([e]) Throw an object without changing the current exception backtrace. The default argument is the current exception (if called within a - + .. function:: backtrace() Get a backtrace object for the current program point. - + .. function:: catch_backtrace() Get the backtrace of the current exception, for use within - + .. function:: assert(cond) Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. - + .. function:: @assert cond [text] @@ -740,122 +740,122 @@ Errors .. function:: ArgumentError(msg) The parameters to a function call do not match a valid signature. - + .. function:: AssertionError([msg]) The asserted condition did not evalutate to ``true``. - + .. function:: BoundsError([a][, i]) An indexing operation into an array, ``a``, tried to access an out- of-bounds element, ``i``. - + .. function:: DimensionMismatch([msg]) The objects called do not have matching dimensionality. - + .. function:: DivideError() Integer division was attempted with a denominator value of 0. - + .. function:: DomainError() The arguments to a function or constructor are outside the valid domain. - + .. function:: EOFError() No more data was available to read from a file or stream. - + .. function:: ErrorException(msg) Generic error type. The error message, in the *.msg* field, may provide more specific details. - + .. function:: InexactError() Type conversion cannot be done exactly. - + .. function:: InterruptException() The process was stopped by a terminal interrupt (CTRL+C). - + .. function:: KeyError(key) An indexing operation into an ``Associative`` (``Dict``) or ``Set`` like object tried to access or delete a non-existent element. - + .. function:: LoadError(file::AbstractString, line::Int, error) An error occurred while *including*, *requiring*, or *using* a file. The error specifics should be available in the *.error* field. - + .. function:: MethodError(f, args) A method with the required type signature does not exist in the given generic function. - + .. function:: NullException() An attempted access to a ``Nullable`` with no defined value. - + .. function:: OutOfMemoryError() An operation allocated too much memory for either the system or the garbage collector to handle properly. - + .. function:: ReadOnlyMemoryError() An operation tried to write to memory that is read-only. - + .. function:: OverflowError() The result of an expression is too large for the specified type and will cause a wraparound. - + .. function:: ParseError(msg) The expression passed to the *parse* function could not be interpreted as a valid Julia expression. - + .. function:: ProcessExitedException() After a client Julia process has exited, further attempts to reference the dead child will throw this exception. - + .. function:: StackOverflowError() The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. - + .. function:: SystemError(prefix::AbstractString[, errnum::Int32]) A system call failed with an error code (in the ``errno`` global variable). - + .. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) A type assertion failure, or calling an intrinsic function with an incorrect argument type. - + .. function:: UndefRefError() The item or field is not defined for the given object. - + .. function:: UndefVarError(var::Symbol) A symbol in the current scope is not defined. - + Events ------ @@ -863,12 +863,12 @@ Events .. function:: Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling - + .. function:: Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling - + Reflection ---------- @@ -876,67 +876,67 @@ Reflection .. function:: module_name(m::Module) -> Symbol Get the name of a module as a symbol. - + .. function:: module_parent(m::Module) -> Module Get a module's enclosing module. ``Main`` is its own parent. - + .. function:: current_module() -> Module Get the *dynamically* current module, which is the module code is currently being read from. In general, this is not the same as the module containing the call to this function. - + .. function:: fullname(m::Module) Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and - + .. function:: names(x::Module[, all=false[, imported=false]]) Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. - + .. function:: nfields(x::DataType) -> Int Get the number of fields of a data type. - + .. function:: fieldnames(x::DataType) Get an array of the fields of a data type. - + .. function:: isconst([m::Module], s::Symbol) -> Bool Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``. - + .. function:: isgeneric(f::Function) -> Bool Determine whether a function is generic. - + .. function:: function_name(f::Function) -> Symbol Get the name of a generic function as a symbol, or ``:anonymous``. - + .. function:: function_module(f::Function, types) -> Module Determine the module containing a given definition of a generic function. - + .. function:: functionloc(m::Method) Returns a tuple ``(filename,line)`` giving the location of a method definition. - + .. function:: functionloc(m::Method) Returns a tuple ``(filename,line)`` giving the location of a method definition. - + Internals --------- @@ -944,75 +944,75 @@ Internals .. function:: gc() Perform garbage collection. This should not generally be used. - + .. function:: gc_enable(on::Bool) Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Returns previous GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. - + .. function:: macroexpand(x) Takes the expression x and returns an equivalent expression with all macros removed (expanded). - + .. function:: expand(x) Takes the expression x and returns an equivalent expression in lowered form - + .. function:: code_lowered(f, types) Returns an array of lowered ASTs for the methods matching the given generic function and type signature. - + .. function:: @code_lowered() Evaluates the arguments to the function call, determines their types, and calls ``code_lowered()`` on the resulting expression - + .. function:: code_typed(f, types; optimize=true) Returns an array of lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The keyword argument ``optimize`` controls whether additional optimizations, such as inlining, are also applied. - + .. function:: @code_typed() Evaluates the arguments to the function call, determines their types, and calls ``code_typed()`` on the resulting expression - + .. function:: code_warntype(f, types) Displays lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The ASTs are annotated in such a way as to cause ``non-leaf`` types to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability. Not all non-leaf types are particularly problematic for performance, so the results need to be used judiciously. See *@code_warntype* for more information. - + .. function:: @code_warntype() Evaluates the arguments to the function call, determines their types, and calls ``code_warntype()`` on the resulting expression - + .. function:: code_llvm(f, types) Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to ``STDOUT``. All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. - + .. function:: @code_llvm() Evaluates the arguments to the function call, determines their types, and calls ``code_llvm()`` on the resulting expression - + .. function:: code_native(f, types) Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. - + .. function:: @code_native() Evaluates the arguments to the function call, determines their types, and calls ``code_native()`` on the resulting expression - + .. function:: precompile(f, args::Tuple{Vararg{Any}}) Compile the given function ``f`` for the argument tuple (of types) - + diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index 5b67f29eb50ec..a3bc015f733fc 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -7,92 +7,92 @@ .. function:: ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) Call function in C-exported shared library, specified by AbstractString or :Symbol. Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. Each ``ArgumentValue`` to the ``ccall`` will be converted to the corresponding ``ArgumentType``, by automatic insertion of calls to ArgumentValue))``. (see also the documentation for each of these functions for further details). In most cases, this simply results in a call to `convert(ArgumentType, ArgumentValue)`` - + .. function:: cglobal((symbol, library)[, type=Void]) Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ``ccall``. Returns a supplied. The values can be read or written by ``unsafe_load`` or - + .. function:: cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically. For example: - + .. function:: unsafe_convert(T, x) Convert ``x`` to a value of type ``T`` In cases where ``convert`` would need to take a Julia object and turn it into a ``Ptr``, this function should be used to define and perform that conversion. Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. Accordingly, the argument ``x`` to this function should never be an expression, only a variable name or field reference. For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. The ``unsafe`` prefix on this function indicates that using the result of this function after the ``x`` argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time. - + .. function:: cconvert(T, x) Convert ``x`` to a value of type ``T``, typically by calling In cases where ``x`` cannot be safely converted to ``T``, unlike from ``T``, which however is suitable for ``unsafe_convert`` to handle. Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``. - + .. function:: unsafe_load(p::Ptr{T}, i::Integer) Load a value of type ``T`` from the address of the ith element expression ``p[i-1]``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C. - + .. function:: unsafe_store!(p::Ptr{T}, x, i::Integer) Store a value of type ``T`` to the address of the ith element expression ``p[i-1] = x``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. - + .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. - + .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. - + .. function:: copy!(dest, do, src, so, N) Copy ``N`` elements from collection ``src`` starting at offset - + .. function:: copy!(dest, do, src, so, N) Copy ``N`` elements from collection ``src`` starting at offset - + .. function:: pointer(array[, index]) Get the native address of an array or string element. Be careful to ensure that a julia reference to ``a`` exists as long as this pointer will be used. This function is ``unsafe`` like Calling ``Ref(array[, index])`` is generally preferable to this function. - + .. function:: pointer_to_array(pointer, dims[, take_ownership::Bool]) Wrap a native pointer as a Julia Array object. The pointer element type determines the array element type. ``own`` optionally specifies whether Julia should take ownership of the memory, calling ``free`` on the pointer when the array is no longer referenced. - + .. function:: pointer_from_objref(object_instance) Get the memory address of a Julia object as a ``Ptr``. The existence of the resulting ``Ptr`` will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that the ``Ptr`` will be used. - + .. function:: unsafe_pointer_to_objref(p::Ptr) Convert a ``Ptr`` to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined behavior results, hence this function is considered - + .. function:: disable_sigint(f::Function) Disable Ctrl-C handler during execution of a function, for calling external code that is not interrupt safe. Intended to be called using ``do`` block syntax as follows: - + .. function:: reenable_sigint(f::Function) Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of ``disable_sigint``. - + .. function:: systemerror(sysfunc, iftrue) Raises a ``SystemError`` for ``errno`` with the descriptive string - + .. data:: Ptr{T} diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index a21ab57d193f7..3d41c2eb7cd09 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -27,57 +27,57 @@ The ``state`` object may be anything, and should be chosen appropriately for eac .. function:: start(iter) -> state Get initial iteration state for an iterable object - + .. function:: done(iter, state) -> Bool Test whether we are done iterating - + .. function:: next(iter, state) -> item, state For a given iterable object and iteration state, return the current item and the next iteration state - + .. function:: zip(iters...) For a set of iterable objects, returns an iterable of tuples, where the ``i``th tuple contains the ``i``th component of each input iterable. Note that ``zip()`` is its own inverse: - + .. function:: enumerate(iter) An iterator that yields ``(i, x)`` where ``i`` is an index starting at 1, and ``x`` is the ``i``th value from the given iterator. It's useful when you need not only the values ``x`` over which you are iterating, but also the index ``i`` of the iterations. - + .. function:: rest(iter, state) An iterator that yields the same elements as ``iter``, but starting at the given ``state``. - + .. function:: countfrom(start=1, step=1) An iterator that counts forever, starting at ``start`` and incrementing by ``step``. - + .. function:: take(iter, n) An iterator that generates at most the first ``n`` elements of - + .. function:: drop(iter, n) An iterator that generates all but the first ``n`` elements of - + .. function:: cycle(iter) An iterator that cycles through ``iter`` forever. - + .. function:: repeated(x[, n::Int]) An iterator that generates the value ``x`` forever. If ``n`` is specified, generates ``x`` that many times (equivalent to - + Fully implemented by: @@ -102,22 +102,22 @@ General Collections .. function:: isempty(collection) -> Bool Determine whether a collection is empty (has no elements). - + .. function:: empty!(collection) -> collection Remove all elements from a ``collection``. - + .. function:: length(s) The number of characters in string ``s``. - + .. function:: endof(collection) -> Integer Returns the last index of the collection. - + Fully implemented by: @@ -138,347 +138,347 @@ Iterable Collections .. function:: in(item, collection) -> Bool Determine whether an item is in the given collection, in the sense that it is ``==`` to one of the values generated by iterating over the collection. Some collections need a slightly different definition; for example ``Set``s check whether the item To test for the presence of a key in a dictionary, use ``haskey()`` or ``k in keys(dict)``. - + .. 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 ``(key,value)`` tuple type. The definition that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types. - + .. 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``. - + .. function:: findin(a, b) Returns the indices of elements in collection ``a`` that appear in collection ``b`` - + .. function:: 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``. - + .. function:: 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``. - + .. function:: 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``. - + .. function:: 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 - + .. function:: 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 - + .. function:: 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 - + .. function:: 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 - + .. function:: maximum(A, dims) Compute the maximum value of an array over the given dimensions. - + .. function:: maximum(A, dims) Compute the maximum value of an array over the given dimensions. - + .. function:: maximum!(r, A) Compute the maximum value of ``A`` over the singleton dimensions of - + .. function:: minimum(A, dims) Compute the minimum value of an array over the given dimensions. - + .. function:: minimum(A, dims) Compute the minimum value of an array over the given dimensions. - + .. function:: minimum!(r, A) Compute the minimum value of ``A`` over the singleton dimensions of - + .. function:: extrema(itr) Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. - + .. function:: indmax(itr) -> Integer Returns the index of the maximum element in a collection. - + .. function:: indmin(itr) -> Integer Returns the index of the minimum element in a collection. - + .. function:: findmax(A, dims) -> (maxval, index) For an array input, returns the value and index of the maximum over the given dimensions. - + .. function:: findmax(A, dims) -> (maxval, index) For an array input, returns the value and index of the maximum over the given dimensions. - + .. function:: findmin(A, dims) -> (minval, index) For an array input, returns the value and index of the minimum over the given dimensions. - + .. function:: findmin(A, dims) -> (minval, index) For an array input, returns the value and index of the minimum over the given dimensions. - + .. function:: maxabs(A, dims) Compute the maximum absolute values over given dimensions. - + .. function:: maxabs(A, dims) Compute the maximum absolute values over given dimensions. - + .. function:: maxabs!(r, A) Compute the maximum absolute values over the singleton dimensions of ``r``, and write values to ``r``. - + .. function:: minabs(A, dims) Compute the minimum absolute values over given dimensions. - + .. function:: minabs(A, dims) Compute the minimum absolute values over given dimensions. - + .. function:: minabs!(r, A) Compute the minimum absolute values over the singleton dimensions of ``r``, and write values to ``r``. - + .. function:: sum(f, itr) Sum the results of calling function ``f`` on each element of - + .. function:: sum(f, itr) Sum the results of calling function ``f`` on each element of - + .. function:: sum!(r, A) Sum elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + .. function:: sum(f, itr) Sum the results of calling function ``f`` on each element of - + .. function:: sumabs(A, dims) Sum absolute values of elements of an array over the given dimensions. - + .. function:: sumabs(A, dims) Sum absolute values of elements of an array over the given dimensions. - + .. function:: sumabs!(r, A) Sum absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + .. function:: sumabs2(A, dims) Sum squared absolute values of elements of an array over the given dimensions. - + .. function:: sumabs2(A, dims) Sum squared absolute values of elements of an array over the given dimensions. - + .. function:: sumabs2!(r, A) Sum squared absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + .. function:: prod(A, dims) Multiply elements of an array over the given dimensions. - + .. function:: prod(A, dims) Multiply elements of an array over the given dimensions. - + .. function:: prod!(r, A) Multiply elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + .. function:: any(p, itr) -> Bool Determine whether predicate ``p`` returns true for any elements of - + .. function:: any(p, itr) -> Bool Determine whether predicate ``p`` returns true for any elements of - + .. function:: any!(r, A) Test whether any values in ``A`` along the singleton dimensions of - + .. function:: all(p, itr) -> Bool Determine whether predicate ``p`` returns true for all elements of - + .. function:: all(p, itr) -> Bool Determine whether predicate ``p`` returns true for all elements of - + .. function:: all!(r, A) Test whether all values in ``A`` along the singleton dimensions of - + .. function:: count(p, itr) -> Integer Count the number of elements in ``itr`` for which predicate ``p`` returns true. - + .. function:: any(p, itr) -> Bool Determine whether predicate ``p`` returns true for any elements of - + .. function:: all(p, itr) -> Bool Determine whether predicate ``p`` returns true for all elements of - + .. function:: map(f, c...) -> collection Transform collection ``c`` by applying ``f`` to each element. For multiple collection arguments, apply ``f`` elementwise. - + .. 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. - + .. 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. - + .. function:: mapreduce(f, op, itr) Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). - + .. function:: mapreduce(f, op, itr) Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). - + .. function:: mapfoldl(f, op, itr) Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). - + .. function:: mapfoldl(f, op, itr) Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). - + .. function:: mapfoldr(f, op, itr) Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). - + .. function:: mapfoldr(f, op, itr) Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(op, itr)``). - + .. function:: first(coll) Get the first element of an iterable collection. Returns the start point of a ``Range`` even if it is empty. - + .. 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. - + .. function:: step(r) Get the step size of a ``Range`` object. - + .. function:: collect(element_type, collection) Return an array of type ``Array{element_type,1}`` of all items in a collection. - + .. function:: collect(element_type, collection) Return an array of type ``Array{element_type,1}`` of all items in a collection. - + .. function:: issubset(A, S) -> Bool True if A is a subset of or equal to S. - + .. function:: filter(function, collection) Return a copy of ``collection``, removing elements for which passed two arguments (key and value). - + .. 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). - + Indexable Collections --------------------- @@ -486,12 +486,12 @@ Indexable Collections .. function:: 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, ...)``. - + .. function:: 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, ...)``. - + Fully implemented by: @@ -531,22 +531,22 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: Dict([itr]) 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. Alternatively, a sequence of pair arguments may be passed. - + .. function:: haskey(collection, key) -> Bool Determine whether a collection has a mapping for a given key. - + .. 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: - + .. 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: - + time() end @@ -554,12 +554,12 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: 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: - + .. function:: 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: - + time() end @@ -567,42 +567,42 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: getkey(collection, key, default) Return the key matching argument ``key`` if one exists in - + .. function:: delete!(collection, key) Delete the mapping for the given key in a collection, and return the collection. - + .. function:: pop!(collection) -> item Remove the last item in ``collection`` and return it. - + .. function:: keys(collection) Return an iterator over all keys in a collection. - + .. function:: values(collection) Return an iterator over all values in a collection. - + .. function:: merge(collection, others...) 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. - + .. function:: merge!(collection, others...) Update collection with pairs from the other collections - + .. function:: sizehint!(s, n) Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. - + Fully implemented by: @@ -624,77 +624,77 @@ Set-Like Collections .. function:: 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. - + .. function:: IntSet([itr]) Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use ``Set`` instead. - + .. function:: union(s1, s2...) Construct the union of two or more sets. Maintains order with arrays. - + .. function:: union!(s, iterable) Union each element of ``iterable`` into set ``s`` in-place. - + .. function:: intersect(s1, s2...) Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. - + .. function:: setdiff(s1, s2) Construct the set of elements in ``s1`` but not ``s2``. Maintains order with arrays. Note that both arguments must be collections, and both will be iterated over. In particular, - + .. function:: setdiff!(s, iterable) Remove each element of ``iterable`` from set ``s`` in-place. - + .. function:: symdiff(s1, s2...) Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. - + .. function:: symdiff!(s1, s2) Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - + .. function:: symdiff!(s1, s2) Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - + .. function:: symdiff!(s1, s2) Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - + .. function:: complement(s) Returns the set-complement of ``IntSet`` ``s``. - + .. function:: complement!(s) Mutates ``IntSet`` ``s`` into its set-complement. - + .. function:: intersect!(s1, s2) Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of - + .. function:: issubset(A, S) -> Bool True if A is a subset of or equal to S. - + Fully implemented by: @@ -711,62 +711,62 @@ Dequeues .. function:: push!(collection, items...) -> collection Insert one or more ``items`` at the end of ``collection``. Use ``append!()`` to add all the elements of another collection to to ``append!([1, 2, 3], [4, 5, 6])``. - + .. function:: pop!(collection) -> item Remove the last item in ``collection`` and return it. - + .. function:: unshift!(collection, items...) -> collection Insert one or more ``items`` at the beginning of ``collection``. - + .. function:: shift!(collection) -> item Remove the first ``item`` from ``collection``. - + .. function:: insert!(collection, index, item) Insert an ``item`` into ``collection`` at the given ``index``. - + .. function:: deleteat!(collection, itr) Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. - + .. function:: deleteat!(collection, itr) Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. - + .. function:: splice!(collection, range[, replacement]) -> items Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. - + .. function:: splice!(collection, range[, replacement]) -> items Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. - + .. function:: resize!(collection, n) -> collection Resize ``collection`` 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. - + .. function:: append!(collection, collection2) -> collection. Add the elements of ``collection2`` to the end of ``collection``. 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)``. - + .. function:: prepend!(collection, items) -> collection Insert the elements of ``items`` to the beginning of - + Fully implemented by: @@ -786,22 +786,22 @@ changed efficiently. .. function:: PriorityQueue(K, V[, ord]) Construct a new ``PriorityQueue``, with keys of type ``K`` and values/priorites of type ``V``. If an order is not given, the priority queue is min-ordered using the default comparison for - + .. function:: enqueue!(pq, k, v) Insert the a key ``k`` into a priority queue ``pq`` with priority - + .. function:: dequeue!(pq) Remove and return the lowest priority key from a priority queue. - + .. function:: peek(pq) Return the lowest priority key from a priority queue without removing that key from the queue. - + :obj:`PriorityQueue` also behaves similarly to a :obj:`Dict` in that keys can be inserted and priorities accessed or changed using indexing notation. @@ -836,25 +836,25 @@ is used, so that elements popped from the heap are given in ascending order. .. function:: heapify(v[, ord]) Return a new vector in binary heap order, optionally using the given ordering. - + .. function:: heapify!(v[, ord]) In-place ``heapify()``. - + .. function:: isheap(v[, ord]) Return true iff an array is heap-ordered according to the given order. - + .. function:: heappush!(v, x[, ord]) Given a binary heap-ordered array, push a new element ``x``, preserving the heap property. For efficiency, this function does not check that the array is indeed heap-ordered. - + .. function:: heappop!(v[, ord]) Given a binary heap-ordered array, remove and return the lowest ordered element. For efficiency, this function does not check that the array is indeed heap-ordered. - + diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index 24260a383a1f0..87f13fa81d34f 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -50,27 +50,27 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + .. function:: Dates.DateFormat(format::AbstractString) -> DateFormat @@ -79,52 +79,52 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + .. function:: now(::Type{UTC}) -> DateTime Returns a DateTime corresponding to the user's system time as UTC/GMT. - + .. function:: now(::Type{UTC}) -> DateTime Returns a DateTime corresponding to the user's system time as UTC/GMT. - + .. function:: eps(::DateTime) -> Millisecond Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. - + Accessor Functions ~~~~~~~~~~~~~~~~~~ @@ -132,27 +132,27 @@ Accessor Functions .. function:: year(dt::TimeType) -> Int64 Return the field part of a Date or DateTime as an ``Int64``. - + .. function:: Year(v) Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. - + .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) Simultaneously return the year and month parts of a Date or DateTime. - + .. function:: monthday(dt::TimeType) -> (Int64, Int64) Simultaneously return the month and day parts of a Date or DateTime. - + .. function:: yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) Simultaneously return the year, month, and day parts of a Date or DateTime. - + Query Functions ~~~~~~~~~~~~~~~ @@ -160,144 +160,144 @@ Query Functions .. function:: dayname(dt::TimeType; locale="english") -> AbstractString Return the full day name corresponding to the day of the week of the Date or DateTime in the given ``locale``. - + .. function:: dayabbr(dt::TimeType; locale="english") -> AbstractString Return the abbreviated name corresponding to the day of the week of the Date or DateTime in the given ``locale``. - + .. function:: dayofweek(dt::TimeType) -> Int64 Returns the day of the week as an ``Int64`` with ``1 = Monday, 2 = Tuesday, etc.``. - + .. function:: dayofweekofmonth(dt::TimeType) -> Int For the day of week of ``dt``, returns which number it is in etc.` In the range 1:5. - + .. function:: daysofweekinmonth(dt::TimeType) -> Int For the day of week of ``dt``, returns the total number of that day of the week in ``dt``'s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by including ``dayofweekofmonth(dt) == daysofweekinmonth(dt)`` in the adjuster function. - + .. function:: monthname(dt::TimeType; locale="english") -> AbstractString Return the full name of the month of the Date or DateTime in the given ``locale``. - + .. function:: monthabbr(dt::TimeType; locale="english") -> AbstractString Return the abbreviated month name of the Date or DateTime in the given ``locale``. - + .. function:: daysinmonth(dt::TimeType) -> Int Returns the number of days in the month of ``dt``. Value will be 28, 29, 30, or 31. - + .. function:: isleapyear(dt::TimeType) -> Bool Returns true if the year of ``dt`` is a leap year. - + .. function:: dayofyear(dt::TimeType) -> Int Returns the day of the year for ``dt`` with January 1st being day 1. - + .. function:: daysinyear(dt::TimeType) -> Int Returns 366 if the year of ``dt`` is a leap year, otherwise returns 365. - + .. function:: quarterofyear(dt::TimeType) -> Int Returns the quarter that ``dt`` resides in. Range of value is 1:4. - + .. function:: dayofquarter(dt::TimeType) -> Int Returns the day of the current quarter of ``dt``. Range of value is 1:92. - + Adjuster Functions ~~~~~~~~~~~~~~~~~~ .. function:: trunc([T], x[, digits[, base]]) - + .. function:: firstdayofweek(dt::TimeType) -> TimeType Adjusts ``dt`` to the Monday of its week. - + .. function:: lastdayofweek(dt::TimeType) -> TimeType Adjusts ``dt`` to the Sunday of its week. - + .. function:: firstdayofmonth(dt::TimeType) -> TimeType Adjusts ``dt`` to the first day of its month. - + .. function:: lastdayofmonth(dt::TimeType) -> TimeType Adjusts ``dt`` to the last day of its month. - + .. function:: firstdayofyear(dt::TimeType) -> TimeType Adjusts ``dt`` to the first day of its year. - + .. function:: lastdayofyear(dt::TimeType) -> TimeType Adjusts ``dt`` to the last day of its year. - + .. function:: firstdayofquarter(dt::TimeType) -> TimeType Adjusts ``dt`` to the first day of its quarter. - + .. function:: lastdayofquarter(dt::TimeType) -> TimeType Adjusts ``dt`` to the last day of its quarter. - + .. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + .. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + .. function:: tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType Adjusts ``dt`` to the first ``dow`` of its month. Alternatively, - + .. function:: tolast(dt::TimeType, dow::Int;of=Month) -> TimeType Adjusts ``dt`` to the last ``dow`` of its month. Alternatively, - + .. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + .. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + .. function:: recur{T<:TimeType}(func::Function,dr::StepRange{T};negate=false,limit=10000) -> Vector{T} @@ -313,12 +313,12 @@ Periods .. function:: Year(v) Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. - + .. function:: default(p::Period) -> Period Returns a sensible ``default`` value for the input Period by returning ``one(p)`` for Year, Month, and Day, and ``zero(p)`` for Hour, Minute, Second, and Millisecond. - + Conversion Functions ~~~~~~~~~~~~~~~~~~~~ @@ -326,37 +326,37 @@ Conversion Functions .. function:: today() -> Date Returns the date portion of ``now()``. - + .. function:: unix2datetime(x) -> DateTime Takes the number of seconds since unix epoch - + .. function:: datetime2unix(dt::DateTime) -> Float64 Takes the given DateTime and returns the number of seconds since the unix epoch as a ``Float64``. - + .. function:: julian2datetime(julian_days) -> DateTime Takes the number of Julian calendar days since epoch - + .. function:: datetime2julian(dt::DateTime) -> Float64 Takes the given DateTime and returns the number of Julian calendar days since the julian epoch as a ``Float64``. - + .. function:: rata2datetime(days) -> DateTime Takes the number of Rata Die days since epoch - + .. function:: datetime2rata(dt::TimeType) -> Int64 Returns the number of Rata Die days since epoch from the given Date or DateTime. - + Constants ~~~~~~~~~ diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index 6f47724d02aef..3e458266cfa6f 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -8,285 +8,285 @@ .. function:: pwd() -> AbstractString Get the current working directory. - + .. function:: cd(f[, dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. - + .. function:: cd(f[, dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. - + .. function:: readdir([dir]) -> Vector{ByteString} Returns the files and directories in the directory *dir* (or the current working directory if not given). - + .. function:: mkdir(path[, mode]) Make a new directory with name ``path`` and permissions ``mode``. mask. - + .. function:: mkpath(path[, mode]) Create all directories in the given ``path``, with permissions creation mask. - + .. function:: symlink(target, link) Creates a symbolic link to ``target`` with the name ``link``. Note: This function raises an error under operating systems that - + .. function:: readlink(path) -> AbstractString Returns the value of a symbolic link ``path``. - + .. function:: chmod(path, mode) Change the permissions mode of ``path`` to ``mode``. Only integer - + .. function:: stat(file) Returns a structure whose fields contain information about the file. The fields of the structure are: - + .. function:: lstat(file) Like stat, but for symbolic links gets the info for the link itself rather than the file it refers to. This function must be called on a file path rather than a file object or a file descriptor. - + .. function:: ctime(file) Equivalent to stat(file).ctime - + .. function:: mtime(file) Equivalent to stat(file).mtime - + .. function:: filemode(file) Equivalent to stat(file).mode - + .. function:: filesize(path...) Equivalent to stat(file).size - + .. function:: uperm(file) Gets the permissions of the owner of the file as a bitfield of For allowed arguments, see ``stat``. - + .. function:: gperm(file) Like uperm but gets the permissions of the group owning the file - + .. function:: operm(file) Like uperm but gets the permissions for people who neither own the file nor are a member of the group owning the file - + .. function:: cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) Copy the file, link, or directory from *src* to *dest*. If *follow_symlinks=false*, and src is a symbolic link, dst will be created as a symbolic link. If *follow_symlinks=true* and src is a symbolic link, dst will be a copy of the file or directory *src* refers to. - + .. function:: download(url[, localfile]) Download a file from the given url, optionally renaming it to the given local file name. Note that this function relies on the availability of external tools such as ``curl``, ``wget`` or production use or situations in which more options are need, please use a package that provides the desired functionality instead. - + .. function:: mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) Move the file, link, or directory from *src* to *dest*. - + .. function:: rm(path::AbstractString; recursive=false) Delete the file, link, or empty directory at the given path. If contents are removed recursively. - + .. function:: touch(path::AbstractString) Update the last-modified timestamp on a file to the current time. - + .. function:: tempname() Generate a unique temporary file path. - + .. function:: tempdir() Obtain the path of a temporary directory (possibly shared with other processes). - + .. function:: mktemp([parent=tempdir()]) Returns ``(path, io)``, where ``path`` is the path of a new temporary file in ``parent`` and ``io`` is an open file object for this path. - + .. function:: mktempdir([parent=tempdir()]) Create a temporary directory in the ``parent`` directory and return its path. - + .. function:: isblockdev(path) -> Bool Returns ``true`` if ``path`` is a block device, ``false`` otherwise. - + .. function:: ischardev(path) -> Bool Returns ``true`` if ``path`` is a character device, ``false`` otherwise. - + .. function:: isdir(path) -> Bool Returns ``true`` if ``path`` is a directory, ``false`` otherwise. - + .. function:: isexecutable(path) -> Bool Returns ``true`` if the current user has permission to execute - + .. function:: isfifo(path) -> Bool Returns ``true`` if ``path`` is a FIFO, ``false`` otherwise. - + .. function:: isfile(path) -> Bool Returns ``true`` if ``path`` is a regular file, ``false`` otherwise. - + .. function:: islink(path) -> Bool Returns ``true`` if ``path`` is a symbolic link, ``false`` otherwise. - + .. function:: ismount(path) -> Bool Returns ``true`` if ``path`` is a mount point, ``false`` otherwise. - + .. function:: ispath(path) -> Bool Returns ``true`` if ``path`` is a valid filesystem path, ``false`` otherwise. - + .. function:: isreadable(path) -> Bool Returns ``true`` if the current user has permission to read - + .. function:: issetgid(path) -> Bool Returns ``true`` if ``path`` has the setgid flag set, ``false`` otherwise. - + .. function:: issetuid(path) -> Bool Returns ``true`` if ``path`` has the setuid flag set, ``false`` otherwise. - + .. function:: issocket(path) -> Bool Returns ``true`` if ``path`` is a socket, ``false`` otherwise. - + .. function:: issticky(path) -> Bool Returns ``true`` if ``path`` has the sticky bit set, ``false`` otherwise. - + .. function:: iswritable(path) -> Bool Returns ``true`` if the current user has permission to write to - + .. function:: homedir() -> AbstractString Return the current user's home directory. - + .. function:: dirname(path::AbstractString) -> AbstractString Get the directory part of a path. - + .. function:: basename(path::AbstractString) -> AbstractString Get the file name part of a path. - + .. function:: @__FILE__() -> AbstractString name of the script being run. Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e ``. - + .. function:: isabspath(path::AbstractString) -> Bool Determines whether a path is absolute (begins at the root directory). - + .. function:: isdirpath(path::AbstractString) -> Bool Determines whether a path refers to a directory (for example, ends with a path separator). - + .. function:: joinpath(parts...) -> AbstractString Join path components into a full path. If some argument is an absolute path, then prior components are dropped. - + .. function:: abspath(path::AbstractString) -> AbstractString Convert a path to an absolute path by adding the current directory if necessary. - + .. function:: normpath(path::AbstractString) -> AbstractString Normalize a path, removing ``.`` and ``..`` entries. - + .. function:: realpath(path::AbstractString) -> AbstractString Canonicalize a path by expanding symbolic links and removing ``.`` and ``..`` entries. - + .. function:: relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString Return a relative filepath to path either from the current directory or from an optional start directory. This is a path computation: the filesystem is not accessed to confirm the existence or nature of path or startpath. - + .. function:: expanduser(path::AbstractString) -> AbstractString On Unix systems, replace a tilde character at the start of a path with the current user's home directory. - + .. function:: splitdir(path::AbstractString) -> (AbstractString, AbstractString) Split a path into a tuple of the directory name and file name. - + .. function:: splitdrive(path::AbstractString) -> (AbstractString, AbstractString) On Windows, split a path into the drive letter part and the path part. On Unix systems, the first component is always the empty string. - + .. function:: splitext(path::AbstractString) -> (AbstractString, AbstractString) If the last component of a path contains a dot, split the path into everything before the dot and everything including and after the dot. Otherwise, return a tuple of the argument unmodified and the empty string. - + diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 422475070152f..d1970287b469a 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -22,242 +22,242 @@ General I/O .. function:: open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - + .. function:: open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - + .. function:: open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. - + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + .. function:: takebuf_array(b::IOBuffer) Obtain the contents of an ``IOBuffer`` as an array, without copying. Afterwards, the IOBuffer is reset to its initial state. - + .. function:: takebuf_string(b::IOBuffer) Obtain the contents of an ``IOBuffer`` as a string, without copying. Afterwards, the IOBuffer is reset to its initial state. - + .. function:: fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream Create an ``IOStream`` object from an integer file descriptor. If descriptor. By default, an ``IOStream`` is closed when it is garbage collected. ``name`` allows you to associate the descriptor with a named file. - + .. function:: flush(stream) Commit all currently buffered writes to the given stream. - + .. function:: close(stream) Close an I/O stream. Performs a ``flush`` first. - + .. function:: write(stream, x) Write the canonical binary representation of a value to the given stream. - + .. function:: read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. - + .. function:: read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. - + .. function:: read!(stream, array::Array) Read binary data from a stream, filling in the argument ``array``. - + .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b)) Read at most ``nb`` bytes from the stream into ``b``, returning the number of bytes read (increasing the size of ``b`` as needed). - + .. function:: readbytes(stream, nb=typemax(Int)) Read at most ``nb`` bytes from the stream, returning a - + .. function:: position(s) Get the current position of a stream. - + .. function:: seek(s, pos) Seek a stream to the given position. - + .. function:: seekstart(s) Seek a stream to its beginning. - + .. function:: seekend(s) Seek a stream to its end. - + .. function:: skip(s, offset) Seek a stream relative to the current position. - + .. function:: mark(s) Add a mark at the current position of stream ``s``. Returns the marked position. See also ``unmark()``, ``reset()``, ``ismarked()`` - + .. function:: unmark(s) Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. See also ``mark()``, ``reset()``, ``ismarked()`` - + .. function:: reset(s) Reset a stream ``s`` to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked. See also ``mark()``, ``unmark()``, ``ismarked()`` - + .. function:: ismarked(s) Returns true if stream ``s`` is marked. See also ``mark()``, ``unmark()``, ``reset()`` - + .. function:: eof(stream) -> Bool Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return ``false``. Therefore it is always safe to read one byte after seeing ``eof`` return ``false``. ``eof`` will return ``false`` as long as buffered data is still available, even if the remote end of a connection is closed. - + .. function:: isreadonly(stream) -> Bool Determine whether a stream is read-only. - + .. function:: isopen(stream) -> Bool Determine whether a stream is open (i.e. has not been closed yet). If the connection has been closed remotely (in case of e.g. a socket), ``isopen`` will return ``false`` even though buffered data may still be available. Use ``eof`` to check if necessary. - + .. function:: serialize(stream, value) Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``. The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. - + .. function:: deserialize(stream) Read a value written by ``serialize``. - + .. function:: print_escaped(io, str::AbstractString, esc::AbstractString) General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). - + .. function:: print_unescaped(io, s::AbstractString) General unescaping of traditional C and Unicode escape sequences. Reverse of ``print_escaped()``. - + .. function:: print_joined(io, items, delim[, last]) Print elements of ``items`` to ``io`` with ``delim`` between them. If ``last`` is specified, it is used as the final delimiter instead of ``delim``. - + .. function:: print_shortest(io, x) Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number ``x``, ensuring that it would parse to the exact same number. - + .. function:: fd(stream) Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. - + .. function:: redirect_stdout(stream) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - + .. function:: redirect_stdout(stream) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - + .. function:: redirect_stderr([stream]) Like redirect_stdout, but for STDERR - + .. function:: redirect_stdin([stream]) Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read from STDIN, may be written to wr. - + .. function:: readchomp(x) Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). - + .. function:: truncate(file, n) Resize the file or buffer given by the first argument to exactly file or buffer is grown - + .. function:: skipchars(stream, predicate; linecomment::Char) Advance the stream until before the first character for which isspace)` will skip all whitespace. If keyword argument through the end of a line will also be skipped. - + .. function:: countlines(io[, eol::Char]) Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first argument. EOL markers other than '\n' are supported by passing them as the second argument. - + .. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. - + .. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. - + .. function:: readavailable(stream) Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``. - + Text I/O -------- @@ -265,172 +265,172 @@ Text I/O .. function:: show(x) Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. The representation used by ``show`` generally includes Julia-specific formatting and type information. - + .. function:: showcompact(x) Show a more compact representation of a value. This is used for printing array elements. If a new type has a different compact representation, it should overload ``showcompact(io, x)`` where the first argument is a stream. - + .. function:: showall(x) Similar to ``show``, except shows all elements of arrays. - + .. function:: summary(x) Return a string giving a brief description of a value. By default returns ``string(typeof(x))``. For arrays, returns strings like - + .. function:: print(x) Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call formatting and tries to avoid Julia-specific details. - + .. function:: println(x) Print (using ``print()``) ``x`` followed by a newline. - + .. function:: print_with_color(color::Symbol[, io], strings...) Print strings in a color specified as a symbol, for example - + .. function:: info(msg) Display an informational message. - + .. function:: warn(msg) Display a warning. - + .. function:: @printf([io::IOStream], "%Fmt", args...) Print arg(s) using C ``printf()`` style format specification string. Optionally, an IOStream may be passed as the first argument to redirect output. - + .. function:: @sprintf("%Fmt", args...) Return ``@printf`` formatted output as string. - + .. function:: sprint(f::Function, args...) Call the given function with an I/O stream and the supplied extra arguments. Everything written to this I/O stream is returned as a string. - + .. function:: showerror(io, e) Show a descriptive representation of an exception object. - + .. function:: dump(x) Show all user-visible structure of a value. - + .. function:: xdump(x) Show all structure of a value, including all fields of objects. - + .. function:: readall(filename::AbstractString) Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. - + .. function:: readall(filename::AbstractString) Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. - + .. function:: readline(stream=STDIN) Read a single line of text, including a trailing newline character - + .. function:: readuntil(stream, delim) Read a string, up to and including the given delimiter byte. - + .. function:: readlines(stream) Read all lines as an array. - + .. function:: eachline(stream) Create an iterable object that will yield each line from a stream. - + .. function:: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + .. function:: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + .. function:: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + .. function:: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + .. function:: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + .. function:: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + .. function:: writedlm(f, A, delim='\t') Write ``A`` (a vector, matrix or an iterable collection of iterable rows) as text to ``f`` (either a filename string or an ``IO`` stream) using the given delimeter ``delim`` (which defaults to tab, but can be any printable Julia object, typically a ``Char`` or For example, two vectors ``x`` and ``y`` of the same length can be written as two columns of tab-delimited text to ``f`` by either - + .. function:: readcsv(source, [T::Type]; options...) Equivalent to ``readdlm`` with ``delim`` set to comma. - + .. function:: writecsv(filename, A) Equivalent to ``writedlm`` with ``delim`` set to comma. - + .. function:: Base64EncodePipe(ostream) Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to necessary to complete the encoding (but does not close - + .. function:: Base64DecodePipe(istream) Returns a new read-only I/O stream, which decodes base64-encoded data read from ``istream``. - + .. function:: base64encode(writefunc, args...) Given a ``write``-like function ``writefunc``, which takes an I/O stream as its first argument, ``base64(writefunc, args...)`` calls returns the string. ``base64(args...)`` is equivalent to using the standard ``write`` functions and returns the base64-encoded string. - + .. function:: base64decode(string) Decodes the base64-encoded ``string`` and returns a - + Multimedia I/O -------------- @@ -456,37 +456,37 @@ Julia environments (such as the IPython-based IJulia notebook). .. function:: display(x) Display ``x`` using the topmost applicable display in the display stack, typically using the richest supported multimedia output for display ``d`` only, throwing a ``MethodError`` if ``d`` cannot display objects of this type. There are also two variants with a ``mime`` argument (a MIME type string, such as ``image/png``), which attempt to display ``x`` using the requested MIME type *only*, throwing a ``MethodError`` if this type is not supported by either the display(s) or by ``x``. With these variants, one can also supply the ``raw`` data in the requested MIME type by passing ``x::AbstractString`` (for MIME types with text-based storage, such as text/html or application/postscript) or ``x::Vector{UInt8}`` (for binary MIME types). - + .. function:: redisplay(x) By default, the ``redisplay`` functions simply call ``display``. However, some display backends may override ``redisplay`` to modify an existing display of ``x`` (if any). Using ``redisplay`` is also a hint to the backend that ``x`` may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt. - + .. function:: displayable(mime) -> Bool Returns a boolean value indicating whether the given ``mime`` type display stack, or specifically by the display ``d`` in the second variant. - + .. function:: writemime(stream, mime, x) The ``display`` functions ultimately call ``writemime`` in order to write an object ``x`` as a given ``mime`` type to a given I/O provide a rich multimedia representation of a user-defined type for ``T``, via: ``writemime(stream, ::MIME"mime", x::T) = ...``, where ``mime`` is a MIME-type string and the function body calls literal strings; to construct ``MIME`` types in a more flexible manner use ``MIME{symbol("")}``.) For example, if you define a ``MyImage`` type and know how to write it to a PNG file, you could define a function ``writemime(stream, be displayed on any PNG-capable `Display`` (such as IJulia). As usual, be sure to ``import Base.writemime`` in order to add new methods to the built-in Julia function ``writemime``. Technically, the ``MIME"mime"`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. - + .. function:: mimewritable(mime, x) Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding - + .. function:: reprmime(mime, x) Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the representation of ``x`` in the requested ``mime`` type, as written by ``writemime`` (throwing a ``MethodError`` if no appropriate MIME types with textual representations (such as ``text/html`` or ``application/postscript``), whereas binary data is returned as ``Vector{UInt8}``. (The function ``istext(mime)`` returns whether or not Julia treats a given ``mime`` type as text.) As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) or a ``Vector{UInt8}`` (for binary MIME types), the requested ``mime`` format and simply returns ``x``. - + .. function:: stringmime(mime, x) Returns an ``AbstractString`` containing the representation of string. - + As mentioned above, one can also define new display backends. For example, a module that can display PNG images in a window can register @@ -517,22 +517,22 @@ stack with: .. function:: pushdisplay(d::Display) Pushes a new display ``d`` on top of the global display-backend stack. Calling ``display(x)`` or ``display(mime, x)`` will display topmost backend that does not throw a ``MethodError``). - + .. function:: popdisplay() Pop the topmost backend off of the display-backend stack, or the topmost copy of ``d`` in the second variant. - + .. function:: TextDisplay(stream) Returns a ``TextDisplay <: Display``, which can display any object as the text/plain MIME type (only), writing the text representation to the given I/O stream. (The text representation is the same as the way an object is printed in the Julia REPL.) - + .. function:: istext(m::MIME) Determine whether a MIME type is text data. - + Memory-mapped I/O ----------------- @@ -540,17 +540,17 @@ Memory-mapped I/O .. function:: mmap_array(type, dims, stream[, offset]) Create an ``Array`` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory. The type determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). The file is passed via the stream argument. When you initialize the stream, use ``r`` for a ``read-only`` array, and ``w+`` to create a new array used to write values to disk. Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position. For example, the following code: creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. A more portable file would need to encode the word size–-32 bit or 64 bit–-and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 - + .. function:: mmap_bitarray([type], dims, stream[, offset]) Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as ``mmap_array()``, but the byte representation is different. The ``type`` parameter is optional, and must be ``Bool`` if given. This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. - + .. function:: msync(ptr, len[, flags]) Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. - + Network I/O ----------- @@ -558,117 +558,117 @@ Network I/O .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. - + .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. - + .. function:: listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket - + .. function:: listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket - + .. function:: getaddrinfo(host) Gets the IP address of the ``host`` (may have to do a DNS lookup) - + .. function:: parseip(addr) Parse a string specifying an IPv4 or IPv6 ip address. - + .. function:: IPv4(host::Integer) -> IPv4 Returns IPv4 object from ip address formatted as Integer - + .. function:: IPv6(host::Integer) -> IPv6 Returns IPv6 object from ip address formatted as Integer - + .. function:: nb_available(stream) Returns the number of bytes available for reading before a read from this stream or buffer will block. - + .. function:: accept(server[, client]) Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. - + .. function:: listenany(port_hint) -> (UInt16, TcpServer) Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server was created on and the server itself. - + .. function:: watch_file(cb=false, s; poll=false) Watch file or directory ``s`` and run callback ``cb`` when ``s`` is modified. The ``poll`` parameter specifies whether to use file system event monitoring or polling. The callback function ``cb`` should accept 3 arguments: ``(filename, events, status)`` where an object with boolean fields ``changed`` and ``renamed`` when using file system event monitoring, or ``readable`` and - + .. function:: poll_fd(fd, seconds::Real; readable=false, writable=false) Poll a file descriptor fd for changes in the read or write availability and with a timeout given by the second argument. If the timeout is not needed, use ``wait(fd)`` instead. The keyword arguments determine which of read and/or write status should be monitored and at least one of them needs to be set to true. The returned value is an object with boolean fields ``readable``, - + .. function:: poll_file(s, interval_seconds::Real, seconds::Real) Monitor a file for changes by polling every *interval_seconds* seconds for *seconds* seconds. A return value of true indicates the file changed, a return value of false indicates a timeout. - + .. function:: bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) Bind ``socket`` to the given ``host:port``. Note that *0.0.0.0* will listen on all devices. - + .. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) Send ``msg`` over ``socket to `host:port``. - + .. function:: recv(socket::UDPSocket) Read a UDP packet from the specified socket, and return the bytes received. This call blocks. - + .. function:: recvfrom(socket::UDPSocket) -> (address, data) Read a UDP packet from the specified socket, returning a tuple of appropriate. - + .. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) Set UDP socket options. ``multicast_loop``: loopback for multicast packets (default: true). ``multicast_ttl``: TTL for multicast packets. ``enable_broadcast``: flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). ``ttl``: Time-to-live of packets sent on the socket. - + .. function:: ntoh(x) Converts the endianness of a value from Network byte order (big- endian) to that used by the Host. - + .. function:: hton(x) Converts the endianness of a value from that used by the Host to Network byte order (big-endian). - + .. function:: ltoh(x) Converts the endianness of a value from Little-endian to that used by the Host. - + .. function:: htol(x) Converts the endianness of a value from that used by the Host to Little-endian. - + .. data:: ENDIAN_BOM diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index f20e663f6e67b..c98bd72c9e445 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -7,62 +7,62 @@ .. function:: malloc(size::Integer) -> Ptr{Void} Call ``malloc`` from the C standard library. - + .. function:: calloc(num::Integer, size::Integer) -> Ptr{Void} Call ``calloc`` from the C standard library. - + .. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void} Call ``realloc`` from the C standard library. See warning in the documentation for ``free`` regarding only using this on memory originally obtained from ``malloc``. - + .. function:: free(addr::Ptr) Call ``free`` from the C standard library. Only use this on memory obtained from ``malloc``, not on pointers retrieved from other C libraries. ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library, to avoid assertion failures if multiple ``libc`` libraries exist on the system. - + .. function:: errno([code]) Get the value of the C library's ``errno``. If an argument is specified, it is used to set the value of ``errno``. The value of ``errno`` is only valid immediately after a ``ccall`` to a C library routine that sets it. Specifically, you cannot call executed between prompts. - + .. function:: strerror(n) Convert a system call error code to a descriptive string - + .. function:: time(t::TmStruct) Converts a ``TmStruct`` struct to a number of seconds since the epoch. - + .. function:: strftime([format], time) Convert time, given as a number of seconds since the epoch or a Supported formats are the same as those in the standard C library. - + .. function:: strptime([format], timestr) Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the will tell the C library to use the current system settings to determine the timezone. - + .. function:: TmStruct([seconds]) Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, - + .. function:: flush_cstdio() Flushes the C ``stdout`` and ``stderr`` streams (which may have been written to by external C code). - + .. function:: msync(ptr, len[, flags]) Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. - + .. data:: MS_ASYNC @@ -79,10 +79,10 @@ .. function:: mmap(len, prot, flags, fd, offset) Low-level interface to the ``mmap`` system call. See the man page. - + .. function:: munmap(pointer, len) Low-level interface for unmapping memory (see the man page). With is unmapped for you when the array goes out of scope. - + diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index 953dd1a923247..c5e5538223a46 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -7,12 +7,12 @@ .. function:: dlopen(libfile::AbstractString[, flags::Integer]) Load a shared library, returning an opaque handle. The optional flags argument is a bitwise-or of zero or more of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default is these flags, on POSIX platforms, is to specify symbols to be available for usage in other shared libraries, in situations where there are dependencies between shared libraries. - + .. function:: dlopen_e(libfile::AbstractString[, flags::Integer]) Similar to ``dlopen()``, except returns a ``NULL`` pointer instead of raising errors. - + .. data:: RTLD_DEEPBIND @@ -49,22 +49,22 @@ .. function:: dlsym(handle, sym) Look up a symbol from a shared library handle, return callable function pointer on success. - + .. function:: dlsym_e(handle, sym) Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. - + .. function:: dlclose(handle) Close shared library referenced by handle. - + .. function:: find_library(names, locations) Searches for the first library in ``names`` in the paths in the that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a - + .. data:: DL_LOAD_PATH diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 45ba5f4683424..9d9e741358acd 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -16,7 +16,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: *(s, t) Concatenate strings. The ``*`` operator is an alias to this function. - + .. function:: \\(A, B) :noindex: @@ -28,406 +28,406 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: dot(x, y) Compute the dot product. For complex vectors, the first vector is conjugated. - + .. function:: vecdot(x, y) For any iterable containers ``x`` and ``y`` (including arrays of any dimension) of numbers (or any element type for which ``dot`` is defined), compute the Euclidean dot product (the sum of - + .. function:: cross(x, y) Compute the cross product of two 3-vectors. - + .. function:: factorize(A) Compute a convenient factorization (including LU, Cholesky, Bunch- Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: - + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. - + Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. .. function:: lu(A) -> L, U, p Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. - + .. function:: lufact(A[, pivot=Val{true}]) -> F Compute the LU factorization of ``A``. The return type of ``F`` depends on the type of ``A``. In most cases, if ``A`` is a subtype pivoting is chosen (default) the element type should also support examples are shown in the table below. The individual components of the factorization ``F`` can be accessed by indexing: - + .. function:: lufact!(A) -> LU overwriting the input A, instead of creating a copy. For sparse 1-based indices to 0-based indices. - + .. function:: chol(A[, LU]) -> F Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. - + .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + .. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky overwriting the input ``A``, instead of creating a copy. different matrix ``F`` with the same structure when used as: - + .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + .. function:: qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] Compute the (pivoted) QR factorization of ``A`` such that either is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. - + .. function:: qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. - + .. function:: qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. - + .. function:: qrfact!(A[, pivot=Val{false}]) instead of creating a copy. - + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. - + .. function:: bkfact(A) -> BunchKaufman Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix ``A`` and return a - + .. [Bunch1977] J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. `url `_. .. function:: bkfact!(A) -> BunchKaufman overwriting the input ``A``, instead of creating a copy. - + .. function:: sqrtm(A) Compute the matrix square root of ``A``. If ``B = sqrtm(A)``, then using Schur factorizations (``schurfact()``) unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition (``eigfact()``). In the latter situation for positive definite matrices, the matrix square root has ``Real`` elements, otherwise it has ``Complex`` elements. - + .. function:: eig(A, B) -> D, V Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. - + .. function:: eig(A, B) -> D, V Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. - + .. function:: eigvals(A,[irange,][vl,][vu]) Returns the eigenvalues of ``A``. If ``A`` is ``Symmetric``, only a subset of the eigenvalues by specifying either a eigenvalues, or a pair ``vl`` and ``vu`` for the lower and upper boundaries of the eigenvalues. For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option ``permute=true`` permutes the matrix to become closer to upper triangular, and ``scale=true`` scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is ``true`` for both options. - + .. function:: eigmax(A) Returns the largest eigenvalue of ``A``. - + .. function:: eigmin(A) Returns the smallest eigenvalue of ``A``. - + .. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix Returns a matrix ``M`` whose columns are the eigenvectors of ``A``. k]``.) The `permute`` and ``scale`` keywords are the same as for For ``SymTridiagonal`` matrices, if the optional vector of eigenvalues ``eigvals`` is specified, returns the specific corresponding eigenvectors. - + .. function:: eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) - + .. function:: eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) - + .. function:: eigfact!(A[, B]) Same as ``eigfact()``, but saves space by overwriting the input - + .. function:: hessfact(A) Compute the Hessenberg decomposition of ``A`` and return a unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``. When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with ``full()``. - + .. function:: hessfact!(A) overwriting the input A, instead of creating a copy. - + .. function:: schurfact(A, B) -> GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and - + .. function:: schurfact!(A) Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See ``schurfact()`` - + .. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See ``schurfact()`` - + .. function:: ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + .. function:: ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + .. function:: ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + .. function:: ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + .. function:: schurfact(A, B) -> GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and - + .. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See ``schurfact()`` - + .. function:: ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + .. function:: ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + .. function:: ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + .. function:: ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + .. function:: svdfact(A, B) -> GeneralizedSVD Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. - + .. function:: svdfact!(A[, thin=true]) -> SVD overwriting the input A, instead of creating a copy. If ``thin`` is to produce a thin decomposition. - + .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. - + .. function:: svdvals(A, B) Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. - + .. function:: svdvals!(A) Returns the singular values of ``A``, while saving space by overwriting the input. - + .. function:: svdfact(A, B) -> GeneralizedSVD Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. - + .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. - + .. function:: svdvals(A, B) Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. - + .. function:: triu(M, k) Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. - + .. function:: triu(M, k) Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. - + .. function:: triu!(M, k) Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. - + .. function:: triu!(M, k) Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. - + .. function:: tril(M, k) Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. - + .. function:: tril(M, k) Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. - + .. function:: tril!(M, k) Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. - + .. function:: tril!(M, k) Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. - + .. function:: diagind(M[, k]) A ``Range`` giving the indices of the ``k``th diagonal of the matrix ``M``. - + .. function:: diag(M[, k]) The ``k``th diagonal of a matrix, as a vector. Use ``diagm`` to construct a diagonal matrix. - + .. function:: diagm(v[, k]) Construct a diagonal matrix and place ``v`` on the ``k``th diagonal. - + .. function:: scale(b, A) Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. - + .. function:: scale(b, A) Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. - + .. function:: scale!(b, A) Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. - + .. function:: scale!(b, A) Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. - + .. function:: Tridiagonal(dl, d, du) Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. - + .. function:: Bidiagonal(dv, ev, isupper) Constructs an upper (``isupper=true``) or lower (``isupper=false``) bidiagonal matrix using the given diagonal (``dv``) and off- diagonal (``ev``) vectors. The result is of type ``Bidiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with ``full()``. - + .. function:: SymTridiagonal(d, du) Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. - + .. function:: rank(M) Compute the rank of a matrix. - + .. function:: norm(A[, p]) Compute the ``p``-norm of a vector or the operator norm of a matrix For vectors, ``p`` can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, ``norm(A, Inf)`` returns the largest value in For matrices, valid values of ``p`` are ``1``, ``2``, or ``Inf``. implemented.) Use ``vecnorm()`` to compute the Frobenius norm. - + .. function:: vecnorm(A[, p]) For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``-norm (defaulting to ``p=2``) as if For example, if ``A`` is a matrix and ``p=2``, then this is equivalent to the Frobenius norm. - + .. function:: cond(M[, p]) Condition number of the matrix ``M``, computed using the operator - + .. function:: condskeel(M[, x, p]) Skeel condition number \kappa_S of the matrix ``M``, optionally with respect to the vector ``x``, as computed using the operator values for ``p`` are ``1``, ``2``, or ``Inf``. This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. - + .. function:: trace(M) Matrix trace - + .. function:: det(M) Matrix determinant - + .. function:: logdet(M) Log of matrix determinant. Equivalent to ``log(det(M))``, but may provide increased accuracy and/or speed. - + .. function:: logabsdet(M) @@ -436,132 +436,132 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: inv(M) Matrix inverse - + .. function:: pinv(M[, tol]) Computes the Moore-Penrose pseudoinverse. For matrices ``M`` with floating point elements, it is convenient to compute the pseudoinverse by inverting only singular values above a given threshold, ``tol``. The optimal choice of ``tol`` varies both with the value of ``M`` and the intended application of the pseudoinverse. The default value of ``tol`` is essentially machine epsilon for the real part of a matrix element multiplied by the larger matrix dimension. For inverting dense ill- conditioned matrices in a least-squares sense, ``tol = sqrt(eps(real(float(one(eltype(M))))))`` is recommended. For more information, see [8859], [B96], [S84], [KY88]. - + .. function:: nullspace(M) Basis for nullspace of ``M``. - + .. function:: repmat(A, n, m) Construct a matrix by repeating the given matrix ``n`` times in dimension 1 and ``m`` times in dimension 2. - + .. function:: repeat(A, inner = Int[], outer = Int[]) Construct an array by repeating the entries of ``A``. The i-th element of ``inner`` specifies the number of times that the individual entries of the i-th dimension of ``A`` should be repeated. The i-th element of ``outer`` specifies the number of times that a slice along the i-th dimension of ``A`` should be repeated. - + .. function:: kron(A, B) Kronecker tensor product of two vectors or two matrices. - + .. function:: blkdiag(A...) Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. - + .. function:: linreg(x, y, w) Weighted least-squares linear regression. - + .. function:: linreg(x, y, w) Weighted least-squares linear regression. - + .. function:: expm(A) Matrix exponential. - + .. function:: lyap(A, C) Computes the solution ``X`` to the continuous Lyapunov equation part and no two eigenvalues are negative complex conjugates of each other. - + .. function:: sylvester(A, B, C) Computes the solution ``X`` to the Sylvester equation `AX + XB + C - + .. function:: issym(A) -> Bool Test whether a matrix is symmetric. - + .. function:: isposdef(A) -> Bool Test whether a matrix is positive definite. - + .. function:: isposdef!(A) -> Bool Test whether a matrix is positive definite, overwriting ``A`` in the processes. - + .. function:: istril(A) -> Bool Test whether a matrix is lower triangular. - + .. function:: istriu(A) -> Bool Test whether a matrix is upper triangular. - + .. function:: isdiag(A) -> Bool Test whether a matrix is diagonal. - + .. function:: ishermitian(A) -> Bool Test whether a matrix is Hermitian. - + .. function:: transpose(A) The transposition operator (``.'``). - + .. function:: transpose!(dest, src) Transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. - + .. function:: ctranspose(A) The conjugate transposition operator (``'``). - + .. function:: ctranspose!(dest, src) Conjugate transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. - + .. function:: eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) Computes eigenvalues ``d`` of ``A`` using Lanczos or Arnoldi iterations for real symmetric or general nonsymmetric matrices respectively. If ``B`` is provided, the generalized eigenproblem is solved. The following keyword arguments are supported: corresponding Ritz vectors ``v`` (only if ``ritzvec=true``), the number of converged eigenvalues ``nconv``, the number of iterations Note: The ``sigma`` and ``which`` keywords interact: the - + .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) Lanczos or Arnoldi iterations. Uses ``eigs()`` underneath. Inputs are: - + .. function:: peakflops(n; parallel=false) double precision ``Base.LinAlg.BLAS.gemm!()``. By default, if no arguments are specified, it multiplies a matrix of size ``n x n``, where ``n = 2000``. If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with ``blas_set_num_threads(n)``. If the keyword argument ``parallel`` is set to ``true``, flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument ``n`` still refers to the size of the problem that is solved on each processor. - + BLAS Functions -------------- @@ -580,217 +580,217 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: dot(n, X, incx, Y, incy) Dot product of two vectors consisting of ``n`` elements of array stride ``incy``. - + .. function:: dotu(n, X, incx, Y, incy) Dot function for two complex vectors. - + .. function:: dotc(n, X, incx, U, incy) Dot function for two complex vectors conjugating the first vector. - + .. function:: blascopy!(n, X, incx, Y, incy) Copy ``n`` elements of array ``X`` with stride ``incx`` to array - + .. function:: nrm2(n, X, incx) 2-norm of a vector consisting of ``n`` elements of array ``X`` with stride ``incx``. - + .. function:: asum(n, X, incx) sum of the absolute values of the first ``n`` elements of array - + .. function:: axpy!(a, X, Y) Overwrite ``Y`` with ``a*X + Y``. Returns ``Y``. - + .. function:: scal!(n, a, X, incx) Overwrite ``X`` with ``a*X``. Returns ``X``. - + .. function:: scal(n, a, X, incx) Returns ``a*X``. - + .. function:: ger!(alpha, x, y, A) Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as - + .. function:: syr!(uplo, alpha, x, A) Rank-1 update of the symmetric matrix ``A`` with vector ``x`` as - + .. function:: syrk!(uplo, trans, alpha, A, beta, C) Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. - + .. function:: syrk(uplo, trans, alpha, A) Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``, according to ``trans`` ('N' or 'T'). - + .. function:: her!(uplo, alpha, x, A) Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When lower triangle). Returns ``A``. - + .. function:: herk!(uplo, trans, alpha, A, beta, C) Methods for complex arrays only. Rank-k update of the Hermitian matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. - + .. function:: herk(uplo, trans, alpha, A) Methods for complex arrays only. Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of - + .. function:: gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) Update vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'*x + beta*y`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension ``m`` by ``size(A,2)`` with updated ``y``. - + .. function:: gbmv(trans, m, kl, ku, alpha, A, x, beta, y) Returns ``alpha*A*x`` or ``alpha*A'*x`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension diagonals. - + .. function:: sbmv!(uplo, k, alpha, A, x, beta, y) Update vector ``y`` as ``alpha*A*x + beta*y`` where ``A`` is a a symmetric band matrix of order ``size(A,2)`` with ``k`` super- diagonals stored in the argument ``A``. The storage layout for http://www.netlib.org/lapack/explore-html/. Returns the updated ``y``. - + .. function:: sbmv(uplo, k, A, x) Returns ``A*x`` where ``A`` is a symmetric band matrix of order - + .. function:: sbmv(uplo, k, A, x) Returns ``A*x`` where ``A`` is a symmetric band matrix of order - + .. function:: gemm!(tA, tB, alpha, A, B, beta, C) Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. Returns the updated ``C``. - + .. function:: gemm(tA, tB, A, B) Returns ``A*B`` or the other three variants according to ``tA`` - + .. function:: gemm(tA, tB, A, B) Returns ``A*B`` or the other three variants according to ``tA`` - + .. function:: gemv!(tA, alpha, A, x, beta, y) Update the vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``). Returns the updated - + .. function:: gemv(tA, A, x) Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). - + .. function:: gemv(tA, A, x) Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). - + .. function:: symm!(side, ul, alpha, A, B, beta, C) Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` according to ``side``. ``A`` is assumed to be symmetric. Only the - + .. function:: symm(tA, tB, alpha, A, B) Returns ``alpha*A*B`` or the other three variants according to - + .. function:: symm(tA, tB, alpha, A, B) Returns ``alpha*A*B`` or the other three variants according to - + .. function:: symm(tA, tB, alpha, A, B) Returns ``alpha*A*B`` or the other three variants according to - + .. function:: symv!(ul, alpha, A, x, beta, y) Update the vector ``y`` as ``alpha*A*x + beta*y``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. Returns the updated ``y``. - + .. function:: symv(ul, A, x) Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - + .. function:: symv(ul, A, x) Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - + .. function:: trmm!(side, ul, tA, dA, alpha, A, B) Update ``B`` as ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``B``. - + .. function:: trmm(side, ul, tA, dA, alpha, A, B) Returns ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). - + .. function:: trsm!(side, ul, tA, dA, alpha, A, B) Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and ``tA`` (transpose A). Only the ``ul`` triangle of diagonal is assumed to be all ones). Returns the updated ``B``. - + .. function:: trsm(side, ul, tA, dA, alpha, A, B) Returns the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and assumed to be all ones). - + .. function:: trmv!(side, ul, tA, dA, alpha, A, b) Update ``b`` as ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``b``. - + .. function:: trmv(side, ul, tA, dA, alpha, A, b) Returns ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). - + .. function:: trsv!(ul, tA, dA, A, b) Overwrite ``b`` with the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` triangular (the diagonal is assumed to be all ones). Returns the updated ``b``. - + .. function:: trsv(ul, tA, dA, A, b) Returns the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` (triangle of diagonal is assumed to be all ones). - + .. function:: blas_set_num_threads(n) Set the number of threads the BLAS library should use. - + .. data:: I diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index e58631839972e..2c8bb04e65f26 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -12,31 +12,31 @@ Mathematical Operators .. function:: -(x, y) Subtraction operator. - + .. _+: .. function:: +(x, y...) Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. ``+(x, y, z, ...)``. - + .. _-: .. function:: -(x, y) Subtraction operator. - + .. _*: .. function:: *(s, t) Concatenate strings. The ``*`` operator is an alias to this function. - + .. _/: .. function:: /(x, y) Right division operator: multiplication of ``x`` by the inverse of arguments. - + .. _\\: .. function:: \\(x, y) @@ -48,31 +48,31 @@ Mathematical Operators .. function:: ^(s, n) Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. - + .. _.+: .. function:: .+(x, y) Element-wise addition operator. - + .. _.-: .. function:: .-(x, y) Element-wise subtraction operator. - + .. _.*: .. function:: .*(x, y) Element-wise multiplication operator. - + .. _./: .. function:: ./(x, y) Element-wise right division operator. - + .. _.\\: .. function:: .\\(x, y) @@ -83,106 +83,106 @@ Mathematical Operators .. function:: .^(x, y) Element-wise exponentiation operator. - + .. function:: fma(x, y, z) Computes ``x*y+z`` without rounding the intermediate result algorithms. See ``muladd``. - + .. function:: muladd(x, y, z) Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``, or to - + .. function:: div(x, y) The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. - + .. function:: fld(x, y) Largest integer less than or equal to ``x/y``. - + .. function:: cld(x, y) Smallest integer larger than or equal to ``x/y``. - + .. function:: mod(x, y) Modulus after division, returning in the range [0,``y``), if ``y`` is positive, or (``y``,0] if ``y`` is negative. - + .. function:: mod2pi(x) Modulus after division by 2pi, returning in the range [0,2pi). This function computes a floating point representation of the modulus after division by numerically exact 2pi, and is therefore not exactly the same as mod(x,2pi), which would compute the modulus of x relative to division by the floating-point number 2pi. - + .. function:: rem(x, y) Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than ``y``. This value is always exact. - + .. function:: divrem(x, y) The quotient and remainder from Euclidean division. Equivalent to - + .. function:: fldmod(x, y) The floored quotient and modulus after division. Equivalent to - + .. function:: mod1(x, m) Modulus after division, returning in the range (0,m] - + .. function:: rem1(x, m) Remainder after division, returning in the range (0,m] - + .. _//: .. function:: //(num, den) Divide two integers or rational numbers, giving a ``Rational`` result. - + .. function:: rationalize([Type=Int], x; tol=eps(x)) Approximate floating point number ``x`` as a Rational number with components of the given integer type. The result will differ from - + .. function:: num(x) Numerator of the rational representation of ``x`` - + .. function:: den(x) Denominator of the rational representation of ``x`` - + .. _<<: .. function:: <<(x, n) Left bit shift operator. - + .. _>>: .. function:: >>(x, n) Right bit shift operator, preserving the sign of ``x``. - + .. _>>>: .. function:: >>>(x, n) Unsigned right bit shift operator. - + .. _\:: .. function:: \:(start, [step], stop) @@ -195,131 +195,131 @@ Mathematical Operators .. function:: colon(start[, step], stop) Called by ``:`` syntax for constructing ranges. - + .. function:: range(start[, step], length) Construct a range by length, given a starting value and optional step (defaults to 1). - + .. _==: .. function:: ==(x, y) Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``. Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. Follows IEEE semantics for floating-point numbers. Collections should generally implement ``==`` by calling ``==`` recursively on all contents. New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible. - + .. _!=: .. function:: !=(x, y) Not-equals comparison operator. Always gives the opposite answer as the fallback definition ``!=(x,y) = !(x==y)`` instead. - + .. _===: .. function:: ===(x, y) See the ``is()`` operator - + .. _!==: .. function:: !==(x, y) Equivalent to ``!is(x, y)`` - + .. _<: .. function:: <(x, y) Less-than comparison operator. New numeric types should implement this function for two arguments of the new type. Because of the behavior of floating-point NaN values, ``<`` implements a partial order. Types with a canonical partial order should implement ``<``, and types with a canonical total order should implement ``isless``. - + .. _<=: .. function:: <=(x, y) Less-than-or-equals comparison operator. - + .. _>: .. function:: >(x, y) Greater-than comparison operator. Generally, new types should implement ``<`` instead of this function, and rely on the fallback definition ``>(x,y) = y=: .. function:: >=(x, y) Greater-than-or-equals comparison operator. - + .. _.==: .. function:: .==(x, y) Element-wise equality comparison operator. - + .. _.!=: .. function:: .!=(x, y) Element-wise not-equals comparison operator. - + .. _.<: .. function:: .<(x, y) Element-wise less-than comparison operator. - + .. _.<=: .. function:: .<=(x, y) Element-wise less-than-or-equals comparison operator. - + .. _.>: .. function:: .>(x, y) Element-wise greater-than comparison operator. - + .. _.>=: .. function:: .>=(x, y) Element-wise greater-than-or-equals comparison operator. - + .. function:: cmp(x, y) Return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``, respectively. Uses the total order implemented by ``isless``. For floating-point numbers, uses ``<`` but throws an error for unordered arguments. - + .. _~: .. function:: ~(x) Bitwise not - + .. _&: .. function:: &(x, y) Bitwise and - + .. _|: .. function:: |(x, y) Bitwise or - + .. _$: .. function:: \$(x, y) Bitwise exclusive or - + .. _!: .. function:: !(x) Boolean not - + .. _&&: .. function:: x && y @@ -334,97 +334,97 @@ Mathematical Operators .. function:: A_ldiv_Bc(a, b) Matrix operator A \ B^H - + .. function:: A_ldiv_Bt(a, b) Matrix operator A \ B^T - + .. function:: A_mul_B!(Y, A, B) -> Y Calculates the matrix-matrix or matrix-vector product *A B* and stores the result in *Y*, overwriting the existing value of *Y*. - + .. function:: A_mul_Bc(...) Matrix operator A B^H - + .. function:: A_mul_Bt(...) Matrix operator A B^T - + .. function:: A_rdiv_Bc(...) Matrix operator A / B^H - + .. function:: A_rdiv_Bt(a, b) Matrix operator A / B^T - + .. function:: Ac_ldiv_B(...) Matrix operator A^H \ B - + .. function:: Ac_ldiv_Bc(...) Matrix operator A^H \ B^H - + .. function:: Ac_mul_B(...) Matrix operator A^H B - + .. function:: Ac_mul_Bc(...) Matrix operator A^H B^H - + .. function:: Ac_rdiv_B(a, b) Matrix operator A^H / B - + .. function:: Ac_rdiv_Bc(a, b) Matrix operator A^H / B^H - + .. function:: At_ldiv_B(...) Matrix operator A^T \ B - + .. function:: At_ldiv_Bt(...) Matrix operator A^T \ B^T - + .. function:: At_mul_B(...) Matrix operator A^T B - + .. function:: At_mul_Bt(...) Matrix operator A^T B^T - + .. function:: At_rdiv_B(a, b) Matrix operator A^T / B - + .. function:: At_rdiv_Bt(a, b) Matrix operator A^T / B^T - + Mathematical Functions ---------------------- @@ -432,292 +432,292 @@ Mathematical Functions .. function:: isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) Inexact equality comparison - behaves slightly different depending on types of input args: For default tolerance arguments, ``maxeps = max(eps(abs(x)), eps(abs(y)))``. - + .. function:: sin(x) Compute sine of ``x``, where ``x`` is in radians - + .. function:: cos(x) Compute cosine of ``x``, where ``x`` is in radians - + .. function:: tan(x) Compute tangent of ``x``, where ``x`` is in radians - + .. function:: sind(x) Compute sine of ``x``, where ``x`` is in degrees - + .. function:: cosd(x) Compute cosine of ``x``, where ``x`` is in degrees - + .. function:: tand(x) Compute tangent of ``x``, where ``x`` is in degrees - + .. function:: sinpi(x) Compute \sin(\pi x) more accurately than ``sin(pi*x)``, especially for large ``x``. - + .. function:: cospi(x) Compute \cos(\pi x) more accurately than ``cos(pi*x)``, especially for large ``x``. - + .. function:: sinh(x) Compute hyperbolic sine of ``x`` - + .. function:: cosh(x) Compute hyperbolic cosine of ``x`` - + .. function:: tanh(x) Compute hyperbolic tangent of ``x`` - + .. function:: asin(x) Compute the inverse sine of ``x``, where the output is in radians - + .. function:: acos(x) Compute the inverse cosine of ``x``, where the output is in radians - + .. function:: atan(x) Compute the inverse tangent of ``x``, where the output is in radians - + .. function:: atan2(y, x) Compute the inverse tangent of ``y/x``, using the signs of both - + .. function:: asind(x) Compute the inverse sine of ``x``, where the output is in degrees - + .. function:: acosd(x) Compute the inverse cosine of ``x``, where the output is in degrees - + .. function:: atand(x) Compute the inverse tangent of ``x``, where the output is in degrees - + .. function:: sec(x) Compute the secant of ``x``, where ``x`` is in radians - + .. function:: csc(x) Compute the cosecant of ``x``, where ``x`` is in radians - + .. function:: cot(x) Compute the cotangent of ``x``, where ``x`` is in radians - + .. function:: secd(x) Compute the secant of ``x``, where ``x`` is in degrees - + .. function:: cscd(x) Compute the cosecant of ``x``, where ``x`` is in degrees - + .. function:: cotd(x) Compute the cotangent of ``x``, where ``x`` is in degrees - + .. function:: asec(x) Compute the inverse secant of ``x``, where the output is in radians - + .. function:: acsc(x) Compute the inverse cosecant of ``x``, where the output is in radians - + .. function:: acot(x) Compute the inverse cotangent of ``x``, where the output is in radians - + .. function:: asecd(x) Compute the inverse secant of ``x``, where the output is in degrees - + .. function:: acscd(x) Compute the inverse cosecant of ``x``, where the output is in degrees - + .. function:: acotd(x) Compute the inverse cotangent of ``x``, where the output is in degrees - + .. function:: sech(x) Compute the hyperbolic secant of ``x`` - + .. function:: csch(x) Compute the hyperbolic cosecant of ``x`` - + .. function:: coth(x) Compute the hyperbolic cotangent of ``x`` - + .. function:: asinh(x) Compute the inverse hyperbolic sine of ``x`` - + .. function:: acosh(x) Compute the inverse hyperbolic cosine of ``x`` - + .. function:: atanh(x) Compute the inverse hyperbolic tangent of ``x`` - + .. function:: asech(x) Compute the inverse hyperbolic secant of ``x`` - + .. function:: acsch(x) Compute the inverse hyperbolic cosecant of ``x`` - + .. function:: acoth(x) Compute the inverse hyperbolic cotangent of ``x`` - + .. function:: sinc(x) Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. - + .. function:: cosc(x) Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq 0, and 0 if x = 0. This is the derivative of ``sinc(x)``. - + .. function:: deg2rad(x) Convert ``x`` from degrees to radians - + .. function:: rad2deg(x) Convert ``x`` from radians to degrees - + .. function:: hypot(x, y) Compute the \sqrt{x^2+y^2} avoiding overflow and underflow - + .. function:: log(b, x) Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. - + .. function:: log(b, x) Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. - + .. function:: log2(x) Compute the logarithm of ``x`` to base 2. Throws ``DomainError`` for negative ``Real`` arguments. - + .. function:: log10(x) Compute the logarithm of ``x`` to base 10. Throws ``DomainError`` for negative ``Real`` arguments. - + .. function:: log1p(x) Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. - + .. function:: frexp(val) Return ``(x,exp)`` such that ``x`` has a magnitude in the interval - + .. function:: exp(x) Compute e^x - + .. function:: exp2(x) Compute 2^x - + .. function:: exp10(x) Compute 10^x - + .. function:: ldexp(x, n) Compute x \times 2^n - + .. function:: modf(x) Return a tuple (fpart,ipart) of the fractional and integral parts of a number. Both parts have the same sign as the argument. - + .. function:: expm1(x) Accurately compute e^x-1 - + .. function:: round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. - + julia> round(pi, 2) 3.14 @@ -787,434 +787,434 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. - + .. function:: ceil([T], x[, digits[, base]]) - + .. function:: floor([T], x[, digits[, base]]) - + .. function:: trunc([T], x[, digits[, base]]) - + .. function:: unsafe_trunc(T, x) value is not representable by ``T``, an arbitrary value will be returned. - + .. function:: signif(x, digits[, base]) Rounds (in the sense of ``round``) ``x`` so that there are representation, default 10. E.g., ``signif(123.456, 2)`` is - + .. function:: min(x, y, ...) Return the minimum of the arguments. Operates elementwise over arrays. - + .. function:: max(x, y, ...) Return the maximum of the arguments. Operates elementwise over arrays. - + .. function:: minmax(x, y) Return ``(min(x,y), max(x,y))``. See also: ``extrema()`` that returns ``(minimum(x), maximum(x))`` - + .. function:: clamp(x, lo, hi) Return x if ``lo <= x <= hi``. If ``x < lo``, return ``lo``. If ``x Operates elementwise over `x`` if it is an array. - + .. function:: abs(x) Absolute value of ``x`` - + .. function:: abs2(x) Squared absolute value of ``x`` - + .. function:: copysign(x, y) Return ``x`` such that it has the same sign as ``y`` - + .. function:: sign(x) Return ``+1`` if ``x`` is positive, ``0`` if ``x == 0``, and ``-1`` if ``x`` is negative. - + .. function:: signbit(x) Returns ``true`` if the value of the sign of ``x`` is negative, otherwise ``false``. - + .. function:: flipsign(x, y) Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``. - + .. function:: sqrt(x) Return \sqrt{x}. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. The prefix operator ``√`` is equivalent to ``sqrt``. - + .. function:: isqrt(n) Integer square root: the largest integer ``m`` such that ``m*m <= n``. - + .. function:: cbrt(x) Return x^{1/3}. The prefix operator ``∛`` is equivalent to - + .. function:: erf(x) Compute the error function of ``x``, defined by - + .. function:: erfc(x) Compute the complementary error function of ``x``, defined by 1 - - + .. function:: erfcx(x) Compute the scaled complementary error function of ``x``, defined by e^{x^2} \operatorname{erfc}(x). Note also that - + .. function:: erfi(x) Compute the imaginary error function of ``x``, defined by -i - + .. function:: dawson(x) Compute the Dawson function (scaled imaginary error function) of - + .. function:: erfinv(x) Compute the inverse error function of a real ``x``, defined by - + .. function:: erfcinv(x) Compute the inverse error complementary function of a real ``x``, defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. - + .. function:: real(z) Return the real part of the complex number ``z`` - + .. function:: imag(z) Return the imaginary part of the complex number ``z`` - + .. function:: reim(z) Return both the real and imaginary parts of the complex number - + .. function:: conj(z) Compute the complex conjugate of a complex number ``z`` - + .. function:: angle(z) Compute the phase angle in radians of a complex number ``z`` - + .. function:: cis(z) Return \exp(iz). - + .. function:: binomial(n, k) Number of ways to choose ``k`` out of ``n`` items - + .. function:: factorial(n, k) Compute ``factorial(n)/factorial(k)`` - + .. function:: factorial(n, k) Compute ``factorial(n)/factorial(k)`` - + .. function:: factor(n) -> Dict Compute the prime factorization of an integer ``n``. Returns a dictionary. The keys of the dictionary correspond to the factors, and hence are of the same type as ``n``. The value associated with each key indicates the number of times the factor appears in the factorization. - + .. function:: gcd(x, y) Greatest common (positive) divisor (or zero if x and y are both zero). - + .. function:: lcm(x, y) Least common (non-negative) multiple. - + .. function:: gcdx(x, y) Computes the greatest common (positive) divisor of ``x`` and ``y`` and their Bézout coefficients, i.e. the integer coefficients ``u`` and ``v`` that satisfy ux+vy = d = gcd(x,y). Note: Bézout coefficients are *not* uniquely defined. ``gcdx`` - + .. function:: ispow2(n) -> Bool Test whether ``n`` is a power of two - + .. function:: nextpow2(n) The smallest power of two not less than ``n``. Returns 0 for - + .. function:: prevpow2(n) The largest power of two not greater than ``n``. Returns 0 for - + .. function:: nextpow(a, x) The smallest ``a^n`` not less than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must be greater than 0. - + .. function:: prevpow(a, x) The largest ``a^n`` not greater than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must not be less than 1. - + .. function:: nextprod([k_1, k_2, ...], n) Next integer not less than ``n`` that can be written as \prod k_i^{p_i} for integers p_1, p_2, etc. - + .. function:: prevprod([k_1, k_2, ...], n) Previous integer not greater than ``n`` that can be written as - + .. function:: invmod(x, m) Take the inverse of ``x`` modulo ``m``: ``y`` such that xy = 1 - + .. function:: powermod(x, p, m) Compute x^p \pmod m - + .. function:: gamma(x) Compute the gamma function of ``x`` - + .. function:: lgamma(x) Compute the logarithm of the absolute value of ``gamma()`` for logarithm of ``gamma(x)``. - + .. function:: lfact(x) Compute the logarithmic factorial of ``x`` - + .. function:: digamma(x) Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(x)``) - + .. function:: invdigamma(x) Compute the inverse digamma function of ``x``. - + .. function:: trigamma(x) Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``) - + .. function:: polygamma(m, x) Compute the polygamma function of order ``m`` of argument ``x`` - + .. function:: airy(k, x) kth derivative of the Airy function \operatorname{Ai}(x). - + .. function:: airyai(x) Airy function \operatorname{Ai}(x). - + .. function:: airyprime(x) Airy function derivative \operatorname{Ai}'(x). - + .. function:: airyaiprime(x) Airy function derivative \operatorname{Ai}'(x). - + .. function:: airybi(x) Airy function \operatorname{Bi}(x). - + .. function:: airybiprime(x) Airy function derivative \operatorname{Bi}'(x). - + .. function:: airyx(k, x) scaled kth derivative of the Airy function, return k == 1``, and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} k == 3``. - + .. function:: besselj0(x) Bessel function of the first kind of order 0, J_0(x). - + .. function:: besselj1(x) Bessel function of the first kind of order 1, J_1(x). - + .. function:: besselj(nu, x) Bessel function of the first kind of order ``nu``, J_\nu(x). - + .. function:: besseljx(nu, x) Scaled Bessel function of the first kind of order ``nu``, J_\nu(x) e^{- | \operatorname{Im}(x) |}. - + .. function:: bessely0(x) Bessel function of the second kind of order 0, Y_0(x). - + .. function:: bessely1(x) Bessel function of the second kind of order 1, Y_1(x). - + .. function:: bessely(nu, x) Bessel function of the second kind of order ``nu``, Y_\nu(x). - + .. function:: besselyx(nu, x) Scaled Bessel function of the second kind of order ``nu``, Y_\nu(x) e^{- | \operatorname{Im}(x) |}. - + .. function:: hankelh1(nu, x) Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x). - + .. function:: hankelh1x(nu, x) Scaled Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x) e^{-x i}. - + .. function:: hankelh2(nu, x) Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x). - + .. function:: hankelh2x(nu, x) Scaled Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x) e^{x i}. - + .. function:: besselh(nu, k, x) Bessel function of the third kind of order ``nu`` (Hankel function). ``k`` is either 1 or 2, selecting ``hankelh1`` or - + .. function:: besseli(nu, x) Modified Bessel function of the first kind of order ``nu``, I_\nu(x). - + .. function:: besselix(nu, x) Scaled modified Bessel function of the first kind of order ``nu``, I_\nu(x) e^{- | \operatorname{Re}(x) |}. - + .. function:: besselk(nu, x) Modified Bessel function of the second kind of order ``nu``, K_\nu(x). - + .. function:: besselkx(nu, x) Scaled modified Bessel function of the second kind of order ``nu``, K_\nu(x) e^x. - + .. function:: beta(x, y) Euler integral of the first kind \operatorname{B}(x,y) = - + .. function:: lbeta(x, y) Natural logarithm of the absolute value of the beta function - + .. function:: eta(x) Dirichlet eta function \eta(s) = - + .. function:: zeta(s, z) Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) - + .. function:: zeta(s, z) Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) - + .. function:: ndigits(n, b) Compute the number of digits in number ``n`` written in base ``b``. - + .. function:: widemul(x, y) Multiply ``x`` and ``y``, giving the result as a larger type. - + .. function:: @evalpoly(z, c...) Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients ascending order by power of ``z``. This macro expands to efficient inline code that uses either Horner's method or, for complex ``z``, a more efficient Goertzel-like algorithm. - + Statistics ---------- @@ -1222,122 +1222,122 @@ Statistics .. function:: mean(v[, region]) Compute the mean of whole array ``v``, or optionally along the dimensions in ``region``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. - + .. function:: mean!(r, v) Compute the mean of ``v`` over the singleton dimensions of ``r``, and write results to ``r``. - + .. function:: std(v[, region]) Compute the sample standard deviation of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the - + .. function:: stdm(v, m) Compute the sample standard deviation of a vector ``v`` with known mean ``m``. Note: Julia does not ignore ``NaN`` values in the computation. - + .. function:: var(v[, region]) Compute the sample variance of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the - + .. function:: varm(v, m) Compute the sample variance of a vector ``v`` with known mean computation. - + .. function:: middle(array) Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + .. function:: middle(array) Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + .. function:: middle(array) Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + .. function:: middle(array) Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + .. function:: median(v) Compute the median of a vector ``v``. ``NaN`` is returned if the data contains any ``NaN`` values. For applications requiring the handling of missing data, the ``DataArrays`` package is recommended. - + .. function:: median!(v) Like ``median``, but may overwrite the input vector. - + .. function:: hist(v, e) -> e, counts Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. - + .. function:: hist(v, e) -> e, counts Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. - + .. function:: hist!(counts, v, e) -> e, counts Compute the histogram of ``v``, using a vector/range ``e`` as the edges for the bins. This function writes the resultant counts to a pre-allocated array ``counts``. - + .. function:: hist2d(M, e1, e2) -> (edge1, edge2, counts) Compute a ``2d histogram`` of a set of N points specified by N-by-2 matrix ``M``. Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as integer bin counts or vectors of bin edges. The result is a tuple of ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges used in the second dimension), and ``counts``, a histogram matrix of size - + .. function:: hist2d!(counts, M, e1, e2) -> (e1, e2, counts) Compute a ``2d histogram`` with respect to the bins delimited by the edges given in ``e1`` and ``e2``. This function writes the results to a pre-allocated array ``counts``. - + .. function:: histrange(v, n) Compute *nice* bin ranges for the edges of a histogram of ``v``, using approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - + .. function:: midpoints(e) Compute the midpoints of the bins with edges ``e``. The result is a vector/range of length ``length(e) - 1``. Note: Julia does not ignore ``NaN`` values in the computation. - + .. function:: quantile(v, p) Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. - + .. function:: quantile(v, p) Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. - + .. function:: quantile!(v, p) Like ``quantile``, but overwrites the input vector. - + .. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) Compute the Pearson covariance between the vector(s) in ``v1`` and This function accepts three keyword arguments: The size of the result depends on the size of ``v1`` and ``v2``. When both ``v1`` and ``v2`` are vectors, it returns the covariance between them as a scalar. When either one is a matrix, it returns a covariance matrix of size ``(n1, n2)``, where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and ``v2``, which depend on the setting of ``vardim``. Note: ``v2`` can be omitted, which indicates ``v2 = v1``. - + .. function:: cor(v1[, v2][, vardim=1, mean=nothing]) Compute the Pearson correlation between the vector(s) in ``v1`` and Users can use the keyword argument ``vardim`` to specify the variable dimension, and ``mean`` to supply pre-computed mean values. - + Signal Processing ----------------- @@ -1351,182 +1351,182 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: fft(A[, dims]) Performs a multidimensional FFT of the array ``A``. The optional an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also A one-dimensional FFT computes the one-dimensional discrete Fourier transform (DFT) as defined by A multidimensional FFT simply performs this operation along each transformed dimension of ``A``. Higher performance is usually possible with multi-threading. Use processors. - + .. function:: fft!(A[, dims]) Same as ``fft()``, but operates in-place on ``A``, which must be an array of complex floating-point numbers. - + .. function:: ifft(A[, dims]) Multidimensional inverse FFT. A one-dimensional inverse FFT computes A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``. - + .. function:: ifft!(A[, dims]) Same as ``ifft()``, but operates in-place on ``A``. - + .. function:: bfft(A[, dims]) Similar to ``ifft()``, but computes an unnormalized inverse sizes of the transformed dimensions in order to obtain the inverse. scaling step, which in some applications can be combined with other computational steps elsewhere.) - + .. function:: bfft!(A[, dims]) Same as ``bfft()``, but operates in-place on ``A``. - + .. function:: plan_fft(A[, dims[, flags[, timelimit]]]) Pre-plan an optimized FFT along given dimensions (``dims``) of arrays matching the shape and type of ``A``. (The first two arguments have the same meaning as for ``fft()``.) Returns a function ``plan(A)`` that computes ``fft(A, dims)`` quickly. The ``flags`` argument is a bitwise-or of FFTW planner flags, defaulting to ``FFTW.ESTIMATE``. e.g. passing ``FFTW.MEASURE`` or benchmarking different possible FFT algorithms and picking the fastest one; see the FFTW manual for more information on planner flags. The optional ``timelimit`` argument specifies a rough upper bound on the allowed planning time, in seconds. Passing that operates in-place on its argument (which must be an array of complex floating-point numbers). ``plan_ifft()`` and so on are similar but produce plans that perform the equivalent of the inverse transforms ``ifft()`` and so on. - + .. function:: plan_ifft(A[, dims[, flags[, timelimit]]]) Same as ``plan_fft()``, but produces a plan that performs inverse transforms ``ifft()``. - + .. function:: plan_bfft(A[, dims[, flags[, timelimit]]]) Same as ``plan_fft()``, but produces a plan that performs an unnormalized backwards transform ``bfft()``. - + .. function:: plan_fft!(A[, dims[, flags[, timelimit]]]) Same as ``plan_fft()``, but operates in-place on ``A``. - + .. function:: plan_ifft!(A[, dims[, flags[, timelimit]]]) Same as ``plan_ifft()``, but operates in-place on ``A``. - + .. function:: plan_bfft!(A[, dims[, flags[, timelimit]]]) Same as ``plan_bfft()``, but operates in-place on ``A``. - + .. function:: rfft(A[, dims]) Multidimensional FFT of a real array A, exploiting the fact that the transform has conjugate symmetry in order to save roughly half the computational time and storage costs compared with ``fft()``. If ``A`` has size ``(n_1, ..., n_d)``, the result has size The optional ``dims`` argument specifies an iterable subset of one or more dimensions of ``A`` to transform, similar to ``fft()``. Instead of (roughly) halving the first dimension of ``A`` in the result, the ``dims[1]`` dimension is (roughly) halved in the same way. - + .. function:: irfft(A, d[, dims]) Inverse of ``rfft()``: for a complex array ``A``, gives the corresponding real array whose FFT yields ``A`` in the first half. As for ``rfft()``, ``dims`` is an optional subset of dimensions to transform, defaulting to ``1:ndims(A)``. floor(size(A,dims[1])/2)+1``. (This parameter cannot be inferred from `size(A)`` due to the possibility of rounding by the - + .. function:: brfft(A, d[, dims]) Similar to ``irfft()`` but computes an unnormalized inverse transform (similar to ``bfft()``), which must be divided by the product of the sizes of the transformed dimensions (of the real output array) in order to obtain the inverse transform. - + .. function:: plan_rfft(A[, dims[, flags[, timelimit]]]) Pre-plan an optimized real-input FFT, similar to ``plan_fft()`` except for ``rfft()`` instead of ``fft()``. The first two arguments, and the size of the transformed result, are the same as for ``rfft()``. - + .. function:: plan_brfft(A, d[, dims[, flags[, timelimit]]]) Pre-plan an optimized real-input unnormalized transform, similar to first two arguments and the size of the transformed result, are the same as for ``brfft()``. - + .. function:: plan_irfft(A, d[, dims[, flags[, timelimit]]]) Pre-plan an optimized inverse real-input FFT, similar to respectively. The first three arguments have the same meaning as for ``irfft()``. - + .. function:: dct(A[, dims]) Performs a multidimensional type-II discrete cosine transform (DCT) of the array ``A``, using the unitary normalization of the DCT. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also ``plan_dct()`` for even greater efficiency. - + .. function:: dct!(A[, dims]) Same as ``dct!()``, except that it operates in-place on ``A``, which must be an array of real or complex floating-point values. - + .. function:: idct(A[, dims]) Computes the multidimensional inverse discrete cosine transform unitary normalization). The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see efficiency. - + .. function:: idct!(A[, dims]) Same as ``idct!()``, but operates in-place on ``A``. - + .. function:: plan_dct(A[, dims[, flags[, timelimit]]]) Pre-plan an optimized discrete cosine transform (DCT), similar to The first two arguments have the same meaning as for ``dct()``. - + .. function:: plan_dct!(A[, dims[, flags[, timelimit]]]) Same as ``plan_dct()``, but operates in-place on ``A``. - + .. function:: plan_idct(A[, dims[, flags[, timelimit]]]) Pre-plan an optimized inverse discrete cosine transform (DCT), similar to ``plan_fft()`` except producing a function that computes - + .. function:: plan_idct!(A[, dims[, flags[, timelimit]]]) Same as ``plan_idct()``, but operates in-place on ``A``. - + .. function:: fftshift(x, dim) Swap the first and second halves of the given dimension of array - + .. function:: fftshift(x, dim) Swap the first and second halves of the given dimension of array - + .. function:: ifftshift(x[, dim]) Undoes the effect of ``fftshift``. - + .. function:: filt(b, a, x[, si]) Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an optional initial filter state vector ``si`` (defaults to zeros). - + .. function:: filt!(out, b, a, x[, si]) Same as ``filt()`` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. - + .. function:: deconv(b, a) Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. - + .. function:: conv(u, v) Convolution of two vectors. Uses FFT algorithm. - + .. function:: conv2(B, A) 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm - + .. function:: conv2(B, A) 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm - + .. function:: xcorr(u, v) Compute the cross-correlation of two vectors. - + The following functions are defined within the ``Base.FFTW`` module. @@ -1535,22 +1535,22 @@ The following functions are defined within the ``Base.FFTW`` module. .. function:: r2r(A, kind[, dims]) Performs a multidimensional real-input/real-output (r2r) transform of type ``kind`` of the array ``A``, as defined in the FFTW manual. types (``FFTW.REDFT00``, ``FFTW.REDFT01``, ``FFTW.REDFT10``, or Hartley transform (``FFTW.DHT``). The ``kind`` argument may be an array or tuple in order to specify different transform types along the different dimensions of ``A``; ``kind[end]`` is used for any unspecified dimensions. See the FFTW manual for precise definitions of these transform types, at http://www.fftw.org/doc. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. ``kind[i]`` is then the transform type for ``dims[i]``, with See also ``plan_r2r()`` to pre-plan optimized r2r transforms. - + .. function:: r2r!(A, kind[, dims]) Same as ``r2r()``, but operates in-place on ``A``, which must be an array of real or complex floating-point numbers. - + .. function:: plan_r2r(A, kind[, dims[, flags[, timelimit]]]) Pre-plan an optimized r2r transform, similar to ``Base.plan_fft()`` except that the transforms (and the first three arguments) correspond to ``r2r()`` and ``r2r!()``, respectively. - + .. function:: plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) Similar to ``Base.plan_fft()``, but corresponds to ``r2r!()``. - + .. currentmodule:: Base Numerical Integration @@ -1563,5 +1563,5 @@ some built-in integration support in Julia. .. function:: quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) Numerically integrate the function ``f(x)`` from ``a`` to ``b``, and optionally over additional intervals ``b`` to ``c`` and so on. Keyword options include a relative error tolerance ``reltol`` absolute error tolerance ``abstol`` (defaults to 0), a maximum number of function evaluations ``maxevals`` (defaults to ``10^7``), and the ``order`` of the integration rule (defaults to 7). Returns a pair ``(I,E)`` of the estimated integral ``I`` and an estimated upper bound on the absolute error ``E``. If ``maxevals`` is not exceeded then ``E <= max(abstol, reltol*norm(I))`` will hold. (Note that it is useful to specify a positive ``abstol`` in cases where ``norm(I)`` may be zero.) The endpoints ``a`` etcetera can also be complex (in which case the integral is performed over straight-line segments in the complex plane). If the endpoints are ``BigFloat``, then the integration will be performed in ``BigFloat`` precision as well (note: it is advisable to increase the integration ``order`` in rough proportion to the precision, for smooth integrands). More generally, the precision is set by the precision of the integration endpoints The integrand ``f(x)`` can return any numeric scalar, vector, or matrix type, or in fact any type supporting ``+``, ``-``, multiplication by real values, and a ``norm`` (i.e., any normed vector space). Alternatively, a different norm can be specified by passing a *norm*-like function as the *norm* keyword argument multi-dimensional integration (cubature), there are many different algorithms (often much better than simple nested 1d integrals) and the optimal choice tends to be very problem-dependent. See the Julia external-package listing for available algorithms for multidimensional integration or other specialized tasks (such as integrals of highly oscillatory or singular functions).] The algorithm is an adaptive Gauss-Kronrod integration technique: the integral in each interval is estimated using a Kronrod rule Gauss rule (``order`` points). The interval with the largest error is then subdivided into two intervals and the process is repeated until the desired error tolerance is achieved. These quadrature rules work best for smooth functions within each interval, so if your function has a known discontinuity or other singularity, it is best to subdivide your interval to put the singularity at an endpoint. For example, if ``f`` has a discontinuity at ``x=0.7`` and you want to integrate from 0 to 1, you should use ``quadgk(f, 0,0.7,1)`` to subdivide the interval at the point of discontinuity. The integrand is never evaluated exactly at the endpoints of the intervals, so it is possible to integrate functions that diverge at the endpoints as long as the singularity is integrable (for example, a ``log(x)`` or For real-valued endpoints, the starting and/or ending points may be infinite. (A coordinate transformation is performed internally to map the infinite interval to a finite one.) - + diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index aac9e41d7d68f..9c6022f86a865 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -15,112 +15,112 @@ Data Formats .. function:: bin(n[, pad]) Convert an integer to a binary string, optionally specifying a number of digits to pad to. - + .. function:: hex(n[, pad]) Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. - + .. function:: dec(n[, pad]) Convert an integer to a decimal string, optionally specifying a number of digits to pad to. - + .. function:: oct(n[, pad]) Convert an integer to an octal string, optionally specifying a number of digits to pad to. - + .. function:: base(base, n[, pad]) Convert an integer to a string in the given base, optionally specifying a number of digits to pad to. The base can be specified as either an integer, or as a ``UInt8`` array of character values to use as digit symbols. - + .. function:: digits(n[, base][, pad]) Returns an array of the digits of ``n`` in the given base, optionally padded with zeros to a specified size. More significant digits are at higher indexes, such that ``n == sum([digits[k]*base^(k-1) for k=1:length(digits)])``. - + .. function:: digits!(array, n[, base]) Fills an array of the digits of ``n`` in the given base. More significant digits are at higher indexes. If the array length is insufficient, the least significant digits are filled up to the array length. If the array length is excessive, the excess portion is filled with zeros. - + .. function:: bits(n) A string giving the literal bit representation of a number. - + .. function:: parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. - + .. function:: tryparse(type, str[, base]) Like ``parse``, but returns a ``Nullable`` of the requested type. The result will be null if the string does not contain a valid number. - + .. function:: big(x) Convert a number to a maximum precision representation (typically some pitfalls with floating-point numbers. - + .. function:: signed(x) Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. - + .. function:: unsigned(x) -> Unsigned Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as unsigned without checking for negative values. - + .. function:: float(x) Convert a number, array, or string to a ``FloatingPoint`` data type. For numeric data, the smallest suitable ``FloatingPoint`` type is used. Converts strings to ``Float64``. - + .. function:: significand(x) Extract the significand(s) (a.k.a. mantissa), in binary representation, of a floating-point number or array. If ``x`` is a non-zero finite number, than the result will be a number of the same type on the interval [1,2). Otherwise ``x`` is returned. - + .. function:: exponent(x) -> Int Get the exponent of a normalized floating-point number. - + .. function:: complex(r[, i]) Convert real numbers or arrays to complex. ``i`` defaults to zero. - + .. function:: bswap(n) Byte-swap an integer - + .. function:: num2hex(f) Get a hexadecimal string of the binary representation of a floating point number - + .. function:: hex2num(str) Convert a hexadecimal string to the floating point number it represents - + .. function:: hex2bytes(s::ASCIIString) Convert an arbitrarily long hexadecimal string to its binary representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. - + .. function:: bytes2hex(bin_arr::Array{UInt8, 1}) Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. - + General Number Functions and Constants -------------------------------------- @@ -128,12 +128,12 @@ General Number Functions and Constants .. function:: one(x) Get the multiplicative identity element for the type of x (x can also specify the type itself). For matrices, returns an identity matrix of the appropriate size and type. - + .. function:: zero(x) Get the additive identity element for the type of x (x can also specify the type itself). - + .. data:: pi π @@ -190,87 +190,87 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool Test whether a floating point number is subnormal - + .. function:: isfinite(f) -> Bool Test whether a number is finite - + .. function:: isinf(f) -> Bool Test whether a number is infinite - + .. function:: isnan(f) -> Bool Test whether a floating point number is not a number (NaN) - + .. function:: inf(f) Returns positive infinity of the floating point type ``f`` or of the same floating point type as ``f`` - + .. function:: nan(f) Returns NaN (not-a-number) of the floating point type ``f`` or of the same floating point type as ``f`` - + .. function:: nextfloat(f) Get the next floating point number in lexicographic order - + .. function:: prevfloat(f) -> FloatingPoint Get the previous floating point number in lexicographic order - + .. function:: isinteger(x) -> Bool Test whether ``x`` or all its elements are numerically equal to some integer - + .. function:: isreal(x) -> Bool Test whether ``x`` or all its elements are numerically equal to some real number - + .. function:: Float32(x[, mode::RoundingMode]) Create a Float32 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. - + .. function:: Float64(x[, mode::RoundingMode]) Create a Float64 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. - + .. function:: BigInt(x) Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``). The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. Instances can be constructed from strings via ``parse()``, or using the ``big`` string literal. - + .. function:: BigFloat(x) Create an arbitrary precision floating point number. ``x`` may be an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results are promoted to a ``BigFloat``. Note that because decimal literals are converted to floating point numbers when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead prefer to initialize constants from strings via ``parse()``, or using the ``big`` string literal. - + .. function:: get_rounding(T) Get the current floating point rounding mode for type ``T``, controlling the rounding of basic arithmetic functions (``+()``, Valid modes are ``RoundNearest``, ``RoundToZero``, ``RoundUp``, - + .. function:: set_rounding(T, mode) Set the rounding mode of floating point type ``T``, controlling the rounding of basic arithmetic functions (``+()``, ``-()``, ``*()``, Note that this may affect other types, for instance changing the rounding mode of ``Float64`` will change the rounding mode of - + .. function:: with_rounding(f::Function, T, mode) Change the rounding mode of floating point type ``T`` for the duration of ``f``. It is logically equivalent to: See ``get_rounding`` for available rounding modes. - + Integers ~~~~~~~~ @@ -278,57 +278,57 @@ Integers .. function:: count_ones(x::Integer) -> Integer Number of ones in the binary representation of ``x``. - + .. function:: count_zeros(x::Integer) -> Integer Number of zeros in the binary representation of ``x``. - + .. function:: leading_zeros(x::Integer) -> Integer Number of zeros leading the binary representation of ``x``. - + .. function:: leading_ones(x::Integer) -> Integer Number of ones leading the binary representation of ``x``. - + .. function:: trailing_zeros(x::Integer) -> Integer Number of zeros trailing the binary representation of ``x``. - + .. function:: trailing_ones(x::Integer) -> Integer Number of ones trailing the binary representation of ``x``. - + .. function:: isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). - + .. function:: isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). - + .. function:: primes(n) Returns a collection of the prime numbers <= ``n``. - + .. function:: isodd(x::Integer) -> Bool Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and - + .. function:: iseven(x::Integer) -> Bool Returns ``true`` is ``x`` is even (that is, divisible by 2), and - + BigFloats --------- @@ -337,22 +337,22 @@ The `BigFloat` type implements arbitrary-precision floating-point arithmetic usi .. function:: precision(num::FloatingPoint) Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. - + .. function:: get_bigfloat_precision() Get the precision (in bits) currently used for BigFloat arithmetic. - + .. function:: set_bigfloat_precision(x::Int64) Set the precision (in bits) to be used to BigFloat arithmetic. - + .. function:: with_bigfloat_precision(f::Function, precision::Integer) Change the BigFloat arithmetic precision (in bits) for the duration of ``f``. It is logically equivalent to: - + .. _random-numbers: @@ -376,50 +376,50 @@ As ``BigInt`` represents unbounded integers, the interval must be specified (e.g .. function:: srand([rng][, seed]) Reseed the random number generator. If a ``seed`` is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. For ``MersenneTwister``, the integers or a filename, in which case the seed is read from a file. - + .. function:: MersenneTwister([seed]) Create a ``MersenneTwister`` RNG object. Different RNG objects can have their own seeds, which may be useful for generating different streams of random numbers. - + .. function:: RandomDevice() Create a ``RandomDevice`` RNG object. Two such objects will always generate different streams of random numbers. - + .. function:: rand([rng][, S][, dims...]) Pick a random element or array of random elements from the set of values specified by ``S``; ``S`` can be - + .. function:: rand!([rng], A[, coll]) Populate the array A with random values. If the indexable collection ``coll`` is specified, the values are picked randomly from ``coll``. This is equivalent to ``copy!(A, rand(rng, coll, size(A)))`` or ``copy!(A, rand(rng, eltype(A), size(A)))`` but without allocating a new array. - + .. function:: bitrand([rng][, dims...]) Generate a ``BitArray`` of random boolean values. - + .. function:: randn([rng][, dims...]) Generate a normally-distributed random number with mean 0 and standard deviation 1. Optionally generate an array of normally- distributed random numbers. - + .. function:: randn!([rng], A::Array{Float64, N}) Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand function. - + .. function:: randexp([rng][, dims...]) Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. - + .. function:: randexp!([rng], A::Array{Float64, N}) Fill the array A with random numbers following the exponential distribution (with scale 1). - + diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 0b1319d7e2308..0b43168793c9c 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -10,102 +10,102 @@ Tasks .. function:: Task(func) Create a ``Task`` (i.e. thread, or coroutine) to execute the given function (which must be callable with no arguments). The task exits when this function returns. - + .. function:: yieldto(task, arg = nothing) Switch to the given task. The first time a task is switched to, the task's function is called with no arguments. On subsequent switches, ``arg`` is returned from the task's last call to considering states or scheduling in any way. Its use is discouraged. - + .. function:: current_task() Get the currently running Task. - + .. function:: istaskdone(task) -> Bool Tell whether a task has exited. - + .. function:: istaskstarted(task) -> Bool Tell whether a task has started executing. - + .. function:: consume(task, values...) Receive the next value passed to ``produce`` by the specified task. Additional arguments may be passed, to be returned from the last - + .. function:: produce(value) Send the given value to the last ``consume`` call, switching to the consumer task. If the next ``consume`` call passes any values, they are returned by ``produce``. - + .. function:: yield() Switch to the scheduler to allow another scheduled task to run. A task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. - + .. function:: task_local_storage(body, symbol, value) Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. - + .. function:: task_local_storage(body, symbol, value) Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. - + .. function:: task_local_storage(body, symbol, value) Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. - + .. function:: Condition() Create an edge-triggered event source that tasks can wait for. Tasks that call ``wait`` on a ``Condition`` are suspended and queued. Tasks are woken up when ``notify`` is later called on the time ``notify`` is called can be woken up. For level-triggered notifications, you must keep extra state to keep track of whether a notification has happened. The ``RemoteRef`` type does this, and so can be used for level-triggered events. - + .. function:: notify(condition, val=nothing; all=true, error=false) Wake up tasks waiting for a condition, passing them ``val``. If otherwise only one is. If ``error`` is true, the passed value is raised as an exception in the woken tasks. - + .. function:: schedule(t::Task, [val]; error=false) Add a task to the scheduler's queue. This causes the task to run constantly when the system is otherwise idle, unless the task performs a blocking operation such as ``wait``. If a second argument is provided, it will be passed to the task task. - + .. function:: @schedule() Wrap an expression in a Task and add it to the scheduler's queue. - + .. function:: @task() Wrap an expression in a Task without executing it, and return the Task. This only creates a task, and does not run it. - + .. function:: sleep(seconds) Block the current task for a specified number of seconds. The minimum sleep time is 1 millisecond or input of ``0.001``. - + .. function:: ReentrantLock() Creates a reentrant lock. The same task can acquire the lock as many times as required. Each lock must be matched with an unlock. - + .. function:: lock(l::ReentrantLock) Associates ``l`` with the current task. If ``l`` is already locked by a different task, waits for it to become available. The same task can acquire the lock multiple times. Each ``lock`` must be matched by an ``unlock`` - + .. function:: unlock(l::ReentrantLock) Releases ownership of the lock by the current task. If the lock had been acquired before, it just decrements an internal counter and returns immediately. - + General Parallel Computing Support ---------------------------------- @@ -113,152 +113,152 @@ General Parallel Computing Support .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. - + .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. - + .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. - + .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. - + .. function:: nprocs() Get the number of available processes. - + .. function:: nworkers() Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. - + .. function:: procs(S::SharedArray) Get the vector of processes that have mapped the shared array - + .. function:: workers() Returns a list of all worker process identifiers. - + .. function:: rmprocs(pids...) Removes the specified workers. - + .. function:: interrupt([pids...]) Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted. - + .. function:: myid() Get the id of the current process. - + .. function:: pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) Transform collections ``lsts`` by applying ``f`` to each element in parallel. If ``nprocs() > 1``, the calling process will be dedicated to assigning tasks. All other available processes will be used as parallel workers, or on the processes specified by If ``err_retry`` is true, it retries a failed application of ``f`` on a different worker. If ``err_stop`` is true, it takes precedence over the value of ``err_retry`` and ``pmap`` stops execution on the first error. - + .. function:: remotecall(id, func, args...) Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. - + .. function:: wait([x]) Block the current task until some event occurs, depending on the type of the argument: If no argument is passed, the task blocks for an undefined period. If the task's state is set to ``:waiting``, it can only be restarted by an explicit call to ``schedule`` or ``yieldto``. If the task's state is ``:runnable``, it might be restarted unpredictably. Often ``wait`` is called within a ``while`` loop to ensure a waited-for condition is met before proceeding. - + .. function:: fetch(RemoteRef) Wait for and get the value of a remote reference. - + .. function:: remotecall_wait(id, func, args...) Perform ``wait(remotecall(...))`` in one message. - + .. function:: remotecall_fetch(id, func, args...) Perform ``fetch(remotecall(...))`` in one message. - + .. function:: put!(RemoteRef, value) Store a value to a remote reference. Implements ``shared queue of length 1`` semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. - + .. function:: take!(RemoteRef) Fetch the value of a remote reference, removing it so that the reference is empty again. - + .. function:: isready(r::RemoteRef) Determine whether a ``RemoteRef`` has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. It is recommended that this function only be used on a ``RemoteRef`` that is assigned once. If the argument ``RemoteRef`` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for ``r`` in a separate task instead, or to use a local - + .. function:: RemoteRef(n) Make an uninitialized remote reference on process ``n``. - + .. function:: RemoteRef(n) Make an uninitialized remote reference on process ``n``. - + .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) Waits till ``testcb`` returns ``true`` or for ``secs`` seconds, whichever is earlier. ``testcb`` is polled every ``pollint`` seconds. - + .. function:: @spawn() Execute an expression on an automatically-chosen process, returning a ``RemoteRef`` to the result. - + .. function:: @spawnat() Accepts two arguments, ``p`` and an expression, and runs the expression asynchronously on process ``p``, returning a - + .. function:: @fetch() Equivalent to ``fetch(@spawn expr)``. - + .. function:: @fetchfrom() Equivalent to ``fetch(@spawnat p expr)``. - + .. function:: @async() Schedule an expression to run on the local machine, also adding it to the set of items that the nearest enclosing ``@sync`` waits for. - + .. function:: @sync() Wait until all dynamically-enclosed uses of ``@async``, ``@spawn``, - + .. function:: @parallel() A parallel for loop of the form The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, reduction on the calling process. Note that without a reducer function, @parallel executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with ``@sync``, like - + Shared Arrays (Experimental, UNIX-only feature) ----------------------------------------------- @@ -266,22 +266,22 @@ Shared Arrays (Experimental, UNIX-only feature) .. function:: SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) Construct a SharedArray of a bitstype ``T`` and size ``dims`` across the processes specified by ``pids`` - all of which have to be on the same host. If ``pids`` is left unspecified, the shared array will be mapped across all processes on the current host, including the master. But, ``localindexes`` and ``indexpids`` will only refer to worker processes. This facilitates work distribution code to use workers for actual computation with the master process acting as a driver. If an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, it is called on all the participating workers. - + .. function:: procs(S::SharedArray) Get the vector of processes that have mapped the shared array - + .. function:: sdata(S::SharedArray) Returns the actual ``Array`` object backing ``S`` - + .. function:: indexpids(S::SharedArray) Returns the index of the current worker into the ``pids`` vector, i.e., the list of workers mapping the SharedArray - + Cluster Manager Interface ------------------------- @@ -293,27 +293,27 @@ Cluster Manager Interface .. function:: launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) Implemented by cluster managers. For every Julia worker launched by this function, it should append a ``WorkerConfig`` entry to once all workers, requested by ``manager`` have been launched. was called with. - + .. function:: manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) Implemented by cluster managers. It is called on the master process, during a worker's lifetime, with appropriate ``op`` values: - + .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. - + .. function:: init_worker(manager::FooManager) Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets for transport. - + .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. - + .. function:: Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index 36a41338871ce..fd766cb97a799 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -10,135 +10,135 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, .. function:: dir(names...) -> AbstractString Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. - + .. function:: dir(names...) -> AbstractString Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. - + .. function:: init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) Initialize ``Pkg.dir()`` as a package directory. This will be done automatically when the ``JULIA_PKGDIR`` is not set and clones a local METADATA git repository from the site and branch specified by its arguments, which are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. - + .. function:: resolve() Determines an optimal, consistent set of package versions to install or upgrade to. The optimal set of package versions is based on the contents of ``Pkg.dir(``REQUIRE``)`` and the state of installed packages in ``Pkg.dir()``, Packages that are no longer required are moved into ``Pkg.dir(``.trash``)``. - + .. function:: edit() Opens ``Pkg.dir(``REQUIRE``)`` in the editor specified by the command returns, it runs ``Pkg.resolve()`` to determine and install a new optimal set of installed package versions. - + .. function:: add(pkg, vers...) Add a requirement entry for ``pkg`` to ``Pkg.dir(``REQUIRE``)`` and call ``Pkg.resolve()``. If ``vers`` are given, they must be intervals for ``pkg``. - + .. function:: rm(pkg) Remove all requirement entries for ``pkg`` from - + .. function:: clone(pkg) If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. - + .. function:: clone(pkg) If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. - + .. function:: available(pkg) -> Vector{VersionNumber} Returns the version numbers available for package ``pkg``. - + .. function:: available(pkg) -> Vector{VersionNumber} Returns the version numbers available for package ``pkg``. - + .. function:: installed(pkg) -> Void | VersionNumber If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. - + .. function:: installed(pkg) -> Void | VersionNumber If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. - + .. function:: status() Prints out a summary of what packages are installed and what version and state they're in. - + .. function:: update() Update package the metadata repo – kept in safely be pulled from their origin; then call ``Pkg.resolve()`` to determine a new optimal set of packages versions. - + .. function:: checkout(pkg[, branch="master"]) Checkout the ``Pkg.dir(pkg)`` repo to the branch ``branch``. Defaults to checking out the ``master`` branch. To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` - + .. function:: pin(pkg, version) Pin ``pkg`` at registered version ``version``. - + .. function:: pin(pkg, version) Pin ``pkg`` at registered version ``version``. - + .. function:: free(pkg) Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and You can also supply an iterable collection of package names, e.g., once. - + .. function:: build(pkgs...) Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. - + .. function:: build(pkgs...) Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. - + .. function:: generate(pkg, license) Generate a new package named ``pkg`` with one of these license keys: ``MIT``, ``BSD`` or ``ASL``. If you want to make a package with a different license, you can edit it afterwards. Generate creates a git repo at ``Pkg.dir(pkg)`` for the package and inside it ``LICENSE.md``, ``README.md``, the julia entrypoint - + .. function:: register(pkg[, url]) Register ``pkg`` at the git URL ``url``, defaulting to the configured origin URL of the git repo ``Pkg.dir(pkg)``. - + .. function:: tag(pkg[, ver[, commit]]) Tag ``commit`` as version ``ver`` of package ``pkg`` and create a version entry in ``METADATA``. If not provided, ``commit`` defaults to the current commit of the ``pkg`` repo. If ``ver`` is one of the symbols ``:patch``, ``:minor``, ``:major`` the next patch, minor or major version is used. If ``ver`` is not provided, it defaults to - + .. function:: publish() For each new package version tagged in ``METADATA`` not already published, make sure that the tagged package commits have been pushed to the repo at the registered URL for the package and if they all have, open a pull request to ``METADATA``. - + .. function:: test(pkgs...) Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. - + .. function:: test(pkgs...) Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. - + diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index e214e1183badf..4e11d1152943f 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -11,7 +11,7 @@ .. function:: @profile() periodic backtraces. These are appended to an internal buffer of backtraces. - + .. currentmodule:: Base.Profile The methods in :mod:`Base.Profile` are not exported and need to be called e.g. as ``Profile.print()``. @@ -19,40 +19,40 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a .. function:: clear() Clear any existing backtraces from the internal buffer. - + .. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. - + .. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. - + .. function:: init(; n::Integer, delay::Float64) Configure the ``delay`` between backtraces (measured in seconds), and the number ``n`` of instruction pointers that may be stored. Each instruction pointer corresponds to a single line of code; backtraces generally consist of a long list of instruction pointers. Default settings can be obtained by calling this function with no arguments, and each can be set independently using keywords or in the order ``(n, delay)``. - + .. function:: fetch() -> data Returns a reference to the internal buffer of backtraces. Note that subsequent operations, like ``clear()``, can affect ``data`` unless you first make a copy. Note that the values in ``data`` have meaning only on this machine in the current session, because it depends on the exact memory addresses used in JIT-compiling. This function is primarily for internal use; ``retrieve()`` may be a better choice for most users. - + .. function:: retrieve() -> data, lidict set of all backtraces (``data``) and a dictionary that maps the values that store the file name, function name, and line number. This function allows you to save profiling results for future analysis. - + .. function:: callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} Given a previous profiling run, determine who called a particular function. Supplying the filename (and optionally, range of line numbers over which the function is defined) allows you to disambiguate an overloaded method. The returned value is a vector containing a count of the number of calls and line information about the caller. One can optionally supply backtrace data obtained from ``retrieve()``; otherwise, the current internal profile buffer is used. - + .. function:: clear_malloc_data() Clears any stored memory allocation data when running julia with ` force JIT-compilation), then call ``clear_malloc_data()``. Then execute your command(s) again, quit Julia, and examine the resulting ``*.mem`` files. - + diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 8ef13f75c3302..9a73bc3f9589c 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -120,37 +120,37 @@ Sorting Functions .. function:: sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) Sort the vector ``v`` in place. ``QuickSort`` is used by default for numeric arrays while ``MergeSort`` is used for other arrays. You can specify an algorithm to use via the ``alg`` keyword (see Sorting Algorithms for available algorithms). The ``by`` keyword lets you provide a function that will be applied to each element before comparison; the ``lt`` keyword allows providing a custom order. These options are independent and can be used together in all possible combinations: if both ``by`` and ``lt`` are specified, the ``lt`` function is applied to the result of the ``by`` function; ``rev=true`` reverses whatever ordering specified via the - + .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) Sort a multidimensional array ``A`` along the given dimension. - + .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) Sort a multidimensional array ``A`` along the given dimension. - + .. function:: sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) Return a permutation vector of indices of ``v`` that puts it in sorted order. Specify ``alg`` to choose a particular sorting algorithm (see Sorting Algorithms). ``MergeSort`` is used by default, and since it is stable, the resulting permutation will be the lexicographically first one that puts the input array into sorted order – i.e. indices of equal elements appear in ascending order. If you choose a non-stable sorting algorithm such as order may be returned. The order is specified using the same keywords as ``sort!``. See also ``sortperm!()`` - + .. function:: sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) Like ``sortperm``, but accepts a preallocated index vector ``ix``. If ``initialized`` is ``false`` (the default), ix is initialized to contain the values ``1:length(v)``. See also ``sortperm()`` - + .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) Sort the rows of matrix ``A`` lexicographically. - + .. function:: sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) Sort the columns of matrix ``A`` lexicographically. - + Order-Related Functions ----------------------- @@ -158,32 +158,32 @@ Order-Related Functions .. function:: issorted(v, [by=,] [lt=,] [rev=false]) Test whether a vector is in sorted order. The ``by``, ``lt`` and as they do for ``sort``. - + .. function:: searchsorted(a, x, [by=,] [lt=,] [rev=false]) Returns the range of indices of ``a`` which compare as equal to order. Returns an empty range located at the insertion point if - + .. function:: searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) Returns the index of the first value in ``a`` greater than or equal to ``x``, according to the specified order. Returns ``length(a)+1`` if ``x`` is greater than all values in ``a``. - + .. function:: searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) Returns the index of the last value in ``a`` less than or equal to less than all values in ``a``. - + .. function:: select!(v, k, [by=,] [lt=,] [rev=false]) Partially sort the vector ``v`` in place, according to the order specified by ``by``, ``lt`` and ``rev`` so that the value at index the position where it would appear if the array were fully sorted via a non-stable algorithm. If ``k`` is a single index, that value is returned; if ``k`` is a range, an array of values at those indices is returned. Note that ``select!`` does not fully sort the input array. - + .. function:: select(v, k, [by=,] [lt=,] [rev=false]) Variant of ``select!`` which copies ``v`` before partially sorting it, thereby returning the same thing as ``select!`` but leaving - + Sorting Algorithms ------------------ diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index d59f309ed1257..79d994b6cebf3 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -7,17 +7,17 @@ .. function:: length(s) The number of characters in string ``s``. - + .. function:: sizeof(s::AbstractString) The number of bytes in string ``s``. - + .. function:: *(s, t) Concatenate strings. The ``*`` operator is an alias to this function. - + julia> "Hello " * "world" "Hello world" @@ -25,355 +25,355 @@ .. function:: ^(s, n) Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. - + .. function:: string(xs...) Create a string from any values using the ``print`` function. - + .. function:: repr(x) Create a string from any value using the ``showall`` function. - + .. function:: bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. - + .. function:: bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. - + .. function:: ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. - + .. function:: ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. - + .. function:: ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. - + .. function:: utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). - + .. function:: utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). - + .. function:: utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). - + .. function:: normalize_string(s, normalform::Symbol) Normalize the string ``s`` according to one of the four ``normal forms`` of the Unicode standard: ``normalform`` can be ``:NFC``, composition) and D (canonical decomposition) convert different visually identical representations of the same abstract string into a single canonical form, with form C being more compact. Normal forms KC and KD additionally canonicalize ``compatibility equivalents``: they convert characters that are abstractly similar but visually distinct into a single canonical choice (e.g. they expand ligatures into the individual characters), with form KC being more compact. Alternatively, finer control and additional transformations may be be obtained by calling *normalize_string(s; keywords...)*, where any number of the following boolean keywords options (which all default to ``false`` except for ``compose``) are specified: For example, NFKC corresponds to the options ``compose=true, compat=true, stable=true``. - + .. function:: graphemes(s) -> iterator over substrings of s Returns an iterator over substrings of ``s`` that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) - + .. function:: isvalid(str, i) Tells whether index ``i`` is valid for the given string - + .. function:: isvalid(str, i) Tells whether index ``i`` is valid for the given string - + .. function:: is_assigned_char(c) -> Bool Returns true if the given char or integer is an assigned Unicode code point. - + .. function:: ismatch(r::Regex, s::AbstractString) -> Bool Test whether a string contains a match of the given regular expression. - + .. function:: match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) Search for the first match of the regular expression ``r`` in ``s`` and return a RegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessing ``m.match`` and the captured sequences can be retrieved by accessing ``m.captures`` The optional ``idx`` argument specifies an index at which to start the search. - + .. function:: eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) Search for all matches of a the regular expression ``r`` in ``s`` and return a iterator over the matches. If overlap is true, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges. - + .. function:: matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} Return a vector of the matching substrings from eachmatch. - + .. function:: lpad(string, n, p) Make a string at least ``n`` columns wide when printed, by padding on the left with copies of ``p``. - + .. function:: rpad(string, n, p) Make a string at least ``n`` columns wide when printed, by padding on the right with copies of ``p``. - + .. function:: search(string, chars[, start]) Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that ``s[search(s,x)] == x``: - + .. function:: rsearch(string, chars[, start]) Similar to ``search``, but returning the last occurrence of the given characters within the given string, searching in reverse from - + .. function:: searchindex(string, substring[, start]) Similar to ``search``, but return only the start index at which the substring is found, or 0 if it is not. - + .. function:: rsearchindex(string, substring[, start]) Similar to ``rsearch``, but return only the start index at which the substring is found, or 0 if it is not. - + .. function:: contains(haystack, needle) Determine whether the second argument is a substring of the first. - + .. function:: replace(string, pat, r[, n]) Search for the given pattern ``pat``, and replace each occurrence with ``r``. If ``n`` is provided, replace at most ``n`` occurrences. As with search, the second argument may be a single character, a vector or a set of characters, a string, or a regular expression. If ``r`` is a function, each occurrence is replaced with ``r(s)`` where ``s`` is the matched substring. - + .. function:: split(string, [chars]; limit=0, keep=true) Return an array of substrings by splitting the given string on occurrences of the given character delimiters, which may be specified in any of the formats allowed by ``search``'s second argument (i.e. a single character, collection of characters, string, or regular expression). If ``chars`` is omitted, it defaults to the set of all space characters, and ``keep`` is taken to be false. The two keyword arguments are optional: they are are a maximum size for the result and a flag determining whether empty fields should be kept in the result. - + .. function:: rsplit(string, [chars]; limit=0, keep=true) Similar to ``split``, but starting from the end of the string. - + .. function:: strip(string[, chars]) Return ``string`` with any leading and trailing whitespace removed. If ``chars`` (a character, or vector or set of characters) is provided, instead remove characters contained in it. - + .. function:: lstrip(string[, chars]) Return ``string`` with any leading whitespace removed. If ``chars`` remove characters contained in it. - + .. function:: rstrip(string[, chars]) Return ``string`` with any trailing whitespace removed. If provided, instead remove characters contained in it. - + .. function:: startswith(string, prefix | chars) Returns ``true`` if ``string`` starts with ``prefix``. If the second argument is a vector or set of characters, tests whether the first character of ``string`` belongs to that set. - + .. function:: endswith(string, suffix | chars) Returns ``true`` if ``string`` ends with ``suffix``. If the second argument is a vector or set of characters, tests whether the last character of ``string`` belongs to that set. - + .. function:: uppercase(string) Returns ``string`` with all characters converted to uppercase. - + .. function:: lowercase(string) Returns ``string`` with all characters converted to lowercase. - + .. function:: ucfirst(string) Returns ``string`` with the first character converted to uppercase. - + .. function:: lcfirst(string) Returns ``string`` with the first character converted to lowercase. - + .. function:: join(strings, delim[, last]) Join an array of ``strings`` into a single string, inserting the given delimiter between adjacent strings. If ``last`` is given, it will be used instead of ``delim`` between the last two strings. For example, ``join([``apples``, `bananas``, ``pineapples``], ``, `, convertible to strings via `print(io::IOBuffer, x)``. - + .. function:: chop(string) Remove the last character from a string - + .. function:: chomp(string) Remove a trailing newline from a string - + .. function:: ind2chr(string, i) Convert a byte index to a character index - + .. function:: chr2ind(string, i) Convert a character index to a byte index - + .. function:: isvalid(str, i) Tells whether index ``i`` is valid for the given string - + .. function:: nextind(str, i) Get the next valid string index after ``i``. Returns a value greater than ``endof(str)`` at or after the end of the string. - + .. function:: prevind(str, i) Get the previous valid string index before ``i``. Returns a value less than ``1`` at the beginning of the string. - + .. function:: randstring([rng], len=8) Create a random ASCII string of length ``len``, consisting of upper- and lower-case letters and the digits 0-9. The optional Numbers*. - + .. function:: charwidth(c) Gives the number of columns needed to print a character. - + .. function:: strwidth(s) Gives the number of columns needed to print a string. - + .. function:: isalnum(c::Union{Char, AbstractString}) -> Bool Tests whether a character is alphanumeric, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter or Number, i.e. a character whose category code begins with 'L' or - + .. function:: isalpha(c::Union{Char, AbstractString}) -> Bool Tests whether a character is alphabetic, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'. - + .. function:: isascii(c::Union{Char, AbstractString}) -> Bool Tests whether a character belongs to the ASCII character set, or whether this is true for all elements of a string. - + .. function:: iscntrl(c::Union{Char, AbstractString}) -> Bool Tests whether a character is a control character, or whether this is true for all elements of a string. Control characters are the non-printing characters of the Latin-1 subset of Unicode. - + .. function:: isdigit(c::Union{Char, AbstractString}) -> Bool Tests whether a character is a numeric digit (0-9), or whether this is true for all elements of a string. - + .. function:: isgraph(c::Union{Char, AbstractString}) -> Bool Tests whether a character is printable, and not a space, or whether this is true for all elements of a string. Any character that would cause a printer to use ink should be classified with isgraph(c)==true. - + .. function:: islower(c::Union{Char, AbstractString}) -> Bool Tests whether a character is a lowercase letter, or whether this is true for all elements of a string. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase. - + .. function:: isnumber(c::Union{Char, AbstractString}) -> Bool Tests whether a character is numeric, or whether this is true for all elements of a string. A character is classified as numeric if it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'. - + .. function:: isprint(c::Union{Char, AbstractString}) -> Bool Tests whether a character is printable, including spaces, but not a control character. For strings, tests whether this is true for all elements of the string. - + .. function:: ispunct(c::Union{Char, AbstractString}) -> Bool Tests whether a character belongs to the Unicode general category Punctuation, i.e. a character whose category code begins with 'P'. For strings, tests whether this is true for all elements of the string. - + .. function:: isspace(c::Union{Char, AbstractString}) -> Bool Tests whether a character is any whitespace character. Includes ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs. For strings, tests whether this is true for all elements of the string. - + .. function:: isupper(c::Union{Char, AbstractString}) -> Bool Tests whether a character is an uppercase letter, or whether this is true for all elements of a string. A character is classified as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. - + .. function:: isxdigit(c::Union{Char, AbstractString}) -> Bool Tests whether a character is a valid hexadecimal digit, or whether this is true for all elements of a string. - + .. function:: symbol(x...) -> Symbol Create a ``Symbol`` by concatenating the string representations of the arguments together. - + .. function:: escape_string(str::AbstractString) -> AbstractString General escaping of traditional C and Unicode escape sequences. See - + .. function:: unescape_string(s::AbstractString) -> AbstractString General unescaping of traditional C and Unicode escape sequences. Reverse of ``escape_string()``. See also ``print_unescaped()``. - + .. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. - + .. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. - + .. function:: wstring(s) This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - + .. function:: wstring(s) This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - + .. function:: wstring(s) This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - + diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst index e4c89950d799c..e97aa5b87697d 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -15,7 +15,7 @@ binary install, you can run the test suite using ``Base.runtests()``. .. function:: runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) Run the Julia unit tests listed in ``tests``, which can be either a string or an array of strings, using ``numcores`` processors. (not exported) - + .. module:: Base.Test Test Framework @@ -132,22 +132,22 @@ Macros .. function:: @test(ex) Test the expression ``ex`` and calls the current handler to handle the result. - + .. function:: @test_throws(extype, ex) Test that the expression ``ex`` throws an exception of type - + .. function:: @test_approx_eq(a, b) Test two floating point numbers ``a`` and ``b`` for equality taking in account small numerical errors. - + .. function:: @test_approx_eq_eps(a, b, tol) Test two floating point numbers ``a`` and ``b`` for equality taking in account a margin of tolerance given by ``tol``. - + Functions --------- @@ -155,5 +155,5 @@ Functions .. function:: with_handler(f, handler) Run the function ``f`` using the ``handler`` as the handler. - + From a10049918507dfbac446dc74dfec72fd8a349972 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sat, 27 Jun 2015 20:17:30 -0400 Subject: [PATCH 16/27] new doc city: forward-port changes to old helpdb.jl from past week --- base/docs/helpdb.jl | 124 ++++++++++++++++++++++++++++++++++--- doc/stdlib/arrays.rst | 34 +++++++++- doc/stdlib/base.rst | 4 +- doc/stdlib/collections.rst | 26 +++++++- doc/stdlib/file.rst | 2 +- doc/stdlib/io-network.rst | 2 +- doc/stdlib/linalg.rst | 32 ++++++---- doc/stdlib/numbers.rst | 23 ++++++- doc/stdlib/parallel.rst | 16 +++-- doc/stdlib/pkg.rst | 4 +- 10 files changed, 231 insertions(+), 36 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index 08a5d6742b44a..41f35e5867c69 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -37,8 +37,36 @@ AbstractArray `A` in an efficient manner. For array types that have opted into fast linear indexing (like `Array`), this is simply the range `1:length(A)`. For other array types, this returns a specialized Cartesian range to efficiently index into the -array with indices specified for every dimension. Example for a -sparse 2-d array: +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 non-integer indices). + +Example for a sparse 2-d array: + + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 """ eachindex @@ -325,7 +353,8 @@ doc""" sub(A, inds...) Like `getindex()`, but returns a view into the parent array `A` -with the given indices instead of making a copy. Calling +with the given indices instead of making a copy. Calling +`getindex()` or `setindex!()` on the returned `SubArray` computes the indices to the parent array on the fly without checking bounds. """ @@ -360,6 +389,7 @@ doc""" slice(A, inds...) Returns a view of array `A` with the given indices like +`sub()`, but drops all dimensions indexed with scalars. """ slice @@ -2605,6 +2635,7 @@ doc""" Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling + `wait` on the timer object) at a specified interval. """ Timer @@ -3956,7 +3987,31 @@ doc""" 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. +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{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 + + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 + + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 + + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 """ merge @@ -5060,6 +5115,7 @@ doc""" mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) Move the file, link, or directory from *src* to *dest*. +`remove_destination=true` will first remove an existing *dst*. """ mv @@ -6046,7 +6102,8 @@ base64encode doc""" base64decode(string) -Decodes the base64-encoded `string` and returns a +Decodes the base64-encoded `string` and returns a `Vector{UInt8}` of +the decoded bytes. """ base64decode @@ -6742,6 +6799,7 @@ doc""" For any iterable containers `x` and `y` (including arrays of any dimension) of numbers (or any element type for which `dot` is defined), compute the Euclidean dot product (the sum of +`dot(x[i],y[i])`) as if they were vectors. """ vecdot @@ -6801,6 +6859,8 @@ doc""" Compute the Cholesky factorization of a symmetric positive definite matrix `A` and return the matrix `F`. If `LU` is `Val{:U}` +(Upper), `F` is of type `UpperTriangular` and `A = F'*F`. If +`LU` is `Val{:L}` (Lower), `F` is of type `LowerTriangular` and `A = F*F'`. `LU` defaults to `Val{:U}`. """ chol @@ -6809,10 +6869,14 @@ doc""" cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky Compute the Cholesky factorization of a dense symmetric positive +(semi)definite matrix `A` and return either a `Cholesky` if +`pivot==Val{false}` or `CholeskyPivoted` if +`pivot==Val{true}`. `LU` may be `:L` for using the lower part or `:U` for the upper part. The default is to use `:U`. The triangular matrix can be obtained from the factorization `F` with: `F[:L]` and `F[:U]`. The following functions are -available for `Cholesky` objects: `size`, `\`, `inv`, +available for `Cholesky` objects: `size`, `\\`, `inv`, +`det`. For `CholeskyPivoted` there is also defined a `rank`. If `pivot==Val{false}` a `PosDefException` exception is thrown in case the matrix is not positive definite. The argument `tol` determines the tolerance for determining the rank. For negative @@ -6826,7 +6890,7 @@ doc""" Compute the Cholesky factorization of a sparse positive definite matrix `A`. A fill-reducing permutation is used. `F = cholfact(A)` is most frequently used to solve systems of equations -with `F\b`, but also the methods `diag`, `det`, `logdet` +with `F\\b`, but also the methods `diag`, `det`, `logdet` are defined for `F`. You can also extract individual factors from `F`, using `F[:L]`. However, since pivoting is on by default, the factorization is internally represented as `A == @@ -6835,11 +6899,13 @@ without accounting for `P` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact `combined` factors like `PtL = F[:PtL]` (the equivalent of `P'*L`) and `LtP = F[:UP]` (the equivalent of `L'*P`). + Setting optional `shift` keyword argument computes the factorization of `A+shift*I` instead of `A`. If the `perm` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. """ @@ -6848,8 +6914,11 @@ cholfact doc""" cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky +`cholfact!` is the same as `cholfact()`, but saves space by overwriting the input `A`, instead of creating a copy. +`cholfact!` can also reuse the symbolic factorization from a different matrix `F` with the same structure when used as: +`cholfact!(F::CholmodFactor, A)`. """ cholfact! @@ -7445,6 +7514,8 @@ doc""" For any iterable container `A` (including arrays of any dimension) of numbers (or any element type for which `norm` is defined), compute the `p`-norm (defaulting to `p=2`) as if +`A` were a vector of the corresponding length. + For example, if `A` is a matrix and `p=2`, then this is equivalent to the Frobenius norm. """ @@ -7491,6 +7562,16 @@ provide increased accuracy and/or speed. """ logdet +doc""" + logabsdet(M) + +Log of absolute value of determinant of real matrix. Equivalent to +`(log(abs(det(M))), sign(det(M)))`, but may provide increased +accuracy and/or speed. +""" +logdet + + doc""" inv(M) @@ -7789,6 +7870,7 @@ doc""" ger!(alpha, x, y, A) Rank-1 update of the matrix `A` with vectors `x` and `y` as +`alpha*x*y' + A`. """ Base.LinAlg.BLAS.ger! @@ -7796,6 +7878,8 @@ doc""" syr!(uplo, alpha, x, A) Rank-1 update of the symmetric matrix `A` with vector `x` as +`alpha*x*x.' + A`. When `uplo` is 'U' the upper triangle of +`A` is updated ('L' for lower triangle). Returns `A`. """ Base.LinAlg.BLAS.syr! @@ -7823,6 +7907,7 @@ doc""" Methods for complex arrays only. Rank-1 update of the Hermitian matrix `A` with vector `x` as `alpha*x*x' + A`. When +`uplo` is 'U' the upper triangle of `A` is updated ('L' for lower triangle). Returns `A`. """ Base.LinAlg.BLAS.her! @@ -8975,6 +9060,7 @@ doc""" Compute the natural logarithm of `x`. Throws `DomainError` for negative `Real` arguments. Use complex negative arguments to obtain complex results. + There is an experimental variant in the `Base.Math.JuliaLibm` module, which is typically faster and more accurate. """ @@ -10825,6 +10911,7 @@ Create an arbitrary precision integer. `x` may be an `Int` (or anything that can be converted to an `Int`). The usual mathematical operators are defined for this type, and results are promoted to a `BigInt`. + Instances can be constructed from strings via `parse()`, or using the `big` string literal. """ @@ -10837,10 +10924,14 @@ Create an arbitrary precision floating point number. `x` may be an `Integer`, a `Float64` or a `BigInt`. The usual mathematical operators are defined for this type, and results are promoted to a `BigFloat`. + Note that because decimal literals are converted to floating point numbers when parsed, `BigFloat(2.1)` may not yield what you expect. You may instead prefer to initialize constants from strings via `parse()`, or using the `big` string literal. + + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision """ BigFloat @@ -10929,6 +11020,9 @@ and `false` if `x` is not prime with high probability. The false positive rate is about `0.25^reps`. `reps = 25` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + + julia> isprime(big(3)) + true """ isprime @@ -11277,9 +11371,11 @@ the number of cores on the specific host. Keyword arguments: to the worker from the master process. connected to in parallel at a host. Defaults to 10. -to the host's current directory (as found by *pwd()*) +to the host's current directory (as found by `pwd()`) may be. -Environment variables : + +Environment variables: + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, the worker treats it a fatal situation and terminates. This timeout can be controlled via @@ -11295,8 +11391,10 @@ doc""" Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package `ClusterManagers`. + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable +`JULIA_WORKER_TIMEOUT` in the worker process's environment. Relevant only when using TCP/IP as transport. """ addprocs @@ -11790,7 +11888,9 @@ doc""" Free the package `pkg` to be managed by the package manager again. It calls `Pkg.resolve()` to determine optimal package versions after. This is an inverse for both `Pkg.checkout` and + You can also supply an iterable collection of package names, e.g., +`Pkg.free(("Pkg1", "Pkg2"))` to free multiple packages at once. """ Base.Pkg.free @@ -12249,8 +12349,12 @@ doc""" Returns true if the given value is valid for that type. Types currently can be `Char`, `ASCIIString`, `UTF8String`, +`UTF16String`, or `UTF32String` Values for `Char` can be of type `Char` or `UInt32` Values for `ASCIIString` and +`UTF8String` can be of that type, or `Vector{UInt8}` Values for +`UTF16String` can be `UTF16String` or `Vector{UInt16}` Values for `UTF32String` can be `UTF32String`, `Vector{Char}` or +`Vector{UInt32}`. """ isvalid @@ -12732,7 +12836,7 @@ NUL codepoint (32-bit zero), which is not treated as a character in the string (so that it is mostly invisible in Julia); this allows the string to be passed directly to external functions requiring NUL-terminated data. This NUL is appended automatically by the -then you can instead use *UTF32String(A)`* to construct the string +then you can instead use `UTF32String(A)` to construct the string without making a copy of the data and treating the NUL as a terminator rather than as part of the string. """ diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 4c1f8476b7c84..94e4906a2d478 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -29,7 +29,35 @@ Basic functions .. function:: 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 (like ``Array``), this is simply the range ``1:length(A)``. For other array types, this returns a specialized Cartesian range to efficiently index into the array with indices specified for every dimension. Example for a sparse 2-d array: + 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 (like ``Array``), this is simply the range ``1: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 non-integer indices). + + Example for a sparse 2-d array: + + :: + + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 If you supply more than one ``AbstractArray`` argument, ``eachindex`` @@ -220,7 +248,7 @@ Indexing, Assignment, and Concatenation .. function:: sub(A, inds...) - Like ``getindex()``, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling computes the indices to the parent array on the fly without checking bounds. + Like ``getindex()``, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling ``getindex()`` or ``setindex!()`` on the returned ``SubArray`` computes the indices to the parent array on the fly without checking bounds. .. function:: parent(A) @@ -240,7 +268,7 @@ Indexing, Assignment, and Concatenation .. function:: slice(A, inds...) - Returns a view of array ``A`` with the given indices like + Returns a view of array ``A`` with the given indices like ``sub()``, but drops all dimensions indexed with scalars. .. function:: setindex!(collection, value, key...) diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 864af07dea3b9..29ba74d980638 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -862,12 +862,12 @@ Events .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling + Create a timer that wakes up tasks waiting for it (by calling ``wait`` on the timer object) at a specified interval. .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling + Create a timer that wakes up tasks waiting for it (by calling ``wait`` on the timer object) at a specified interval. Reflection diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index 3d41c2eb7cd09..15a9f3ac9f027 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -591,7 +591,31 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: merge(collection, others...) - 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. + 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{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 + + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 + + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 + + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 .. function:: merge!(collection, others...) diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index 3e458266cfa6f..0c41fac41bdcc 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -107,7 +107,7 @@ .. function:: mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - Move the file, link, or directory from *src* to *dest*. + Move the file, link, or directory from *src* to *dest*. ``remove_destination=true`` will first remove an existing *dst*. .. function:: rm(path::AbstractString; recursive=false) diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index d1970287b469a..25dbbbccc98dd 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -429,7 +429,7 @@ Text I/O .. function:: base64decode(string) - Decodes the base64-encoded ``string`` and returns a + Decodes the base64-encoded ``string`` and returns a ``Vector{UInt8}`` of the decoded bytes. Multimedia I/O diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 9d9e741358acd..d7c9a1e29cb4a 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -32,7 +32,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: vecdot(x, y) - For any iterable containers ``x`` and ``y`` (including arrays of any dimension) of numbers (or any element type for which ``dot`` is defined), compute the Euclidean dot product (the sum of + For any iterable containers ``x`` and ``y`` (including arrays of any dimension) of numbers (or any element type for which ``dot`` is defined), compute the Euclidean dot product (the sum of ``dot(x[i],y[i])``) as if they were vectors. .. function:: cross(x, y) @@ -69,22 +69,30 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: chol(A[, LU]) -> F - Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. + Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` (Upper), ``F`` is of type ``UpperTriangular`` and ``A = F'*F``. If ``LU`` is ``Val{:L}`` (Lower), ``F`` is of type ``LowerTriangular`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). + + Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). + + Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - overwriting the input ``A``, instead of creating a copy. different matrix ``F`` with the same structure when used as: + ``cholfact!`` is the same as ``cholfact()``, but saves space by overwriting the input ``A``, instead of creating a copy. ``cholfact!`` can also reuse the symbolic factorization from a different matrix ``F`` with the same structure when used as: ``cholfact!(F::CholmodFactor, A)``. .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor @@ -401,7 +409,9 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: vecnorm(A[, p]) - For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``-norm (defaulting to ``p=2``) as if For example, if ``A`` is a matrix and ``p=2``, then this is equivalent to the Frobenius norm. + For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``-norm (defaulting to ``p=2``) as if ``A`` were a vector of the corresponding length. + + For example, if ``A`` is a matrix and ``p=2``, then this is equivalent to the Frobenius norm. .. function:: cond(M[, p]) @@ -424,9 +434,9 @@ Linear algebra functions in Julia are largely implemented by calling functions f Matrix determinant -.. function:: logdet(M) +.. function:: logabsdet(M) - Log of matrix determinant. Equivalent to ``log(det(M))``, but may provide increased accuracy and/or speed. + Log of absolute value of determinant of real matrix. Equivalent to ``(log(abs(det(M))), sign(det(M)))``, but may provide increased accuracy and/or speed. .. function:: logabsdet(M) @@ -624,12 +634,12 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: ger!(alpha, x, y, A) - Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as + Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as ``alpha*x*y' + A``. .. function:: syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix ``A`` with vector ``x`` as + Rank-1 update of the symmetric matrix ``A`` with vector ``x`` as ``alpha*x*x.' + A``. When ``uplo`` is 'U' the upper triangle of ``A`` is updated ('L' for lower triangle). Returns ``A``. .. function:: syrk!(uplo, trans, alpha, A, beta, C) @@ -644,7 +654,7 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When lower triangle). Returns ``A``. + Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When ``uplo`` is 'U' the upper triangle of ``A`` is updated ('L' for lower triangle). Returns ``A``. .. function:: herk!(uplo, trans, alpha, A, beta, C) diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 9c6022f86a865..5a0d031f7a9cf 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -249,12 +249,21 @@ General Number Functions and Constants .. function:: BigInt(x) - Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``). The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. Instances can be constructed from strings via ``parse()``, or using the ``big`` string literal. + Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``). The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. + + Instances can be constructed from strings via ``parse()``, or using the ``big`` string literal. .. function:: BigFloat(x) - Create an arbitrary precision floating point number. ``x`` may be an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results are promoted to a ``BigFloat``. Note that because decimal literals are converted to floating point numbers when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead prefer to initialize constants from strings via ``parse()``, or using the ``big`` string literal. + Create an arbitrary precision floating point number. ``x`` may be an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results are promoted to a ``BigFloat``. + + Note that because decimal literals are converted to floating point numbers when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead prefer to initialize constants from strings via ``parse()``, or using the ``big`` string literal. + + :: + + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision .. function:: get_rounding(T) @@ -309,11 +318,21 @@ Integers Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + :: + + julia> isprime(big(3)) + true + .. function:: isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + :: + + julia> isprime(big(3)) + true + .. function:: primes(n) diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 0b43168793c9c..ce12c1929a650 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -112,22 +112,30 @@ General Parallel Computing Support .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable Relevant only when using TCP/IP as transport. + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. .. function:: nprocs() diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index fd766cb97a799..bc606244aa15c 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -99,7 +99,9 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, .. function:: free(pkg) - Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and You can also supply an iterable collection of package names, e.g., once. + Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and + + You can also supply an iterable collection of package names, e.g., ``Pkg.free(("Pkg1", "Pkg2"))`` to free multiple packages at once. .. function:: build(pkgs...) From 93a2a30372362424bb963e6067b54aaeab3d704a Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sat, 27 Jun 2015 21:21:42 -0400 Subject: [PATCH 17/27] wip: fixing missing/out-of-date stuff in new helpdb.jl --- base/docs/helpdb.jl | 42 ++++++++++++++++++++++---- doc/stdlib/arrays.rst | 70 ++++++++++++++++++++++++++----------------- 2 files changed, 79 insertions(+), 33 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index 41f35e5867c69..a236f52785035 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -4,7 +4,6 @@ doc""" Returns the number of dimensions of A """ ndims - doc""" size(A[, dim...]) @@ -12,6 +11,14 @@ 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 = rand(2,3,4); + + julia> size(A,2) + 3 + + julia> size(A,3,2) + (4,3) """ size @@ -122,7 +129,10 @@ doc""" ind2sub(dims, index) -> subscripts Returns a tuple of subscripts into an array with dimensions -the indices of the maximum element +`dims`, corresponding to the linear index `index`. + +**Example** `i, j, ... = ind2sub(size(A), indmax(A))` provides +the indices of the maximum element. """ ind2sub @@ -145,6 +155,7 @@ sub2ind doc""" Array(dims) +`Array{T}(dims)` constructs an uninitialized dense array with element type `T`. `dims` may be a tuple or a series of integer arguments. The syntax `Array(T, dims)` is also available, but deprecated. @@ -156,6 +167,7 @@ doc""" Construct a 1-d array of the specified type. This is usually called with the syntax `Type[]`. Element values can be specified using +`Type[a,b,c,...]`. """ getindex @@ -163,6 +175,7 @@ doc""" cell(dims) Construct an uninitialized cell array (heterogeneous array). +`dims` can be either a tuple or a series of integer arguments. """ cell @@ -216,7 +229,9 @@ doc""" fill(x, dims) Create an array filled with the value `x`. For example, +`fill(1.0, (10,10))` returns a 10x10 array of floats, with each element initialized to 1.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 evaluating `Foo()` once. @@ -229,6 +244,7 @@ doc""" Fill array `A` with the value `x`. If `x` is an object reference, all elements will refer to the same object. `fill!(A, Foo())` will return `A` filled with the result of evaluating +`Foo()` once. """ fill! @@ -248,6 +264,7 @@ Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The `dims` argument may be a tuple or a series of integer arguments. For some special +`AbstractArray` objects which are not real containers (like ranges), this function returns a standard `Array` to allow operating on elements. """ @@ -257,6 +274,7 @@ doc""" reinterpret(type, A) Change the type-interpretation of a block of memory. For example, +`reinterpret(Float32, UInt32(7))` interprets the 4 bytes corresponding to `UInt32(7)` as a `Float32`. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. @@ -280,15 +298,14 @@ eye doc""" eye(A) -Constructs an identity matrix of the same dimensions and type as +Constructs an identity matrix of the same dimensions and type as `A`. """ eye doc""" linspace(start, stop, n=100) -Construct a range of `n` linearly spaced elements from `start` -to `stop`. +Construct a range of `n` linearly spaced elements from `start` to `stop`. """ linspace @@ -296,6 +313,7 @@ doc""" logspace(start, stop, n=50) Construct a vector of `n` logarithmically spaced numbers from +`10^start` to `10^stop`. """ logspace @@ -304,6 +322,7 @@ doc""" Broadcasts the arrays `As` to a common size by expanding singleton dimensions, and returns an array of the results +`f(as...)` for each position. """ broadcast @@ -314,6 +333,7 @@ Like `broadcast`, but store the result of `broadcast(f, As...)` in the `dest` array. Note that `dest` is only used to store the result, and does not supply arguments to `f` unless it is also listed in the `As`, as in `broadcast!(f, A, A, B)` to perform +`A[:] = broadcast(f, A, B)`. """ broadcast! @@ -329,6 +349,7 @@ doc""" broadcast_function(f) Returns a function `broadcast_f` such that +`broadcast_function(f)(As...) === broadcast(f, As...)`. Most useful in the form `const broadcast_f = broadcast_function(f)`. """ broadcast_function @@ -429,6 +450,7 @@ output array along that dimension. For dimensions in `dims`, the size of the output array is the sum of the sizes of the input arrays along that dimension. If `dims` is a single number, the different arrays are tightly stacked along that dimension. If +`dims` is an iterable containing several dimensions, this allows to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, @@ -457,6 +479,8 @@ doc""" 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. For example, +`[a b;c d e]` calls `hvcat((2,3),a,b,c,d,e)`. + If the first argument is a single integer `n`, then all block rows are assumed to have `n` block columns. """ @@ -529,6 +553,7 @@ doc""" findfirst(predicate, A) Return the index of the first element of `A` for which +`predicate` returns true. """ findfirst @@ -536,6 +561,7 @@ doc""" findlast(A) Return the index of the last non-zero value in `A` (determined by +`A[i]!=0`). """ findlast @@ -550,6 +576,7 @@ doc""" findlast(predicate, A) Return the index of the last element of `A` for which +`predicate` returns true. """ findlast @@ -564,6 +591,7 @@ doc""" findnext(predicate, A, i) Find the next index >= `i` of an element of `A` for which +`0` if not found. """ findnext @@ -571,6 +599,7 @@ doc""" findnext(A, v, i) Find the next index >= `i` of an element of `A` equal to `v` +`predicate` returns true, or `0` if not found. """ findnext @@ -586,6 +615,7 @@ doc""" findprev(predicate, A, i) Find the previous index <= `i` of an element of `A` for which +`predicate` returns true, or `0` if not found. """ findprev @@ -593,6 +623,7 @@ doc""" findprev(A, v, i) Find the previous index <= `i` of an element of `A` equal to +`v` (using `==`), or `0` if not found. """ findprev @@ -620,6 +651,7 @@ doc""" Permute the dimensions of array `src` and store the result in the array `dest`. `perm` is a vector specifying a permutation of length `ndims(src)`. The preallocated array `dest` should have +`size(dest) == size(src)[perm]` and is completely overwritten. No in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. """ diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 94e4906a2d478..7ed48ccccecf2 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -16,6 +16,16 @@ Basic functions 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 = rand(2,3,4); + + julia> size(A,2) + 3 + + julia> size(A,3,2) + (4,3) + .. function:: iseltype(A, T) @@ -115,7 +125,7 @@ Constructors .. function:: Array(dims) - element type ``T``. ``dims`` may be a tuple or a series of integer arguments. The syntax ``Array(T, dims)`` is also available, but deprecated. + ``Array{T}(dims)`` constructs an uninitialized dense array with element type ``T``. ``dims`` may be a tuple or a series of integer arguments. The syntax ``Array(T, dims)`` is also available, but deprecated. .. function:: getindex(collection, key...) @@ -125,7 +135,7 @@ Constructors .. function:: cell(dims) - Construct an uninitialized cell array (heterogeneous array). + Construct an uninitialized cell array (heterogeneous array). ``dims`` can be either a tuple or a series of integer arguments. .. function:: zeros(A) @@ -160,12 +170,14 @@ Constructors .. function:: fill(x, dims) - Create an array filled with the value ``x``. For example, element initialized to 1.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 evaluating ``Foo()`` once. + Create an array filled with the value ``x``. For example, ``fill(1.0, (10,10))`` returns a 10x10 array of floats, with each element initialized to 1.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 evaluating ``Foo()`` once. .. function:: fill!(A, x) - Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating + Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating ``Foo()`` once. .. function:: reshape(A, dims) @@ -175,27 +187,27 @@ Constructors .. function:: similar(array, element_type, dims) - Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ranges), this function returns a standard ``Array`` to allow operating on elements. + Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ``AbstractArray`` objects which are not real containers (like ranges), this function returns a standard ``Array`` to allow operating on elements. .. function:: reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. + Change the type-interpretation of a block of memory. For example, ``reinterpret(Float32, UInt32(7))`` interprets the 4 bytes corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as + Constructs an identity matrix of the same dimensions and type as ``A``. .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as + Constructs an identity matrix of the same dimensions and type as ``A``. .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as + Constructs an identity matrix of the same dimensions and type as ``A``. .. function:: linspace(start, stop, n=100) @@ -205,7 +217,7 @@ Constructors .. function:: logspace(start, stop, n=50) - Construct a vector of ``n`` logarithmically spaced numbers from + Construct a vector of ``n`` logarithmically spaced numbers from ``10^start`` to ``10^stop``. Mathematical operators and functions @@ -215,12 +227,12 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) - Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results + Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results ``f(as...)`` for each position. .. function:: broadcast!(f, dest, As...) - Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. Note that ``dest`` is only used to store the result, and does not supply arguments to ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform + Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. Note that ``dest`` is only used to store the result, and does not supply arguments to ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform ``A[:] = broadcast(f, A, B)``. .. function:: bitbroadcast(f, As...) @@ -230,7 +242,7 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast_function(f) - Returns a function ``broadcast_f`` such that useful in the form ``const broadcast_f = broadcast_function(f)``. + Returns a function ``broadcast_f`` such that ``broadcast_function(f)(As...) === broadcast(f, As...)``. Most useful in the form ``const broadcast_f = broadcast_function(f)``. .. function:: broadcast!_function(f) @@ -288,7 +300,7 @@ Indexing, Assignment, and Concatenation .. function:: cat(dims, A...) - Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. + Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If ``dims`` is an iterable containing several dimensions, this allows to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. .. function:: vcat(A...) @@ -303,7 +315,9 @@ Indexing, Assignment, and Concatenation .. function:: 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. For example, If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. + 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. For example, ``[a b;c d e]`` calls ``hvcat((2,3),a,b,c,d,e)``. + + If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. .. function:: flipdim(A, d) @@ -338,62 +352,62 @@ Indexing, Assignment, and Concatenation .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which + Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which + Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which + Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which + Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which + Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which + Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` ``predicate`` returns true, or ``0`` if not found. .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` ``predicate`` returns true, or ``0`` if not found. .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` ``predicate`` returns true, or ``0`` if not found. .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. .. function:: permutedims(A, perm) @@ -408,7 +422,7 @@ Indexing, Assignment, and Concatenation .. function:: permutedims!(dest, src, perm) - Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have ``size(dest) == size(src)[perm]`` and is completely overwritten. No in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. .. function:: squeeze(A, dims) From 4340acae44b0d948f80bcda426150e3c33b9b980 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sat, 27 Jun 2015 21:25:07 -0400 Subject: [PATCH 18/27] temporarily add back an up-to-date doc/helpdb.jl from master --- doc/helpdb.jl | 13263 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 13263 insertions(+) create mode 100644 doc/helpdb.jl diff --git a/doc/helpdb.jl b/doc/helpdb.jl new file mode 100644 index 0000000000000..da10fee2d15de --- /dev/null +++ b/doc/helpdb.jl @@ -0,0 +1,13263 @@ +# automatically generated from files in doc/stdlib/ -- do not edit here + +Any[ + +("Base","ndims","ndims(A) -> Integer + + Returns the number of dimensions of A + +"), + +("Base","size","size(A[, 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 = rand(2,3,4); + + julia> size(A, 2) + 3 + + julia> size(A,3,2) + (4,3) + +"), + +("Base","iseltype","iseltype(A, T) + + Tests whether A or its elements are of type T + +"), + +("Base","length","length(A) -> Integer + + Returns the number of elements in A + +"), + +("Base","eachindex","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 (like \"Array\"), this is + simply the range \"1: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 non-integer indices). + + Example for a sparse 2-d array: + + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 + +"), + +("Base","Base","Base.linearindexing(A) + + \"linearindexing\" defines how an AbstractArray most efficiently + accesses its elements. If \"Base.linearindexing(A)\" returns + \"Base.LinearFast()\", this means that linear indexing with only + one index is an efficient operation. If it instead returns + \"Base.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 + traits-based 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 define \"linearindexing\" in the + type-domain: + + Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() + +"), + +("Base","countnz","countnz(A) + + Counts the number of nonzero values in array A (dense or sparse). + Note that this is not a constant-time operation. For sparse + matrices, one should usually use \"nnz\", which returns the number + of stored values. + +"), + +("Base","conj!","conj!(A) + + Convert an array to its complex conjugate in-place + +"), + +("Base","stride","stride(A, k) + + Returns the distance in memory (in number of elements) between + adjacent elements in dimension k + +"), + +("Base","strides","strides(A) + + Returns a tuple of the memory strides in each dimension + +"), + +("Base","ind2sub","ind2sub(dims, index) -> subscripts + + Returns a tuple of subscripts into an array with dimensions + \"dims\", corresponding to the linear index \"index\" + + **Example** \"i, j, ... = ind2sub(size(A), indmax(A))\" provides + the indices of the maximum element + +"), + +("Base","ind2sub","ind2sub(a, index) -> subscripts + + Returns a tuple of subscripts into array \"a\" corresponding to the + linear index \"index\" + +"), + +("Base","sub2ind","sub2ind(dims, i, j, k...) -> index + + The inverse of \"ind2sub\", returns the linear index corresponding + to the provided subscripts + +"), + +("Base","Array","Array(dims) + + \"Array{T}(dims)\" constructs an uninitialized dense array with + element type \"T\". \"dims\" may be a tuple or a series of integer + arguments. The syntax \"Array(T, dims)\" is also available, but + deprecated. + +"), + +("Base","getindex","getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called + with the syntax \"Type[]\". Element values can be specified using + \"Type[a,b,c,...]\". + +"), + +("Base","cell","cell(dims) + + Construct an uninitialized cell array (heterogeneous array). + \"dims\" can be either a tuple or a series of integer arguments. + +"), + +("Base","zeros","zeros(type, dims) + + Create an array of all zeros of specified type. The type defaults + to Float64 if not specified. + +"), + +("Base","zeros","zeros(A) + + Create an array of all zeros with the same element type and shape + as A. + +"), + +("Base","ones","ones(type, dims) + + Create an array of all ones of specified type. The type defaults to + Float64 if not specified. + +"), + +("Base","ones","ones(A) + + Create an array of all ones with the same element type and shape as + A. + +"), + +("Base","trues","trues(dims) + + Create a \"BitArray\" with all values set to true + +"), + +("Base","falses","falses(dims) + + Create a \"BitArray\" with all values set to false + +"), + +("Base","fill","fill(x, dims) + + Create an array filled with the value \"x\". For example, + \"fill(1.0, (10,10))\" returns a 10x10 array of floats, with each + element initialized to 1.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 evaluating \"Foo()\" once. + +"), + +("Base","fill!","fill!(A, x) + + Fill array \"A\" with the value \"x\". If \"x\" is an object + reference, all elements will refer to the same object. \"fill!(A, + Foo())\" will return \"A\" filled with the result of evaluating + \"Foo()\" once. + +"), + +("Base","reshape","reshape(A, dims) + + Create an array with the same data as the given array, but with + different dimensions. An implementation for a particular type of + array may choose whether the data is copied or shared. + +"), + +("Base","similar","similar(array, element_type, dims) + + Create an uninitialized array of the same type as the given array, + but with the specified element type and dimensions. The second and + third arguments are both optional. The \"dims\" argument may be a + tuple or a series of integer arguments. For some special + \"AbstractArray\" objects which are not real containers (like + ranges), this function returns a standard \"Array\" to allow + operating on elements. + +"), + +("Base","reinterpret","reinterpret(type, A) + + Change the type-interpretation of a block of memory. For example, + \"reinterpret(Float32, UInt32(7))\" interprets the 4 bytes + corresponding to \"UInt32(7)\" as a \"Float32\". For arrays, this + constructs an array with the same binary data as the given array, + but with the specified element type. + +"), + +("Base","eye","eye(n) + + n-by-n identity matrix + +"), + +("Base","eye","eye(m, n) + + m-by-n identity matrix + +"), + +("Base","eye","eye(A) + + Constructs an identity matrix of the same dimensions and type as + \"A\". + +"), + +("Base","linspace","linspace(start, stop, n=100) + + Construct a range of \"n\" linearly spaced elements from \"start\" + to \"stop\". + +"), + +("Base","logspace","logspace(start, stop, n=50) + + Construct a vector of \"n\" logarithmically spaced numbers from + \"10^start\" to \"10^stop\". + +"), + +("Base","broadcast","broadcast(f, As...) + + Broadcasts the arrays \"As\" to a common size by expanding + singleton dimensions, and returns an array of the results + \"f(as...)\" for each position. + +"), + +("Base","broadcast!","broadcast!(f, dest, As...) + + Like \"broadcast\", but store the result of \"broadcast(f, As...)\" + in the \"dest\" array. Note that \"dest\" is only used to store the + result, and does not supply arguments to \"f\" unless it is also + listed in the \"As\", as in \"broadcast!(f, A, A, B)\" to perform + \"A[:] = broadcast(f, A, B)\". + +"), + +("Base","bitbroadcast","bitbroadcast(f, As...) + + Like \"broadcast\", but allocates a \"BitArray\" to store the + result, rather then an \"Array\". + +"), + +("Base","broadcast_function","broadcast_function(f) + + Returns a function \"broadcast_f\" such that + \"broadcast_function(f)(As...) === broadcast(f, As...)\". Most + useful in the form \"const broadcast_f = broadcast_function(f)\". + +"), + +("Base","broadcast!_function","broadcast!_function(f) + + Like \"broadcast_function\", but for \"broadcast!\". + +"), + +("Base","getindex","getindex(A, inds...) + + Returns a subset of array \"A\" as specified by \"inds\", where + each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See + the manual section on *array indexing* for details. + +"), + +("Base","sub","sub(A, inds...) + + Like \"getindex()\", but returns a view into the parent array \"A\" + with the given indices instead of making a copy. Calling + \"getindex()\" or \"setindex!()\" on the returned \"SubArray\" + computes the indices to the parent array on the fly without + checking bounds. + +"), + +("Base","parent","parent(A) + + Returns the \"parent array\" of an array view type (e.g., + SubArray), or the array itself if it is not a view + +"), + +("Base","parentindexes","parentindexes(A) + + From an array view \"A\", returns the corresponding indexes in the + parent + +"), + +("Base","slicedim","slicedim(A, d, i) + + Return all the data of \"A\" where the index for dimension \"d\" + equals \"i\". Equivalent to \"A[:,:,...,i,:,:,...]\" where \"i\" is + in position \"d\". + +"), + +("Base","slice","slice(A, inds...) + + Returns a view of array \"A\" with the given indices like + \"sub()\", but drops all dimensions indexed with scalars. + +"), + +("Base","setindex!","setindex!(A, X, inds...) + + Store values from array \"X\" within some subset of \"A\" as + specified by \"inds\". + +"), + +("Base","broadcast_getindex","broadcast_getindex(A, inds...) + + Broadcasts the \"inds\" arrays to a common size like \"broadcast\", + and returns an array of the results \"A[ks...]\", where \"ks\" goes + over the positions in the broadcast. + +"), + +("Base","broadcast_setindex!","broadcast_setindex!(A, X, inds...) + + Broadcasts the \"X\" and \"inds\" arrays to a common size and + stores the value from each position in \"X\" at the indices given + by the same positions in \"inds\". + +"), + +("Base","cat","cat(dims, A...) + + Concatenate the input arrays along the specified dimensions in the + iterable \"dims\". For dimensions not in \"dims\", all input arrays + should have the same size, which will also be the size of the + output array along that dimension. For dimensions in \"dims\", the + size of the output array is the sum of the sizes of the input + arrays along that dimension. If \"dims\" is a single number, the + different arrays are tightly stacked along that dimension. If + \"dims\" is an iterable containing several dimensions, this allows + to construct block diagonal matrices and their higher-dimensional + 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 with *matrices[1]*, *matrices[2]*, ... as diagonal + blocks and matching zero blocks away from the diagonal. + +"), + +("Base","vcat","vcat(A...) + + Concatenate along dimension 1 + +"), + +("Base","hcat","hcat(A...) + + Concatenate along dimension 2 + +"), + +("Base","hvcat","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. For example, + \"[a b;c d e]\" calls \"hvcat((2,3),a,b,c,d,e)\". + + If the first argument is a single integer \"n\", then all block + rows are assumed to have \"n\" block columns. + +"), + +("Base","flipdim","flipdim(A, d) + + Reverse \"A\" in dimension \"d\". + +"), + +("Base","circshift","circshift(A, shifts) + + Circularly shift the data in an array. The second argument is a + vector giving the amount to shift in each dimension. + +"), + +("Base","find","find(A) + + Return a vector of the linear indexes of the non-zeros in \"A\" + (determined by \"A[i]!=0\"). A common use of this is to convert a + boolean array to an array of indexes of the \"true\" elements. + +"), + +("Base","find","find(f, A) + + Return a vector of the linear indexes of \"A\" where \"f\" returns + true. + +"), + +("Base","findn","findn(A) + + Return a vector of indexes for each dimension giving the locations + of the non-zeros in \"A\" (determined by \"A[i]!=0\"). + +"), + +("Base","findnz","findnz(A) + + Return a tuple \"(I, J, V)\" where \"I\" and \"J\" are the row and + column indexes of the non-zero values in matrix \"A\", and \"V\" is + a vector of the non-zero values. + +"), + +("Base","findfirst","findfirst(A) + + Return the index of the first non-zero value in \"A\" (determined + by \"A[i]!=0\"). + +"), + +("Base","findfirst","findfirst(A, v) + + Return the index of the first element equal to \"v\" in \"A\". + +"), + +("Base","findfirst","findfirst(predicate, A) + + Return the index of the first element of \"A\" for which + \"predicate\" returns true. + +"), + +("Base","findlast","findlast(A) + + Return the index of the last non-zero value in \"A\" (determined by + \"A[i]!=0\"). + +"), + +("Base","findlast","findlast(A, v) + + Return the index of the last element equal to \"v\" in \"A\". + +"), + +("Base","findlast","findlast(predicate, A) + + Return the index of the last element of \"A\" for which + \"predicate\" returns true. + +"), + +("Base","findnext","findnext(A, i) + + Find the next index >= \"i\" of a non-zero element of \"A\", or + \"0\" if not found. + +"), + +("Base","findnext","findnext(predicate, A, i) + + Find the next index >= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + +"), + +("Base","findnext","findnext(A, v, i) + + Find the next index >= \"i\" of an element of \"A\" equal to \"v\" + (using \"==\"), or \"0\" if not found. + +"), + +("Base","findprev","findprev(A, i) + + Find the previous index <= \"i\" of a non-zero element of \"A\", or + 0 if not found. + +"), + +("Base","findprev","findprev(predicate, A, i) + + Find the previous index <= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + +"), + +("Base","findprev","findprev(A, v, i) + + Find the previous index <= \"i\" of an element of \"A\" equal to + \"v\" (using \"==\"), or \"0\" if not found. + +"), + +("Base","permutedims","permutedims(A, perm) + + Permute the dimensions of array \"A\". \"perm\" is a vector + specifying a permutation of length \"ndims(A)\". This is a + generalization of transpose for multi-dimensional arrays. Transpose + is equivalent to \"permutedims(A, [2,1])\". + +"), + +("Base","ipermutedims","ipermutedims(A, perm) + + Like \"permutedims()\", except the inverse of the given permutation + is applied. + +"), + +("Base","permutedims!","permutedims!(dest, src, perm) + + Permute the dimensions of array \"src\" and store the result in the + array \"dest\". \"perm\" is a vector specifying a permutation of + length \"ndims(src)\". The preallocated array \"dest\" should have + \"size(dest) == size(src)[perm]\" and is completely overwritten. No + in-place permutation is supported and unexpected results will + happen if *src* and *dest* have overlapping memory regions. + +"), + +("Base","squeeze","squeeze(A, dims) + + Remove the dimensions specified by \"dims\" from array \"A\". + Elements of \"dims\" must be unique and within the range + \"1:ndims(A)\". + +"), + +("Base","vec","vec(Array) -> Vector + + Vectorize an array using column-major convention. + +"), + +("Base","promote_shape","promote_shape(s1, s2) + + Check two array shapes for compatibility, allowing trailing + singleton dimensions, and return whichever shape has more + dimensions. + +"), + +("Base","checkbounds","checkbounds(array, indexes...) + + Throw an error if the specified indexes are not in bounds for the + given array. + +"), + +("Base","randsubseq","randsubseq(A, p) -> Vector + + Return a vector consisting of a random subsequence of the given + array \"A\", where each element of \"A\" is included (in order) + with independent probability \"p\". (Complexity is linear in + \"p*length(A)\", so this function is efficient even if \"p\" is + small and \"A\" is large.) Technically, this process is known as + \"Bernoulli sampling\" of \"A\". + +"), + +("Base","randsubseq!","randsubseq!(S, A, p) + + Like \"randsubseq\", but the results are stored in \"S\" (which is + resized as needed). + +"), + +("Base","cumprod","cumprod(A[, dim]) + + Cumulative product along a dimension \"dim\" (defaults to 1). See + also \"cumprod!()\" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). + +"), + +("Base","cumprod!","cumprod!(B, A[, dim]) + + Cumulative product of \"A\" along a dimension, storing the result + in \"B\". The dimension defaults to 1. + +"), + +("Base","cumsum","cumsum(A[, dim]) + + Cumulative sum along a dimension \"dim\" (defaults to 1). See also + \"cumsum!()\" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). + +"), + +("Base","cumsum!","cumsum!(B, A[, dim]) + + Cumulative sum of \"A\" along a dimension, storing the result in + \"B\". The dimension defaults to 1. + +"), + +("Base","cumsum_kbn","cumsum_kbn(A[, dim]) + + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier + compensated summation algorithm for additional accuracy. The + dimension defaults to 1. + +"), + +("Base","cummin","cummin(A[, dim]) + + Cumulative minimum along a dimension. The dimension defaults to 1. + +"), + +("Base","cummax","cummax(A[, dim]) + + Cumulative maximum along a dimension. The dimension defaults to 1. + +"), + +("Base","diff","diff(A[, dim]) + + Finite difference operator of matrix or vector. + +"), + +("Base","gradient","gradient(F[, h]) + + Compute differences along vector \"F\", using \"h\" as the spacing + between points. The default spacing is one. + +"), + +("Base","rot180","rot180(A) + + Rotate matrix \"A\" 180 degrees. + +"), + +("Base","rot180","rot180(A, k) + + Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. + If \"k\" is even, this is equivalent to a \"copy\". + +"), + +("Base","rotl90","rotl90(A) + + Rotate matrix \"A\" left 90 degrees. + +"), + +("Base","rotl90","rotl90(A, k) + + Rotate matrix \"A\" left 90 degrees an integer \"k\" number of + times. If \"k\" is zero or a multiple of four, this is equivalent + to a \"copy\". + +"), + +("Base","rotr90","rotr90(A) + + Rotate matrix \"A\" right 90 degrees. + +"), + +("Base","rotr90","rotr90(A, k) + + Rotate matrix \"A\" right 90 degrees an integer \"k\" number of + times. If \"k\" is zero or a multiple of four, this is equivalent + to a \"copy\". + +"), + +("Base","reducedim","reducedim(f, A, dims[, initial]) + + Reduce 2-argument function \"f\" along dimensions of \"A\". + \"dims\" is a vector specifying the dimensions to reduce, and + \"initial\" is the initial value to use in the reductions. For *+*, + ***, *max* and *min* the *initial* argument is optional. + + The associativity of the reduction is implementation-dependent; if + you need a particular associativity, e.g. left-to-right, you should + write your own loop. See documentation for \"reduce\". + +"), + +("Base","mapreducedim","mapreducedim(f, op, A, dims[, initial]) + + Evaluates to the same as *reducedim(op, map(f, A), dims, + f(initial))*, but is generally faster because the intermediate + array is avoided. + +"), + +("Base","mapslices","mapslices(f, A, dims) + + Transform the given dimensions of array \"A\" using function \"f\". + \"f\" is called on each slice of \"A\" of the form + \"A[...,:,...,:,...]\". \"dims\" is an integer vector specifying + where the colons go in this expression. The results are + concatenated along the remaining dimensions. For example, if + \"dims\" is \"[1,2]\" and A is 4-dimensional, \"f\" is called on + \"A[:,:,i,j]\" for all \"i\" and \"j\". + +"), + +("Base","sum_kbn","sum_kbn(A) + + Returns the sum of all array elements, using the Kahan-Babuska- + Neumaier compensated summation algorithm for additional accuracy. + +"), + +("Base","cartesianmap","cartesianmap(f, dims) + + Given a \"dims\" tuple of integers \"(m, n, ...)\", call \"f\" on + all combinations of integers in the ranges \"1:m\", \"1:n\", etc. + + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 + +"), + +("Base","nthperm","nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + +"), + +("Base","nthperm","nthperm(p) + + Return the \"k\" that generated permutation \"p\". Note that + \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". + +"), + +("Base","nthperm!","nthperm!(v, k) + + In-place version of \"nthperm()\". + +"), + +("Base","randperm","randperm([rng], n) + + Construct a random permutation of length \"n\". The optional + \"rng\" argument specifies a random number generator, see *Random + Numbers*. + +"), + +("Base","invperm","invperm(v) + + Return the inverse permutation of v. + +"), + +("Base","isperm","isperm(v) -> Bool + + Returns true if v is a valid permutation. + +"), + +("Base","permute!","permute!(v, p) + + Permute vector \"v\" in-place, according to permutation \"p\". No + checking is done to verify that \"p\" is a permutation. + + To return a new permutation, use \"v[p]\". Note that this is + generally faster than \"permute!(v,p)\" for large vectors. + +"), + +("Base","ipermute!","ipermute!(v, p) + + Like permute!, but the inverse of the given permutation is applied. + +"), + +("Base","randcycle","randcycle([rng], n) + + Construct a random cyclic permutation of length \"n\". The optional + \"rng\" argument specifies a random number generator, see *Random + Numbers*. + +"), + +("Base","shuffle","shuffle([rng], v) + + Return a randomly permuted copy of \"v\". The optional \"rng\" + argument specifies a random number generator, see *Random Numbers*. + +"), + +("Base","shuffle!","shuffle!([rng], v) + + In-place version of \"shuffle()\". + +"), + +("Base","reverse","reverse(v[, start=1[, stop=length(v)]]) + + Return a copy of \"v\" reversed from start to stop. + +"), + +("Base","reverseind","reverseind(v, i) + + Given an index \"i\" in \"reverse(v)\", return the corresponding + index in \"v\" so that \"v[reverseind(v,i)] == reverse(v)[i]\". + (This can be nontrivial in the case where \"v\" is a Unicode + string.) + +"), + +("Base","reverse!","reverse!(v[, start=1[, stop=length(v)]]) -> v + + In-place version of \"reverse()\". + +"), + +("Base","combinations","combinations(array, n) + + Generate all combinations of \"n\" elements from an indexable + object. Because the number of combinations can be very large, this + function returns an iterator object. Use + \"collect(combinations(array,n))\" to get an array of all + combinations. + +"), + +("Base","permutations","permutations(array) + + Generate all permutations of an indexable object. Because the + number of permutations can be very large, this function returns an + iterator object. Use \"collect(permutations(array))\" to get an + array of all permutations. + +"), + +("Base","partitions","partitions(n) + + Generate all integer arrays that sum to \"n\". Because the number + of partitions can be very large, this function returns an iterator + object. Use \"collect(partitions(n))\" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using \"length(partitions(n))\". + +"), + +("Base","partitions","partitions(n, m) + + Generate all arrays of \"m\" integers that sum to \"n\". Because + the number of partitions can be very large, this function returns + an iterator object. Use \"collect(partitions(n,m))\" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using \"length(partitions(n,m))\". + +"), + +("Base","partitions","partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + \"collect(partitions(array))\" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using \"length(partitions(array))\". + +"), + +("Base","partitions","partitions(array, m) + + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use \"collect(partitions(array,m))\" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using \"length(partitions(array,m))\". + +"), + +("Base","bitpack","bitpack(A::AbstractArray{T, N}) -> BitArray + + Converts a numeric array to a packed boolean array + +"), + +("Base","bitunpack","bitunpack(B::BitArray{N}) -> Array{Bool,N} + + Converts a packed boolean array to an array of booleans + +"), + +("Base","flipbits!","flipbits!(B::BitArray{N}) -> BitArray{N} + + Performs a bitwise not operation on B. See *~ operator*. + +"), + +("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on \"src\" and put the result + into \"dest\". + +"), + +("Base","rol!","rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on B. + +"), + +("Base","rol","rol(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation. + +"), + +("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on \"src\" and put the result + into \"dest\". + +"), + +("Base","ror!","ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on B. + +"), + +("Base","ror","ror(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation. + +"), + +("Base","sparse","sparse(I, J, V[, m, n, combine]) + + Create a sparse matrix \"S\" of dimensions \"m x n\" such that + \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to + combine duplicates. If \"m\" and \"n\" are not specified, they are + set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" + function is not supplied, duplicates are added by default. + +"), + +("Base","sparsevec","sparsevec(I, V[, m, combine]) + + Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] + = V[k]\". Duplicates are combined using the \"combine\" function, + which defaults to \"+\" if it is not provided. In julia, sparse + vectors are really just sparse matrices with one column. Given + Julia's Compressed Sparse Columns (CSC) storage format, a sparse + column matrix with one column is sparse, whereas a sparse row + matrix with one row ends up being dense. + +"), + +("Base","sparsevec","sparsevec(D::Dict[, m]) + + Create a sparse matrix of size \"m x 1\" where the row values are + keys from the dictionary, and the nonzero values are the values + from the dictionary. + +"), + +("Base","issparse","issparse(S) + + Returns \"true\" if \"S\" is sparse, and \"false\" otherwise. + +"), + +("Base","sparse","sparse(A) + + Convert an AbstractMatrix \"A\" into a sparse matrix. + +"), + +("Base","sparsevec","sparsevec(A) + + Convert a dense vector \"A\" into a sparse matrix of size \"m x + 1\". In julia, sparse vectors are really just sparse matrices with + one column. + +"), + +("Base","full","full(S) + + Convert a sparse matrix \"S\" into a dense matrix. + +"), + +("Base","nnz","nnz(A) + + Returns the number of stored (filled) elements in a sparse matrix. + +"), + +("Base","spzeros","spzeros(m, n) + + Create a sparse matrix of size \"m x n\". This sparse matrix will + not contain any nonzero values. No storage will be allocated for + nonzero values during construction. + +"), + +("Base","spones","spones(S) + + Create a sparse matrix with the same structure as that of \"S\", + but with every nonzero element having the value \"1.0\". + +"), + +("Base","speye","speye(type, m[, n]) + + Create a sparse identity matrix of specified type of size \"m x + m\". In case \"n\" is supplied, create a sparse identity matrix of + size \"m x n\". + +"), + +("Base","spdiagm","spdiagm(B, d[, m, n]) + + Construct a sparse diagonal matrix. \"B\" is a tuple of vectors + containing the diagonals and \"d\" is a tuple containing the + positions of the diagonals. In the case the input contains only one + diagonaly, \"B\" can be a vector (instead of a tuple) and \"d\" can + be the diagonal position (instead of a tuple), defaulting to 0 + (diagonal). Optionally, \"m\" and \"n\" specify the size of the + resulting sparse matrix. + +"), + +("Base","sprand","sprand([rng], m, n, p[, rfn]) + + Create a random \"m\" by \"n\" sparse matrix, in which the + probability of any element being nonzero is independently given by + \"p\" (and hence the mean density of nonzeros is also exactly + \"p\"). Nonzero values are sampled from the distribution specified + by \"rfn\". The uniform distribution is used in case \"rfn\" is not + specified. The optional \"rng\" argument specifies a random number + generator, see *Random Numbers*. + +"), + +("Base","sprandn","sprandn(m, n, p) + + Create a random \"m\" by \"n\" sparse matrix with the specified + (independent) probability \"p\" of any entry being nonzero, where + nonzero values are sampled from the normal distribution. + +"), + +("Base","sprandbool","sprandbool(m, n, p) + + Create a random \"m\" by \"n\" sparse boolean matrix with the + specified (independent) probability \"p\" of any entry being + \"true\". + +"), + +("Base","etree","etree(A[, post]) + + Compute the elimination tree of a symmetric sparse matrix \"A\" + from \"triu(A)\" and, optionally, its post-ordering permutation. + +"), + +("Base","symperm","symperm(A, p) + + Return the symmetric permutation of A, which is \"A[p,p]\". A + should be symmetric and sparse, where only the upper triangular + part of the matrix is stored. This algorithm ignores the lower + triangular part of the matrix. Only the upper triangular part of + the result is returned as well. + +"), + +("Base","nonzeros","nonzeros(A) + + Return a vector of the structural nonzero values in sparse matrix + \"A\". This includes zeros that are explicitly stored in the sparse + matrix. The returned vector points directly to the internal nonzero + storage of \"A\", and any modifications to the returned vector will + mutate \"A\" as well. See \"rowvals(A)\" and \"nzrange(A, col)\". + +"), + +("Base","rowvals","rowvals(A) + + Return a vector of the row indices of \"A\", and any modifications + to the returned vector will mutate \"A\" as well. Given the + internal storage format of sparse matrices, providing access to how + the row indices are stored internally can be useful in conjuction + with iterating over structural nonzero values. See \"nonzeros(A)\" + and \"nzrange(A, col)\". + +"), + +("Base","nzrange","nzrange(A, col) + + Return the range of indices to the structural nonzero values of a + sparse matrix column. In conjunction with \"nonzeros(A)\" and + \"rowvals(A)\", 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 + +"), + +("Base","exit","exit([code]) + + Quit (or control-D at the prompt). The default exit code is zero, + indicating that the processes completed successfully. + +"), + +("Base","quit","quit() + + Quit the program indicating that the processes completed + successfully. This function calls \"exit(0)\" (see \"exit()\"). + +"), + +("Base","atexit","atexit(f) + + Register a zero-argument function to be called at exit. + +"), + +("Base","atreplinit","atreplinit(f) + + Register a one-argument function to be called before the REPL + interface is initialized in interactive sessions; this is useful to + customize the interface. The argument of \"f\" is the REPL object. + This function should be called from within the \".juliarc.jl\" + initialization file. + +"), + +("Base","isinteractive","isinteractive() -> Bool + + Determine whether Julia is running an interactive session. + +"), + +("Base","whos","whos([Module,] [pattern::Regex]) + + Print information about exported global variables in a module, + optionally restricted to those matching \"pattern\". + +"), + +("Base","edit","edit(file::AbstractString[, line]) + + Edit a file optionally providing a line number to edit at. Returns + to the julia prompt when you quit the editor. + +"), + +("Base","edit","edit(function[, types]) + + Edit the definition of a function, optionally specifying a tuple of + types to indicate which method to edit. + +"), + +("Base","@edit","@edit() + + Evaluates the arguments to the function call, determines their + types, and calls the \"edit\" function on the resulting expression + +"), + +("Base","less","less(file::AbstractString[, line]) + + Show a file using the default pager, optionally providing a + starting line number. Returns to the julia prompt when you quit the + pager. + +"), + +("Base","less","less(function[, types]) + + Show the definition of a function using the default pager, + optionally specifying a tuple of types to indicate which method to + see. + +"), + +("Base","@less","@less() + + Evaluates the arguments to the function call, determines their + types, and calls the \"less\" function on the resulting expression + +"), + +("Base","clipboard","clipboard(x) + + Send a printed form of \"x\" to the operating system clipboard + (\"copy\"). + +"), + +("Base","clipboard","clipboard() -> AbstractString + + Return a string with the contents of the operating system clipboard + (\"paste\"). + +"), + +("Base","require","require(file::AbstractString...) + + Load source files once, in the context of the \"Main\" module, on + every active node, searching standard locations for files. + \"require\" is considered a top-level operation, so it sets the + current \"include\" path but does not use it to search for files + (see help for \"include\"). This function is typically used to load + library code, and is implicitly called by \"using\" to load + packages. + + When searching for files, \"require\" first looks in the current + working directory, then looks for package code under \"Pkg.dir()\", + then tries paths in the global array \"LOAD_PATH\". + +"), + +("Base","reload","reload(file::AbstractString) + + Like \"require\", except forces loading of files regardless of + whether they have been loaded before. Typically used when + interactively developing libraries. + +"), + +("Base","include","include(path::AbstractString) + + Evaluate the contents of a source file in the current context. + During including, a task-local include path is set to the directory + containing the file. Nested calls to \"include\" will search + relative to that path. All paths refer to files on node 1 when + running in parallel, and files will be fetched from node 1. This + function is typically used to load source interactively, or to + combine files in packages that are broken into multiple source + files. + +"), + +("Base","include_string","include_string(code::AbstractString) + + Like \"include\", except reads code from the given string rather + than from a file. Since there is no file path involved, no path + processing or fetching from node 1 is done. + +"), + +("Base","help","help(name) + + Get help for a function. \"name\" can be an object or a string. + +"), + +("Base","apropos","apropos(string) + + Search documentation for functions related to \"string\". + +"), + +("Base","which","which(f, types) + + Returns the method of \"f\" (a \"Method\" object) that would be + called for arguments of the given types. + + If \"types\" is an abstract type, then the method that would be + called by \"invoke\" is returned. + +"), + +("Base","which","which(symbol) + + Return the module in which the binding for the variable referenced + by \"symbol\" was created. + +"), + +("Base","@which","@which() + + Applied to a function call, it evaluates the arguments to the + specified function call, and returns the \"Method\" object for the + method that would be called for those arguments. Applied to a + variable, it returns the module in which the variable was bound. It + calls out to the \"which\" function. + +"), + +("Base","methods","methods(f[, types]) + + Returns the method table for \"f\". + + If \"types\" is specified, returns an array of methods whose types + match. + +"), + +("Base","methodswith","methodswith(typ[, module or function][, showparents]) + + Return an array of methods with an argument of type \"typ\". If + optional \"showparents\" is \"true\", also return arguments with a + parent type of \"typ\", excluding type \"Any\". + + The optional second argument restricts the search to a particular + module or function. + +"), + +("Base","@show","@show() + + Show an expression and result, returning the result + +"), + +("Base","versioninfo","versioninfo([verbose::Bool]) + + Print information about the version of Julia in use. If the + \"verbose\" argument is true, detailed system information is shown + as well. + +"), + +("Base","workspace","workspace() + + Replace the top-level module (\"Main\") with a new one, providing a + clean workspace. The previous \"Main\" module is made available as + \"LastMain\". A previously-loaded package can be accessed using a + statement such as \"using LastMain.Package\". + + This function should only be used interactively. + +"), + +("Base","ans","ans + + A variable referring to the last computed value, automatically set + at the interactive prompt. + +"), + +("Base","is","is(x, y) -> Bool +===(x, y) -> Bool +≡(x, y) -> Bool + + Determine whether \"x\" and \"y\" are identical, in the sense that + no program could distinguish them. Compares mutable objects by + address in memory, and compares immutable objects (such as numbers) + by contents at the bit level. This function is sometimes called + \"egal\". + +"), + +("Base","isa","isa(x, type) -> Bool + + Determine whether \"x\" is of the given \"type\". + +"), + +("Base","isequal","isequal(x, y) + + Similar to \"==\", except treats all floating-point \"NaN\" values + as equal to each other, and treats \"-0.0\" as unequal to \"0.0\". + The default implementation of \"isequal\" calls \"==\", so if you + have a type that doesn't have these floating-point subtleties then + you probably only need to define \"==\". + + \"isequal\" is the comparison function used by hash tables + (\"Dict\"). \"isequal(x,y)\" must imply that \"hash(x) == + hash(y)\". + + This typically means that if you define your own \"==\" function + then you must define a corresponding \"hash\" (and vice versa). + Collections typically implement \"isequal\" by calling \"isequal\" + recursively on all contents. + + Scalar types generally do not need to implement \"isequal\" + separate from \"==\", unless they represent floating-point numbers + amenable to a more efficient implementation than that provided as a + generic fallback (based on \"isnan\", \"signbit\", and \"==\"). + +"), + +("Base","isless","isless(x, y) + + Test whether \"x\" is less than \"y\", according to a canonical + total order. Values that are normally unordered, such as \"NaN\", + are ordered in an arbitrary but consistent fashion. This is the + default comparison used by \"sort\". Non-numeric types with a + canonical total order should implement this function. Numeric types + only need to implement it if they have special values such as + \"NaN\". + +"), + +("Base","ifelse","ifelse(condition::Bool, x, y) + + Return \"x\" if \"condition\" is true, otherwise return \"y\". This + differs from \"?\" or \"if\" in that it is an ordinary function, so + all the arguments are evaluated first. In some cases, using + \"ifelse\" instead of an \"if\" statement can eliminate the branch + in generated code and provide higher performance in tight loops. + +"), + +("Base","lexcmp","lexcmp(x, y) + + Compare \"x\" and \"y\" lexicographically and return -1, 0, or 1 + depending on whether \"x\" is less than, equal to, or greater than + \"y\", respectively. This function should be defined for + lexicographically comparable types, and \"lexless\" will call + \"lexcmp\" by default. + +"), + +("Base","lexless","lexless(x, y) + + Determine whether \"x\" is lexicographically less than \"y\". + +"), + +("Base","typeof","typeof(x) + + Get the concrete type of \"x\". + +"), + +("Base","tuple","tuple(xs...) + + Construct a tuple of the given objects. + +"), + +("Base","ntuple","ntuple(f::Function, n) + + Create a tuple of length \"n\", computing each element as \"f(i)\", + where \"i\" is the index of the element. + +"), + +("Base","object_id","object_id(x) + + Get a unique integer id for \"x\". \"object_id(x)==object_id(y)\" + if and only if \"is(x,y)\". + +"), + +("Base","hash","hash(x[, h]) + + Compute an integer hash code such that \"isequal(x,y)\" implies + \"hash(x)==hash(y)\". The optional second argument \"h\" is a hash + code to be mixed with the result. + + New types should implement the 2-argument form, typically by + calling the 2-argument \"hash\" method recursively in order to mix + hashes of the contents with each other (and with \"h\"). + Typically, any type that implements \"hash\" should also implement + its own \"==\" (hence \"isequal\") to guarantee the property + mentioned above. + +"), + +("Base","finalizer","finalizer(x, function) + + Register a function \"f(x)\" to be called when there are no + program-accessible references to \"x\". The behavior of this + function is unpredictable if \"x\" is of a bits type. + +"), + +("Base","finalize","finalize(x) + + Immediately run finalizers registered for object \"x\". + +"), + +("Base","copy","copy(x) + + Create a shallow copy of \"x\": the outer structure is copied, but + not all internal values. For example, copying an array produces a + new array with identically-same elements as the original. + +"), + +("Base","deepcopy","deepcopy(x) + + Create a deep copy of \"x\": everything is copied recursively, + resulting in a fully independent object. For example, deep-copying + an array produces a new array whose elements are deep copies of the + original elements. Calling *deepcopy* on an object should generally + have the same effect as serializing and then deserializing it. + + As a special case, functions can only be actually deep-copied if + they are anonymous, otherwise they are just copied. The difference + is only relevant in the case of closures, i.e. functions which may + contain hidden internal references. + + While it isn't normally necessary, user-defined types can override + the default \"deepcopy\" behavior by defining a specialized version + of the function \"deepcopy_internal(x::T, dict::ObjectIdDict)\" + (which shouldn't otherwise be used), where \"T\" is the type to be + specialized for, and \"dict\" keeps track of objects copied so far + within the recursion. Within the definition, \"deepcopy_internal\" + should be used in place of \"deepcopy\", and the \"dict\" variable + should be updated as appropriate before returning. + +"), + +("Base","isdefined","isdefined([object], index | symbol) + + Tests whether an assignable location is defined. The arguments can + be an array and index, a composite object and field name (as a + symbol), or a module and a symbol. With a single symbol argument, + tests whether a global variable with that name is defined in + \"current_module()\". + +"), + +("Base","convert","convert(T, x) + + Convert \"x\" to a value of type \"T\". + + If \"T\" is an \"Integer\" type, an \"InexactError\" will be raised + if \"x\" is not representable by \"T\", for example if \"x\" is not + integer-valued, or is outside the range supported by \"T\". + + julia> convert(Int, 3.0) + 3 + + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 + + If \"T\" is a \"FloatingPoint\" or \"Rational\" type, then it will + return the closest value to \"x\" representable by \"T\". + + julia> x = 1/3 + 0.3333333333333333 + + julia> convert(Float32, x) + 0.33333334f0 + + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 + +"), + +("Base","promote","promote(xs...) + + Convert all arguments to their common promotion type (if any), and + return them all (as a tuple). + +"), + +("Base","oftype","oftype(x, y) + + Convert \"y\" to the type of \"x\" (\"convert(typeof(x), y)\"). + +"), + +("Base","widen","widen(type | x) + + If the argument is a type, return a \"larger\" type (for numeric + types, this will be a type with at least as much range and + precision as the argument, and usually more). Otherwise the + argument \"x\" is converted to \"widen(typeof(x))\". + + julia> widen(Int32) + Int64 + + julia> widen(1.5f0) + 1.5 + +"), + +("Base","identity","identity(x) + + The identity function. Returns its argument. + +"), + +("Base","super","super(T::DataType) + + Return the supertype of DataType T + +"), + +("Base","issubtype","issubtype(type1, type2) + + True if and only if all values of \"type1\" are also of \"type2\". + Can also be written using the \"<:\" infix operator as \"type1 <: + type2\". + +"), + +("Base","<:","<:(T1, T2) + + Subtype operator, equivalent to \"issubtype(T1,T2)\". + +"), + +("Base","subtypes","subtypes(T::DataType) + + Return a list of immediate subtypes of DataType T. Note that all + currently loaded subtypes are included, including those not visible + in the current module. + +"), + +("Base","typemin","typemin(type) + + The lowest value representable by the given (real) numeric type. + +"), + +("Base","typemax","typemax(type) + + The highest value representable by the given (real) numeric type. + +"), + +("Base","realmin","realmin(type) + + The smallest in absolute value non-subnormal value representable by + the given floating-point type + +"), + +("Base","realmax","realmax(type) + + The highest finite value representable by the given floating-point + type + +"), + +("Base","maxintfloat","maxintfloat(type) + + The largest integer losslessly representable by the given floating- + point type + +"), + +("Base","sizeof","sizeof(type) + + Size, in bytes, of the canonical binary representation of the given + type, if any. + +"), + +("Base","eps","eps([type]) + + The distance between 1.0 and the next larger representable + floating-point value of \"type\". Only floating-point types are + sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" + is returned. + +"), + +("Base","eps","eps(x) + + The distance between \"x\" and the next larger representable + floating-point value of the same type as \"x\". + +"), + +("Base","promote_type","promote_type(type1, type2) + + Determine a type big enough to hold values of each argument type + without loss, whenever possible. In some cases, where no type + exists to which both types can be promoted losslessly, some loss is + tolerated; for example, \"promote_type(Int64,Float64)\" returns + \"Float64\" even though strictly, not all \"Int64\" values can be + represented exactly as \"Float64\" values. + +"), + +("Base","promote_rule","promote_rule(type1, type2) + + Specifies what type should be used by \"promote\" when given values + of types \"type1\" and \"type2\". This function should not be + called directly, but should have definitions added to it for new + types as appropriate. + +"), + +("Base","getfield","getfield(value, name::Symbol) + + Extract a named field from a value of composite type. The syntax + \"a.b\" calls \"getfield(a, :b)\", and the syntax \"a.(b)\" calls + \"getfield(a, b)\". + +"), + +("Base","setfield!","setfield!(value, name::Symbol, x) + + Assign \"x\" to a named field in \"value\" of composite type. The + syntax \"a.b = c\" calls \"setfield!(a, :b, c)\", and the syntax + \"a.(b) = c\" calls \"setfield!(a, b, c)\". + +"), + +("Base","fieldoffsets","fieldoffsets(type) + + The byte offset of each field of a type relative to the data start. + For example, we could use it in the following manner to summarize + information about a struct type: + + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; + + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) + +"), + +("Base","fieldtype","fieldtype(type, name::Symbol | index::Int) + + Determine the declared type of a field (specified by name or index) + in a composite type. + +"), + +("Base","isimmutable","isimmutable(v) + + True if value \"v\" is immutable. See *Immutable Composite Types* + for a discussion of immutability. Note that this function works on + values, so if you give it a type, it will tell you that a value of + \"DataType\" is mutable. + +"), + +("Base","isbits","isbits(T) + + True if \"T\" is a \"plain data\" type, meaning it is immutable and + contains no references to other values. Typical examples are + numeric types such as \"UInt8\", \"Float64\", and + \"Complex{Float64}\". + + julia> isbits(Complex{Float64}) + true + + julia> isbits(Complex) + false + +"), + +("Base","isleaftype","isleaftype(T) + + Determine whether \"T\" is a concrete type that can have instances, + meaning its only subtypes are itself and \"None\" (but \"T\" itself + is not \"None\"). + +"), + +("Base","typejoin","typejoin(T, S) + + Compute a type that contains both \"T\" and \"S\". + +"), + +("Base","typeintersect","typeintersect(T, S) + + Compute a type that contains the intersection of \"T\" and \"S\". + Usually this will be the smallest such type or one close to it. + +"), + +("Base","Val{c}","Val{c}() + + Create a \"value type\" out of \"c\", which must be an \"isbits\" + value. The intent of this construct is to be able to dispatch on + constants, e.g., \"f(Val{false})\" allows you to dispatch directly + (at compile-time) to an implementation \"f(::Type{Val{false}})\", + without having to test the boolean value at runtime. + +"), + +("","@enum EnumName EnumValue1[=x] EnumValue2[=y]","@enum EnumName EnumValue1[=x] EnumValue2[=y] + + Create an \"Enum\" type with name \"EnumName\" and enum member + values of \"EnumValue1\" and \"EnumValue2\" with optional assigned + values of \"x\" and \"y\", respectively. \"EnumName\" can be used + just like other types and enum member values as regular values, + such as + + julia> @enum FRUIT apple=1 orange=2 kiwi=3 + + julia> f(x::FRUIT) = \"I'm a FRUIT with value: \$(Int(x))\" + f (generic function with 1 method) + + julia> f(apple) + \"I'm a FRUIT with value: 1\" + +"), + +("Base","instances","instances(T::Type) + + Return a collection of all instances of the given type, if + applicable. Mostly used for enumerated types (see \"@enum\"). + +"), + +("Base","method_exists","method_exists(f, Tuple type) -> Bool + + Determine whether the given generic function has a method matching + the given \"Tuple\" of argument types. + + julia> method_exists(length, Tuple{Array}) + true + +"), + +("Base","applicable","applicable(f, args...) -> Bool + + Determine whether the given generic function has a method + applicable to the given arguments. + + julia> function f(x, y) + x + y + end; + + julia> applicable(f, 1) + false + + julia> applicable(f, 1, 2) + true + +"), + +("Base","invoke","invoke(f, (types...), args...) + + Invoke a method for the given generic function matching the + specified types (as a tuple), on the specified arguments. The + arguments must be compatible with the specified types. This allows + invoking a method other than the most specific matching method, + which is useful when the behavior of a more general definition is + explicitly needed (often as part of the implementation of a more + specific method of the same function). + +"), + +("Base","|>","|>(x, f) + + Applies a function to the preceding argument. This allows for easy + function chaining. + + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 + +"), + +("Base","call","call(x, args...) + + If \"x\" is not a \"Function\", then \"x(args...)\" is equivalent + to \"call(x, args...)\". This means that function-like behavior + can be added to any type by defining new \"call\" methods. + +"), + +("Base","eval","eval([m::Module], expr::Expr) + + Evaluate an expression in the given module and return the result. + Every module (except those defined with \"baremodule\") has its own + 1-argument definition of \"eval\", which evaluates expressions in + that module. + +"), + +("Base","@eval","@eval() + + Evaluate an expression and return the value. + +"), + +("Base","evalfile","evalfile(path::AbstractString) + + Load the file using \"include\", evaluate all expressions, and + return the value of the last one. + +"), + +("Base","esc","esc(e::ANY) + + Only valid in the context of an Expr returned from a macro. + Prevents the macro hygiene pass from turning embedded variables + into gensym variables. See the *Macros* section of the + Metaprogramming chapter of the manual for more details and + examples. + +"), + +("Base","gensym","gensym([tag]) + + Generates a symbol which will not conflict with other variable + names. + +"), + +("Base","@gensym","@gensym() + + Generates a gensym symbol for a variable. For example, \"@gensym x + y\" is transformed into \"x = gensym(\"x\"); y = gensym(\"y\")\". + +"), + +("Base","parse","parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could + later be passed to eval for execution). Start is the index of the + first character to start parsing. If \"greedy\" is true (default), + \"parse\" will try to consume as much input as it can; otherwise, + it will stop as soon as it has parsed a valid expression. + Incomplete but otherwise syntactically valid expressions will + return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is + true (default), syntax errors other than incomplete expressions + will raise an error. If \"raise\" is false, \"parse\" will return + an expression that will raise an error upon evaluation. + +"), + +("Base","parse","parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An + error is thrown if there are additional characters after the first + expression. If \"raise\" is true (default), syntax errors will + raise an error; otherwise, \"parse\" will return an expression that + will raise an error upon evaluation. + +"), + +("Base","Nullable","Nullable(x) + + Wrap value \"x\" in an object of type \"Nullable\", which indicates + whether a value is present. \"Nullable(x)\" yields a non-empty + wrapper, and \"Nullable{T}()\" yields an empty instance of a + wrapper that might contain a value of type \"T\". + +"), + +("Base","get","get(x) + + Attempt to access the value of the \"Nullable\" object, \"x\". + Returns the value if it is present; otherwise, throws a + \"NullException\". + +"), + +("Base","get","get(x, y) + + Attempt to access the value of the \"Nullable{T}\" object, \"x\". + Returns the value if it is present; otherwise, returns \"convert(T, + y)\". + +"), + +("Base","isnull","isnull(x) + + Is the \"Nullable\" object \"x\" null, i.e. missing a value? + +"), + +("Base","run","run(command) + + Run a command object, constructed with backticks. Throws an error + if anything goes wrong, including the process exiting with a non- + zero status. + +"), + +("Base","spawn","spawn(command) + + Run a command object asynchronously, returning the resulting + \"Process\" object. + +"), + +("Base","DevNull","DevNull + + Used in a stream redirect to discard all data written to it. + Essentially equivalent to /dev/null on Unix or NUL on Windows. + Usage: \"run(`cat test.txt` |> DevNull)\" + +"), + +("Base","success","success(command) + + Run a command object, constructed with backticks, and tell whether + it was successful (exited with a code of 0). An exception is raised + if the process cannot be started. + +"), + +("Base","process_running","process_running(p::Process) + + Determine whether a process is currently running. + +"), + +("Base","process_exited","process_exited(p::Process) + + Determine whether a process has exited. + +"), + +("Base","kill","kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the + process. + +"), + +("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) + + Start running \"command\" asynchronously, and return a tuple + \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" + reads from the process's standard output and \"stdio\" optionally + specifies the process's standard input stream. If \"mode\" is + \"\"w\"\", then \"stream\" writes to the process's standard input + and \"stdio\" optionally specifies the process's standard output + stream. + +"), + +("Base","open","open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) + + Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + \"f\". + +"), + +("Base","Sys","Sys.set_process_title(title::AbstractString) + + Set the process title. No-op on some operating systems. (not + exported) + +"), + +("Base","Sys","Sys.get_process_title() + + Get the process title. On some systems, will always return empty + string. (not exported) + +"), + +("Base","readandwrite","readandwrite(command) + + Starts running a command asynchronously, and returns a tuple + (stdout,stdin,process) of the output stream and input stream of the + process, and the process object itself. + +"), + +("Base","ignorestatus","ignorestatus(command) + + Mark a command object so that running it will not throw an error if + the result code is non-zero. + +"), + +("Base","detach","detach(command) + + Mark a command object so that it will be run in a new process + group, allowing it to outlive the julia process, and not have + Ctrl-C interrupts passed to it. + +"), + +("Base","setenv","setenv(command, env; dir=working_dir) + + Set environment variables to use when running the given command. + \"env\" is either a dictionary mapping strings to strings, an array + of strings of the form \"\"var=val\"\", or zero or more + \"\"var\"=>val\" pair arguments. In order to modify (rather than + replace) the existing environment, create \"env\" by \"copy(ENV)\" + and then setting \"env[\"var\"]=val\" as desired, or use + \"withenv\". + + The \"dir\" keyword argument can be used to specify a working + directory for the command. + +"), + +("Base","withenv","withenv(f::Function, kv::Pair...) + + Execute \"f()\" in an environment that is temporarily modified (not + replaced as in \"setenv\") by zero or more \"\"var\"=>val\" + arguments \"kv\". \"withenv\" is generally used via the + \"withenv(kv...) do ... end\" syntax. A value of \"nothing\" can + be used to temporarily unset an environment variable (if it is + set). When \"withenv\" returns, the original environment has been + restored. + +"), + +("Base","pipe","pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source + and destination can be commands, I/O streams, strings, or results + of other \"pipe\" calls. At least one argument must be a command. + Strings refer to filenames. When called with more than two + arguments, they are chained together from left to right. For + example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". + This provides a more concise way to specify multi-stage pipelines. + + **Examples**: + * \"run(pipe(`ls`, `grep xyz`))\" + + * \"run(pipe(`ls`, \"out.txt\"))\" + + * \"run(pipe(\"out.txt\", `grep xyz`))\" + +"), + +("Base","pipe","pipe(command; stdin, stdout, stderr, append=false) + + Redirect I/O to or from the given \"command\". Keyword arguments + specify which of the command's streams should be redirected. + \"append\" controls whether file output appends to the file. This + is a more general version of the 2-argument \"pipe\" function. + \"pipe(from, to)\" is equivalent to \"pipe(from, stdout=to)\" when + \"from\" is a command, and to \"pipe(to, stdin=from)\" when + \"from\" is another kind of data source. + + **Examples**: + * \"run(pipe(`dothings`, stdout=\"out.txt\", + stderr=\"errs.txt\"))\" + + * \"run(pipe(`update`, stdout=\"log.txt\", append=true))\" + +"), + +("Base","gethostname","gethostname() -> AbstractString + + Get the local machine's host name. + +"), + +("Base","getipaddr","getipaddr() -> AbstractString + + Get the IP address of the local machine, as a string of the form + \"x.x.x.x\". + +"), + +("Base","getpid","getpid() -> Int32 + + Get julia's process ID. + +"), + +("Base","time","time() + + Get the system time in seconds since the epoch, with fairly high + (typically, microsecond) resolution. + +"), + +("Base","time_ns","time_ns() + + Get the time in nanoseconds. The time corresponding to 0 is + undefined, and wraps every 5.8 years. + +"), + +("Base","tic","tic() + + Set a timer to be read by the next call to \"toc()\" or \"toq()\". + The macro call \"@time expr\" can also be used to time evaluation. + +"), + +("Base","toc","toc() + + Print and return the time elapsed since the last \"tic()\". + +"), + +("Base","toq","toq() + + Return, but do not print, the time elapsed since the last + \"tic()\". + +"), + +("Base","@time","@time() + + A macro to execute an expression, printing the time it took to + execute, the number of allocations, and the total number of bytes + its execution caused to be allocated, before returning the value of + the expression. + +"), + +("Base","@timev","@timev() + + This is a verbose version of the \"@time\" macro, it first prints + the same information as \"@time\", then any non-zero memory + allocation counters, and then returns the value of the expression. + +"), + +("Base","@timed","@timed() + + A macro to execute an expression, and return the value of the + expression, elapsed time, total bytes allocated, garbage collection + time, and an object with various memory allocation counters. + +"), + +("Base","@elapsed","@elapsed() + + A macro to evaluate an expression, discarding the resulting value, + instead returning the number of seconds it took to execute as a + floating-point number. + +"), + +("Base","@allocated","@allocated() + + A macro to evaluate an expression, discarding the resulting value, + instead returning the total number of bytes allocated during + evaluation of the expression. Note: the expression is evaluated + inside a local function, instead of the current context, in order + to eliminate the effects of compilation, however, there still may + be some allocations due to JIT compilation. This also makes the + results inconsistent with the \"@time\" macros, which do not try to + adjust for the effects of compilation. + +"), + +("Base","EnvHash","EnvHash() -> EnvHash + + A singleton of this type provides a hash table interface to + environment variables. + +"), + +("Base","ENV","ENV + + Reference to the singleton \"EnvHash\", providing a dictionary + interface to system environment variables. + +"), + +("Base","@unix","@unix() + + Given \"@unix? a : b\", do \"a\" on Unix systems (including Linux + and OS X) and \"b\" elsewhere. See documentation for Handling + Platform Variations in the Calling C and Fortran Code section of + the manual. + +"), + +("Base","@osx","@osx() + + Given \"@osx? a : b\", do \"a\" on OS X and \"b\" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. + +"), + +("Base","@linux","@linux() + + Given \"@linux? a : b\", do \"a\" on Linux and \"b\" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. + +"), + +("Base","@windows","@windows() + + Given \"@windows? a : b\", do \"a\" on Windows and \"b\" elsewhere. + See documentation for Handling Platform Variations in the Calling C + and Fortran Code section of the manual. + +"), + +("Base","error","error(message::AbstractString) + + Raise an \"ErrorException\" with the given message + +"), + +("Base","throw","throw(e) + + Throw an object as an exception + +"), + +("Base","rethrow","rethrow([e]) + + Throw an object without changing the current exception backtrace. + The default argument is the current exception (if called within a + \"catch\" block). + +"), + +("Base","backtrace","backtrace() + + Get a backtrace object for the current program point. + +"), + +("Base","catch_backtrace","catch_backtrace() + + Get the backtrace of the current exception, for use within + \"catch\" blocks. + +"), + +("Base","assert","assert(cond) + + Throw an \"AssertionError\" if \"cond\" is false. Also available as + the macro \"@assert expr\". + +"), + +("","@assert cond [text]","@assert cond [text] + + Throw an \"AssertionError\" if \"cond\" is false. Preferred syntax + for writing assertions. + +"), + +("Base","ArgumentError","ArgumentError(msg) + + The parameters to a function call do not match a valid signature. + +"), + +("Base","AssertionError","AssertionError([msg]) + + The asserted condition did not evalutate to \"true\". + +"), + +("Base","BoundsError","BoundsError([a][, i]) + + An indexing operation into an array, \"a\", tried to access an out- + of-bounds element, \"i\". + +"), + +("Base","DimensionMismatch","DimensionMismatch([msg]) + + The objects called do not have matching dimensionality. + +"), + +("Base","DivideError","DivideError() + + Integer division was attempted with a denominator value of 0. + +"), + +("Base","DomainError","DomainError() + + The arguments to a function or constructor are outside the valid + domain. + +"), + +("Base","EOFError","EOFError() + + No more data was available to read from a file or stream. + +"), + +("Base","ErrorException","ErrorException(msg) + + Generic error type. The error message, in the *.msg* field, may + provide more specific details. + +"), + +("Base","InexactError","InexactError() + + Type conversion cannot be done exactly. + +"), + +("Base","InterruptException","InterruptException() + + The process was stopped by a terminal interrupt (CTRL+C). + +"), + +("Base","KeyError","KeyError(key) + + An indexing operation into an \"Associative\" (\"Dict\") or \"Set\" + like object tried to access or delete a non-existent element. + +"), + +("Base","LoadError","LoadError(file::AbstractString, line::Int, error) + + An error occurred while *including*, *requiring*, or *using* a + file. The error specifics should be available in the *.error* + field. + +"), + +("Base","MethodError","MethodError(f, args) + + A method with the required type signature does not exist in the + given generic function. + +"), + +("Base","NullException","NullException() + + An attempted access to a \"Nullable\" with no defined value. + +"), + +("Base","OutOfMemoryError","OutOfMemoryError() + + An operation allocated too much memory for either the system or the + garbage collector to handle properly. + +"), + +("Base","ReadOnlyMemoryError","ReadOnlyMemoryError() + + An operation tried to write to memory that is read-only. + +"), + +("Base","OverflowError","OverflowError() + + The result of an expression is too large for the specified type and + will cause a wraparound. + +"), + +("Base","ParseError","ParseError(msg) + + The expression passed to the *parse* function could not be + interpreted as a valid Julia expression. + +"), + +("Base","ProcessExitedException","ProcessExitedException() + + After a client Julia process has exited, further attempts to + reference the dead child will throw this exception. + +"), + +("Base","StackOverflowError","StackOverflowError() + + The function call grew beyond the size of the call stack. This + usually happens when a call recurses infinitely. + +"), + +("Base","SystemError","SystemError(prefix::AbstractString[, errnum::Int32]) + + A system call failed with an error code (in the \"errno\" global + variable). + +"), + +("Base","TypeError","TypeError(func::Symbol, context::AbstractString, expected::Type, got) + + A type assertion failure, or calling an intrinsic function with an + incorrect argument type. + +"), + +("Base","UndefRefError","UndefRefError() + + The item or field is not defined for the given object. + +"), + +("Base","UndefVarError","UndefVarError(var::Symbol) + + A symbol in the current scope is not defined. + +"), + +("Base","Timer","Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. The callback is + passed one argument, the timer object itself. The callback will be + invoked after the specified initial delay, and then repeating with + the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is + only triggered once. Times are in seconds. A timer is stopped and + has its resources freed by calling \"close\" on it. + +"), + +("Base","Timer","Timer(delay, repeat=0) + + Create a timer that wakes up tasks waiting for it (by calling + \"wait\" on the timer object) at a specified interval. + +"), + +("Base","module_name","module_name(m::Module) -> Symbol + + Get the name of a module as a symbol. + +"), + +("Base","module_parent","module_parent(m::Module) -> Module + + Get a module's enclosing module. \"Main\" is its own parent. + +"), + +("Base","current_module","current_module() -> Module + + Get the *dynamically* current module, which is the module code is + currently being read from. In general, this is not the same as the + module containing the call to this function. + +"), + +("Base","fullname","fullname(m::Module) + + Get the fully-qualified name of a module as a tuple of symbols. For + example, \"fullname(Base.Pkg)\" gives \"(:Base,:Pkg)\", and + \"fullname(Main)\" gives \"()\". + +"), + +("Base","names","names(x::Module[, all=false[, imported=false]]) + + Get an array of the names exported by a module, with optionally + more module globals according to the additional parameters. + +"), + +("Base","nfields","nfields(x::DataType) -> Int + + Get the number of fields of a data type. + +"), + +("Base","fieldnames","fieldnames(x::DataType) + + Get an array of the fields of a data type. + +"), + +("Base","isconst","isconst([m::Module], s::Symbol) -> Bool + + Determine whether a global is declared \"const\" in a given module. + The default module argument is \"current_module()\". + +"), + +("Base","isgeneric","isgeneric(f::Function) -> Bool + + Determine whether a function is generic. + +"), + +("Base","function_name","function_name(f::Function) -> Symbol + + Get the name of a generic function as a symbol, or \":anonymous\". + +"), + +("Base","function_module","function_module(f::Function, types) -> Module + + Determine the module containing a given definition of a generic + function. + +"), + +("Base","functionloc","functionloc(f::Function, types) + + Returns a tuple \"(filename,line)\" giving the location of a method + definition. + +"), + +("Base","functionloc","functionloc(m::Method) + + Returns a tuple \"(filename,line)\" giving the location of a method + definition. + +"), + +("Base","gc","gc() + + Perform garbage collection. This should not generally be used. + +"), + +("Base","gc_enable","gc_enable(on::Bool) + + Control whether garbage collection is enabled using a boolean + argument (true for enabled, false for disabled). Returns previous + GC state. Disabling garbage collection should be used only with + extreme caution, as it can cause memory use to grow without bound. + +"), + +("Base","macroexpand","macroexpand(x) + + Takes the expression x and returns an equivalent expression with + all macros removed (expanded). + +"), + +("Base","expand","expand(x) + + Takes the expression x and returns an equivalent expression in + lowered form + +"), + +("Base","code_lowered","code_lowered(f, types) + + Returns an array of lowered ASTs for the methods matching the given + generic function and type signature. + +"), + +("Base","@code_lowered","@code_lowered() + + Evaluates the arguments to the function call, determines their + types, and calls \"code_lowered()\" on the resulting expression + +"), + +("Base","code_typed","code_typed(f, types; optimize=true) + + Returns an array of lowered and type-inferred ASTs for the methods + matching the given generic function and type signature. The keyword + argument \"optimize\" controls whether additional optimizations, + such as inlining, are also applied. + +"), + +("Base","@code_typed","@code_typed() + + Evaluates the arguments to the function call, determines their + types, and calls \"code_typed()\" on the resulting expression + +"), + +("Base","code_warntype","code_warntype(f, types) + + Displays lowered and type-inferred ASTs for the methods matching + the given generic function and type signature. The ASTs are + annotated in such a way as to cause \"non-leaf\" types to be + emphasized (if color is available, displayed in red). This serves + as a warning of potential type instability. Not all non-leaf types + are particularly problematic for performance, so the results need + to be used judiciously. See *@code_warntype* for more information. + +"), + +("Base","@code_warntype","@code_warntype() + + Evaluates the arguments to the function call, determines their + types, and calls \"code_warntype()\" on the resulting expression + +"), + +("Base","code_llvm","code_llvm(f, types) + + Prints the LLVM bitcodes generated for running the method matching + the given generic function and type signature to \"STDOUT\". + + All metadata and dbg.* calls are removed from the printed bitcode. + Use code_llvm_raw for the full IR. + +"), + +("Base","@code_llvm","@code_llvm() + + Evaluates the arguments to the function call, determines their + types, and calls \"code_llvm()\" on the resulting expression + +"), + +("Base","code_native","code_native(f, types) + + Prints the native assembly instructions generated for running the + method matching the given generic function and type signature to + STDOUT. + +"), + +("Base","@code_native","@code_native() + + Evaluates the arguments to the function call, determines their + types, and calls \"code_native()\" on the resulting expression + +"), + +("Base","precompile","precompile(f, args::Tuple{Vararg{Any}}) + + Compile the given function \"f\" for the argument tuple (of types) + \"args\", but do not execute it. + +"), + +("Base","ccall","ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) + + Call function in C-exported shared library, specified by + \"(function name, library)\" tuple, where each component is an + AbstractString or :Symbol. + + Note that the argument type tuple must be a literal tuple, and not + a tuple-valued variable or expression. Alternatively, ccall may + also be used to call a function pointer, such as one returned by + dlsym. + + Each \"ArgumentValue\" to the \"ccall\" will be converted to the + corresponding \"ArgumentType\", by automatic insertion of calls to + \"unsafe_convert(ArgumentType, cconvert(ArgumentType, + ArgumentValue))\". (see also the documentation for each of these + functions for further details). In most cases, this simply results + in a call to \"convert(ArgumentType, ArgumentValue)\" + +"), + +("Base","cglobal","cglobal((symbol, library)[, type=Void]) + + Obtain a pointer to a global variable in a C-exported shared + library, specified exactly as in \"ccall\". Returns a + \"Ptr{Type}\", defaulting to \"Ptr{Void}\" if no Type argument is + supplied. The values can be read or written by \"unsafe_load\" or + \"unsafe_store!\", respectively. + +"), + +("Base","cfunction","cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + + Generate C-callable function pointer from Julia function. Type + annotation of the return value in the callback function is a must + for situations where Julia cannot infer the return type + automatically. + + For example: + + function foo() + # body + + retval::Float64 + end + + bar = cfunction(foo, Float64, ()) + +"), + +("Base","unsafe_convert","unsafe_convert(T, x) + + Convert \"x\" to a value of type \"T\" + + In cases where \"convert\" would need to take a Julia object and + turn it into a \"Ptr\", this function should be used to define and + perform that conversion. + + Be careful to ensure that a julia reference to \"x\" exists as long + as the result of this function will be used. Accordingly, the + argument \"x\" to this function should never be an expression, only + a variable name or field reference. For example, \"x=a.b.c\" is + acceptable, but \"x=[a,b,c]\" is not. + + The \"unsafe\" prefix on this function indicates that using the + result of this function after the \"x\" argument to this function + is no longer accessible to the program may cause undefined + behavior, including program corruption or segfaults, at any later + time. + +"), + +("Base","cconvert","cconvert(T, x) + + Convert \"x\" to a value of type \"T\", typically by calling + \"convert(T,x)\" + + In cases where \"x\" cannot be safely converted to \"T\", unlike + \"convert\", \"cconvert\" may return an object of a type different + from \"T\", which however is suitable for \"unsafe_convert\" to + handle. + + Neither \"convert\" nor \"cconvert\" should take a Julia object and + turn it into a \"Ptr\". + +"), + +("Base","unsafe_load","unsafe_load(p::Ptr{T}, i::Integer) + + Load a value of type \"T\" from the address of the ith element + (1-indexed) starting at \"p\". This is equivalent to the C + expression \"p[i-1]\". + + The \"unsafe\" prefix on this function indicates that no validation + is performed on the pointer \"p\" to ensure that it is valid. + Incorrect usage may segfault your program or return garbage + answers, in the same manner as C. + +"), + +("Base","unsafe_store!","unsafe_store!(p::Ptr{T}, x, i::Integer) + + Store a value of type \"T\" to the address of the ith element + (1-indexed) starting at \"p\". This is equivalent to the C + expression \"p[i-1] = x\". + + The \"unsafe\" prefix on this function indicates that no validation + is performed on the pointer \"p\" to ensure that it is valid. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. + +"), + +("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy \"N\" elements from a source pointer to a destination, with no + checking. The size of an element is determined by the type of the + pointers. + + The \"unsafe\" prefix on this function indicates that no validation + is performed on the pointers \"dest\" and \"src\" to ensure that + they are valid. Incorrect usage may corrupt or segfault your + program, in the same manner as C. + +"), + +("Base","unsafe_copy!","unsafe_copy!(dest::Array, do, src::Array, so, N) + + Copy \"N\" elements from a source array to a destination, starting + at offset \"so\" in the source and \"do\" in the destination + (1-indexed). + + The \"unsafe\" prefix on this function indicates that no validation + is performed to ensure that N is inbounds on either array. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. + +"), + +("Base","copy!","copy!(dest, src) + + Copy all elements from collection \"src\" to array \"dest\". + Returns \"dest\". + +"), + +("Base","copy!","copy!(dest, do, src, so, N) + + Copy \"N\" elements from collection \"src\" starting at offset + \"so\", to array \"dest\" starting at offset \"do\". Returns + \"dest\". + +"), + +("Base","pointer","pointer(array[, index]) + + Get the native address of an array or string element. Be careful to + ensure that a julia reference to \"a\" exists as long as this + pointer will be used. This function is \"unsafe\" like + \"unsafe_convert\". + + Calling \"Ref(array[, index])\" is generally preferable to this + function. + +"), + +("Base","pointer_to_array","pointer_to_array(pointer, dims[, take_ownership::Bool]) + + Wrap a native pointer as a Julia Array object. The pointer element + type determines the array element type. \"own\" optionally + specifies whether Julia should take ownership of the memory, + calling \"free\" on the pointer when the array is no longer + referenced. + +"), + +("Base","pointer_from_objref","pointer_from_objref(object_instance) + + Get the memory address of a Julia object as a \"Ptr\". The + existence of the resulting \"Ptr\" will not protect the object from + garbage collection, so you must ensure that the object remains + referenced for the whole time that the \"Ptr\" will be used. + +"), + +("Base","unsafe_pointer_to_objref","unsafe_pointer_to_objref(p::Ptr) + + Convert a \"Ptr\" to an object reference. Assumes the pointer + refers to a valid heap-allocated Julia object. If this is not the + case, undefined behavior results, hence this function is considered + \"unsafe\" and should be used with care. + +"), + +("Base","disable_sigint","disable_sigint(f::Function) + + Disable Ctrl-C handler during execution of a function, for calling + external code that is not interrupt safe. Intended to be called + using \"do\" block syntax as follows: + + disable_sigint() do + # interrupt-unsafe code + ... + end + +"), + +("Base","reenable_sigint","reenable_sigint(f::Function) + + Re-enable Ctrl-C handler during execution of a function. + Temporarily reverses the effect of \"disable_sigint\". + +"), + +("Base","systemerror","systemerror(sysfunc, iftrue) + + Raises a \"SystemError\" for \"errno\" with the descriptive string + \"sysfunc\" if \"bool\" is true + +"), + +("Base","Ptr{T}","Ptr{T} + + A memory address referring to data of type \"T\". However, there is + no guarantee that the memory is actually valid, or that it actually + represents data of the specified type. + +"), + +("Base","Ref{T}","Ref{T} + + An object that safely references data of type \"T\". This type is + guaranteed to point to valid, Julia-allocated memory of the correct + type. The underlying data is protected from freeing by the garbage + collector as long as the \"Ref\" itself is referenced. + + When passed as a \"ccall\" argument (either as a \"Ptr\" or \"Ref\" + type), a \"Ref\" object will be converted to a native pointer to + the data it references. + + There is no invalid (NULL) \"Ref\". + +"), + +("Base","Cchar","Cchar + + Equivalent to the native \"char\" c-type + +"), + +("Base","Cuchar","Cuchar + + Equivalent to the native \"unsigned char\" c-type (UInt8) + +"), + +("Base","Cshort","Cshort + + Equivalent to the native \"signed short\" c-type (Int16) + +"), + +("Base","Cushort","Cushort + + Equivalent to the native \"unsigned short\" c-type (UInt16) + +"), + +("Base","Cint","Cint + + Equivalent to the native \"signed int\" c-type (Int32) + +"), + +("Base","Cuint","Cuint + + Equivalent to the native \"unsigned int\" c-type (UInt32) + +"), + +("Base","Clong","Clong + + Equivalent to the native \"signed long\" c-type + +"), + +("Base","Culong","Culong + + Equivalent to the native \"unsigned long\" c-type + +"), + +("Base","Clonglong","Clonglong + + Equivalent to the native \"signed long long\" c-type (Int64) + +"), + +("Base","Culonglong","Culonglong + + Equivalent to the native \"unsigned long long\" c-type (UInt64) + +"), + +("Base","Cintmax_t","Cintmax_t + + Equivalent to the native \"intmax_t\" c-type (Int64) + +"), + +("Base","Cuintmax_t","Cuintmax_t + + Equivalent to the native \"uintmax_t\" c-type (UInt64) + +"), + +("Base","Csize_t","Csize_t + + Equivalent to the native \"size_t\" c-type (UInt) + +"), + +("Base","Cssize_t","Cssize_t + + Equivalent to the native \"ssize_t\" c-type + +"), + +("Base","Cptrdiff_t","Cptrdiff_t + + Equivalent to the native \"ptrdiff_t\" c-type (Int) + +"), + +("Base","Coff_t","Coff_t + + Equivalent to the native \"off_t\" c-type + +"), + +("Base","Cwchar_t","Cwchar_t + + Equivalent to the native \"wchar_t\" c-type (Int32) + +"), + +("Base","Cfloat","Cfloat + + Equivalent to the native \"float\" c-type (Float32) + +"), + +("Base","Cdouble","Cdouble + + Equivalent to the native \"double\" c-type (Float64) + +"), + +("Base","start","start(iter) -> state + + Get initial iteration state for an iterable object + +"), + +("Base","done","done(iter, state) -> Bool + + Test whether we are done iterating + +"), + +("Base","next","next(iter, state) -> item, state + + For a given iterable object and iteration state, return the current + item and the next iteration state + +"), + +("Base","zip","zip(iters...) + + For a set of iterable objects, returns an iterable of tuples, where + the \"i\"th tuple contains the \"i\"th component of each input + iterable. + + Note that \"zip()\" is its own inverse: + \"collect(zip(zip(a...)...)) == collect(a)\". + +"), + +("Base","enumerate","enumerate(iter) + + An iterator that yields \"(i, x)\" where \"i\" is an index starting + at 1, and \"x\" is the \"i\"th value from the given iterator. It's + useful when you need not only the values \"x\" over which you are + iterating, but also the index \"i\" of the iterations. + + julia> a = [\"a\", \"b\", \"c\"]; + + julia> for (index, value) in enumerate(a) + println(\"\$index \$value\") + end + 1 a + 2 b + 3 c + +"), + +("Base","rest","rest(iter, state) + + An iterator that yields the same elements as \"iter\", but starting + at the given \"state\". + +"), + +("Base","countfrom","countfrom(start=1, step=1) + + An iterator that counts forever, starting at \"start\" and + incrementing by \"step\". + +"), + +("Base","take","take(iter, n) + + An iterator that generates at most the first \"n\" elements of + \"iter\". + +"), + +("Base","drop","drop(iter, n) + + An iterator that generates all but the first \"n\" elements of + \"iter\". + +"), + +("Base","cycle","cycle(iter) + + An iterator that cycles through \"iter\" forever. + +"), + +("Base","repeated","repeated(x[, n::Int]) + + An iterator that generates the value \"x\" forever. If \"n\" is + specified, generates \"x\" that many times (equivalent to + \"take(repeated(x), n)\"). + +"), + +("Base","isempty","isempty(collection) -> Bool + + Determine whether a collection is empty (has no elements). + + julia> isempty([]) + true + + julia> isempty([1 2 3]) + false + +"), + +("Base","empty!","empty!(collection) -> collection + + Remove all elements from a \"collection\". + +"), + +("Base","length","length(collection) -> Integer + + For ordered, indexable collections, the maximum index \"i\" for + which \"getindex(collection, i)\" is valid. For unordered + collections, the number of elements. + +"), + +("Base","endof","endof(collection) -> Integer + + Returns the last index of the collection. + + julia> endof([1,2,4]) + 3 + +"), + +("Base","in","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)\". + +"), + +("Base","eltype","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 \"(key,value)\" tuple type. 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. + +"), + +("Base","indexin","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\". + +"), + +("Base","findin","findin(a, b) + + Returns the indices of elements in collection \"a\" that appear in + collection \"b\" + +"), + +("Base","unique","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\". + +"), + +("Base","reduce","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. + +"), + +("Base","reduce","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\". + +"), + +("Base","foldl","foldl(op, v0, itr) + + Like \"reduce()\", but with guaranteed left associativity. \"v0\" + will be used exactly once. + +"), + +("Base","foldl","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)\"). + +"), + +("Base","foldr","foldr(op, v0, itr) + + Like \"reduce()\", but with guaranteed right associativity. \"v0\" + will be used exactly once. + +"), + +("Base","foldr","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)\"). + +"), + +("Base","maximum","maximum(itr) + + Returns the largest element in a collection. + +"), + +("Base","maximum","maximum(A, dims) + + Compute the maximum value of an array over the given dimensions. + +"), + +("Base","maximum!","maximum!(r, A) + + Compute the maximum value of \"A\" over the singleton dimensions of + \"r\", and write results to \"r\". + +"), + +("Base","minimum","minimum(itr) + + Returns the smallest element in a collection. + +"), + +("Base","minimum","minimum(A, dims) + + Compute the minimum value of an array over the given dimensions. + +"), + +("Base","minimum!","minimum!(r, A) + + Compute the minimum value of \"A\" over the singleton dimensions of + \"r\", and write results to \"r\". + +"), + +("Base","extrema","extrema(itr) + + Compute both the minimum and maximum element in a single pass, and + return them as a 2-tuple. + +"), + +("Base","indmax","indmax(itr) -> Integer + + Returns the index of the maximum element in a collection. + +"), + +("Base","indmin","indmin(itr) -> Integer + + Returns the index of the minimum element in a collection. + +"), + +("Base","findmax","findmax(itr) -> (x, index) + + Returns the maximum element and its index. + +"), + +("Base","findmax","findmax(A, dims) -> (maxval, index) + + For an array input, returns the value and index of the maximum over + the given dimensions. + +"), + +("Base","findmin","findmin(itr) -> (x, index) + + Returns the minimum element and its index. + +"), + +("Base","findmin","findmin(A, dims) -> (minval, index) + + For an array input, returns the value and index of the minimum over + the given dimensions. + +"), + +("Base","maxabs","maxabs(itr) + + Compute the maximum absolute value of a collection of values. + +"), + +("Base","maxabs","maxabs(A, dims) + + Compute the maximum absolute values over given dimensions. + +"), + +("Base","maxabs!","maxabs!(r, A) + + Compute the maximum absolute values over the singleton dimensions + of \"r\", and write values to \"r\". + +"), + +("Base","minabs","minabs(itr) + + Compute the minimum absolute value of a collection of values. + +"), + +("Base","minabs","minabs(A, dims) + + Compute the minimum absolute values over given dimensions. + +"), + +("Base","minabs!","minabs!(r, A) + + Compute the minimum absolute values over the singleton dimensions + of \"r\", and write values to \"r\". + +"), + +("Base","sum","sum(itr) + + Returns the sum of all elements in a collection. + +"), + +("Base","sum","sum(A, dims) + + Sum elements of an array over the given dimensions. + +"), + +("Base","sum!","sum!(r, A) + + Sum elements of \"A\" over the singleton dimensions of \"r\", and + write results to \"r\". + +"), + +("Base","sum","sum(f, itr) + + Sum the results of calling function \"f\" on each element of + \"itr\". + +"), + +("Base","sumabs","sumabs(itr) + + Sum absolute values of all elements in a collection. This is + equivalent to *sum(abs(itr))* but faster. + +"), + +("Base","sumabs","sumabs(A, dims) + + Sum absolute values of elements of an array over the given + dimensions. + +"), + +("Base","sumabs!","sumabs!(r, A) + + Sum absolute values of elements of \"A\" over the singleton + dimensions of \"r\", and write results to \"r\". + +"), + +("Base","sumabs2","sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This + is equivalent to *sum(abs2(itr))* but faster. + +"), + +("Base","sumabs2","sumabs2(A, dims) + + Sum squared absolute values of elements of an array over the given + dimensions. + +"), + +("Base","sumabs2!","sumabs2!(r, A) + + Sum squared absolute values of elements of \"A\" over the singleton + dimensions of \"r\", and write results to \"r\". + +"), + +("Base","prod","prod(itr) + + Returns the product of all elements of a collection. + +"), + +("Base","prod","prod(A, dims) + + Multiply elements of an array over the given dimensions. + +"), + +("Base","prod!","prod!(r, A) + + Multiply elements of \"A\" over the singleton dimensions of \"r\", + and write results to \"r\". + +"), + +("Base","any","any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + +"), + +("Base","any","any(A, dims) + + Test whether any values along the given dimensions of an array are + true. + +"), + +("Base","any!","any!(r, A) + + Test whether any values in \"A\" along the singleton dimensions of + \"r\" are true, and write results to \"r\". + +"), + +("Base","all","all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + +"), + +("Base","all","all(A, dims) + + Test whether all values along the given dimensions of an array are + true. + +"), + +("Base","all!","all!(r, A) + + Test whether all values in \"A\" along the singleton dimensions of + \"r\" are true, and write results to \"r\". + +"), + +("Base","count","count(p, itr) -> Integer + + Count the number of elements in \"itr\" for which predicate \"p\" + returns true. + +"), + +("Base","any","any(p, itr) -> Bool + + Determine whether predicate \"p\" returns true for any elements of + \"itr\". + +"), + +("Base","all","all(p, itr) -> Bool + + Determine whether predicate \"p\" returns true for all elements of + \"itr\". + + julia> all(i->(4<=i<=6), [4,5,6]) + true + +"), + +("Base","map","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 + +"), + +("Base","map!","map!(function, collection) + + In-place version of \"map()\". + +"), + +("Base","map!","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. + +"), + +("Base","mapreduce","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","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","mapfoldl(f, op, v0, itr) + + Like \"mapreduce()\", but with guaranteed left associativity. + \"v0\" will be used exactly once. + +"), + +("Base","mapfoldl","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","mapfoldr(f, op, v0, itr) + + Like \"mapreduce()\", but with guaranteed right associativity. + \"v0\" will be used exactly once. + +"), + +("Base","mapfoldr","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","first(coll) + + Get the first element of an iterable collection. Returns the start + point of a \"Range\" even if it is empty. + +"), + +("Base","last","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. + +"), + +("Base","step","step(r) + + Get the step size of a \"Range\" object. + +"), + +("Base","collect","collect(collection) + + Return an array of all items in a collection. For associative + collections, returns (key, value) tuples. + +"), + +("Base","collect","collect(element_type, collection) + + Return an array of type \"Array{element_type,1}\" of all items in a + collection. + +"), + +("Base","issubset","issubset(a, b) +⊆(A, S) -> Bool +⊈(A, S) -> Bool +⊊(A, S) -> Bool + + Determine whether every element of \"a\" is also in \"b\", using + \"in()\". + +"), + +("Base","filter","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). + +"), + +("Base","filter!","filter!(function, collection) + + Update \"collection\", removing elements for which \"function\" is + false. For associative collections, the function is passed two + arguments (key and value). + +"), + +("Base","getindex","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, ...)\". + +"), + +("Base","setindex!","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, ...)\". + +"), + +("Base","Dict","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{ASCIIString,Int64} with 2 entries: + \"B\" => 2 + \"A\" => 1 + + Alternatively, a sequence of pair arguments may be passed. + + julia> Dict(\"A\"=>1, \"B\"=>2) + Dict{ASCIIString,Int64} with 2 entries: + \"B\" => 2 + \"A\" => 1 + +"), + +("Base","haskey","haskey(collection, key) -> Bool + + Determine whether a collection has a mapping for a given key. + +"), + +("Base","get","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. + +"), + +("Base","get","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 + +"), + +("Base","get!","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\". + +"), + +("Base","get!","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 + +"), + +("Base","getkey","getkey(collection, key, default) + + Return the key matching argument \"key\" if one exists in + \"collection\", otherwise return \"default\". + +"), + +("Base","delete!","delete!(collection, key) + + Delete the mapping for the given key in a collection, and return + the collection. + +"), + +("Base","pop!","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. + +"), + +("Base","keys","keys(collection) + + Return an iterator over all keys in a collection. + \"collect(keys(d))\" returns an array of keys. + +"), + +("Base","values","values(collection) + + Return an iterator over all values in a collection. + \"collect(values(d))\" returns an array of values. + +"), + +("Base","merge","merge(collection, others...) + + 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{ASCIIString,Float64} with 2 entries: + \"bar\" => 42.0 + \"foo\" => 0.0 + + julia> b = Dict(utf8(\"baz\") => 17, utf8(\"bar\") => 4711) + Dict{UTF8String,Int64} with 2 entries: + \"bar\" => 4711 + \"baz\" => 17 + + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + \"bar\" => 4711.0 + \"baz\" => 17.0 + \"foo\" => 0.0 + + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + \"bar\" => 42.0 + \"baz\" => 17.0 + \"foo\" => 0.0 + +"), + +("Base","merge!","merge!(collection, others...) + + Update collection with pairs from the other collections + +"), + +("Base","sizehint!","sizehint!(s, n) + + Suggest that collection \"s\" reserve capacity for at least \"n\" + elements. This can improve performance. + +"), + +("Base","Set","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","IntSet([itr]) + + Construct a sorted set of the integers generated by the given + iterable object, or an empty set. Implemented as a bit string, and + therefore designed for dense integer sets. Only non-negative + integers can be stored. If the set will be sparse (for example + holding a single very large integer), use \"Set\" instead. + +"), + +("Base","union","union(s1, s2...) +∪(s1, s2) + + Construct the union of two or more sets. Maintains order with + arrays. + +"), + +("Base","union!","union!(s, iterable) + + Union each element of \"iterable\" into set \"s\" in-place. + +"), + +("Base","intersect","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. + +"), + +("Base","setdiff","setdiff(s1, s2) + + Construct the set of elements in \"s1\" but not \"s2\". 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. + +"), + +("Base","setdiff!","setdiff!(s, iterable) + + Remove each element of \"iterable\" from set \"s\" in-place. + +"), + +("Base","symdiff","symdiff(s1, s2...) + + Construct the symmetric difference of elements in the passed in + sets or arrays. Maintains order with arrays. + +"), + +("Base","symdiff!","symdiff!(s, n) + + The set \"s\" is destructively modified to toggle the inclusion of + integer \"n\". + +"), + +("Base","symdiff!","symdiff!(s, itr) + + For each element in \"itr\", destructively toggle its inclusion in + set \"s\". + +"), + +("Base","symdiff!","symdiff!(s1, s2) + + Construct the symmetric difference of sets \"s1\" and \"s2\", + storing the result in \"s1\". + +"), + +("Base","complement","complement(s) + + Returns the set-complement of \"IntSet\" \"s\". + +"), + +("Base","complement!","complement!(s) + + Mutates \"IntSet\" \"s\" into its set-complement. + +"), + +("Base","intersect!","intersect!(s1, s2) + + 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","issubset(A, S) -> Bool +⊆(A, S) -> Bool + + True if A is a subset of or equal to S. + +"), + +("Base","push!","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])\". + +"), + +("Base","pop!","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 + +"), + +("Base","unshift!","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 + +"), + +("Base","shift!","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 + +"), + +("Base","insert!","insert!(collection, index, item) + + Insert an \"item\" into \"collection\" at the given \"index\". + \"index\" is the index of \"item\" in the resulting \"collection\". + + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 + +"), + +("Base","deleteat!","deleteat!(collection, index) + + Remove the item at the given \"index\" and return the modified + \"collection\". 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 + +"), + +("Base","deleteat!","deleteat!(collection, itr) + + Remove the items at the indices given by \"itr\", and return the + modified \"collection\". Subsequent items are shifted to fill the + resulting gap. \"itr\" must be sorted and unique. + + 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], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 + +"), + +("Base","splice!","splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. + Subsequent items are shifted down 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)\". + +"), + +("Base","splice!","splice!(collection, range[, replacement]) -> items + + Remove items in the specified index range, and return a collection + containing the removed items. Subsequent items are shifted down 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 + +"), + +("Base","resize!","resize!(collection, n) -> collection + + Resize \"collection\" 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 + +"), + +("Base","append!","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)\". + +"), + +("Base","prepend!","prepend!(collection, items) -> collection + + Insert the elements of \"items\" to the beginning of + \"collection\". + + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 + +"), + +("Base.Collections","PriorityQueue","PriorityQueue(K, V[, ord]) + + Construct a new \"PriorityQueue\", with keys of type \"K\" and + values/priorites of type \"V\". If an order is not given, the + priority queue is min-ordered using the default comparison for + \"V\". + +"), + +("Base.Collections","enqueue!","enqueue!(pq, k, v) + + Insert the a key \"k\" into a priority queue \"pq\" with priority + \"v\". + +"), + +("Base.Collections","dequeue!","dequeue!(pq) + + Remove and return the lowest priority key from a priority queue. + +"), + +("Base.Collections","peek","peek(pq) + + Return the lowest priority key from a priority queue without + removing that key from the queue. + +"), + +("Base.Collections","heapify","heapify(v[, ord]) + + Return a new vector in binary heap order, optionally using the + given ordering. + +"), + +("Base.Collections","heapify!","heapify!(v[, ord]) + + In-place \"heapify()\". + +"), + +("Base.Collections","isheap","isheap(v[, ord]) + + Return true iff an array is heap-ordered according to the given + order. + +"), + +("Base.Collections","heappush!","heappush!(v, x[, ord]) + + Given a binary heap-ordered array, push a new element \"x\", + preserving the heap property. For efficiency, this function does + not check that the array is indeed heap-ordered. + +"), + +("Base.Collections","heappop!","heappop!(v[, ord]) + + Given a binary heap-ordered array, remove and return the lowest + ordered element. For efficiency, this function does not check that + the array is indeed heap-ordered. + +"), + +("Base","nothing","nothing + + The singleton instance of type \"Void\", used by convention when + there is no value to return (as in a C \"void\" function). Can be + converted to an empty \"Nullable\" value. + +"), + +("Base","OS_NAME","OS_NAME + + A symbol representing the name of the operating system. Possible + values are \":Linux\", \":Darwin\" (OS X), or \":Windows\". + +"), + +("Base","ARGS","ARGS + + An array of the command line arguments passed to Julia, as strings. + +"), + +("Base","C_NULL","C_NULL + + The C null pointer constant, sometimes used when calling external + code. + +"), + +("Base","CPU_CORES","CPU_CORES + + The number of CPU cores in the system. + +"), + +("Base","WORD_SIZE","WORD_SIZE + + Standard word size on the current machine, in bits. + +"), + +("Base","VERSION","VERSION + + An object describing which version of Julia is in use. + +"), + +("Base","LOAD_PATH","LOAD_PATH + + An array of paths (as strings) where the \"require\" function looks + for code. + +"), + +("Base","JULIA_HOME","JULIA_HOME + + A string containing the full path to the directory containing the + \"julia\" executable. + +"), + +("Base","ANY","ANY + + Equivalent to \"Any\" for dispatch purposes, but signals the + compiler to skip code generation specialization for that field + +"), + +("Dates","Period","Period + +"), + +("Dates","Year","Year + +"), + +("Dates","Month","Month + +"), + +("Dates","Week","Week + +"), + +("Dates","Day","Day + +"), + +("Dates","Hour","Hour + +"), + +("Dates","Minute","Minute + +"), + +("Dates","Second","Second + +"), + +("Dates","Millisecond","Millisecond + + \"Period\" types represent discrete, human representations of time. + +"), + +("Dates","Instant","Instant + + \"Instant\" types represent integer-based, machine representations + of time as continuous timelines starting from an epoch. + +"), + +("Dates","UTInstant{T}","UTInstant{T} + + The \"UTInstant\" represents a machine timeline based on *UT* time + (1 day = one revolution of the earth). The \"{T}\" is a \"Period\" + parameter that indicates the resolution or precision of the + instant. + +"), + +("Dates","TimeType","TimeType + + \"TimeType\" types wrap \"Instant\" machine instances to provide + human representations of the machine instant. + +"), + +("Dates","DateTime","DateTime + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + +"), + +("Dates","Date","Date + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + +"), + +("Dates","DateTime","DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + +"), + +("Dates","DateTime","DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + +"), + +("Dates","DateTime","DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + +"), + +("Dates","DateTime","DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + +"), + +("Dates","DateTime","DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +-----------------+-----------+-----------------------------------------------------------------+ + | Code | Matches | Comment | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"y\\\" | 1996, 96 | Returns year of 1996, 0096 | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"m\\\" | 1, 01 | Matches 1 or 2-digit months | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"u\\\" | Jan | Matches abbreviated months according to the \\\"locale\\\" keyword | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"U\\\" | January | Matches full month names according to the \\\"locale\\\" keyword | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"d\\\" | 1, 01 | Matches 1 or 2-digit days | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"H\\\" | 00 | Matches hours | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"M\\\" | 00 | Matches minutes | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"S\\\" | 00 | Matches seconds | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"s\\\" | .500 | Matches milliseconds | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"e\\\" | Mon, Tues | Matches abbreviated days of the week | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"E\\\" | Monday | Matches full name days of the week | + +-----------------+-----------+-----------------------------------------------------------------+ + | \\\"yyyymmdd\\\" | 19960101 | Matches fixed-width year, month, and day | + +-----------------+-----------+-----------------------------------------------------------------+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + +"), + +("Dates","Dates","Dates.DateFormat(format::AbstractString) -> DateFormat + + Construct a date formatting object that can be passed repeatedly + for parsing similarly formatted date strings. \"format\" is a + format string in the form described above (e.g. \"\"yyyy-mm- + dd\"\"). + +"), + +("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a \"DateTime\", but passes a + \"DateFormat\" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a \"DateFormat\" object then use this + method for parsing. + +"), + +("Dates","Date","Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + +"), + +("Dates","Date","Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + +"), + +("Dates","Date","Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + +"), + +("Dates","Date","Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. + +"), + +("Dates","Date","Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date + + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. + +"), + +("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". + +"), + +("Dates","now","now() -> DateTime + + Returns a DateTime corresponding to the user's system time + including the system timezone locale. + +"), + +("Dates","now","now(::Type{UTC}) -> DateTime + + Returns a DateTime corresponding to the user's system time as + UTC/GMT. + +"), + +("Dates","eps","eps(::DateTime) -> Millisecond +eps(::Date) -> Day + + Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" + for \"Date\" values. + +"), + +("Dates","year","year(dt::TimeType) -> Int64 +month(dt::TimeType) -> Int64 +week(dt::TimeType) -> Int64 +day(dt::TimeType) -> Int64 +hour(dt::TimeType) -> Int64 +minute(dt::TimeType) -> Int64 +second(dt::TimeType) -> Int64 +millisecond(dt::TimeType) -> Int64 + + Return the field part of a Date or DateTime as an \"Int64\". + +"), + +("Dates","Year","Year(dt::TimeType) -> Year +Month(dt::TimeType) -> Month +Week(dt::TimeType) -> Week +Day(dt::TimeType) -> Day +Hour(dt::TimeType) -> Hour +Minute(dt::TimeType) -> Minute +Second(dt::TimeType) -> Second +Millisecond(dt::TimeType) -> Millisecond + + Return the field part of a Date or DateTime as a \"Period\" type. + +"), + +("Dates","yearmonth","yearmonth(dt::TimeType) -> (Int64, Int64) + + Simultaneously return the year and month parts of a Date or + DateTime. + +"), + +("Dates","monthday","monthday(dt::TimeType) -> (Int64, Int64) + + Simultaneously return the month and day parts of a Date or + DateTime. + +"), + +("Dates","yearmonthday","yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + + Simultaneously return the year, month, and day parts of a Date or + DateTime. + +"), + +("Dates","dayname","dayname(dt::TimeType; locale=\"english\") -> AbstractString + + Return the full day name corresponding to the day of the week of + the Date or DateTime in the given \"locale\". + +"), + +("Dates","dayabbr","dayabbr(dt::TimeType; locale=\"english\") -> AbstractString + + Return the abbreviated name corresponding to the day of the week of + the Date or DateTime in the given \"locale\". + +"), + +("Dates","dayofweek","dayofweek(dt::TimeType) -> Int64 + + Returns the day of the week as an \"Int64\" with \"1 = Monday, 2 = + Tuesday, etc.\". + +"), + +("Dates","dayofweekofmonth","dayofweekofmonth(dt::TimeType) -> Int + + For the day of week of \"dt\", returns which number it is in + \"dt\"'s month. So if the day of the week of \"dt\" is Monday, then + \"1 = First Monday of the month, 2 = Second Monday of the month, + etc.\" In the range 1:5. + +"), + +("Dates","daysofweekinmonth","daysofweekinmonth(dt::TimeType) -> Int + + For the day of week of \"dt\", returns the total number of that day + of the week in \"dt\"'s month. Returns 4 or 5. Useful in temporal + expressions for specifying the last day of a week in a month by + including \"dayofweekofmonth(dt) == daysofweekinmonth(dt)\" in the + adjuster function. + +"), + +("Dates","monthname","monthname(dt::TimeType; locale=\"english\") -> AbstractString + + Return the full name of the month of the Date or DateTime in the + given \"locale\". + +"), + +("Dates","monthabbr","monthabbr(dt::TimeType; locale=\"english\") -> AbstractString + + Return the abbreviated month name of the Date or DateTime in the + given \"locale\". + +"), + +("Dates","daysinmonth","daysinmonth(dt::TimeType) -> Int + + Returns the number of days in the month of \"dt\". Value will be + 28, 29, 30, or 31. + +"), + +("Dates","isleapyear","isleapyear(dt::TimeType) -> Bool + + Returns true if the year of \"dt\" is a leap year. + +"), + +("Dates","dayofyear","dayofyear(dt::TimeType) -> Int + + Returns the day of the year for \"dt\" with January 1st being day + 1. + +"), + +("Dates","daysinyear","daysinyear(dt::TimeType) -> Int + + Returns 366 if the year of \"dt\" is a leap year, otherwise returns + 365. + +"), + +("Dates","quarterofyear","quarterofyear(dt::TimeType) -> Int + + Returns the quarter that \"dt\" resides in. Range of value is 1:4. + +"), + +("Dates","dayofquarter","dayofquarter(dt::TimeType) -> Int + + Returns the day of the current quarter of \"dt\". Range of value is + 1:92. + +"), + +("Dates","trunc","trunc(dt::TimeType, ::Type{Period}) -> TimeType + + Truncates the value of \"dt\" according to the provided \"Period\" + type. E.g. if \"dt\" is \"1996-01-01T12:30:00\", then + \"trunc(dt,Day) == 1996-01-01T00:00:00\". + +"), + +("Dates","firstdayofweek","firstdayofweek(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the Monday of its week. + +"), + +("Dates","lastdayofweek","lastdayofweek(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the Sunday of its week. + +"), + +("Dates","firstdayofmonth","firstdayofmonth(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the first day of its month. + +"), + +("Dates","lastdayofmonth","lastdayofmonth(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the last day of its month. + +"), + +("Dates","firstdayofyear","firstdayofyear(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the first day of its year. + +"), + +("Dates","lastdayofyear","lastdayofyear(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the last day of its year. + +"), + +("Dates","firstdayofquarter","firstdayofquarter(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the first day of its quarter. + +"), + +("Dates","lastdayofquarter","lastdayofquarter(dt::TimeType) -> TimeType + + Adjusts \"dt\" to the last day of its quarter. + +"), + +("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts \"dt\" to the next day of week corresponding to \"dow\" + with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows + the current \"dt\" to be considered as the next \"dow\", allowing + for no adjustment to occur. + +"), + +("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts \"dt\" to the previous day of week corresponding to \"dow\" + with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows + the current \"dt\" to be considered as the previous \"dow\", + allowing for no adjustment to occur. + +"), + +("Dates","tofirst","tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + + Adjusts \"dt\" to the first \"dow\" of its month. Alternatively, + \"of=Year\" will adjust to the first \"dow\" of the year. + +"), + +("Dates","tolast","tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + + Adjusts \"dt\" to the last \"dow\" of its month. Alternatively, + \"of=Year\" will adjust to the last \"dow\" of the year. + +"), + +("Dates","tonext","tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts \"dt\" by iterating at most \"limit\" iterations by + \"step\" increments until \"func\" returns true. \"func\" must take + a single \"TimeType\" argument and return a \"Bool\". \"same\" + allows \"dt\" to be considered in satisfying \"func\". \"negate\" + will make the adjustment process terminate when \"func\" returns + false instead of true. + +"), + +("Dates","toprev","toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + + Adjusts \"dt\" by iterating at most \"limit\" iterations by + \"step\" increments until \"func\" returns true. \"func\" must take + a single \"TimeType\" argument and return a \"Bool\". \"same\" + allows \"dt\" to be considered in satisfying \"func\". \"negate\" + will make the adjustment process terminate when \"func\" returns + false instead of true. + +"), + +("Dates","recur{T<:TimeType}","recur{T<:TimeType}(func::Function, dr::StepRange{T};negate=false, limit=10000) -> Vector{T} + + \"func\" takes a single TimeType argument and returns a \"Bool\" + indicating whether the input should be \"included\" in the final + set. \"recur\" applies \"func\" over each element in the range of + \"dr\", including those elements for which \"func\" returns + \"true\" in the resulting Array, unless \"negate=true\", then only + elements where \"func\" returns \"false\" are included. + +"), + +("Dates","Year","Year(v) +Month(v) +Week(v) +Day(v) +Hour(v) +Minute(v) +Second(v) +Millisecond(v) + + Construct a \"Period\" type with the given \"v\" value. Input must + be losslessly convertible to an \"Int64\". + +"), + +("Dates","default","default(p::Period) -> Period + + Returns a sensible \"default\" value for the input Period by + returning \"one(p)\" for Year, Month, and Day, and \"zero(p)\" for + Hour, Minute, Second, and Millisecond. + +"), + +("Dates","today","today() -> Date + + Returns the date portion of \"now()\". + +"), + +("Dates","unix2datetime","unix2datetime(x) -> DateTime + + Takes the number of seconds since unix epoch + \"1970-01-01T00:00:00\" and converts to the corresponding DateTime. + +"), + +("Dates","datetime2unix","datetime2unix(dt::DateTime) -> Float64 + + Takes the given DateTime and returns the number of seconds since + the unix epoch as a \"Float64\". + +"), + +("Dates","julian2datetime","julian2datetime(julian_days) -> DateTime + + Takes the number of Julian calendar days since epoch + \"-4713-11-24T12:00:00\" and returns the corresponding DateTime. + +"), + +("Dates","datetime2julian","datetime2julian(dt::DateTime) -> Float64 + + Takes the given DateTime and returns the number of Julian calendar + days since the julian epoch as a \"Float64\". + +"), + +("Dates","rata2datetime","rata2datetime(days) -> DateTime + + Takes the number of Rata Die days since epoch + \"0000-12-31T00:00:00\" and returns the corresponding DateTime. + +"), + +("Dates","datetime2rata","datetime2rata(dt::TimeType) -> Int64 + + Returns the number of Rata Die days since epoch from the given Date + or DateTime. + +"), + +("Base","pwd","pwd() -> AbstractString + + Get the current working directory. + +"), + +("Base","cd","cd(dir::AbstractString) + + Set the current working directory. + +"), + +("Base","cd","cd(f[, dir]) + + Temporarily changes the current working directory (HOME if not + specified) and applies function f before returning. + +"), + +("Base","readdir","readdir([dir]) -> Vector{ByteString} + + Returns the files and directories in the directory *dir* (or the + current working directory if not given). + +"), + +("Base","mkdir","mkdir(path[, mode]) + + Make a new directory with name \"path\" and permissions \"mode\". + \"mode\" defaults to 0o777, modified by the current file creation + mask. + +"), + +("Base","mkpath","mkpath(path[, mode]) + + Create all directories in the given \"path\", with permissions + \"mode\". \"mode\" defaults to 0o777, modified by the current file + creation mask. + +"), + +("Base","symlink","symlink(target, link) + + Creates a symbolic link to \"target\" with the name \"link\". + + Note: This function raises an error under operating systems that + do not support soft symbolic links, such as Windows XP. + +"), + +("Base","readlink","readlink(path) -> AbstractString + + Returns the value of a symbolic link \"path\". + +"), + +("Base","chmod","chmod(path, mode) + + Change the permissions mode of \"path\" to \"mode\". Only integer + \"mode\"s (e.g. 0o777) are currently supported. + +"), + +("Base","stat","stat(file) + + Returns a structure whose fields contain information about the + file. The fields of the structure are: + + +-----------+------------------------------------------------------------------------+ + | size | The size (in bytes) of the file | + +-----------+------------------------------------------------------------------------+ + | device | ID of the device that contains the file | + +-----------+------------------------------------------------------------------------+ + | inode | The inode number of the file | + +-----------+------------------------------------------------------------------------+ + | mode | The protection mode of the file | + +-----------+------------------------------------------------------------------------+ + | nlink | The number of hard links to the file | + +-----------+------------------------------------------------------------------------+ + | uid | The user id of the owner of the file | + +-----------+------------------------------------------------------------------------+ + | gid | The group id of the file owner | + +-----------+------------------------------------------------------------------------+ + | rdev | If this file refers to a device, the ID of the device it refers to | + +-----------+------------------------------------------------------------------------+ + | blksize | The file-system preferred block size for the file | + +-----------+------------------------------------------------------------------------+ + | blocks | The number of such blocks allocated | + +-----------+------------------------------------------------------------------------+ + | mtime | Unix timestamp of when the file was last modified | + +-----------+------------------------------------------------------------------------+ + | ctime | Unix timestamp of when the file was created | + +-----------+------------------------------------------------------------------------+ + +"), + +("Base","lstat","lstat(file) + + Like stat, but for symbolic links gets the info for the link itself + rather than the file it refers to. This function must be called on + a file path rather than a file object or a file descriptor. + +"), + +("Base","ctime","ctime(file) + + Equivalent to stat(file).ctime + +"), + +("Base","mtime","mtime(file) + + Equivalent to stat(file).mtime + +"), + +("Base","filemode","filemode(file) + + Equivalent to stat(file).mode + +"), + +("Base","filesize","filesize(path...) + + Equivalent to stat(file).size + +"), + +("Base","uperm","uperm(file) + + Gets the permissions of the owner of the file as a bitfield of + + +------+-----------------------+ + | 01 | Execute Permission | + +------+-----------------------+ + | 02 | Write Permission | + +------+-----------------------+ + | 04 | Read Permission | + +------+-----------------------+ + + For allowed arguments, see \"stat\". + +"), + +("Base","gperm","gperm(file) + + Like uperm but gets the permissions of the group owning the file + +"), + +("Base","operm","operm(file) + + Like uperm but gets the permissions for people who neither own the + file nor are a member of the group owning the file + +"), + +("Base","cp","cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + + Copy the file, link, or directory from *src* to *dest*. + \"remove_destination=true\" will first remove an existing *dst*. + + If *follow_symlinks=false*, and src is a symbolic link, dst will be + created as a symbolic link. If *follow_symlinks=true* and src is a + symbolic link, dst will be a copy of the file or directory *src* + refers to. + +"), + +("Base","download","download(url[, localfile]) + + Download a file from the given url, optionally renaming it to the + given local file name. Note that this function relies on the + availability of external tools such as \"curl\", \"wget\" or + \"fetch\" to download the file and is provided for convenience. For + production use or situations in which more options are need, please + use a package that provides the desired functionality instead. + +"), + +("Base","mv","mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + + Move the file, link, or directory from *src* to *dest*. + \"remove_destination=true\" will first remove an existing *dst*. + +"), + +("Base","rm","rm(path::AbstractString; recursive=false) + + Delete the file, link, or empty directory at the given path. If + \"recursive=true\" is passed and the path is a directory, then all + contents are removed recursively. + +"), + +("Base","touch","touch(path::AbstractString) + + Update the last-modified timestamp on a file to the current time. + +"), + +("Base","tempname","tempname() + + Generate a unique temporary file path. + +"), + +("Base","tempdir","tempdir() + + Obtain the path of a temporary directory (possibly shared with + other processes). + +"), + +("Base","mktemp","mktemp([parent=tempdir()]) + + Returns \"(path, io)\", where \"path\" is the path of a new + temporary file in \"parent\" and \"io\" is an open file object for + this path. + +"), + +("Base","mktempdir","mktempdir([parent=tempdir()]) + + Create a temporary directory in the \"parent\" directory and return + its path. + +"), + +("Base","isblockdev","isblockdev(path) -> Bool + + Returns \"true\" if \"path\" is a block device, \"false\" + otherwise. + +"), + +("Base","ischardev","ischardev(path) -> Bool + + Returns \"true\" if \"path\" is a character device, \"false\" + otherwise. + +"), + +("Base","isdir","isdir(path) -> Bool + + Returns \"true\" if \"path\" is a directory, \"false\" otherwise. + +"), + +("Base","isexecutable","isexecutable(path) -> Bool + + Returns \"true\" if the current user has permission to execute + \"path\", \"false\" otherwise. + +"), + +("Base","isfifo","isfifo(path) -> Bool + + Returns \"true\" if \"path\" is a FIFO, \"false\" otherwise. + +"), + +("Base","isfile","isfile(path) -> Bool + + Returns \"true\" if \"path\" is a regular file, \"false\" + otherwise. + +"), + +("Base","islink","islink(path) -> Bool + + Returns \"true\" if \"path\" is a symbolic link, \"false\" + otherwise. + +"), + +("Base","ismount","ismount(path) -> Bool + + Returns \"true\" if \"path\" is a mount point, \"false\" otherwise. + +"), + +("Base","ispath","ispath(path) -> Bool + + Returns \"true\" if \"path\" is a valid filesystem path, \"false\" + otherwise. + +"), + +("Base","isreadable","isreadable(path) -> Bool + + Returns \"true\" if the current user has permission to read + \"path\", \"false\" otherwise. + +"), + +("Base","issetgid","issetgid(path) -> Bool + + Returns \"true\" if \"path\" has the setgid flag set, \"false\" + otherwise. + +"), + +("Base","issetuid","issetuid(path) -> Bool + + Returns \"true\" if \"path\" has the setuid flag set, \"false\" + otherwise. + +"), + +("Base","issocket","issocket(path) -> Bool + + Returns \"true\" if \"path\" is a socket, \"false\" otherwise. + +"), + +("Base","issticky","issticky(path) -> Bool + + Returns \"true\" if \"path\" has the sticky bit set, \"false\" + otherwise. + +"), + +("Base","iswritable","iswritable(path) -> Bool + + Returns \"true\" if the current user has permission to write to + \"path\", \"false\" otherwise. + +"), + +("Base","homedir","homedir() -> AbstractString + + Return the current user's home directory. + +"), + +("Base","dirname","dirname(path::AbstractString) -> AbstractString + + Get the directory part of a path. + +"), + +("Base","basename","basename(path::AbstractString) -> AbstractString + + Get the file name part of a path. + +"), + +("Base","@__FILE__","@__FILE__() -> AbstractString + + \"@__FILE__\" expands to a string with the absolute path and file + name of the script being run. Returns \"nothing\" if run from a + REPL or an empty string if evaluated by \"julia -e \". + +"), + +("Base","isabspath","isabspath(path::AbstractString) -> Bool + + Determines whether a path is absolute (begins at the root + directory). + +"), + +("Base","isdirpath","isdirpath(path::AbstractString) -> Bool + + Determines whether a path refers to a directory (for example, ends + with a path separator). + +"), + +("Base","joinpath","joinpath(parts...) -> AbstractString + + Join path components into a full path. If some argument is an + absolute path, then prior components are dropped. + +"), + +("Base","abspath","abspath(path::AbstractString) -> AbstractString + + Convert a path to an absolute path by adding the current directory + if necessary. + +"), + +("Base","normpath","normpath(path::AbstractString) -> AbstractString + + Normalize a path, removing \".\" and \"..\" entries. + +"), + +("Base","realpath","realpath(path::AbstractString) -> AbstractString + + Canonicalize a path by expanding symbolic links and removing \".\" + and \"..\" entries. + +"), + +("Base","relpath","relpath(path::AbstractString, startpath::AbstractString = \".\") -> AbstractString + + Return a relative filepath to path either from the current + directory or from an optional start directory. This is a path + computation: the filesystem is not accessed to confirm the + existence or nature of path or startpath. + +"), + +("Base","expanduser","expanduser(path::AbstractString) -> AbstractString + + On Unix systems, replace a tilde character at the start of a path + with the current user's home directory. + +"), + +("Base","splitdir","splitdir(path::AbstractString) -> (AbstractString, AbstractString) + + Split a path into a tuple of the directory name and file name. + +"), + +("Base","splitdrive","splitdrive(path::AbstractString) -> (AbstractString, AbstractString) + + On Windows, split a path into the drive letter part and the path + part. On Unix systems, the first component is always the empty + string. + +"), + +("Base","splitext","splitext(path::AbstractString) -> (AbstractString, AbstractString) + + If the last component of a path contains a dot, split the path into + everything before the dot and everything including and after the + dot. Otherwise, return a tuple of the argument unmodified and the + empty string. + +"), + + +("Base","STDOUT","STDOUT + + Global variable referring to the standard out stream. + +"), + +("Base","STDERR","STDERR + + Global variable referring to the standard error stream. + +"), + +("Base","STDIN","STDIN + + Global variable referring to the standard input stream. + +"), + +("Base","open","open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + +"), + +("Base","open","open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of \"mode\" + correspond to those from \"fopen(3)\" or Perl \"open\", and are + equivalent to setting the following boolean groups: + + +------+-----------------------------------+ + | r | read | + +------+-----------------------------------+ + | r+ | read, write | + +------+-----------------------------------+ + | w | write, create, truncate | + +------+-----------------------------------+ + | w+ | read, write, create, truncate | + +------+-----------------------------------+ + | a | write, create, append | + +------+-----------------------------------+ + | a+ | read, write, create, append | + +------+-----------------------------------+ + +"), + +("Base","open","open(f::function, args...) + + Apply the function \"f\" to the result of \"open(args...)\" and + close the resulting file descriptor upon completion. + + **Example**: \"open(readall, \"file.txt\")\" + +"), + +("Base","IOBuffer","IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + +"), + +("Base","IOBuffer","IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + +"), + +("Base","IOBuffer","IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + +"), + +("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. + +"), + +("Base","takebuf_array","takebuf_array(b::IOBuffer) + + Obtain the contents of an \"IOBuffer\" as an array, without + copying. Afterwards, the IOBuffer is reset to its initial state. + +"), + +("Base","takebuf_string","takebuf_string(b::IOBuffer) + + Obtain the contents of an \"IOBuffer\" as a string, without + copying. Afterwards, the IOBuffer is reset to its initial state. + +"), + +("Base","fdio","fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + + Create an \"IOStream\" object from an integer file descriptor. If + \"own\" is true, closing this object will close the underlying + descriptor. By default, an \"IOStream\" is closed when it is + garbage collected. \"name\" allows you to associate the descriptor + with a named file. + +"), + +("Base","flush","flush(stream) + + Commit all currently buffered writes to the given stream. + +"), + +("Base","close","close(stream) + + Close an I/O stream. Performs a \"flush\" first. + +"), + +("Base","write","write(stream, x) + + Write the canonical binary representation of a value to the given + stream. + +"), + +("Base","read","read(stream, type) + + Read a value of the given type from a stream, in canonical binary + representation. + +"), + +("Base","read","read(stream, type, dims) + + Read a series of values of the given type from a stream, in + canonical binary representation. \"dims\" is either a tuple or a + series of integer arguments specifying the size of \"Array\" to + return. + +"), + +("Base","read!","read!(stream, array::Array) + + Read binary data from a stream, filling in the argument \"array\". + +"), + +("Base","readbytes!","readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + + Read at most \"nb\" bytes from the stream into \"b\", returning the + number of bytes read (increasing the size of \"b\" as needed). + +"), + +("Base","readbytes","readbytes(stream, nb=typemax(Int)) + + Read at most \"nb\" bytes from the stream, returning a + \"Vector{UInt8}\" of the bytes read. + +"), + +("Base","position","position(s) + + Get the current position of a stream. + +"), + +("Base","seek","seek(s, pos) + + Seek a stream to the given position. + +"), + +("Base","seekstart","seekstart(s) + + Seek a stream to its beginning. + +"), + +("Base","seekend","seekend(s) + + Seek a stream to its end. + +"), + +("Base","skip","skip(s, offset) + + Seek a stream relative to the current position. + +"), + +("Base","mark","mark(s) + + Add a mark at the current position of stream \"s\". Returns the + marked position. + + See also \"unmark()\", \"reset()\", \"ismarked()\" + +"), + +("Base","unmark","unmark(s) + + Remove a mark from stream \"s\". Returns \"true\" if the stream was + marked, \"false\" otherwise. + + See also \"mark()\", \"reset()\", \"ismarked()\" + +"), + +("Base","reset","reset(s) + + Reset a stream \"s\" to a previously marked position, and remove + the mark. Returns the previously marked position. Throws an error + if the stream is not marked. + + See also \"mark()\", \"unmark()\", \"ismarked()\" + +"), + +("Base","ismarked","ismarked(s) + + Returns true if stream \"s\" is marked. + + See also \"mark()\", \"unmark()\", \"reset()\" + +"), + +("Base","eof","eof(stream) -> Bool + + Tests whether an I/O stream is at end-of-file. If the stream is not + yet exhausted, this function will block to wait for more data if + necessary, and then return \"false\". Therefore it is always safe + to read one byte after seeing \"eof\" return \"false\". \"eof\" + will return \"false\" as long as buffered data is still available, + even if the remote end of a connection is closed. + +"), + +("Base","isreadonly","isreadonly(stream) -> Bool + + Determine whether a stream is read-only. + +"), + +("Base","isopen","isopen(stream) -> Bool + + Determine whether a stream is open (i.e. has not been closed yet). + If the connection has been closed remotely (in case of e.g. a + socket), \"isopen\" will return \"false\" even though buffered data + may still be available. Use \"eof\" to check if necessary. + +"), + +("Base","serialize","serialize(stream, value) + + Write an arbitrary value to a stream in an opaque format, such that + it can be read back by \"deserialize\". The read-back value will be + as identical as possible to the original. In general, this process + will not work if the reading and writing are done by different + versions of Julia, or an instance of Julia with a different system + image. + +"), + +("Base","deserialize","deserialize(stream) + + Read a value written by \"serialize\". + +"), + +("Base","print_escaped","print_escaped(io, str::AbstractString, esc::AbstractString) + + General escaping of traditional C and Unicode escape sequences, + plus any characters in esc are also escaped (with a backslash). + +"), + +("Base","print_unescaped","print_unescaped(io, s::AbstractString) + + General unescaping of traditional C and Unicode escape sequences. + Reverse of \"print_escaped()\". + +"), + +("Base","print_joined","print_joined(io, items, delim[, last]) + + Print elements of \"items\" to \"io\" with \"delim\" between them. + If \"last\" is specified, it is used as the final delimiter instead + of \"delim\". + +"), + +("Base","print_shortest","print_shortest(io, x) + + Print the shortest possible representation, with the minimum number + of consecutive non-zero digits, of number \"x\", ensuring that it + would parse to the exact same number. + +"), + +("Base","fd","fd(stream) + + Returns the file descriptor backing the stream or file. Note that + this function only applies to synchronous *File*'s and *IOStream*'s + not to any of the asynchronous streams. + +"), + +("Base","redirect_stdout","redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be + redirected. Returns a tuple (rd,wr) representing the pipe ends. + Data written to STDOUT may now be read from the rd end of the pipe. + The wr end is given for convenience in case the old STDOUT object + was cached by the user and needs to be replaced elsewhere. + +"), + +("Base","redirect_stdout","redirect_stdout(stream) + + Replace STDOUT by stream for all C and julia level output to + STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + +"), + +("Base","redirect_stderr","redirect_stderr([stream]) + + Like redirect_stdout, but for STDERR + +"), + +("Base","redirect_stdin","redirect_stdin([stream]) + + Like redirect_stdout, but for STDIN. Note that the order of the + return tuple is still (rd,wr), i.e. data to be read from STDIN, may + be written to wr. + +"), + +("Base","readchomp","readchomp(x) + + Read the entirety of x as a string but remove trailing newlines. + Equivalent to chomp(readall(x)). + +"), + +("Base","truncate","truncate(file, n) + + Resize the file or buffer given by the first argument to exactly + *n* bytes, filling previously unallocated space with '\\0' if the + file or buffer is grown + +"), + +("Base","skipchars","skipchars(stream, predicate; linecomment::Char) + + Advance the stream until before the first character for which + \"predicate\" returns false. For example \"skipchars(stream, + isspace)\" will skip all whitespace. If keyword argument + \"linecomment\" is specified, characters from that character + through the end of a line will also be skipped. + +"), + +("Base","countlines","countlines(io[, eol::Char]) + + Read io until the end of the stream/file and count the number of + non-empty lines. To specify a file pass the filename as the first + argument. EOL markers other than '\\n' are supported by passing + them as the second argument. + +"), + +("Base","PipeBuffer","PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. + Seeking and truncating are not supported. See IOBuffer for the + available constructors. + +"), + +("Base","PipeBuffer","PipeBuffer(data::Vector{UInt8}[, maxsize]) + + Create a PipeBuffer to operate on a data vector, optionally + specifying a size beyond which the underlying Array may not be + grown. + +"), + +("Base","readavailable","readavailable(stream) + + Read all available data on the stream, blocking the task only if no + data is available. The result is a \"Vector{UInt8,1}\". + +"), + +("Base","show","show(x) + + Write an informative text representation of a value to the current + output stream. New types should overload \"show(io, x)\" where the + first argument is a stream. The representation used by \"show\" + generally includes Julia-specific formatting and type information. + +"), + +("Base","showcompact","showcompact(x) + + Show a more compact representation of a value. This is used for + printing array elements. If a new type has a different compact + representation, it should overload \"showcompact(io, x)\" where the + first argument is a stream. + +"), + +("Base","showall","showall(x) + + Similar to \"show\", except shows all elements of arrays. + +"), + +("Base","summary","summary(x) + + Return a string giving a brief description of a value. By default + returns \"string(typeof(x))\". For arrays, returns strings like + \"2x2 Float64 Array\". + +"), + +("Base","print","print(x) + + Write (to the default output stream) a canonical (un-decorated) + text representation of a value if there is one, otherwise call + \"show\". The representation used by \"print\" includes minimal + formatting and tries to avoid Julia-specific details. + +"), + +("Base","println","println(x) + + Print (using \"print()\") \"x\" followed by a newline. + +"), + +("Base","print_with_color","print_with_color(color::Symbol[, io], strings...) + + Print strings in a color specified as a symbol, for example + \":red\" or \":blue\". + +"), + +("Base","info","info(msg) + + Display an informational message. + +"), + +("Base","warn","warn(msg) + + Display a warning. + +"), + +("Base","@printf","@printf([io::IOStream], \"%Fmt\", args...) + + Print arg(s) using C \"printf()\" style format specification + string. Optionally, an IOStream may be passed as the first argument + to redirect output. + +"), + +("Base","@sprintf","@sprintf(\"%Fmt\", args...) + + Return \"@printf\" formatted output as string. + +"), + +("Base","sprint","sprint(f::Function, args...) + + Call the given function with an I/O stream and the supplied extra + arguments. Everything written to this I/O stream is returned as a + string. + +"), + +("Base","showerror","showerror(io, e) + + Show a descriptive representation of an exception object. + +"), + +("Base","dump","dump(x) + + Show all user-visible structure of a value. + +"), + +("Base","xdump","xdump(x) + + Show all structure of a value, including all fields of objects. + +"), + +("Base","readall","readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + +"), + +("Base","readall","readall(filename::AbstractString) + + Open \"filename\", read the entire contents as a string, then close + the file. Equivalent to \"open(readall, filename)\". + +"), + +("Base","readline","readline(stream=STDIN) + + Read a single line of text, including a trailing newline character + (if one is reached before the end of the input), from the given + \"stream\" (defaults to \"STDIN\"), + +"), + +("Base","readuntil","readuntil(stream, delim) + + Read a string, up to and including the given delimiter byte. + +"), + +("Base","readlines","readlines(stream) + + Read all lines as an array. + +"), + +("Base","eachline","eachline(stream) + + Create an iterable object that will yield each line from a stream. + +"), + +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + +"), + +("Base","readdlm","readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + +"), + +("Base","readdlm","readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"\\n\". + +"), + +("Base","readdlm","readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"\\n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + +"), + +("Base","readdlm","readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"\\n\". + +"), + +("Base","readdlm","readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"\\n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + +"), + +("Base","writedlm","writedlm(f, A, delim='\\t') + + Write \"A\" (a vector, matrix or an iterable collection of iterable + rows) as text to \"f\" (either a filename string or an \"IO\" + stream) using the given delimeter \"delim\" (which defaults to tab, + but can be any printable Julia object, typically a \"Char\" or + \"AbstractString\"). + + For example, two vectors \"x\" and \"y\" of the same length can be + written as two columns of tab-delimited text to \"f\" by either + \"writedlm(f, [x y])\" or by \"writedlm(f, zip(x, y))\". + +"), + +("Base","readcsv","readcsv(source, [T::Type]; options...) + + Equivalent to \"readdlm\" with \"delim\" set to comma. + +"), + +("Base","writecsv","writecsv(filename, A) + + Equivalent to \"writedlm\" with \"delim\" set to comma. + +"), + +("Base","Base64EncodePipe","Base64EncodePipe(ostream) + + Returns a new write-only I/O stream, which converts any bytes + written to it into base64-encoded ASCII bytes written to + \"ostream\". Calling \"close\" on the \"Base64Pipe\" stream is + necessary to complete the encoding (but does not close + \"ostream\"). + +"), + +("Base","Base64DecodePipe","Base64DecodePipe(istream) + + Returns a new read-only I/O stream, which decodes base64-encoded + data read from \"istream\". + +"), + +("Base","base64encode","base64encode(writefunc, args...) +base64encode(args...) + + Given a \"write\"-like function \"writefunc\", which takes an I/O + stream as its first argument, \"base64(writefunc, args...)\" calls + \"writefunc\" to write \"args...\" to a base64-encoded string, and + returns the string. \"base64(args...)\" is equivalent to + \"base64(write, args...)\": it converts its arguments into bytes + using the standard \"write\" functions and returns the + base64-encoded string. + +"), + +("Base","base64decode","base64decode(string) + + Decodes the base64-encoded \"string\" and returns a + \"Vector{UInt8}\" of the decoded bytes. + +"), + +("Base","display","display(x) +display(d::Display, x) +display(mime, x) +display(d::Display, mime, x) + + Display \"x\" using the topmost applicable display in the display + stack, typically using the richest supported multimedia output for + \"x\", with plain-text \"STDOUT\" output as a fallback. The + \"display(d, x)\" variant attempts to display \"x\" on the given + display \"d\" only, throwing a \"MethodError\" if \"d\" cannot + display objects of this type. + + There are also two variants with a \"mime\" argument (a MIME type + string, such as \"\"image/png\"\"), which attempt to display \"x\" + using the requested MIME type *only*, throwing a \"MethodError\" if + this type is not supported by either the display(s) or by \"x\". + With these variants, one can also supply the \"raw\" data in the + requested MIME type by passing \"x::AbstractString\" (for MIME + types with text-based storage, such as text/html or + application/postscript) or \"x::Vector{UInt8}\" (for binary MIME + types). + +"), + +("Base","redisplay","redisplay(x) +redisplay(d::Display, x) +redisplay(mime, x) +redisplay(d::Display, mime, x) + + By default, the \"redisplay\" functions simply call \"display\". + However, some display backends may override \"redisplay\" to modify + an existing display of \"x\" (if any). Using \"redisplay\" is + also a hint to the backend that \"x\" may be redisplayed several + times, and the backend may choose to defer the display until (for + example) the next interactive prompt. + +"), + +("Base","displayable","displayable(mime) -> Bool +displayable(d::Display, mime) -> Bool + + Returns a boolean value indicating whether the given \"mime\" type + (string) is displayable by any of the displays in the current + display stack, or specifically by the display \"d\" in the second + variant. + +"), + +("Base","writemime","writemime(stream, mime, x) + + The \"display\" functions ultimately call \"writemime\" in order to + write an object \"x\" as a given \"mime\" type to a given I/O + \"stream\" (usually a memory buffer), if possible. In order to + provide a rich multimedia representation of a user-defined type + \"T\", it is only necessary to define a new \"writemime\" method + for \"T\", via: \"writemime(stream, ::MIME\"mime\", x::T) = ...\", + where \"mime\" is a MIME-type string and the function body calls + \"write\" (or similar) to write that representation of \"x\" to + \"stream\". (Note that the \"MIME\"\"\" notation only supports + literal strings; to construct \"MIME\" types in a more flexible + manner use \"MIME{symbol(\"\")}\".) + + For example, if you define a \"MyImage\" type and know how to write + it to a PNG file, you could define a function \"writemime(stream, + ::MIME\"image/png\", x::MyImage) = ...`\" to allow your images to + be displayed on any PNG-capable \"Display\" (such as IJulia). As + usual, be sure to \"import Base.writemime\" in order to add new + methods to the built-in Julia function \"writemime\". + + Technically, the \"MIME\"mime\"\" macro defines a singleton type + for the given \"mime\" string, which allows us to exploit Julia's + dispatch mechanisms in determining how to display objects of any + given type. + +"), + +("Base","mimewritable","mimewritable(mime, x) + + Returns a boolean value indicating whether or not the object \"x\" + can be written as the given \"mime\" type. (By default, this is + determined automatically by the existence of the corresponding + \"writemime\" function for \"typeof(x)\".) + +"), + +("Base","reprmime","reprmime(mime, x) + + Returns an \"AbstractString\" or \"Vector{UInt8}\" containing the + representation of \"x\" in the requested \"mime\" type, as written + by \"writemime\" (throwing a \"MethodError\" if no appropriate + \"writemime\" is available). An \"AbstractString\" is returned for + MIME types with textual representations (such as \"\"text/html\"\" + or \"\"application/postscript\"\"), whereas binary data is returned + as \"Vector{UInt8}\". (The function \"istext(mime)\" returns + whether or not Julia treats a given \"mime\" type as text.) + + As a special case, if \"x\" is an \"AbstractString\" (for textual + MIME types) or a \"Vector{UInt8}\" (for binary MIME types), the + \"reprmime\" function assumes that \"x\" is already in the + requested \"mime\" format and simply returns \"x\". + +"), + +("Base","stringmime","stringmime(mime, x) + + Returns an \"AbstractString\" containing the representation of + \"x\" in the requested \"mime\" type. This is similar to + \"reprmime\" except that binary data is base64-encoded as an ASCII + string. + +"), + +("Base","pushdisplay","pushdisplay(d::Display) + + Pushes a new display \"d\" on top of the global display-backend + stack. Calling \"display(x)\" or \"display(mime, x)\" will display + \"x\" on the topmost compatible backend in the stack (i.e., the + topmost backend that does not throw a \"MethodError\"). + +"), + +("Base","popdisplay","popdisplay() +popdisplay(d::Display) + + Pop the topmost backend off of the display-backend stack, or the + topmost copy of \"d\" in the second variant. + +"), + +("Base","TextDisplay","TextDisplay(stream) + + Returns a \"TextDisplay <: Display\", which can display any object + as the text/plain MIME type (only), writing the text representation + to the given I/O stream. (The text representation is the same as + the way an object is printed in the Julia REPL.) + +"), + +("Base","istext","istext(m::MIME) + + Determine whether a MIME type is text data. + +"), + +("Base","mmap_array","mmap_array(type, dims, stream[, offset]) + + Create an \"Array\" whose values are linked to a file, using + memory-mapping. This provides a convenient way of working with data + too large to fit in the computer's memory. + + The type determines how the bytes of the array are interpreted. + Note that the file must be stored in binary format, and no format + conversions are possible (this is a limitation of operating + systems, not Julia). + + \"dims\" is a tuple specifying the size of the array. + + The file is passed via the stream argument. When you initialize + the stream, use \"\"r\"\" for a \"read-only\" array, and \"\"w+\"\" + to create a new array used to write values to disk. + + Optionally, you can specify an offset (in bytes) if, for example, + you want to skip over a header in the file. The default value for + the offset is the current stream position. + + For example, the following code: + + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open(\"/tmp/mmap.bin\", \"w+\") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) + + # Test by reading it back in + s = open(\"/tmp/mmap.bin\") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) + + creates a \"m\"-by-\"n\" \"Matrix{Int}\", linked to the file + associated with stream \"s\". + + A more portable file would need to encode the word size---32 bit or + 64 bit---and endianness information in the header. In practice, + consider encoding binary data using standard formats like HDF5 + (which can be used with memory-mapping). + +"), + +("Base","mmap_bitarray","mmap_bitarray([type], dims, stream[, offset]) + + Create a \"BitArray\" whose values are linked to a file, using + memory-mapping; it has the same purpose, works in the same way, and + has the same arguments, as \"mmap_array()\", but the byte + representation is different. The \"type\" parameter is optional, + and must be \"Bool\" if given. + + **Example**: \"B = mmap_bitarray((25,30000), s)\" + + This would create a 25-by-30000 \"BitArray\", linked to the file + associated with stream \"s\". + +"), + +("Base","msync","msync(array) + + Forces synchronization between the in-memory version of a memory- + mapped \"Array\" or \"BitArray\" and the on-disk version. + +"), + +("Base","connect","connect([host], port) -> TcpSocket + + Connect to the host \"host\" on port \"port\" + +"), + +("Base","connect","connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at \"path\" + +"), + +("Base","listen","listen([addr], port) -> TcpServer + + Listen on port on the address specified by \"addr\". By default + this listens on localhost only. To listen on all interfaces pass, + \"IPv4(0)\" or \"IPv6(0)\" as appropriate. + +"), + +("Base","listen","listen(path) -> PipeServer + + Listens on/Creates a Named Pipe/Domain Socket + +"), + +("Base","getaddrinfo","getaddrinfo(host) + + Gets the IP address of the \"host\" (may have to do a DNS lookup) + +"), + +("Base","parseip","parseip(addr) + + Parse a string specifying an IPv4 or IPv6 ip address. + +"), + +("Base","IPv4","IPv4(host::Integer) -> IPv4 + + Returns IPv4 object from ip address formatted as Integer + +"), + +("Base","IPv6","IPv6(host::Integer) -> IPv6 + + Returns IPv6 object from ip address formatted as Integer + +"), + +("Base","nb_available","nb_available(stream) + + Returns the number of bytes available for reading before a read + from this stream or buffer will block. + +"), + +("Base","accept","accept(server[, client]) + + Accepts a connection on the given server and returns a connection + to the client. An uninitialized client stream may be provided, in + which case it will be used instead of creating a new stream. + +"), + +("Base","listenany","listenany(port_hint) -> (UInt16, TcpServer) + + Create a TcpServer on any port, using hint as a starting point. + Returns a tuple of the actual port that the server was created on + and the server itself. + +"), + +("Base","watch_file","watch_file(cb=false, s; poll=false) + + Watch file or directory \"s\" and run callback \"cb\" when \"s\" is + modified. The \"poll\" parameter specifies whether to use file + system event monitoring or polling. The callback function \"cb\" + should accept 3 arguments: \"(filename, events, status)\" where + \"filename\" is the name of file that was modified, \"events\" is + an object with boolean fields \"changed\" and \"renamed\" when + using file system event monitoring, or \"readable\" and + \"writable\" when using polling, and \"status\" is always 0. Pass + \"false\" for \"cb\" to not use a callback function. + +"), + +("Base","poll_fd","poll_fd(fd, seconds::Real; readable=false, writable=false) + + Poll a file descriptor fd for changes in the read or write + availability and with a timeout given by the second argument. If + the timeout is not needed, use \"wait(fd)\" instead. The keyword + arguments determine which of read and/or write status should be + monitored and at least one of them needs to be set to true. The + returned value is an object with boolean fields \"readable\", + \"writable\", and \"timedout\", giving the result of the polling. + +"), + +("Base","poll_file","poll_file(s, interval_seconds::Real, seconds::Real) + + Monitor a file for changes by polling every *interval_seconds* + seconds for *seconds* seconds. A return value of true indicates the + file changed, a return value of false indicates a timeout. + +"), + +("Base","bind","bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + + Bind \"socket\" to the given \"host:port\". Note that *0.0.0.0* + will listen on all devices. + +"), + +("Base","send","send(socket::UDPSocket, host::IPv4, port::Integer, msg) + + Send \"msg\" over \"socket to ``host:port\". + +"), + +("Base","recv","recv(socket::UDPSocket) + + Read a UDP packet from the specified socket, and return the bytes + received. This call blocks. + +"), + +("Base","recvfrom","recvfrom(socket::UDPSocket) -> (address, data) + + Read a UDP packet from the specified socket, returning a tuple of + (address, data), where address will be either IPv4 or IPv6 as + appropriate. + +"), + +("Base","setopt","setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + + Set UDP socket options. \"multicast_loop\": loopback for multicast + packets (default: true). \"multicast_ttl\": TTL for multicast + packets. \"enable_broadcast\": flag must be set to true if socket + will be used for broadcast messages, or else the UDP system will + return an access error (default: false). \"ttl\": Time-to-live of + packets sent on the socket. + +"), + +("Base","ntoh","ntoh(x) + + Converts the endianness of a value from Network byte order (big- + endian) to that used by the Host. + +"), + +("Base","hton","hton(x) + + Converts the endianness of a value from that used by the Host to + Network byte order (big-endian). + +"), + +("Base","ltoh","ltoh(x) + + Converts the endianness of a value from Little-endian to that used + by the Host. + +"), + +("Base","htol","htol(x) + + Converts the endianness of a value from that used by the Host to + Little-endian. + +"), + +("Base","ENDIAN_BOM","ENDIAN_BOM + + The 32-bit byte-order-mark indicates the native byte order of the + host machine. Little-endian machines will contain the value + 0x04030201. Big-endian machines will contain the value 0x01020304. + +"), + +("Libc","malloc","malloc(size::Integer) -> Ptr{Void} + + Call \"malloc\" from the C standard library. + +"), + +("Libc","calloc","calloc(num::Integer, size::Integer) -> Ptr{Void} + + Call \"calloc\" from the C standard library. + +"), + +("Libc","realloc","realloc(addr::Ptr, size::Integer) -> Ptr{Void} + + Call \"realloc\" from the C standard library. + + See warning in the documentation for \"free\" regarding only using + this on memory originally obtained from \"malloc\". + +"), + +("Libc","free","free(addr::Ptr) + + Call \"free\" from the C standard library. Only use this on memory + obtained from \"malloc\", not on pointers retrieved from other C + libraries. \"Ptr\" objects obtained from C libraries should be + freed by the free functions defined in that library, to avoid + assertion failures if multiple \"libc\" libraries exist on the + system. + +"), + +("Libc","errno","errno([code]) + + Get the value of the C library's \"errno\". If an argument is + specified, it is used to set the value of \"errno\". + + The value of \"errno\" is only valid immediately after a \"ccall\" + to a C library routine that sets it. Specifically, you cannot call + \"errno\" at the next prompt in a REPL, because lots of code is + executed between prompts. + +"), + +("Libc","strerror","strerror(n) + + Convert a system call error code to a descriptive string + +"), + +("Libc","time","time(t::TmStruct) + + Converts a \"TmStruct\" struct to a number of seconds since the + epoch. + +"), + +("Libc","strftime","strftime([format], time) + + Convert time, given as a number of seconds since the epoch or a + \"TmStruct\", to a formatted string using the given format. + Supported formats are the same as those in the standard C library. + +"), + +("Libc","strptime","strptime([format], timestr) + + Parse a formatted time string into a \"TmStruct\" giving the + seconds, minute, hour, date, etc. Supported formats are the same as + those in the standard C library. On some platforms, timezones will + not be parsed correctly. If the result of this function will be + passed to \"time\" to convert it to seconds since the epoch, the + \"isdst\" field should be filled in manually. Setting it to \"-1\" + will tell the C library to use the current system settings to + determine the timezone. + +"), + +("Libc","TmStruct","TmStruct([seconds]) + + Convert a number of seconds since the epoch to broken-down format, + with fields \"sec\", \"min\", \"hour\", \"mday\", \"month\", + \"year\", \"wday\", \"yday\", and \"isdst\". + +"), + +("Libc","flush_cstdio","flush_cstdio() + + Flushes the C \"stdout\" and \"stderr\" streams (which may have + been written to by external C code). + +"), + +("Libc","msync","msync(ptr, len[, flags]) + + Forces synchronization of the \"mmap()\"ped memory region from + \"ptr\" to \"ptr+len\". Flags defaults to \"MS_SYNC\", but can be a + combination of \"MS_ASYNC\", \"MS_SYNC\", or \"MS_INVALIDATE\". See + your platform man page for specifics. The flags argument is not + valid on Windows. + + You may not need to call \"msync\", because synchronization is + performed at intervals automatically by the operating system. + However, you can call this directly if, for example, you are + concerned about losing the result of a long-running calculation. + +"), + +("Libc","MS_ASYNC","MS_ASYNC + + Enum constant for \"msync()\". See your platform man page for + details. (not available on Windows). + +"), + +("Libc","MS_SYNC","MS_SYNC + + Enum constant for \"msync()\". See your platform man page for + details. (not available on Windows). + +"), + +("Libc","MS_INVALIDATE","MS_INVALIDATE + + Enum constant for \"msync()\". See your platform man page for + details. (not available on Windows). + +"), + +("Libc","mmap","mmap(len, prot, flags, fd, offset) + + Low-level interface to the \"mmap\" system call. See the man page. + +"), + +("Libc","munmap","munmap(pointer, len) + + Low-level interface for unmapping memory (see the man page). With + \"mmap_array()\" you do not need to call this directly; the memory + is unmapped for you when the array goes out of scope. + +"), + +("Libdl","dlopen","dlopen(libfile::AbstractString[, flags::Integer]) + + Load a shared library, returning an opaque handle. + + The optional flags argument is a bitwise-or of zero or more of + \"RTLD_LOCAL\", \"RTLD_GLOBAL\", \"RTLD_LAZY\", \"RTLD_NOW\", + \"RTLD_NODELETE\", \"RTLD_NOLOAD\", \"RTLD_DEEPBIND\", and + \"RTLD_FIRST\". These are converted to the corresponding flags of + the POSIX (and/or GNU libc and/or MacOS) dlopen command, if + possible, or are ignored if the specified functionality is not + available on the current platform. The default is + \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL\". An important usage of + these flags, on POSIX platforms, is to specify + \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL\" in order for the library's + symbols to be available for usage in other shared libraries, in + situations where there are dependencies between shared libraries. + +"), + +("Libdl","dlopen_e","dlopen_e(libfile::AbstractString[, flags::Integer]) + + Similar to \"dlopen()\", except returns a \"NULL\" pointer instead + of raising errors. + +"), + +("Libdl","RTLD_DEEPBIND","RTLD_DEEPBIND + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_FIRST","RTLD_FIRST + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_GLOBAL","RTLD_GLOBAL + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_LAZY","RTLD_LAZY + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_LOCAL","RTLD_LOCAL + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_NODELETE","RTLD_NODELETE + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_NOLOAD","RTLD_NOLOAD + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","RTLD_NOW","RTLD_NOW + + Enum constant for \"dlopen()\". See your platform man page for + details, if applicable. + +"), + +("Libdl","dlsym","dlsym(handle, sym) + + Look up a symbol from a shared library handle, return callable + function pointer on success. + +"), + +("Libdl","dlsym_e","dlsym_e(handle, sym) + + Look up a symbol from a shared library handle, silently return NULL + pointer on lookup failure. + +"), + +("Libdl","dlclose","dlclose(handle) + + Close shared library referenced by handle. + +"), + +("Libdl","find_library","find_library(names, locations) + + Searches for the first library in \"names\" in the paths in the + \"locations\" list, \"DL_LOAD_PATH\", or system library paths (in + that order) which can successfully be dlopen'd. On success, the + return value will be one of the names (potentially prefixed by one + of the paths in locations). This string can be assigned to a + \"global const\" and used as the library name in future + \"ccall\"'s. On failure, it returns the empty string. + +"), + +("Libdl","DL_LOAD_PATH","DL_LOAD_PATH + + When calling \"dlopen\", the paths in this list will be searched + first, in order, before searching the system locations for a valid + library handle. + +"), + +("Base","*","*(A, B) + + Matrix multiplication + +"), + +("Base","\\","\\(A, B) + + Matrix division using a polyalgorithm. For input matrices \"A\" and + \"B\", the result \"X\" is such that \"A*X == B\" when \"A\" is + square. The solver that is used depends upon the structure of + \"A\". A direct solver is used for upper- or lower triangular + \"A\". For Hermitian \"A\" (equivalent to symmetric \"A\" for non- + complex \"A\") the \"BunchKaufman\" factorization is used. + Otherwise an LU factorization is used. For rectangular \"A\" the + result is the minimum-norm least squares solution computed by a + pivoted QR factorization of \"A\" and a rank estimate of A based on + the R factor. + + When \"A\" is sparse, a similar polyalgorithm is used. For + indefinite matrices, the LDLt factorization does not use pivoting + during the numerical factorization and therefore the procedure can + fail even for invertible matrices. + +"), + +("Base","dot","dot(x, y) +⋅(x, y) + + Compute the dot product. For complex vectors, the first vector is + conjugated. + +"), + +("Base","vecdot","vecdot(x, y) + + For any iterable containers \"x\" and \"y\" (including arrays of + any dimension) of numbers (or any element type for which \"dot\" is + defined), compute the Euclidean dot product (the sum of + \"dot(x[i],y[i])\") as if they were vectors. + +"), + +("Base","cross","cross(x, y) +×(x, y) + + Compute the cross product of two 3-vectors. + +"), + +("Base","factorize","factorize(A) + + Compute a convenient factorization (including LU, Cholesky, Bunch- + Kaufman, LowerTriangular, UpperTriangular) of A, based upon the + type of the input matrix. The return value can then be reused for + efficient solving of multiple systems. For example: + \"A=factorize(A); x=A\\\\b; y=A\\\\C\". + +"), + +("Base","full","full(F) + + Reconstruct the matrix \"A\" from the factorization + \"F=factorize(A)\". + +"), + +("Base","lu","lu(A) -> L, U, p + + Compute the LU factorization of \"A\", such that \"A[p,:] = L*U\". + +"), + +("Base","lufact","lufact(A[, pivot=Val{true}]) -> F + + Compute the LU factorization of \"A\". The return type of \"F\" + depends on the type of \"A\". In most cases, if \"A\" is a subtype + \"S\" of AbstractMatrix with an element type \"T`\" supporting + \"+\", \"-\", \"*\" and \"/\" the return type is \"LU{T,S{T}}\". If + pivoting is chosen (default) the element type should also support + \"abs\" and \"<\". When \"A\" is sparse and have element of type + \"Float32\", \"Float64\", \"Complex{Float32}\", or + \"Complex{Float64}\" the return type is \"UmfpackLU\". Some + examples are shown in the table below. + + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input \\\"A\\\" | Type of output \\\"F\\\" | Relationship between \\\"F\\\" and \\\"A\\\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \\\"Matrix()\\\" | \\\"LU\\\" | \\\"F[:L]*F[:U] == A[F[:p], :]\\\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \\\"Tridiagonal()\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | \\\"SparseMatrixCSC()\\\" | \\\"UmfpackLU\\\" | \\\"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\\\" | + +-------------------------+---------------------------+----------------------------------------------+ + + The individual components of the factorization \"F\" can be + accessed by indexing: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | \\\"LU\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | \\\"UmfpackLU\\\" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:L]\\\" | \\\"L\\\" (lower triangular) part of \\\"LU\\\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:U]\\\" | \\\"U\\\" (upper triangular) part of \\\"LU\\\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:p]\\\" | (right) permutation \\\"Vector\\\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:P]\\\" | (right) permutation \\\"Matrix\\\" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:q]\\\" | left permutation \\\"Vector\\\" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:Rs]\\\" | \\\"Vector\\\" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \\\"F[:(:)]\\\" | \\\"(L,U,p,q,Rs)\\\" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | \\\"LU\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | \\\"UmfpackLU\\\" | + +--------------------+--------+--------------------------+---------------+ + | \\\"/\\\" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | \\\"\\\\\\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \\\"cond\\\" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \\\"det\\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \\\"logdet\\\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \\\"logabsdet\\\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \\\"size\\\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + +"), + +("Base","lufact!","lufact!(A) -> LU + + \"lufact!\" is the same as \"lufact()\", but saves space by + overwriting the input A, instead of creating a copy. For sparse + \"A\" the \"nzval\" field is not overwritten but the index fields, + \"colptr\" and \"rowval\" are decremented in place, converting from + 1-based indices to 0-based indices. + +"), + +("Base","chol","chol(A[, LU]) -> F + + Compute the Cholesky factorization of a symmetric positive definite + matrix \"A\" and return the matrix \"F\". If \"LU\" is \"Val{:U}\" + (Upper), \"F\" is of type \"UpperTriangular\" and \"A = F'*F\". If + \"LU\" is \"Val{:L}\" (Lower), \"F\" is of type \"LowerTriangular\" + and \"A = F*F'\". \"LU\" defaults to \"Val{:U}\". + +"), + +("Base","cholfact","cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive + (semi)definite matrix \"A\" and return either a \"Cholesky\" if + \"pivot==Val{false}\" or \"CholeskyPivoted\" if + \"pivot==Val{true}\". \"LU\" may be \":L\" for using the lower part + or \":U\" for the upper part. The default is to use \":U\". The + triangular matrix can be obtained from the factorization \"F\" + with: \"F[:L]\" and \"F[:U]\". The following functions are + available for \"Cholesky\" objects: \"size\", \"\\\", \"inv\", + \"det\". For \"CholeskyPivoted\" there is also defined a \"rank\". + If \"pivot==Val{false}\" a \"PosDefException\" exception is thrown + in case the matrix is not positive definite. The argument \"tol\" + determines the tolerance for determining the rank. For negative + values, the tolerance is the machine precision. + +"), + +("Base","cholfact","cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite + matrix \"A\". A fill-reducing permutation is used. \"F = + cholfact(A)\" is most frequently used to solve systems of equations + with \"F\\b\", but also the methods \"diag\", \"det\", \"logdet\" + are defined for \"F\". You can also extract individual factors + from \"F\", using \"F[:L]\". However, since pivoting is on by + default, the factorization is internally represented as \"A == + P'*L*L'*P\" with a permutation matrix \"P\"; using just \"L\" + without accounting for \"P\" will give incorrect answers. To + include the effects of permutation, it's typically preferable to + extact \"combined\" factors like \"PtL = F[:PtL]\" (the equivalent + of \"P'*L\") and \"LtP = F[:UP]\" (the equivalent of \"L'*P\"). + + Setting optional \"shift\" keyword argument computes the + factorization of \"A+shift*I\" instead of \"A\". If the \"perm\" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. + +"), + +("Base","cholfact!","cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + \"cholfact!\" is the same as \"cholfact()\", but saves space by + overwriting the input \"A\", instead of creating a copy. + \"cholfact!\" can also reuse the symbolic factorization from a + different matrix \"F\" with the same structure when used as: + \"cholfact!(F::CholmodFactor, A)\". + +"), + +("Base","ldltfact","ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix \"A\" such + that \"A=L*Diagonal(d)*L'\" where \"L\" is a unit lower triangular + matrix and \"d\" is a vector with non-negative elements. + +"), + +("Base","ldltfact","ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix \"A\". A fill-reducing permutation is used. \"F = + ldltfact(A)\" is most frequently used to solve systems of equations + with \"F\\b\", but also the methods \"diag\", \"det\", \"logdet\" + are defined for \"F\". You can also extract individual factors from + \"F\", using \"F[:L]\". However, since pivoting is on by default, + the factorization is internally represented as \"A == P'*L*D*L'*P\" + with a permutation matrix \"P\"; using just \"L\" without + accounting for \"P\" will give incorrect answers. To include the + effects of permutation, it's typically preferable to extact + \"combined\" factors like \"PtL = F[:PtL]\" (the equivalent of + \"P'*L\") and \"LtP = F[:UP]\" (the equivalent of \"L'*P\"). The + complete list of supported factors is \":L, :PtL, :D, :UP, :U, :LD, + :DU, :PtLD, :DUP\". + + Setting optional \"shift\" keyword argument computes the + factorization of \"A+shift*I\" instead of \"A\". If the \"perm\" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. + +"), + +("Base","qr","qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + + Compute the (pivoted) QR factorization of \"A\" such that either + \"A = Q*R\" or \"A[:,p] = Q*R\". Also see \"qrfact\". The default + is to compute a thin factorization. Note that \"R\" is not extended + with zeros when the full \"Q\" is requested. + +"), + +("Base","qrfact","qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of \"A\". The return type of \"F\" + depends on the element type of \"A\" and whether pivoting is + specified (with \"pivot==Val{true}\"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \\\"eltype(A)\\\" | \\\"pivot\\\" | Relationship between \\\"F\\\" and \\\"A\\\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \\\"QR\\\" | not \\\"BlasFloat\\\" | either | \\\"A==F[:Q]*F[:R]\\\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \\\"QRCompactWY\\\" | \\\"BlasFloat\\\" | \\\"Val{false}\\\" | \\\"A==F[:Q]*F[:R]\\\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \\\"QRPivoted\\\" | \\\"BlasFloat\\\" | \\\"Val{true}\\\" | \\\"A[:,F[:p]]==F[:Q]*F[:R]\\\" | + +------------------+-------------------+----------------+---------------------------------------+ + + \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", + \"Complex64\" or \"Complex128\". + + The individual components of the factorization \"F\" can be + accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \\\"QR\\\" | \\\"QRCompactWY\\\" | \\\"QRPivoted\\\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \\\"F[:Q]\\\" | \\\"Q\\\" (orthogonal/unitary) part of \\\"QR\\\" | ✓ (\\\"QRPackedQ\\\") | ✓ (\\\"QRCompactWYQ\\\") | ✓ (\\\"QRPackedQ\\\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \\\"F[:R]\\\" | \\\"R\\\" (upper right triangular) part of \\\"QR\\\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \\\"F[:p]\\\" | pivot \\\"Vector\\\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \\\"F[:P]\\\" | (pivot) permutation \\\"Matrix\\\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the \"QR\" objects: + \"size\", \"\\\". When \"A\" is rectangular, \"\\\" will return a + least squares solution and if the solution is not unique, the one + with smallest norm is returned. + + Multiplication with respect to either thin or full \"Q\" is + allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A + \"Q\" matrix can be converted into a regular matrix with \"full()\" + which has a named argument \"thin\". + + Note: \"qrfact\" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the \"Q\" and \"R\" matrices can be stored compactly rather + as two separate dense matrices.The data contained in \"QR\" or + \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, + which is a compact representation of the rotation matrix: + + Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) + + where \\tau_i is the scale factor and v_i is the projection + vector associated with the i^{th} Householder elementary + reflector.The data contained in \"QRCompactWY\" can be used to + construct the \"QRCompactWYQ\" type, which is a compact + representation of the rotation matrix + + Q = I + Y T Y^T + + where \"Y\" is m \\times r lower trapezoidal and \"T\" is r + \\times r upper triangular. The *compact WY* representation + [Schreiber1989] is not to be confused with the older, *WY* + representation [Bischof1987]. (The LAPACK documentation uses + \"V\" in lieu of \"Y\".) + + [Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 + +"), + +("Base","qrfact","qrfact(A) -> SPQR.Factorization + + Compute the QR factorization of a sparse matrix \"A\". A fill- + reducing permutation is used. The main application of this type is + to solve least squares problems with \"\\\". The function calls the + C library SPQR and a few additional functions from the library are + wrapped but not exported. + +"), + +("Base","qrfact!","qrfact!(A[, pivot=Val{false}]) + + \"qrfact!\" is the same as \"qrfact()\" when A is a subtype of + \"StridedMatrix\", but saves space by overwriting the input \"A\", + instead of creating a copy. + +"), + +("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a + \"QRCompactWYQ\" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. + + Optionally takes a \"thin\" Boolean argument, which if \"true\" + omits the columns that span the rows of \"R\" in the QR + factorization that are zero. The resulting matrix is the \"Q\" in a + thin QR factorization (sometimes called the reduced QR + factorization). If \"false\", returns a \"Q\" that spans all rows + of \"R\" in its corresponding QR factorization. + +"), + +("Base","bkfact","bkfact(A) -> BunchKaufman + + Compute the Bunch-Kaufman [Bunch1977] factorization of a real + symmetric or complex Hermitian matrix \"A\" and return a + \"BunchKaufman\" object. The following functions are available for + \"BunchKaufman\" objects: \"size\", \"\\\", \"inv\", \"issym\", + \"ishermitian\". + +"), + +("Base","bkfact!","bkfact!(A) -> BunchKaufman + + \"bkfact!\" is the same as \"bkfact()\", but saves space by + overwriting the input \"A\", instead of creating a copy. + +"), + +("Base","sqrtm","sqrtm(A) + + Compute the matrix square root of \"A\". If \"B = sqrtm(A)\", then + \"B*B == A\" within roundoff error. + + \"sqrtm\" uses a polyalgorithm, computing the matrix square root + using Schur factorizations (\"schurfact()\") unless it detects the + matrix to be Hermitian or real symmetric, in which case it computes + the matrix square root from an eigendecomposition (\"eigfact()\"). + In the latter situation for positive definite matrices, the matrix + square root has \"Real\" elements, otherwise it has \"Complex\" + elements. + +"), + +("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" + for details on the \"balance\" keyword argument. + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + \"eig\" is a wrapper around \"eigfact()\", extracting all parts of + the factorization to a tuple; where possible, using \"eigfact()\" + is recommended. + +"), + +("Base","eig","eig(A, B) -> D, V + + Computes generalized eigenvalues and vectors of \"A\" with respect + to \"B\". + + \"eig\" is a wrapper around \"eigfact()\", extracting all parts of + the factorization to a tuple; where possible, using \"eigfact()\" + is recommended. + +"), + +("Base","eigvals","eigvals(A,[irange,][vl,][vu]) + + Returns the eigenvalues of \"A\". If \"A\" is \"Symmetric\", + \"Hermitian\" or \"SymTridiagonal\", it is possible to calculate + only a subset of the eigenvalues by specifying either a + \"UnitRange\" \"irange\" covering indices of the sorted + eigenvalues, or a pair \"vl\" and \"vu\" for the lower and upper + boundaries of the eigenvalues. + + For general non-symmetric matrices it is possible to specify how + the matrix is balanced before the eigenvector calculation. The + option \"permute=true\" permutes the matrix to become closer to + upper triangular, and \"scale=true\" scales the matrix by its + diagonal elements to make rows and columns more equal in norm. The + default is \"true\" for both options. + +"), + +("Base","eigmax","eigmax(A) + + Returns the largest eigenvalue of \"A\". + +"), + +("Base","eigmin","eigmin(A) + + Returns the smallest eigenvalue of \"A\". + +"), + +("Base","eigvecs","eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + + Returns a matrix \"M\" whose columns are the eigenvectors of \"A\". + (The \"k\"th eigenvector can be obtained from the slice \"M[:, + k]\".) The \"permute\" and \"scale\" keywords are the same as for + \"eigfact()\". + + For \"SymTridiagonal\" matrices, if the optional vector of + eigenvalues \"eigvals\" is specified, returns the specific + corresponding eigenvectors. + +"), + +("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of \"A\", returning an + \"Eigen\" factorization object \"F\" which contains the eigenvalues + in \"F[:values]\" and the eigenvectors in the columns of the matrix + \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the + slice \"F[:vectors][:, k]\".) + + The following functions are available for \"Eigen\" objects: + \"inv\", \"det\". + + If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it + is possible to calculate only a subset of the eigenvalues by + specifying either a \"UnitRange\" \"irange\" covering indices of + the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower + and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the + matrix is balanced before the eigenvector calculation. The option + \"permute=true\" permutes the matrix to become closer to upper + triangular, and \"scale=true\" scales the matrix by its diagonal + elements to make rows and columns more equal in norm. The default + is \"true\" for both options. + +"), + +("Base","eigfact","eigfact(A, B) -> GeneralizedEigen + + Computes the generalized eigenvalue decomposition of \"A\" and + \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" + which contains the generalized eigenvalues in \"F[:values]\" and + the generalized eigenvectors in the columns of the matrix + \"F[:vectors]\". (The \"k\"th generalized eigenvector can be + obtained from the slice \"F[:vectors][:, k]\".) + +"), + +("Base","eigfact!","eigfact!(A[, B]) + + Same as \"eigfact()\", but saves space by overwriting the input + \"A\" (and \"B\"), instead of creating a copy. + +"), + +("Base","hessfact","hessfact(A) + + Compute the Hessenberg decomposition of \"A\" and return a + \"Hessenberg\" object. If \"F\" is the factorization object, the + unitary matrix can be accessed with \"F[:Q]\" and the Hessenberg + matrix with \"F[:H]\". When \"Q\" is extracted, the resulting type + is the \"HessenbergQ\" object, and may be converted to a regular + matrix with \"full()\". + +"), + +("Base","hessfact!","hessfact!(A) + + \"hessfact!\" is the same as \"hessfact()\", but saves space by + overwriting the input A, instead of creating a copy. + +"), + +("Base","schurfact","schurfact(A) -> Schur + + Computes the Schur factorization of the matrix \"A\". The (quasi) + triangular Schur factor can be obtained from the \"Schur\" object + \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the + unitary/orthogonal Schur vectors can be obtained with + \"F[:vectors]\" or \"F[:Z]\" such that + \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" + can be obtained with \"F[:values]\". + +"), + +("Base","schurfact!","schurfact!(A) + + Computes the Schur factorization of \"A\", overwriting \"A\" in the + process. See \"schurfact()\" + +"), + +("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + + See \"schurfact()\" + +"), + +("Base","ordschur","ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" + according to the logical array \"select\" returning a Schur object + \"F\". The selected eigenvalues appear in the leading diagonal of + \"F[:Schur]\" and the the corresponding leading columns of + \"F[:vectors]\" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via \"select\". + +"), + +("Base","ordschur!","ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", + overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" + +"), + +("Base","ordschur","ordschur(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\". + +"), + +("Base","ordschur!","ordschur!(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\", + overwriting \"S\" in the process. See \"ordschur()\" + +"), + +("Base","schurfact","schurfact(A, B) -> GeneralizedSchur + + Computes the Generalized Schur (or QZ) factorization of the + matrices \"A\" and \"B\". The (quasi) triangular Schur factors can + be obtained from the \"Schur\" object \"F\" with \"F[:S]\" and + \"F[:T]\", the left unitary/orthogonal Schur vectors can be + obtained with \"F[:left]\" or \"F[:Q]\" and the right + unitary/orthogonal Schur vectors can be obtained with \"F[:right]\" + or \"F[:Z]\" such that \"A=F[:left]*F[:S]*F[:right]'\" and + \"B=F[:left]*F[:T]*F[:right]'\". The generalized eigenvalues of + \"A\" and \"B\" can be obtained with \"F[:alpha]./F[:beta]\". + +"), + +("Base","schur","schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + + See \"schurfact()\" + +"), + +("Base","ordschur","ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix \"(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" + and returns a GeneralizedSchur object \"GS\". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of + \"A\" and \"B\" can still be obtained with + \"GS[:alpha]./GS[:beta]\". + +"), + +("Base","ordschur!","ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices \"(S, T, Q, Z)\" in the process. See + \"ordschur()\". + +"), + +("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur + object. See \"ordschur()\". + +"), + +("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + \"ordschur()\". + +"), + +("Base","svdfact","svdfact(A[, thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of \"A\" and return + an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained + from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" + and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is + \"true\", an economy mode decomposition is returned. The algorithm + produces \"Vt\" and hence \"Vt\" is more efficient to extract than + \"V\". The default is to produce a thin decomposition. + +"), + +("Base","svdfact!","svdfact!(A[, thin=true]) -> SVD + + \"svdfact!\" is the same as \"svdfact()\", but saves space by + overwriting the input A, instead of creating a copy. If \"thin\" is + \"true\", an economy mode decomposition is returned. The default is + to produce a thin decomposition. + +"), + +("Base","svd","svd(A[, thin=true]) -> U, S, V + + Wrapper around \"svdfact\" extracting all parts the factorization + to a tuple. Direct use of \"svdfact\" is therefore generally more + efficient. Computes the SVD of A, returning \"U\", vector \"S\", + and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is + \"true\", an economy mode decomposition is returned. The default is + to produce a thin decomposition. + +"), + +("Base","svdvals","svdvals(A) + + Returns the singular values of \"A\". + +"), + +("Base","svdvals!","svdvals!(A) + + Returns the singular values of \"A\", while saving space by + overwriting the input. + +"), + +("Base","svdfact","svdfact(A, B) -> GeneralizedSVD + + Compute the generalized SVD of \"A\" and \"B\", returning a + \"GeneralizedSVD\" Factorization object \"F\", such that \"A = + F[:U]*F[:D1]*F[:R0]*F[:Q]'\" and \"B = + F[:V]*F[:D2]*F[:R0]*F[:Q]'\". + +"), + +("Base","svd","svd(A, B) -> U, V, Q, D1, D2, R0 + + Wrapper around \"svdfact\" extracting all parts the factorization + to a tuple. Direct use of \"svdfact\" is therefore generally more + efficient. The function returns the generalized SVD of \"A\" and + \"B\", returning \"U\", \"V\", \"Q\", \"D1\", \"D2\", and \"R0\" + such that \"A = U*D1*R0*Q'\" and \"B = V*D2*R0*Q'\". + +"), + +("Base","svdvals","svdvals(A, B) + + Return only the singular values from the generalized singular value + decomposition of \"A\" and \"B\". + +"), + +("Base","triu","triu(M) + + Upper triangle of a matrix. + +"), + +("Base","triu","triu(M, k) + + Returns the upper triangle of \"M\" starting from the \"k\"th + superdiagonal. + +"), + +("Base","triu!","triu!(M) + + Upper triangle of a matrix, overwriting \"M\" in the process. + +"), + +("Base","triu!","triu!(M, k) + + Returns the upper triangle of \"M\" starting from the \"k\"th + superdiagonal, overwriting \"M\" in the process. + +"), + +("Base","tril","tril(M) + + Lower triangle of a matrix. + +"), + +("Base","tril","tril(M, k) + + Returns the lower triangle of \"M\" starting from the \"k\"th + subdiagonal. + +"), + +("Base","tril!","tril!(M) + + Lower triangle of a matrix, overwriting \"M\" in the process. + +"), + +("Base","tril!","tril!(M, k) + + Returns the lower triangle of \"M\" starting from the \"k\"th + subdiagonal, overwriting \"M\" in the process. + +"), + +("Base","diagind","diagind(M[, k]) + + A \"Range\" giving the indices of the \"k\"th diagonal of the + matrix \"M\". + +"), + +("Base","diag","diag(M[, k]) + + The \"k\"th diagonal of a matrix, as a vector. Use \"diagm\" to + construct a diagonal matrix. + +"), + +("Base","diagm","diagm(v[, k]) + + Construct a diagonal matrix and place \"v\" on the \"k\"th + diagonal. + +"), + +("Base","scale","scale(A, b) + +"), + +("Base","scale","scale(b, A) + + Scale an array \"A\" by a scalar \"b\", returning a new array. + + If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" + scales each column \"i\" of \"A\" by \"b[i]\" (similar to + \"A*diagm(b)\"), while \"scale(b,A)\" scales each row \"i\" of + \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), returning a new + array. + + Note: for large \"A\", \"scale\" can be much faster than \"A .* b\" + or \"b .* A\", due to the use of BLAS. + +"), + +("Base","scale!","scale!(A, b) + +"), + +("Base","scale!","scale!(b, A) + + Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but + overwriting \"A\" in-place. + + If \"A\" is a matrix and \"b\" is a vector, then \"scale!(A,b)\" + scales each column \"i\" of \"A\" by \"b[i]\" (similar to + \"A*diagm(b)\"), while \"scale!(b,A)\" scales each row \"i\" of + \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), again operating in- + place on \"A\". + +"), + +("Base","Tridiagonal","Tridiagonal(dl, d, du) + + Construct a tridiagonal matrix from the lower diagonal, diagonal, + and upper diagonal, respectively. The result is of type + \"Tridiagonal\" and provides efficient specialized linear solvers, + but may be converted into a regular matrix with \"full()\". + +"), + +("Base","Bidiagonal","Bidiagonal(dv, ev, isupper) + + Constructs an upper (\"isupper=true\") or lower (\"isupper=false\") + bidiagonal matrix using the given diagonal (\"dv\") and off- + diagonal (\"ev\") vectors. The result is of type \"Bidiagonal\" + and provides efficient specialized linear solvers, but may be + converted into a regular matrix with \"full()\". + +"), + +("Base","SymTridiagonal","SymTridiagonal(d, du) + + Construct a real symmetric tridiagonal matrix from the diagonal and + upper diagonal, respectively. The result is of type + \"SymTridiagonal\" and provides efficient specialized eigensolvers, + but may be converted into a regular matrix with \"full()\". + +"), + +("Base","rank","rank(M) + + Compute the rank of a matrix. + +"), + +("Base","norm","norm(A[, p]) + + Compute the \"p\"-norm of a vector or the operator norm of a matrix + \"A\", defaulting to the \"p=2\"-norm. + + For vectors, \"p\" can assume any numeric value (even though not + all values produce a mathematically valid vector norm). In + particular, \"norm(A, Inf)\" returns the largest value in + \"abs(A)\", whereas \"norm(A, -Inf)\" returns the smallest. + + For matrices, valid values of \"p\" are \"1\", \"2\", or \"Inf\". + (Note that for sparse matrices, \"p=2\" is currently not + implemented.) Use \"vecnorm()\" to compute the Frobenius norm. + +"), + +("Base","vecnorm","vecnorm(A[, p]) + + For any iterable container \"A\" (including arrays of any + dimension) of numbers (or any element type for which \"norm\" is + defined), compute the \"p\"-norm (defaulting to \"p=2\") as if + \"A\" were a vector of the corresponding length. + + For example, if \"A\" is a matrix and \"p=2\", then this is + equivalent to the Frobenius norm. + +"), + +("Base","cond","cond(M[, p]) + + Condition number of the matrix \"M\", computed using the operator + \"p\"-norm. Valid values for \"p\" are \"1\", \"2\" (default), or + \"Inf\". + +"), + +("Base","condskeel","condskeel(M[, x, p]) + + \\kappa_S(M, p) & = \\left\\Vert \\left\\vert M \\right\\vert + \\left\\vert M^{-1} \\right\\vert \\right\\Vert_p \\\\ + \\kappa_S(M, x, p) & = \\left\\Vert \\left\\vert M \\right\\vert + \\left\\vert M^{-1} \\right\\vert \\left\\vert x \\right\\vert + \\right\\Vert_p + + Skeel condition number \\kappa_S of the matrix \"M\", optionally + with respect to the vector \"x\", as computed using the operator + \"p\"-norm. \"p\" is \"Inf\" by default, if not provided. Valid + values for \"p\" are \"1\", \"2\", or \"Inf\". + + This quantity is also known in the literature as the Bauer + condition number, relative condition number, or componentwise + relative condition number. + +"), + +("Base","trace","trace(M) + + Matrix trace + +"), + +("Base","det","det(M) + + Matrix determinant + +"), + +("Base","logdet","logdet(M) + + Log of matrix determinant. Equivalent to \"log(det(M))\", but may + provide increased accuracy and/or speed. + +"), + +("Base","logabsdet","logabsdet(M) + + Log of absolute value of determinant of real matrix. Equivalent to + \"(log(abs(det(M))), sign(det(M)))\", but may provide increased + accuracy and/or speed. + +"), + +("Base","inv","inv(M) + + Matrix inverse + +"), + +("Base","pinv","pinv(M[, tol]) + + Computes the Moore-Penrose pseudoinverse. + + For matrices \"M\" with floating point elements, it is convenient + to compute the pseudoinverse by inverting only singular values + above a given threshold, \"tol\". + + The optimal choice of \"tol\" varies both with the value of \"M\" + and the intended application of the pseudoinverse. The default + value of \"tol\" is + \"eps(real(float(one(eltype(M)))))*maximum(size(A))\", which is + essentially machine epsilon for the real part of a matrix element + multiplied by the larger matrix dimension. For inverting dense ill- + conditioned matrices in a least-squares sense, \"tol = + sqrt(eps(real(float(one(eltype(M))))))\" is recommended. + + For more information, see [8859], [B96], [S84], [KY88]. + + [8859] Issue 8859, \"Fix least squares\", + https://github.com/JuliaLang/julia/pull/8859 + + [B96] Åke Björck, \"Numerical Methods for Least Squares + Problems\", SIAM Press, Philadelphia, 1996, \"Other Titles in + Applied Mathematics\", Vol. 51. doi:10.1137/1.9781611971484 + + [S84] G. W. Stewart, \"Rank Degeneracy\", SIAM Journal on + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 + + [KY88] Konstantinos Konstantinides and Kung Yao, + \"Statistical analysis of effective singular values in + matrix rank determination\", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 + +"), + +("Base","nullspace","nullspace(M) + + Basis for nullspace of \"M\". + +"), + +("Base","repmat","repmat(A, n, m) + + Construct a matrix by repeating the given matrix \"n\" times in + dimension 1 and \"m\" times in dimension 2. + +"), + +("Base","repeat","repeat(A, inner = Int[], outer = Int[]) + + Construct an array by repeating the entries of \"A\". The i-th + element of \"inner\" specifies the number of times that the + individual entries of the i-th dimension of \"A\" should be + repeated. The i-th element of \"outer\" specifies the number of + times that a slice along the i-th dimension of \"A\" should be + repeated. + +"), + +("Base","kron","kron(A, B) + + Kronecker tensor product of two vectors or two matrices. + +"), + +("Base","blkdiag","blkdiag(A...) + + Concatenate matrices block-diagonally. Currently only implemented + for sparse matrices. + +"), + +("Base","linreg","linreg(x, y) -> [a; b] + + Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is + the closest line to the given points \"(x,y)\". In other words, + this function determines parameters \"[a, b]\" that minimize the + squared error between \"y\" and \"a+b*x\". + + **Example**: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, \"o\") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + +"), + +("Base","linreg","linreg(x, y, w) + + Weighted least-squares linear regression. + +"), + +("Base","expm","expm(A) + + Matrix exponential. + +"), + +("Base","lyap","lyap(A, C) + + Computes the solution \"X\" to the continuous Lyapunov equation + \"AX + XA' + C = 0\", where no eigenvalue of \"A\" has a zero real + part and no two eigenvalues are negative complex conjugates of each + other. + +"), + +("Base","sylvester","sylvester(A, B, C) + + Computes the solution \"X\" to the Sylvester equation \"AX + XB + C + = 0\", where \"A\", \"B\" and \"C\" have compatible dimensions and + \"A\" and \"-B\" have no eigenvalues with equal real part. + +"), + +("Base","issym","issym(A) -> Bool + + Test whether a matrix is symmetric. + +"), + +("Base","isposdef","isposdef(A) -> Bool + + Test whether a matrix is positive definite. + +"), + +("Base","isposdef!","isposdef!(A) -> Bool + + Test whether a matrix is positive definite, overwriting \"A\" in + the processes. + +"), + +("Base","istril","istril(A) -> Bool + + Test whether a matrix is lower triangular. + +"), + +("Base","istriu","istriu(A) -> Bool + + Test whether a matrix is upper triangular. + +"), + +("Base","isdiag","isdiag(A) -> Bool + + Test whether a matrix is diagonal. + +"), + +("Base","ishermitian","ishermitian(A) -> Bool + + Test whether a matrix is Hermitian. + +"), + +("Base","transpose","transpose(A) + + The transposition operator (\".'\"). + +"), + +("Base","transpose!","transpose!(dest, src) + + Transpose array \"src\" and store the result in the preallocated + array \"dest\", which should have a size corresponding to + \"(size(src,2),size(src,1))\". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. + +"), + +("Base","ctranspose","ctranspose(A) + + The conjugate transposition operator (\"'\"). + +"), + +("Base","ctranspose!","ctranspose!(dest, src) + + Conjugate transpose array \"src\" and store the result in the + preallocated array \"dest\", which should have a size corresponding + to \"(size(src,2),size(src,1))\". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. + +"), + +("Base","eigs","eigs(A[, B], ; nev=6, which=\"LM\", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) + + Computes eigenvalues \"d\" of \"A\" using Lanczos or Arnoldi + iterations for real symmetric or general nonsymmetric matrices + respectively. If \"B\" is provided, the generalized eigenproblem is + solved. + + The following keyword arguments are supported: + * \"nev\": Number of eigenvalues + + * \"ncv\": Number of Krylov vectors used in the computation; + should satisfy + + \"nev+1 <= ncv <= n\" for real symmetric problems and + \"nev+2 <= ncv <= n\" for other problems, where \"n\" is + the size of the input matrix \"A\". The default is \"ncv = + max(20,2*nev+1)\". Note that these restrictions limit the + input matrix \"A\" to be of dimension at least 2. + + * \"which\": type of eigenvalues to compute. See the note + below. + + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\"which\\\" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":LM\\\" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":SM\\\" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":LR\\\" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":SR\\\" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":LI\\\" | eigenvalues of largest imaginary part (nonsymmetric or complex \\\"A\\\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":SI\\\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \\\"A\\\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \\\":BE\\\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \\\"A\\\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + + * \"tol\": tolerance (tol \\le 0.0 defaults to + \"DLAMCH('EPS')\") + + * \"maxiter\": Maximum number of iterations (default = 300) + + * \"sigma\": Specifies the level shift used in inverse + iteration. If \"nothing\" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + \"sigma\" using shift and invert iterations. + + * \"ritzvec\": Returns the Ritz vectors \"v\" (eigenvectors) + if \"true\" + + * \"v0\": starting vector from which to start the iterations + + \"eigs\" returns the \"nev\" requested eigenvalues in \"d\", the + corresponding Ritz vectors \"v\" (only if \"ritzvec=true\"), the + number of converged eigenvalues \"nconv\", the number of iterations + \"niter\" and the number of matrix vector multiplications + \"nmult\", as well as the final residual vector \"resid\". + + Note: The \"sigma\" and \"which\" keywords interact: the + description of eigenvalues searched for by \"which\" do _not_ + necessarily refer to the eigenvalues of \"A\", but rather the + linear operator constructed by the specification of the iteration + mode implied by \"sigma\". + + +-----------------+------------------------------------+------------------------------------+ + | \\\"sigma\\\" | iteration mode | \\\"which\\\" refers to eigenvalues of | + +-----------------+------------------------------------+------------------------------------+ + | \\\"nothing\\\" | ordinary (forward) | A | + +-----------------+------------------------------------+------------------------------------+ + | real or complex | inverse with level shift \\\"sigma\\\" | (A - \\\\sigma I )^{-1} | + +-----------------+------------------------------------+------------------------------------+ + +"), + +("Base","svds","svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + + \"svds\" computes largest singular values \"s\" of \"A\" using + Lanczos or Arnoldi iterations. Uses \"eigs()\" underneath. + + Inputs are: + * \"A\": Linear operator. It can either subtype of + \"AbstractArray\" (e.g., sparse matrix) or duck typed. For + duck typing \"A\" has to support \"size(A)\", \"eltype(A)\", + \"A * vector\" and \"A' * vector\". + + * \"nsv\": Number of singular values. + + * \"ritzvec\": Whether to return the left and right singular + vectors \"left_sv\" and \"right_sv\", default is \"true\". If + \"false\" the singular vectors are omitted from the output. + + * \"tol\": tolerance, see \"eigs()\". + + * \"maxiter\": Maximum number of iterations, see \"eigs()\". + + **Example**: + + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) + +"), + +("Base","peakflops","peakflops(n; parallel=false) + + \"peakflops\" computes the peak flop rate of the computer by using + double precision \"Base.LinAlg.BLAS.gemm!()\". By default, if no + arguments are specified, it multiplies a matrix of size \"n x n\", + where \"n = 2000\". If the underlying BLAS is using multiple + threads, higher flop rates are realized. The number of BLAS threads + can be set with \"blas_set_num_threads(n)\". + + If the keyword argument \"parallel\" is set to \"true\", + \"peakflops\" is run in parallel on all the worker processors. The + flop rate of the entire parallel computer is returned. When running + in parallel, only 1 BLAS thread is used. The argument \"n\" still + refers to the size of the problem that is solved on each processor. + +"), + +("Base.LinAlg.BLAS","dot","dot(n, X, incx, Y, incy) + + Dot product of two vectors consisting of \"n\" elements of array + \"X\" with stride \"incx\" and \"n\" elements of array \"Y\" with + stride \"incy\". + +"), + +("Base.LinAlg.BLAS","dotu","dotu(n, X, incx, Y, incy) + + Dot function for two complex vectors. + +"), + +("Base.LinAlg.BLAS","dotc","dotc(n, X, incx, U, incy) + + Dot function for two complex vectors conjugating the first vector. + +"), + +("Base.LinAlg.BLAS","blascopy!","blascopy!(n, X, incx, Y, incy) + + Copy \"n\" elements of array \"X\" with stride \"incx\" to array + \"Y\" with stride \"incy\". Returns \"Y\". + +"), + +("Base.LinAlg.BLAS","nrm2","nrm2(n, X, incx) + + 2-norm of a vector consisting of \"n\" elements of array \"X\" with + stride \"incx\". + +"), + +("Base.LinAlg.BLAS","asum","asum(n, X, incx) + + sum of the absolute values of the first \"n\" elements of array + \"X\" with stride \"incx\". + +"), + +("Base.LinAlg.BLAS","axpy!","axpy!(a, X, Y) + + Overwrite \"Y\" with \"a*X + Y\". Returns \"Y\". + +"), + +("Base.LinAlg.BLAS","scal!","scal!(n, a, X, incx) + + Overwrite \"X\" with \"a*X\". Returns \"X\". + +"), + +("Base.LinAlg.BLAS","scal","scal(n, a, X, incx) + + Returns \"a*X\". + +"), + +("Base.LinAlg.BLAS","ger!","ger!(alpha, x, y, A) + + Rank-1 update of the matrix \"A\" with vectors \"x\" and \"y\" as + \"alpha*x*y' + A\". + +"), + +("Base.LinAlg.BLAS","syr!","syr!(uplo, alpha, x, A) + + Rank-1 update of the symmetric matrix \"A\" with vector \"x\" as + \"alpha*x*x.' + A\". When \"uplo\" is 'U' the upper triangle of + \"A\" is updated ('L' for lower triangle). Returns \"A\". + +"), + +("Base.LinAlg.BLAS","syrk!","syrk!(uplo, trans, alpha, A, beta, C) + + Rank-k update of the symmetric matrix \"C\" as \"alpha*A*A.' + + beta*C\" or \"alpha*A.'*A + beta*C\" according to whether \"trans\" + is 'N' or 'T'. When \"uplo\" is 'U' the upper triangle of \"C\" is + updated ('L' for lower triangle). Returns \"C\". + +"), + +("Base.LinAlg.BLAS","syrk","syrk(uplo, trans, alpha, A) + + Returns either the upper triangle or the lower triangle, according + to \"uplo\" ('U' or 'L'), of \"alpha*A*A.'\" or \"alpha*A.'*A\", + according to \"trans\" ('N' or 'T'). + +"), + +("Base.LinAlg.BLAS","her!","her!(uplo, alpha, x, A) + + Methods for complex arrays only. Rank-1 update of the Hermitian + matrix \"A\" with vector \"x\" as \"alpha*x*x' + A\". When + \"uplo\" is 'U' the upper triangle of \"A\" is updated ('L' for + lower triangle). Returns \"A\". + +"), + +("Base.LinAlg.BLAS","herk!","herk!(uplo, trans, alpha, A, beta, C) + + Methods for complex arrays only. Rank-k update of the Hermitian + matrix \"C\" as \"alpha*A*A' + beta*C\" or \"alpha*A'*A + beta*C\" + according to whether \"trans\" is 'N' or 'T'. When \"uplo\" is 'U' + the upper triangle of \"C\" is updated ('L' for lower triangle). + Returns \"C\". + +"), + +("Base.LinAlg.BLAS","herk","herk(uplo, trans, alpha, A) + + Methods for complex arrays only. Returns either the upper triangle + or the lower triangle, according to \"uplo\" ('U' or 'L'), of + \"alpha*A*A'\" or \"alpha*A'*A\", according to \"trans\" ('N' or + 'T'). + +"), + +("Base.LinAlg.BLAS","gbmv!","gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) + + Update vector \"y\" as \"alpha*A*x + beta*y\" or \"alpha*A'*x + + beta*y\" according to \"trans\" ('N' or 'T'). The matrix \"A\" is + a general band matrix of dimension \"m\" by \"size(A,2)\" with + \"kl\" sub-diagonals and \"ku\" super-diagonals. Returns the + updated \"y\". + +"), + +("Base.LinAlg.BLAS","gbmv","gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + + Returns \"alpha*A*x\" or \"alpha*A'*x\" according to \"trans\" ('N' + or 'T'). The matrix \"A\" is a general band matrix of dimension + \"m\" by \"size(A,2)\" with \"kl\" sub-diagonals and \"ku\" super- + diagonals. + +"), + +("Base.LinAlg.BLAS","sbmv!","sbmv!(uplo, k, alpha, A, x, beta, y) + + Update vector \"y\" as \"alpha*A*x + beta*y\" where \"A\" is a a + symmetric band matrix of order \"size(A,2)\" with \"k\" super- + diagonals stored in the argument \"A\". The storage layout for + \"A\" is described the reference BLAS module, level-2 BLAS at + http://www.netlib.org/lapack/explore-html/. + + Returns the updated \"y\". + +"), + +("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, alpha, A, x) + + Returns \"alpha*A*x\" where \"A\" is a symmetric band matrix of + order \"size(A,2)\" with \"k\" super-diagonals stored in the + argument \"A\". + +"), + +("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, A, x) + + Returns \"A*x\" where \"A\" is a symmetric band matrix of order + \"size(A,2)\" with \"k\" super-diagonals stored in the argument + \"A\". + +"), + +("Base.LinAlg.BLAS","gemm!","gemm!(tA, tB, alpha, A, B, beta, C) + + Update \"C\" as \"alpha*A*B + beta*C\" or the other three variants + according to \"tA\" (transpose \"A\") and \"tB\". Returns the + updated \"C\". + +"), + +("Base.LinAlg.BLAS","gemm","gemm(tA, tB, alpha, A, B) + + Returns \"alpha*A*B\" or the other three variants according to + \"tA\" (transpose \"A\") and \"tB\". + +"), + +("Base.LinAlg.BLAS","gemm","gemm(tA, tB, A, B) + + Returns \"A*B\" or the other three variants according to \"tA\" + (transpose \"A\") and \"tB\". + +"), + +("Base.LinAlg.BLAS","gemv!","gemv!(tA, alpha, A, x, beta, y) + + Update the vector \"y\" as \"alpha*A*x + beta*y\" or \"alpha*A'x + + beta*y\" according to \"tA\" (transpose \"A\"). Returns the updated + \"y\". + +"), + +("Base.LinAlg.BLAS","gemv","gemv(tA, alpha, A, x) + + Returns \"alpha*A*x\" or \"alpha*A'x\" according to \"tA\" + (transpose \"A\"). + +"), + +("Base.LinAlg.BLAS","gemv","gemv(tA, A, x) + + Returns \"A*x\" or \"A'x\" according to \"tA\" (transpose \"A\"). + +"), + +("Base.LinAlg.BLAS","symm!","symm!(side, ul, alpha, A, B, beta, C) + + Update \"C\" as \"alpha*A*B + beta*C\" or \"alpha*B*A + beta*C\" + according to \"side\". \"A\" is assumed to be symmetric. Only the + \"ul\" triangle of \"A\" is used. Returns the updated \"C\". + +"), + +("Base.LinAlg.BLAS","symm","symm(side, ul, alpha, A, B) + + Returns \"alpha*A*B\" or \"alpha*B*A\" according to \"side\". \"A\" + is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is + used. + +"), + +("Base.LinAlg.BLAS","symm","symm(side, ul, A, B) + + Returns \"A*B\" or \"B*A\" according to \"side\". \"A\" is assumed + to be symmetric. Only the \"ul\" triangle of \"A\" is used. + +"), + +("Base.LinAlg.BLAS","symm","symm(tA, tB, alpha, A, B) + + Returns \"alpha*A*B\" or the other three variants according to + \"tA\" (transpose \"A\") and \"tB\". + +"), + +("Base.LinAlg.BLAS","symv!","symv!(ul, alpha, A, x, beta, y) + + Update the vector \"y\" as \"alpha*A*x + beta*y\". \"A\" is assumed + to be symmetric. Only the \"ul\" triangle of \"A\" is used. + Returns the updated \"y\". + +"), + +("Base.LinAlg.BLAS","symv","symv(ul, alpha, A, x) + + Returns \"alpha*A*x\". \"A\" is assumed to be symmetric. Only the + \"ul\" triangle of \"A\" is used. + +"), + +("Base.LinAlg.BLAS","symv","symv(ul, A, x) + + Returns \"A*x\". \"A\" is assumed to be symmetric. Only the + \"ul\" triangle of \"A\" is used. + +"), + +("Base.LinAlg.BLAS","trmm!","trmm!(side, ul, tA, dA, alpha, A, B) + + Update \"B\" as \"alpha*A*B\" or one of the other three variants + determined by \"side\" (A on left or right) and \"tA\" (transpose + A). Only the \"ul\" triangle of \"A\" is used. \"dA\" indicates if + \"A\" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated \"B\". + +"), + +("Base.LinAlg.BLAS","trmm","trmm(side, ul, tA, dA, alpha, A, B) + + Returns \"alpha*A*B\" or one of the other three variants determined + by \"side\" (A on left or right) and \"tA\" (transpose A). Only the + \"ul\" triangle of \"A\" is used. \"dA\" indicates if \"A\" is + unit-triangular (the diagonal is assumed to be all ones). + +"), + +("Base.LinAlg.BLAS","trsm!","trsm!(side, ul, tA, dA, alpha, A, B) + + Overwrite \"B\" with the solution to \"A*X = alpha*B\" or one of + the other three variants determined by \"side\" (A on left or right + of \"X\") and \"tA\" (transpose A). Only the \"ul\" triangle of + \"A\" is used. \"dA\" indicates if \"A\" is unit-triangular (the + diagonal is assumed to be all ones). Returns the updated \"B\". + +"), + +("Base.LinAlg.BLAS","trsm","trsm(side, ul, tA, dA, alpha, A, B) + + Returns the solution to \"A*X = alpha*B\" or one of the other three + variants determined by \"side\" (A on left or right of \"X\") and + \"tA\" (transpose A). Only the \"ul\" triangle of \"A\" is used. + \"dA\" indicates if \"A\" is unit-triangular (the diagonal is + assumed to be all ones). + +"), + +("Base.LinAlg.BLAS","trmv!","trmv!(side, ul, tA, dA, alpha, A, b) + + Update \"b\" as \"alpha*A*b\" or one of the other three variants + determined by \"side\" (A on left or right) and \"tA\" (transpose + A). Only the \"ul\" triangle of \"A\" is used. \"dA\" indicates if + \"A\" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated \"b\". + +"), + +("Base.LinAlg.BLAS","trmv","trmv(side, ul, tA, dA, alpha, A, b) + + Returns \"alpha*A*b\" or one of the other three variants determined + by \"side\" (A on left or right) and \"tA\" (transpose A). Only the + \"ul\" triangle of \"A\" is used. \"dA\" indicates if \"A\" is + unit-triangular (the diagonal is assumed to be all ones). + +"), + +("Base.LinAlg.BLAS","trsv!","trsv!(ul, tA, dA, A, b) + + Overwrite \"b\" with the solution to \"A*x = b\" or one of the + other two variants determined by \"tA\" (transpose A) and \"ul\" + (triangle of \"A\" used). \"dA\" indicates if \"A\" is unit- + triangular (the diagonal is assumed to be all ones). Returns the + updated \"b\". + +"), + +("Base.LinAlg.BLAS","trsv","trsv(ul, tA, dA, A, b) + + Returns the solution to \"A*x = b\" or one of the other two + variants determined by \"tA\" (transpose A) and \"ul\" (triangle of + \"A\" is used.) \"dA\" indicates if \"A\" is unit-triangular (the + diagonal is assumed to be all ones). + +"), + +("Base.LinAlg.BLAS","blas_set_num_threads","blas_set_num_threads(n) + + Set the number of threads the BLAS library should use. + +"), + +("Base.LinAlg.BLAS","I","I + + An object of type \"UniformScaling\", representing an identity + matrix of any size. + +"), + +("Base","-","-(x) + + Unary minus operator. + +"), + +("Base","+","+(x, y...) + + Addition operator. \"x+y+z+...\" calls this function with all + arguments, i.e. \"+(x, y, z, ...)\". + +"), + +("Base","-","-(x, y) + + Subtraction operator. + +"), + +("Base","*","*(x, y...) + + Multiplication operator. \"x*y*z*...\" calls this function with all + arguments, i.e. \"*(x, y, z, ...)\". + +"), + +("Base","/","/(x, y) + + Right division operator: multiplication of \"x\" by the inverse of + \"y\" on the right. Gives floating-point results for integer + arguments. + +"), + +("Base","\\","\\(x, y) + + Left division operator: multiplication of \"y\" by the inverse of + \"x\" on the left. Gives floating-point results for integer + arguments. + +"), + +("Base","^","^(x, y) + + Exponentiation operator. + +"), + +("Base",".+",".+(x, y) + + Element-wise addition operator. + +"), + +("Base",".-",".-(x, y) + + Element-wise subtraction operator. + +"), + +("Base",".*",".*(x, y) + + Element-wise multiplication operator. + +"), + +("Base","./","./(x, y) + + Element-wise right division operator. + +"), + +("Base",".\\",".\\(x, y) + + Element-wise left division operator. + +"), + +("Base",".^",".^(x, y) + + Element-wise exponentiation operator. + +"), + +("Base","fma","fma(x, y, z) + + Computes \"x*y+z\" without rounding the intermediate result + \"x*y\". On some systems this is significantly more expensive than + \"x*y+z\". \"fma\" is used to improve accuracy in certain + algorithms. See \"muladd\". + +"), + +("Base","muladd","muladd(x, y, z) + + Combined multiply-add, computes \"x*y+z\" in an efficient manner. + This may on some systems be equivalent to \"x*y+z\", or to + \"fma(x,y,z)\". \"muladd\" is used to improve performance. See + \"fma\". + +"), + +("Base","div","div(x, y) +÷(x, y) + + The quotient from Euclidean division. Computes \"x/y\", truncated + to an integer. + +"), + +("Base","fld","fld(x, y) + + Largest integer less than or equal to \"x/y\". + +"), + +("Base","cld","cld(x, y) + + Smallest integer larger than or equal to \"x/y\". + +"), + +("Base","mod","mod(x, y) + + Modulus after division, returning in the range [0,``y``), if \"y\" + is positive, or (\"y\",0] if \"y\" is negative. + +"), + +("Base","mod2pi","mod2pi(x) + + Modulus after division by 2pi, returning in the range [0,2pi). + + This function computes a floating point representation of the + modulus after division by numerically exact 2pi, and is therefore + not exactly the same as mod(x,2pi), which would compute the modulus + of x relative to division by the floating-point number 2pi. + +"), + +("Base","rem","rem(x, y) +%(x, y) + + Remainder from Euclidean division, returning a value of the same + sign as``x``, and smaller in magnitude than \"y\". This value is + always exact. + +"), + +("Base","divrem","divrem(x, y) + + The quotient and remainder from Euclidean division. Equivalent to + \"(x÷y, x%y)\". + +"), + +("Base","fldmod","fldmod(x, y) + + The floored quotient and modulus after division. Equivalent to + \"(fld(x,y), mod(x,y))\". + +"), + +("Base","mod1","mod1(x, m) + + Modulus after division, returning in the range (0,m] + +"), + +("Base","rem1","rem1(x, m) + + Remainder after division, returning in the range (0,m] + +"), + +("Base","//","//(num, den) + + Divide two integers or rational numbers, giving a \"Rational\" + result. + +"), + +("Base","rationalize","rationalize([Type=Int], x; tol=eps(x)) + + Approximate floating point number \"x\" as a Rational number with + components of the given integer type. The result will differ from + \"x\" by no more than \"tol\". + +"), + +("Base","num","num(x) + + Numerator of the rational representation of \"x\" + +"), + +("Base","den","den(x) + + Denominator of the rational representation of \"x\" + +"), + +("Base","<<","<<(x, n) + + Left bit shift operator. + +"), + +("Base",">>",">>(x, n) + + Right bit shift operator, preserving the sign of \"x\". + +"), + +("Base",">>>",">>>(x, n) + + Unsigned right bit shift operator. + +"), + +("Base",":",":(start[, step], stop) + + Range operator. \"a:b\" constructs a range from \"a\" to \"b\" with + a step size of 1, and \"a:s:b\" is similar but uses a step size of + \"s\". These syntaxes call the function \"colon\". The colon is + also used in indexing to select whole dimensions. + +"), + +("Base","colon","colon(start[, step], stop) + + Called by \":\" syntax for constructing ranges. + +"), + +("Base","range","range(start[, step], length) + + Construct a range by length, given a starting value and optional + step (defaults to 1). + +"), + +("Base","==","==(x, y) + + Generic equality operator, giving a single \"Bool\" result. Falls + back to \"===\". Should be implemented for all types with a notion + of equality, based on the abstract value that an instance + represents. For example, all numeric types are compared by numeric + value, ignoring type. Strings are compared as sequences of + characters, ignoring encoding. + + Follows IEEE semantics for floating-point numbers. + + Collections should generally implement \"==\" by calling \"==\" + recursively on all contents. + + New numeric types should implement this function for two arguments + of the new type, and handle comparison to other types via promotion + rules where possible. + +"), + +("Base","!=","!=(x, y) +≠(x, y) + + Not-equals comparison operator. Always gives the opposite answer as + \"==\". New types should generally not implement this, and rely on + the fallback definition \"!=(x,y) = !(x==y)\" instead. + +"), + +("Base","===","===(x, y) +≡(x, y) + + See the \"is()\" operator + +"), + +("Base","!==","!==(x, y) +≢(x, y) + + Equivalent to \"!is(x, y)\" + +"), + +("Base","<","<(x, y) + + Less-than comparison operator. New numeric types should implement + this function for two arguments of the new type. Because of the + behavior of floating-point NaN values, \"<\" implements a partial + order. Types with a canonical partial order should implement \"<\", + and types with a canonical total order should implement \"isless\". + +"), + +("Base","<=","<=(x, y) +≤(x, y) + + Less-than-or-equals comparison operator. + +"), + +("Base",">",">(x, y) + + Greater-than comparison operator. Generally, new types should + implement \"<\" instead of this function, and rely on the fallback + definition \">(x,y) = y=",">=(x, y) +≥(x, y) + + Greater-than-or-equals comparison operator. + +"), + +("Base",".==",".==(x, y) + + Element-wise equality comparison operator. + +"), + +("Base",".!=",".!=(x, y) +.≠(x, y) + + Element-wise not-equals comparison operator. + +"), + +("Base",".<",".<(x, y) + + Element-wise less-than comparison operator. + +"), + +("Base",".<=",".<=(x, y) +.≤(x, y) + + Element-wise less-than-or-equals comparison operator. + +"), + +("Base",".>",".>(x, y) + + Element-wise greater-than comparison operator. + +"), + +("Base",".>=",".>=(x, y) +.≥(x, y) + + Element-wise greater-than-or-equals comparison operator. + +"), + +("Base","cmp","cmp(x, y) + + Return -1, 0, or 1 depending on whether \"x\" is less than, equal + to, or greater than \"y\", respectively. Uses the total order + implemented by \"isless\". For floating-point numbers, uses \"<\" + but throws an error for unordered arguments. + +"), + +("Base","~","~(x) + + Bitwise not + +"), + +("Base","&","&(x, y) + + Bitwise and + +"), + +("Base","|","|(x, y) + + Bitwise or + +"), + +("Base","\$","\$(x, y) + + Bitwise exclusive or + +"), + +("Base","!","!(x) + + Boolean not + +"), + +("","x && y","x && y + + Short-circuiting boolean and + +"), + +("","x || y","x || y + + Short-circuiting boolean or + +"), + +("Base","A_ldiv_Bc","A_ldiv_Bc(a, b) + + Matrix operator A \\ B^H + +"), + +("Base","A_ldiv_Bt","A_ldiv_Bt(a, b) + + Matrix operator A \\ B^T + +"), + +("Base","A_mul_B!","A_mul_B!(Y, A, B) -> Y + + Calculates the matrix-matrix or matrix-vector product *A B* and + stores the result in *Y*, overwriting the existing value of *Y*. + + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); + + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 + +"), + +("Base","A_mul_Bc","A_mul_Bc(...) + + Matrix operator A B^H + +"), + +("Base","A_mul_Bt","A_mul_Bt(...) + + Matrix operator A B^T + +"), + +("Base","A_rdiv_Bc","A_rdiv_Bc(...) + + Matrix operator A / B^H + +"), + +("Base","A_rdiv_Bt","A_rdiv_Bt(a, b) + + Matrix operator A / B^T + +"), + +("Base","Ac_ldiv_B","Ac_ldiv_B(...) + + Matrix operator A^H \\ B + +"), + +("Base","Ac_ldiv_Bc","Ac_ldiv_Bc(...) + + Matrix operator A^H \\ B^H + +"), + +("Base","Ac_mul_B","Ac_mul_B(...) + + Matrix operator A^H B + +"), + +("Base","Ac_mul_Bc","Ac_mul_Bc(...) + + Matrix operator A^H B^H + +"), + +("Base","Ac_rdiv_B","Ac_rdiv_B(a, b) + + Matrix operator A^H / B + +"), + +("Base","Ac_rdiv_Bc","Ac_rdiv_Bc(a, b) + + Matrix operator A^H / B^H + +"), + +("Base","At_ldiv_B","At_ldiv_B(...) + + Matrix operator A^T \\ B + +"), + +("Base","At_ldiv_Bt","At_ldiv_Bt(...) + + Matrix operator A^T \\ B^T + +"), + +("Base","At_mul_B","At_mul_B(...) + + Matrix operator A^T B + +"), + +("Base","At_mul_Bt","At_mul_Bt(...) + + Matrix operator A^T B^T + +"), + +("Base","At_rdiv_B","At_rdiv_B(a, b) + + Matrix operator A^T / B + +"), + +("Base","At_rdiv_Bt","At_rdiv_Bt(a, b) + + Matrix operator A^T / B^T + +"), + +("Base","isapprox","isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + + Inexact equality comparison - behaves slightly different depending + on types of input args: + + * For \"FloatingPoint\" numbers, \"isapprox\" returns \"true\" if + \"abs(x-y) <= atol + rtol*max(abs(x), abs(y))\". + + * For \"Integer\" and \"Rational\" numbers, \"isapprox\" returns + \"true\" if \"abs(x-y) <= atol\". The *rtol* argument is ignored. + If one of \"x\" and \"y\" is \"FloatingPoint\", the other is + promoted, and the method above is called instead. + + * For \"Complex\" numbers, the distance in the complex plane is + compared, using the same criterion as above. + + For default tolerance arguments, \"maxeps = max(eps(abs(x)), + eps(abs(y)))\". + +"), + +("Base","sin","sin(x) + + Compute sine of \"x\", where \"x\" is in radians + +"), + +("Base","cos","cos(x) + + Compute cosine of \"x\", where \"x\" is in radians + +"), + +("Base","tan","tan(x) + + Compute tangent of \"x\", where \"x\" is in radians + +"), + +("Base","sind","sind(x) + + Compute sine of \"x\", where \"x\" is in degrees + +"), + +("Base","cosd","cosd(x) + + Compute cosine of \"x\", where \"x\" is in degrees + +"), + +("Base","tand","tand(x) + + Compute tangent of \"x\", where \"x\" is in degrees + +"), + +("Base","sinpi","sinpi(x) + + Compute \\sin(\\pi x) more accurately than \"sin(pi*x)\", + especially for large \"x\". + +"), + +("Base","cospi","cospi(x) + + Compute \\cos(\\pi x) more accurately than \"cos(pi*x)\", + especially for large \"x\". + +"), + +("Base","sinh","sinh(x) + + Compute hyperbolic sine of \"x\" + +"), + +("Base","cosh","cosh(x) + + Compute hyperbolic cosine of \"x\" + +"), + +("Base","tanh","tanh(x) + + Compute hyperbolic tangent of \"x\" + +"), + +("Base","asin","asin(x) + + Compute the inverse sine of \"x\", where the output is in radians + +"), + +("Base","acos","acos(x) + + Compute the inverse cosine of \"x\", where the output is in radians + +"), + +("Base","atan","atan(x) + + Compute the inverse tangent of \"x\", where the output is in + radians + +"), + +("Base","atan2","atan2(y, x) + + Compute the inverse tangent of \"y/x\", using the signs of both + \"x\" and \"y\" to determine the quadrant of the return value. + +"), + +("Base","asind","asind(x) + + Compute the inverse sine of \"x\", where the output is in degrees + +"), + +("Base","acosd","acosd(x) + + Compute the inverse cosine of \"x\", where the output is in degrees + +"), + +("Base","atand","atand(x) + + Compute the inverse tangent of \"x\", where the output is in + degrees + +"), + +("Base","sec","sec(x) + + Compute the secant of \"x\", where \"x\" is in radians + +"), + +("Base","csc","csc(x) + + Compute the cosecant of \"x\", where \"x\" is in radians + +"), + +("Base","cot","cot(x) + + Compute the cotangent of \"x\", where \"x\" is in radians + +"), + +("Base","secd","secd(x) + + Compute the secant of \"x\", where \"x\" is in degrees + +"), + +("Base","cscd","cscd(x) + + Compute the cosecant of \"x\", where \"x\" is in degrees + +"), + +("Base","cotd","cotd(x) + + Compute the cotangent of \"x\", where \"x\" is in degrees + +"), + +("Base","asec","asec(x) + + Compute the inverse secant of \"x\", where the output is in radians + +"), + +("Base","acsc","acsc(x) + + Compute the inverse cosecant of \"x\", where the output is in + radians + +"), + +("Base","acot","acot(x) + + Compute the inverse cotangent of \"x\", where the output is in + radians + +"), + +("Base","asecd","asecd(x) + + Compute the inverse secant of \"x\", where the output is in degrees + +"), + +("Base","acscd","acscd(x) + + Compute the inverse cosecant of \"x\", where the output is in + degrees + +"), + +("Base","acotd","acotd(x) + + Compute the inverse cotangent of \"x\", where the output is in + degrees + +"), + +("Base","sech","sech(x) + + Compute the hyperbolic secant of \"x\" + +"), + +("Base","csch","csch(x) + + Compute the hyperbolic cosecant of \"x\" + +"), + +("Base","coth","coth(x) + + Compute the hyperbolic cotangent of \"x\" + +"), + +("Base","asinh","asinh(x) + + Compute the inverse hyperbolic sine of \"x\" + +"), + +("Base","acosh","acosh(x) + + Compute the inverse hyperbolic cosine of \"x\" + +"), + +("Base","atanh","atanh(x) + + Compute the inverse hyperbolic tangent of \"x\" + +"), + +("Base","asech","asech(x) + + Compute the inverse hyperbolic secant of \"x\" + +"), + +("Base","acsch","acsch(x) + + Compute the inverse hyperbolic cosecant of \"x\" + +"), + +("Base","acoth","acoth(x) + + Compute the inverse hyperbolic cotangent of \"x\" + +"), + +("Base","sinc","sinc(x) + + Compute \\sin(\\pi x) / (\\pi x) if x \\neq 0, and 1 if x = 0. + +"), + +("Base","cosc","cosc(x) + + Compute \\cos(\\pi x) / x - \\sin(\\pi x) / (\\pi x^2) if x \\neq + 0, and 0 if x = 0. This is the derivative of \"sinc(x)\". + +"), + +("Base","deg2rad","deg2rad(x) + + Convert \"x\" from degrees to radians + +"), + +("Base","rad2deg","rad2deg(x) + + Convert \"x\" from radians to degrees + +"), + +("Base","hypot","hypot(x, y) + + Compute the \\sqrt{x^2+y^2} avoiding overflow and underflow + +"), + +("Base","log","log(x) + + Compute the natural logarithm of \"x\". Throws \"DomainError\" for + negative \"Real\" arguments. Use complex negative arguments to + obtain complex results. + + There is an experimental variant in the \"Base.Math.JuliaLibm\" + module, which is typically faster and more accurate. + +"), + +("Base","log","log(b, x) + + Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" + for negative \"Real\" arguments. + +"), + +("Base","log2","log2(x) + + Compute the logarithm of \"x\" to base 2. Throws \"DomainError\" + for negative \"Real\" arguments. + +"), + +("Base","log10","log10(x) + + Compute the logarithm of \"x\" to base 10. Throws \"DomainError\" + for negative \"Real\" arguments. + +"), + +("Base","log1p","log1p(x) + + Accurate natural logarithm of \"1+x\". Throws \"DomainError\" for + \"Real\" arguments less than -1. + + There is an experimental variant in the \"Base.Math.JuliaLibm\" + module, which is typically faster and more accurate. + +"), + +("Base","frexp","frexp(val) + + Return \"(x,exp)\" such that \"x\" has a magnitude in the interval + \"[1/2, 1)\" or 0, and val = x \\times 2^{exp}. + +"), + +("Base","exp","exp(x) + + Compute e^x + +"), + +("Base","exp2","exp2(x) + + Compute 2^x + +"), + +("Base","exp10","exp10(x) + + Compute 10^x + +"), + +("Base","ldexp","ldexp(x, n) + + Compute x \\times 2^n + +"), + +("Base","modf","modf(x) + + Return a tuple (fpart,ipart) of the fractional and integral parts + of a number. Both parts have the same sign as the argument. + +"), + +("Base","expm1","expm1(x) + + Accurately compute e^x-1 + +"), + +("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) + + \"round(x)\" rounds \"x\" to an integer value according to the + default rounding mode (see \"get_rounding()\"), returning a value + of the same type as \"x\". By default (\"RoundNearest\"), this will + round to the nearest integer, with ties (fractional values of 0.5) + being rounded to the even integer. + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional \"RoundingMode\" argument will change how the number + gets rounded. + + \"round(T, x, [r::RoundingMode])\" converts the result to type + \"T\", throwing an \"InexactError\" if the value is not + representable. + + \"round(x, digits)\" rounds to the specified number of digits after + the decimal place (or before if negative). \"round(x, digits, + base)\" rounds using a base other than 10. + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the \"Float64\" value represented by \"1.15\" is + actually *less* than 1.15, yet will be rounded to 1.2. + + julia> x = 1.15 + 1.15 + + julia> @sprintf \"%.20f\" x + \"1.14999999999999991118\" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + +"), + +("Base","RoundingMode","RoundingMode + + A type which controls rounding behavior. Currently supported + rounding modes are: + + * \"RoundNearest\" (default) + + * \"RoundNearestTiesAway\" + + * \"RoundNearestTiesUp\" + + * \"RoundToZero\" + + * \"RoundUp\" + + * \"RoundDown\" + +"), + +("Base","RoundNearest","RoundNearest + + The default rounding mode. Rounds to the nearest integer, with ties + (fractional values of 0.5) being rounded to the nearest even + integer. + +"), + +("Base","RoundNearestTiesAway","RoundNearestTiesAway + + Rounds to nearest integer, with ties rounded away from zero (C/C++ + \"round()\" behaviour). + +"), + +("Base","RoundNearestTiesUp","RoundNearestTiesUp + + Rounds to nearest integer, with ties rounded toward positive + infinity (Java/JavaScript \"round()\" behaviour). + +"), + +("Base","RoundToZero","RoundToZero + + \"round()\" using this rounding mode is an alias for \"trunc()\". + +"), + +("Base","RoundUp","RoundUp + + \"round()\" using this rounding mode is an alias for \"ceil()\". + +"), + +("Base","RoundDown","RoundDown + + \"round()\" using this rounding mode is an alias for \"floor()\". + +"), + +("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) + + Returns the nearest integral value of the same type as the complex- + valued \"z\" to \"z\", breaking ties using the specified + \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding + the real components while the second is used for rounding the + imaginary components. + +"), + +("Base","ceil","ceil([T], x[, digits[, base]]) + + \"ceil(x)\" returns the nearest integral value of the same type as + \"x\" that is greater than or equal to \"x\". + + \"ceil(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. + + \"digits\" and \"base\" work as for \"round()\". + +"), + +("Base","floor","floor([T], x[, digits[, base]]) + + \"floor(x)\" returns the nearest integral value of the same type as + \"x\" that is less than or equal to \"x\". + + \"floor(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. + + \"digits\" and \"base\" work as for \"round()\". + +"), + +("Base","trunc","trunc([T], x[, digits[, base]]) + + \"trunc(x)\" returns the nearest integral value of the same type as + \"x\" whose absolute value is less than or equal to \"x\". + + \"trunc(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. + + \"digits\" and \"base\" work as for \"round()\". + +"), + +("Base","unsafe_trunc","unsafe_trunc(T, x) + + \"unsafe_trunc(T, x)\" returns the nearest integral value of type + \"T\" whose absolute value is less than or equal to \"x\". If the + value is not representable by \"T\", an arbitrary value will be + returned. + +"), + +("Base","signif","signif(x, digits[, base]) + + Rounds (in the sense of \"round\") \"x\" so that there are + \"digits\" significant digits, under a base \"base\" + representation, default 10. E.g., \"signif(123.456, 2)\" is + \"120.0\", and \"signif(357.913, 4, 2)\" is \"352.0\". + +"), + +("Base","min","min(x, y, ...) + + Return the minimum of the arguments. Operates elementwise over + arrays. + +"), + +("Base","max","max(x, y, ...) + + Return the maximum of the arguments. Operates elementwise over + arrays. + +"), + +("Base","minmax","minmax(x, y) + + Return \"(min(x,y), max(x,y))\". See also: \"extrema()\" that + returns \"(minimum(x), maximum(x))\" + +"), + +("Base","clamp","clamp(x, lo, hi) + + Return x if \"lo <= x <= hi\". If \"x < lo\", return \"lo\". If \"x + > hi\", return \"hi\". Arguments are promoted to a common type. + Operates elementwise over \"x\" if it is an array. + +"), + +("Base","abs","abs(x) + + Absolute value of \"x\" + +"), + +("Base","abs2","abs2(x) + + Squared absolute value of \"x\" + +"), + +("Base","copysign","copysign(x, y) + + Return \"x\" such that it has the same sign as \"y\" + +"), + +("Base","sign","sign(x) + + Return \"+1\" if \"x\" is positive, \"0\" if \"x == 0\", and \"-1\" + if \"x\" is negative. + +"), + +("Base","signbit","signbit(x) + + Returns \"true\" if the value of the sign of \"x\" is negative, + otherwise \"false\". + +"), + +("Base","flipsign","flipsign(x, y) + + Return \"x\" with its sign flipped if \"y\" is negative. For + example \"abs(x) = flipsign(x,x)\". + +"), + +("Base","sqrt","sqrt(x) + + Return \\sqrt{x}. Throws \"DomainError\" for negative \"Real\" + arguments. Use complex negative arguments instead. The prefix + operator \"√\" is equivalent to \"sqrt\". + +"), + +("Base","isqrt","isqrt(n) + + Integer square root: the largest integer \"m\" such that \"m*m <= + n\". + +"), + +("Base","cbrt","cbrt(x) + + Return x^{1/3}. The prefix operator \"∛\" is equivalent to + \"cbrt\". + +"), + +("Base","erf","erf(x) + + Compute the error function of \"x\", defined by + \\frac{2}{\\sqrt{\\pi}} \\int_0^x e^{-t^2} dt for arbitrary complex + \"x\". + +"), + +("Base","erfc","erfc(x) + + Compute the complementary error function of \"x\", defined by 1 - + \\operatorname{erf}(x). + +"), + +("Base","erfcx","erfcx(x) + + Compute the scaled complementary error function of \"x\", defined + by e^{x^2} \\operatorname{erfc}(x). Note also that + \\operatorname{erfcx}(-ix) computes the Faddeeva function w(x). + +"), + +("Base","erfi","erfi(x) + + Compute the imaginary error function of \"x\", defined by -i + \\operatorname{erf}(ix). + +"), + +("Base","dawson","dawson(x) + + Compute the Dawson function (scaled imaginary error function) of + \"x\", defined by \\frac{\\sqrt{\\pi}}{2} e^{-x^2} + \\operatorname{erfi}(x). + +"), + +("Base","erfinv","erfinv(x) + + Compute the inverse error function of a real \"x\", defined by + \\operatorname{erf}(\\operatorname{erfinv}(x)) = x. + +"), + +("Base","erfcinv","erfcinv(x) + + Compute the inverse error complementary function of a real \"x\", + defined by \\operatorname{erfc}(\\operatorname{erfcinv}(x)) = x. + +"), + +("Base","real","real(z) + + Return the real part of the complex number \"z\" + +"), + +("Base","imag","imag(z) + + Return the imaginary part of the complex number \"z\" + +"), + +("Base","reim","reim(z) + + Return both the real and imaginary parts of the complex number + \"z\" + +"), + +("Base","conj","conj(z) + + Compute the complex conjugate of a complex number \"z\" + +"), + +("Base","angle","angle(z) + + Compute the phase angle in radians of a complex number \"z\" + +"), + +("Base","cis","cis(z) + + Return \\exp(iz). + +"), + +("Base","binomial","binomial(n, k) + + Number of ways to choose \"k\" out of \"n\" items + +"), + +("Base","factorial","factorial(n) + + Factorial of \"n\". If \"n\" is an \"Integer\", the factorial is + computed as an integer (promoted to at least 64 bits). Note that + this may overflow if \"n\" is not small, but you can use + \"factorial(big(n))\" to compute the result exactly in arbitrary + precision. If \"n\" is not an \"Integer\", \"factorial(n)\" is + equivalent to \"gamma(n+1)\". + +"), + +("Base","factorial","factorial(n, k) + + Compute \"factorial(n)/factorial(k)\" + +"), + +("Base","factor","factor(n) -> Dict + + Compute the prime factorization of an integer \"n\". Returns a + dictionary. The keys of the dictionary correspond to the factors, + and hence are of the same type as \"n\". The value associated with + each key indicates the number of times the factor appears in the + factorization. + + julia> factor(100) # == 2*2*5*5 + Dict{Int64,Int64} with 2 entries: + 2 => 2 + 5 => 2 + +"), + +("Base","gcd","gcd(x, y) + + Greatest common (positive) divisor (or zero if x and y are both + zero). + +"), + +("Base","lcm","lcm(x, y) + + Least common (non-negative) multiple. + +"), + +("Base","gcdx","gcdx(x, y) + + Computes the greatest common (positive) divisor of \"x\" and \"y\" + and their Bézout coefficients, i.e. the integer coefficients \"u\" + and \"v\" that satisfy ux+vy = d = gcd(x,y). + + julia> gcdx(12, 42) + (6,-3,1) + + julia> gcdx(240, 46) + (2,-9,47) + + Note: Bézout coefficients are *not* uniquely defined. \"gcdx\" + returns the minimal Bézout coefficients that are computed by the + extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, + Algorithm X.) These coefficients \"u\" and \"v\" are minimal in + the sense that |u| < |\\frac y d and |v| < |\\frac x d. + Furthermore, the signs of \"u\" and \"v\" are chosen so that + \"d\" is positive. + +"), + +("Base","ispow2","ispow2(n) -> Bool + + Test whether \"n\" is a power of two + +"), + +("Base","nextpow2","nextpow2(n) + + The smallest power of two not less than \"n\". Returns 0 for + \"n==0\", and returns \"-nextpow2(-n)\" for negative arguments. + +"), + +("Base","prevpow2","prevpow2(n) + + The largest power of two not greater than \"n\". Returns 0 for + \"n==0\", and returns \"-prevpow2(-n)\" for negative arguments. + +"), + +("Base","nextpow","nextpow(a, x) + + The smallest \"a^n\" not less than \"x\", where \"n\" is a non- + negative integer. \"a\" must be greater than 1, and \"x\" must be + greater than 0. + +"), + +("Base","prevpow","prevpow(a, x) + + The largest \"a^n\" not greater than \"x\", where \"n\" is a non- + negative integer. \"a\" must be greater than 1, and \"x\" must not + be less than 1. + +"), + +("Base","nextprod","nextprod([k_1, k_2, ...], n) + + Next integer not less than \"n\" that can be written as \\prod + k_i^{p_i} for integers p_1, p_2, etc. + +"), + +("Base","prevprod","prevprod([k_1, k_2, ...], n) + + Previous integer not greater than \"n\" that can be written as + \\prod k_i^{p_i} for integers p_1, p_2, etc. + +"), + +("Base","invmod","invmod(x, m) + + Take the inverse of \"x\" modulo \"m\": \"y\" such that xy = 1 + \\pmod m + +"), + +("Base","powermod","powermod(x, p, m) + + Compute x^p \\pmod m + +"), + +("Base","gamma","gamma(x) + + Compute the gamma function of \"x\" + +"), + +("Base","lgamma","lgamma(x) + + Compute the logarithm of the absolute value of \"gamma()\" for + \"Real\" \"x\", while for \"Complex\" \"x\" it computes the + logarithm of \"gamma(x)\". + +"), + +("Base","lfact","lfact(x) + + Compute the logarithmic factorial of \"x\" + +"), + +("Base","digamma","digamma(x) + + Compute the digamma function of \"x\" (the logarithmic derivative + of \"gamma(x)\") + +"), + +("Base","invdigamma","invdigamma(x) + + Compute the inverse digamma function of \"x\". + +"), + +("Base","trigamma","trigamma(x) + + Compute the trigamma function of \"x\" (the logarithmic second + derivative of \"gamma(x)\") + +"), + +("Base","polygamma","polygamma(m, x) + + Compute the polygamma function of order \"m\" of argument \"x\" + (the \"(m+1)th\" derivative of the logarithm of \"gamma(x)\") + +"), + +("Base","airy","airy(k, x) + + kth derivative of the Airy function \\operatorname{Ai}(x). + +"), + +("Base","airyai","airyai(x) + + Airy function \\operatorname{Ai}(x). + +"), + +("Base","airyprime","airyprime(x) + + Airy function derivative \\operatorname{Ai}'(x). + +"), + +("Base","airyaiprime","airyaiprime(x) + + Airy function derivative \\operatorname{Ai}'(x). + +"), + +("Base","airybi","airybi(x) + + Airy function \\operatorname{Bi}(x). + +"), + +("Base","airybiprime","airybiprime(x) + + Airy function derivative \\operatorname{Bi}'(x). + +"), + +("Base","airyx","airyx(k, x) + + scaled kth derivative of the Airy function, return + \\operatorname{Ai}(x) e^{\\frac{2}{3} x \\sqrt{x}} for \"k == 0 || + k == 1\", and \\operatorname{Ai}(x) e^{- \\left| \\operatorname{Re} + \\left( \\frac{2}{3} x \\sqrt{x} \\right) \\right|} for \"k == 2 || + k == 3\". + +"), + +("Base","besselj0","besselj0(x) + + Bessel function of the first kind of order 0, J_0(x). + +"), + +("Base","besselj1","besselj1(x) + + Bessel function of the first kind of order 1, J_1(x). + +"), + +("Base","besselj","besselj(nu, x) + + Bessel function of the first kind of order \"nu\", J_\\nu(x). + +"), + +("Base","besseljx","besseljx(nu, x) + + Scaled Bessel function of the first kind of order \"nu\", J_\\nu(x) + e^{- | \\operatorname{Im}(x) |}. + +"), + +("Base","bessely0","bessely0(x) + + Bessel function of the second kind of order 0, Y_0(x). + +"), + +("Base","bessely1","bessely1(x) + + Bessel function of the second kind of order 1, Y_1(x). + +"), + +("Base","bessely","bessely(nu, x) + + Bessel function of the second kind of order \"nu\", Y_\\nu(x). + +"), + +("Base","besselyx","besselyx(nu, x) + + Scaled Bessel function of the second kind of order \"nu\", + Y_\\nu(x) e^{- | \\operatorname{Im}(x) |}. + +"), + +("Base","hankelh1","hankelh1(nu, x) + + Bessel function of the third kind of order \"nu\", H^{(1)}_\\nu(x). + +"), + +("Base","hankelh1x","hankelh1x(nu, x) + + Scaled Bessel function of the third kind of order \"nu\", + H^{(1)}_\\nu(x) e^{-x i}. + +"), + +("Base","hankelh2","hankelh2(nu, x) + + Bessel function of the third kind of order \"nu\", H^{(2)}_\\nu(x). + +"), + +("Base","hankelh2x","hankelh2x(nu, x) + + Scaled Bessel function of the third kind of order \"nu\", + H^{(2)}_\\nu(x) e^{x i}. + +"), + +("Base","besselh","besselh(nu, k, x) + + Bessel function of the third kind of order \"nu\" (Hankel + function). \"k\" is either 1 or 2, selecting \"hankelh1\" or + \"hankelh2\", respectively. + +"), + +("Base","besseli","besseli(nu, x) + + Modified Bessel function of the first kind of order \"nu\", + I_\\nu(x). + +"), + +("Base","besselix","besselix(nu, x) + + Scaled modified Bessel function of the first kind of order \"nu\", + I_\\nu(x) e^{- | \\operatorname{Re}(x) |}. + +"), + +("Base","besselk","besselk(nu, x) + + Modified Bessel function of the second kind of order \"nu\", + K_\\nu(x). + +"), + +("Base","besselkx","besselkx(nu, x) + + Scaled modified Bessel function of the second kind of order \"nu\", + K_\\nu(x) e^x. + +"), + +("Base","beta","beta(x, y) + + Euler integral of the first kind \\operatorname{B}(x,y) = + \\Gamma(x)\\Gamma(y)/\\Gamma(x+y). + +"), + +("Base","lbeta","lbeta(x, y) + + Natural logarithm of the absolute value of the beta function + \\log(|\\operatorname{B}(x,y)|). + +"), + +("Base","eta","eta(x) + + Dirichlet eta function \\eta(s) = + \\sum^\\infty_{n=1}(-)^{n-1}/n^{s}. + +"), + +("Base","zeta","zeta(s) + + Riemann zeta function \\zeta(s). + +"), + +("Base","zeta","zeta(s, z) + + Hurwitz zeta function \\zeta(s, z). (This is equivalent to the + Riemann zeta function \\zeta(s) for the case of \"z=1\".) + +"), + +("Base","ndigits","ndigits(n, b) + + Compute the number of digits in number \"n\" written in base \"b\". + +"), + +("Base","widemul","widemul(x, y) + + Multiply \"x\" and \"y\", giving the result as a larger type. + +"), + +("Base","@evalpoly","@evalpoly(z, c...) + + Evaluate the polynomial \\sum_k c[k] z^{k-1} for the coefficients + \"c[1]\", \"c[2]\", ...; that is, the coefficients are given in + ascending order by power of \"z\". This macro expands to efficient + inline code that uses either Horner's method or, for complex \"z\", + a more efficient Goertzel-like algorithm. + +"), + +("Base","mean","mean(v[, region]) + + Compute the mean of whole array \"v\", or optionally along the + dimensions in \"region\". Note: Julia does not ignore \"NaN\" + values in the computation. For applications requiring the handling + of missing data, the \"DataArray\" package is recommended. + +"), + +("Base","mean!","mean!(r, v) + + Compute the mean of \"v\" over the singleton dimensions of \"r\", + and write results to \"r\". + +"), + +("Base","std","std(v[, region]) + + Compute the sample standard deviation of a vector or array \"v\", + optionally along dimensions in \"region\". The algorithm returns an + estimator of the generative distribution's standard deviation under + the assumption that each entry of \"v\" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating \"sqrt(sum((v - mean(v)).^2) / (length(v) - 1))\". + Note: Julia does not ignore \"NaN\" values in the computation. For + applications requiring the handling of missing data, the + \"DataArray\" package is recommended. + +"), + +("Base","stdm","stdm(v, m) + + Compute the sample standard deviation of a vector \"v\" with known + mean \"m\". Note: Julia does not ignore \"NaN\" values in the + computation. + +"), + +("Base","var","var(v[, region]) + + Compute the sample variance of a vector or array \"v\", optionally + along dimensions in \"region\". The algorithm will return an + estimator of the generative distribution's variance under the + assumption that each entry of \"v\" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating \"sum((v - mean(v)).^2) / (length(v) - 1)\". Note: + Julia does not ignore \"NaN\" values in the computation. For + applications requiring the handling of missing data, the + \"DataArray\" package is recommended. + +"), + +("Base","varm","varm(v, m) + + Compute the sample variance of a vector \"v\" with known mean + \"m\". Note: Julia does not ignore \"NaN\" values in the + computation. + +"), + +("Base","middle","middle(x) + + Compute the middle of a scalar value, which is equivalent to \"x\" + itself, but of the type of \"middle(x, x)\" for consistency. + +"), + +("Base","middle","middle(x, y) + + Compute the middle of two reals \"x\" and \"y\", which is + equivalent in both value and type to computing their mean (\"(x + + y) / 2\"). + +"), + +("Base","middle","middle(range) + + Compute the middle of a range, which consists in computing the mean + of its extrema. Since a range is sorted, the mean is performed with + the first and last element. + +"), + +("Base","middle","middle(array) + + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. + +"), + +("Base","median","median(v) + + Compute the median of a vector \"v\". \"NaN\" is returned if the + data contains any \"NaN\" values. For applications requiring the + handling of missing data, the \"DataArrays\" package is + recommended. + +"), + +("Base","median!","median!(v) + + Like \"median\", but may overwrite the input vector. + +"), + +("Base","hist","hist(v[, n]) -> e, counts + + Compute the histogram of \"v\", optionally using approximately + \"n\" bins. The return values are a range \"e\", which correspond + to the edges of the bins, and \"counts\" containing the number of + elements of \"v\" in each bin. Note: Julia does not ignore \"NaN\" + values in the computation. + +"), + +("Base","hist","hist(v, e) -> e, counts + + Compute the histogram of \"v\" using a vector/range \"e\" as the + edges for the bins. The result will be a vector of length + \"length(e) - 1\", such that the element at location \"i\" + satisfies \"sum(e[i] .< v .<= e[i+1])\". Note: Julia does not + ignore \"NaN\" values in the computation. + +"), + +("Base","hist!","hist!(counts, v, e) -> e, counts + + Compute the histogram of \"v\", using a vector/range \"e\" as the + edges for the bins. This function writes the resultant counts to a + pre-allocated array \"counts\". + +"), + +("Base","hist2d","hist2d(M, e1, e2) -> (edge1, edge2, counts) + + Compute a \"2d histogram\" of a set of N points specified by N-by-2 + matrix \"M\". Arguments \"e1\" and \"e2\" are bins for each + dimension, specified either as integer bin counts or vectors of bin + edges. The result is a tuple of \"edge1\" (the bin edges used in + the first dimension), \"edge2\" (the bin edges used in the second + dimension), and \"counts\", a histogram matrix of size + \"(length(edge1)-1, length(edge2)-1)\". Note: Julia does not ignore + \"NaN\" values in the computation. + +"), + +("Base","hist2d!","hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + + Compute a \"2d histogram\" with respect to the bins delimited by + the edges given in \"e1\" and \"e2\". This function writes the + results to a pre-allocated array \"counts\". + +"), + +("Base","histrange","histrange(v, n) + + Compute *nice* bin ranges for the edges of a histogram of \"v\", + using approximately \"n\" bins. The resulting step sizes will be 1, + 2 or 5 multiplied by a power of 10. Note: Julia does not ignore + \"NaN\" values in the computation. + +"), + +("Base","midpoints","midpoints(e) + + Compute the midpoints of the bins with edges \"e\". The result is a + vector/range of length \"length(e) - 1\". Note: Julia does not + ignore \"NaN\" values in the computation. + +"), + +("Base","quantile","quantile(v, p) + + Compute the quantiles of a vector \"v\" at a specified set of + probability values \"p\". Note: Julia does not ignore \"NaN\" + values in the computation. + +"), + +("Base","quantile","quantile(v, p) + + Compute the quantile of a vector \"v\" at the probability \"p\". + Note: Julia does not ignore \"NaN\" values in the computation. + +"), + +("Base","quantile!","quantile!(v, p) + + Like \"quantile\", but overwrites the input vector. + +"), + +("Base","cov","cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + + Compute the Pearson covariance between the vector(s) in \"v1\" and + \"v2\". Here, \"v1\" and \"v2\" can be either vectors or matrices. + + This function accepts three keyword arguments: + + * \"vardim\": the dimension of variables. When \"vardim = 1\", + variables are considered in columns while observations in rows; + when \"vardim = 2\", variables are in rows while observations in + columns. By default, it is set to \"1\". + + * \"corrected\": whether to apply Bessel's correction (divide by + \"n-1\" instead of \"n\"). By default, it is set to \"true\". + + * \"mean\": allow users to supply mean values that are known. By + default, it is set to \"nothing\", which indicates that the + mean(s) are unknown, and the function will compute the mean. + Users can use \"mean=0\" to indicate that the input data are + centered, and hence there's no need to subtract the mean. + + The size of the result depends on the size of \"v1\" and \"v2\". + When both \"v1\" and \"v2\" are vectors, it returns the covariance + between them as a scalar. When either one is a matrix, it returns a + covariance matrix of size \"(n1, n2)\", where \"n1\" and \"n2\" are + the numbers of slices in \"v1\" and \"v2\", which depend on the + setting of \"vardim\". + + Note: \"v2\" can be omitted, which indicates \"v2 = v1\". + +"), + +("Base","cor","cor(v1[, v2][, vardim=1, mean=nothing]) + + Compute the Pearson correlation between the vector(s) in \"v1\" and + \"v2\". + + Users can use the keyword argument \"vardim\" to specify the + variable dimension, and \"mean\" to supply pre-computed mean + values. + +"), + +("Base","fft","fft(A[, dims]) + + Performs a multidimensional FFT of the array \"A\". The optional + \"dims\" argument specifies an iterable subset of dimensions (e.g. + an integer, range, tuple, or array) to transform along. Most + efficient if the size of \"A\" along the transformed dimensions is + a product of small primes; see \"nextprod()\". See also + \"plan_fft()\" for even greater efficiency. + + A one-dimensional FFT computes the one-dimensional discrete Fourier + transform (DFT) as defined by + + \\operatorname{DFT}(A)[k] = + \\sum_{n=1}^{\\operatorname{length}(A)} + \\exp\\left(-i\\frac{2\\pi + (n-1)(k-1)}{\\operatorname{length}(A)} \\right) A[n]. + + A multidimensional FFT simply performs this operation along each + transformed dimension of \"A\". + + Higher performance is usually possible with multi-threading. Use + *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* + processors. + +"), + +("Base","fft!","fft!(A[, dims]) + + Same as \"fft()\", but operates in-place on \"A\", which must be an + array of complex floating-point numbers. + +"), + +("Base","ifft","ifft(A[, dims]) + + Multidimensional inverse FFT. + + A one-dimensional inverse FFT computes + + \\operatorname{IDFT}(A)[k] = + \\frac{1}{\\operatorname{length}(A)} + \\sum_{n=1}^{\\operatorname{length}(A)} + \\exp\\left(+i\\frac{2\\pi (n-1)(k-1)} + {\\operatorname{length}(A)} \\right) A[n]. + + A multidimensional inverse FFT simply performs this operation along + each transformed dimension of \"A\". + +"), + +("Base","ifft!","ifft!(A[, dims]) + + Same as \"ifft()\", but operates in-place on \"A\". + +"), + +("Base","bfft","bfft(A[, dims]) + + Similar to \"ifft()\", but computes an unnormalized inverse + (backward) transform, which must be divided by the product of the + sizes of the transformed dimensions in order to obtain the inverse. + (This is slightly more efficient than \"ifft()\" because it omits a + scaling step, which in some applications can be combined with other + computational steps elsewhere.) + + \\operatorname{BDFT}(A)[k] = \\operatorname{length}(A) + \\operatorname{IDFT}(A)[k] + +"), + +("Base","bfft!","bfft!(A[, dims]) + + Same as \"bfft()\", but operates in-place on \"A\". + +"), + +("Base","plan_fft","plan_fft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized FFT along given dimensions (\"dims\") of + arrays matching the shape and type of \"A\". (The first two + arguments have the same meaning as for \"fft()\".) Returns a + function \"plan(A)\" that computes \"fft(A, dims)\" quickly. + + The \"flags\" argument is a bitwise-or of FFTW planner flags, + defaulting to \"FFTW.ESTIMATE\". e.g. passing \"FFTW.MEASURE\" or + \"FFTW.PATIENT\" will instead spend several seconds (or more) + benchmarking different possible FFT algorithms and picking the + fastest one; see the FFTW manual for more information on planner + flags. The optional \"timelimit\" argument specifies a rough upper + bound on the allowed planning time, in seconds. Passing + \"FFTW.MEASURE\" or \"FFTW.PATIENT\" may cause the input array + \"A\" to be overwritten with zeros during plan creation. + + \"plan_fft!()\" is the same as \"plan_fft()\" but creates a plan + that operates in-place on its argument (which must be an array of + complex floating-point numbers). \"plan_ifft()\" and so on are + similar but produce plans that perform the equivalent of the + inverse transforms \"ifft()\" and so on. + +"), + +("Base","plan_ifft","plan_ifft(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_fft()\", but produces a plan that performs inverse + transforms \"ifft()\". + +"), + +("Base","plan_bfft","plan_bfft(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_fft()\", but produces a plan that performs an + unnormalized backwards transform \"bfft()\". + +"), + +("Base","plan_fft!","plan_fft!(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_fft()\", but operates in-place on \"A\". + +"), + +("Base","plan_ifft!","plan_ifft!(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_ifft()\", but operates in-place on \"A\". + +"), + +("Base","plan_bfft!","plan_bfft!(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_bfft()\", but operates in-place on \"A\". + +"), + +("Base","rfft","rfft(A[, dims]) + + Multidimensional FFT of a real array A, exploiting the fact that + the transform has conjugate symmetry in order to save roughly half + the computational time and storage costs compared with \"fft()\". + If \"A\" has size \"(n_1, ..., n_d)\", the result has size + \"(floor(n_1/2)+1, ..., n_d)\". + + The optional \"dims\" argument specifies an iterable subset of one + or more dimensions of \"A\" to transform, similar to \"fft()\". + Instead of (roughly) halving the first dimension of \"A\" in the + result, the \"dims[1]\" dimension is (roughly) halved in the same + way. + +"), + +("Base","irfft","irfft(A, d[, dims]) + + Inverse of \"rfft()\": for a complex array \"A\", gives the + corresponding real array whose FFT yields \"A\" in the first half. + As for \"rfft()\", \"dims\" is an optional subset of dimensions to + transform, defaulting to \"1:ndims(A)\". + + \"d\" is the length of the transformed real array along the + \"dims[1]\" dimension, which must satisfy \"d == + floor(size(A,dims[1])/2)+1\". (This parameter cannot be inferred + from \"size(A)\" due to the possibility of rounding by the + \"floor\" function here.) + +"), + +("Base","brfft","brfft(A, d[, dims]) + + Similar to \"irfft()\" but computes an unnormalized inverse + transform (similar to \"bfft()\"), which must be divided by the + product of the sizes of the transformed dimensions (of the real + output array) in order to obtain the inverse transform. + +"), + +("Base","plan_rfft","plan_rfft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized real-input FFT, similar to \"plan_fft()\" + except for \"rfft()\" instead of \"fft()\". The first two + arguments, and the size of the transformed result, are the same as + for \"rfft()\". + +"), + +("Base","plan_brfft","plan_brfft(A, d[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized real-input unnormalized transform, similar to + \"plan_rfft()\" except for \"brfft()\" instead of \"rfft()\". The + first two arguments and the size of the transformed result, are the + same as for \"brfft()\". + +"), + +("Base","plan_irfft","plan_irfft(A, d[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized inverse real-input FFT, similar to + \"plan_rfft()\" except for \"irfft()\" and \"brfft()\", + respectively. The first three arguments have the same meaning as + for \"irfft()\". + +"), + +("Base","dct","dct(A[, dims]) + + Performs a multidimensional type-II discrete cosine transform (DCT) + of the array \"A\", using the unitary normalization of the DCT. The + optional \"dims\" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. Most efficient if the size of \"A\" along the transformed + dimensions is a product of small primes; see \"nextprod()\". See + also \"plan_dct()\" for even greater efficiency. + +"), + +("Base","dct!","dct!(A[, dims]) + + Same as \"dct!()\", except that it operates in-place on \"A\", + which must be an array of real or complex floating-point values. + +"), + +("Base","idct","idct(A[, dims]) + + Computes the multidimensional inverse discrete cosine transform + (DCT) of the array \"A\" (technically, a type-III DCT with the + unitary normalization). The optional \"dims\" argument specifies an + iterable subset of dimensions (e.g. an integer, range, tuple, or + array) to transform along. Most efficient if the size of \"A\" + along the transformed dimensions is a product of small primes; see + \"nextprod()\". See also \"plan_idct()\" for even greater + efficiency. + +"), + +("Base","idct!","idct!(A[, dims]) + + Same as \"idct!()\", but operates in-place on \"A\". + +"), + +("Base","plan_dct","plan_dct(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized discrete cosine transform (DCT), similar to + \"plan_fft()\" except producing a function that computes \"dct()\". + The first two arguments have the same meaning as for \"dct()\". + +"), + +("Base","plan_dct!","plan_dct!(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_dct()\", but operates in-place on \"A\". + +"), + +("Base","plan_idct","plan_idct(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized inverse discrete cosine transform (DCT), + similar to \"plan_fft()\" except producing a function that computes + \"idct()\". The first two arguments have the same meaning as for + \"idct()\". + +"), + +("Base","plan_idct!","plan_idct!(A[, dims[, flags[, timelimit]]]) + + Same as \"plan_idct()\", but operates in-place on \"A\". + +"), + +("Base","fftshift","fftshift(x) + + Swap the first and second halves of each dimension of \"x\". + +"), + +("Base","fftshift","fftshift(x, dim) + + Swap the first and second halves of the given dimension of array + \"x\". + +"), + +("Base","ifftshift","ifftshift(x[, dim]) + + Undoes the effect of \"fftshift\". + +"), + +("Base","filt","filt(b, a, x[, si]) + + Apply filter described by vectors \"a\" and \"b\" to vector \"x\", + with an optional initial filter state vector \"si\" (defaults to + zeros). + +"), + +("Base","filt!","filt!(out, b, a, x[, si]) + + Same as \"filt()\" but writes the result into the \"out\" argument, + which may alias the input \"x\" to modify it in-place. + +"), + +("Base","deconv","deconv(b, a) + + Construct vector \"c\" such that \"b = conv(a,c) + r\". Equivalent + to polynomial division. + +"), + +("Base","conv","conv(u, v) + + Convolution of two vectors. Uses FFT algorithm. + +"), + +("Base","conv2","conv2(u, v, A) + + 2-D convolution of the matrix \"A\" with the 2-D separable kernel + generated by the vectors \"u\" and \"v\". Uses 2-D FFT algorithm + +"), + +("Base","conv2","conv2(B, A) + + 2-D convolution of the matrix \"B\" with the matrix \"A\". Uses + 2-D FFT algorithm + +"), + +("Base","xcorr","xcorr(u, v) + + Compute the cross-correlation of two vectors. + +"), + +("Base.FFTW","r2r","r2r(A, kind[, dims]) + + Performs a multidimensional real-input/real-output (r2r) transform + of type \"kind\" of the array \"A\", as defined in the FFTW manual. + \"kind\" specifies either a discrete cosine transform of various + types (\"FFTW.REDFT00\", \"FFTW.REDFT01\", \"FFTW.REDFT10\", or + \"FFTW.REDFT11\"), a discrete sine transform of various types + (\"FFTW.RODFT00\", \"FFTW.RODFT01\", \"FFTW.RODFT10\", or + \"FFTW.RODFT11\"), a real-input DFT with halfcomplex-format output + (\"FFTW.R2HC\" and its inverse \"FFTW.HC2R\"), or a discrete + Hartley transform (\"FFTW.DHT\"). The \"kind\" argument may be an + array or tuple in order to specify different transform types along + the different dimensions of \"A\"; \"kind[end]\" is used for any + unspecified dimensions. See the FFTW manual for precise + definitions of these transform types, at http://www.fftw.org/doc. + + The optional \"dims\" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. \"kind[i]\" is then the transform type for \"dims[i]\", with + \"kind[end]\" being used for \"i > length(kind)\". + + See also \"plan_r2r()\" to pre-plan optimized r2r transforms. + +"), + +("Base.FFTW","r2r!","r2r!(A, kind[, dims]) + + Same as \"r2r()\", but operates in-place on \"A\", which must be an + array of real or complex floating-point numbers. + +"), + +("Base.FFTW","plan_r2r","plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized r2r transform, similar to \"Base.plan_fft()\" + except that the transforms (and the first three arguments) + correspond to \"r2r()\" and \"r2r!()\", respectively. + +"), + +("Base.FFTW","plan_r2r!","plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + + Similar to \"Base.plan_fft()\", but corresponds to \"r2r!()\". + +"), + +("Base","quadgk","quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + + Numerically integrate the function \"f(x)\" from \"a\" to \"b\", + and optionally over additional intervals \"b\" to \"c\" and so on. + Keyword options include a relative error tolerance \"reltol\" + (defaults to \"sqrt(eps)\" in the precision of the endpoints), an + absolute error tolerance \"abstol\" (defaults to 0), a maximum + number of function evaluations \"maxevals\" (defaults to \"10^7\"), + and the \"order\" of the integration rule (defaults to 7). + + Returns a pair \"(I,E)\" of the estimated integral \"I\" and an + estimated upper bound on the absolute error \"E\". If \"maxevals\" + is not exceeded then \"E <= max(abstol, reltol*norm(I))\" will + hold. (Note that it is useful to specify a positive \"abstol\" in + cases where \"norm(I)\" may be zero.) + + The endpoints \"a\" etcetera can also be complex (in which case the + integral is performed over straight-line segments in the complex + plane). If the endpoints are \"BigFloat\", then the integration + will be performed in \"BigFloat\" precision as well (note: it is + advisable to increase the integration \"order\" in rough proportion + to the precision, for smooth integrands). More generally, the + precision is set by the precision of the integration endpoints + (promoted to floating-point types). + + The integrand \"f(x)\" can return any numeric scalar, vector, or + matrix type, or in fact any type supporting \"+\", \"-\", + multiplication by real values, and a \"norm\" (i.e., any normed + vector space). Alternatively, a different norm can be specified by + passing a *norm*-like function as the *norm* keyword argument + (which defaults to *vecnorm*). + + [Only one-dimensional integrals are provided by this function. For + multi-dimensional integration (cubature), there are many different + algorithms (often much better than simple nested 1d integrals) and + the optimal choice tends to be very problem-dependent. See the + Julia external-package listing for available algorithms for + multidimensional integration or other specialized tasks (such as + integrals of highly oscillatory or singular functions).] + + The algorithm is an adaptive Gauss-Kronrod integration technique: + the integral in each interval is estimated using a Kronrod rule + (\"2*order+1\" points) and the error is estimated using an embedded + Gauss rule (\"order\" points). The interval with the largest + error is then subdivided into two intervals and the process is + repeated until the desired error tolerance is achieved. + + These quadrature rules work best for smooth functions within each + interval, so if your function has a known discontinuity or other + singularity, it is best to subdivide your interval to put the + singularity at an endpoint. For example, if \"f\" has a + discontinuity at \"x=0.7\" and you want to integrate from 0 to 1, + you should use \"quadgk(f, 0,0.7,1)\" to subdivide the interval at + the point of discontinuity. The integrand is never evaluated + exactly at the endpoints of the intervals, so it is possible to + integrate functions that diverge at the endpoints as long as the + singularity is integrable (for example, a \"log(x)\" or + \"1/sqrt(x)\" singularity). + + For real-valued endpoints, the starting and/or ending points may be + infinite. (A coordinate transformation is performed internally to + map the infinite interval to a finite one.) + +"), + +("Base","bin","bin(n[, pad]) + + Convert an integer to a binary string, optionally specifying a + number of digits to pad to. + +"), + +("Base","hex","hex(n[, pad]) + + Convert an integer to a hexadecimal string, optionally specifying a + number of digits to pad to. + +"), + +("Base","dec","dec(n[, pad]) + + Convert an integer to a decimal string, optionally specifying a + number of digits to pad to. + +"), + +("Base","oct","oct(n[, pad]) + + Convert an integer to an octal string, optionally specifying a + number of digits to pad to. + +"), + +("Base","base","base(base, n[, pad]) + + Convert an integer to a string in the given base, optionally + specifying a number of digits to pad to. The base can be specified + as either an integer, or as a \"UInt8\" array of character values + to use as digit symbols. + +"), + +("Base","digits","digits(n[, base][, pad]) + + Returns an array of the digits of \"n\" in the given base, + optionally padded with zeros to a specified size. More significant + digits are at higher indexes, such that \"n == + sum([digits[k]*base^(k-1) for k=1:length(digits)])\". + +"), + +("Base","digits!","digits!(array, n[, base]) + + Fills an array of the digits of \"n\" in the given base. More + significant digits are at higher indexes. If the array length is + insufficient, the least significant digits are filled up to the + array length. If the array length is excessive, the excess portion + is filled with zeros. + +"), + +("Base","bits","bits(n) + + A string giving the literal bit representation of a number. + +"), + +("Base","parse","parse(type, str[, base]) + + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. + +"), + +("Base","tryparse","tryparse(type, str[, base]) + + Like \"parse\", but returns a \"Nullable\" of the requested type. + The result will be null if the string does not contain a valid + number. + +"), + +("Base","big","big(x) + + Convert a number to a maximum precision representation (typically + \"BigInt\" or \"BigFloat\"). See \"BigFloat\" for information about + some pitfalls with floating-point numbers. + +"), + +("Base","signed","signed(x) + + Convert a number to a signed integer. If the argument is unsigned, + it is reinterpreted as signed without checking for overflow. + +"), + +("Base","unsigned","unsigned(x) -> Unsigned + + Convert a number to an unsigned integer. If the argument is signed, + it is reinterpreted as unsigned without checking for negative + values. + +"), + +("Base","float","float(x) + + Convert a number, array, or string to a \"FloatingPoint\" data + type. For numeric data, the smallest suitable \"FloatingPoint\" + type is used. Converts strings to \"Float64\". + +"), + +("Base","significand","significand(x) + + Extract the significand(s) (a.k.a. mantissa), in binary + representation, of a floating-point number or array. If \"x\" is a + non-zero finite number, than the result will be a number of the + same type on the interval [1,2). Otherwise \"x\" is returned. + + julia> significand(15.2)/15.2 + 0.125 + + julia> significand(15.2)*8 + 15.2 + +"), + +("Base","exponent","exponent(x) -> Int + + Get the exponent of a normalized floating-point number. + +"), + +("Base","complex","complex(r[, i]) + + Convert real numbers or arrays to complex. \"i\" defaults to zero. + +"), + +("Base","bswap","bswap(n) + + Byte-swap an integer + +"), + +("Base","num2hex","num2hex(f) + + Get a hexadecimal string of the binary representation of a floating + point number + +"), + +("Base","hex2num","hex2num(str) + + Convert a hexadecimal string to the floating point number it + represents + +"), + +("Base","hex2bytes","hex2bytes(s::ASCIIString) + + Convert an arbitrarily long hexadecimal string to its binary + representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. + +"), + +("Base","bytes2hex","bytes2hex(bin_arr::Array{UInt8, 1}) + + Convert an array of bytes to its hexadecimal representation. All + characters are in lower-case. Returns an ASCIIString. + +"), + +("Base","one","one(x) + + Get the multiplicative identity element for the type of x (x can + also specify the type itself). For matrices, returns an identity + matrix of the appropriate size and type. + +"), + +("Base","zero","zero(x) + + Get the additive identity element for the type of x (x can also + specify the type itself). + +"), + +("Base","pi","pi +π + + The constant pi + +"), + +("Base","im","im + + The imaginary unit + +"), + +("Base","e","e +eu + + The constant e + +"), + +("Base","catalan","catalan + + Catalan's constant + +"), + +("Base","γ","γ +eulergamma + + Euler's constant + +"), + +("Base","φ","φ +golden + + The golden ratio + +"), + +("Base","Inf","Inf + + Positive infinity of type Float64 + +"), + +("Base","Inf32","Inf32 + + Positive infinity of type Float32 + +"), + +("Base","Inf16","Inf16 + + Positive infinity of type Float16 + +"), + +("Base","NaN","NaN + + A not-a-number value of type Float64 + +"), + +("Base","NaN32","NaN32 + + A not-a-number value of type Float32 + +"), + +("Base","NaN16","NaN16 + + A not-a-number value of type Float16 + +"), + +("Base","issubnormal","issubnormal(f) -> Bool + + Test whether a floating point number is subnormal + +"), + +("Base","isfinite","isfinite(f) -> Bool + + Test whether a number is finite + +"), + +("Base","isinf","isinf(f) -> Bool + + Test whether a number is infinite + +"), + +("Base","isnan","isnan(f) -> Bool + + Test whether a floating point number is not a number (NaN) + +"), + +("Base","inf","inf(f) + + Returns positive infinity of the floating point type \"f\" or of + the same floating point type as \"f\" + +"), + +("Base","nan","nan(f) + + Returns NaN (not-a-number) of the floating point type \"f\" or of + the same floating point type as \"f\" + +"), + +("Base","nextfloat","nextfloat(f) + + Get the next floating point number in lexicographic order + +"), + +("Base","prevfloat","prevfloat(f) -> FloatingPoint + + Get the previous floating point number in lexicographic order + +"), + +("Base","isinteger","isinteger(x) -> Bool + + Test whether \"x\" or all its elements are numerically equal to + some integer + +"), + +("Base","isreal","isreal(x) -> Bool + + Test whether \"x\" or all its elements are numerically equal to + some real number + +"), + +("Base","Float32","Float32(x[, mode::RoundingMode]) + + Create a Float32 from \"x\". If \"x\" is not exactly representable + then \"mode\" determines how \"x\" is rounded. + + julia> Float32(1/3, RoundDown) + 0.3333333f0 + + julia> Float32(1/3, RoundUp) + 0.33333334f0 + + See \"get_rounding\" for available rounding modes. + +"), + +("Base","Float64","Float64(x[, mode::RoundingMode]) + + Create a Float64 from \"x\". If \"x\" is not exactly representable + then \"mode\" determines how \"x\" is rounded. + + julia> Float64(pi, RoundDown) + 3.141592653589793 + + julia> Float64(pi, RoundUp) + 3.1415926535897936 + + See \"get_rounding\" for available rounding modes. + +"), + +("Base","BigInt","BigInt(x) + + Create an arbitrary precision integer. \"x\" may be an \"Int\" (or + anything that can be converted to an \"Int\"). The usual + mathematical operators are defined for this type, and results are + promoted to a \"BigInt\". + + Instances can be constructed from strings via \"parse()\", or using + the \"big\" string literal. + +"), + +("Base","BigFloat","BigFloat(x) + + Create an arbitrary precision floating point number. \"x\" may be + an \"Integer\", a \"Float64\" or a \"BigInt\". The usual + mathematical operators are defined for this type, and results are + promoted to a \"BigFloat\". + + Note that because decimal literals are converted to floating point + numbers when parsed, \"BigFloat(2.1)\" may not yield what you + expect. You may instead prefer to initialize constants from strings + via \"parse()\", or using the \"big\" string literal. + + julia> big\"2.1\" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision + +"), + +("Base","get_rounding","get_rounding(T) + + Get the current floating point rounding mode for type \"T\", + controlling the rounding of basic arithmetic functions (\"+()\", + \"-()\", \"*()\", \"/()\" and \"sqrt()\") and type conversion. + + Valid modes are \"RoundNearest\", \"RoundToZero\", \"RoundUp\", + \"RoundDown\", and \"RoundFromZero\" (\"BigFloat\" only). + +"), + +("Base","set_rounding","set_rounding(T, mode) + + Set the rounding mode of floating point type \"T\", controlling the + rounding of basic arithmetic functions (\"+()\", \"-()\", \"*()\", + \"/()\" and \"sqrt()\") and type conversion. + + Note that this may affect other types, for instance changing the + rounding mode of \"Float64\" will change the rounding mode of + \"Float32\". See \"get_rounding\" for available modes + +"), + +("Base","with_rounding","with_rounding(f::Function, T, mode) + + Change the rounding mode of floating point type \"T\" for the + duration of \"f\". It is logically equivalent to: + + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) + + See \"get_rounding\" for available rounding modes. + +"), + +("Base","count_ones","count_ones(x::Integer) -> Integer + + Number of ones in the binary representation of \"x\". + + julia> count_ones(7) + 3 + +"), + +("Base","count_zeros","count_zeros(x::Integer) -> Integer + + Number of zeros in the binary representation of \"x\". + + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 + +"), + +("Base","leading_zeros","leading_zeros(x::Integer) -> Integer + + Number of zeros leading the binary representation of \"x\". + + julia> leading_zeros(Int32(1)) + 31 + +"), + +("Base","leading_ones","leading_ones(x::Integer) -> Integer + + Number of ones leading the binary representation of \"x\". + + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 + +"), + +("Base","trailing_zeros","trailing_zeros(x::Integer) -> Integer + + Number of zeros trailing the binary representation of \"x\". + + julia> trailing_zeros(2) + 1 + +"), + +("Base","trailing_ones","trailing_ones(x::Integer) -> Integer + + Number of ones trailing the binary representation of \"x\". + + julia> trailing_ones(3) + 2 + +"), + +("Base","isprime","isprime(x::Integer) -> Bool + + Returns \"true\" if \"x\" is prime, and \"false\" otherwise. + + julia> isprime(3) + true + +"), + +("Base","isprime","isprime(x::BigInt[, reps = 25]) -> Bool + + Probabilistic primality test. Returns \"true\" if \"x\" is prime; + and \"false\" if \"x\" is not prime with high probability. The + false positive rate is about \"0.25^reps\". \"reps = 25\" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). + + julia> isprime(big(3)) + true + +"), + +("Base","primes","primes(n) + + Returns a collection of the prime numbers <= \"n\". + +"), + +("Base","isodd","isodd(x::Integer) -> Bool + + Returns \"true\" if \"x\" is odd (that is, not divisible by 2), and + \"false\" otherwise. + + julia> isodd(9) + true + + julia> isodd(10) + false + +"), + +("Base","iseven","iseven(x::Integer) -> Bool + + Returns \"true\" is \"x\" is even (that is, divisible by 2), and + \"false\" otherwise. + + julia> iseven(9) + false + + julia> iseven(10) + true + +"), + +("Base","precision","precision(num::FloatingPoint) + + Get the precision of a floating point number, as defined by the + effective number of bits in the mantissa. + +"), + +("Base","get_bigfloat_precision","get_bigfloat_precision() + + Get the precision (in bits) currently used for BigFloat arithmetic. + +"), + +("Base","set_bigfloat_precision","set_bigfloat_precision(x::Int64) + + Set the precision (in bits) to be used to BigFloat arithmetic. + +"), + +("Base","with_bigfloat_precision","with_bigfloat_precision(f::Function, precision::Integer) + + Change the BigFloat arithmetic precision (in bits) for the duration + of \"f\". It is logically equivalent to: + + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) + +"), + +("Base","srand","srand([rng][, seed]) + + Reseed the random number generator. If a \"seed\" is provided, the + RNG will give a reproducible sequence of numbers, otherwise Julia + will get entropy from the system. For \"MersenneTwister\", the + \"seed\" may be a non-negative integer, a vector of \"UInt32\" + integers or a filename, in which case the seed is read from a file. + \"RandomDevice\" does not support seeding. + +"), + +("Base","MersenneTwister","MersenneTwister([seed]) + + Create a \"MersenneTwister\" RNG object. Different RNG objects can + have their own seeds, which may be useful for generating different + streams of random numbers. + +"), + +("Base","RandomDevice","RandomDevice() + + Create a \"RandomDevice\" RNG object. Two such objects will always + generate different streams of random numbers. + +"), + +("Base","rand","rand([rng][, S][, dims...]) + + Pick a random element or array of random elements from the set of + values specified by \"S\"; \"S\" can be + + * an indexable collection (for example \"1:n\" or + \"['x','y','z']\"), or + + * a type: the set of values to pick from is then equivalent to + \"typemin(S):typemax(S)\" for integers (this is not applicable to + \"BigInt\"), and to [0,1) for floating point numbers; + + \"S\" defaults to \"Float64\". + +"), + +("Base","rand!","rand!([rng], A[, coll]) + + Populate the array A with random values. If the indexable + collection \"coll\" is specified, the values are picked randomly + from \"coll\". This is equivalent to \"copy!(A, rand(rng, coll, + size(A)))\" or \"copy!(A, rand(rng, eltype(A), size(A)))\" but + without allocating a new array. + +"), + +("Base","bitrand","bitrand([rng][, dims...]) + + Generate a \"BitArray\" of random boolean values. + +"), + +("Base","randn","randn([rng][, dims...]) + + Generate a normally-distributed random number with mean 0 and + standard deviation 1. Optionally generate an array of normally- + distributed random numbers. + +"), + +("Base","randn!","randn!([rng], A::Array{Float64, N}) + + Fill the array A with normally-distributed (mean 0, standard + deviation 1) random numbers. Also see the rand function. + +"), + +("Base","randexp","randexp([rng][, dims...]) + + Generate a random number according to the exponential distribution + with scale 1. Optionally generate an array of such random numbers. + +"), + +("Base","randexp!","randexp!([rng], A::Array{Float64, N}) + + Fill the array A with random numbers following the exponential + distribution (with scale 1). + +"), + +("Base","Task","Task(func) + + Create a \"Task\" (i.e. thread, or coroutine) to execute the given + function (which must be callable with no arguments). The task exits + when this function returns. + +"), + +("Base","yieldto","yieldto(task, arg = nothing) + + Switch to the given task. The first time a task is switched to, the + task's function is called with no arguments. On subsequent + switches, \"arg\" is returned from the task's last call to + \"yieldto\". This is a low-level call that only switches tasks, not + considering states or scheduling in any way. Its use is + discouraged. + +"), + +("Base","current_task","current_task() + + Get the currently running Task. + +"), + +("Base","istaskdone","istaskdone(task) -> Bool + + Tell whether a task has exited. + +"), + +("Base","istaskstarted","istaskstarted(task) -> Bool + + Tell whether a task has started executing. + +"), + +("Base","consume","consume(task, values...) + + Receive the next value passed to \"produce\" by the specified task. + Additional arguments may be passed, to be returned from the last + \"produce\" call in the producer. + +"), + +("Base","produce","produce(value) + + Send the given value to the last \"consume\" call, switching to the + consumer task. If the next \"consume\" call passes any values, they + are returned by \"produce\". + +"), + +("Base","yield","yield() + + Switch to the scheduler to allow another scheduled task to run. A + task that calls this function is still runnable, and will be + restarted immediately if there are no other runnable tasks. + +"), + +("Base","task_local_storage","task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local + storage. + +"), + +("Base","task_local_storage","task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local + storage. + +"), + +("Base","task_local_storage","task_local_storage(body, symbol, value) + + Call the function \"body\" with a modified task-local storage, in + which \"value\" is assigned to \"symbol\"; the previous value of + \"symbol\", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. + +"), + +("Base","Condition","Condition() + + Create an edge-triggered event source that tasks can wait for. + Tasks that call \"wait\" on a \"Condition\" are suspended and + queued. Tasks are woken up when \"notify\" is later called on the + \"Condition\". Edge triggering means that only tasks waiting at the + time \"notify\" is called can be woken up. For level-triggered + notifications, you must keep extra state to keep track of whether a + notification has happened. The \"RemoteRef\" type does this, and so + can be used for level-triggered events. + +"), + +("Base","notify","notify(condition, val=nothing; all=true, error=false) + + Wake up tasks waiting for a condition, passing them \"val\". If + \"all\" is true (the default), all waiting tasks are woken, + otherwise only one is. If \"error\" is true, the passed value is + raised as an exception in the woken tasks. + +"), + +("Base","schedule","schedule(t::Task, [val]; error=false) + + Add a task to the scheduler's queue. This causes the task to run + constantly when the system is otherwise idle, unless the task + performs a blocking operation such as \"wait\". + + If a second argument is provided, it will be passed to the task + (via the return value of \"yieldto\") when it runs again. If + \"error\" is true, the value is raised as an exception in the woken + task. + +"), + +("Base","@schedule","@schedule() + + Wrap an expression in a Task and add it to the scheduler's queue. + +"), + +("Base","@task","@task() + + Wrap an expression in a Task without executing it, and return the + Task. This only creates a task, and does not run it. + +"), + +("Base","sleep","sleep(seconds) + + Block the current task for a specified number of seconds. The + minimum sleep time is 1 millisecond or input of \"0.001\". + +"), + +("Base","ReentrantLock","ReentrantLock() + + Creates a reentrant lock. The same task can acquire the lock as + many times as required. Each lock must be matched with an unlock. + +"), + +("Base","lock","lock(l::ReentrantLock) + + Associates \"l\" with the current task. If \"l\" is already locked + by a different task, waits for it to become available. The same + task can acquire the lock multiple times. Each \"lock\" must be + matched by an \"unlock\" + +"), + +("Base","unlock","unlock(l::ReentrantLock) + + Releases ownership of the lock by the current task. If the lock had + been acquired before, it just decrements an internal counter and + returns immediately. + +"), + +("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built \"LocalManager\" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. \"addprocs(4)\" will add 4 processes + on the local machine. + +"), + +("Base","addprocs","addprocs() -> List of process identifiers + + Equivalent to \"addprocs(CPU_CORES)\" + +"), + +("Base","addprocs","addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + \"machines\" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string \"machine_spec\" or a + tuple - \"(machine_spec, count)\" + + \"machine_spec\" is a string of the form \"[user@]host[:port] + [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" + to the standard ssh port. If \"[bind_addr[:port]]\" is specified, + other workers will connect to this worker at the specified + \"bind_addr\" and \"port\". + + \"count\" is the number of workers to be launched on the specified + host. If specified as \":auto\" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + \"tunnel\" : if \"true\" then SSH tunneling will be used to connect + to the worker from the master process. + + \"sshflags\" : specifies additional ssh options, e.g. + \"sshflags=`-i /home/foo/bar.pem`\" . + + \"max_parallel\" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + \"dir\" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + \"exename\" : name of the julia executable. Defaults to + \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case + may be. + + \"exeflags\" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable \"JULIA_WORKER_TIMEOUT\". The value of + \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. + +"), + +("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster + manager implemented in package \"ClusterManagers\". + + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. + Relevant only when using TCP/IP as transport. + +"), + +("Base","nprocs","nprocs() + + Get the number of available processes. + +"), + +("Base","nworkers","nworkers() + + Get the number of available worker processes. This is one less than + nprocs(). Equal to nprocs() if nprocs() == 1. + +"), + +("Base","procs","procs() + + Returns a list of all process identifiers. + +"), + +("Base","workers","workers() + + Returns a list of all worker process identifiers. + +"), + +("Base","rmprocs","rmprocs(pids...) + + Removes the specified workers. + +"), + +("Base","interrupt","interrupt([pids...]) + + Interrupt the current executing task on the specified workers. This + is equivalent to pressing Ctrl-C on the local machine. If no + arguments are given, all workers are interrupted. + +"), + +("Base","myid","myid() + + Get the id of the current process. + +"), + +("Base","pmap","pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + + Transform collections \"lsts\" by applying \"f\" to each element in + parallel. If \"nprocs() > 1\", the calling process will be + dedicated to assigning tasks. All other available processes will be + used as parallel workers, or on the processes specified by + \"pids\". + + If \"err_retry\" is true, it retries a failed application of \"f\" + on a different worker. If \"err_stop\" is true, it takes precedence + over the value of \"err_retry\" and \"pmap\" stops execution on the + first error. + +"), + +("Base","remotecall","remotecall(id, func, args...) + + Call a function asynchronously on the given arguments on the + specified process. Returns a \"RemoteRef\". + +"), + +("Base","wait","wait([x]) + + Block the current task until some event occurs, depending on the + type of the argument: + + * \"RemoteRef\": Wait for a value to become available for the + specified remote reference. + + * \"Condition\": Wait for \"notify\" on a condition. + + * \"Process\": Wait for a process or process chain to exit. The + \"exitcode\" field of a process can be used to determine success + or failure. + + * \"Task\": Wait for a \"Task\" to finish, returning its result + value. If the task fails with an exception, the exception is + propagated (re-thrown in the task that called \"wait\"). + + * \"RawFD\": Wait for changes on a file descriptor (see *poll_fd* + for keyword arguments and return code) + + If no argument is passed, the task blocks for an undefined period. + If the task's state is set to \":waiting\", it can only be + restarted by an explicit call to \"schedule\" or \"yieldto\". If + the task's state is \":runnable\", it might be restarted + unpredictably. + + Often \"wait\" is called within a \"while\" loop to ensure a + waited-for condition is met before proceeding. + +"), + +("Base","fetch","fetch(RemoteRef) + + Wait for and get the value of a remote reference. + +"), + +("Base","remotecall_wait","remotecall_wait(id, func, args...) + + Perform \"wait(remotecall(...))\" in one message. + +"), + +("Base","remotecall_fetch","remotecall_fetch(id, func, args...) + + Perform \"fetch(remotecall(...))\" in one message. + +"), + +("Base","put!","put!(RemoteRef, value) + + Store a value to a remote reference. Implements \"shared queue of + length 1\" semantics: if a value is already present, blocks until + the value is removed with \"take!\". Returns its first argument. + +"), + +("Base","take!","take!(RemoteRef) + + Fetch the value of a remote reference, removing it so that the + reference is empty again. + +"), + +("Base","isready","isready(r::RemoteRef) + + Determine whether a \"RemoteRef\" has a value stored to it. Note + that this function can cause race conditions, since by the time you + receive its result it may no longer be true. It is recommended that + this function only be used on a \"RemoteRef\" that is assigned + once. + + If the argument \"RemoteRef\" is owned by a different node, this + call will block to wait for the answer. It is recommended to wait + for \"r\" in a separate task instead, or to use a local + \"RemoteRef\" as a proxy: + + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block + +"), + +("Base","RemoteRef","RemoteRef() + + Make an uninitialized remote reference on the local machine. + +"), + +("Base","RemoteRef","RemoteRef(n) + + Make an uninitialized remote reference on process \"n\". + +"), + +("Base","timedwait","timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + + Waits till \"testcb\" returns \"true\" or for \"secs`\" seconds, + whichever is earlier. \"testcb\" is polled every \"pollint\" + seconds. + +"), + +("Base","@spawn","@spawn() + + Execute an expression on an automatically-chosen process, returning + a \"RemoteRef\" to the result. + +"), + +("Base","@spawnat","@spawnat() + + Accepts two arguments, \"p\" and an expression, and runs the + expression asynchronously on process \"p\", returning a + \"RemoteRef\" to the result. + +"), + +("Base","@fetch","@fetch() + + Equivalent to \"fetch(@spawn expr)\". + +"), + +("Base","@fetchfrom","@fetchfrom() + + Equivalent to \"fetch(@spawnat p expr)\". + +"), + +("Base","@async","@async() + + Schedule an expression to run on the local machine, also adding it + to the set of items that the nearest enclosing \"@sync\" waits for. + +"), + +("Base","@sync","@sync() + + Wait until all dynamically-enclosed uses of \"@async\", \"@spawn\", + \"@spawnat\" and \"@parallel\" are complete. + +"), + +("Base","@parallel","@parallel() + + A parallel for loop of the form + + @parallel [reducer] for var = range + body + end + + The specified range is partitioned and locally executed across all + workers. In case an optional reducer function is specified, + @parallel performs local reductions on each worker with a final + reduction on the calling process. + + Note that without a reducer function, @parallel executes + asynchronously, i.e. it spawns independent tasks on all available + workers and returns immediately without waiting for completion. To + wait for completion, prefix the call with \"@sync\", like + + @sync @parallel for var = range + body + end + +"), + +("Base","SharedArray","SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + + Construct a SharedArray of a bitstype \"T\" and size \"dims\" + across the processes specified by \"pids\" - all of which have to + be on the same host. + + If \"pids\" is left unspecified, the shared array will be mapped + across all processes on the current host, including the master. + But, \"localindexes\" and \"indexpids\" will only refer to worker + processes. This facilitates work distribution code to use workers + for actual computation with the master process acting as a driver. + + If an \"init\" function of the type \"initfn(S::SharedArray)\" is + specified, it is called on all the participating workers. + +"), + +("Base","procs","procs(S::SharedArray) + + Get the vector of processes that have mapped the shared array + +"), + +("Base","sdata","sdata(S::SharedArray) + + Returns the actual \"Array\" object backing \"S\" + +"), + +("Base","indexpids","indexpids(S::SharedArray) + + Returns the index of the current worker into the \"pids\" vector, + i.e., the list of workers mapping the SharedArray + +"), + +("Base","launch","launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + + Implemented by cluster managers. For every Julia worker launched by + this function, it should append a \"WorkerConfig\" entry to + \"launched\" and notify \"launch_ntfy\". The function MUST exit + once all workers, requested by \"manager\" have been launched. + \"params\" is a dictionary of all keyword arguments \"addprocs\" + was called with. + +"), + +("Base","manage","manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + + Implemented by cluster managers. It is called on the master + process, during a worker's lifetime, with appropriate \"op\" + values: + + * with \":register\"/\":deregister\" when a worker is added / + removed from the Julia worker pool. + + * with \":interrupt\" when \"interrupt(workers)\" is called. + The \"ClusterManager\" should signal the appropriate worker + with an interrupt signal. + + * with \":finalize\" for cleanup purposes. + +"), + +("Base","kill","kill(manager::FooManager, pid::Int, config::WorkerConfig) + + Implemented by cluster managers. It is called on the master + process, by \"rmprocs\". It should cause the remote worker + specified by \"pid\" to exit. + \"Base.kill(manager::ClusterManager.....)\" executes a remote + \"exit()\" on \"pid\" + +"), + +("Base","init_worker","init_worker(manager::FooManager) + + Called by cluster managers implementing custom transports. It + initializes a newly launched process as a worker. Command line + argument \"--worker\" has the effect of initializing a process as a + worker using TCP/IP sockets for transport. + +"), + +("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id \"pid\", specified + by \"config\" and return a pair of \"AsyncStream\" objects. + Messages from \"pid\" to current process will be read off + \"instrm\", while messages to be sent to \"pid\" will be written to + \"outstrm\". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP + socket connections in-between workers. + +"), + +("Base","Base","Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + + Called by cluster managers using custom transports. It should be + called when the custom transport implementation receives the first + message from a remote worker. The custom transport must manage a + logical connection to the remote worker and provide two AsyncStream + objects, one for incoming messages and the other for messages + addressed to the remote worker. + +"), + +("Base.Pkg","dir","dir() -> AbstractString + + Returns the absolute path of the package directory. This defaults + to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION + .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell + syntax). If the \"JULIA_PKGDIR\" environment variable is set, then + that path is used in the returned value as \"joinpath(ENV[\"JULIA_ + PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If + \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to + whatever the current working directory is. + +"), + +("Base.Pkg","dir","dir(names...) -> AbstractString + + Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends + path components to the package directory and normalizes the + resulting path. In particular, \"Pkg.dir(pkg)\" returns the path to + the package \"pkg\". + +"), + +("Base.Pkg","init","init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) + + Initialize \"Pkg.dir()\" as a package directory. This will be done + automatically when the \"JULIA_PKGDIR\" is not set and + \"Pkg.dir()\" uses its default value. As part of this process, + clones a local METADATA git repository from the site and branch + specified by its arguments, which are typically not provided. + Explicit (non-default) arguments can be used to support a custom + METADATA setup. + +"), + +("Base.Pkg","resolve","resolve() + + Determines an optimal, consistent set of package versions to + install or upgrade to. The optimal set of package versions is based + on the contents of \"Pkg.dir(\"REQUIRE\")\" and the state of + installed packages in \"Pkg.dir()\", Packages that are no longer + required are moved into \"Pkg.dir(\".trash\")\". + +"), + +("Base.Pkg","edit","edit() + + Opens \"Pkg.dir(\"REQUIRE\")\" in the editor specified by the + \"VISUAL\" or \"EDITOR\" environment variables; when the editor + command returns, it runs \"Pkg.resolve()\" to determine and install + a new optimal set of installed package versions. + +"), + +("Base.Pkg","add","add(pkg, vers...) + + Add a requirement entry for \"pkg\" to \"Pkg.dir(\"REQUIRE\")\" and + call \"Pkg.resolve()\". If \"vers\" are given, they must be + \"VersionNumber\" objects and they specify acceptable version + intervals for \"pkg\". + +"), + +("Base.Pkg","rm","rm(pkg) + + Remove all requirement entries for \"pkg\" from + \"Pkg.dir(\"REQUIRE\")\" and call \"Pkg.resolve()\". + +"), + +("Base.Pkg","clone","clone(url[, pkg]) + + Clone a package directly from the git URL \"url\". The package does + not need to be a registered in \"Pkg.dir(\"METADATA\")\". The + package repo is cloned by the name \"pkg\" if provided; if not + provided, \"pkg\" is determined automatically from \"url\". + +"), + +("Base.Pkg","clone","clone(pkg) + + If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone + it from that URL on the default branch. The package does not need + to have any registered versions. + +"), + +("Base.Pkg","available","available() -> Vector{ASCIIString} + + Returns the names of available packages. + +"), + +("Base.Pkg","available","available(pkg) -> Vector{VersionNumber} + + Returns the version numbers available for package \"pkg\". + +"), + +("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the + installed version number of each package. + +"), + +("Base.Pkg","installed","installed(pkg) -> Void | VersionNumber + + If \"pkg\" is installed, return the installed version number, + otherwise return \"nothing\". + +"), + +("Base.Pkg","status","status() + + Prints out a summary of what packages are installed and what + version and state they're in. + +"), + +("Base.Pkg","update","update() + + Update package the metadata repo – kept in + \"Pkg.dir(\"METADATA\")\" – then update any fixed packages that can + safely be pulled from their origin; then call \"Pkg.resolve()\" to + determine a new optimal set of packages versions. + +"), + +("Base.Pkg","checkout","checkout(pkg[, branch=\"master\"]) + + Checkout the \"Pkg.dir(pkg)\" repo to the branch \"branch\". + Defaults to checking out the \"master\" branch. To go back to using + the newest compatible released version, use \"Pkg.free(pkg)\" + +"), + +("Base.Pkg","pin","pin(pkg) + + Pin \"pkg\" at the current version. To go back to using the newest + compatible released version, use \"Pkg.free(pkg)\" + +"), + +("Base.Pkg","pin","pin(pkg, version) + + Pin \"pkg\" at registered version \"version\". + +"), + +("Base.Pkg","free","free(pkg) + + Free the package \"pkg\" to be managed by the package manager + again. It calls \"Pkg.resolve()\" to determine optimal package + versions after. This is an inverse for both \"Pkg.checkout\" and + \"Pkg.pin\". + + You can also supply an iterable collection of package names, e.g., + \"Pkg.free((\"Pkg1\", \"Pkg2\"))\" to free multiple packages at + once. + +"), + +("Base.Pkg","build","build() + + Run the build scripts for all installed packages in depth-first + recursive order. + +"), + +("Base.Pkg","build","build(pkgs...) + + Run the build script in \"deps/build.jl\" for each package in + \"pkgs\" and all of their dependencies in depth-first recursive + order. This is called automatically by \"Pkg.resolve()\" on all + installed or updated packages. + +"), + +("Base.Pkg","generate","generate(pkg, license) + + Generate a new package named \"pkg\" with one of these license + keys: \"\"MIT\"\", \"\"BSD\"\" or \"\"ASL\"\". If you want to make + a package with a different license, you can edit it afterwards. + Generate creates a git repo at \"Pkg.dir(pkg)\" for the package and + inside it \"LICENSE.md\", \"README.md\", the julia entrypoint + \"\$pkg/src/\$pkg.jl\", and a travis test file, \".travis.yml\". + +"), + +("Base.Pkg","register","register(pkg[, url]) + + Register \"pkg\" at the git URL \"url\", defaulting to the + configured origin URL of the git repo \"Pkg.dir(pkg)\". + +"), + +("Base.Pkg","tag","tag(pkg[, ver[, commit]]) + + Tag \"commit\" as version \"ver\" of package \"pkg\" and create a + version entry in \"METADATA\". If not provided, \"commit\" defaults + to the current commit of the \"pkg\" repo. If \"ver\" is one of the + symbols \":patch\", \":minor\", \":major\" the next patch, minor or + major version is used. If \"ver\" is not provided, it defaults to + \":patch\". + +"), + +("Base.Pkg","publish","publish() + + For each new package version tagged in \"METADATA\" not already + published, make sure that the tagged package commits have been + pushed to the repo at the registered URL for the package and if + they all have, open a pull request to \"METADATA\". + +"), + +("Base.Pkg","test","test() + + Run the tests for all installed packages ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its \"test/runtests.jl\" file + and test dependencies are specified in \"test/REQUIRE\". + +"), + +("Base.Pkg","test","test(pkgs...) + + Run the tests for each package in \"pkgs\" ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its \"test/runtests.jl\" file + and test dependencies are specified in \"test/REQUIRE\". + +"), + +("Base","@profile","@profile() + + \"@profile \" runs your expression while taking + periodic backtraces. These are appended to an internal buffer of + backtraces. + +"), + +("Base.Profile","clear","clear() + + Clear any existing backtraces from the internal buffer. + +"), + +("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to \"io\" (by default, \"STDOUT\"). If you + do not supply a \"data\" vector, the internal buffer of accumulated + backtraces will be used. \"format\" can be \":tree\" or \":flat\". + If \"C==true\", backtraces from C and Fortran code are shown. + \"combine==true\" merges instruction pointers that correspond to + the same line of code. \"cols\" controls the width of the display. + +"), + +("Base.Profile","print","print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + + Prints profiling results to \"io\". This variant is used to examine + results exported by a previous call to \"retrieve()\". Supply the + vector \"data\" of backtraces and a dictionary \"lidict\" of line + information. + +"), + +("Base.Profile","init","init(; n::Integer, delay::Float64) + + Configure the \"delay\" between backtraces (measured in seconds), + and the number \"n\" of instruction pointers that may be stored. + Each instruction pointer corresponds to a single line of code; + backtraces generally consist of a long list of instruction + pointers. Default settings can be obtained by calling this function + with no arguments, and each can be set independently using keywords + or in the order \"(n, delay)\". + +"), + +("Base.Profile","fetch","fetch() -> data + + Returns a reference to the internal buffer of backtraces. Note that + subsequent operations, like \"clear()\", can affect \"data\" unless + you first make a copy. Note that the values in \"data\" have + meaning only on this machine in the current session, because it + depends on the exact memory addresses used in JIT-compiling. This + function is primarily for internal use; \"retrieve()\" may be a + better choice for most users. + +"), + +("Base.Profile","retrieve","retrieve() -> data, lidict + + \"Exports\" profiling results in a portable format, returning the + set of all backtraces (\"data\") and a dictionary that maps the + (session-specific) instruction pointers in \"data\" to \"LineInfo\" + values that store the file name, function name, and line number. + This function allows you to save profiling results for future + analysis. + +"), + +("Base.Profile","callers","callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} + + Given a previous profiling run, determine who called a particular + function. Supplying the filename (and optionally, range of line + numbers over which the function is defined) allows you to + disambiguate an overloaded method. The returned value is a vector + containing a count of the number of calls and line information + about the caller. One can optionally supply backtrace data + obtained from \"retrieve()\"; otherwise, the current internal + profile buffer is used. + +"), + +("Base.Profile","clear_malloc_data","clear_malloc_data() + + Clears any stored memory allocation data when running julia with \" + --track-allocation\". Execute the command(s) you want to test (to + force JIT-compilation), then call \"clear_malloc_data()\". Then + execute your command(s) again, quit Julia, and examine the + resulting \"*.mem\" files. + +"), + + +("Base","sort!","sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the vector \"v\" in place. \"QuickSort\" is used by default + for numeric arrays while \"MergeSort\" is used for other arrays. + You can specify an algorithm to use via the \"alg\" keyword (see + Sorting Algorithms for available algorithms). The \"by\" keyword + lets you provide a function that will be applied to each element + before comparison; the \"lt\" keyword allows providing a custom + \"less than\" function; use \"rev=true\" to reverse the sorting + order. These options are independent and can be used together in + all possible combinations: if both \"by\" and \"lt\" are specified, + the \"lt\" function is applied to the result of the \"by\" + function; \"rev=true\" reverses whatever ordering specified via the + \"by\" and \"lt\" keywords. + +"), + +("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of \"sort!\" that returns a sorted copy of \"v\" leaving + \"v\" itself unmodified. + +"), + +("Base","sort","sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort a multidimensional array \"A\" along the given dimension. + +"), + +("Base","sortperm","sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Return a permutation vector of indices of \"v\" that puts it in + sorted order. Specify \"alg\" to choose a particular sorting + algorithm (see Sorting Algorithms). \"MergeSort\" is used by + default, and since it is stable, the resulting permutation will be + the lexicographically first one that puts the input array into + sorted order – i.e. indices of equal elements appear in ascending + order. If you choose a non-stable sorting algorithm such as + \"QuickSort\", a different permutation that puts the array into + order may be returned. The order is specified using the same + keywords as \"sort!\". + + See also \"sortperm!()\" + +"), + +("Base","sortperm!","sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + + Like \"sortperm\", but accepts a preallocated index vector \"ix\". + If \"initialized\" is \"false\" (the default), ix is initialized to + contain the values \"1:length(v)\". + + See also \"sortperm()\" + +"), + +("Base","sortrows","sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the rows of matrix \"A\" lexicographically. + +"), + +("Base","sortcols","sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort the columns of matrix \"A\" lexicographically. + +"), + +("Base","issorted","issorted(v, [by=,] [lt=,] [rev=false]) + + Test whether a vector is in sorted order. The \"by\", \"lt\" and + \"rev\" keywords modify what order is considered to be sorted just + as they do for \"sort\". + +"), + +("Base","searchsorted","searchsorted(a, x, [by=,] [lt=,] [rev=false]) + + Returns the range of indices of \"a\" which compare as equal to + \"x\" according to the order specified by the \"by\", \"lt\" and + \"rev\" keywords, assuming that \"a\" is already sorted in that + order. Returns an empty range located at the insertion point if + \"a\" does not contain values equal to \"x\". + +"), + +("Base","searchsortedfirst","searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + + Returns the index of the first value in \"a\" greater than or equal + to \"x\", according to the specified order. Returns \"length(a)+1\" + if \"x\" is greater than all values in \"a\". + +"), + +("Base","searchsortedlast","searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + + Returns the index of the last value in \"a\" less than or equal to + \"x\", according to the specified order. Returns \"0\" if \"x\" is + less than all values in \"a\". + +"), + +("Base","select!","select!(v, k, [by=,] [lt=,] [rev=false]) + + Partially sort the vector \"v\" in place, according to the order + specified by \"by\", \"lt\" and \"rev\" so that the value at index + \"k\" (or range of adjacent values if \"k\" is a range) occurs at + the position where it would appear if the array were fully sorted + via a non-stable algorithm. If \"k\" is a single index, that value + is returned; if \"k\" is a range, an array of values at those + indices is returned. Note that \"select!\" does not fully sort the + input array. + +"), + +("Base","select","select(v, k, [by=,] [lt=,] [rev=false]) + + Variant of \"select!\" which copies \"v\" before partially sorting + it, thereby returning the same thing as \"select!\" but leaving + \"v\" unmodified. + +"), + +("Base","length","length(s) + + The number of characters in string \"s\". + +"), + +("Base","sizeof","sizeof(s::AbstractString) + + The number of bytes in string \"s\". + +"), + +("Base","*","*(s, t) + + Concatenate strings. The \"*\" operator is an alias to this + function. + + julia> \"Hello \" * \"world\" + \"Hello world\" + +"), + +("Base","^","^(s, n) + + Repeat \"n\" times the string \"s\". The \"^\" operator is an alias + to this function. + + julia> \"Test \"^3 + \"Test Test Test \" + +"), + +("Base","string","string(xs...) + + Create a string from any values using the \"print\" function. + +"), + +("Base","repr","repr(x) + + Create a string from any value using the \"showall\" function. + +"), + +("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) + + Create a string from the address of a C (0-terminated) string + encoded in ASCII or UTF-8. A copy is made; the ptr can be safely + freed. If \"length\" is specified, the string does not have to be + 0-terminated. + +"), + +("Base","bytestring","bytestring(s) + + Convert a string to a contiguous byte array representation + appropriate for passing it to C functions. The string will be + encoded as either ASCII or UTF-8. + +"), + +("Base","ascii","ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + +"), + +("Base","ascii","ascii(s) + + Convert a string to a contiguous ASCII string (all characters must + be valid ASCII characters). + +"), + +("Base","ascii","ascii(::Ptr{UInt8}[, length]) + + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If \"length\" is specified, the string does not have to be + 0-terminated. + +"), + +("Base","utf8","utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + +"), + +("Base","utf8","utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string + encoded in UTF-8. A copy is made; the ptr can be safely freed. If + \"length\" is specified, the string does not have to be + 0-terminated. + +"), + +("Base","utf8","utf8(s) + + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). + +"), + +("Base","normalize_string","normalize_string(s, normalform::Symbol) + + Normalize the string \"s\" according to one of the four \"normal + forms\" of the Unicode standard: \"normalform\" can be \":NFC\", + \":NFD\", \":NFKC\", or \":NFKD\". Normal forms C (canonical + composition) and D (canonical decomposition) convert different + visually identical representations of the same abstract string into + a single canonical form, with form C being more compact. Normal + forms KC and KD additionally canonicalize \"compatibility + equivalents\": they convert characters that are abstractly similar + but visually distinct into a single canonical choice (e.g. they + expand ligatures into the individual characters), with form KC + being more compact. + + Alternatively, finer control and additional transformations may be + be obtained by calling *normalize_string(s; keywords...)*, where + any number of the following boolean keywords options (which all + default to \"false\" except for \"compose\") are specified: + + * \"compose=false\": do not perform canonical composition + + * \"decompose=true\": do canonical decomposition instead of + canonical composition (\"compose=true\" is ignored if present) + + * \"compat=true\": compatibility equivalents are canonicalized + + * \"casefold=true\": perform Unicode case folding, e.g. for case- + insensitive string comparison + + * \"newline2lf=true\", \"newline2ls=true\", or + \"newline2ps=true\": convert various newline sequences (LF, CRLF, + CR, NEL) into a linefeed (LF), line-separation (LS), or + paragraph-separation (PS) character, respectively + + * \"stripmark=true\": strip diacritical marks (e.g. accents) + + * \"stripignore=true\": strip Unicode's \"default ignorable\" + characters (e.g. the soft hyphen or the left-to-right marker) + + * \"stripcc=true\": strip control characters; horizontal tabs and + form feeds are converted to spaces; newlines are also converted + to spaces unless a newline-conversion flag was specified + + * \"rejectna=true\": throw an error if unassigned code points are + found + + * \"stable=true\": enforce Unicode Versioning Stability + + For example, NFKC corresponds to the options \"compose=true, + compat=true, stable=true\". + +"), + +("Base","graphemes","graphemes(s) -> iterator over substrings of s + + Returns an iterator over substrings of \"s\" that correspond to the + extended graphemes in the string, as defined by Unicode UAX #29. + (Roughly, these are what users would perceive as single characters, + even though they may contain more than one codepoint; for example a + letter combined with an accent mark is a single grapheme.) + +"), + +("Base","isvalid","isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which + currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" + +"), + +("Base","isvalid","isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types + currently can be \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of + type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and + \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for + \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values + for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or + \"Vector{UInt32}\" + +"), + +("Base","is_assigned_char","is_assigned_char(c) -> Bool + + Returns true if the given char or integer is an assigned Unicode + code point. + +"), + +("Base","ismatch","ismatch(r::Regex, s::AbstractString) -> Bool + + Test whether a string contains a match of the given regular + expression. + +"), + +("Base","match","match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + + Search for the first match of the regular expression \"r\" in \"s\" + and return a RegexMatch object containing the match, or nothing if + the match failed. The matching substring can be retrieved by + accessing \"m.match\" and the captured sequences can be retrieved + by accessing \"m.captures\" The optional \"idx\" argument specifies + an index at which to start the search. + +"), + +("Base","eachmatch","eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + + Search for all matches of a the regular expression \"r\" in \"s\" + and return a iterator over the matches. If overlap is true, the + matching sequences are allowed to overlap indices in the original + string, otherwise they must be from distinct character ranges. + +"), + +("Base","matchall","matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + + Return a vector of the matching substrings from eachmatch. + +"), + +("Base","lpad","lpad(string, n, p) + + Make a string at least \"n\" columns wide when printed, by padding + on the left with copies of \"p\". + +"), + +("Base","rpad","rpad(string, n, p) + + Make a string at least \"n\" columns wide when printed, by padding + on the right with copies of \"p\". + +"), + +("Base","search","search(string, chars[, start]) + + Search for the first occurrence of the given characters within the + given string. The second argument may be a single character, a + vector or a set of characters, a string, or a regular expression + (though regular expressions are only allowed on contiguous strings, + such as ASCII or UTF-8 strings). The third argument optionally + specifies a starting index. The return value is a range of indexes + where the matching sequence is found, such that \"s[search(s,x)] == + x\": + + \"search(string, \"substring\")\" = \"start:end\" such that + \"string[start:end] == \"substring\"\", or \"0:-1\" if unmatched. + + \"search(string, 'c')\" = \"index\" such that + \"string[index] == 'c'\", or \"0\" if unmatched. + +"), + +("Base","rsearch","rsearch(string, chars[, start]) + + Similar to \"search\", but returning the last occurrence of the + given characters within the given string, searching in reverse from + \"start\". + +"), + +("Base","searchindex","searchindex(string, substring[, start]) + + Similar to \"search\", but return only the start index at which the + substring is found, or 0 if it is not. + +"), + +("Base","rsearchindex","rsearchindex(string, substring[, start]) + + Similar to \"rsearch\", but return only the start index at which + the substring is found, or 0 if it is not. + +"), + +("Base","contains","contains(haystack, needle) + + Determine whether the second argument is a substring of the first. + +"), + +("Base","replace","replace(string, pat, r[, n]) + + Search for the given pattern \"pat\", and replace each occurrence + with \"r\". If \"n\" is provided, replace at most \"n\" + occurrences. As with search, the second argument may be a single + character, a vector or a set of characters, a string, or a regular + expression. If \"r\" is a function, each occurrence is replaced + with \"r(s)\" where \"s\" is the matched substring. + +"), + +("Base","split","split(string, [chars]; limit=0, keep=true) + + Return an array of substrings by splitting the given string on + occurrences of the given character delimiters, which may be + specified in any of the formats allowed by \"search\"'s second + argument (i.e. a single character, collection of characters, + string, or regular expression). If \"chars\" is omitted, it + defaults to the set of all space characters, and \"keep\" is taken + to be false. The two keyword arguments are optional: they are are a + maximum size for the result and a flag determining whether empty + fields should be kept in the result. + +"), + +("Base","rsplit","rsplit(string, [chars]; limit=0, keep=true) + + Similar to \"split\", but starting from the end of the string. + +"), + +("Base","strip","strip(string[, chars]) + + Return \"string\" with any leading and trailing whitespace removed. + If \"chars\" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. + +"), + +("Base","lstrip","lstrip(string[, chars]) + + Return \"string\" with any leading whitespace removed. If \"chars\" + (a character, or vector or set of characters) is provided, instead + remove characters contained in it. + +"), + +("Base","rstrip","rstrip(string[, chars]) + + Return \"string\" with any trailing whitespace removed. If + \"chars\" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. + +"), + +("Base","startswith","startswith(string, prefix | chars) + + Returns \"true\" if \"string\" starts with \"prefix\". If the + second argument is a vector or set of characters, tests whether the + first character of \"string\" belongs to that set. + +"), + +("Base","endswith","endswith(string, suffix | chars) + + Returns \"true\" if \"string\" ends with \"suffix\". If the second + argument is a vector or set of characters, tests whether the last + character of \"string\" belongs to that set. + +"), + +("Base","uppercase","uppercase(string) + + Returns \"string\" with all characters converted to uppercase. + +"), + +("Base","lowercase","lowercase(string) + + Returns \"string\" with all characters converted to lowercase. + +"), + +("Base","ucfirst","ucfirst(string) + + Returns \"string\" with the first character converted to uppercase. + +"), + +("Base","lcfirst","lcfirst(string) + + Returns \"string\" with the first character converted to lowercase. + +"), + +("Base","join","join(strings, delim[, last]) + + Join an array of \"strings\" into a single string, inserting the + given delimiter between adjacent strings. If \"last\" is given, it + will be used instead of \"delim\" between the last two strings. For + example, \"join([\"apples\", \"bananas\", \"pineapples\"], \", \", + \" and \") == \"apples, bananas and pineapples\"\". + + \"strings\" can be any iterable over elements \"x\" which are + convertible to strings via \"print(io::IOBuffer, x)\". + +"), + +("Base","chop","chop(string) + + Remove the last character from a string + +"), + +("Base","chomp","chomp(string) + + Remove a trailing newline from a string + +"), + +("Base","ind2chr","ind2chr(string, i) + + Convert a byte index to a character index + +"), + +("Base","chr2ind","chr2ind(string, i) + + Convert a character index to a byte index + +"), + +("Base","isvalid","isvalid(str, i) + + Tells whether index \"i\" is valid for the given string + +"), + +("Base","nextind","nextind(str, i) + + Get the next valid string index after \"i\". Returns a value + greater than \"endof(str)\" at or after the end of the string. + +"), + +("Base","prevind","prevind(str, i) + + Get the previous valid string index before \"i\". Returns a value + less than \"1\" at the beginning of the string. + +"), + +("Base","randstring","randstring([rng], len=8) + + Create a random ASCII string of length \"len\", consisting of + upper- and lower-case letters and the digits 0-9. The optional + \"rng\" argument specifies a random number generator, see *Random + Numbers*. + +"), + +("Base","charwidth","charwidth(c) + + Gives the number of columns needed to print a character. + +"), + +("Base","strwidth","strwidth(s) + + Gives the number of columns needed to print a string. + +"), + +("Base","isalnum","isalnum(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is alphanumeric, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter or + Number, i.e. a character whose category code begins with 'L' or + 'N'. + +"), + +("Base","isalpha","isalpha(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is alphabetic, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter, + i.e. a character whose category code begins with 'L'. + +"), + +("Base","isascii","isascii(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character belongs to the ASCII character set, or + whether this is true for all elements of a string. + +"), + +("Base","iscntrl","iscntrl(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a control character, or whether this + is true for all elements of a string. Control characters are the + non-printing characters of the Latin-1 subset of Unicode. + +"), + +("Base","isdigit","isdigit(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a numeric digit (0-9), or whether this + is true for all elements of a string. + +"), + +("Base","isgraph","isgraph(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is printable, and not a space, or whether + this is true for all elements of a string. Any character that + would cause a printer to use ink should be classified with + isgraph(c)==true. + +"), + +("Base","islower","islower(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a lowercase letter, or whether this is + true for all elements of a string. A character is classified as + lowercase if it belongs to Unicode category Ll, Letter: Lowercase. + +"), + +("Base","isnumber","isnumber(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is numeric, or whether this is true for + all elements of a string. A character is classified as numeric if + it belongs to the Unicode general category Number, i.e. a character + whose category code begins with 'N'. + +"), + +("Base","isprint","isprint(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is printable, including spaces, but not a + control character. For strings, tests whether this is true for all + elements of the string. + +"), + +("Base","ispunct","ispunct(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character belongs to the Unicode general category + Punctuation, i.e. a character whose category code begins with 'P'. + For strings, tests whether this is true for all elements of the + string. + +"), + +("Base","isspace","isspace(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is any whitespace character. Includes + ASCII characters '\\t', '\\n', '\\v', '\\f', '\\r', and ' ', + Latin-1 character U+0085, and characters in Unicode category Zs. + For strings, tests whether this is true for all elements of the + string. + +"), + +("Base","isupper","isupper(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is an uppercase letter, or whether this + is true for all elements of a string. A character is classified + as uppercase if it belongs to Unicode category Lu, Letter: + Uppercase, or Lt, Letter: Titlecase. + +"), + +("Base","isxdigit","isxdigit(c::Union{Char, AbstractString}) -> Bool + + Tests whether a character is a valid hexadecimal digit, or whether + this is true for all elements of a string. + +"), + +("Base","symbol","symbol(x...) -> Symbol + + Create a \"Symbol\" by concatenating the string representations of + the arguments together. + +"), + +("Base","escape_string","escape_string(str::AbstractString) -> AbstractString + + General escaping of traditional C and Unicode escape sequences. See + \"print_escaped()\" for more general escaping. + +"), + +("Base","unescape_string","unescape_string(s::AbstractString) -> AbstractString + + General unescaping of traditional C and Unicode escape sequences. + Reverse of \"escape_string()\". See also \"print_unescaped()\". + +"), + +("Base","utf16","utf16(s) + + Create a UTF-16 string from a byte array, array of \"UInt16\", or + any other string type. (Data must be valid UTF-16. Conversions of + byte arrays check for a byte-order marker in the first two bytes, + and do not include it in the resulting string.) + + Note that the resulting \"UTF16String\" data is terminated by the + NUL codepoint (16-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf16(s)* conversion function. If you have a \"UInt16\" array + \"A\" that is already NUL-terminated valid UTF-16 data, then you + can instead use *UTF16String(A)`* to construct the string without + making a copy of the data and treating the NUL as a terminator + rather than as part of the string. + +"), + +("Base","utf16","utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + + Create a string from the address of a NUL-terminated UTF-16 string. + A copy is made; the pointer can be safely freed. If \"length\" is + specified, the string does not have to be NUL-terminated. + +"), + +("Base","utf32","utf32(s) + + Create a UTF-32 string from a byte array, array of \"Char\" or + \"UInt32\", or any other string type. (Conversions of byte arrays + check for a byte-order marker in the first four bytes, and do not + include it in the resulting string.) + + Note that the resulting \"UTF32String\" data is terminated by the + NUL codepoint (32-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf32(s)* conversion function. If you have a \"Char\" or + \"UInt32\" array \"A\" that is already NUL-terminated UTF-32 data, + then you can instead use *UTF32String(A)`* to construct the string + without making a copy of the data and treating the NUL as a + terminator rather than as part of the string. + +"), + +("Base","utf32","utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) + + Create a string from the address of a NUL-terminated UTF-32 string. + A copy is made; the pointer can be safely freed. If \"length\" is + specified, the string does not have to be NUL-terminated. + +"), + +("Base","wstring","wstring(s) + + This is a synonym for either \"utf32(s)\" or \"utf16(s)\", + depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. + The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is + also provided. + +"), + +("Base","runtests","runtests([tests=[\"all\"][, numcores=iceil(CPU_CORES/2)]]) + + Run the Julia unit tests listed in \"tests\", which can be either a + string or an array of strings, using \"numcores\" processors. (not + exported) + +"), + +("Base.Test","@test","@test(ex) + + Test the expression \"ex\" and calls the current handler to handle + the result. + +"), + +("Base.Test","@test_throws","@test_throws(extype, ex) + + Test that the expression \"ex\" throws an exception of type + \"extype\" and calls the current handler to handle the result. + +"), + +("Base.Test","@test_approx_eq","@test_approx_eq(a, b) + + Test two floating point numbers \"a\" and \"b\" for equality taking + in account small numerical errors. + +"), + +("Base.Test","@test_approx_eq_eps","@test_approx_eq_eps(a, b, tol) + + Test two floating point numbers \"a\" and \"b\" for equality taking + in account a margin of tolerance given by \"tol\". + +"), + +("Base.Test","with_handler","with_handler(f, handler) + + Run the function \"f\" using the \"handler\" as the handler. + +"), + + +] From 89c7e91206fe4df717fd177a9b2fc58bee2ebbfb Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 21:41:21 -0400 Subject: [PATCH 19/27] add getdoc back --- doc/newdoc.jl | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 doc/newdoc.jl diff --git a/doc/newdoc.jl b/doc/newdoc.jl new file mode 100644 index 0000000000000..83e2b25974b8c --- /dev/null +++ b/doc/newdoc.jl @@ -0,0 +1,31 @@ +using Base.Meta + +exceptions = ["ans", "CPU_CORES", "JULIA_HOME", "STDOUT", "STDERR", "STDIN", "help", "apropos", "Help"] + +qualify = ["ccall", "in", "<:", "|>", "*", "\\", "*", "/", "^", ".+", ".-", ".*", + "./", ".\\", ".^", "//", "<<", ">>", ">>>", "==", "!=", "===", "!==", + "<", "<=", ">", ">=", ".==", ".!=", ".<", ".<=", ".>", ".>=", "|", "*", + "^", ":"] + +cd(joinpath(dirname(@__FILE__), "..", "base", "docs")) do + open("helpdb.jl", "w") do io + for (mod, func, desc) in evalfile("helpdb.jl") + (func in exceptions || ismatch(r"[\{\} ]", func)) && continue + isop = ismatch(r"[^\w@!]|^!$", func) + isbase = mod == "Base" && !(func in qualify) + + isop && !isbase && (func = "(:($func))") + desc = replace(rstrip(desc), "\$", "\\\$") + desc = replace(desc, "\"\"\"", "\\\"\"\"") + + println(io, """ + doc\""" + ```rst + $desc + ``` + \""" + $(isbase ? func : "$mod.$func") + """) + end + end +end From 9be5f637a0706e2fe43526bd3cb1b74949633d77 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 21:41:36 -0400 Subject: [PATCH 20/27] fix helpdb.jl --- base/docs/helpdb.jl | 15511 +++++++++++++++++++++++++++--------------- 1 file changed, 10097 insertions(+), 5414 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index a236f52785035..bcae513ed6e17 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -1,55 +1,65 @@ doc""" - ndims(A) -> Integer +```rst +ndims(A) -> Integer -Returns the number of dimensions of A + Returns the number of dimensions of A +``` """ ndims + doc""" - size(A[, dim...]) +```rst +size(A[, 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.: + 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 = rand(2,3,4); + julia> A = rand(2,3,4); - julia> size(A,2) - 3 + julia> size(A, 2) + 3 - julia> size(A,3,2) - (4,3) + julia> size(A,3,2) + (4,3) +``` """ size doc""" - iseltype(A, T) +```rst +iseltype(A, T) -Tests whether A or its elements are of type T + Tests whether A or its elements are of type T +``` """ iseltype doc""" - length(A) -> Integer +```rst +length(A) -> Integer -Returns the number of elements in A + Returns the number of elements in A +``` """ length doc""" - eachindex(A...) +```rst +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 (like `Array`), this is -simply the range `1: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 non-integer indices). + 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 (like "Array"), this is + simply the range "1: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 non-integer indices). -Example for a sparse 2-d array: + Example for a sparse 2-d array: julia> A = sprand(2, 3, 0.5) 2x3 sparse matrix with 4 Float64 entries: @@ -74,12871 +84,17544 @@ Example for a sparse 2-d array: A[iter] = 0.4864987874354343 (iter.I_1,iter.I_2) = (2,3) A[iter] = 0.8090413606455655 +``` """ eachindex doc""" - Base.linearindexing(A) +```rst +Base.linearindexing(A) + + "linearindexing" defines how an AbstractArray most efficiently + accesses its elements. If "Base.linearindexing(A)" returns + "Base.LinearFast()", this means that linear indexing with only + one index is an efficient operation. If it instead returns + "Base.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 + traits-based mechanism to enable efficient generic code for all + array types. -accesses its elements. If `Base.linearindexing(A)` returns -one index is an efficient operation. If it instead returns -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 -traits-based 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 define `linearindexing` in the -type-domain: + An abstract array subtype "MyArray" that wishes to opt into fast + linear indexing behaviors should define "linearindexing" in the + type-domain: + + Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() +``` """ Base doc""" - countnz(A) +```rst +countnz(A) -Counts the number of nonzero values in array A (dense or sparse). -Note that this is not a constant-time operation. For sparse -matrices, one should usually use `nnz`, which returns the number -of stored values. + Counts the number of nonzero values in array A (dense or sparse). + Note that this is not a constant-time operation. For sparse + matrices, one should usually use "nnz", which returns the number + of stored values. +``` """ countnz doc""" - conj!(A) +```rst +conj!(A) -Convert an array to its complex conjugate in-place + Convert an array to its complex conjugate in-place +``` """ conj! doc""" - stride(A, k) +```rst +stride(A, k) -Returns the distance in memory (in number of elements) between -adjacent elements in dimension k + Returns the distance in memory (in number of elements) between + adjacent elements in dimension k +``` """ stride doc""" - strides(A) +```rst +strides(A) -Returns a tuple of the memory strides in each dimension + Returns a tuple of the memory strides in each dimension +``` """ strides doc""" - ind2sub(dims, index) -> subscripts +```rst +ind2sub(dims, index) -> subscripts -Returns a tuple of subscripts into an array with dimensions -`dims`, corresponding to the linear index `index`. + Returns a tuple of subscripts into an array with dimensions + "dims", corresponding to the linear index "index" -**Example** `i, j, ... = ind2sub(size(A), indmax(A))` provides -the indices of the maximum element. + **Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides + the indices of the maximum element +``` """ ind2sub doc""" - ind2sub(a, index) -> subscripts +```rst +ind2sub(a, index) -> subscripts -Returns a tuple of subscripts into array `a` corresponding to the -linear index `index` + Returns a tuple of subscripts into array "a" corresponding to the + linear index "index" +``` """ ind2sub doc""" - sub2ind(dims, i, j, k...) -> index +```rst +sub2ind(dims, i, j, k...) -> index -The inverse of `ind2sub`, returns the linear index corresponding -to the provided subscripts + The inverse of "ind2sub", returns the linear index corresponding + to the provided subscripts +``` """ sub2ind doc""" - Array(dims) +```rst +Array(dims) -`Array{T}(dims)` constructs an uninitialized dense array with -element type `T`. `dims` may be a tuple or a series of integer -arguments. The syntax `Array(T, dims)` is also available, but -deprecated. + "Array{T}(dims)" constructs an uninitialized dense array with + element type "T". "dims" may be a tuple or a series of integer + arguments. The syntax "Array(T, dims)" is also available, but + deprecated. +``` """ Array doc""" - getindex(type[, elements...]) +```rst +getindex(type[, elements...]) -Construct a 1-d array of the specified type. This is usually called -with the syntax `Type[]`. Element values can be specified using -`Type[a,b,c,...]`. + Construct a 1-d array of the specified type. This is usually called + with the syntax "Type[]". Element values can be specified using + "Type[a,b,c,...]". +``` """ getindex doc""" - cell(dims) +```rst +cell(dims) -Construct an uninitialized cell array (heterogeneous array). -`dims` can be either a tuple or a series of integer arguments. + Construct an uninitialized cell array (heterogeneous array). + "dims" can be either a tuple or a series of integer arguments. +``` """ cell doc""" - zeros(type, dims) +```rst +zeros(type, dims) -Create an array of all zeros of specified type. The type defaults -to Float64 if not specified. + Create an array of all zeros of specified type. The type defaults + to Float64 if not specified. +``` """ zeros doc""" - zeros(A) +```rst +zeros(A) -Create an array of all zeros with the same element type and shape -as A. + Create an array of all zeros with the same element type and shape + as A. +``` """ zeros doc""" - ones(type, dims) +```rst +ones(type, dims) -Create an array of all ones of specified type. The type defaults to -Float64 if not specified. + Create an array of all ones of specified type. The type defaults to + Float64 if not specified. +``` """ ones doc""" - ones(A) +```rst +ones(A) -Create an array of all ones with the same element type and shape as -A. + Create an array of all ones with the same element type and shape as + A. +``` """ ones doc""" - trues(dims) +```rst +trues(dims) -Create a `BitArray` with all values set to true + Create a "BitArray" with all values set to true +``` """ trues doc""" - falses(dims) +```rst +falses(dims) -Create a `BitArray` with all values set to false + Create a "BitArray" with all values set to false +``` """ falses doc""" - fill(x, dims) +```rst +fill(x, dims) -Create an array filled with the value `x`. For example, -`fill(1.0, (10,10))` returns a 10x10 array of floats, with each -element initialized to 1.0. + Create an array filled with the value "x". For example, + "fill(1.0, (10,10))" returns a 10x10 array of floats, with each + element initialized to 1.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 evaluating `Foo()` once. + 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 evaluating "Foo()" once. +``` """ fill doc""" - fill!(A, x) +```rst +fill!(A, x) -Fill array `A` with the value `x`. If `x` is an object -reference, all elements will refer to the same object. `fill!(A, -Foo())` will return `A` filled with the result of evaluating -`Foo()` once. + Fill array "A" with the value "x". If "x" is an object + reference, all elements will refer to the same object. "fill!(A, + Foo())" will return "A" filled with the result of evaluating + "Foo()" once. +``` """ fill! doc""" - reshape(A, dims) +```rst +reshape(A, dims) -Create an array with the same data as the given array, but with -different dimensions. An implementation for a particular type of -array may choose whether the data is copied or shared. + Create an array with the same data as the given array, but with + different dimensions. An implementation for a particular type of + array may choose whether the data is copied or shared. +``` """ reshape doc""" - similar(array, element_type, dims) +```rst +similar(array, element_type, dims) -Create an uninitialized array of the same type as the given array, -but with the specified element type and dimensions. The second and -third arguments are both optional. The `dims` argument may be a -tuple or a series of integer arguments. For some special -`AbstractArray` objects which are not real containers (like -ranges), this function returns a standard `Array` to allow -operating on elements. + Create an uninitialized array of the same type as the given array, + but with the specified element type and dimensions. The second and + third arguments are both optional. The "dims" argument may be a + tuple or a series of integer arguments. For some special + "AbstractArray" objects which are not real containers (like + ranges), this function returns a standard "Array" to allow + operating on elements. +``` """ similar doc""" - reinterpret(type, A) +```rst +reinterpret(type, A) -Change the type-interpretation of a block of memory. For example, -`reinterpret(Float32, UInt32(7))` interprets the 4 bytes -corresponding to `UInt32(7)` as a `Float32`. For arrays, this -constructs an array with the same binary data as the given array, -but with the specified element type. + Change the type-interpretation of a block of memory. For example, + "reinterpret(Float32, UInt32(7))" interprets the 4 bytes + corresponding to "UInt32(7)" as a "Float32". For arrays, this + constructs an array with the same binary data as the given array, + but with the specified element type. +``` """ reinterpret doc""" - eye(n) +```rst +eye(n) -n-by-n identity matrix + n-by-n identity matrix +``` """ eye doc""" - eye(m, n) +```rst +eye(m, n) -m-by-n identity matrix + m-by-n identity matrix +``` """ eye doc""" - eye(A) +```rst +eye(A) -Constructs an identity matrix of the same dimensions and type as `A`. + Constructs an identity matrix of the same dimensions and type as + "A". +``` """ eye doc""" - linspace(start, stop, n=100) +```rst +linspace(start, stop, n=100) -Construct a range of `n` linearly spaced elements from `start` to `stop`. + Construct a range of "n" linearly spaced elements from "start" + to "stop". +``` """ linspace doc""" - logspace(start, stop, n=50) +```rst +logspace(start, stop, n=50) -Construct a vector of `n` logarithmically spaced numbers from -`10^start` to `10^stop`. + Construct a vector of "n" logarithmically spaced numbers from + "10^start" to "10^stop". +``` """ logspace doc""" - broadcast(f, As...) +```rst +broadcast(f, As...) -Broadcasts the arrays `As` to a common size by expanding -singleton dimensions, and returns an array of the results -`f(as...)` for each position. + Broadcasts the arrays "As" to a common size by expanding + singleton dimensions, and returns an array of the results + "f(as...)" for each position. +``` """ broadcast doc""" - broadcast!(f, dest, As...) +```rst +broadcast!(f, dest, As...) -Like `broadcast`, but store the result of `broadcast(f, As...)` -in the `dest` array. Note that `dest` is only used to store the -result, and does not supply arguments to `f` unless it is also -listed in the `As`, as in `broadcast!(f, A, A, B)` to perform -`A[:] = broadcast(f, A, B)`. + Like "broadcast", but store the result of "broadcast(f, As...)" + in the "dest" array. Note that "dest" is only used to store the + result, and does not supply arguments to "f" unless it is also + listed in the "As", as in "broadcast!(f, A, A, B)" to perform + "A[:] = broadcast(f, A, B)". +``` """ broadcast! doc""" - bitbroadcast(f, As...) +```rst +bitbroadcast(f, As...) -Like `broadcast`, but allocates a `BitArray` to store the -result, rather then an `Array`. + Like "broadcast", but allocates a "BitArray" to store the + result, rather then an "Array". +``` """ bitbroadcast doc""" - broadcast_function(f) +```rst +broadcast_function(f) -Returns a function `broadcast_f` such that -`broadcast_function(f)(As...) === broadcast(f, As...)`. Most -useful in the form `const broadcast_f = broadcast_function(f)`. + Returns a function "broadcast_f" such that + "broadcast_function(f)(As...) === broadcast(f, As...)". Most + useful in the form "const broadcast_f = broadcast_function(f)". +``` """ broadcast_function doc""" - broadcast!_function(f) +```rst +broadcast!_function(f) -Like `broadcast_function`, but for `broadcast!`. + Like "broadcast_function", but for "broadcast!". +``` """ broadcast!_function doc""" - getindex(A, inds...) +```rst +getindex(A, inds...) -Returns a subset of array `A` as specified by `inds`, where -each `ind` may be an `Int`, a `Range`, or a `Vector`. See -the manual section on *array indexing* for details. + Returns a subset of array "A" as specified by "inds", where + each "ind" may be an "Int", a "Range", or a "Vector". See + the manual section on *array indexing* for details. +``` """ getindex doc""" - sub(A, inds...) +```rst +sub(A, inds...) -Like `getindex()`, but returns a view into the parent array `A` -with the given indices instead of making a copy. Calling -`getindex()` or `setindex!()` on the returned `SubArray` -computes the indices to the parent array on the fly without -checking bounds. + Like "getindex()", but returns a view into the parent array "A" + with the given indices instead of making a copy. Calling + "getindex()" or "setindex!()" on the returned "SubArray" + computes the indices to the parent array on the fly without + checking bounds. +``` """ sub doc""" - parent(A) +```rst +parent(A) -Returns the `parent array` of an array view type (e.g., -SubArray), or the array itself if it is not a view + Returns the "parent array" of an array view type (e.g., + SubArray), or the array itself if it is not a view +``` """ parent doc""" - parentindexes(A) +```rst +parentindexes(A) -From an array view `A`, returns the corresponding indexes in the -parent + From an array view "A", returns the corresponding indexes in the + parent +``` """ parentindexes doc""" - slicedim(A, d, i) +```rst +slicedim(A, d, i) -Return all the data of `A` where the index for dimension `d` -equals `i`. Equivalent to `A[:,:,...,i,:,:,...]` where `i` is -in position `d`. + Return all the data of "A" where the index for dimension "d" + equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is + in position "d". +``` """ slicedim doc""" - slice(A, inds...) +```rst +slice(A, inds...) -Returns a view of array `A` with the given indices like -`sub()`, but drops all dimensions indexed with scalars. + Returns a view of array "A" with the given indices like + "sub()", but drops all dimensions indexed with scalars. +``` """ slice doc""" - setindex!(A, X, inds...) +```rst +setindex!(A, X, inds...) -Store values from array `X` within some subset of `A` as -specified by `inds`. + Store values from array "X" within some subset of "A" as + specified by "inds". +``` """ setindex! doc""" - broadcast_getindex(A, inds...) +```rst +broadcast_getindex(A, inds...) -Broadcasts the `inds` arrays to a common size like `broadcast`, -and returns an array of the results `A[ks...]`, where `ks` goes -over the positions in the broadcast. + Broadcasts the "inds" arrays to a common size like "broadcast", + and returns an array of the results "A[ks...]", where "ks" goes + over the positions in the broadcast. +``` """ broadcast_getindex doc""" - broadcast_setindex!(A, X, inds...) +```rst +broadcast_setindex!(A, X, inds...) -Broadcasts the `X` and `inds` arrays to a common size and -stores the value from each position in `X` at the indices given -by the same positions in `inds`. + Broadcasts the "X" and "inds" arrays to a common size and + stores the value from each position in "X" at the indices given + by the same positions in "inds". +``` """ broadcast_setindex! doc""" - cat(dims, A...) - -Concatenate the input arrays along the specified dimensions in the -iterable `dims`. For dimensions not in `dims`, all input arrays -should have the same size, which will also be the size of the -output array along that dimension. For dimensions in `dims`, the -size of the output array is the sum of the sizes of the input -arrays along that dimension. If `dims` is a single number, the -different arrays are tightly stacked along that dimension. If -`dims` is an iterable containing several dimensions, this allows -to construct block diagonal matrices and their higher-dimensional -analogues by simultaneously increasing several dimensions for every -new input array and putting zero blocks elsewhere. For example, -block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal -blocks and matching zero blocks away from the diagonal. +```rst +cat(dims, A...) + + Concatenate the input arrays along the specified dimensions in the + iterable "dims". For dimensions not in "dims", all input arrays + should have the same size, which will also be the size of the + output array along that dimension. For dimensions in "dims", the + size of the output array is the sum of the sizes of the input + arrays along that dimension. If "dims" is a single number, the + different arrays are tightly stacked along that dimension. If + "dims" is an iterable containing several dimensions, this allows + to construct block diagonal matrices and their higher-dimensional + 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 with *matrices[1]*, *matrices[2]*, ... as diagonal + blocks and matching zero blocks away from the diagonal. +``` """ cat doc""" - vcat(A...) +```rst +vcat(A...) -Concatenate along dimension 1 + Concatenate along dimension 1 +``` """ vcat doc""" - hcat(A...) +```rst +hcat(A...) -Concatenate along dimension 2 + Concatenate along dimension 2 +``` """ hcat doc""" - hvcat(rows::Tuple{Vararg{Int}}, values...) +```rst +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. For example, -`[a b;c d e]` calls `hvcat((2,3),a,b,c,d,e)`. + 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. For example, + "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". -If the first argument is a single integer `n`, then all block -rows are assumed to have `n` block columns. + If the first argument is a single integer "n", then all block + rows are assumed to have "n" block columns. +``` """ hvcat doc""" - flipdim(A, d) +```rst +flipdim(A, d) -Reverse `A` in dimension `d`. + Reverse "A" in dimension "d". +``` """ flipdim doc""" - circshift(A, shifts) +```rst +circshift(A, shifts) -Circularly shift the data in an array. The second argument is a -vector giving the amount to shift in each dimension. + Circularly shift the data in an array. The second argument is a + vector giving the amount to shift in each dimension. +``` """ circshift doc""" - find(A) +```rst +find(A) -Return a vector of the linear indexes of the non-zeros in `A` -boolean array to an array of indexes of the `true` elements. + Return a vector of the linear indexes of the non-zeros in "A" + (determined by "A[i]!=0"). A common use of this is to convert a + boolean array to an array of indexes of the "true" elements. +``` """ find doc""" - find(f, A) +```rst +find(f, A) -Return a vector of the linear indexes of `A` where `f` returns -true. + Return a vector of the linear indexes of "A" where "f" returns + true. +``` """ find doc""" - findn(A) +```rst +findn(A) -Return a vector of indexes for each dimension giving the locations -of the non-zeros in `A` (determined by `A[i]!=0`). + Return a vector of indexes for each dimension giving the locations + of the non-zeros in "A" (determined by "A[i]!=0"). +``` """ findn doc""" - findnz(A) +```rst +findnz(A) -Return a tuple `(I, J, V)` where `I` and `J` are the row and -column indexes of the non-zero values in matrix `A`, and `V` is -a vector of the non-zero values. + Return a tuple "(I, J, V)" where "I" and "J" are the row and + column indexes of the non-zero values in matrix "A", and "V" is + a vector of the non-zero values. +``` """ findnz doc""" - findfirst(A) +```rst +findfirst(A) -Return the index of the first non-zero value in `A` (determined -by `A[i]!=0`). + Return the index of the first non-zero value in "A" (determined + by "A[i]!=0"). +``` """ findfirst doc""" - findfirst(A, v) +```rst +findfirst(A, v) -Return the index of the first element equal to `v` in `A`. + Return the index of the first element equal to "v" in "A". +``` """ findfirst doc""" - findfirst(predicate, A) +```rst +findfirst(predicate, A) -Return the index of the first element of `A` for which -`predicate` returns true. + Return the index of the first element of "A" for which + "predicate" returns true. +``` """ findfirst doc""" - findlast(A) +```rst +findlast(A) -Return the index of the last non-zero value in `A` (determined by -`A[i]!=0`). + Return the index of the last non-zero value in "A" (determined by + "A[i]!=0"). +``` """ findlast doc""" - findlast(A, v) +```rst +findlast(A, v) -Return the index of the last element equal to `v` in `A`. + Return the index of the last element equal to "v" in "A". +``` """ findlast doc""" - findlast(predicate, A) +```rst +findlast(predicate, A) -Return the index of the last element of `A` for which -`predicate` returns true. + Return the index of the last element of "A" for which + "predicate" returns true. +``` """ findlast doc""" - findnext(A, i) +```rst +findnext(A, i) -Find the next index >= `i` of a non-zero element of `A`, or + Find the next index >= "i" of a non-zero element of "A", or + "0" if not found. +``` """ findnext doc""" - findnext(predicate, A, i) +```rst +findnext(predicate, A, i) -Find the next index >= `i` of an element of `A` for which -`0` if not found. + Find the next index >= "i" of an element of "A" for which + "predicate" returns true, or "0" if not found. +``` """ findnext doc""" - findnext(A, v, i) +```rst +findnext(A, v, i) -Find the next index >= `i` of an element of `A` equal to `v` -`predicate` returns true, or `0` if not found. + Find the next index >= "i" of an element of "A" equal to "v" + (using "=="), or "0" if not found. +``` """ findnext doc""" - findprev(A, i) +```rst +findprev(A, i) -Find the previous index <= `i` of a non-zero element of `A`, or -0 if not found. + Find the previous index <= "i" of a non-zero element of "A", or + 0 if not found. +``` """ findprev doc""" - findprev(predicate, A, i) +```rst +findprev(predicate, A, i) -Find the previous index <= `i` of an element of `A` for which -`predicate` returns true, or `0` if not found. + Find the previous index <= "i" of an element of "A" for which + "predicate" returns true, or "0" if not found. +``` """ findprev doc""" - findprev(A, v, i) +```rst +findprev(A, v, i) -Find the previous index <= `i` of an element of `A` equal to -`v` (using `==`), or `0` if not found. + Find the previous index <= "i" of an element of "A" equal to + "v" (using "=="), or "0" if not found. +``` """ findprev doc""" - permutedims(A, perm) +```rst +permutedims(A, perm) -Permute the dimensions of array `A`. `perm` is a vector -specifying a permutation of length `ndims(A)`. This is a -generalization of transpose for multi-dimensional arrays. Transpose -is equivalent to `permutedims(A, [2,1])`. + Permute the dimensions of array "A". "perm" is a vector + specifying a permutation of length "ndims(A)". This is a + generalization of transpose for multi-dimensional arrays. Transpose + is equivalent to "permutedims(A, [2,1])". +``` """ permutedims doc""" - ipermutedims(A, perm) +```rst +ipermutedims(A, perm) -Like `permutedims()`, except the inverse of the given permutation -is applied. + Like "permutedims()", except the inverse of the given permutation + is applied. +``` """ ipermutedims doc""" - permutedims!(dest, src, perm) +```rst +permutedims!(dest, src, perm) -Permute the dimensions of array `src` and store the result in the -array `dest`. `perm` is a vector specifying a permutation of -length `ndims(src)`. The preallocated array `dest` should have -`size(dest) == size(src)[perm]` and is completely overwritten. No -in-place permutation is supported and unexpected results will -happen if *src* and *dest* have overlapping memory regions. + Permute the dimensions of array "src" and store the result in the + array "dest". "perm" is a vector specifying a permutation of + length "ndims(src)". The preallocated array "dest" should have + "size(dest) == size(src)[perm]" and is completely overwritten. No + in-place permutation is supported and unexpected results will + happen if *src* and *dest* have overlapping memory regions. +``` """ permutedims! doc""" - squeeze(A, dims) +```rst +squeeze(A, dims) -Remove the dimensions specified by `dims` from array `A`. -Elements of `dims` must be unique and within the range + Remove the dimensions specified by "dims" from array "A". + Elements of "dims" must be unique and within the range + "1:ndims(A)". +``` """ squeeze doc""" - vec(Array) -> Vector +```rst +vec(Array) -> Vector -Vectorize an array using column-major convention. + Vectorize an array using column-major convention. +``` """ vec doc""" - promote_shape(s1, s2) +```rst +promote_shape(s1, s2) -Check two array shapes for compatibility, allowing trailing -singleton dimensions, and return whichever shape has more -dimensions. + Check two array shapes for compatibility, allowing trailing + singleton dimensions, and return whichever shape has more + dimensions. +``` """ promote_shape doc""" - checkbounds(array, indexes...) +```rst +checkbounds(array, indexes...) -Throw an error if the specified indexes are not in bounds for the -given array. + Throw an error if the specified indexes are not in bounds for the + given array. +``` """ checkbounds doc""" - randsubseq(A, p) -> Vector +```rst +randsubseq(A, p) -> Vector -Return a vector consisting of a random subsequence of the given -array `A`, where each element of `A` is included (in order) -with independent probability `p`. (Complexity is linear in -small and `A` is large.) Technically, this process is known as + Return a vector consisting of a random subsequence of the given + array "A", where each element of "A" is included (in order) + with independent probability "p". (Complexity is linear in + "p*length(A)", so this function is efficient even if "p" is + small and "A" is large.) Technically, this process is known as + "Bernoulli sampling" of "A". +``` """ randsubseq doc""" - randsubseq!(S, A, p) +```rst +randsubseq!(S, A, p) -Like `randsubseq`, but the results are stored in `S` (which is -resized as needed). + Like "randsubseq", but the results are stored in "S" (which is + resized as needed). +``` """ randsubseq! doc""" - cumprod(A[, dim]) +```rst +cumprod(A[, dim]) -Cumulative product along a dimension `dim` (defaults to 1). See -also `cumprod!()` to use a preallocated output array, both for -performance and to control the precision of the output (e.g. to -avoid overflow). + Cumulative product along a dimension "dim" (defaults to 1). See + also "cumprod!()" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). +``` """ cumprod doc""" - cumprod!(B, A[, dim]) +```rst +cumprod!(B, A[, dim]) -Cumulative product of `A` along a dimension, storing the result -in `B`. The dimension defaults to 1. + Cumulative product of "A" along a dimension, storing the result + in "B". The dimension defaults to 1. +``` """ cumprod! doc""" - cumsum(A[, dim]) +```rst +cumsum(A[, dim]) -Cumulative sum along a dimension `dim` (defaults to 1). See also -performance and to control the precision of the output (e.g. to -avoid overflow). + Cumulative sum along a dimension "dim" (defaults to 1). See also + "cumsum!()" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). +``` """ cumsum doc""" - cumsum!(B, A[, dim]) +```rst +cumsum!(B, A[, dim]) -Cumulative sum of `A` along a dimension, storing the result in + Cumulative sum of "A" along a dimension, storing the result in + "B". The dimension defaults to 1. +``` """ cumsum! doc""" - cumsum_kbn(A[, dim]) +```rst +cumsum_kbn(A[, dim]) -Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier -compensated summation algorithm for additional accuracy. The -dimension defaults to 1. + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier + compensated summation algorithm for additional accuracy. The + dimension defaults to 1. +``` """ cumsum_kbn doc""" - cummin(A[, dim]) +```rst +cummin(A[, dim]) -Cumulative minimum along a dimension. The dimension defaults to 1. + Cumulative minimum along a dimension. The dimension defaults to 1. +``` """ cummin doc""" - cummax(A[, dim]) +```rst +cummax(A[, dim]) -Cumulative maximum along a dimension. The dimension defaults to 1. + Cumulative maximum along a dimension. The dimension defaults to 1. +``` """ cummax doc""" - diff(A[, dim]) +```rst +diff(A[, dim]) -Finite difference operator of matrix or vector. + Finite difference operator of matrix or vector. +``` """ diff doc""" - gradient(F[, h]) +```rst +gradient(F[, h]) -Compute differences along vector `F`, using `h` as the spacing -between points. The default spacing is one. + Compute differences along vector "F", using "h" as the spacing + between points. The default spacing is one. +``` """ gradient doc""" - rot180(A) +```rst +rot180(A) -Rotate matrix `A` 180 degrees. + Rotate matrix "A" 180 degrees. +``` """ rot180 doc""" - rot180(A, k) +```rst +rot180(A, k) -Rotate matrix `A` 180 degrees an integer `k` number of times. -If `k` is even, this is equivalent to a `copy`. + Rotate matrix "A" 180 degrees an integer "k" number of times. + If "k" is even, this is equivalent to a "copy". +``` """ rot180 doc""" - rotl90(A) +```rst +rotl90(A) -Rotate matrix `A` left 90 degrees. + Rotate matrix "A" left 90 degrees. +``` """ rotl90 doc""" - rotl90(A, k) +```rst +rotl90(A, k) -Rotate matrix `A` left 90 degrees an integer `k` number of -times. If `k` is zero or a multiple of four, this is equivalent -to a `copy`. + Rotate matrix "A" left 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". +``` """ rotl90 doc""" - rotr90(A) +```rst +rotr90(A) -Rotate matrix `A` right 90 degrees. + Rotate matrix "A" right 90 degrees. +``` """ rotr90 doc""" - rotr90(A, k) +```rst +rotr90(A, k) -Rotate matrix `A` right 90 degrees an integer `k` number of -times. If `k` is zero or a multiple of four, this is equivalent -to a `copy`. + Rotate matrix "A" right 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". +``` """ rotr90 doc""" - reducedim(f, A, dims[, initial]) +```rst +reducedim(f, A, dims[, initial]) + + Reduce 2-argument function "f" along dimensions of "A". + "dims" is a vector specifying the dimensions to reduce, and + "initial" is the initial value to use in the reductions. For *+*, + ***, *max* and *min* the *initial* argument is optional. -Reduce 2-argument function `f` along dimensions of `A`. -The associativity of the reduction is implementation-dependent; if -you need a particular associativity, e.g. left-to-right, you should -write your own loop. See documentation for `reduce`. + The associativity of the reduction is implementation-dependent; if + you need a particular associativity, e.g. left-to-right, you should + write your own loop. See documentation for "reduce". +``` """ reducedim doc""" - mapreducedim(f, op, A, dims[, initial]) +```rst +mapreducedim(f, op, A, dims[, initial]) -Evaluates to the same as *reducedim(op, map(f, A), dims, -f(initial))*, but is generally faster because the intermediate -array is avoided. + Evaluates to the same as *reducedim(op, map(f, A), dims, + f(initial))*, but is generally faster because the intermediate + array is avoided. +``` """ mapreducedim doc""" - mapslices(f, A, dims) +```rst +mapslices(f, A, dims) -Transform the given dimensions of array `A` using function `f`. -where the colons go in this expression. The results are -concatenated along the remaining dimensions. For example, if + Transform the given dimensions of array "A" using function "f". + "f" is called on each slice of "A" of the form + "A[...,:,...,:,...]". "dims" is an integer vector specifying + where the colons go in this expression. The results are + concatenated along the remaining dimensions. For example, if + "dims" is "[1,2]" and A is 4-dimensional, "f" is called on + "A[:,:,i,j]" for all "i" and "j". +``` """ mapslices doc""" - sum_kbn(A) +```rst +sum_kbn(A) -Returns the sum of all array elements, using the Kahan-Babuska- -Neumaier compensated summation algorithm for additional accuracy. + Returns the sum of all array elements, using the Kahan-Babuska- + Neumaier compensated summation algorithm for additional accuracy. +``` """ sum_kbn doc""" - cartesianmap(f, dims) +```rst +cartesianmap(f, dims) + + Given a "dims" tuple of integers "(m, n, ...)", call "f" on + all combinations of integers in the ranges "1:m", "1:n", etc. -Given a `dims` tuple of integers `(m, n, ...)`, call `f` on -all combinations of integers in the ranges `1:m`, `1:n`, etc. + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 +``` """ cartesianmap doc""" - nthperm(v, k) +```rst +nthperm(v, k) -Compute the kth lexicographic permutation of a vector. + Compute the kth lexicographic permutation of a vector. +``` """ nthperm doc""" - nthperm(p) +```rst +nthperm(p) -Return the `k` that generated permutation `p`. Note that + Return the "k" that generated permutation "p". Note that + "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". +``` """ nthperm doc""" - nthperm!(v, k) +```rst +nthperm!(v, k) -In-place version of `nthperm()`. + In-place version of "nthperm()". +``` """ nthperm! doc""" - randperm([rng], n) +```rst +randperm([rng], n) -Construct a random permutation of length `n`. The optional -Numbers*. + Construct a random permutation of length "n". The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. +``` """ randperm doc""" - invperm(v) +```rst +invperm(v) -Return the inverse permutation of v. + Return the inverse permutation of v. +``` """ invperm doc""" - isperm(v) -> Bool +```rst +isperm(v) -> Bool -Returns true if v is a valid permutation. + Returns true if v is a valid permutation. +``` """ isperm doc""" - permute!(v, p) +```rst +permute!(v, p) -Permute vector `v` in-place, according to permutation `p`. No -checking is done to verify that `p` is a permutation. -To return a new permutation, use `v[p]`. Note that this is -generally faster than `permute!(v,p)` for large vectors. + Permute vector "v" in-place, according to permutation "p". No + checking is done to verify that "p" is a permutation. + + To return a new permutation, use "v[p]". Note that this is + generally faster than "permute!(v,p)" for large vectors. +``` """ permute! doc""" - ipermute!(v, p) +```rst +ipermute!(v, p) -Like permute!, but the inverse of the given permutation is applied. + Like permute!, but the inverse of the given permutation is applied. +``` """ ipermute! doc""" - randcycle([rng], n) +```rst +randcycle([rng], n) -Construct a random cyclic permutation of length `n`. The optional -Numbers*. + Construct a random cyclic permutation of length "n". The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. +``` """ randcycle doc""" - shuffle([rng], v) +```rst +shuffle([rng], v) -Return a randomly permuted copy of `v`. The optional `rng` -argument specifies a random number generator, see *Random Numbers*. + Return a randomly permuted copy of "v". The optional "rng" + argument specifies a random number generator, see *Random Numbers*. +``` """ shuffle doc""" - shuffle!([rng], v) +```rst +shuffle!([rng], v) -In-place version of `shuffle()`. + In-place version of "shuffle()". +``` """ shuffle! doc""" - reverse(v[, start=1[, stop=length(v)]]) +```rst +reverse(v[, start=1[, stop=length(v)]]) -Return a copy of `v` reversed from start to stop. + Return a copy of "v" reversed from start to stop. +``` """ reverse doc""" - reverseind(v, i) +```rst +reverseind(v, i) -Given an index `i` in `reverse(v)`, return the corresponding -index in `v` so that `v[reverseind(v,i)] == reverse(v)[i]`. -string.) + Given an index "i" in "reverse(v)", return the corresponding + index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". + (This can be nontrivial in the case where "v" is a Unicode + string.) +``` """ reverseind doc""" - reverse!(v[, start=1[, stop=length(v)]]) -> v +```rst +reverse!(v[, start=1[, stop=length(v)]]) -> v -In-place version of `reverse()`. + In-place version of "reverse()". +``` """ reverse! doc""" - combinations(array, n) +```rst +combinations(array, n) -Generate all combinations of `n` elements from an indexable -object. Because the number of combinations can be very large, this -function returns an iterator object. Use -combinations. + Generate all combinations of "n" elements from an indexable + object. Because the number of combinations can be very large, this + function returns an iterator object. Use + "collect(combinations(array,n))" to get an array of all + combinations. +``` """ combinations doc""" - permutations(array) +```rst +permutations(array) -Generate all permutations of an indexable object. Because the -number of permutations can be very large, this function returns an -iterator object. Use `collect(permutations(array))` to get an -array of all permutations. + Generate all permutations of an indexable object. Because the + number of permutations can be very large, this function returns an + iterator object. Use "collect(permutations(array))" to get an + array of all permutations. +``` """ permutations doc""" - partitions(n) +```rst +partitions(n) -Generate all integer arrays that sum to `n`. Because the number -of partitions can be very large, this function returns an iterator -object. Use `collect(partitions(n))` to get an array of all -partitions. The number of partitions to generate can be efficiently -computed using `length(partitions(n))`. + Generate all integer arrays that sum to "n". Because the number + of partitions can be very large, this function returns an iterator + object. Use "collect(partitions(n))" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using "length(partitions(n))". +``` """ partitions doc""" - partitions(n, m) +```rst +partitions(n, m) -Generate all arrays of `m` integers that sum to `n`. Because -the number of partitions can be very large, this function returns -an iterator object. Use `collect(partitions(n,m))` to get an -array of all partitions. The number of partitions to generate can -be efficiently computed using `length(partitions(n,m))`. + Generate all arrays of "m" integers that sum to "n". Because + the number of partitions can be very large, this function returns + an iterator object. Use "collect(partitions(n,m))" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using "length(partitions(n,m))". +``` """ partitions doc""" - partitions(array) +```rst +partitions(array) -Generate all set partitions of the elements of an array, -represented as arrays of arrays. Because the number of partitions -can be very large, this function returns an iterator object. Use -The number of partitions to generate can be efficiently computed -using `length(partitions(array))`. + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + "collect(partitions(array))" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using "length(partitions(array))". +``` """ partitions doc""" - partitions(array, m) +```rst +partitions(array, m) -Generate all set partitions of the elements of an array into -exactly m subsets, represented as arrays of arrays. Because the -number of partitions can be very large, this function returns an -iterator object. Use `collect(partitions(array,m))` to get an -array of all partitions. The number of partitions into m subsets is -equal to the Stirling number of the second kind and can be -efficiently computed using `length(partitions(array,m))`. + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use "collect(partitions(array,m))" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using "length(partitions(array,m))". +``` """ partitions doc""" - bitpack(A::AbstractArray{T, N}) -> BitArray +```rst +bitpack(A::AbstractArray{T, N}) -> BitArray -Converts a numeric array to a packed boolean array + Converts a numeric array to a packed boolean array +``` """ bitpack doc""" - bitunpack(B::BitArray{N}) -> Array{Bool,N} +```rst +bitunpack(B::BitArray{N}) -> Array{Bool,N} -Converts a packed boolean array to an array of booleans + Converts a packed boolean array to an array of booleans +``` """ bitunpack doc""" - flipbits!(B::BitArray{N}) -> BitArray{N} +```rst +flipbits!(B::BitArray{N}) -> BitArray{N} -Performs a bitwise not operation on B. See *~ operator*. + Performs a bitwise not operation on B. See *~ operator*. +``` """ flipbits! doc""" - rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +```rst +rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} -Performs a left rotation operation on `src` and put the result -into `dest`. + Performs a left rotation operation on "src" and put the result + into "dest". +``` """ rol! doc""" - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} +```rst +rol!(B::BitArray{1}, i::Integer) -> BitArray{1} -Performs a left rotation operation on B. + Performs a left rotation operation on B. +``` """ rol! doc""" - rol(B::BitArray{1}, i::Integer) -> BitArray{1} +```rst +rol(B::BitArray{1}, i::Integer) -> BitArray{1} -Performs a left rotation operation. + Performs a left rotation operation. +``` """ rol doc""" - ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +```rst +ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} -Performs a right rotation operation on `src` and put the result -into `dest`. + Performs a right rotation operation on "src" and put the result + into "dest". +``` """ ror! doc""" - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} +```rst +ror!(B::BitArray{1}, i::Integer) -> BitArray{1} -Performs a right rotation operation on B. + Performs a right rotation operation on B. +``` """ ror! doc""" - ror(B::BitArray{1}, i::Integer) -> BitArray{1} +```rst +ror(B::BitArray{1}, i::Integer) -> BitArray{1} -Performs a right rotation operation. + Performs a right rotation operation. +``` """ ror doc""" - sparse(I, J, V[, m, n, combine]) +```rst +sparse(I, J, V[, m, n, combine]) -Create a sparse matrix `S` of dimensions `m x n` such that -combine duplicates. If `m` and `n` are not specified, they are -set to `max(I)` and `max(J)` respectively. If the `combine` -function is not supplied, duplicates are added by default. + Create a sparse matrix "S" of dimensions "m x n" such that + "S[I[k], J[k]] = V[k]". The "combine" function is used to + combine duplicates. If "m" and "n" are not specified, they are + set to "max(I)" and "max(J)" respectively. If the "combine" + function is not supplied, duplicates are added by default. +``` """ sparse doc""" - sparsevec(I, V[, m, combine]) +```rst +sparsevec(I, V[, m, combine]) -Create a sparse matrix `S` of size `m x 1` such that `S[I[k]] -which defaults to `+` if it is not provided. In julia, sparse -vectors are really just sparse matrices with one column. Given -Julia's Compressed Sparse Columns (CSC) storage format, a sparse -column matrix with one column is sparse, whereas a sparse row -matrix with one row ends up being dense. + Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] + = V[k]". Duplicates are combined using the "combine" function, + which defaults to "+" if it is not provided. In julia, sparse + vectors are really just sparse matrices with one column. Given + Julia's Compressed Sparse Columns (CSC) storage format, a sparse + column matrix with one column is sparse, whereas a sparse row + matrix with one row ends up being dense. +``` """ sparsevec doc""" - sparsevec(D::Dict[, m]) +```rst +sparsevec(D::Dict[, m]) -Create a sparse matrix of size `m x 1` where the row values are -keys from the dictionary, and the nonzero values are the values -from the dictionary. + Create a sparse matrix of size "m x 1" where the row values are + keys from the dictionary, and the nonzero values are the values + from the dictionary. +``` """ sparsevec doc""" - issparse(S) +```rst +issparse(S) -Returns `true` if `S` is sparse, and `false` otherwise. + Returns "true" if "S" is sparse, and "false" otherwise. +``` """ issparse doc""" - sparse(A) +```rst +sparse(A) -Convert an AbstractMatrix `A` into a sparse matrix. + Convert an AbstractMatrix "A" into a sparse matrix. +``` """ sparse doc""" - sparsevec(A) +```rst +sparsevec(A) -Convert a dense vector `A` into a sparse matrix of size `m x -1`. In julia, sparse vectors are really just sparse matrices with -one column. + Convert a dense vector "A" into a sparse matrix of size "m x + 1". In julia, sparse vectors are really just sparse matrices with + one column. +``` """ sparsevec doc""" - full(S) +```rst +full(S) -Convert a sparse matrix `S` into a dense matrix. + Convert a sparse matrix "S" into a dense matrix. +``` """ full doc""" - nnz(A) +```rst +nnz(A) -Returns the number of stored (filled) elements in a sparse matrix. + Returns the number of stored (filled) elements in a sparse matrix. +``` """ nnz doc""" - spzeros(m, n) +```rst +spzeros(m, n) -Create a sparse matrix of size `m x n`. This sparse matrix will -not contain any nonzero values. No storage will be allocated for -nonzero values during construction. + Create a sparse matrix of size "m x n". This sparse matrix will + not contain any nonzero values. No storage will be allocated for + nonzero values during construction. +``` """ spzeros doc""" - spones(S) +```rst +spones(S) -Create a sparse matrix with the same structure as that of `S`, -but with every nonzero element having the value `1.0`. + Create a sparse matrix with the same structure as that of "S", + but with every nonzero element having the value "1.0". +``` """ spones doc""" - speye(type, m[, n]) +```rst +speye(type, m[, n]) -Create a sparse identity matrix of specified type of size `m x -m`. In case `n` is supplied, create a sparse identity matrix of -size `m x n`. + Create a sparse identity matrix of specified type of size "m x + m". In case "n" is supplied, create a sparse identity matrix of + size "m x n". +``` """ speye doc""" - spdiagm(B, d[, m, n]) +```rst +spdiagm(B, d[, m, n]) -Construct a sparse diagonal matrix. `B` is a tuple of vectors -containing the diagonals and `d` is a tuple containing the -positions of the diagonals. In the case the input contains only one -diagonaly, `B` can be a vector (instead of a tuple) and `d` can -be the diagonal position (instead of a tuple), defaulting to 0 -resulting sparse matrix. + Construct a sparse diagonal matrix. "B" is a tuple of vectors + containing the diagonals and "d" is a tuple containing the + positions of the diagonals. In the case the input contains only one + diagonaly, "B" can be a vector (instead of a tuple) and "d" can + be the diagonal position (instead of a tuple), defaulting to 0 + (diagonal). Optionally, "m" and "n" specify the size of the + resulting sparse matrix. +``` """ spdiagm doc""" - sprand([rng], m, n, p[, rfn]) +```rst +sprand([rng], m, n, p[, rfn]) -Create a random `m` by `n` sparse matrix, in which the -probability of any element being nonzero is independently given by -by `rfn`. The uniform distribution is used in case `rfn` is not -specified. The optional `rng` argument specifies a random number -generator, see *Random Numbers*. + Create a random "m" by "n" sparse matrix, in which the + probability of any element being nonzero is independently given by + "p" (and hence the mean density of nonzeros is also exactly + "p"). Nonzero values are sampled from the distribution specified + by "rfn". The uniform distribution is used in case "rfn" is not + specified. The optional "rng" argument specifies a random number + generator, see *Random Numbers*. +``` """ sprand doc""" - sprandn(m, n, p) +```rst +sprandn(m, n, p) -Create a random `m` by `n` sparse matrix with the specified -nonzero values are sampled from the normal distribution. + Create a random "m" by "n" sparse matrix with the specified + (independent) probability "p" of any entry being nonzero, where + nonzero values are sampled from the normal distribution. +``` """ sprandn doc""" - sprandbool(m, n, p) +```rst +sprandbool(m, n, p) -Create a random `m` by `n` sparse boolean matrix with the -specified (independent) probability `p` of any entry being + Create a random "m" by "n" sparse boolean matrix with the + specified (independent) probability "p" of any entry being + "true". +``` """ sprandbool doc""" - etree(A[, post]) +```rst +etree(A[, post]) -Compute the elimination tree of a symmetric sparse matrix `A` -from `triu(A)` and, optionally, its post-ordering permutation. + Compute the elimination tree of a symmetric sparse matrix "A" + from "triu(A)" and, optionally, its post-ordering permutation. +``` """ etree doc""" - symperm(A, p) +```rst +symperm(A, p) -Return the symmetric permutation of A, which is `A[p,p]`. A -should be symmetric and sparse, where only the upper triangular -part of the matrix is stored. This algorithm ignores the lower -triangular part of the matrix. Only the upper triangular part of -the result is returned as well. + Return the symmetric permutation of A, which is "A[p,p]". A + should be symmetric and sparse, where only the upper triangular + part of the matrix is stored. This algorithm ignores the lower + triangular part of the matrix. Only the upper triangular part of + the result is returned as well. +``` """ symperm doc""" - nonzeros(A) +```rst +nonzeros(A) -Return a vector of the structural nonzero values in sparse matrix -matrix. The returned vector points directly to the internal nonzero -storage of `A`, and any modifications to the returned vector will -mutate `A` as well. See `rowvals(A)` and `nzrange(A, col)`. + Return a vector of the structural nonzero values in sparse matrix + "A". This includes zeros that are explicitly stored in the sparse + matrix. The returned vector points directly to the internal nonzero + storage of "A", and any modifications to the returned vector will + mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". +``` """ nonzeros doc""" - rowvals(A) +```rst +rowvals(A) -Return a vector of the row indices of `A`, and any modifications -to the returned vector will mutate `A` as well. Given the -internal storage format of sparse matrices, providing access to how -the row indices are stored internally can be useful in conjuction -with iterating over structural nonzero values. See `nonzeros(A)` -and `nzrange(A, col)`. + Return a vector of the row indices of "A", and any modifications + to the returned vector will mutate "A" as well. Given the + internal storage format of sparse matrices, providing access to how + the row indices are stored internally can be useful in conjuction + with iterating over structural nonzero values. See "nonzeros(A)" + and "nzrange(A, col)". +``` """ rowvals doc""" - nzrange(A, col) +```rst +nzrange(A, col) + + Return the range of indices to the structural nonzero values of a + sparse matrix column. In conjunction with "nonzeros(A)" and + "rowvals(A)", this allows for convenient iterating over a sparse + matrix -Return the range of indices to the structural nonzero values of a -sparse matrix column. In conjunction with `nonzeros(A)` and -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 +``` """ nzrange doc""" - exit([code]) +```rst +exit([code]) -Quit (or control-D at the prompt). The default exit code is zero, -indicating that the processes completed successfully. + Quit (or control-D at the prompt). The default exit code is zero, + indicating that the processes completed successfully. +``` """ exit doc""" - quit() +```rst +quit() -Quit the program indicating that the processes completed -successfully. This function calls `exit(0)` (see `exit()`). + Quit the program indicating that the processes completed + successfully. This function calls "exit(0)" (see "exit()"). +``` """ quit doc""" - atexit(f) +```rst +atexit(f) -Register a zero-argument function to be called at exit. + Register a zero-argument function to be called at exit. +``` """ atexit doc""" - atreplinit(f) +```rst +atreplinit(f) -Register a one-argument function to be called before the REPL -interface is initialized in interactive sessions; this is useful to -customize the interface. The argument of `f` is the REPL object. -This function should be called from within the `.juliarc.jl` -initialization file. + Register a one-argument function to be called before the REPL + interface is initialized in interactive sessions; this is useful to + customize the interface. The argument of "f" is the REPL object. + This function should be called from within the ".juliarc.jl" + initialization file. +``` """ atreplinit doc""" - isinteractive() -> Bool +```rst +isinteractive() -> Bool -Determine whether Julia is running an interactive session. + Determine whether Julia is running an interactive session. +``` """ isinteractive doc""" - whos([Module,] [pattern::Regex]) +```rst +whos([Module,] [pattern::Regex]) -Print information about exported global variables in a module, -optionally restricted to those matching `pattern`. + Print information about exported global variables in a module, + optionally restricted to those matching "pattern". +``` """ whos doc""" - edit(file::AbstractString[, line]) +```rst +edit(file::AbstractString[, line]) -Edit a file optionally providing a line number to edit at. Returns -to the julia prompt when you quit the editor. + Edit a file optionally providing a line number to edit at. Returns + to the julia prompt when you quit the editor. +``` """ edit doc""" - edit(function[, types]) +```rst +edit(function[, types]) -Edit the definition of a function, optionally specifying a tuple of -types to indicate which method to edit. + Edit the definition of a function, optionally specifying a tuple of + types to indicate which method to edit. +``` """ edit doc""" - @edit() +```rst +@edit() -Evaluates the arguments to the function call, determines their -types, and calls the `edit` function on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls the "edit" function on the resulting expression +``` """ @edit doc""" - less(file::AbstractString[, line]) +```rst +less(file::AbstractString[, line]) -Show a file using the default pager, optionally providing a -starting line number. Returns to the julia prompt when you quit the -pager. + Show a file using the default pager, optionally providing a + starting line number. Returns to the julia prompt when you quit the + pager. +``` """ less doc""" - less(function[, types]) +```rst +less(function[, types]) -Show the definition of a function using the default pager, -optionally specifying a tuple of types to indicate which method to -see. + Show the definition of a function using the default pager, + optionally specifying a tuple of types to indicate which method to + see. +``` """ less doc""" - @less() +```rst +@less() -Evaluates the arguments to the function call, determines their -types, and calls the `less` function on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls the "less" function on the resulting expression +``` """ @less doc""" - clipboard(x) +```rst +clipboard(x) -Send a printed form of `x` to the operating system clipboard + Send a printed form of "x" to the operating system clipboard + ("copy"). +``` """ clipboard doc""" - clipboard() -> AbstractString +```rst +clipboard() -> AbstractString -Return a string with the contents of the operating system clipboard + Return a string with the contents of the operating system clipboard + ("paste"). +``` """ clipboard doc""" - require(file::AbstractString...) +```rst +require(file::AbstractString...) + + Load source files once, in the context of the "Main" module, on + every active node, searching standard locations for files. + "require" is considered a top-level operation, so it sets the + current "include" path but does not use it to search for files + (see help for "include"). This function is typically used to load + library code, and is implicitly called by "using" to load + packages. -Load source files once, in the context of the `Main` module, on -every active node, searching standard locations for files. -current `include` path but does not use it to search for files -library code, and is implicitly called by `using` to load -packages. -When searching for files, `require` first looks in the current -working directory, then looks for package code under `Pkg.dir()`, -then tries paths in the global array `LOAD_PATH`. + When searching for files, "require" first looks in the current + working directory, then looks for package code under "Pkg.dir()", + then tries paths in the global array "LOAD_PATH". +``` """ require doc""" - reload(file::AbstractString) +```rst +reload(file::AbstractString) -Like `require`, except forces loading of files regardless of -whether they have been loaded before. Typically used when -interactively developing libraries. + Like "require", except forces loading of files regardless of + whether they have been loaded before. Typically used when + interactively developing libraries. +``` """ reload doc""" - include(path::AbstractString) +```rst +include(path::AbstractString) -Evaluate the contents of a source file in the current context. -During including, a task-local include path is set to the directory -containing the file. Nested calls to `include` will search -relative to that path. All paths refer to files on node 1 when -running in parallel, and files will be fetched from node 1. This -function is typically used to load source interactively, or to -combine files in packages that are broken into multiple source -files. + Evaluate the contents of a source file in the current context. + During including, a task-local include path is set to the directory + containing the file. Nested calls to "include" will search + relative to that path. All paths refer to files on node 1 when + running in parallel, and files will be fetched from node 1. This + function is typically used to load source interactively, or to + combine files in packages that are broken into multiple source + files. +``` """ include doc""" - include_string(code::AbstractString) +```rst +include_string(code::AbstractString) -Like `include`, except reads code from the given string rather -than from a file. Since there is no file path involved, no path -processing or fetching from node 1 is done. + Like "include", except reads code from the given string rather + than from a file. Since there is no file path involved, no path + processing or fetching from node 1 is done. +``` """ include_string doc""" - which(f, types) +```rst +which(f, types) -Returns the method of `f` (a `Method` object) that would be -called for arguments of the given types. -If `types` is an abstract type, then the method that would be -called by `invoke` is returned. + Returns the method of "f" (a "Method" object) that would be + called for arguments of the given types. + + If "types" is an abstract type, then the method that would be + called by "invoke" is returned. +``` """ which doc""" - which(symbol) +```rst +which(symbol) -Return the module in which the binding for the variable referenced -by `symbol` was created. + Return the module in which the binding for the variable referenced + by "symbol" was created. +``` """ which doc""" - @which() +```rst +@which() -Applied to a function call, it evaluates the arguments to the -specified function call, and returns the `Method` object for the -method that would be called for those arguments. Applied to a -variable, it returns the module in which the variable was bound. It -calls out to the `which` function. + Applied to a function call, it evaluates the arguments to the + specified function call, and returns the "Method" object for the + method that would be called for those arguments. Applied to a + variable, it returns the module in which the variable was bound. It + calls out to the "which" function. +``` """ @which doc""" - methods(f[, types]) +```rst +methods(f[, types]) + + Returns the method table for "f". -Returns the method table for `f`. -If `types` is specified, returns an array of methods whose types -match. + If "types" is specified, returns an array of methods whose types + match. +``` """ methods doc""" - methodswith(typ[, module or function][, showparents]) +```rst +methodswith(typ[, module or function][, showparents]) + + Return an array of methods with an argument of type "typ". If + optional "showparents" is "true", also return arguments with a + parent type of "typ", excluding type "Any". -Return an array of methods with an argument of type `typ`. If -optional `showparents` is `true`, also return arguments with a -parent type of `typ`, excluding type `Any`. -The optional second argument restricts the search to a particular -module or function. + The optional second argument restricts the search to a particular + module or function. +``` """ methodswith doc""" - @show() +```rst +@show() -Show an expression and result, returning the result + Show an expression and result, returning the result +``` """ @show doc""" - versioninfo([verbose::Bool]) +```rst +versioninfo([verbose::Bool]) -Print information about the version of Julia in use. If the -as well. + Print information about the version of Julia in use. If the + "verbose" argument is true, detailed system information is shown + as well. +``` """ versioninfo doc""" - workspace() +```rst +workspace() -Replace the top-level module (`Main`) with a new one, providing a -clean workspace. The previous `Main` module is made available as -statement such as `using LastMain.Package`. -This function should only be used interactively. + Replace the top-level module ("Main") with a new one, providing a + clean workspace. The previous "Main" module is made available as + "LastMain". A previously-loaded package can be accessed using a + statement such as "using LastMain.Package". + + This function should only be used interactively. +``` """ workspace doc""" - is(x, y) -> Bool +```rst +is(x, y) -> Bool +===(x, y) -> Bool +≡(x, y) -> Bool -Determine whether `x` and `y` are identical, in the sense that -no program could distinguish them. Compares mutable objects by -address in memory, and compares immutable objects (such as numbers) -by contents at the bit level. This function is sometimes called + Determine whether "x" and "y" are identical, in the sense that + no program could distinguish them. Compares mutable objects by + address in memory, and compares immutable objects (such as numbers) + by contents at the bit level. This function is sometimes called + "egal". +``` """ is doc""" - isa(x, type) -> Bool +```rst +isa(x, type) -> Bool -Determine whether `x` is of the given `type`. + Determine whether "x" is of the given "type". +``` """ isa doc""" - isequal(x, y) +```rst +isequal(x, y) + + Similar to "==", except treats all floating-point "NaN" values + as equal to each other, and treats "-0.0" as unequal to "0.0". + The default implementation of "isequal" calls "==", so if you + have a type that doesn't have these floating-point subtleties then + you probably only need to define "==". + + "isequal" is the comparison function used by hash tables + ("Dict"). "isequal(x,y)" must imply that "hash(x) == + hash(y)". + + This typically means that if you define your own "==" function + then you must define a corresponding "hash" (and vice versa). + Collections typically implement "isequal" by calling "isequal" + recursively on all contents. -Similar to `==`, except treats all floating-point `NaN` values -as equal to each other, and treats `-0.0` as unequal to `0.0`. -The default implementation of `isequal` calls `==`, so if you -have a type that doesn't have these floating-point subtleties then -you probably only need to define `==`. -hash(y)`. -This typically means that if you define your own `==` function -then you must define a corresponding `hash` (and vice versa). -Collections typically implement `isequal` by calling `isequal` -recursively on all contents. -Scalar types generally do not need to implement `isequal` -separate from `==`, unless they represent floating-point numbers -amenable to a more efficient implementation than that provided as a -generic fallback (based on `isnan`, `signbit`, and `==`). + Scalar types generally do not need to implement "isequal" + separate from "==", unless they represent floating-point numbers + amenable to a more efficient implementation than that provided as a + generic fallback (based on "isnan", "signbit", and "=="). +``` """ isequal doc""" - isless(x, y) +```rst +isless(x, y) -Test whether `x` is less than `y`, according to a canonical -total order. Values that are normally unordered, such as `NaN`, -are ordered in an arbitrary but consistent fashion. This is the -default comparison used by `sort`. Non-numeric types with a -canonical total order should implement this function. Numeric types -only need to implement it if they have special values such as + Test whether "x" is less than "y", according to a canonical + total order. Values that are normally unordered, such as "NaN", + are ordered in an arbitrary but consistent fashion. This is the + default comparison used by "sort". Non-numeric types with a + canonical total order should implement this function. Numeric types + only need to implement it if they have special values such as + "NaN". +``` """ isless doc""" - ifelse(condition::Bool, x, y) +```rst +ifelse(condition::Bool, x, y) -Return `x` if `condition` is true, otherwise return `y`. This -differs from `?` or `if` in that it is an ordinary function, so -all the arguments are evaluated first. In some cases, using -in generated code and provide higher performance in tight loops. + Return "x" if "condition" is true, otherwise return "y". This + differs from "?" or "if" in that it is an ordinary function, so + all the arguments are evaluated first. In some cases, using + "ifelse" instead of an "if" statement can eliminate the branch + in generated code and provide higher performance in tight loops. +``` """ ifelse doc""" - lexcmp(x, y) +```rst +lexcmp(x, y) -Compare `x` and `y` lexicographically and return -1, 0, or 1 -depending on whether `x` is less than, equal to, or greater than -lexicographically comparable types, and `lexless` will call + Compare "x" and "y" lexicographically and return -1, 0, or 1 + depending on whether "x" is less than, equal to, or greater than + "y", respectively. This function should be defined for + lexicographically comparable types, and "lexless" will call + "lexcmp" by default. +``` """ lexcmp doc""" - lexless(x, y) +```rst +lexless(x, y) -Determine whether `x` is lexicographically less than `y`. + Determine whether "x" is lexicographically less than "y". +``` """ lexless doc""" - typeof(x) +```rst +typeof(x) -Get the concrete type of `x`. + Get the concrete type of "x". +``` """ typeof doc""" - tuple(xs...) +```rst +tuple(xs...) -Construct a tuple of the given objects. + Construct a tuple of the given objects. +``` """ tuple doc""" - ntuple(f::Function, n) +```rst +ntuple(f::Function, n) -Create a tuple of length `n`, computing each element as `f(i)`, -where `i` is the index of the element. + Create a tuple of length "n", computing each element as "f(i)", + where "i" is the index of the element. +``` """ ntuple doc""" - object_id(x) +```rst +object_id(x) -Get a unique integer id for `x`. `object_id(x)==object_id(y)` -if and only if `is(x,y)`. + Get a unique integer id for "x". "object_id(x)==object_id(y)" + if and only if "is(x,y)". +``` """ object_id doc""" - hash(x[, h]) +```rst +hash(x[, h]) -Compute an integer hash code such that `isequal(x,y)` implies -code to be mixed with the result. -New types should implement the 2-argument form, typically by -calling the 2-argument `hash` method recursively in order to mix -hashes of the contents with each other (and with `h`). -Typically, any type that implements `hash` should also implement -its own `==` (hence `isequal`) to guarantee the property -mentioned above. + Compute an integer hash code such that "isequal(x,y)" implies + "hash(x)==hash(y)". The optional second argument "h" is a hash + code to be mixed with the result. + + New types should implement the 2-argument form, typically by + calling the 2-argument "hash" method recursively in order to mix + hashes of the contents with each other (and with "h"). + Typically, any type that implements "hash" should also implement + its own "==" (hence "isequal") to guarantee the property + mentioned above. +``` """ hash doc""" - finalizer(x, function) +```rst +finalizer(x, function) -Register a function `f(x)` to be called when there are no -program-accessible references to `x`. The behavior of this -function is unpredictable if `x` is of a bits type. + Register a function "f(x)" to be called when there are no + program-accessible references to "x". The behavior of this + function is unpredictable if "x" is of a bits type. +``` """ finalizer doc""" - finalize(x) +```rst +finalize(x) -Immediately run finalizers registered for object `x`. + Immediately run finalizers registered for object "x". +``` """ finalize doc""" - copy(x) +```rst +copy(x) -Create a shallow copy of `x`: the outer structure is copied, but -not all internal values. For example, copying an array produces a -new array with identically-same elements as the original. + Create a shallow copy of "x": the outer structure is copied, but + not all internal values. For example, copying an array produces a + new array with identically-same elements as the original. +``` """ copy doc""" - deepcopy(x) - -Create a deep copy of `x`: everything is copied recursively, -resulting in a fully independent object. For example, deep-copying -an array produces a new array whose elements are deep copies of the -original elements. Calling *deepcopy* on an object should generally -have the same effect as serializing and then deserializing it. -As a special case, functions can only be actually deep-copied if -they are anonymous, otherwise they are just copied. The difference -is only relevant in the case of closures, i.e. functions which may -contain hidden internal references. -While it isn't normally necessary, user-defined types can override -the default `deepcopy` behavior by defining a specialized version -of the function `deepcopy_internal(x::T, dict::ObjectIdDict)` -specialized for, and `dict` keeps track of objects copied so far -within the recursion. Within the definition, `deepcopy_internal` -should be used in place of `deepcopy`, and the `dict` variable -should be updated as appropriate before returning. +```rst +deepcopy(x) + + Create a deep copy of "x": everything is copied recursively, + resulting in a fully independent object. For example, deep-copying + an array produces a new array whose elements are deep copies of the + original elements. Calling *deepcopy* on an object should generally + have the same effect as serializing and then deserializing it. + + As a special case, functions can only be actually deep-copied if + they are anonymous, otherwise they are just copied. The difference + is only relevant in the case of closures, i.e. functions which may + contain hidden internal references. + + While it isn't normally necessary, user-defined types can override + the default "deepcopy" behavior by defining a specialized version + of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" + (which shouldn't otherwise be used), where "T" is the type to be + specialized for, and "dict" keeps track of objects copied so far + within the recursion. Within the definition, "deepcopy_internal" + should be used in place of "deepcopy", and the "dict" variable + should be updated as appropriate before returning. +``` """ deepcopy doc""" - isdefined([object], index | symbol) +```rst +isdefined([object], index | symbol) -Tests whether an assignable location is defined. The arguments can -be an array and index, a composite object and field name (as a -symbol), or a module and a symbol. With a single symbol argument, -tests whether a global variable with that name is defined in + Tests whether an assignable location is defined. The arguments can + be an array and index, a composite object and field name (as a + symbol), or a module and a symbol. With a single symbol argument, + tests whether a global variable with that name is defined in + "current_module()". +``` """ isdefined doc""" - convert(T, x) +```rst +convert(T, x) + + Convert "x" to a value of type "T". + + If "T" is an "Integer" type, an "InexactError" will be raised + if "x" is not representable by "T", for example if "x" is not + integer-valued, or is outside the range supported by "T". + + julia> convert(Int, 3.0) + 3 + + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 + + If "T" is a "FloatingPoint" or "Rational" type, then it will + return the closest value to "x" representable by "T". -Convert `x` to a value of type `T`. -If `T` is an `Integer` type, an `InexactError` will be raised -if `x` is not representable by `T`, for example if `x` is not -integer-valued, or is outside the range supported by `T`. -If `T` is a `FloatingPoint` or `Rational` type, then it will -return the closest value to `x` representable by `T`. + julia> x = 1/3 + 0.3333333333333333 + + julia> convert(Float32, x) + 0.33333334f0 + + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 +``` """ convert doc""" - promote(xs...) +```rst +promote(xs...) -Convert all arguments to their common promotion type (if any), and -return them all (as a tuple). + Convert all arguments to their common promotion type (if any), and + return them all (as a tuple). +``` """ promote doc""" - oftype(x, y) +```rst +oftype(x, y) -Convert `y` to the type of `x` (`convert(typeof(x), y)`). + Convert "y" to the type of "x" ("convert(typeof(x), y)"). +``` """ oftype doc""" - widen(type | x) +```rst +widen(type | x) + + If the argument is a type, return a "larger" type (for numeric + types, this will be a type with at least as much range and + precision as the argument, and usually more). Otherwise the + argument "x" is converted to "widen(typeof(x))". -If the argument is a type, return a `larger` type (for numeric -types, this will be a type with at least as much range and -precision as the argument, and usually more). Otherwise the -argument `x` is converted to `widen(typeof(x))`. + julia> widen(Int32) + Int64 + + julia> widen(1.5f0) + 1.5 +``` """ widen doc""" - identity(x) +```rst +identity(x) -The identity function. Returns its argument. + The identity function. Returns its argument. +``` """ identity doc""" - super(T::DataType) +```rst +super(T::DataType) -Return the supertype of DataType T + Return the supertype of DataType T +``` """ super doc""" - issubtype(type1, type2) +```rst +issubtype(type1, type2) -True if and only if all values of `type1` are also of `type2`. -Can also be written using the `<:` infix operator as `type1 <: -type2`. + True if and only if all values of "type1" are also of "type2". + Can also be written using the "<:" infix operator as "type1 <: + type2". +``` """ issubtype doc""" - <:(T1, T2) +```rst +<:(T1, T2) -Subtype operator, equivalent to `issubtype(T1,T2)`. + Subtype operator, equivalent to "issubtype(T1,T2)". +``` """ Base.(:(<:)) doc""" - subtypes(T::DataType) +```rst +subtypes(T::DataType) -Return a list of immediate subtypes of DataType T. Note that all -currently loaded subtypes are included, including those not visible -in the current module. + Return a list of immediate subtypes of DataType T. Note that all + currently loaded subtypes are included, including those not visible + in the current module. +``` """ subtypes doc""" - typemin(type) +```rst +typemin(type) -The lowest value representable by the given (real) numeric type. + The lowest value representable by the given (real) numeric type. +``` """ typemin doc""" - typemax(type) +```rst +typemax(type) -The highest value representable by the given (real) numeric type. + The highest value representable by the given (real) numeric type. +``` """ typemax doc""" - realmin(type) +```rst +realmin(type) -The smallest in absolute value non-subnormal value representable by -the given floating-point type + The smallest in absolute value non-subnormal value representable by + the given floating-point type +``` """ realmin doc""" - realmax(type) +```rst +realmax(type) -The highest finite value representable by the given floating-point -type + The highest finite value representable by the given floating-point + type +``` """ realmax doc""" - maxintfloat(type) +```rst +maxintfloat(type) -The largest integer losslessly representable by the given floating- -point type + The largest integer losslessly representable by the given floating- + point type +``` """ maxintfloat doc""" - sizeof(type) +```rst +sizeof(type) -Size, in bytes, of the canonical binary representation of the given -type, if any. + Size, in bytes, of the canonical binary representation of the given + type, if any. +``` """ sizeof doc""" - eps([type]) +```rst +eps([type]) -The distance between 1.0 and the next larger representable -floating-point value of `type`. Only floating-point types are -sensible arguments. If `type` is omitted, then `eps(Float64)` -is returned. + The distance between 1.0 and the next larger representable + floating-point value of "type". Only floating-point types are + sensible arguments. If "type" is omitted, then "eps(Float64)" + is returned. +``` """ eps doc""" - eps(x) +```rst +eps(x) -The distance between `x` and the next larger representable -floating-point value of the same type as `x`. + The distance between "x" and the next larger representable + floating-point value of the same type as "x". +``` """ eps doc""" - promote_type(type1, type2) +```rst +promote_type(type1, type2) -Determine a type big enough to hold values of each argument type -without loss, whenever possible. In some cases, where no type -exists to which both types can be promoted losslessly, some loss is -tolerated; for example, `promote_type(Int64,Float64)` returns -represented exactly as `Float64` values. + Determine a type big enough to hold values of each argument type + without loss, whenever possible. In some cases, where no type + exists to which both types can be promoted losslessly, some loss is + tolerated; for example, "promote_type(Int64,Float64)" returns + "Float64" even though strictly, not all "Int64" values can be + represented exactly as "Float64" values. +``` """ promote_type doc""" - promote_rule(type1, type2) +```rst +promote_rule(type1, type2) -Specifies what type should be used by `promote` when given values -of types `type1` and `type2`. This function should not be -called directly, but should have definitions added to it for new -types as appropriate. + Specifies what type should be used by "promote" when given values + of types "type1" and "type2". This function should not be + called directly, but should have definitions added to it for new + types as appropriate. +``` """ promote_rule doc""" - getfield(value, name::Symbol) +```rst +getfield(value, name::Symbol) -Extract a named field from a value of composite type. The syntax + Extract a named field from a value of composite type. The syntax + "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls + "getfield(a, b)". +``` """ getfield doc""" - setfield!(value, name::Symbol, x) +```rst +setfield!(value, name::Symbol, x) -Assign `x` to a named field in `value` of composite type. The -syntax `a.b = c` calls `setfield!(a, :b, c)`, and the syntax + Assign "x" to a named field in "value" of composite type. The + syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax + "a.(b) = c" calls "setfield!(a, b, c)". +``` """ setfield! doc""" - fieldoffsets(type) +```rst +fieldoffsets(type) + + The byte offset of each field of a type relative to the data start. + For example, we could use it in the following manner to summarize + information about a struct type: + + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; -The byte offset of each field of a type relative to the data start. -For example, we could use it in the following manner to summarize -information about a struct type: + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) +``` """ fieldoffsets doc""" - fieldtype(type, name::Symbol | index::Int) +```rst +fieldtype(type, name::Symbol | index::Int) -Determine the declared type of a field (specified by name or index) -in a composite type. + Determine the declared type of a field (specified by name or index) + in a composite type. +``` """ fieldtype doc""" - isimmutable(v) +```rst +isimmutable(v) -True if value `v` is immutable. See *Immutable Composite Types* -for a discussion of immutability. Note that this function works on -values, so if you give it a type, it will tell you that a value of + True if value "v" is immutable. See *Immutable Composite Types* + for a discussion of immutability. Note that this function works on + values, so if you give it a type, it will tell you that a value of + "DataType" is mutable. +``` """ isimmutable doc""" - isbits(T) +```rst +isbits(T) -True if `T` is a `plain data` type, meaning it is immutable and -contains no references to other values. Typical examples are -numeric types such as `UInt8`, `Float64`, and + True if "T" is a "plain data" type, meaning it is immutable and + contains no references to other values. Typical examples are + numeric types such as "UInt8", "Float64", and + "Complex{Float64}". + + julia> isbits(Complex{Float64}) + true + + julia> isbits(Complex) + false +``` """ isbits doc""" - isleaftype(T) +```rst +isleaftype(T) -Determine whether `T` is a concrete type that can have instances, -meaning its only subtypes are itself and `None` (but `T` itself -is not `None`). + Determine whether "T" is a concrete type that can have instances, + meaning its only subtypes are itself and "None" (but "T" itself + is not "None"). +``` """ isleaftype doc""" - typejoin(T, S) +```rst +typejoin(T, S) -Compute a type that contains both `T` and `S`. + Compute a type that contains both "T" and "S". +``` """ typejoin doc""" - typeintersect(T, S) +```rst +typeintersect(T, S) -Compute a type that contains the intersection of `T` and `S`. -Usually this will be the smallest such type or one close to it. + Compute a type that contains the intersection of "T" and "S". + Usually this will be the smallest such type or one close to it. +``` """ typeintersect doc""" - instances(T::Type) +```rst +instances(T::Type) -Return a collection of all instances of the given type, if -applicable. Mostly used for enumerated types (see `@enum`). + Return a collection of all instances of the given type, if + applicable. Mostly used for enumerated types (see "@enum"). +``` """ instances doc""" - method_exists(f, Tuple type) -> Bool +```rst +method_exists(f, Tuple type) -> Bool + + Determine whether the given generic function has a method matching + the given "Tuple" of argument types. -Determine whether the given generic function has a method matching -the given `Tuple` of argument types. + julia> method_exists(length, Tuple{Array}) + true +``` """ method_exists doc""" - applicable(f, args...) -> Bool +```rst +applicable(f, args...) -> Bool + + Determine whether the given generic function has a method + applicable to the given arguments. + + julia> function f(x, y) + x + y + end; + + julia> applicable(f, 1) + false -Determine whether the given generic function has a method -applicable to the given arguments. + julia> applicable(f, 1, 2) + true +``` """ applicable doc""" - invoke(f, (types...), args...) +```rst +invoke(f, (types...), args...) -Invoke a method for the given generic function matching the -specified types (as a tuple), on the specified arguments. The -arguments must be compatible with the specified types. This allows -invoking a method other than the most specific matching method, -which is useful when the behavior of a more general definition is -explicitly needed (often as part of the implementation of a more -specific method of the same function). + Invoke a method for the given generic function matching the + specified types (as a tuple), on the specified arguments. The + arguments must be compatible with the specified types. This allows + invoking a method other than the most specific matching method, + which is useful when the behavior of a more general definition is + explicitly needed (often as part of the implementation of a more + specific method of the same function). +``` """ invoke doc""" - |>(x, f) +```rst +|>(x, f) -Applies a function to the preceding argument. This allows for easy -function chaining. + Applies a function to the preceding argument. This allows for easy + function chaining. + + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 +``` """ Base.(:(|>)) doc""" - call(x, args...) +```rst +call(x, args...) -If `x` is not a `Function`, then `x(args...)` is equivalent -to `call(x, args...)`. This means that function-like behavior -can be added to any type by defining new `call` methods. + If "x" is not a "Function", then "x(args...)" is equivalent + to "call(x, args...)". This means that function-like behavior + can be added to any type by defining new "call" methods. +``` """ call doc""" - eval([m::Module], expr::Expr) +```rst +eval([m::Module], expr::Expr) -Evaluate an expression in the given module and return the result. -Every module (except those defined with `baremodule`) has its own -1-argument definition of `eval`, which evaluates expressions in -that module. + Evaluate an expression in the given module and return the result. + Every module (except those defined with "baremodule") has its own + 1-argument definition of "eval", which evaluates expressions in + that module. +``` """ eval doc""" - @eval() +```rst +@eval() -Evaluate an expression and return the value. + Evaluate an expression and return the value. +``` """ @eval doc""" - evalfile(path::AbstractString) +```rst +evalfile(path::AbstractString) -Load the file using `include`, evaluate all expressions, and -return the value of the last one. + Load the file using "include", evaluate all expressions, and + return the value of the last one. +``` """ evalfile doc""" - esc(e::ANY) +```rst +esc(e::ANY) -Only valid in the context of an Expr returned from a macro. -Prevents the macro hygiene pass from turning embedded variables -into gensym variables. See the *Macros* section of the -Metaprogramming chapter of the manual for more details and -examples. + Only valid in the context of an Expr returned from a macro. + Prevents the macro hygiene pass from turning embedded variables + into gensym variables. See the *Macros* section of the + Metaprogramming chapter of the manual for more details and + examples. +``` """ esc doc""" - gensym([tag]) +```rst +gensym([tag]) -Generates a symbol which will not conflict with other variable -names. + Generates a symbol which will not conflict with other variable + names. +``` """ gensym doc""" - @gensym() +```rst +@gensym() -Generates a gensym symbol for a variable. For example, `@gensym x -y` is transformed into `x = gensym(`x`); y = gensym(`y`)`. + Generates a gensym symbol for a variable. For example, "@gensym x + y" is transformed into "x = gensym("x"); y = gensym("y")". +``` """ @gensym doc""" - parse(str, start; greedy=true, raise=true) +```rst +parse(str, start; greedy=true, raise=true) -Parse the expression string and return an expression (which could -later be passed to eval for execution). Start is the index of the -first character to start parsing. If `greedy` is true (default), -it will stop as soon as it has parsed a valid expression. -Incomplete but otherwise syntactically valid expressions will -return `Expr(:incomplete, `(error message)`)`. If `raise` is -true (default), syntax errors other than incomplete expressions -will raise an error. If `raise` is false, `parse` will return -an expression that will raise an error upon evaluation. + Parse the expression string and return an expression (which could + later be passed to eval for execution). Start is the index of the + first character to start parsing. If "greedy" is true (default), + "parse" will try to consume as much input as it can; otherwise, + it will stop as soon as it has parsed a valid expression. + Incomplete but otherwise syntactically valid expressions will + return "Expr(:incomplete, "(error message)")". If "raise" is + true (default), syntax errors other than incomplete expressions + will raise an error. If "raise" is false, "parse" will return + an expression that will raise an error upon evaluation. +``` """ parse doc""" - parse(str; raise=true) +```rst +parse(str; raise=true) -Parse the whole string greedily, returning a single expression. An -error is thrown if there are additional characters after the first -expression. If `raise` is true (default), syntax errors will -raise an error; otherwise, `parse` will return an expression that -will raise an error upon evaluation. + Parse the whole string greedily, returning a single expression. An + error is thrown if there are additional characters after the first + expression. If "raise" is true (default), syntax errors will + raise an error; otherwise, "parse" will return an expression that + will raise an error upon evaluation. +``` """ parse doc""" - Nullable(x) +```rst +Nullable(x) -Wrap value `x` in an object of type `Nullable`, which indicates -whether a value is present. `Nullable(x)` yields a non-empty -wrapper, and `Nullable{T}()` yields an empty instance of a -wrapper that might contain a value of type `T`. + Wrap value "x" in an object of type "Nullable", which indicates + whether a value is present. "Nullable(x)" yields a non-empty + wrapper, and "Nullable{T}()" yields an empty instance of a + wrapper that might contain a value of type "T". +``` """ Nullable doc""" - get(x) +```rst +get(x) -Attempt to access the value of the `Nullable` object, `x`. -Returns the value if it is present; otherwise, throws a + Attempt to access the value of the "Nullable" object, "x". + Returns the value if it is present; otherwise, throws a + "NullException". +``` """ get doc""" - get(x, y) +```rst +get(x, y) -Attempt to access the value of the `Nullable{T}` object, `x`. -Returns the value if it is present; otherwise, returns `convert(T, -y)`. + Attempt to access the value of the "Nullable{T}" object, "x". + Returns the value if it is present; otherwise, returns "convert(T, + y)". +``` """ get doc""" - isnull(x) +```rst +isnull(x) -Is the `Nullable` object `x` null, i.e. missing a value? + Is the "Nullable" object "x" null, i.e. missing a value? +``` """ isnull doc""" - run(command) +```rst +run(command) -Run a command object, constructed with backticks. Throws an error -if anything goes wrong, including the process exiting with a non- -zero status. + Run a command object, constructed with backticks. Throws an error + if anything goes wrong, including the process exiting with a non- + zero status. +``` """ run doc""" - spawn(command) +```rst +spawn(command) -Run a command object asynchronously, returning the resulting + Run a command object asynchronously, returning the resulting + "Process" object. +``` """ spawn doc""" - DevNull +```rst +DevNull -Used in a stream redirect to discard all data written to it. -Essentially equivalent to /dev/null on Unix or NUL on Windows. -Usage: `run(`cat test.txt` |> DevNull)` + Used in a stream redirect to discard all data written to it. + Essentially equivalent to /dev/null on Unix or NUL on Windows. + Usage: "run(`cat test.txt` |> DevNull)" +``` """ DevNull doc""" - success(command) +```rst +success(command) -Run a command object, constructed with backticks, and tell whether -it was successful (exited with a code of 0). An exception is raised -if the process cannot be started. + Run a command object, constructed with backticks, and tell whether + it was successful (exited with a code of 0). An exception is raised + if the process cannot be started. +``` """ success doc""" - process_running(p::Process) +```rst +process_running(p::Process) -Determine whether a process is currently running. + Determine whether a process is currently running. +``` """ process_running doc""" - process_exited(p::Process) +```rst +process_exited(p::Process) -Determine whether a process has exited. + Determine whether a process has exited. +``` """ process_exited doc""" - kill(p::Process, signum=SIGTERM) +```rst +kill(p::Process, signum=SIGTERM) -Send a signal to a process. The default is to terminate the -process. + Send a signal to a process. The default is to terminate the + process. +``` """ kill doc""" - open(command, mode::AbstractString="r", stdio=DevNull) +```rst +open(command, mode::AbstractString="r", stdio=DevNull) -Start running `command` asynchronously, and return a tuple -reads from the process's standard output and `stdio` optionally -specifies the process's standard input stream. If `mode` is -and `stdio` optionally specifies the process's standard output -stream. + Start running "command" asynchronously, and return a tuple + "(stream,process)". If "mode" is ""r"", then "stream" + reads from the process's standard output and "stdio" optionally + specifies the process's standard input stream. If "mode" is + ""w"", then "stream" writes to the process's standard input + and "stdio" optionally specifies the process's standard output + stream. +``` """ open doc""" - open(f::Function, command, mode::AbstractString="r", stdio=DevNull) +```rst +open(f::Function, command, mode::AbstractString="r", stdio=DevNull) -Similar to `open(command, mode, stdio)`, but calls `f(stream)` -on the resulting read or write stream, then closes the stream and -waits for the process to complete. Returns the value returned by + Similar to "open(command, mode, stdio)", but calls "f(stream)" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + "f". +``` """ open doc""" - Sys.set_process_title(title::AbstractString) +```rst +Sys.set_process_title(title::AbstractString) -Set the process title. No-op on some operating systems. (not -exported) + Set the process title. No-op on some operating systems. (not + exported) +``` """ Sys doc""" - Sys.get_process_title() +```rst +Sys.get_process_title() -Get the process title. On some systems, will always return empty -string. (not exported) + Get the process title. On some systems, will always return empty + string. (not exported) +``` """ Sys doc""" - readandwrite(command) +```rst +readandwrite(command) -Starts running a command asynchronously, and returns a tuple -process, and the process object itself. + Starts running a command asynchronously, and returns a tuple + (stdout,stdin,process) of the output stream and input stream of the + process, and the process object itself. +``` """ readandwrite doc""" - ignorestatus(command) +```rst +ignorestatus(command) -Mark a command object so that running it will not throw an error if -the result code is non-zero. + Mark a command object so that running it will not throw an error if + the result code is non-zero. +``` """ ignorestatus doc""" - detach(command) +```rst +detach(command) -Mark a command object so that it will be run in a new process -group, allowing it to outlive the julia process, and not have -Ctrl-C interrupts passed to it. + Mark a command object so that it will be run in a new process + group, allowing it to outlive the julia process, and not have + Ctrl-C interrupts passed to it. +``` """ detach doc""" - setenv(command, env; dir=working_dir) +```rst +setenv(command, env; dir=working_dir) + + Set environment variables to use when running the given command. + "env" is either a dictionary mapping strings to strings, an array + of strings of the form ""var=val"", or zero or more + ""var"=>val" pair arguments. In order to modify (rather than + replace) the existing environment, create "env" by "copy(ENV)" + and then setting "env["var"]=val" as desired, or use + "withenv". -Set environment variables to use when running the given command. -of strings of the form `var=val`, or zero or more -replace) the existing environment, create `env` by `copy(ENV)` -and then setting `env[`var`]=val` as desired, or use -The `dir` keyword argument can be used to specify a working -directory for the command. + The "dir" keyword argument can be used to specify a working + directory for the command. +``` """ setenv doc""" - withenv(f::Function, kv::Pair...) +```rst +withenv(f::Function, kv::Pair...) -Execute `f()` in an environment that is temporarily modified (not -replaced as in `setenv`) by zero or more `var`=>val` -arguments `kv`. `withenv` is generally used via the -be used to temporarily unset an environment variable (if it is -set). When `withenv` returns, the original environment has been -restored. + Execute "f()" in an environment that is temporarily modified (not + replaced as in "setenv") by zero or more ""var"=>val" + arguments "kv". "withenv" is generally used via the + "withenv(kv...) do ... end" syntax. A value of "nothing" can + be used to temporarily unset an environment variable (if it is + set). When "withenv" returns, the original environment has been + restored. +``` """ withenv doc""" - pipe(from, to, ...) +```rst +pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source + and destination can be commands, I/O streams, strings, or results + of other "pipe" calls. At least one argument must be a command. + Strings refer to filenames. When called with more than two + arguments, they are chained together from left to right. For + example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". + This provides a more concise way to specify multi-stage pipelines. + + **Examples**: + * "run(pipe(`ls`, `grep xyz`))" + + * "run(pipe(`ls`, "out.txt"))" -Create a pipeline from a data source to a destination. The source -and destination can be commands, I/O streams, strings, or results -of other `pipe` calls. At least one argument must be a command. -Strings refer to filenames. When called with more than two -arguments, they are chained together from left to right. For -example `pipe(a,b,c)` is equivalent to `pipe(pipe(a,b),c)`. -This provides a more concise way to specify multi-stage pipelines. + * "run(pipe("out.txt", `grep xyz`))" +``` """ pipe doc""" - pipe(command; stdin, stdout, stderr, append=false) +```rst +pipe(command; stdin, stdout, stderr, append=false) -Redirect I/O to or from the given `command`. Keyword arguments -specify which of the command's streams should be redirected. -is a more general version of the 2-argument `pipe` function. + Redirect I/O to or from the given "command". Keyword arguments + specify which of the command's streams should be redirected. + "append" controls whether file output appends to the file. This + is a more general version of the 2-argument "pipe" function. + "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when + "from" is a command, and to "pipe(to, stdin=from)" when + "from" is another kind of data source. + + **Examples**: + * "run(pipe(`dothings`, stdout="out.txt", + stderr="errs.txt"))" + + * "run(pipe(`update`, stdout="log.txt", append=true))" +``` """ pipe doc""" - gethostname() -> AbstractString +```rst +gethostname() -> AbstractString -Get the local machine's host name. + Get the local machine's host name. +``` """ gethostname doc""" - getipaddr() -> AbstractString +```rst +getipaddr() -> AbstractString -Get the IP address of the local machine, as a string of the form + Get the IP address of the local machine, as a string of the form + "x.x.x.x". +``` """ getipaddr doc""" - getpid() -> Int32 +```rst +getpid() -> Int32 -Get julia's process ID. + Get julia's process ID. +``` """ getpid doc""" - time() +```rst +time() -Get the system time in seconds since the epoch, with fairly high + Get the system time in seconds since the epoch, with fairly high + (typically, microsecond) resolution. +``` """ time doc""" - time_ns() +```rst +time_ns() -Get the time in nanoseconds. The time corresponding to 0 is -undefined, and wraps every 5.8 years. + Get the time in nanoseconds. The time corresponding to 0 is + undefined, and wraps every 5.8 years. +``` """ time_ns doc""" - tic() +```rst +tic() -Set a timer to be read by the next call to `toc()` or `toq()`. -The macro call `@time expr` can also be used to time evaluation. + Set a timer to be read by the next call to "toc()" or "toq()". + The macro call "@time expr" can also be used to time evaluation. +``` """ tic doc""" - toc() +```rst +toc() -Print and return the time elapsed since the last `tic()`. + Print and return the time elapsed since the last "tic()". +``` """ toc doc""" - toq() +```rst +toq() -Return, but do not print, the time elapsed since the last + Return, but do not print, the time elapsed since the last + "tic()". +``` """ toq doc""" - @time() +```rst +@time() -A macro to execute an expression, printing the time it took to -execute, the number of allocations, and the total number of bytes -its execution caused to be allocated, before returning the value of -the expression. + A macro to execute an expression, printing the time it took to + execute, the number of allocations, and the total number of bytes + its execution caused to be allocated, before returning the value of + the expression. +``` """ @time doc""" - @timev() +```rst +@timev() -This is a verbose version of the `@time` macro, it first prints -the same information as `@time`, then any non-zero memory -allocation counters, and then returns the value of the expression. + This is a verbose version of the "@time" macro, it first prints + the same information as "@time", then any non-zero memory + allocation counters, and then returns the value of the expression. +``` """ @timev doc""" - @timed() +```rst +@timed() -A macro to execute an expression, and return the value of the -expression, elapsed time, total bytes allocated, garbage collection -time, and an object with various memory allocation counters. + A macro to execute an expression, and return the value of the + expression, elapsed time, total bytes allocated, garbage collection + time, and an object with various memory allocation counters. +``` """ @timed doc""" - @elapsed() +```rst +@elapsed() -A macro to evaluate an expression, discarding the resulting value, -instead returning the number of seconds it took to execute as a -floating-point number. + A macro to evaluate an expression, discarding the resulting value, + instead returning the number of seconds it took to execute as a + floating-point number. +``` """ @elapsed doc""" - @allocated() +```rst +@allocated() -A macro to evaluate an expression, discarding the resulting value, -instead returning the total number of bytes allocated during -evaluation of the expression. Note: the expression is evaluated -inside a local function, instead of the current context, in order -to eliminate the effects of compilation, however, there still may -be some allocations due to JIT compilation. This also makes the -results inconsistent with the `@time` macros, which do not try to -adjust for the effects of compilation. + A macro to evaluate an expression, discarding the resulting value, + instead returning the total number of bytes allocated during + evaluation of the expression. Note: the expression is evaluated + inside a local function, instead of the current context, in order + to eliminate the effects of compilation, however, there still may + be some allocations due to JIT compilation. This also makes the + results inconsistent with the "@time" macros, which do not try to + adjust for the effects of compilation. +``` """ @allocated doc""" - EnvHash() -> EnvHash +```rst +EnvHash() -> EnvHash -A singleton of this type provides a hash table interface to -environment variables. + A singleton of this type provides a hash table interface to + environment variables. +``` """ EnvHash doc""" - ENV +```rst +ENV -Reference to the singleton `EnvHash`, providing a dictionary -interface to system environment variables. + Reference to the singleton "EnvHash", providing a dictionary + interface to system environment variables. +``` """ ENV doc""" - @unix() +```rst +@unix() -Given `@unix? a : b`, do `a` on Unix systems (including Linux -and OS X) and `b` elsewhere. See documentation for Handling -Platform Variations in the Calling C and Fortran Code section of -the manual. + Given "@unix? a : b", do "a" on Unix systems (including Linux + and OS X) and "b" elsewhere. See documentation for Handling + Platform Variations in the Calling C and Fortran Code section of + the manual. +``` """ @unix doc""" - @osx() +```rst +@osx() -Given `@osx? a : b`, do `a` on OS X and `b` elsewhere. See -documentation for Handling Platform Variations in the Calling C and -Fortran Code section of the manual. + Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. +``` """ @osx doc""" - @linux() +```rst +@linux() -Given `@linux? a : b`, do `a` on Linux and `b` elsewhere. See -documentation for Handling Platform Variations in the Calling C and -Fortran Code section of the manual. + Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. +``` """ @linux doc""" - @windows() +```rst +@windows() -Given `@windows? a : b`, do `a` on Windows and `b` elsewhere. -See documentation for Handling Platform Variations in the Calling C -and Fortran Code section of the manual. + Given "@windows? a : b", do "a" on Windows and "b" elsewhere. + See documentation for Handling Platform Variations in the Calling C + and Fortran Code section of the manual. +``` """ @windows doc""" - error(message::AbstractString) +```rst +error(message::AbstractString) -Raise an `ErrorException` with the given message + Raise an "ErrorException" with the given message +``` """ error doc""" - throw(e) +```rst +throw(e) -Throw an object as an exception + Throw an object as an exception +``` """ throw doc""" - rethrow([e]) +```rst +rethrow([e]) -Throw an object without changing the current exception backtrace. -The default argument is the current exception (if called within a + Throw an object without changing the current exception backtrace. + The default argument is the current exception (if called within a + "catch" block). +``` """ rethrow doc""" - backtrace() +```rst +backtrace() -Get a backtrace object for the current program point. + Get a backtrace object for the current program point. +``` """ backtrace doc""" - catch_backtrace() +```rst +catch_backtrace() -Get the backtrace of the current exception, for use within + Get the backtrace of the current exception, for use within + "catch" blocks. +``` """ catch_backtrace doc""" - assert(cond) +```rst +assert(cond) -Throw an `AssertionError` if `cond` is false. Also available as -the macro `@assert expr`. + Throw an "AssertionError" if "cond" is false. Also available as + the macro "@assert expr". +``` """ assert doc""" - ArgumentError(msg) +```rst +ArgumentError(msg) -The parameters to a function call do not match a valid signature. + The parameters to a function call do not match a valid signature. +``` """ ArgumentError doc""" - AssertionError([msg]) +```rst +AssertionError([msg]) -The asserted condition did not evalutate to `true`. + The asserted condition did not evalutate to "true". +``` """ AssertionError doc""" - BoundsError([a][, i]) +```rst +BoundsError([a][, i]) -An indexing operation into an array, `a`, tried to access an out- -of-bounds element, `i`. + An indexing operation into an array, "a", tried to access an out- + of-bounds element, "i". +``` """ BoundsError doc""" - DimensionMismatch([msg]) +```rst +DimensionMismatch([msg]) -The objects called do not have matching dimensionality. + The objects called do not have matching dimensionality. +``` """ DimensionMismatch doc""" - DivideError() +```rst +DivideError() -Integer division was attempted with a denominator value of 0. + Integer division was attempted with a denominator value of 0. +``` """ DivideError doc""" - DomainError() +```rst +DomainError() -The arguments to a function or constructor are outside the valid -domain. + The arguments to a function or constructor are outside the valid + domain. +``` """ DomainError doc""" - EOFError() +```rst +EOFError() -No more data was available to read from a file or stream. + No more data was available to read from a file or stream. +``` """ EOFError doc""" - ErrorException(msg) +```rst +ErrorException(msg) -Generic error type. The error message, in the *.msg* field, may -provide more specific details. + Generic error type. The error message, in the *.msg* field, may + provide more specific details. +``` """ ErrorException doc""" - InexactError() +```rst +InexactError() -Type conversion cannot be done exactly. + Type conversion cannot be done exactly. +``` """ InexactError doc""" - InterruptException() +```rst +InterruptException() -The process was stopped by a terminal interrupt (CTRL+C). + The process was stopped by a terminal interrupt (CTRL+C). +``` """ InterruptException doc""" - KeyError(key) +```rst +KeyError(key) -An indexing operation into an `Associative` (`Dict`) or `Set` -like object tried to access or delete a non-existent element. + An indexing operation into an "Associative" ("Dict") or "Set" + like object tried to access or delete a non-existent element. +``` """ KeyError doc""" - LoadError(file::AbstractString, line::Int, error) +```rst +LoadError(file::AbstractString, line::Int, error) -An error occurred while *including*, *requiring*, or *using* a -file. The error specifics should be available in the *.error* -field. + An error occurred while *including*, *requiring*, or *using* a + file. The error specifics should be available in the *.error* + field. +``` """ LoadError doc""" - MethodError(f, args) +```rst +MethodError(f, args) -A method with the required type signature does not exist in the -given generic function. + A method with the required type signature does not exist in the + given generic function. +``` """ MethodError doc""" - NullException() +```rst +NullException() -An attempted access to a `Nullable` with no defined value. + An attempted access to a "Nullable" with no defined value. +``` """ NullException doc""" - OutOfMemoryError() +```rst +OutOfMemoryError() -An operation allocated too much memory for either the system or the -garbage collector to handle properly. + An operation allocated too much memory for either the system or the + garbage collector to handle properly. +``` """ OutOfMemoryError doc""" - ReadOnlyMemoryError() +```rst +ReadOnlyMemoryError() -An operation tried to write to memory that is read-only. + An operation tried to write to memory that is read-only. +``` """ ReadOnlyMemoryError doc""" - OverflowError() +```rst +OverflowError() -The result of an expression is too large for the specified type and -will cause a wraparound. + The result of an expression is too large for the specified type and + will cause a wraparound. +``` """ OverflowError doc""" - ParseError(msg) +```rst +ParseError(msg) -The expression passed to the *parse* function could not be -interpreted as a valid Julia expression. + The expression passed to the *parse* function could not be + interpreted as a valid Julia expression. +``` """ ParseError doc""" - ProcessExitedException() +```rst +ProcessExitedException() -After a client Julia process has exited, further attempts to -reference the dead child will throw this exception. + After a client Julia process has exited, further attempts to + reference the dead child will throw this exception. +``` """ ProcessExitedException doc""" - StackOverflowError() +```rst +StackOverflowError() -The function call grew beyond the size of the call stack. This -usually happens when a call recurses infinitely. + The function call grew beyond the size of the call stack. This + usually happens when a call recurses infinitely. +``` """ StackOverflowError doc""" - SystemError(prefix::AbstractString[, errnum::Int32]) +```rst +SystemError(prefix::AbstractString[, errnum::Int32]) -A system call failed with an error code (in the `errno` global -variable). + A system call failed with an error code (in the "errno" global + variable). +``` """ SystemError doc""" - TypeError(func::Symbol, context::AbstractString, expected::Type, got) +```rst +TypeError(func::Symbol, context::AbstractString, expected::Type, got) -A type assertion failure, or calling an intrinsic function with an -incorrect argument type. + A type assertion failure, or calling an intrinsic function with an + incorrect argument type. +``` """ TypeError doc""" - UndefRefError() +```rst +UndefRefError() -The item or field is not defined for the given object. + The item or field is not defined for the given object. +``` """ UndefRefError doc""" - UndefVarError(var::Symbol) +```rst +UndefVarError(var::Symbol) -A symbol in the current scope is not defined. + A symbol in the current scope is not defined. +``` """ UndefVarError doc""" - Timer(callback::Function, delay, repeat=0) +```rst +Timer(callback::Function, delay, repeat=0) -Create a timer to call the given callback function. The callback is -passed one argument, the timer object itself. The callback will be -invoked after the specified initial delay, and then repeating with -the given `repeat` interval. If `repeat` is `0`, the timer is -only triggered once. Times are in seconds. A timer is stopped and -has its resources freed by calling `close` on it. + Create a timer to call the given callback function. The callback is + passed one argument, the timer object itself. The callback will be + invoked after the specified initial delay, and then repeating with + the given "repeat" interval. If "repeat" is "0", the timer is + only triggered once. Times are in seconds. A timer is stopped and + has its resources freed by calling "close" on it. +``` """ Timer doc""" - Timer(delay, repeat=0) +```rst +Timer(delay, repeat=0) -Create a timer that wakes up tasks waiting for it (by calling - `wait` on the timer object) at a specified interval. + Create a timer that wakes up tasks waiting for it (by calling + "wait" on the timer object) at a specified interval. +``` """ Timer doc""" - module_name(m::Module) -> Symbol +```rst +module_name(m::Module) -> Symbol -Get the name of a module as a symbol. + Get the name of a module as a symbol. +``` """ module_name doc""" - module_parent(m::Module) -> Module +```rst +module_parent(m::Module) -> Module -Get a module's enclosing module. `Main` is its own parent. + Get a module's enclosing module. "Main" is its own parent. +``` """ module_parent doc""" - current_module() -> Module +```rst +current_module() -> Module -Get the *dynamically* current module, which is the module code is -currently being read from. In general, this is not the same as the -module containing the call to this function. + Get the *dynamically* current module, which is the module code is + currently being read from. In general, this is not the same as the + module containing the call to this function. +``` """ current_module doc""" - fullname(m::Module) +```rst +fullname(m::Module) -Get the fully-qualified name of a module as a tuple of symbols. For -example, `fullname(Base.Pkg)` gives `(:Base,:Pkg)`, and + Get the fully-qualified name of a module as a tuple of symbols. For + example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and + "fullname(Main)" gives "()". +``` """ fullname doc""" - names(x::Module[, all=false[, imported=false]]) +```rst +names(x::Module[, all=false[, imported=false]]) -Get an array of the names exported by a module, with optionally -more module globals according to the additional parameters. + Get an array of the names exported by a module, with optionally + more module globals according to the additional parameters. +``` """ names doc""" - nfields(x::DataType) -> Int +```rst +nfields(x::DataType) -> Int -Get the number of fields of a data type. + Get the number of fields of a data type. +``` """ nfields doc""" - fieldnames(x::DataType) +```rst +fieldnames(x::DataType) -Get an array of the fields of a data type. + Get an array of the fields of a data type. +``` """ fieldnames doc""" - isconst([m::Module], s::Symbol) -> Bool +```rst +isconst([m::Module], s::Symbol) -> Bool -Determine whether a global is declared `const` in a given module. -The default module argument is `current_module()`. + Determine whether a global is declared "const" in a given module. + The default module argument is "current_module()". +``` """ isconst doc""" - isgeneric(f::Function) -> Bool +```rst +isgeneric(f::Function) -> Bool -Determine whether a function is generic. + Determine whether a function is generic. +``` """ isgeneric doc""" - function_name(f::Function) -> Symbol +```rst +function_name(f::Function) -> Symbol -Get the name of a generic function as a symbol, or `:anonymous`. + Get the name of a generic function as a symbol, or ":anonymous". +``` """ function_name doc""" - function_module(f::Function, types) -> Module +```rst +function_module(f::Function, types) -> Module -Determine the module containing a given definition of a generic -function. + Determine the module containing a given definition of a generic + function. +``` """ function_module doc""" - functionloc(f::Function, types) +```rst +functionloc(f::Function, types) -Returns a tuple `(filename,line)` giving the location of a method -definition. + Returns a tuple "(filename,line)" giving the location of a method + definition. +``` """ functionloc doc""" - functionloc(m::Method) +```rst +functionloc(m::Method) -Returns a tuple `(filename,line)` giving the location of a method -definition. + Returns a tuple "(filename,line)" giving the location of a method + definition. +``` """ functionloc doc""" - gc() +```rst +gc() -Perform garbage collection. This should not generally be used. + Perform garbage collection. This should not generally be used. +``` """ gc doc""" - gc_enable(on::Bool) +```rst +gc_enable(on::Bool) -Control whether garbage collection is enabled using a boolean -argument (true for enabled, false for disabled). Returns previous -GC state. Disabling garbage collection should be used only with -extreme caution, as it can cause memory use to grow without bound. + Control whether garbage collection is enabled using a boolean + argument (true for enabled, false for disabled). Returns previous + GC state. Disabling garbage collection should be used only with + extreme caution, as it can cause memory use to grow without bound. +``` """ gc_enable doc""" - macroexpand(x) +```rst +macroexpand(x) -Takes the expression x and returns an equivalent expression with -all macros removed (expanded). + Takes the expression x and returns an equivalent expression with + all macros removed (expanded). +``` """ macroexpand doc""" - expand(x) +```rst +expand(x) -Takes the expression x and returns an equivalent expression in -lowered form + Takes the expression x and returns an equivalent expression in + lowered form +``` """ expand doc""" - code_lowered(f, types) +```rst +code_lowered(f, types) -Returns an array of lowered ASTs for the methods matching the given -generic function and type signature. + Returns an array of lowered ASTs for the methods matching the given + generic function and type signature. +``` """ code_lowered doc""" - @code_lowered() +```rst +@code_lowered() -Evaluates the arguments to the function call, determines their -types, and calls `code_lowered()` on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls "code_lowered()" on the resulting expression +``` """ @code_lowered doc""" - code_typed(f, types; optimize=true) +```rst +code_typed(f, types; optimize=true) -Returns an array of lowered and type-inferred ASTs for the methods -matching the given generic function and type signature. The keyword -argument `optimize` controls whether additional optimizations, -such as inlining, are also applied. + Returns an array of lowered and type-inferred ASTs for the methods + matching the given generic function and type signature. The keyword + argument "optimize" controls whether additional optimizations, + such as inlining, are also applied. +``` """ code_typed doc""" - @code_typed() +```rst +@code_typed() -Evaluates the arguments to the function call, determines their -types, and calls `code_typed()` on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls "code_typed()" on the resulting expression +``` """ @code_typed doc""" - code_warntype(f, types) +```rst +code_warntype(f, types) -Displays lowered and type-inferred ASTs for the methods matching -the given generic function and type signature. The ASTs are -annotated in such a way as to cause `non-leaf` types to be -emphasized (if color is available, displayed in red). This serves -as a warning of potential type instability. Not all non-leaf types -are particularly problematic for performance, so the results need -to be used judiciously. See *@code_warntype* for more information. + Displays lowered and type-inferred ASTs for the methods matching + the given generic function and type signature. The ASTs are + annotated in such a way as to cause "non-leaf" types to be + emphasized (if color is available, displayed in red). This serves + as a warning of potential type instability. Not all non-leaf types + are particularly problematic for performance, so the results need + to be used judiciously. See *@code_warntype* for more information. +``` """ code_warntype doc""" - @code_warntype() +```rst +@code_warntype() -Evaluates the arguments to the function call, determines their -types, and calls `code_warntype()` on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls "code_warntype()" on the resulting expression +``` """ @code_warntype doc""" - code_llvm(f, types) +```rst +code_llvm(f, types) -Prints the LLVM bitcodes generated for running the method matching -the given generic function and type signature to `STDOUT`. -All metadata and dbg.* calls are removed from the printed bitcode. -Use code_llvm_raw for the full IR. + Prints the LLVM bitcodes generated for running the method matching + the given generic function and type signature to "STDOUT". + + All metadata and dbg.* calls are removed from the printed bitcode. + Use code_llvm_raw for the full IR. +``` """ code_llvm doc""" - @code_llvm() +```rst +@code_llvm() -Evaluates the arguments to the function call, determines their -types, and calls `code_llvm()` on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls "code_llvm()" on the resulting expression +``` """ @code_llvm doc""" - code_native(f, types) +```rst +code_native(f, types) -Prints the native assembly instructions generated for running the -method matching the given generic function and type signature to -STDOUT. + Prints the native assembly instructions generated for running the + method matching the given generic function and type signature to + STDOUT. +``` """ code_native doc""" - @code_native() +```rst +@code_native() -Evaluates the arguments to the function call, determines their -types, and calls `code_native()` on the resulting expression + Evaluates the arguments to the function call, determines their + types, and calls "code_native()" on the resulting expression +``` """ @code_native doc""" - precompile(f, args::Tuple{Vararg{Any}}) +```rst +precompile(f, args::Tuple{Vararg{Any}}) -Compile the given function `f` for the argument tuple (of types) + Compile the given function "f" for the argument tuple (of types) + "args", but do not execute it. +``` """ precompile doc""" - ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) +```rst +ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) + + Call function in C-exported shared library, specified by + "(function name, library)" tuple, where each component is an + AbstractString or :Symbol. + + Note that the argument type tuple must be a literal tuple, and not + a tuple-valued variable or expression. Alternatively, ccall may + also be used to call a function pointer, such as one returned by + dlsym. -Call function in C-exported shared library, specified by -AbstractString or :Symbol. -Note that the argument type tuple must be a literal tuple, and not -a tuple-valued variable or expression. Alternatively, ccall may -also be used to call a function pointer, such as one returned by -dlsym. -Each `ArgumentValue` to the `ccall` will be converted to the -corresponding `ArgumentType`, by automatic insertion of calls to -ArgumentValue))`. (see also the documentation for each of these -functions for further details). In most cases, this simply results -in a call to `convert(ArgumentType, ArgumentValue)` + Each "ArgumentValue" to the "ccall" will be converted to the + corresponding "ArgumentType", by automatic insertion of calls to + "unsafe_convert(ArgumentType, cconvert(ArgumentType, + ArgumentValue))". (see also the documentation for each of these + functions for further details). In most cases, this simply results + in a call to "convert(ArgumentType, ArgumentValue)" +``` """ Base.ccall doc""" - cglobal((symbol, library)[, type=Void]) +```rst +cglobal((symbol, library)[, type=Void]) -Obtain a pointer to a global variable in a C-exported shared -library, specified exactly as in `ccall`. Returns a -supplied. The values can be read or written by `unsafe_load` or + Obtain a pointer to a global variable in a C-exported shared + library, specified exactly as in "ccall". Returns a + "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is + supplied. The values can be read or written by "unsafe_load" or + "unsafe_store!", respectively. +``` """ cglobal doc""" - cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) +```rst +cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) -Generate C-callable function pointer from Julia function. Type -annotation of the return value in the callback function is a must -for situations where Julia cannot infer the return type -automatically. -For example: + Generate C-callable function pointer from Julia function. Type + annotation of the return value in the callback function is a must + for situations where Julia cannot infer the return type + automatically. + + For example: + + function foo() + # body + + retval::Float64 + end + + bar = cfunction(foo, Float64, ()) +``` """ cfunction doc""" - unsafe_convert(T, x) +```rst +unsafe_convert(T, x) + + Convert "x" to a value of type "T" + + In cases where "convert" would need to take a Julia object and + turn it into a "Ptr", this function should be used to define and + perform that conversion. + + Be careful to ensure that a julia reference to "x" exists as long + as the result of this function will be used. Accordingly, the + argument "x" to this function should never be an expression, only + a variable name or field reference. For example, "x=a.b.c" is + acceptable, but "x=[a,b,c]" is not. -Convert `x` to a value of type `T` -In cases where `convert` would need to take a Julia object and -turn it into a `Ptr`, this function should be used to define and -perform that conversion. -Be careful to ensure that a julia reference to `x` exists as long -as the result of this function will be used. Accordingly, the -argument `x` to this function should never be an expression, only -a variable name or field reference. For example, `x=a.b.c` is -acceptable, but `x=[a,b,c]` is not. -The `unsafe` prefix on this function indicates that using the -result of this function after the `x` argument to this function -is no longer accessible to the program may cause undefined -behavior, including program corruption or segfaults, at any later -time. + The "unsafe" prefix on this function indicates that using the + result of this function after the "x" argument to this function + is no longer accessible to the program may cause undefined + behavior, including program corruption or segfaults, at any later + time. +``` """ unsafe_convert doc""" - cconvert(T, x) +```rst +cconvert(T, x) -Convert `x` to a value of type `T`, typically by calling -In cases where `x` cannot be safely converted to `T`, unlike -from `T`, which however is suitable for `unsafe_convert` to -handle. -Neither `convert` nor `cconvert` should take a Julia object and -turn it into a `Ptr`. + Convert "x" to a value of type "T", typically by calling + "convert(T,x)" + + In cases where "x" cannot be safely converted to "T", unlike + "convert", "cconvert" may return an object of a type different + from "T", which however is suitable for "unsafe_convert" to + handle. + + Neither "convert" nor "cconvert" should take a Julia object and + turn it into a "Ptr". +``` """ cconvert doc""" - unsafe_load(p::Ptr{T}, i::Integer) +```rst +unsafe_load(p::Ptr{T}, i::Integer) + + Load a value of type "T" from the address of the ith element + (1-indexed) starting at "p". This is equivalent to the C + expression "p[i-1]". -Load a value of type `T` from the address of the ith element -expression `p[i-1]`. -The `unsafe` prefix on this function indicates that no validation -is performed on the pointer `p` to ensure that it is valid. -Incorrect usage may segfault your program or return garbage -answers, in the same manner as C. + The "unsafe" prefix on this function indicates that no validation + is performed on the pointer "p" to ensure that it is valid. + Incorrect usage may segfault your program or return garbage + answers, in the same manner as C. +``` """ unsafe_load doc""" - unsafe_store!(p::Ptr{T}, x, i::Integer) +```rst +unsafe_store!(p::Ptr{T}, x, i::Integer) -Store a value of type `T` to the address of the ith element -expression `p[i-1] = x`. -The `unsafe` prefix on this function indicates that no validation -is performed on the pointer `p` to ensure that it is valid. -Incorrect usage may corrupt or segfault your program, in the same -manner as C. + Store a value of type "T" to the address of the ith element + (1-indexed) starting at "p". This is equivalent to the C + expression "p[i-1] = x". + + The "unsafe" prefix on this function indicates that no validation + is performed on the pointer "p" to ensure that it is valid. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. +``` """ unsafe_store! doc""" - unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) +```rst +unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy "N" elements from a source pointer to a destination, with no + checking. The size of an element is determined by the type of the + pointers. -Copy `N` elements from a source pointer to a destination, with no -checking. The size of an element is determined by the type of the -pointers. -The `unsafe` prefix on this function indicates that no validation -is performed on the pointers `dest` and `src` to ensure that -they are valid. Incorrect usage may corrupt or segfault your -program, in the same manner as C. + The "unsafe" prefix on this function indicates that no validation + is performed on the pointers "dest" and "src" to ensure that + they are valid. Incorrect usage may corrupt or segfault your + program, in the same manner as C. +``` """ unsafe_copy! doc""" - unsafe_copy!(dest::Array, do, src::Array, so, N) +```rst +unsafe_copy!(dest::Array, do, src::Array, so, N) + + Copy "N" elements from a source array to a destination, starting + at offset "so" in the source and "do" in the destination + (1-indexed). -Copy `N` elements from a source array to a destination, starting -at offset `so` in the source and `do` in the destination -The `unsafe` prefix on this function indicates that no validation -is performed to ensure that N is inbounds on either array. -Incorrect usage may corrupt or segfault your program, in the same -manner as C. + The "unsafe" prefix on this function indicates that no validation + is performed to ensure that N is inbounds on either array. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. +``` """ unsafe_copy! doc""" - copy!(dest, src) +```rst +copy!(dest, src) -Copy all elements from collection `src` to array `dest`. -Returns `dest`. + Copy all elements from collection "src" to array "dest". + Returns "dest". +``` """ copy! doc""" - copy!(dest, do, src, so, N) +```rst +copy!(dest, do, src, so, N) -Copy `N` elements from collection `src` starting at offset + Copy "N" elements from collection "src" starting at offset + "so", to array "dest" starting at offset "do". Returns + "dest". +``` """ copy! doc""" - pointer(array[, index]) +```rst +pointer(array[, index]) -Get the native address of an array or string element. Be careful to -ensure that a julia reference to `a` exists as long as this -pointer will be used. This function is `unsafe` like -Calling `Ref(array[, index])` is generally preferable to this -function. + Get the native address of an array or string element. Be careful to + ensure that a julia reference to "a" exists as long as this + pointer will be used. This function is "unsafe" like + "unsafe_convert". + + Calling "Ref(array[, index])" is generally preferable to this + function. +``` """ pointer doc""" - pointer_to_array(pointer, dims[, take_ownership::Bool]) +```rst +pointer_to_array(pointer, dims[, take_ownership::Bool]) -Wrap a native pointer as a Julia Array object. The pointer element -type determines the array element type. `own` optionally -specifies whether Julia should take ownership of the memory, -calling `free` on the pointer when the array is no longer -referenced. + Wrap a native pointer as a Julia Array object. The pointer element + type determines the array element type. "own" optionally + specifies whether Julia should take ownership of the memory, + calling "free" on the pointer when the array is no longer + referenced. +``` """ pointer_to_array doc""" - pointer_from_objref(object_instance) +```rst +pointer_from_objref(object_instance) -Get the memory address of a Julia object as a `Ptr`. The -existence of the resulting `Ptr` will not protect the object from -garbage collection, so you must ensure that the object remains -referenced for the whole time that the `Ptr` will be used. + Get the memory address of a Julia object as a "Ptr". The + existence of the resulting "Ptr" will not protect the object from + garbage collection, so you must ensure that the object remains + referenced for the whole time that the "Ptr" will be used. +``` """ pointer_from_objref doc""" - unsafe_pointer_to_objref(p::Ptr) +```rst +unsafe_pointer_to_objref(p::Ptr) -Convert a `Ptr` to an object reference. Assumes the pointer -refers to a valid heap-allocated Julia object. If this is not the -case, undefined behavior results, hence this function is considered + Convert a "Ptr" to an object reference. Assumes the pointer + refers to a valid heap-allocated Julia object. If this is not the + case, undefined behavior results, hence this function is considered + "unsafe" and should be used with care. +``` """ unsafe_pointer_to_objref doc""" - disable_sigint(f::Function) +```rst +disable_sigint(f::Function) + + Disable Ctrl-C handler during execution of a function, for calling + external code that is not interrupt safe. Intended to be called + using "do" block syntax as follows: -Disable Ctrl-C handler during execution of a function, for calling -external code that is not interrupt safe. Intended to be called -using `do` block syntax as follows: + disable_sigint() do + # interrupt-unsafe code + ... + end +``` """ disable_sigint doc""" - reenable_sigint(f::Function) +```rst +reenable_sigint(f::Function) -Re-enable Ctrl-C handler during execution of a function. -Temporarily reverses the effect of `disable_sigint`. + Re-enable Ctrl-C handler during execution of a function. + Temporarily reverses the effect of "disable_sigint". +``` """ reenable_sigint doc""" - systemerror(sysfunc, iftrue) +```rst +systemerror(sysfunc, iftrue) -Raises a `SystemError` for `errno` with the descriptive string + Raises a "SystemError" for "errno" with the descriptive string + "sysfunc" if "bool" is true +``` """ systemerror doc""" - Cchar +```rst +Cchar -Equivalent to the native `char` c-type + Equivalent to the native "char" c-type +``` """ Cchar doc""" - Cuchar +```rst +Cuchar -Equivalent to the native `unsigned char` c-type (UInt8) + Equivalent to the native "unsigned char" c-type (UInt8) +``` """ Cuchar doc""" - Cshort +```rst +Cshort -Equivalent to the native `signed short` c-type (Int16) + Equivalent to the native "signed short" c-type (Int16) +``` """ Cshort doc""" - Cushort +```rst +Cushort -Equivalent to the native `unsigned short` c-type (UInt16) + Equivalent to the native "unsigned short" c-type (UInt16) +``` """ Cushort doc""" - Cint +```rst +Cint -Equivalent to the native `signed int` c-type (Int32) + Equivalent to the native "signed int" c-type (Int32) +``` """ Cint doc""" - Cuint +```rst +Cuint -Equivalent to the native `unsigned int` c-type (UInt32) + Equivalent to the native "unsigned int" c-type (UInt32) +``` """ Cuint doc""" - Clong +```rst +Clong -Equivalent to the native `signed long` c-type + Equivalent to the native "signed long" c-type +``` """ Clong doc""" - Culong +```rst +Culong -Equivalent to the native `unsigned long` c-type + Equivalent to the native "unsigned long" c-type +``` """ Culong doc""" - Clonglong +```rst +Clonglong -Equivalent to the native `signed long long` c-type (Int64) + Equivalent to the native "signed long long" c-type (Int64) +``` """ Clonglong doc""" - Culonglong +```rst +Culonglong -Equivalent to the native `unsigned long long` c-type (UInt64) + Equivalent to the native "unsigned long long" c-type (UInt64) +``` """ Culonglong doc""" - Cintmax_t +```rst +Cintmax_t -Equivalent to the native `intmax_t` c-type (Int64) + Equivalent to the native "intmax_t" c-type (Int64) +``` """ Cintmax_t doc""" - Cuintmax_t +```rst +Cuintmax_t -Equivalent to the native `uintmax_t` c-type (UInt64) + Equivalent to the native "uintmax_t" c-type (UInt64) +``` """ Cuintmax_t doc""" - Csize_t +```rst +Csize_t -Equivalent to the native `size_t` c-type (UInt) + Equivalent to the native "size_t" c-type (UInt) +``` """ Csize_t doc""" - Cssize_t +```rst +Cssize_t -Equivalent to the native `ssize_t` c-type + Equivalent to the native "ssize_t" c-type +``` """ Cssize_t doc""" - Cptrdiff_t +```rst +Cptrdiff_t -Equivalent to the native `ptrdiff_t` c-type (Int) + Equivalent to the native "ptrdiff_t" c-type (Int) +``` """ Cptrdiff_t doc""" - Coff_t +```rst +Coff_t -Equivalent to the native `off_t` c-type + Equivalent to the native "off_t" c-type +``` """ Coff_t doc""" - Cwchar_t +```rst +Cwchar_t -Equivalent to the native `wchar_t` c-type (Int32) + Equivalent to the native "wchar_t" c-type (Int32) +``` """ Cwchar_t doc""" - Cfloat +```rst +Cfloat -Equivalent to the native `float` c-type (Float32) + Equivalent to the native "float" c-type (Float32) +``` """ Cfloat doc""" - Cdouble +```rst +Cdouble -Equivalent to the native `double` c-type (Float64) + Equivalent to the native "double" c-type (Float64) +``` """ Cdouble doc""" - start(iter) -> state +```rst +start(iter) -> state -Get initial iteration state for an iterable object + Get initial iteration state for an iterable object +``` """ start doc""" - done(iter, state) -> Bool +```rst +done(iter, state) -> Bool -Test whether we are done iterating + Test whether we are done iterating +``` """ done doc""" - next(iter, state) -> item, state +```rst +next(iter, state) -> item, state -For a given iterable object and iteration state, return the current -item and the next iteration state + For a given iterable object and iteration state, return the current + item and the next iteration state +``` """ next doc""" - zip(iters...) +```rst +zip(iters...) + + For a set of iterable objects, returns an iterable of tuples, where + the "i"th tuple contains the "i"th component of each input + iterable. -For a set of iterable objects, returns an iterable of tuples, where -the `i`th tuple contains the `i`th component of each input -iterable. -Note that `zip()` is its own inverse: + Note that "zip()" is its own inverse: + "collect(zip(zip(a...)...)) == collect(a)". +``` """ zip doc""" - enumerate(iter) +```rst +enumerate(iter) -An iterator that yields `(i, x)` where `i` is an index starting -at 1, and `x` is the `i`th value from the given iterator. It's -useful when you need not only the values `x` over which you are -iterating, but also the index `i` of the iterations. + An iterator that yields "(i, x)" where "i" is an index starting + at 1, and "x" is the "i"th value from the given iterator. It's + useful when you need not only the values "x" over which you are + iterating, but also the index "i" of the iterations. + + julia> a = ["a", "b", "c"]; + + julia> for (index, value) in enumerate(a) + println("\$index \$value") + end + 1 a + 2 b + 3 c +``` """ enumerate doc""" - rest(iter, state) +```rst +rest(iter, state) -An iterator that yields the same elements as `iter`, but starting -at the given `state`. + An iterator that yields the same elements as "iter", but starting + at the given "state". +``` """ rest doc""" - countfrom(start=1, step=1) +```rst +countfrom(start=1, step=1) -An iterator that counts forever, starting at `start` and -incrementing by `step`. + An iterator that counts forever, starting at "start" and + incrementing by "step". +``` """ countfrom doc""" - take(iter, n) +```rst +take(iter, n) -An iterator that generates at most the first `n` elements of + An iterator that generates at most the first "n" elements of + "iter". +``` """ take doc""" - drop(iter, n) +```rst +drop(iter, n) -An iterator that generates all but the first `n` elements of + An iterator that generates all but the first "n" elements of + "iter". +``` """ drop doc""" - cycle(iter) +```rst +cycle(iter) -An iterator that cycles through `iter` forever. + An iterator that cycles through "iter" forever. +``` """ cycle doc""" - repeated(x[, n::Int]) +```rst +repeated(x[, n::Int]) -An iterator that generates the value `x` forever. If `n` is -specified, generates `x` that many times (equivalent to + An iterator that generates the value "x" forever. If "n" is + specified, generates "x" that many times (equivalent to + "take(repeated(x), n)"). +``` """ repeated doc""" - isempty(collection) -> Bool +```rst +isempty(collection) -> Bool -Determine whether a collection is empty (has no elements). + Determine whether a collection is empty (has no elements). + + julia> isempty([]) + true + + julia> isempty([1 2 3]) + false +``` """ isempty doc""" - empty!(collection) -> collection +```rst +empty!(collection) -> collection -Remove all elements from a `collection`. + Remove all elements from a "collection". +``` """ empty! doc""" - length(collection) -> Integer +```rst +length(collection) -> Integer -For ordered, indexable collections, the maximum index `i` for -which `getindex(collection, i)` is valid. For unordered -collections, the number of elements. + For ordered, indexable collections, the maximum index "i" for + which "getindex(collection, i)" is valid. For unordered + collections, the number of elements. +``` """ length doc""" - endof(collection) -> Integer +```rst +endof(collection) -> Integer + + Returns the last index of the collection. -Returns the last index of the collection. + julia> endof([1,2,4]) + 3 +``` """ endof doc""" - in(item, collection) -> Bool +```rst +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 -To test for the presence of a key in a dictionary, use `haskey()` -or `k in keys(dict)`. + 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)". +``` """ Base.in doc""" - eltype(type) +```rst +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 `(key,value)` tuple type. The definition -that instances can be passed instead of types. However the form -that accepts a type argument should be defined for new types. + Determine the type of the elements generated by iterating a + collection of the given "type". For associative collection types, + this will be a "(key,value)" tuple type. 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. +``` """ eltype doc""" - indexin(a, b) +```rst +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`. + 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". +``` """ indexin doc""" - findin(a, b) +```rst +findin(a, b) -Returns the indices of elements in collection `a` that appear in -collection `b` + Returns the indices of elements in collection "a" that appear in + collection "b" +``` """ findin doc""" - unique(itr[, dim]) +```rst +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`. + 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". +``` """ unique doc""" - reduce(op, v0, itr) +```rst +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. -Reduce the given collection `ìtr` with the given binary operator -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)`, -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. + 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. +``` """ reduce doc""" - reduce(op, itr) +```rst +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`. + 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". +``` """ reduce doc""" - foldl(op, v0, itr) +```rst +foldl(op, v0, itr) -Like `reduce()`, but with guaranteed left associativity. `v0` -will be used exactly once. + Like "reduce()", but with guaranteed left associativity. "v0" + will be used exactly once. +``` """ foldl doc""" - foldl(op, itr) +```rst +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 + 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)"). +``` """ foldl doc""" - foldr(op, v0, itr) +```rst +foldr(op, v0, itr) -Like `reduce()`, but with guaranteed right associativity. `v0` -will be used exactly once. + Like "reduce()", but with guaranteed right associativity. "v0" + will be used exactly once. +``` """ foldr doc""" - foldr(op, itr) +```rst +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 + 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)"). +``` """ foldr doc""" - maximum(itr) +```rst +maximum(itr) -Returns the largest element in a collection. + Returns the largest element in a collection. +``` """ maximum doc""" - maximum(A, dims) +```rst +maximum(A, dims) -Compute the maximum value of an array over the given dimensions. + Compute the maximum value of an array over the given dimensions. +``` """ maximum doc""" - maximum!(r, A) +```rst +maximum!(r, A) -Compute the maximum value of `A` over the singleton dimensions of + Compute the maximum value of "A" over the singleton dimensions of + "r", and write results to "r". +``` """ maximum! doc""" - minimum(itr) +```rst +minimum(itr) -Returns the smallest element in a collection. + Returns the smallest element in a collection. +``` """ minimum doc""" - minimum(A, dims) +```rst +minimum(A, dims) -Compute the minimum value of an array over the given dimensions. + Compute the minimum value of an array over the given dimensions. +``` """ minimum doc""" - minimum!(r, A) +```rst +minimum!(r, A) -Compute the minimum value of `A` over the singleton dimensions of + Compute the minimum value of "A" over the singleton dimensions of + "r", and write results to "r". +``` """ minimum! doc""" - extrema(itr) +```rst +extrema(itr) -Compute both the minimum and maximum element in a single pass, and -return them as a 2-tuple. + Compute both the minimum and maximum element in a single pass, and + return them as a 2-tuple. +``` """ extrema doc""" - indmax(itr) -> Integer +```rst +indmax(itr) -> Integer -Returns the index of the maximum element in a collection. + Returns the index of the maximum element in a collection. +``` """ indmax doc""" - indmin(itr) -> Integer +```rst +indmin(itr) -> Integer -Returns the index of the minimum element in a collection. + Returns the index of the minimum element in a collection. +``` """ indmin doc""" - findmax(itr) -> (x, index) +```rst +findmax(itr) -> (x, index) -Returns the maximum element and its index. + Returns the maximum element and its index. +``` """ findmax doc""" - findmax(A, dims) -> (maxval, index) +```rst +findmax(A, dims) -> (maxval, index) -For an array input, returns the value and index of the maximum over -the given dimensions. + For an array input, returns the value and index of the maximum over + the given dimensions. +``` """ findmax doc""" - findmin(itr) -> (x, index) +```rst +findmin(itr) -> (x, index) -Returns the minimum element and its index. + Returns the minimum element and its index. +``` """ findmin doc""" - findmin(A, dims) -> (minval, index) +```rst +findmin(A, dims) -> (minval, index) -For an array input, returns the value and index of the minimum over -the given dimensions. + For an array input, returns the value and index of the minimum over + the given dimensions. +``` """ findmin doc""" - maxabs(itr) +```rst +maxabs(itr) -Compute the maximum absolute value of a collection of values. + Compute the maximum absolute value of a collection of values. +``` """ maxabs doc""" - maxabs(A, dims) +```rst +maxabs(A, dims) -Compute the maximum absolute values over given dimensions. + Compute the maximum absolute values over given dimensions. +``` """ maxabs doc""" - maxabs!(r, A) +```rst +maxabs!(r, A) -Compute the maximum absolute values over the singleton dimensions -of `r`, and write values to `r`. + Compute the maximum absolute values over the singleton dimensions + of "r", and write values to "r". +``` """ maxabs! doc""" - minabs(itr) +```rst +minabs(itr) -Compute the minimum absolute value of a collection of values. + Compute the minimum absolute value of a collection of values. +``` """ minabs doc""" - minabs(A, dims) +```rst +minabs(A, dims) -Compute the minimum absolute values over given dimensions. + Compute the minimum absolute values over given dimensions. +``` """ minabs doc""" - minabs!(r, A) +```rst +minabs!(r, A) -Compute the minimum absolute values over the singleton dimensions -of `r`, and write values to `r`. + Compute the minimum absolute values over the singleton dimensions + of "r", and write values to "r". +``` """ minabs! doc""" - sum(itr) +```rst +sum(itr) -Returns the sum of all elements in a collection. + Returns the sum of all elements in a collection. +``` """ sum doc""" - sum(A, dims) +```rst +sum(A, dims) -Sum elements of an array over the given dimensions. + Sum elements of an array over the given dimensions. +``` """ sum doc""" - sum!(r, A) +```rst +sum!(r, A) -Sum elements of `A` over the singleton dimensions of `r`, and -write results to `r`. + Sum elements of "A" over the singleton dimensions of "r", and + write results to "r". +``` """ sum! doc""" - sum(f, itr) +```rst +sum(f, itr) -Sum the results of calling function `f` on each element of + Sum the results of calling function "f" on each element of + "itr". +``` """ sum doc""" - sumabs(itr) +```rst +sumabs(itr) -Sum absolute values of all elements in a collection. This is -equivalent to *sum(abs(itr))* but faster. + Sum absolute values of all elements in a collection. This is + equivalent to *sum(abs(itr))* but faster. +``` """ sumabs doc""" - sumabs(A, dims) +```rst +sumabs(A, dims) -Sum absolute values of elements of an array over the given -dimensions. + Sum absolute values of elements of an array over the given + dimensions. +``` """ sumabs doc""" - sumabs!(r, A) +```rst +sumabs!(r, A) -Sum absolute values of elements of `A` over the singleton -dimensions of `r`, and write results to `r`. + Sum absolute values of elements of "A" over the singleton + dimensions of "r", and write results to "r". +``` """ sumabs! doc""" - sumabs2(itr) +```rst +sumabs2(itr) -Sum squared absolute values of all elements in a collection. This -is equivalent to *sum(abs2(itr))* but faster. + Sum squared absolute values of all elements in a collection. This + is equivalent to *sum(abs2(itr))* but faster. +``` """ sumabs2 doc""" - sumabs2(A, dims) +```rst +sumabs2(A, dims) -Sum squared absolute values of elements of an array over the given -dimensions. + Sum squared absolute values of elements of an array over the given + dimensions. +``` """ sumabs2 doc""" - sumabs2!(r, A) +```rst +sumabs2!(r, A) -Sum squared absolute values of elements of `A` over the singleton -dimensions of `r`, and write results to `r`. + Sum squared absolute values of elements of "A" over the singleton + dimensions of "r", and write results to "r". +``` """ sumabs2! doc""" - prod(itr) +```rst +prod(itr) -Returns the product of all elements of a collection. + Returns the product of all elements of a collection. +``` """ prod doc""" - prod(A, dims) +```rst +prod(A, dims) -Multiply elements of an array over the given dimensions. + Multiply elements of an array over the given dimensions. +``` """ prod doc""" - prod!(r, A) +```rst +prod!(r, A) -Multiply elements of `A` over the singleton dimensions of `r`, -and write results to `r`. + Multiply elements of "A" over the singleton dimensions of "r", + and write results to "r". +``` """ prod! doc""" - any(itr) -> Bool +```rst +any(itr) -> Bool -Test whether any elements of a boolean collection are true. + Test whether any elements of a boolean collection are true. +``` """ any doc""" - any(A, dims) +```rst +any(A, dims) -Test whether any values along the given dimensions of an array are -true. + Test whether any values along the given dimensions of an array are + true. +``` """ any doc""" - any!(r, A) +```rst +any!(r, A) -Test whether any values in `A` along the singleton dimensions of + Test whether any values in "A" along the singleton dimensions of + "r" are true, and write results to "r". +``` """ any! doc""" - all(itr) -> Bool +```rst +all(itr) -> Bool -Test whether all elements of a boolean collection are true. + Test whether all elements of a boolean collection are true. +``` """ all doc""" - all(A, dims) +```rst +all(A, dims) -Test whether all values along the given dimensions of an array are -true. + Test whether all values along the given dimensions of an array are + true. +``` """ all doc""" - all!(r, A) +```rst +all!(r, A) -Test whether all values in `A` along the singleton dimensions of + Test whether all values in "A" along the singleton dimensions of + "r" are true, and write results to "r". +``` """ all! doc""" - count(p, itr) -> Integer +```rst +count(p, itr) -> Integer -Count the number of elements in `itr` for which predicate `p` -returns true. + Count the number of elements in "itr" for which predicate "p" + returns true. +``` """ count doc""" - any(p, itr) -> Bool +```rst +any(p, itr) -> Bool -Determine whether predicate `p` returns true for any elements of + Determine whether predicate "p" returns true for any elements of + "itr". +``` """ any doc""" - all(p, itr) -> Bool +```rst +all(p, itr) -> Bool -Determine whether predicate `p` returns true for all elements of + Determine whether predicate "p" returns true for all elements of + "itr". + + julia> all(i->(4<=i<=6), [4,5,6]) + true +``` """ all doc""" - map(f, c...) -> collection +```rst +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 -Transform collection `c` by applying `f` to each element. For -multiple collection arguments, apply `f` elementwise. + julia> map(+, [1, 2, 3], [10, 20, 30]) + 3-element Array{Int64,1}: + 11 + 22 + 33 +``` """ map doc""" - map!(function, collection) +```rst +map!(function, collection) -In-place version of `map()`. + In-place version of "map()". +``` """ map! doc""" - map!(function, destination, collection...) +```rst +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. + Like "map()", but stores the result in "destination" rather + than a new collection. "destination" must be at least as large as + the first collection. +``` """ map! doc""" - mapreduce(f, op, v0, itr) +```rst +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 -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. -v0, map(f, itr))`, but will in general execute faster since no -intermediate collection needs to be created. See documentation for -The associativity of the reduction is implementation-dependent. -Additionally, some implementations may reuse the return value of -right associativity and invocation of `f` for every value. + 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. +``` """ mapreduce doc""" - mapreduce(f, op, itr) +```rst +mapreduce(f, op, itr) -Like `mapreduce(f, op, v0, itr)`. In general, this cannot be used -with empty collections (see `reduce(op, itr)`). + Like "mapreduce(f, op, v0, itr)". In general, this cannot be used + with empty collections (see "reduce(op, itr)"). +``` """ mapreduce doc""" - mapfoldl(f, op, v0, itr) +```rst +mapfoldl(f, op, v0, itr) -Like `mapreduce()`, but with guaranteed left associativity. + Like "mapreduce()", but with guaranteed left associativity. + "v0" will be used exactly once. +``` """ mapfoldl doc""" - mapfoldl(f, op, itr) +```rst +mapfoldl(f, op, itr) -Like `mapfoldl(f, op, v0, itr)`, but using the first element of -collections (see `reduce(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)"). +``` """ mapfoldl doc""" - mapfoldr(f, op, v0, itr) +```rst +mapfoldr(f, op, v0, itr) -Like `mapreduce()`, but with guaranteed right associativity. + Like "mapreduce()", but with guaranteed right associativity. + "v0" will be used exactly once. +``` """ mapfoldr doc""" - mapfoldr(f, op, itr) +```rst +mapfoldr(f, op, itr) -Like `mapfoldr(f, op, v0, itr)`, but using the first element of -collections (see `reduce(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)"). +``` """ mapfoldr doc""" - first(coll) +```rst +first(coll) -Get the first element of an iterable collection. Returns the start -point of a `Range` even if it is empty. + Get the first element of an iterable collection. Returns the start + point of a "Range" even if it is empty. +``` """ first doc""" - last(coll) +```rst +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. + 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. +``` """ last doc""" - step(r) +```rst +step(r) -Get the step size of a `Range` object. + Get the step size of a "Range" object. +``` """ step doc""" - collect(collection) +```rst +collect(collection) -Return an array of all items in a collection. For associative -collections, returns (key, value) tuples. + Return an array of all items in a collection. For associative + collections, returns (key, value) tuples. +``` """ collect doc""" - collect(element_type, collection) +```rst +collect(element_type, collection) -Return an array of type `Array{element_type,1}` of all items in a -collection. + Return an array of type "Array{element_type,1}" of all items in a + collection. +``` """ collect doc""" - issubset(a, b) +```rst +issubset(a, b) +⊆(A, S) -> Bool +⊈(A, S) -> Bool +⊊(A, S) -> Bool -Determine whether every element of `a` is also in `b`, using + Determine whether every element of "a" is also in "b", using + "in()". +``` """ issubset doc""" - filter(function, collection) +```rst +filter(function, collection) -Return a copy of `collection`, removing elements for which -passed two arguments (key and value). + Return a copy of "collection", removing elements for which + "function" is false. For associative collections, the function is + passed two arguments (key and value). +``` """ filter doc""" - filter!(function, collection) +```rst +filter!(function, collection) -Update `collection`, removing elements for which `function` is -false. For associative collections, the function is passed two -arguments (key and value). + Update "collection", removing elements for which "function" is + false. For associative collections, the function is passed two + arguments (key and value). +``` """ filter! doc""" - getindex(collection, key...) +```rst +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, ...)`. + 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, ...)". +``` """ getindex doc""" - setindex!(collection, value, key...) +```rst +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, ...)`. + 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, ...)". +``` """ setindex! doc""" - Dict([itr]) +```rst +Dict([itr]) -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. -Alternatively, a sequence of pair arguments may be passed. + "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{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 + + Alternatively, a sequence of pair arguments may be passed. + + julia> Dict("A"=>1, "B"=>2) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 +``` """ Dict doc""" - haskey(collection, key) -> Bool +```rst +haskey(collection, key) -> Bool -Determine whether a collection has a mapping for a given key. + Determine whether a collection has a mapping for a given key. +``` """ haskey doc""" - get(collection, key, default) +```rst +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. + Return the value stored for the given key, or the given default + value if no mapping for the key is present. +``` """ get doc""" - get(f::Function, collection, key) +```rst +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: + 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 +``` """ get doc""" - get!(collection, key, default) +```rst +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`. + Return the value stored for the given key, or if no mapping for the + key is present, store "key => default", and return "default". +``` """ get! doc""" - get!(f::Function, collection, key) +```rst +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()". -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: + This is intended to be called using "do" block syntax: + + get!(dict, key) do + # default value calculated here + time() + end +``` """ get! doc""" - getkey(collection, key, default) +```rst +getkey(collection, key, default) -Return the key matching argument `key` if one exists in + Return the key matching argument "key" if one exists in + "collection", otherwise return "default". +``` """ getkey doc""" - delete!(collection, key) +```rst +delete!(collection, key) -Delete the mapping for the given key in a collection, and return -the collection. + Delete the mapping for the given key in a collection, and return + the collection. +``` """ delete! doc""" - pop!(collection, key[, default]) +```rst +pop!(collection, key[, default]) -Delete and return the mapping for `key` if it exists in -default is not specified. + Delete and return the mapping for "key" if it exists in + "collection", otherwise return "default", or throw an error if + default is not specified. +``` """ pop! doc""" - keys(collection) +```rst +keys(collection) -Return an iterator over all keys in a collection. + Return an iterator over all keys in a collection. + "collect(keys(d))" returns an array of keys. +``` """ keys doc""" - values(collection) +```rst +values(collection) -Return an iterator over all values in a collection. + Return an iterator over all values in a collection. + "collect(values(d))" returns an array of values. +``` """ values doc""" - merge(collection, others...) +```rst +merge(collection, others...) -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. + 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{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 + julia> a = Dict("foo" => 0.0, "bar" => 42.0) + Dict{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 - julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "bar" => 4711 - "baz" => 17 + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 +``` """ merge doc""" - merge!(collection, others...) +```rst +merge!(collection, others...) -Update collection with pairs from the other collections + Update collection with pairs from the other collections +``` """ merge! doc""" - sizehint!(s, n) +```rst +sizehint!(s, n) -Suggest that collection `s` reserve capacity for at least `n` -elements. This can improve performance. + Suggest that collection "s" reserve capacity for at least "n" + elements. This can improve performance. +``` """ sizehint! doc""" - Set([itr]) +```rst +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. + 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. +``` """ Set doc""" - IntSet([itr]) +```rst +IntSet([itr]) -Construct a sorted set of the integers generated by the given -iterable object, or an empty set. Implemented as a bit string, and -therefore designed for dense integer sets. Only non-negative -integers can be stored. If the set will be sparse (for example -holding a single very large integer), use `Set` instead. + Construct a sorted set of the integers generated by the given + iterable object, or an empty set. Implemented as a bit string, and + therefore designed for dense integer sets. Only non-negative + integers can be stored. If the set will be sparse (for example + holding a single very large integer), use "Set" instead. +``` """ IntSet doc""" - union(s1, s2...) +```rst +union(s1, s2...) +∪(s1, s2) -Construct the union of two or more sets. Maintains order with -arrays. + Construct the union of two or more sets. Maintains order with + arrays. +``` """ union doc""" - union!(s, iterable) +```rst +union!(s, iterable) -Union each element of `iterable` into set `s` in-place. + Union each element of "iterable" into set "s" in-place. +``` """ union! doc""" - intersect(s1, s2...) +```rst +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. + Construct the intersection of two or more sets. Maintains order and + multiplicity of the first argument for arrays and ranges. +``` """ intersect doc""" - setdiff(s1, s2) +```rst +setdiff(s1, s2) -Construct the set of elements in `s1` but not `s2`. Maintains -order with arrays. Note that both arguments must be collections, -and both will be iterated over. In particular, + Construct the set of elements in "s1" but not "s2". 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. +``` """ setdiff doc""" - setdiff!(s, iterable) +```rst +setdiff!(s, iterable) -Remove each element of `iterable` from set `s` in-place. + Remove each element of "iterable" from set "s" in-place. +``` """ setdiff! doc""" - symdiff(s1, s2...) +```rst +symdiff(s1, s2...) -Construct the symmetric difference of elements in the passed in -sets or arrays. Maintains order with arrays. + Construct the symmetric difference of elements in the passed in + sets or arrays. Maintains order with arrays. +``` """ symdiff doc""" - symdiff!(s, n) +```rst +symdiff!(s, n) -The set `s` is destructively modified to toggle the inclusion of -integer `n`. + The set "s" is destructively modified to toggle the inclusion of + integer "n". +``` """ symdiff! doc""" - symdiff!(s, itr) +```rst +symdiff!(s, itr) -For each element in `itr`, destructively toggle its inclusion in -set `s`. + For each element in "itr", destructively toggle its inclusion in + set "s". +``` """ symdiff! doc""" - symdiff!(s1, s2) +```rst +symdiff!(s1, s2) -Construct the symmetric difference of sets `s1` and `s2`, -storing the result in `s1`. + Construct the symmetric difference of sets "s1" and "s2", + storing the result in "s1". +``` """ symdiff! doc""" - complement(s) +```rst +complement(s) -Returns the set-complement of `IntSet` `s`. + Returns the set-complement of "IntSet" "s". +``` """ complement doc""" - complement!(s) +```rst +complement!(s) -Mutates `IntSet` `s` into its set-complement. + Mutates "IntSet" "s" into its set-complement. +``` """ complement! doc""" - intersect!(s1, s2) +```rst +intersect!(s1, s2) -Intersects sets `s1` and `s2` and overwrites the set `s1` -with the result. If needed, `s1` will be expanded to the size of + Intersects sets "s1" and "s2" and overwrites the set "s1" + with the result. If needed, "s1" will be expanded to the size of + "s2". +``` """ intersect! doc""" - issubset(A, S) -> Bool +```rst +issubset(A, S) -> Bool +⊆(A, S) -> Bool -True if A is a subset of or equal to S. + True if A is a subset of or equal to S. +``` """ issubset doc""" - push!(collection, items...) -> collection +```rst +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 -Insert one or more `items` at the end of `collection`. -Use `append!()` to add all the elements of another collection to -to `append!([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])". +``` """ push! doc""" - pop!(collection) -> item +```rst +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 -Remove the last item in `collection` and return it. + julia> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 +``` """ pop! doc""" - unshift!(collection, items...) -> collection +```rst +unshift!(collection, items...) -> collection -Insert one or more `items` at the beginning of `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 +``` """ unshift! doc""" - shift!(collection) -> item +```rst +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 -Remove the first `item` from `collection`. + julia> shift!(A) + 1 + + julia> A + 5-element Array{Int64,1}: + 2 + 3 + 4 + 5 + 6 +``` """ shift! doc""" - insert!(collection, index, item) +```rst +insert!(collection, index, item) + + Insert an "item" into "collection" at the given "index". + "index" is the index of "item" in the resulting "collection". -Insert an `item` into `collection` at the given `index`. + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 +``` """ insert! doc""" - deleteat!(collection, index) +```rst +deleteat!(collection, index) + + Remove the item at the given "index" and return the modified + "collection". Subsequent items are shifted to fill the resulting + gap. -Remove the item at the given `index` and return the modified -gap. + julia> deleteat!([6, 5, 4, 3, 2, 1], 2) + 5-element Array{Int64,1}: + 6 + 4 + 3 + 2 + 1 +``` """ deleteat! doc""" - deleteat!(collection, itr) +```rst +deleteat!(collection, itr) -Remove the items at the indices given by `itr`, and return the -modified `collection`. Subsequent items are shifted to fill the -resulting gap. `itr` must be sorted and unique. + Remove the items at the indices given by "itr", and return the + modified "collection". Subsequent items are shifted to fill the + resulting gap. "itr" must be sorted and unique. + + 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], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 +``` """ deleteat! doc""" - splice!(collection, index[, replacement]) -> item - -Remove the item at the given index, and return the removed item. -Subsequent items are shifted down to fill the resulting gap. If -specified, replacement values from an ordered collection will be -spliced in place of the removed item. -To insert `replacement` before an index `n` without removing -any items, use `splice!(collection, n:n-1, replacement)`. +```rst +splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. + Subsequent items are shifted down 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)". +``` """ splice! doc""" - splice!(collection, range[, replacement]) -> items +```rst +splice!(collection, range[, replacement]) -> items + + Remove items in the specified index range, and return a collection + containing the removed items. Subsequent items are shifted down 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} -Remove items in the specified index range, and return a collection -containing the removed items. Subsequent items are shifted down 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> A + 8-element Array{Int64,1}: + -1 + -2 + -3 + 2 + 5 + 4 + 3 + -1 +``` """ splice! doc""" - resize!(collection, n) -> collection - -Resize `collection` 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. +```rst +resize!(collection, n) -> collection + + Resize "collection" 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 +``` """ resize! doc""" - append!(collection, collection2) -> collection. +```rst +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 -Add the elements of `collection2` to the end of `collection`. -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)`. + 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)". +``` """ append! doc""" - prepend!(collection, items) -> collection +```rst +prepend!(collection, items) -> collection -Insert the elements of `items` to the beginning of + Insert the elements of "items" to the beginning of + "collection". + + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 +``` """ prepend! doc""" - PriorityQueue(K, V[, ord]) +```rst +PriorityQueue(K, V[, ord]) -Construct a new `PriorityQueue`, with keys of type `K` and -values/priorites of type `V`. If an order is not given, the -priority queue is min-ordered using the default comparison for + Construct a new "PriorityQueue", with keys of type "K" and + values/priorites of type "V". If an order is not given, the + priority queue is min-ordered using the default comparison for + "V". +``` """ Base.Collections.PriorityQueue doc""" - enqueue!(pq, k, v) +```rst +enqueue!(pq, k, v) -Insert the a key `k` into a priority queue `pq` with priority + Insert the a key "k" into a priority queue "pq" with priority + "v". +``` """ Base.Collections.enqueue! doc""" - dequeue!(pq) +```rst +dequeue!(pq) -Remove and return the lowest priority key from a priority queue. + Remove and return the lowest priority key from a priority queue. +``` """ Base.Collections.dequeue! doc""" - peek(pq) +```rst +peek(pq) -Return the lowest priority key from a priority queue without -removing that key from the queue. + Return the lowest priority key from a priority queue without + removing that key from the queue. +``` """ Base.Collections.peek doc""" - heapify(v[, ord]) +```rst +heapify(v[, ord]) -Return a new vector in binary heap order, optionally using the -given ordering. + Return a new vector in binary heap order, optionally using the + given ordering. +``` """ Base.Collections.heapify doc""" - heapify!(v[, ord]) +```rst +heapify!(v[, ord]) -In-place `heapify()`. + In-place "heapify()". +``` """ Base.Collections.heapify! doc""" - isheap(v[, ord]) +```rst +isheap(v[, ord]) -Return true iff an array is heap-ordered according to the given -order. + Return true iff an array is heap-ordered according to the given + order. +``` """ Base.Collections.isheap doc""" - heappush!(v, x[, ord]) +```rst +heappush!(v, x[, ord]) -Given a binary heap-ordered array, push a new element `x`, -preserving the heap property. For efficiency, this function does -not check that the array is indeed heap-ordered. + Given a binary heap-ordered array, push a new element "x", + preserving the heap property. For efficiency, this function does + not check that the array is indeed heap-ordered. +``` """ Base.Collections.heappush! doc""" - heappop!(v[, ord]) +```rst +heappop!(v[, ord]) -Given a binary heap-ordered array, remove and return the lowest -ordered element. For efficiency, this function does not check that -the array is indeed heap-ordered. + Given a binary heap-ordered array, remove and return the lowest + ordered element. For efficiency, this function does not check that + the array is indeed heap-ordered. +``` """ Base.Collections.heappop! doc""" - nothing +```rst +nothing -The singleton instance of type `Void`, used by convention when -there is no value to return (as in a C `void` function). Can be -converted to an empty `Nullable` value. + The singleton instance of type "Void", used by convention when + there is no value to return (as in a C "void" function). Can be + converted to an empty "Nullable" value. +``` """ nothing doc""" - OS_NAME +```rst +OS_NAME -A symbol representing the name of the operating system. Possible -values are `:Linux`, `:Darwin` (OS X), or `:Windows`. + A symbol representing the name of the operating system. Possible + values are ":Linux", ":Darwin" (OS X), or ":Windows". +``` """ OS_NAME doc""" - ARGS +```rst +ARGS -An array of the command line arguments passed to Julia, as strings. + An array of the command line arguments passed to Julia, as strings. +``` """ ARGS doc""" - C_NULL +```rst +C_NULL -The C null pointer constant, sometimes used when calling external -code. + The C null pointer constant, sometimes used when calling external + code. +``` """ C_NULL doc""" - WORD_SIZE +```rst +WORD_SIZE -Standard word size on the current machine, in bits. + Standard word size on the current machine, in bits. +``` """ WORD_SIZE doc""" - VERSION +```rst +VERSION -An object describing which version of Julia is in use. + An object describing which version of Julia is in use. +``` """ VERSION doc""" - LOAD_PATH +```rst +LOAD_PATH -An array of paths (as strings) where the `require` function looks -for code. + An array of paths (as strings) where the "require" function looks + for code. +``` """ LOAD_PATH doc""" - ANY +```rst +ANY -Equivalent to `Any` for dispatch purposes, but signals the -compiler to skip code generation specialization for that field + Equivalent to "Any" for dispatch purposes, but signals the + compiler to skip code generation specialization for that field +``` """ ANY doc""" - Period - +```rst +Period +``` """ Dates.Period doc""" - Year - +```rst +Year +``` """ Dates.Year doc""" - Month - +```rst +Month +``` """ Dates.Month doc""" - Week - +```rst +Week +``` """ Dates.Week doc""" - Day - +```rst +Day +``` """ Dates.Day doc""" - Hour - +```rst +Hour +``` """ Dates.Hour doc""" - Minute - +```rst +Minute +``` """ Dates.Minute doc""" - Second - +```rst +Second +``` """ Dates.Second doc""" - Millisecond +```rst +Millisecond + "Period" types represent discrete, human representations of time. +``` """ Dates.Millisecond doc""" - Instant +```rst +Instant -of time as continuous timelines starting from an epoch. + "Instant" types represent integer-based, machine representations + of time as continuous timelines starting from an epoch. +``` """ Dates.Instant doc""" - TimeType +```rst +TimeType -human representations of the machine instant. + "TimeType" types wrap "Instant" machine instances to provide + human representations of the machine instant. +``` """ Dates.TimeType doc""" - DateTime +```rst +DateTime -according to the proleptic Gregorian calendar. + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it + according to the proleptic Gregorian calendar. +``` """ Dates.DateTime doc""" - Date +```rst +Date -the proleptic Gregorian calendar. + "Date" wraps a "UTInstant{Day}" and interprets it according to + the proleptic Gregorian calendar. +``` """ Dates.Date doc""" - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime +```rst +DateTime(y[, m, d, h, mi, s, ms]) -> DateTime -Construct a DateTime type by parts. Arguments must be convertible -to `Int64`. + Construct a DateTime type by parts. Arguments must be convertible + to "Int64". +``` """ Dates.DateTime doc""" - DateTime(periods::Period...) -> DateTime +```rst +DateTime(periods::Period...) -> DateTime -Constuct a DateTime type by `Period` type parts. Arguments may be -in any order. DateTime parts not provided will default to the value -of `Dates.default(period)`. + Constuct a DateTime type by "Period" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of "Dates.default(period)". +``` """ Dates.DateTime doc""" - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime +```rst +DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime -Create a DateTime through the adjuster API. The starting point will -be constructed from the provided `y, m, d...` arguments, and will -be adjusted until `f::Function` returns true. The step size in -adjusting can be provided manually through the `step` keyword. If -returns false instead of true. `limit` provides a limit to the -max number of iterations the adjustment API will pursue before -throwing an error (in the case that `f::Function` is never -satisfied). + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided "y, m, d..." arguments, and will + be adjusted until "f::Function" returns true. The step size in + adjusting can be provided manually through the "step" keyword. If + "negate=true", then the adjusting will stop when "f::Function" + returns false instead of true. "limit" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that "f::Function" is never + satisfied). +``` """ Dates.DateTime doc""" - DateTime(dt::Date) -> DateTime +```rst +DateTime(dt::Date) -> DateTime -Converts a `Date` type to a `DateTime`. The hour, minute, -second, and millisecond parts of the new `DateTime` are assumed -to be zero. + Converts a "Date" type to a "DateTime". The hour, minute, + second, and millisecond parts of the new "DateTime" are assumed + to be zero. +``` """ Dates.DateTime doc""" - DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime - -Construct a DateTime type by parsing the `dt` date string -following the pattern given in the `format` string. The following -codes can be used for constructing format strings: -All characters not listed above are treated as delimiters between -date and time slots. So a `dt` string of +```rst +DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string + following the pattern given in the "format" string. The following + codes can be used for constructing format strings: + + +-----------------+-----------+-----------------------------------------------------------------+ + | Code | Matches | Comment | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"y\" | 1996, 96 | Returns year of 1996, 0096 | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"m\" | 1, 01 | Matches 1 or 2-digit months | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"U\" | January | Matches full month names according to the \"locale\" keyword | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"d\" | 1, 01 | Matches 1 or 2-digit days | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"H\" | 00 | Matches hours | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"M\" | 00 | Matches minutes | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"S\" | 00 | Matches seconds | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"s\" | .500 | Matches milliseconds | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"e\" | Mon, Tues | Matches abbreviated days of the week | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"E\" | Monday | Matches full name days of the week | + +-----------------+-----------+-----------------------------------------------------------------+ + | \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | + +-----------------+-----------+-----------------------------------------------------------------+ + + All characters not listed above are treated as delimiters between + date and time slots. So a "dt" string of + "1996-01-15T00:00:00.0" would have a "format" string like + "y-m-dTH:M:S.s". +``` """ Dates.DateTime doc""" - Dates.DateFormat(format::AbstractString) -> DateFormat +```rst +Dates.DateFormat(format::AbstractString) -> DateFormat -Construct a date formatting object that can be passed repeatedly -for parsing similarly formatted date strings. `format` is a -format string in the form described above (e.g. `yyyy-mm- -dd`). + Construct a date formatting object that can be passed repeatedly + for parsing similarly formatted date strings. "format" is a + format string in the form described above (e.g. ""yyyy-mm- + dd""). +``` """ Dates.Dates doc""" - DateTime(dt::AbstractString, df::DateFormat) -> DateTime +```rst +DateTime(dt::AbstractString, df::DateFormat) -> DateTime -Similar form as above for parsing a `DateTime`, but passes a -more efficient if similarly formatted date strings will be parsed -repeatedly to first create a `DateFormat` object then use this -method for parsing. + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. +``` """ Dates.DateTime doc""" - Date(y[, m, d]) -> Date +```rst +Date(y[, m, d]) -> Date -Construct a `Date` type by parts. Arguments must be convertible -to `Int64`. + Construct a "Date" type by parts. Arguments must be convertible + to "Int64". +``` """ Dates.Date doc""" - Date(period::Period...) -> Date +```rst +Date(period::Period...) -> Date -Constuct a Date type by `Period` type parts. Arguments may be in -any order. Date parts not provided will default to the value of + Constuct a Date type by "Period" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + "Dates.default(period)". +``` """ Dates.Date doc""" - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date +```rst +Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date -Create a Date through the adjuster API. The starting point will be -constructed from the provided `y, m` arguments, and will be -adjusted until `f::Function` returns true. The step size in -adjusting can be provided manually through the `step` keyword. If -returns false instead of true. `limit` provides a limit to the -max number of iterations the adjustment API will pursue before -throwing an error (given that `f::Function` is never satisfied). + Create a Date through the adjuster API. The starting point will be + constructed from the provided "y, m" arguments, and will be + adjusted until "f::Function" returns true. The step size in + adjusting can be provided manually through the "step" keyword. If + "negate=true", then the adjusting will stop when "f::Function" + returns false instead of true. "limit" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that "f::Function" is never satisfied). +``` """ Dates.Date doc""" - Date(dt::DateTime) -> Date +```rst +Date(dt::DateTime) -> Date -Converts a `DateTime` type to a `Date`. The hour, minute, -second, and millisecond parts of the `DateTime` are truncated, so -only the year, month and day parts are used in construction. + Converts a "DateTime" type to a "Date". The hour, minute, + second, and millisecond parts of the "DateTime" are truncated, so + only the year, month and day parts are used in construction. +``` """ Dates.Date doc""" - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date +```rst +Date(dt::AbstractString, format::AbstractString; locale="english") -> Date -Construct a Date type by parsing a `dt` date string following the -pattern given in the `format` string. Follows the same -conventions as `DateTime` above. + Construct a Date type by parsing a "dt" date string following the + pattern given in the "format" string. Follows the same + conventions as "DateTime" above. +``` """ Dates.Date doc""" - Date(dt::AbstractString, df::DateFormat) -> Date +```rst +Date(dt::AbstractString, df::DateFormat) -> Date -Parse a date from a date string `dt` using a `DateFormat` -object `df`. + Parse a date from a date string "dt" using a "DateFormat" + object "df". +``` """ Dates.Date doc""" - now() -> DateTime +```rst +now() -> DateTime -Returns a DateTime corresponding to the user's system time -including the system timezone locale. + Returns a DateTime corresponding to the user's system time + including the system timezone locale. +``` """ Dates.now doc""" - now(::Type{UTC}) -> DateTime +```rst +now(::Type{UTC}) -> DateTime -Returns a DateTime corresponding to the user's system time as -UTC/GMT. + Returns a DateTime corresponding to the user's system time as + UTC/GMT. +``` """ Dates.now doc""" - eps(::DateTime) -> Millisecond +```rst +eps(::DateTime) -> Millisecond +eps(::Date) -> Day -Returns `Millisecond(1)` for `DateTime` values and `Day(1)` -for `Date` values. + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" + for "Date" values. +``` """ Dates.eps doc""" - year(dt::TimeType) -> Int64 +```rst +year(dt::TimeType) -> Int64 +month(dt::TimeType) -> Int64 +week(dt::TimeType) -> Int64 +day(dt::TimeType) -> Int64 +hour(dt::TimeType) -> Int64 +minute(dt::TimeType) -> Int64 +second(dt::TimeType) -> Int64 +millisecond(dt::TimeType) -> Int64 -Return the field part of a Date or DateTime as an `Int64`. + Return the field part of a Date or DateTime as an "Int64". +``` """ Dates.year doc""" - Year(dt::TimeType) -> Year +```rst +Year(dt::TimeType) -> Year +Month(dt::TimeType) -> Month +Week(dt::TimeType) -> Week +Day(dt::TimeType) -> Day +Hour(dt::TimeType) -> Hour +Minute(dt::TimeType) -> Minute +Second(dt::TimeType) -> Second +Millisecond(dt::TimeType) -> Millisecond -Return the field part of a Date or DateTime as a `Period` type. + Return the field part of a Date or DateTime as a "Period" type. +``` """ Dates.Year doc""" - yearmonth(dt::TimeType) -> (Int64, Int64) +```rst +yearmonth(dt::TimeType) -> (Int64, Int64) -Simultaneously return the year and month parts of a Date or -DateTime. + Simultaneously return the year and month parts of a Date or + DateTime. +``` """ Dates.yearmonth doc""" - monthday(dt::TimeType) -> (Int64, Int64) +```rst +monthday(dt::TimeType) -> (Int64, Int64) -Simultaneously return the month and day parts of a Date or -DateTime. + Simultaneously return the month and day parts of a Date or + DateTime. +``` """ Dates.monthday doc""" - yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) +```rst +yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) -Simultaneously return the year, month, and day parts of a Date or -DateTime. + Simultaneously return the year, month, and day parts of a Date or + DateTime. +``` """ Dates.yearmonthday doc""" - dayname(dt::TimeType; locale="english") -> AbstractString +```rst +dayname(dt::TimeType; locale="english") -> AbstractString -Return the full day name corresponding to the day of the week of -the Date or DateTime in the given `locale`. + Return the full day name corresponding to the day of the week of + the Date or DateTime in the given "locale". +``` """ Dates.dayname doc""" - dayabbr(dt::TimeType; locale="english") -> AbstractString +```rst +dayabbr(dt::TimeType; locale="english") -> AbstractString -Return the abbreviated name corresponding to the day of the week of -the Date or DateTime in the given `locale`. + Return the abbreviated name corresponding to the day of the week of + the Date or DateTime in the given "locale". +``` """ Dates.dayabbr doc""" - dayofweek(dt::TimeType) -> Int64 +```rst +dayofweek(dt::TimeType) -> Int64 -Returns the day of the week as an `Int64` with `1 = Monday, 2 = -Tuesday, etc.`. + Returns the day of the week as an "Int64" with "1 = Monday, 2 = + Tuesday, etc.". +``` """ Dates.dayofweek doc""" - dayofweekofmonth(dt::TimeType) -> Int +```rst +dayofweekofmonth(dt::TimeType) -> Int -For the day of week of `dt`, returns which number it is in -etc.` In the range 1:5. + For the day of week of "dt", returns which number it is in + "dt"'s month. So if the day of the week of "dt" is Monday, then + "1 = First Monday of the month, 2 = Second Monday of the month, + etc." In the range 1:5. +``` """ Dates.dayofweekofmonth doc""" - daysofweekinmonth(dt::TimeType) -> Int +```rst +daysofweekinmonth(dt::TimeType) -> Int -For the day of week of `dt`, returns the total number of that day -of the week in `dt`'s month. Returns 4 or 5. Useful in temporal -expressions for specifying the last day of a week in a month by -including `dayofweekofmonth(dt) == daysofweekinmonth(dt)` in the -adjuster function. + For the day of week of "dt", returns the total number of that day + of the week in "dt"'s month. Returns 4 or 5. Useful in temporal + expressions for specifying the last day of a week in a month by + including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the + adjuster function. +``` """ Dates.daysofweekinmonth doc""" - monthname(dt::TimeType; locale="english") -> AbstractString +```rst +monthname(dt::TimeType; locale="english") -> AbstractString -Return the full name of the month of the Date or DateTime in the -given `locale`. + Return the full name of the month of the Date or DateTime in the + given "locale". +``` """ Dates.monthname doc""" - monthabbr(dt::TimeType; locale="english") -> AbstractString +```rst +monthabbr(dt::TimeType; locale="english") -> AbstractString -Return the abbreviated month name of the Date or DateTime in the -given `locale`. + Return the abbreviated month name of the Date or DateTime in the + given "locale". +``` """ Dates.monthabbr doc""" - daysinmonth(dt::TimeType) -> Int +```rst +daysinmonth(dt::TimeType) -> Int -Returns the number of days in the month of `dt`. Value will be -28, 29, 30, or 31. + Returns the number of days in the month of "dt". Value will be + 28, 29, 30, or 31. +``` """ Dates.daysinmonth doc""" - isleapyear(dt::TimeType) -> Bool +```rst +isleapyear(dt::TimeType) -> Bool -Returns true if the year of `dt` is a leap year. + Returns true if the year of "dt" is a leap year. +``` """ Dates.isleapyear doc""" - dayofyear(dt::TimeType) -> Int +```rst +dayofyear(dt::TimeType) -> Int -Returns the day of the year for `dt` with January 1st being day -1. + Returns the day of the year for "dt" with January 1st being day + 1. +``` """ Dates.dayofyear doc""" - daysinyear(dt::TimeType) -> Int +```rst +daysinyear(dt::TimeType) -> Int -Returns 366 if the year of `dt` is a leap year, otherwise returns -365. + Returns 366 if the year of "dt" is a leap year, otherwise returns + 365. +``` """ Dates.daysinyear doc""" - quarterofyear(dt::TimeType) -> Int +```rst +quarterofyear(dt::TimeType) -> Int -Returns the quarter that `dt` resides in. Range of value is 1:4. + Returns the quarter that "dt" resides in. Range of value is 1:4. +``` """ Dates.quarterofyear doc""" - dayofquarter(dt::TimeType) -> Int +```rst +dayofquarter(dt::TimeType) -> Int -Returns the day of the current quarter of `dt`. Range of value is -1:92. + Returns the day of the current quarter of "dt". Range of value is + 1:92. +``` """ Dates.dayofquarter doc""" - trunc(dt::TimeType, ::Type{Period}) -> TimeType +```rst +trunc(dt::TimeType, ::Type{Period}) -> TimeType -Truncates the value of `dt` according to the provided `Period` -type. E.g. if `dt` is `1996-01-01T12:30:00`, then + Truncates the value of "dt" according to the provided "Period" + type. E.g. if "dt" is "1996-01-01T12:30:00", then + "trunc(dt,Day) == 1996-01-01T00:00:00". +``` """ Dates.trunc doc""" - firstdayofweek(dt::TimeType) -> TimeType +```rst +firstdayofweek(dt::TimeType) -> TimeType -Adjusts `dt` to the Monday of its week. + Adjusts "dt" to the Monday of its week. +``` """ Dates.firstdayofweek doc""" - lastdayofweek(dt::TimeType) -> TimeType +```rst +lastdayofweek(dt::TimeType) -> TimeType -Adjusts `dt` to the Sunday of its week. + Adjusts "dt" to the Sunday of its week. +``` """ Dates.lastdayofweek doc""" - firstdayofmonth(dt::TimeType) -> TimeType +```rst +firstdayofmonth(dt::TimeType) -> TimeType -Adjusts `dt` to the first day of its month. + Adjusts "dt" to the first day of its month. +``` """ Dates.firstdayofmonth doc""" - lastdayofmonth(dt::TimeType) -> TimeType +```rst +lastdayofmonth(dt::TimeType) -> TimeType -Adjusts `dt` to the last day of its month. + Adjusts "dt" to the last day of its month. +``` """ Dates.lastdayofmonth doc""" - firstdayofyear(dt::TimeType) -> TimeType +```rst +firstdayofyear(dt::TimeType) -> TimeType -Adjusts `dt` to the first day of its year. + Adjusts "dt" to the first day of its year. +``` """ Dates.firstdayofyear doc""" - lastdayofyear(dt::TimeType) -> TimeType +```rst +lastdayofyear(dt::TimeType) -> TimeType -Adjusts `dt` to the last day of its year. + Adjusts "dt" to the last day of its year. +``` """ Dates.lastdayofyear doc""" - firstdayofquarter(dt::TimeType) -> TimeType +```rst +firstdayofquarter(dt::TimeType) -> TimeType -Adjusts `dt` to the first day of its quarter. + Adjusts "dt" to the first day of its quarter. +``` """ Dates.firstdayofquarter doc""" - lastdayofquarter(dt::TimeType) -> TimeType +```rst +lastdayofquarter(dt::TimeType) -> TimeType -Adjusts `dt` to the last day of its quarter. + Adjusts "dt" to the last day of its quarter. +``` """ Dates.lastdayofquarter doc""" - tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType +```rst +tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType -Adjusts `dt` to the next day of week corresponding to `dow` -with `1 = Monday, 2 = Tuesday, etc`. Setting `same=true` allows -the current `dt` to be considered as the next `dow`, allowing -for no adjustment to occur. + Adjusts "dt" to the next day of week corresponding to "dow" + with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows + the current "dt" to be considered as the next "dow", allowing + for no adjustment to occur. +``` """ Dates.tonext doc""" - toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType +```rst +toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType -Adjusts `dt` to the previous day of week corresponding to `dow` -with `1 = Monday, 2 = Tuesday, etc`. Setting `same=true` allows -the current `dt` to be considered as the previous `dow`, -allowing for no adjustment to occur. + Adjusts "dt" to the previous day of week corresponding to "dow" + with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows + the current "dt" to be considered as the previous "dow", + allowing for no adjustment to occur. +``` """ Dates.toprev doc""" - tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType +```rst +tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType -Adjusts `dt` to the first `dow` of its month. Alternatively, + Adjusts "dt" to the first "dow" of its month. Alternatively, + "of=Year" will adjust to the first "dow" of the year. +``` """ Dates.tofirst doc""" - tolast(dt::TimeType, dow::Int;of=Month) -> TimeType +```rst +tolast(dt::TimeType, dow::Int;of=Month) -> TimeType -Adjusts `dt` to the last `dow` of its month. Alternatively, + Adjusts "dt" to the last "dow" of its month. Alternatively, + "of=Year" will adjust to the last "dow" of the year. +``` """ Dates.tolast doc""" - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType +```rst +tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType -Adjusts `dt` by iterating at most `limit` iterations by -a single `TimeType` argument and return a `Bool`. `same` -allows `dt` to be considered in satisfying `func`. `negate` -will make the adjustment process terminate when `func` returns -false instead of true. + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. +``` """ Dates.tonext doc""" - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType +```rst +toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType -Adjusts `dt` by iterating at most `limit` iterations by -a single `TimeType` argument and return a `Bool`. `same` -allows `dt` to be considered in satisfying `func`. `negate` -will make the adjustment process terminate when `func` returns -false instead of true. + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. +``` """ Dates.toprev doc""" - Year(v) +```rst +Year(v) +Month(v) +Week(v) +Day(v) +Hour(v) +Minute(v) +Second(v) +Millisecond(v) -Construct a `Period` type with the given `v` value. Input must -be losslessly convertible to an `Int64`. + Construct a "Period" type with the given "v" value. Input must + be losslessly convertible to an "Int64". +``` """ Dates.Year doc""" - default(p::Period) -> Period +```rst +default(p::Period) -> Period -Returns a sensible `default` value for the input Period by -returning `one(p)` for Year, Month, and Day, and `zero(p)` for -Hour, Minute, Second, and Millisecond. + Returns a sensible "default" value for the input Period by + returning "one(p)" for Year, Month, and Day, and "zero(p)" for + Hour, Minute, Second, and Millisecond. +``` """ Dates.default doc""" - today() -> Date +```rst +today() -> Date -Returns the date portion of `now()`. + Returns the date portion of "now()". +``` """ Dates.today doc""" - unix2datetime(x) -> DateTime +```rst +unix2datetime(x) -> DateTime -Takes the number of seconds since unix epoch + Takes the number of seconds since unix epoch + "1970-01-01T00:00:00" and converts to the corresponding DateTime. +``` """ Dates.unix2datetime doc""" - datetime2unix(dt::DateTime) -> Float64 +```rst +datetime2unix(dt::DateTime) -> Float64 -Takes the given DateTime and returns the number of seconds since -the unix epoch as a `Float64`. + Takes the given DateTime and returns the number of seconds since + the unix epoch as a "Float64". +``` """ Dates.datetime2unix doc""" - julian2datetime(julian_days) -> DateTime +```rst +julian2datetime(julian_days) -> DateTime -Takes the number of Julian calendar days since epoch + Takes the number of Julian calendar days since epoch + "-4713-11-24T12:00:00" and returns the corresponding DateTime. +``` """ Dates.julian2datetime doc""" - datetime2julian(dt::DateTime) -> Float64 +```rst +datetime2julian(dt::DateTime) -> Float64 -Takes the given DateTime and returns the number of Julian calendar -days since the julian epoch as a `Float64`. + Takes the given DateTime and returns the number of Julian calendar + days since the julian epoch as a "Float64". +``` """ Dates.datetime2julian doc""" - rata2datetime(days) -> DateTime +```rst +rata2datetime(days) -> DateTime -Takes the number of Rata Die days since epoch + Takes the number of Rata Die days since epoch + "0000-12-31T00:00:00" and returns the corresponding DateTime. +``` """ Dates.rata2datetime doc""" - datetime2rata(dt::TimeType) -> Int64 +```rst +datetime2rata(dt::TimeType) -> Int64 -Returns the number of Rata Die days since epoch from the given Date -or DateTime. + Returns the number of Rata Die days since epoch from the given Date + or DateTime. +``` """ Dates.datetime2rata doc""" - pwd() -> AbstractString +```rst +pwd() -> AbstractString -Get the current working directory. + Get the current working directory. +``` """ pwd doc""" - cd(dir::AbstractString) +```rst +cd(dir::AbstractString) -Set the current working directory. + Set the current working directory. +``` """ cd doc""" - cd(f[, dir]) +```rst +cd(f[, dir]) -Temporarily changes the current working directory (HOME if not -specified) and applies function f before returning. + Temporarily changes the current working directory (HOME if not + specified) and applies function f before returning. +``` """ cd doc""" - readdir([dir]) -> Vector{ByteString} +```rst +readdir([dir]) -> Vector{ByteString} -Returns the files and directories in the directory *dir* (or the -current working directory if not given). + Returns the files and directories in the directory *dir* (or the + current working directory if not given). +``` """ readdir doc""" - mkdir(path[, mode]) +```rst +mkdir(path[, mode]) -Make a new directory with name `path` and permissions `mode`. -mask. + Make a new directory with name "path" and permissions "mode". + "mode" defaults to 0o777, modified by the current file creation + mask. +``` """ mkdir doc""" - mkpath(path[, mode]) +```rst +mkpath(path[, mode]) -Create all directories in the given `path`, with permissions -creation mask. + Create all directories in the given "path", with permissions + "mode". "mode" defaults to 0o777, modified by the current file + creation mask. +``` """ mkpath doc""" - symlink(target, link) +```rst +symlink(target, link) -Creates a symbolic link to `target` with the name `link`. -Note: This function raises an error under operating systems that + Creates a symbolic link to "target" with the name "link". + + Note: This function raises an error under operating systems that + do not support soft symbolic links, such as Windows XP. +``` """ symlink doc""" - readlink(path) -> AbstractString +```rst +readlink(path) -> AbstractString -Returns the value of a symbolic link `path`. + Returns the value of a symbolic link "path". +``` """ readlink doc""" - chmod(path, mode) +```rst +chmod(path, mode) -Change the permissions mode of `path` to `mode`. Only integer + Change the permissions mode of "path" to "mode". Only integer + "mode"s (e.g. 0o777) are currently supported. +``` """ chmod doc""" - stat(file) - -Returns a structure whose fields contain information about the -file. The fields of the structure are: +```rst +stat(file) + + Returns a structure whose fields contain information about the + file. The fields of the structure are: + + +-----------+------------------------------------------------------------------------+ + | size | The size (in bytes) of the file | + +-----------+------------------------------------------------------------------------+ + | device | ID of the device that contains the file | + +-----------+------------------------------------------------------------------------+ + | inode | The inode number of the file | + +-----------+------------------------------------------------------------------------+ + | mode | The protection mode of the file | + +-----------+------------------------------------------------------------------------+ + | nlink | The number of hard links to the file | + +-----------+------------------------------------------------------------------------+ + | uid | The user id of the owner of the file | + +-----------+------------------------------------------------------------------------+ + | gid | The group id of the file owner | + +-----------+------------------------------------------------------------------------+ + | rdev | If this file refers to a device, the ID of the device it refers to | + +-----------+------------------------------------------------------------------------+ + | blksize | The file-system preferred block size for the file | + +-----------+------------------------------------------------------------------------+ + | blocks | The number of such blocks allocated | + +-----------+------------------------------------------------------------------------+ + | mtime | Unix timestamp of when the file was last modified | + +-----------+------------------------------------------------------------------------+ + | ctime | Unix timestamp of when the file was created | + +-----------+------------------------------------------------------------------------+ +``` """ stat doc""" - lstat(file) +```rst +lstat(file) -Like stat, but for symbolic links gets the info for the link itself -rather than the file it refers to. This function must be called on -a file path rather than a file object or a file descriptor. + Like stat, but for symbolic links gets the info for the link itself + rather than the file it refers to. This function must be called on + a file path rather than a file object or a file descriptor. +``` """ lstat doc""" - ctime(file) +```rst +ctime(file) -Equivalent to stat(file).ctime + Equivalent to stat(file).ctime +``` """ ctime doc""" - mtime(file) +```rst +mtime(file) -Equivalent to stat(file).mtime + Equivalent to stat(file).mtime +``` """ mtime doc""" - filemode(file) +```rst +filemode(file) -Equivalent to stat(file).mode + Equivalent to stat(file).mode +``` """ filemode doc""" - filesize(path...) +```rst +filesize(path...) -Equivalent to stat(file).size + Equivalent to stat(file).size +``` """ filesize doc""" - uperm(file) +```rst +uperm(file) + + Gets the permissions of the owner of the file as a bitfield of -Gets the permissions of the owner of the file as a bitfield of -For allowed arguments, see `stat`. + +------+-----------------------+ + | 01 | Execute Permission | + +------+-----------------------+ + | 02 | Write Permission | + +------+-----------------------+ + | 04 | Read Permission | + +------+-----------------------+ + + For allowed arguments, see "stat". +``` """ uperm doc""" - gperm(file) +```rst +gperm(file) -Like uperm but gets the permissions of the group owning the file + Like uperm but gets the permissions of the group owning the file +``` """ gperm doc""" - operm(file) +```rst +operm(file) -Like uperm but gets the permissions for people who neither own the -file nor are a member of the group owning the file + Like uperm but gets the permissions for people who neither own the + file nor are a member of the group owning the file +``` """ operm doc""" - cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) +```rst +cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + + Copy the file, link, or directory from *src* to *dest*. + "remove_destination=true" will first remove an existing *dst*. -Copy the file, link, or directory from *src* to *dest*. -If *follow_symlinks=false*, and src is a symbolic link, dst will be -created as a symbolic link. If *follow_symlinks=true* and src is a -symbolic link, dst will be a copy of the file or directory *src* -refers to. + If *follow_symlinks=false*, and src is a symbolic link, dst will be + created as a symbolic link. If *follow_symlinks=true* and src is a + symbolic link, dst will be a copy of the file or directory *src* + refers to. +``` """ cp doc""" - download(url[, localfile]) +```rst +download(url[, localfile]) -Download a file from the given url, optionally renaming it to the -given local file name. Note that this function relies on the -availability of external tools such as `curl`, `wget` or -production use or situations in which more options are need, please -use a package that provides the desired functionality instead. + Download a file from the given url, optionally renaming it to the + given local file name. Note that this function relies on the + availability of external tools such as "curl", "wget" or + "fetch" to download the file and is provided for convenience. For + production use or situations in which more options are need, please + use a package that provides the desired functionality instead. +``` """ download doc""" - mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) +```rst +mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) -Move the file, link, or directory from *src* to *dest*. -`remove_destination=true` will first remove an existing *dst*. + Move the file, link, or directory from *src* to *dest*. + "remove_destination=true" will first remove an existing *dst*. +``` """ mv doc""" - rm(path::AbstractString; recursive=false) +```rst +rm(path::AbstractString; recursive=false) -Delete the file, link, or empty directory at the given path. If -contents are removed recursively. + Delete the file, link, or empty directory at the given path. If + "recursive=true" is passed and the path is a directory, then all + contents are removed recursively. +``` """ rm doc""" - touch(path::AbstractString) +```rst +touch(path::AbstractString) -Update the last-modified timestamp on a file to the current time. + Update the last-modified timestamp on a file to the current time. +``` """ touch doc""" - tempname() +```rst +tempname() -Generate a unique temporary file path. + Generate a unique temporary file path. +``` """ tempname doc""" - tempdir() +```rst +tempdir() -Obtain the path of a temporary directory (possibly shared with -other processes). + Obtain the path of a temporary directory (possibly shared with + other processes). +``` """ tempdir doc""" - mktemp([parent=tempdir()]) +```rst +mktemp([parent=tempdir()]) -Returns `(path, io)`, where `path` is the path of a new -temporary file in `parent` and `io` is an open file object for -this path. + Returns "(path, io)", where "path" is the path of a new + temporary file in "parent" and "io" is an open file object for + this path. +``` """ mktemp doc""" - mktempdir([parent=tempdir()]) +```rst +mktempdir([parent=tempdir()]) -Create a temporary directory in the `parent` directory and return -its path. + Create a temporary directory in the "parent" directory and return + its path. +``` """ mktempdir doc""" - isblockdev(path) -> Bool +```rst +isblockdev(path) -> Bool -Returns `true` if `path` is a block device, `false` -otherwise. + Returns "true" if "path" is a block device, "false" + otherwise. +``` """ isblockdev doc""" - ischardev(path) -> Bool +```rst +ischardev(path) -> Bool -Returns `true` if `path` is a character device, `false` -otherwise. + Returns "true" if "path" is a character device, "false" + otherwise. +``` """ ischardev doc""" - isdir(path) -> Bool +```rst +isdir(path) -> Bool -Returns `true` if `path` is a directory, `false` otherwise. + Returns "true" if "path" is a directory, "false" otherwise. +``` """ isdir doc""" - isexecutable(path) -> Bool +```rst +isexecutable(path) -> Bool -Returns `true` if the current user has permission to execute + Returns "true" if the current user has permission to execute + "path", "false" otherwise. +``` """ isexecutable doc""" - isfifo(path) -> Bool +```rst +isfifo(path) -> Bool -Returns `true` if `path` is a FIFO, `false` otherwise. + Returns "true" if "path" is a FIFO, "false" otherwise. +``` """ isfifo doc""" - isfile(path) -> Bool +```rst +isfile(path) -> Bool -Returns `true` if `path` is a regular file, `false` -otherwise. + Returns "true" if "path" is a regular file, "false" + otherwise. +``` """ isfile doc""" - islink(path) -> Bool +```rst +islink(path) -> Bool -Returns `true` if `path` is a symbolic link, `false` -otherwise. + Returns "true" if "path" is a symbolic link, "false" + otherwise. +``` """ islink doc""" - ismount(path) -> Bool +```rst +ismount(path) -> Bool -Returns `true` if `path` is a mount point, `false` otherwise. + Returns "true" if "path" is a mount point, "false" otherwise. +``` """ ismount doc""" - ispath(path) -> Bool +```rst +ispath(path) -> Bool -Returns `true` if `path` is a valid filesystem path, `false` -otherwise. + Returns "true" if "path" is a valid filesystem path, "false" + otherwise. +``` """ ispath doc""" - isreadable(path) -> Bool +```rst +isreadable(path) -> Bool -Returns `true` if the current user has permission to read + Returns "true" if the current user has permission to read + "path", "false" otherwise. +``` """ isreadable doc""" - issetgid(path) -> Bool +```rst +issetgid(path) -> Bool -Returns `true` if `path` has the setgid flag set, `false` -otherwise. + Returns "true" if "path" has the setgid flag set, "false" + otherwise. +``` """ issetgid doc""" - issetuid(path) -> Bool +```rst +issetuid(path) -> Bool -Returns `true` if `path` has the setuid flag set, `false` -otherwise. + Returns "true" if "path" has the setuid flag set, "false" + otherwise. +``` """ issetuid doc""" - issocket(path) -> Bool +```rst +issocket(path) -> Bool -Returns `true` if `path` is a socket, `false` otherwise. + Returns "true" if "path" is a socket, "false" otherwise. +``` """ issocket doc""" - issticky(path) -> Bool +```rst +issticky(path) -> Bool -Returns `true` if `path` has the sticky bit set, `false` -otherwise. + Returns "true" if "path" has the sticky bit set, "false" + otherwise. +``` """ issticky doc""" - iswritable(path) -> Bool +```rst +iswritable(path) -> Bool -Returns `true` if the current user has permission to write to + Returns "true" if the current user has permission to write to + "path", "false" otherwise. +``` """ iswritable doc""" - homedir() -> AbstractString +```rst +homedir() -> AbstractString -Return the current user's home directory. + Return the current user's home directory. +``` """ homedir doc""" - dirname(path::AbstractString) -> AbstractString +```rst +dirname(path::AbstractString) -> AbstractString -Get the directory part of a path. + Get the directory part of a path. +``` """ dirname doc""" - basename(path::AbstractString) -> AbstractString +```rst +basename(path::AbstractString) -> AbstractString -Get the file name part of a path. + Get the file name part of a path. +``` """ basename doc""" - @__FILE__() -> AbstractString +```rst +@__FILE__() -> AbstractString -name of the script being run. Returns `nothing` if run from a -REPL or an empty string if evaluated by `julia -e `. + "@__FILE__" expands to a string with the absolute path and file + name of the script being run. Returns "nothing" if run from a + REPL or an empty string if evaluated by "julia -e ". +``` """ @__FILE__ doc""" - isabspath(path::AbstractString) -> Bool +```rst +isabspath(path::AbstractString) -> Bool -Determines whether a path is absolute (begins at the root -directory). + Determines whether a path is absolute (begins at the root + directory). +``` """ isabspath doc""" - isdirpath(path::AbstractString) -> Bool +```rst +isdirpath(path::AbstractString) -> Bool -Determines whether a path refers to a directory (for example, ends -with a path separator). + Determines whether a path refers to a directory (for example, ends + with a path separator). +``` """ isdirpath doc""" - joinpath(parts...) -> AbstractString +```rst +joinpath(parts...) -> AbstractString -Join path components into a full path. If some argument is an -absolute path, then prior components are dropped. + Join path components into a full path. If some argument is an + absolute path, then prior components are dropped. +``` """ joinpath doc""" - abspath(path::AbstractString) -> AbstractString +```rst +abspath(path::AbstractString) -> AbstractString -Convert a path to an absolute path by adding the current directory -if necessary. + Convert a path to an absolute path by adding the current directory + if necessary. +``` """ abspath doc""" - normpath(path::AbstractString) -> AbstractString +```rst +normpath(path::AbstractString) -> AbstractString -Normalize a path, removing `.` and `..` entries. + Normalize a path, removing "." and ".." entries. +``` """ normpath doc""" - realpath(path::AbstractString) -> AbstractString +```rst +realpath(path::AbstractString) -> AbstractString -Canonicalize a path by expanding symbolic links and removing `.` -and `..` entries. + Canonicalize a path by expanding symbolic links and removing "." + and ".." entries. +``` """ realpath doc""" - relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString +```rst +relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString -Return a relative filepath to path either from the current -directory or from an optional start directory. This is a path -computation: the filesystem is not accessed to confirm the -existence or nature of path or startpath. + Return a relative filepath to path either from the current + directory or from an optional start directory. This is a path + computation: the filesystem is not accessed to confirm the + existence or nature of path or startpath. +``` """ relpath doc""" - expanduser(path::AbstractString) -> AbstractString +```rst +expanduser(path::AbstractString) -> AbstractString -On Unix systems, replace a tilde character at the start of a path -with the current user's home directory. + On Unix systems, replace a tilde character at the start of a path + with the current user's home directory. +``` """ expanduser doc""" - splitdir(path::AbstractString) -> (AbstractString, AbstractString) +```rst +splitdir(path::AbstractString) -> (AbstractString, AbstractString) -Split a path into a tuple of the directory name and file name. + Split a path into a tuple of the directory name and file name. +``` """ splitdir doc""" - splitdrive(path::AbstractString) -> (AbstractString, AbstractString) +```rst +splitdrive(path::AbstractString) -> (AbstractString, AbstractString) -On Windows, split a path into the drive letter part and the path -part. On Unix systems, the first component is always the empty -string. + On Windows, split a path into the drive letter part and the path + part. On Unix systems, the first component is always the empty + string. +``` """ splitdrive doc""" - splitext(path::AbstractString) -> (AbstractString, AbstractString) +```rst +splitext(path::AbstractString) -> (AbstractString, AbstractString) -If the last component of a path contains a dot, split the path into -everything before the dot and everything including and after the -dot. Otherwise, return a tuple of the argument unmodified and the -empty string. + If the last component of a path contains a dot, split the path into + everything before the dot and everything including and after the + dot. Otherwise, return a tuple of the argument unmodified and the + empty string. +``` """ splitext doc""" - open(file_name[, read, write, create, truncate, append]) -> IOStream +```rst +open(file_name[, read, write, create, truncate, append]) -> IOStream -Open a file in a mode specified by five boolean arguments. The -default is to open files for reading only. Returns a stream for -accessing the file. + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. +``` """ open doc""" - open(file_name[, mode]) -> IOStream - -Alternate syntax for open, where a string-based mode specifier is -used instead of the five booleans. The values of `mode` -correspond to those from `fopen(3)` or Perl `open`, and are -equivalent to setting the following boolean groups: +```rst +open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of "mode" + correspond to those from "fopen(3)" or Perl "open", and are + equivalent to setting the following boolean groups: + + +------+-----------------------------------+ + | r | read | + +------+-----------------------------------+ + | r+ | read, write | + +------+-----------------------------------+ + | w | write, create, truncate | + +------+-----------------------------------+ + | w+ | read, write, create, truncate | + +------+-----------------------------------+ + | a | write, create, append | + +------+-----------------------------------+ + | a+ | read, write, create, append | + +------+-----------------------------------+ +``` """ open doc""" - open(f::function, args...) +```rst +open(f::function, args...) + + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. -Apply the function `f` to the result of `open(args...)` and -close the resulting file descriptor upon completion. + **Example**: "open(readall, "file.txt")" +``` """ open doc""" - IOBuffer() -> IOBuffer +```rst +IOBuffer() -> IOBuffer -Create an in-memory I/O stream. + Create an in-memory I/O stream. +``` """ IOBuffer doc""" - IOBuffer(size::Int) +```rst +IOBuffer(size::Int) -Create a fixed size IOBuffer. The buffer will not grow dynamically. + Create a fixed size IOBuffer. The buffer will not grow dynamically. +``` """ IOBuffer doc""" - IOBuffer(string) +```rst +IOBuffer(string) -Create a read-only IOBuffer on the data underlying the given string + Create a read-only IOBuffer on the data underlying the given string +``` """ IOBuffer doc""" - IOBuffer([data][, readable, writable[, maxsize]]) +```rst +IOBuffer([data][, readable, writable[, maxsize]]) -Create an IOBuffer, which may optionally operate on a pre-existing -array. If the readable/writable arguments are given, they restrict -whether or not the buffer may be read from or written to -respectively. By default the buffer is readable but not writable. -The last argument optionally specifies a size beyond which the -buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. +``` """ IOBuffer doc""" - takebuf_array(b::IOBuffer) +```rst +takebuf_array(b::IOBuffer) -Obtain the contents of an `IOBuffer` as an array, without -copying. Afterwards, the IOBuffer is reset to its initial state. + Obtain the contents of an "IOBuffer" as an array, without + copying. Afterwards, the IOBuffer is reset to its initial state. +``` """ takebuf_array doc""" - takebuf_string(b::IOBuffer) +```rst +takebuf_string(b::IOBuffer) -Obtain the contents of an `IOBuffer` as a string, without -copying. Afterwards, the IOBuffer is reset to its initial state. + Obtain the contents of an "IOBuffer" as a string, without + copying. Afterwards, the IOBuffer is reset to its initial state. +``` """ takebuf_string doc""" - fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream +```rst +fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream -Create an `IOStream` object from an integer file descriptor. If -descriptor. By default, an `IOStream` is closed when it is -garbage collected. `name` allows you to associate the descriptor -with a named file. + Create an "IOStream" object from an integer file descriptor. If + "own" is true, closing this object will close the underlying + descriptor. By default, an "IOStream" is closed when it is + garbage collected. "name" allows you to associate the descriptor + with a named file. +``` """ fdio doc""" - flush(stream) +```rst +flush(stream) -Commit all currently buffered writes to the given stream. + Commit all currently buffered writes to the given stream. +``` """ flush doc""" - close(stream) +```rst +close(stream) -Close an I/O stream. Performs a `flush` first. + Close an I/O stream. Performs a "flush" first. +``` """ close doc""" - write(stream, x) +```rst +write(stream, x) -Write the canonical binary representation of a value to the given -stream. + Write the canonical binary representation of a value to the given + stream. +``` """ write doc""" - read(stream, type) +```rst +read(stream, type) -Read a value of the given type from a stream, in canonical binary -representation. + Read a value of the given type from a stream, in canonical binary + representation. +``` """ read doc""" - read(stream, type, dims) +```rst +read(stream, type, dims) -Read a series of values of the given type from a stream, in -canonical binary representation. `dims` is either a tuple or a -series of integer arguments specifying the size of `Array` to -return. + Read a series of values of the given type from a stream, in + canonical binary representation. "dims" is either a tuple or a + series of integer arguments specifying the size of "Array" to + return. +``` """ read doc""" - read!(stream, array::Array) +```rst +read!(stream, array::Array) -Read binary data from a stream, filling in the argument `array`. + Read binary data from a stream, filling in the argument "array". +``` """ read! doc""" - readbytes!(stream, b::Vector{UInt8}, nb=length(b)) +```rst +readbytes!(stream, b::Vector{UInt8}, nb=length(b)) -Read at most `nb` bytes from the stream into `b`, returning the -number of bytes read (increasing the size of `b` as needed). + Read at most "nb" bytes from the stream into "b", returning the + number of bytes read (increasing the size of "b" as needed). +``` """ readbytes! doc""" - readbytes(stream, nb=typemax(Int)) +```rst +readbytes(stream, nb=typemax(Int)) -Read at most `nb` bytes from the stream, returning a + Read at most "nb" bytes from the stream, returning a + "Vector{UInt8}" of the bytes read. +``` """ readbytes doc""" - position(s) +```rst +position(s) -Get the current position of a stream. + Get the current position of a stream. +``` """ position doc""" - seek(s, pos) +```rst +seek(s, pos) -Seek a stream to the given position. + Seek a stream to the given position. +``` """ seek doc""" - seekstart(s) +```rst +seekstart(s) -Seek a stream to its beginning. + Seek a stream to its beginning. +``` """ seekstart doc""" - seekend(s) +```rst +seekend(s) -Seek a stream to its end. + Seek a stream to its end. +``` """ seekend doc""" - skip(s, offset) +```rst +skip(s, offset) -Seek a stream relative to the current position. + Seek a stream relative to the current position. +``` """ skip doc""" - mark(s) +```rst +mark(s) -Add a mark at the current position of stream `s`. Returns the -marked position. -See also `unmark()`, `reset()`, `ismarked()` + Add a mark at the current position of stream "s". Returns the + marked position. + + See also "unmark()", "reset()", "ismarked()" +``` """ mark doc""" - unmark(s) +```rst +unmark(s) + + Remove a mark from stream "s". Returns "true" if the stream was + marked, "false" otherwise. -Remove a mark from stream `s`. Returns `true` if the stream was -marked, `false` otherwise. -See also `mark()`, `reset()`, `ismarked()` + See also "mark()", "reset()", "ismarked()" +``` """ unmark doc""" - reset(s) +```rst +reset(s) + + Reset a stream "s" to a previously marked position, and remove + the mark. Returns the previously marked position. Throws an error + if the stream is not marked. -Reset a stream `s` to a previously marked position, and remove -the mark. Returns the previously marked position. Throws an error -if the stream is not marked. -See also `mark()`, `unmark()`, `ismarked()` + See also "mark()", "unmark()", "ismarked()" +``` """ reset doc""" - ismarked(s) +```rst +ismarked(s) -Returns true if stream `s` is marked. -See also `mark()`, `unmark()`, `reset()` + Returns true if stream "s" is marked. + + See also "mark()", "unmark()", "reset()" +``` """ ismarked doc""" - eof(stream) -> Bool +```rst +eof(stream) -> Bool -Tests whether an I/O stream is at end-of-file. If the stream is not -yet exhausted, this function will block to wait for more data if -necessary, and then return `false`. Therefore it is always safe -to read one byte after seeing `eof` return `false`. `eof` -will return `false` as long as buffered data is still available, -even if the remote end of a connection is closed. + Tests whether an I/O stream is at end-of-file. If the stream is not + yet exhausted, this function will block to wait for more data if + necessary, and then return "false". Therefore it is always safe + to read one byte after seeing "eof" return "false". "eof" + will return "false" as long as buffered data is still available, + even if the remote end of a connection is closed. +``` """ eof doc""" - isreadonly(stream) -> Bool +```rst +isreadonly(stream) -> Bool -Determine whether a stream is read-only. + Determine whether a stream is read-only. +``` """ isreadonly doc""" - isopen(stream) -> Bool +```rst +isopen(stream) -> Bool -Determine whether a stream is open (i.e. has not been closed yet). -If the connection has been closed remotely (in case of e.g. a -socket), `isopen` will return `false` even though buffered data -may still be available. Use `eof` to check if necessary. + Determine whether a stream is open (i.e. has not been closed yet). + If the connection has been closed remotely (in case of e.g. a + socket), "isopen" will return "false" even though buffered data + may still be available. Use "eof" to check if necessary. +``` """ isopen doc""" - serialize(stream, value) +```rst +serialize(stream, value) -Write an arbitrary value to a stream in an opaque format, such that -it can be read back by `deserialize`. The read-back value will be -as identical as possible to the original. In general, this process -will not work if the reading and writing are done by different -versions of Julia, or an instance of Julia with a different system -image. + Write an arbitrary value to a stream in an opaque format, such that + it can be read back by "deserialize". The read-back value will be + as identical as possible to the original. In general, this process + will not work if the reading and writing are done by different + versions of Julia, or an instance of Julia with a different system + image. +``` """ serialize doc""" - deserialize(stream) +```rst +deserialize(stream) -Read a value written by `serialize`. + Read a value written by "serialize". +``` """ deserialize doc""" - print_escaped(io, str::AbstractString, esc::AbstractString) +```rst +print_escaped(io, str::AbstractString, esc::AbstractString) -General escaping of traditional C and Unicode escape sequences, -plus any characters in esc are also escaped (with a backslash). + General escaping of traditional C and Unicode escape sequences, + plus any characters in esc are also escaped (with a backslash). +``` """ print_escaped doc""" - print_unescaped(io, s::AbstractString) +```rst +print_unescaped(io, s::AbstractString) -General unescaping of traditional C and Unicode escape sequences. -Reverse of `print_escaped()`. + General unescaping of traditional C and Unicode escape sequences. + Reverse of "print_escaped()". +``` """ print_unescaped doc""" - print_joined(io, items, delim[, last]) +```rst +print_joined(io, items, delim[, last]) -Print elements of `items` to `io` with `delim` between them. -If `last` is specified, it is used as the final delimiter instead -of `delim`. + Print elements of "items" to "io" with "delim" between them. + If "last" is specified, it is used as the final delimiter instead + of "delim". +``` """ print_joined doc""" - print_shortest(io, x) +```rst +print_shortest(io, x) -Print the shortest possible representation, with the minimum number -of consecutive non-zero digits, of number `x`, ensuring that it -would parse to the exact same number. + Print the shortest possible representation, with the minimum number + of consecutive non-zero digits, of number "x", ensuring that it + would parse to the exact same number. +``` """ print_shortest doc""" - fd(stream) +```rst +fd(stream) -Returns the file descriptor backing the stream or file. Note that -this function only applies to synchronous *File*'s and *IOStream*'s -not to any of the asynchronous streams. + Returns the file descriptor backing the stream or file. Note that + this function only applies to synchronous *File*'s and *IOStream*'s + not to any of the asynchronous streams. +``` """ fd doc""" - redirect_stdout() +```rst +redirect_stdout() -Create a pipe to which all C and Julia level STDOUT output will be -redirected. Returns a tuple (rd,wr) representing the pipe ends. -Data written to STDOUT may now be read from the rd end of the pipe. -The wr end is given for convenience in case the old STDOUT object -was cached by the user and needs to be replaced elsewhere. + Create a pipe to which all C and Julia level STDOUT output will be + redirected. Returns a tuple (rd,wr) representing the pipe ends. + Data written to STDOUT may now be read from the rd end of the pipe. + The wr end is given for convenience in case the old STDOUT object + was cached by the user and needs to be replaced elsewhere. +``` """ redirect_stdout doc""" - redirect_stdout(stream) +```rst +redirect_stdout(stream) -Replace STDOUT by stream for all C and julia level output to -STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + Replace STDOUT by stream for all C and julia level output to + STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. +``` """ redirect_stdout doc""" - redirect_stderr([stream]) +```rst +redirect_stderr([stream]) -Like redirect_stdout, but for STDERR + Like redirect_stdout, but for STDERR +``` """ redirect_stderr doc""" - redirect_stdin([stream]) +```rst +redirect_stdin([stream]) -Like redirect_stdout, but for STDIN. Note that the order of the -return tuple is still (rd,wr), i.e. data to be read from STDIN, may -be written to wr. + Like redirect_stdout, but for STDIN. Note that the order of the + return tuple is still (rd,wr), i.e. data to be read from STDIN, may + be written to wr. +``` """ redirect_stdin doc""" - readchomp(x) +```rst +readchomp(x) -Read the entirety of x as a string but remove trailing newlines. -Equivalent to chomp(readall(x)). + Read the entirety of x as a string but remove trailing newlines. + Equivalent to chomp(readall(x)). +``` """ readchomp doc""" - truncate(file, n) +```rst +truncate(file, n) -Resize the file or buffer given by the first argument to exactly -file or buffer is grown + Resize the file or buffer given by the first argument to exactly + *n* bytes, filling previously unallocated space with '\0' if the + file or buffer is grown +``` """ truncate doc""" - skipchars(stream, predicate; linecomment::Char) +```rst +skipchars(stream, predicate; linecomment::Char) -Advance the stream until before the first character for which -isspace)` will skip all whitespace. If keyword argument -through the end of a line will also be skipped. + Advance the stream until before the first character for which + "predicate" returns false. For example "skipchars(stream, + isspace)" will skip all whitespace. If keyword argument + "linecomment" is specified, characters from that character + through the end of a line will also be skipped. +``` """ skipchars doc""" - countlines(io[, eol::Char]) +```rst +countlines(io[, eol::Char]) -Read io until the end of the stream/file and count the number of -non-empty lines. To specify a file pass the filename as the first -argument. EOL markers other than '\n' are supported by passing -them as the second argument. + Read io until the end of the stream/file and count the number of + non-empty lines. To specify a file pass the filename as the first + argument. EOL markers other than '\n' are supported by passing + them as the second argument. +``` """ countlines doc""" - PipeBuffer() +```rst +PipeBuffer() -An IOBuffer that allows reading and performs writes by appending. -Seeking and truncating are not supported. See IOBuffer for the -available constructors. + An IOBuffer that allows reading and performs writes by appending. + Seeking and truncating are not supported. See IOBuffer for the + available constructors. +``` """ PipeBuffer doc""" - PipeBuffer(data::Vector{UInt8}[, maxsize]) +```rst +PipeBuffer(data::Vector{UInt8}[, maxsize]) -Create a PipeBuffer to operate on a data vector, optionally -specifying a size beyond which the underlying Array may not be -grown. + Create a PipeBuffer to operate on a data vector, optionally + specifying a size beyond which the underlying Array may not be + grown. +``` """ PipeBuffer doc""" - readavailable(stream) +```rst +readavailable(stream) -Read all available data on the stream, blocking the task only if no -data is available. The result is a `Vector{UInt8,1}`. + Read all available data on the stream, blocking the task only if no + data is available. The result is a "Vector{UInt8,1}". +``` """ readavailable doc""" - show(x) +```rst +show(x) -Write an informative text representation of a value to the current -output stream. New types should overload `show(io, x)` where the -first argument is a stream. The representation used by `show` -generally includes Julia-specific formatting and type information. + Write an informative text representation of a value to the current + output stream. New types should overload "show(io, x)" where the + first argument is a stream. The representation used by "show" + generally includes Julia-specific formatting and type information. +``` """ show doc""" - showcompact(x) +```rst +showcompact(x) -Show a more compact representation of a value. This is used for -printing array elements. If a new type has a different compact -representation, it should overload `showcompact(io, x)` where the -first argument is a stream. + Show a more compact representation of a value. This is used for + printing array elements. If a new type has a different compact + representation, it should overload "showcompact(io, x)" where the + first argument is a stream. +``` """ showcompact doc""" - showall(x) +```rst +showall(x) -Similar to `show`, except shows all elements of arrays. + Similar to "show", except shows all elements of arrays. +``` """ showall doc""" - summary(x) +```rst +summary(x) -Return a string giving a brief description of a value. By default -returns `string(typeof(x))`. For arrays, returns strings like + Return a string giving a brief description of a value. By default + returns "string(typeof(x))". For arrays, returns strings like + "2x2 Float64 Array". +``` """ summary doc""" - print(x) +```rst +print(x) -Write (to the default output stream) a canonical (un-decorated) -text representation of a value if there is one, otherwise call -formatting and tries to avoid Julia-specific details. + Write (to the default output stream) a canonical (un-decorated) + text representation of a value if there is one, otherwise call + "show". The representation used by "print" includes minimal + formatting and tries to avoid Julia-specific details. +``` """ print doc""" - println(x) +```rst +println(x) -Print (using `print()`) `x` followed by a newline. + Print (using "print()") "x" followed by a newline. +``` """ println doc""" - print_with_color(color::Symbol[, io], strings...) +```rst +print_with_color(color::Symbol[, io], strings...) -Print strings in a color specified as a symbol, for example + Print strings in a color specified as a symbol, for example + ":red" or ":blue". +``` """ print_with_color doc""" - info(msg) +```rst +info(msg) -Display an informational message. + Display an informational message. +``` """ info doc""" - warn(msg) +```rst +warn(msg) -Display a warning. + Display a warning. +``` """ warn doc""" - @printf([io::IOStream], "%Fmt", args...) +```rst +@printf([io::IOStream], "%Fmt", args...) -Print arg(s) using C `printf()` style format specification -string. Optionally, an IOStream may be passed as the first argument -to redirect output. + Print arg(s) using C "printf()" style format specification + string. Optionally, an IOStream may be passed as the first argument + to redirect output. +``` """ @printf doc""" - @sprintf("%Fmt", args...) +```rst +@sprintf("%Fmt", args...) -Return `@printf` formatted output as string. + Return "@printf" formatted output as string. +``` """ @sprintf doc""" - sprint(f::Function, args...) +```rst +sprint(f::Function, args...) -Call the given function with an I/O stream and the supplied extra -arguments. Everything written to this I/O stream is returned as a -string. + Call the given function with an I/O stream and the supplied extra + arguments. Everything written to this I/O stream is returned as a + string. +``` """ sprint doc""" - showerror(io, e) +```rst +showerror(io, e) -Show a descriptive representation of an exception object. + Show a descriptive representation of an exception object. +``` """ showerror doc""" - dump(x) +```rst +dump(x) -Show all user-visible structure of a value. + Show all user-visible structure of a value. +``` """ dump doc""" - xdump(x) +```rst +xdump(x) -Show all structure of a value, including all fields of objects. + Show all structure of a value, including all fields of objects. +``` """ xdump doc""" - readall(stream::IO) +```rst +readall(stream::IO) -Read the entire contents of an I/O stream as a string. + Read the entire contents of an I/O stream as a string. +``` """ readall doc""" - readall(filename::AbstractString) +```rst +readall(filename::AbstractString) -Open `filename`, read the entire contents as a string, then close -the file. Equivalent to `open(readall, filename)`. + Open "filename", read the entire contents as a string, then close + the file. Equivalent to "open(readall, filename)". +``` """ readall doc""" - readline(stream=STDIN) +```rst +readline(stream=STDIN) -Read a single line of text, including a trailing newline character + Read a single line of text, including a trailing newline character + (if one is reached before the end of the input), from the given + "stream" (defaults to "STDIN"), +``` """ readline doc""" - readuntil(stream, delim) +```rst +readuntil(stream, delim) -Read a string, up to and including the given delimiter byte. + Read a string, up to and including the given delimiter byte. +``` """ readuntil doc""" - readlines(stream) +```rst +readlines(stream) -Read all lines as an array. + Read all lines as an array. +``` """ readlines doc""" - eachline(stream) +```rst +eachline(stream) -Create an iterable object that will yield each line from a stream. + Create an iterable object that will yield each line from a stream. +``` """ eachline doc""" - readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - -Read a matrix from the source where each line (separated by -delimeter. The source can be a text file, stream or byte array. -Memory mapped files can be used by passing the byte array -representation of the mapped segment as source. -If `T` is a numeric type, the result is an array of that type, -with any non-numeric elements as `NaN` for floating-point types, -or zero. Other useful values of `T` include `ASCIIString`, -If `header` is `true`, the first row of data will be read as -header and the tuple `(data_cells, header_cells)` is returned -instead of only `data_cells`. -Specifying `skipstart` will ignore the corresponding number of -initial lines from the input. -If `skipblanks` is `true`, blank lines in the input will be -ignored. -If `use_mmap` is `true`, the file specified by `source` is -memory mapped for potential speedups. Default is `true` except on -Windows. On Windows, you may want to specify `true` if the file -is large, and is only read once and not written to. -If `ignore_invalid_chars` is `true`, bytes in `source` with -invalid character encoding will be ignored. Otherwise an error is -thrown indicating the offending character position. -If `quotes` is `true`, column enclosed within double-quote `"` -characters are allowed to contain new lines and column delimiters. -Double-quote characters within a quoted field must be escaped with -another double-quote. -Specifying `dims` as a tuple of the expected rows and columns -If `comments` is `true`, lines beginning with `comment_char` -and text following `comment_char` in any line are ignored. +```rst +readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + "eol") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, + with any non-numeric elements as "NaN" for floating-point types, + or zero. Other useful values of "T" include "ASCIIString", + "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as + header and the tuple "(data_cells, header_cells)" is returned + instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of + initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be + ignored. + + If "use_mmap" is "true", the file specified by "source" is + memory mapped for potential speedups. Default is "true" except on + Windows. On Windows, you may want to specify "true" if the file + is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" + and text following "comment_char" in any line are ignored. +``` """ readdlm doc""" - readdlm(source, delim::Char, eol::Char; options...) +```rst +readdlm(source, delim::Char, eol::Char; options...) -If all data is numeric, the result will be a numeric array. If some -elements cannot be parsed as numbers, a cell array of numbers and -strings is returned. + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. +``` """ readdlm doc""" - readdlm(source, delim::Char, T::Type; options...) +```rst +readdlm(source, delim::Char, T::Type; options...) -The end of line delimiter is taken as `\n`. + The end of line delimiter is taken as "\n". +``` """ readdlm doc""" - readdlm(source, delim::Char; options...) +```rst +readdlm(source, delim::Char; options...) -The end of line delimiter is taken as `\n`. If all data is -numeric, the result will be a numeric array. If some elements -cannot be parsed as numbers, a cell array of numbers and strings is -returned. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. +``` """ readdlm doc""" - readdlm(source, T::Type; options...) +```rst +readdlm(source, T::Type; options...) -The columns are assumed to be separated by one or more whitespaces. -The end of line delimiter is taken as `\n`. + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". +``` """ readdlm doc""" - readdlm(source; options...) +```rst +readdlm(source; options...) -The columns are assumed to be separated by one or more whitespaces. -The end of line delimiter is taken as `\n`. If all data is -numeric, the result will be a numeric array. If some elements -cannot be parsed as numbers, a cell array of numbers and strings is -returned. + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. +``` """ readdlm doc""" - writedlm(f, A, delim='\t') +```rst +writedlm(f, A, delim='\t') + + Write "A" (a vector, matrix or an iterable collection of iterable + rows) as text to "f" (either a filename string or an "IO" + stream) using the given delimeter "delim" (which defaults to tab, + but can be any printable Julia object, typically a "Char" or + "AbstractString"). -Write `A` (a vector, matrix or an iterable collection of iterable -rows) as text to `f` (either a filename string or an `IO` -stream) using the given delimeter `delim` (which defaults to tab, -but can be any printable Julia object, typically a `Char` or -For example, two vectors `x` and `y` of the same length can be -written as two columns of tab-delimited text to `f` by either + For example, two vectors "x" and "y" of the same length can be + written as two columns of tab-delimited text to "f" by either + "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". +``` """ writedlm doc""" - readcsv(source, [T::Type]; options...) +```rst +readcsv(source, [T::Type]; options...) -Equivalent to `readdlm` with `delim` set to comma. + Equivalent to "readdlm" with "delim" set to comma. +``` """ readcsv doc""" - writecsv(filename, A) +```rst +writecsv(filename, A) -Equivalent to `writedlm` with `delim` set to comma. + Equivalent to "writedlm" with "delim" set to comma. +``` """ writecsv doc""" - Base64EncodePipe(ostream) +```rst +Base64EncodePipe(ostream) -Returns a new write-only I/O stream, which converts any bytes -written to it into base64-encoded ASCII bytes written to -necessary to complete the encoding (but does not close + Returns a new write-only I/O stream, which converts any bytes + written to it into base64-encoded ASCII bytes written to + "ostream". Calling "close" on the "Base64Pipe" stream is + necessary to complete the encoding (but does not close + "ostream"). +``` """ Base64EncodePipe doc""" - Base64DecodePipe(istream) +```rst +Base64DecodePipe(istream) -Returns a new read-only I/O stream, which decodes base64-encoded -data read from `istream`. + Returns a new read-only I/O stream, which decodes base64-encoded + data read from "istream". +``` """ Base64DecodePipe doc""" - base64encode(writefunc, args...) +```rst +base64encode(writefunc, args...) +base64encode(args...) -Given a `write`-like function `writefunc`, which takes an I/O -stream as its first argument, `base64(writefunc, args...)` calls -returns the string. `base64(args...)` is equivalent to -using the standard `write` functions and returns the -base64-encoded string. + Given a "write"-like function "writefunc", which takes an I/O + stream as its first argument, "base64(writefunc, args...)" calls + "writefunc" to write "args..." to a base64-encoded string, and + returns the string. "base64(args...)" is equivalent to + "base64(write, args...)": it converts its arguments into bytes + using the standard "write" functions and returns the + base64-encoded string. +``` """ base64encode doc""" - base64decode(string) +```rst +base64decode(string) -Decodes the base64-encoded `string` and returns a `Vector{UInt8}` of -the decoded bytes. + Decodes the base64-encoded "string" and returns a + "Vector{UInt8}" of the decoded bytes. +``` """ base64decode doc""" - display(x) - -Display `x` using the topmost applicable display in the display -stack, typically using the richest supported multimedia output for -display `d` only, throwing a `MethodError` if `d` cannot -display objects of this type. -There are also two variants with a `mime` argument (a MIME type -string, such as `image/png`), which attempt to display `x` -using the requested MIME type *only*, throwing a `MethodError` if -this type is not supported by either the display(s) or by `x`. -With these variants, one can also supply the `raw` data in the -requested MIME type by passing `x::AbstractString` (for MIME -types with text-based storage, such as text/html or -application/postscript) or `x::Vector{UInt8}` (for binary MIME -types). +```rst +display(x) +display(d::Display, x) +display(mime, x) +display(d::Display, mime, x) + + Display "x" using the topmost applicable display in the display + stack, typically using the richest supported multimedia output for + "x", with plain-text "STDOUT" output as a fallback. The + "display(d, x)" variant attempts to display "x" on the given + display "d" only, throwing a "MethodError" if "d" cannot + display objects of this type. + + There are also two variants with a "mime" argument (a MIME type + string, such as ""image/png""), which attempt to display "x" + using the requested MIME type *only*, throwing a "MethodError" if + this type is not supported by either the display(s) or by "x". + With these variants, one can also supply the "raw" data in the + requested MIME type by passing "x::AbstractString" (for MIME + types with text-based storage, such as text/html or + application/postscript) or "x::Vector{UInt8}" (for binary MIME + types). +``` """ display doc""" - redisplay(x) +```rst +redisplay(x) +redisplay(d::Display, x) +redisplay(mime, x) +redisplay(d::Display, mime, x) -By default, the `redisplay` functions simply call `display`. -However, some display backends may override `redisplay` to modify -an existing display of `x` (if any). Using `redisplay` is -also a hint to the backend that `x` may be redisplayed several -times, and the backend may choose to defer the display until (for -example) the next interactive prompt. + By default, the "redisplay" functions simply call "display". + However, some display backends may override "redisplay" to modify + an existing display of "x" (if any). Using "redisplay" is + also a hint to the backend that "x" may be redisplayed several + times, and the backend may choose to defer the display until (for + example) the next interactive prompt. +``` """ redisplay doc""" - displayable(mime) -> Bool +```rst +displayable(mime) -> Bool +displayable(d::Display, mime) -> Bool -Returns a boolean value indicating whether the given `mime` type -display stack, or specifically by the display `d` in the second -variant. + Returns a boolean value indicating whether the given "mime" type + (string) is displayable by any of the displays in the current + display stack, or specifically by the display "d" in the second + variant. +``` """ displayable doc""" - writemime(stream, mime, x) - -The `display` functions ultimately call `writemime` in order to -write an object `x` as a given `mime` type to a given I/O -provide a rich multimedia representation of a user-defined type -for `T`, via: `writemime(stream, ::MIME"mime", x::T) = ...`, -where `mime` is a MIME-type string and the function body calls -literal strings; to construct `MIME` types in a more flexible -manner use `MIME{symbol("")}`.) -For example, if you define a `MyImage` type and know how to write -it to a PNG file, you could define a function `writemime(stream, -be displayed on any PNG-capable `Display` (such as IJulia). As -usual, be sure to `import Base.writemime` in order to add new -methods to the built-in Julia function `writemime`. -Technically, the `MIME"mime"` macro defines a singleton type -for the given `mime` string, which allows us to exploit Julia's -dispatch mechanisms in determining how to display objects of any -given type. +```rst +writemime(stream, mime, x) + + The "display" functions ultimately call "writemime" in order to + write an object "x" as a given "mime" type to a given I/O + "stream" (usually a memory buffer), if possible. In order to + provide a rich multimedia representation of a user-defined type + "T", it is only necessary to define a new "writemime" method + for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", + where "mime" is a MIME-type string and the function body calls + "write" (or similar) to write that representation of "x" to + "stream". (Note that the "MIME\""" notation only supports + literal strings; to construct "MIME" types in a more flexible + manner use "MIME{symbol("")}".) + + For example, if you define a "MyImage" type and know how to write + it to a PNG file, you could define a function "writemime(stream, + ::MIME"image/png", x::MyImage) = ...`" to allow your images to + be displayed on any PNG-capable "Display" (such as IJulia). As + usual, be sure to "import Base.writemime" in order to add new + methods to the built-in Julia function "writemime". + + Technically, the "MIME"mime"" macro defines a singleton type + for the given "mime" string, which allows us to exploit Julia's + dispatch mechanisms in determining how to display objects of any + given type. +``` """ writemime doc""" - mimewritable(mime, x) +```rst +mimewritable(mime, x) -Returns a boolean value indicating whether or not the object `x` -can be written as the given `mime` type. (By default, this is -determined automatically by the existence of the corresponding + Returns a boolean value indicating whether or not the object "x" + can be written as the given "mime" type. (By default, this is + determined automatically by the existence of the corresponding + "writemime" function for "typeof(x)".) +``` """ mimewritable doc""" - reprmime(mime, x) +```rst +reprmime(mime, x) + + Returns an "AbstractString" or "Vector{UInt8}" containing the + representation of "x" in the requested "mime" type, as written + by "writemime" (throwing a "MethodError" if no appropriate + "writemime" is available). An "AbstractString" is returned for + MIME types with textual representations (such as ""text/html"" + or ""application/postscript""), whereas binary data is returned + as "Vector{UInt8}". (The function "istext(mime)" returns + whether or not Julia treats a given "mime" type as text.) -Returns an `AbstractString` or `Vector{UInt8}` containing the -representation of `x` in the requested `mime` type, as written -by `writemime` (throwing a `MethodError` if no appropriate -MIME types with textual representations (such as `text/html` -or `application/postscript`), whereas binary data is returned -as `Vector{UInt8}`. (The function `istext(mime)` returns -whether or not Julia treats a given `mime` type as text.) -As a special case, if `x` is an `AbstractString` (for textual -MIME types) or a `Vector{UInt8}` (for binary MIME types), the -requested `mime` format and simply returns `x`. + As a special case, if "x" is an "AbstractString" (for textual + MIME types) or a "Vector{UInt8}" (for binary MIME types), the + "reprmime" function assumes that "x" is already in the + requested "mime" format and simply returns "x". +``` """ reprmime doc""" - stringmime(mime, x) +```rst +stringmime(mime, x) -Returns an `AbstractString` containing the representation of -string. + Returns an "AbstractString" containing the representation of + "x" in the requested "mime" type. This is similar to + "reprmime" except that binary data is base64-encoded as an ASCII + string. +``` """ stringmime doc""" - pushdisplay(d::Display) +```rst +pushdisplay(d::Display) -Pushes a new display `d` on top of the global display-backend -stack. Calling `display(x)` or `display(mime, x)` will display -topmost backend that does not throw a `MethodError`). + Pushes a new display "d" on top of the global display-backend + stack. Calling "display(x)" or "display(mime, x)" will display + "x" on the topmost compatible backend in the stack (i.e., the + topmost backend that does not throw a "MethodError"). +``` """ pushdisplay doc""" - popdisplay() +```rst +popdisplay() +popdisplay(d::Display) -Pop the topmost backend off of the display-backend stack, or the -topmost copy of `d` in the second variant. + Pop the topmost backend off of the display-backend stack, or the + topmost copy of "d" in the second variant. +``` """ popdisplay doc""" - TextDisplay(stream) +```rst +TextDisplay(stream) -Returns a `TextDisplay <: Display`, which can display any object -as the text/plain MIME type (only), writing the text representation -to the given I/O stream. (The text representation is the same as -the way an object is printed in the Julia REPL.) + Returns a "TextDisplay <: Display", which can display any object + as the text/plain MIME type (only), writing the text representation + to the given I/O stream. (The text representation is the same as + the way an object is printed in the Julia REPL.) +``` """ TextDisplay doc""" - istext(m::MIME) +```rst +istext(m::MIME) -Determine whether a MIME type is text data. + Determine whether a MIME type is text data. +``` """ istext doc""" - mmap_array(type, dims, stream[, offset]) - -Create an `Array` whose values are linked to a file, using -memory-mapping. This provides a convenient way of working with data -too large to fit in the computer's memory. -The type determines how the bytes of the array are interpreted. -Note that the file must be stored in binary format, and no format -conversions are possible (this is a limitation of operating -systems, not Julia). -The file is passed via the stream argument. When you initialize -the stream, use `r` for a `read-only` array, and `w+` -to create a new array used to write values to disk. -Optionally, you can specify an offset (in bytes) if, for example, -you want to skip over a header in the file. The default value for -the offset is the current stream position. -For example, the following code: -creates a `m`-by-`n` `Matrix{Int}`, linked to the file -associated with stream `s`. -A more portable file would need to encode the word size---32 bit or -64 bit---and endianness information in the header. In practice, -consider encoding binary data using standard formats like HDF5 +```rst +mmap_array(type, dims, stream[, offset]) + + Create an "Array" whose values are linked to a file, using + memory-mapping. This provides a convenient way of working with data + too large to fit in the computer's memory. + + The type determines how the bytes of the array are interpreted. + Note that the file must be stored in binary format, and no format + conversions are possible (this is a limitation of operating + systems, not Julia). + + "dims" is a tuple specifying the size of the array. + + The file is passed via the stream argument. When you initialize + the stream, use ""r"" for a "read-only" array, and ""w+"" + to create a new array used to write values to disk. + + Optionally, you can specify an offset (in bytes) if, for example, + you want to skip over a header in the file. The default value for + the offset is the current stream position. + + For example, the following code: + + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) + + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) + + creates a "m"-by-"n" "Matrix{Int}", linked to the file + associated with stream "s". + + A more portable file would need to encode the word size---32 bit or + 64 bit---and endianness information in the header. In practice, + consider encoding binary data using standard formats like HDF5 + (which can be used with memory-mapping). +``` """ mmap_array doc""" - mmap_bitarray([type], dims, stream[, offset]) +```rst +mmap_bitarray([type], dims, stream[, offset]) + + Create a "BitArray" whose values are linked to a file, using + memory-mapping; it has the same purpose, works in the same way, and + has the same arguments, as "mmap_array()", but the byte + representation is different. The "type" parameter is optional, + and must be "Bool" if given. -Create a `BitArray` whose values are linked to a file, using -memory-mapping; it has the same purpose, works in the same way, and -has the same arguments, as `mmap_array()`, but the byte -representation is different. The `type` parameter is optional, -and must be `Bool` if given. -This would create a 25-by-30000 `BitArray`, linked to the file -associated with stream `s`. + **Example**: "B = mmap_bitarray((25,30000), s)" + + This would create a 25-by-30000 "BitArray", linked to the file + associated with stream "s". +``` """ mmap_bitarray doc""" - msync(array) +```rst +msync(array) -Forces synchronization between the in-memory version of a memory- -mapped `Array` or `BitArray` and the on-disk version. + Forces synchronization between the in-memory version of a memory- + mapped "Array" or "BitArray" and the on-disk version. +``` """ msync doc""" - connect([host], port) -> TcpSocket +```rst +connect([host], port) -> TcpSocket -Connect to the host `host` on port `port` + Connect to the host "host" on port "port" +``` """ connect doc""" - connect(path) -> Pipe +```rst +connect(path) -> Pipe -Connect to the Named Pipe/Domain Socket at `path` + Connect to the Named Pipe/Domain Socket at "path" +``` """ connect doc""" - listen([addr], port) -> TcpServer +```rst +listen([addr], port) -> TcpServer -Listen on port on the address specified by `addr`. By default -this listens on localhost only. To listen on all interfaces pass, + Listen on port on the address specified by "addr". By default + this listens on localhost only. To listen on all interfaces pass, + "IPv4(0)" or "IPv6(0)" as appropriate. +``` """ listen doc""" - listen(path) -> PipeServer +```rst +listen(path) -> PipeServer -Listens on/Creates a Named Pipe/Domain Socket + Listens on/Creates a Named Pipe/Domain Socket +``` """ listen doc""" - getaddrinfo(host) +```rst +getaddrinfo(host) -Gets the IP address of the `host` (may have to do a DNS lookup) + Gets the IP address of the "host" (may have to do a DNS lookup) +``` """ getaddrinfo doc""" - parseip(addr) +```rst +parseip(addr) -Parse a string specifying an IPv4 or IPv6 ip address. + Parse a string specifying an IPv4 or IPv6 ip address. +``` """ parseip doc""" - IPv4(host::Integer) -> IPv4 +```rst +IPv4(host::Integer) -> IPv4 -Returns IPv4 object from ip address formatted as Integer + Returns IPv4 object from ip address formatted as Integer +``` """ IPv4 doc""" - IPv6(host::Integer) -> IPv6 +```rst +IPv6(host::Integer) -> IPv6 -Returns IPv6 object from ip address formatted as Integer + Returns IPv6 object from ip address formatted as Integer +``` """ IPv6 doc""" - nb_available(stream) +```rst +nb_available(stream) -Returns the number of bytes available for reading before a read -from this stream or buffer will block. + Returns the number of bytes available for reading before a read + from this stream or buffer will block. +``` """ nb_available doc""" - accept(server[, client]) +```rst +accept(server[, client]) -Accepts a connection on the given server and returns a connection -to the client. An uninitialized client stream may be provided, in -which case it will be used instead of creating a new stream. + Accepts a connection on the given server and returns a connection + to the client. An uninitialized client stream may be provided, in + which case it will be used instead of creating a new stream. +``` """ accept doc""" - listenany(port_hint) -> (UInt16, TcpServer) +```rst +listenany(port_hint) -> (UInt16, TcpServer) -Create a TcpServer on any port, using hint as a starting point. -Returns a tuple of the actual port that the server was created on -and the server itself. + Create a TcpServer on any port, using hint as a starting point. + Returns a tuple of the actual port that the server was created on + and the server itself. +``` """ listenany doc""" - watch_file(cb=false, s; poll=false) +```rst +watch_file(cb=false, s; poll=false) -Watch file or directory `s` and run callback `cb` when `s` is -modified. The `poll` parameter specifies whether to use file -system event monitoring or polling. The callback function `cb` -should accept 3 arguments: `(filename, events, status)` where -an object with boolean fields `changed` and `renamed` when -using file system event monitoring, or `readable` and + Watch file or directory "s" and run callback "cb" when "s" is + modified. The "poll" parameter specifies whether to use file + system event monitoring or polling. The callback function "cb" + should accept 3 arguments: "(filename, events, status)" where + "filename" is the name of file that was modified, "events" is + an object with boolean fields "changed" and "renamed" when + using file system event monitoring, or "readable" and + "writable" when using polling, and "status" is always 0. Pass + "false" for "cb" to not use a callback function. +``` """ watch_file doc""" - poll_fd(fd, seconds::Real; readable=false, writable=false) +```rst +poll_fd(fd, seconds::Real; readable=false, writable=false) -Poll a file descriptor fd for changes in the read or write -availability and with a timeout given by the second argument. If -the timeout is not needed, use `wait(fd)` instead. The keyword -arguments determine which of read and/or write status should be -monitored and at least one of them needs to be set to true. The -returned value is an object with boolean fields `readable`, + Poll a file descriptor fd for changes in the read or write + availability and with a timeout given by the second argument. If + the timeout is not needed, use "wait(fd)" instead. The keyword + arguments determine which of read and/or write status should be + monitored and at least one of them needs to be set to true. The + returned value is an object with boolean fields "readable", + "writable", and "timedout", giving the result of the polling. +``` """ poll_fd doc""" - poll_file(s, interval_seconds::Real, seconds::Real) +```rst +poll_file(s, interval_seconds::Real, seconds::Real) -Monitor a file for changes by polling every *interval_seconds* -seconds for *seconds* seconds. A return value of true indicates the -file changed, a return value of false indicates a timeout. + Monitor a file for changes by polling every *interval_seconds* + seconds for *seconds* seconds. A return value of true indicates the + file changed, a return value of false indicates a timeout. +``` """ poll_file doc""" - bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) +```rst +bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) -Bind `socket` to the given `host:port`. Note that *0.0.0.0* -will listen on all devices. + Bind "socket" to the given "host:port". Note that *0.0.0.0* + will listen on all devices. +``` """ bind doc""" - send(socket::UDPSocket, host::IPv4, port::Integer, msg) +```rst +send(socket::UDPSocket, host::IPv4, port::Integer, msg) -Send `msg` over `socket to `host:port`. + Send "msg" over "socket to ``host:port". +``` """ send doc""" - recv(socket::UDPSocket) +```rst +recv(socket::UDPSocket) -Read a UDP packet from the specified socket, and return the bytes -received. This call blocks. + Read a UDP packet from the specified socket, and return the bytes + received. This call blocks. +``` """ recv doc""" - recvfrom(socket::UDPSocket) -> (address, data) +```rst +recvfrom(socket::UDPSocket) -> (address, data) -Read a UDP packet from the specified socket, returning a tuple of -appropriate. + Read a UDP packet from the specified socket, returning a tuple of + (address, data), where address will be either IPv4 or IPv6 as + appropriate. +``` """ recvfrom doc""" - setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) +```rst +setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) -Set UDP socket options. `multicast_loop`: loopback for multicast -packets (default: true). `multicast_ttl`: TTL for multicast -packets. `enable_broadcast`: flag must be set to true if socket -will be used for broadcast messages, or else the UDP system will -return an access error (default: false). `ttl`: Time-to-live of -packets sent on the socket. + Set UDP socket options. "multicast_loop": loopback for multicast + packets (default: true). "multicast_ttl": TTL for multicast + packets. "enable_broadcast": flag must be set to true if socket + will be used for broadcast messages, or else the UDP system will + return an access error (default: false). "ttl": Time-to-live of + packets sent on the socket. +``` """ setopt doc""" - ntoh(x) +```rst +ntoh(x) -Converts the endianness of a value from Network byte order (big- -endian) to that used by the Host. + Converts the endianness of a value from Network byte order (big- + endian) to that used by the Host. +``` """ ntoh doc""" - hton(x) +```rst +hton(x) -Converts the endianness of a value from that used by the Host to -Network byte order (big-endian). + Converts the endianness of a value from that used by the Host to + Network byte order (big-endian). +``` """ hton doc""" - ltoh(x) +```rst +ltoh(x) -Converts the endianness of a value from Little-endian to that used -by the Host. + Converts the endianness of a value from Little-endian to that used + by the Host. +``` """ ltoh doc""" - htol(x) +```rst +htol(x) -Converts the endianness of a value from that used by the Host to -Little-endian. + Converts the endianness of a value from that used by the Host to + Little-endian. +``` """ htol doc""" - ENDIAN_BOM +```rst +ENDIAN_BOM -The 32-bit byte-order-mark indicates the native byte order of the -host machine. Little-endian machines will contain the value -0x04030201. Big-endian machines will contain the value 0x01020304. + The 32-bit byte-order-mark indicates the native byte order of the + host machine. Little-endian machines will contain the value + 0x04030201. Big-endian machines will contain the value 0x01020304. +``` """ ENDIAN_BOM doc""" - malloc(size::Integer) -> Ptr{Void} +```rst +malloc(size::Integer) -> Ptr{Void} -Call `malloc` from the C standard library. + Call "malloc" from the C standard library. +``` """ Libc.malloc doc""" - calloc(num::Integer, size::Integer) -> Ptr{Void} +```rst +calloc(num::Integer, size::Integer) -> Ptr{Void} -Call `calloc` from the C standard library. + Call "calloc" from the C standard library. +``` """ Libc.calloc doc""" - realloc(addr::Ptr, size::Integer) -> Ptr{Void} +```rst +realloc(addr::Ptr, size::Integer) -> Ptr{Void} + + Call "realloc" from the C standard library. -Call `realloc` from the C standard library. -See warning in the documentation for `free` regarding only using -this on memory originally obtained from `malloc`. + See warning in the documentation for "free" regarding only using + this on memory originally obtained from "malloc". +``` """ Libc.realloc doc""" - free(addr::Ptr) +```rst +free(addr::Ptr) -Call `free` from the C standard library. Only use this on memory -obtained from `malloc`, not on pointers retrieved from other C -libraries. `Ptr` objects obtained from C libraries should be -freed by the free functions defined in that library, to avoid -assertion failures if multiple `libc` libraries exist on the -system. + Call "free" from the C standard library. Only use this on memory + obtained from "malloc", not on pointers retrieved from other C + libraries. "Ptr" objects obtained from C libraries should be + freed by the free functions defined in that library, to avoid + assertion failures if multiple "libc" libraries exist on the + system. +``` """ Libc.free doc""" - errno([code]) +```rst +errno([code]) -Get the value of the C library's `errno`. If an argument is -specified, it is used to set the value of `errno`. -The value of `errno` is only valid immediately after a `ccall` -to a C library routine that sets it. Specifically, you cannot call -executed between prompts. + Get the value of the C library's "errno". If an argument is + specified, it is used to set the value of "errno". + + The value of "errno" is only valid immediately after a "ccall" + to a C library routine that sets it. Specifically, you cannot call + "errno" at the next prompt in a REPL, because lots of code is + executed between prompts. +``` """ Libc.errno doc""" - strerror(n) +```rst +strerror(n) -Convert a system call error code to a descriptive string + Convert a system call error code to a descriptive string +``` """ Libc.strerror doc""" - time(t::TmStruct) +```rst +time(t::TmStruct) -Converts a `TmStruct` struct to a number of seconds since the -epoch. + Converts a "TmStruct" struct to a number of seconds since the + epoch. +``` """ Libc.time doc""" - strftime([format], time) +```rst +strftime([format], time) -Convert time, given as a number of seconds since the epoch or a -Supported formats are the same as those in the standard C library. + Convert time, given as a number of seconds since the epoch or a + "TmStruct", to a formatted string using the given format. + Supported formats are the same as those in the standard C library. +``` """ Libc.strftime doc""" - strptime([format], timestr) +```rst +strptime([format], timestr) -Parse a formatted time string into a `TmStruct` giving the -seconds, minute, hour, date, etc. Supported formats are the same as -those in the standard C library. On some platforms, timezones will -not be parsed correctly. If the result of this function will be -passed to `time` to convert it to seconds since the epoch, the -will tell the C library to use the current system settings to -determine the timezone. + Parse a formatted time string into a "TmStruct" giving the + seconds, minute, hour, date, etc. Supported formats are the same as + those in the standard C library. On some platforms, timezones will + not be parsed correctly. If the result of this function will be + passed to "time" to convert it to seconds since the epoch, the + "isdst" field should be filled in manually. Setting it to "-1" + will tell the C library to use the current system settings to + determine the timezone. +``` """ Libc.strptime doc""" - TmStruct([seconds]) +```rst +TmStruct([seconds]) -Convert a number of seconds since the epoch to broken-down format, -with fields `sec`, `min`, `hour`, `mday`, `month`, + Convert a number of seconds since the epoch to broken-down format, + with fields "sec", "min", "hour", "mday", "month", + "year", "wday", "yday", and "isdst". +``` """ Libc.TmStruct doc""" - flush_cstdio() +```rst +flush_cstdio() -Flushes the C `stdout` and `stderr` streams (which may have -been written to by external C code). + Flushes the C "stdout" and "stderr" streams (which may have + been written to by external C code). +``` """ Libc.flush_cstdio doc""" - msync(ptr, len[, flags]) +```rst +msync(ptr, len[, flags]) + + Forces synchronization of the "mmap()"ped memory region from + "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a + combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See + your platform man page for specifics. The flags argument is not + valid on Windows. -Forces synchronization of the `mmap()`ped memory region from -combination of `MS_ASYNC`, `MS_SYNC`, or `MS_INVALIDATE`. See -your platform man page for specifics. The flags argument is not -valid on Windows. -You may not need to call `msync`, because synchronization is -performed at intervals automatically by the operating system. -However, you can call this directly if, for example, you are -concerned about losing the result of a long-running calculation. + You may not need to call "msync", because synchronization is + performed at intervals automatically by the operating system. + However, you can call this directly if, for example, you are + concerned about losing the result of a long-running calculation. +``` """ Libc.msync doc""" - MS_ASYNC +```rst +MS_ASYNC -Enum constant for `msync()`. See your platform man page for -details. (not available on Windows). + Enum constant for "msync()". See your platform man page for + details. (not available on Windows). +``` """ Libc.MS_ASYNC doc""" - MS_SYNC +```rst +MS_SYNC -Enum constant for `msync()`. See your platform man page for -details. (not available on Windows). + Enum constant for "msync()". See your platform man page for + details. (not available on Windows). +``` """ Libc.MS_SYNC doc""" - MS_INVALIDATE +```rst +MS_INVALIDATE -Enum constant for `msync()`. See your platform man page for -details. (not available on Windows). + Enum constant for "msync()". See your platform man page for + details. (not available on Windows). +``` """ Libc.MS_INVALIDATE doc""" - mmap(len, prot, flags, fd, offset) +```rst +mmap(len, prot, flags, fd, offset) -Low-level interface to the `mmap` system call. See the man page. + Low-level interface to the "mmap" system call. See the man page. +``` """ Libc.mmap doc""" - munmap(pointer, len) +```rst +munmap(pointer, len) -Low-level interface for unmapping memory (see the man page). With -is unmapped for you when the array goes out of scope. + Low-level interface for unmapping memory (see the man page). With + "mmap_array()" you do not need to call this directly; the memory + is unmapped for you when the array goes out of scope. +``` """ Libc.munmap doc""" - dlopen(libfile::AbstractString[, flags::Integer]) +```rst +dlopen(libfile::AbstractString[, flags::Integer]) + + Load a shared library, returning an opaque handle. -Load a shared library, returning an opaque handle. -The optional flags argument is a bitwise-or of zero or more of -the POSIX (and/or GNU libc and/or MacOS) dlopen command, if -possible, or are ignored if the specified functionality is not -available on the current platform. The default is -these flags, on POSIX platforms, is to specify -symbols to be available for usage in other shared libraries, in -situations where there are dependencies between shared libraries. + The optional flags argument is a bitwise-or of zero or more of + "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", + "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and + "RTLD_FIRST". These are converted to the corresponding flags of + the POSIX (and/or GNU libc and/or MacOS) dlopen command, if + possible, or are ignored if the specified functionality is not + available on the current platform. The default is + "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of + these flags, on POSIX platforms, is to specify + "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's + symbols to be available for usage in other shared libraries, in + situations where there are dependencies between shared libraries. +``` """ Libdl.dlopen doc""" - dlopen_e(libfile::AbstractString[, flags::Integer]) +```rst +dlopen_e(libfile::AbstractString[, flags::Integer]) -Similar to `dlopen()`, except returns a `NULL` pointer instead -of raising errors. + Similar to "dlopen()", except returns a "NULL" pointer instead + of raising errors. +``` """ Libdl.dlopen_e doc""" - RTLD_DEEPBIND +```rst +RTLD_DEEPBIND -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_DEEPBIND doc""" - RTLD_FIRST +```rst +RTLD_FIRST -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_FIRST doc""" - RTLD_GLOBAL +```rst +RTLD_GLOBAL -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_GLOBAL doc""" - RTLD_LAZY +```rst +RTLD_LAZY -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_LAZY doc""" - RTLD_LOCAL +```rst +RTLD_LOCAL -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_LOCAL doc""" - RTLD_NODELETE +```rst +RTLD_NODELETE -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_NODELETE doc""" - RTLD_NOLOAD +```rst +RTLD_NOLOAD -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_NOLOAD doc""" - RTLD_NOW +```rst +RTLD_NOW -Enum constant for `dlopen()`. See your platform man page for -details, if applicable. + Enum constant for "dlopen()". See your platform man page for + details, if applicable. +``` """ Libdl.RTLD_NOW doc""" - dlsym(handle, sym) +```rst +dlsym(handle, sym) -Look up a symbol from a shared library handle, return callable -function pointer on success. + Look up a symbol from a shared library handle, return callable + function pointer on success. +``` """ Libdl.dlsym doc""" - dlsym_e(handle, sym) +```rst +dlsym_e(handle, sym) -Look up a symbol from a shared library handle, silently return NULL -pointer on lookup failure. + Look up a symbol from a shared library handle, silently return NULL + pointer on lookup failure. +``` """ Libdl.dlsym_e doc""" - dlclose(handle) +```rst +dlclose(handle) -Close shared library referenced by handle. + Close shared library referenced by handle. +``` """ Libdl.dlclose doc""" - find_library(names, locations) +```rst +find_library(names, locations) -Searches for the first library in `names` in the paths in the -that order) which can successfully be dlopen'd. On success, the -return value will be one of the names (potentially prefixed by one -of the paths in locations). This string can be assigned to a + Searches for the first library in "names" in the paths in the + "locations" list, "DL_LOAD_PATH", or system library paths (in + that order) which can successfully be dlopen'd. On success, the + return value will be one of the names (potentially prefixed by one + of the paths in locations). This string can be assigned to a + "global const" and used as the library name in future + "ccall"'s. On failure, it returns the empty string. +``` """ Libdl.find_library doc""" - DL_LOAD_PATH +```rst +DL_LOAD_PATH -When calling `dlopen`, the paths in this list will be searched -first, in order, before searching the system locations for a valid -library handle. + When calling "dlopen", the paths in this list will be searched + first, in order, before searching the system locations for a valid + library handle. +``` """ Libdl.DL_LOAD_PATH doc""" - *(A, B) +```rst +*(A, B) -Matrix multiplication + Matrix multiplication +``` """ Base.(:(*)) doc""" - \(A, B) +```rst +\(A, B) -Matrix division using a polyalgorithm. For input matrices `A` and -square. The solver that is used depends upon the structure of -complex `A`) the `BunchKaufman` factorization is used. -Otherwise an LU factorization is used. For rectangular `A` the -result is the minimum-norm least squares solution computed by a -pivoted QR factorization of `A` and a rank estimate of A based on -the R factor. -When `A` is sparse, a similar polyalgorithm is used. For -indefinite matrices, the LDLt factorization does not use pivoting -during the numerical factorization and therefore the procedure can -fail even for invertible matrices. + Matrix division using a polyalgorithm. For input matrices "A" and + "B", the result "X" is such that "A*X == B" when "A" is + square. The solver that is used depends upon the structure of + "A". A direct solver is used for upper- or lower triangular + "A". For Hermitian "A" (equivalent to symmetric "A" for non- + complex "A") the "BunchKaufman" factorization is used. + Otherwise an LU factorization is used. For rectangular "A" the + result is the minimum-norm least squares solution computed by a + pivoted QR factorization of "A" and a rank estimate of A based on + the R factor. + + When "A" is sparse, a similar polyalgorithm is used. For + indefinite matrices, the LDLt factorization does not use pivoting + during the numerical factorization and therefore the procedure can + fail even for invertible matrices. +``` """ Base.(:(\)) doc""" - dot(x, y) +```rst +dot(x, y) +⋅(x, y) -Compute the dot product. For complex vectors, the first vector is -conjugated. + Compute the dot product. For complex vectors, the first vector is + conjugated. +``` """ dot doc""" - vecdot(x, y) +```rst +vecdot(x, y) -For any iterable containers `x` and `y` (including arrays of -any dimension) of numbers (or any element type for which `dot` is -defined), compute the Euclidean dot product (the sum of -`dot(x[i],y[i])`) as if they were vectors. + For any iterable containers "x" and "y" (including arrays of + any dimension) of numbers (or any element type for which "dot" is + defined), compute the Euclidean dot product (the sum of + "dot(x[i],y[i])") as if they were vectors. +``` """ vecdot doc""" - cross(x, y) +```rst +cross(x, y) +×(x, y) -Compute the cross product of two 3-vectors. + Compute the cross product of two 3-vectors. +``` """ cross doc""" - factorize(A) +```rst +factorize(A) -Compute a convenient factorization (including LU, Cholesky, Bunch- -Kaufman, LowerTriangular, UpperTriangular) of A, based upon the -type of the input matrix. The return value can then be reused for -efficient solving of multiple systems. For example: + Compute a convenient factorization (including LU, Cholesky, Bunch- + Kaufman, LowerTriangular, UpperTriangular) of A, based upon the + type of the input matrix. The return value can then be reused for + efficient solving of multiple systems. For example: + "A=factorize(A); x=A\\b; y=A\\C". +``` """ factorize doc""" - full(F) +```rst +full(F) -Reconstruct the matrix `A` from the factorization + Reconstruct the matrix "A" from the factorization + "F=factorize(A)". +``` """ full doc""" - lu(A) -> L, U, p +```rst +lu(A) -> L, U, p -Compute the LU factorization of `A`, such that `A[p,:] = L*U`. + Compute the LU factorization of "A", such that "A[p,:] = L*U". +``` """ lu doc""" - lufact(A[, pivot=Val{true}]) -> F - -Compute the LU factorization of `A`. The return type of `F` -depends on the type of `A`. In most cases, if `A` is a subtype -pivoting is chosen (default) the element type should also support -examples are shown in the table below. -The individual components of the factorization `F` can be -accessed by indexing: +```rst +lufact(A[, pivot=Val{true}]) -> F + + Compute the LU factorization of "A". The return type of "F" + depends on the type of "A". In most cases, if "A" is a subtype + "S" of AbstractMatrix with an element type "T`" supporting + "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If + pivoting is chosen (default) the element type should also support + "abs" and "<". When "A" is sparse and have element of type + "Float32", "Float64", "Complex{Float32}", or + "Complex{Float64}" the return type is "UmfpackLU". Some + examples are shown in the table below. + + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | + +-------------------------+---------------------------+----------------------------------------------+ + + The individual components of the factorization "F" can be + accessed by indexing: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +--------------------+--------+--------------------------+---------------+ + | \"/\" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | \"\\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"cond\" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"det\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"logdet\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \"logabsdet\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \"size\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ +``` """ lufact doc""" - lufact!(A) -> LU +```rst +lufact!(A) -> LU -overwriting the input A, instead of creating a copy. For sparse -1-based indices to 0-based indices. + "lufact!" is the same as "lufact()", but saves space by + overwriting the input A, instead of creating a copy. For sparse + "A" the "nzval" field is not overwritten but the index fields, + "colptr" and "rowval" are decremented in place, converting from + 1-based indices to 0-based indices. +``` """ lufact! doc""" - chol(A[, LU]) -> F +```rst +chol(A[, LU]) -> F -Compute the Cholesky factorization of a symmetric positive definite -matrix `A` and return the matrix `F`. If `LU` is `Val{:U}` -(Upper), `F` is of type `UpperTriangular` and `A = F'*F`. If -`LU` is `Val{:L}` (Lower), `F` is of type `LowerTriangular` -and `A = F*F'`. `LU` defaults to `Val{:U}`. + Compute the Cholesky factorization of a symmetric positive definite + matrix "A" and return the matrix "F". If "LU" is "Val{:U}" + (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If + "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" + and "A = F*F'". "LU" defaults to "Val{:U}". +``` """ chol doc""" - cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - -Compute the Cholesky factorization of a dense symmetric positive -(semi)definite matrix `A` and return either a `Cholesky` if -`pivot==Val{false}` or `CholeskyPivoted` if -`pivot==Val{true}`. `LU` may be `:L` for using the lower part -or `:U` for the upper part. The default is to use `:U`. The -triangular matrix can be obtained from the factorization `F` -with: `F[:L]` and `F[:U]`. The following functions are -available for `Cholesky` objects: `size`, `\\`, `inv`, -`det`. For `CholeskyPivoted` there is also defined a `rank`. -If `pivot==Val{false}` a `PosDefException` exception is thrown -in case the matrix is not positive definite. The argument `tol` -determines the tolerance for determining the rank. For negative -values, the tolerance is the machine precision. +```rst +cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive + (semi)definite matrix "A" and return either a "Cholesky" if + "pivot==Val{false}" or "CholeskyPivoted" if + "pivot==Val{true}". "LU" may be ":L" for using the lower part + or ":U" for the upper part. The default is to use ":U". The + triangular matrix can be obtained from the factorization "F" + with: "F[:L]" and "F[:U]". The following functions are + available for "Cholesky" objects: "size", "\", "inv", + "det". For "CholeskyPivoted" there is also defined a "rank". + If "pivot==Val{false}" a "PosDefException" exception is thrown + in case the matrix is not positive definite. The argument "tol" + determines the tolerance for determining the rank. For negative + values, the tolerance is the machine precision. +``` """ cholfact doc""" - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - -Compute the Cholesky factorization of a sparse positive definite -matrix `A`. A fill-reducing permutation is used. `F = -cholfact(A)` is most frequently used to solve systems of equations -with `F\\b`, but also the methods `diag`, `det`, `logdet` -are defined for `F`. You can also extract individual factors -from `F`, using `F[:L]`. However, since pivoting is on by -default, the factorization is internally represented as `A == -P'*L*L'*P` with a permutation matrix `P`; using just `L` -without accounting for `P` will give incorrect answers. To -include the effects of permutation, it's typically preferable to -extact `combined` factors like `PtL = F[:PtL]` (the equivalent -of `P'*L`) and `LtP = F[:UP]` (the equivalent of `L'*P`). - -Setting optional `shift` keyword argument computes the -factorization of `A+shift*I` instead of `A`. If the `perm` -argument is nonempty, it should be a permutation of *1:size(A,1)* -giving the ordering to use (instead of CHOLMOD's default AMD -ordering). - -The function calls the C library CHOLMOD and many other functions -from the library are wrapped but not exported. +```rst +cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite + matrix "A". A fill-reducing permutation is used. "F = + cholfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors + from "F", using "F[:L]". However, since pivoting is on by + default, the factorization is internally represented as "A == + P'*L*L'*P" with a permutation matrix "P"; using just "L" + without accounting for "P" will give incorrect answers. To + include the effects of permutation, it's typically preferable to + extact "combined" factors like "PtL = F[:PtL]" (the equivalent + of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. +``` """ cholfact doc""" - cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky +```rst +cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky -`cholfact!` is the same as `cholfact()`, but saves space by -overwriting the input `A`, instead of creating a copy. -`cholfact!` can also reuse the symbolic factorization from a -different matrix `F` with the same structure when used as: -`cholfact!(F::CholmodFactor, A)`. + "cholfact!" is the same as "cholfact()", but saves space by + overwriting the input "A", instead of creating a copy. + "cholfact!" can also reuse the symbolic factorization from a + different matrix "F" with the same structure when used as: + "cholfact!(F::CholmodFactor, A)". +``` """ cholfact! doc""" - ldltfact(A) -> LDLtFactorization +```rst +ldltfact(A) -> LDLtFactorization -Compute a factorization of a positive definite matrix `A` such -that `A=L*Diagonal(d)*L'` where `L` is a unit lower triangular -matrix and `d` is a vector with non-negative elements. + Compute a factorization of a positive definite matrix "A" such + that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular + matrix and "d" is a vector with non-negative elements. +``` """ ldltfact doc""" - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - -Compute the LDLt factorization of a sparse symmetric or Hermitian -matrix `A`. A fill-reducing permutation is used. `F = -ldltfact(A)` is most frequently used to solve systems of equations -with `F\b`, but also the methods `diag`, `det`, `logdet` -are defined for `F`. You can also extract individual factors from -the factorization is internally represented as `A == P'*L*D*L'*P` -with a permutation matrix `P`; using just `L` without -accounting for `P` will give incorrect answers. To include the -effects of permutation, it's typically preferable to extact -complete list of supported factors is `:L, :PtL, :D, :UP, :U, :LD, -Setting optional `shift` keyword argument computes the -factorization of `A+shift*I` instead of `A`. If the `perm` -argument is nonempty, it should be a permutation of *1:size(A,1)* -giving the ordering to use (instead of CHOLMOD's default AMD -ordering). -The function calls the C library CHOLMOD and many other functions -from the library are wrapped but not exported. +```rst +ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix "A". A fill-reducing permutation is used. "F = + ldltfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors from + "F", using "F[:L]". However, since pivoting is on by default, + the factorization is internally represented as "A == P'*L*D*L'*P" + with a permutation matrix "P"; using just "L" without + accounting for "P" will give incorrect answers. To include the + effects of permutation, it's typically preferable to extact + "combined" factors like "PtL = F[:PtL]" (the equivalent of + "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The + complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, + :DU, :PtLD, :DUP". + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. +``` """ ldltfact doc""" - qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] +```rst +qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] -Compute the (pivoted) QR factorization of `A` such that either -is to compute a thin factorization. Note that `R` is not extended -with zeros when the full `Q` is requested. + Compute the (pivoted) QR factorization of "A" such that either + "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default + is to compute a thin factorization. Note that "R" is not extended + with zeros when the full "Q" is requested. +``` """ qr doc""" - qrfact(A[, pivot=Val{false}]) -> F - -Computes the QR factorization of `A`. The return type of `F` -depends on the element type of `A` and whether pivoting is -specified (with `pivot==Val{true}`). -The individual components of the factorization `F` can be -accessed by indexing: -The following functions are available for the `QR` objects: -least squares solution and if the solution is not unique, the one -with smallest norm is returned. -Multiplication with respect to either thin or full `Q` is -allowed, i.e. both `F[:Q]*F[:R]` and `F[:Q]*A` are supported. A -which has a named argument `thin`. -Note: `qrfact` returns multiple types because LAPACK uses +```rst +qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of "A". The return type of "F" + depends on the element type of "A" and whether pivoting is + specified (with "pivot==Val{true}"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + + "BlasFloat" refers to any of: "Float32", "Float64", + "Complex64" or "Complex128". + + The individual components of the factorization "F" can be + accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:p]\" | pivot \"Vector\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the "QR" objects: + "size", "\". When "A" is rectangular, "\" will return a + least squares solution and if the solution is not unique, the one + with smallest norm is returned. + + Multiplication with respect to either thin or full "Q" is + allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A + "Q" matrix can be converted into a regular matrix with "full()" + which has a named argument "thin". + + Note: "qrfact" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the "Q" and "R" matrices can be stored compactly rather + as two separate dense matrices.The data contained in "QR" or + "QRPivoted" can be used to construct the "QRPackedQ" type, + which is a compact representation of the rotation matrix: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where \tau_i is the scale factor and v_i is the projection + vector associated with the i^{th} Householder elementary + reflector.The data contained in "QRCompactWY" can be used to + construct the "QRCompactWYQ" type, which is a compact + representation of the rotation matrix + + Q = I + Y T Y^T + + where "Y" is m \times r lower trapezoidal and "T" is r + \times r upper triangular. The *compact WY* representation + [Schreiber1989] is not to be confused with the older, *WY* + representation [Bischof1987]. (The LAPACK documentation uses + "V" in lieu of "Y".) + + [Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 +``` """ qrfact doc""" - qrfact(A) -> SPQR.Factorization +```rst +qrfact(A) -> SPQR.Factorization -Compute the QR factorization of a sparse matrix `A`. A fill- -reducing permutation is used. The main application of this type is -to solve least squares problems with `\`. The function calls the -C library SPQR and a few additional functions from the library are -wrapped but not exported. + Compute the QR factorization of a sparse matrix "A". A fill- + reducing permutation is used. The main application of this type is + to solve least squares problems with "\". The function calls the + C library SPQR and a few additional functions from the library are + wrapped but not exported. +``` """ qrfact doc""" - qrfact!(A[, pivot=Val{false}]) +```rst +qrfact!(A[, pivot=Val{false}]) -instead of creating a copy. + "qrfact!" is the same as "qrfact()" when A is a subtype of + "StridedMatrix", but saves space by overwriting the input "A", + instead of creating a copy. +``` """ qrfact! doc""" - full(QRCompactWYQ[, thin=true]) -> Matrix +```rst +full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a + "QRCompactWYQ" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. -Converts an orthogonal or unitary matrix stored as a -Optionally takes a `thin` Boolean argument, which if `true` -omits the columns that span the rows of `R` in the QR -factorization that are zero. The resulting matrix is the `Q` in a -thin QR factorization (sometimes called the reduced QR -factorization). If `false`, returns a `Q` that spans all rows -of `R` in its corresponding QR factorization. + Optionally takes a "thin" Boolean argument, which if "true" + omits the columns that span the rows of "R" in the QR + factorization that are zero. The resulting matrix is the "Q" in a + thin QR factorization (sometimes called the reduced QR + factorization). If "false", returns a "Q" that spans all rows + of "R" in its corresponding QR factorization. +``` """ full doc""" - bkfact(A) -> BunchKaufman +```rst +bkfact(A) -> BunchKaufman -Compute the Bunch-Kaufman [Bunch1977] factorization of a real -symmetric or complex Hermitian matrix `A` and return a + Compute the Bunch-Kaufman [Bunch1977] factorization of a real + symmetric or complex Hermitian matrix "A" and return a + "BunchKaufman" object. The following functions are available for + "BunchKaufman" objects: "size", "\", "inv", "issym", + "ishermitian". +``` """ bkfact doc""" - bkfact!(A) -> BunchKaufman +```rst +bkfact!(A) -> BunchKaufman -overwriting the input `A`, instead of creating a copy. + "bkfact!" is the same as "bkfact()", but saves space by + overwriting the input "A", instead of creating a copy. +``` """ bkfact! doc""" - sqrtm(A) +```rst +sqrtm(A) + + Compute the matrix square root of "A". If "B = sqrtm(A)", then + "B*B == A" within roundoff error. -Compute the matrix square root of `A`. If `B = sqrtm(A)`, then -using Schur factorizations (`schurfact()`) unless it detects the -matrix to be Hermitian or real symmetric, in which case it computes -the matrix square root from an eigendecomposition (`eigfact()`). -In the latter situation for positive definite matrices, the matrix -square root has `Real` elements, otherwise it has `Complex` -elements. + "sqrtm" uses a polyalgorithm, computing the matrix square root + using Schur factorizations ("schurfact()") unless it detects the + matrix to be Hermitian or real symmetric, in which case it computes + the matrix square root from an eigendecomposition ("eigfact()"). + In the latter situation for positive definite matrices, the matrix + square root has "Real" elements, otherwise it has "Complex" + elements. +``` """ sqrtm doc""" - eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V +```rst +eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V -Computes eigenvalues and eigenvectors of `A`. See `eigfact()` -for details on the `balance` keyword argument. -the factorization to a tuple; where possible, using `eigfact()` -is recommended. + Computes eigenvalues and eigenvectors of "A". See "eigfact()" + for details on the "balance" keyword argument. + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + "eig" is a wrapper around "eigfact()", extracting all parts of + the factorization to a tuple; where possible, using "eigfact()" + is recommended. +``` """ eig doc""" - eig(A, B) -> D, V +```rst +eig(A, B) -> D, V + + Computes generalized eigenvalues and vectors of "A" with respect + to "B". -Computes generalized eigenvalues and vectors of `A` with respect -to `B`. -the factorization to a tuple; where possible, using `eigfact()` -is recommended. + "eig" is a wrapper around "eigfact()", extracting all parts of + the factorization to a tuple; where possible, using "eigfact()" + is recommended. +``` """ eig doc""" - eigvals(A,[irange,][vl,][vu]) +```rst +eigvals(A,[irange,][vl,][vu]) -Returns the eigenvalues of `A`. If `A` is `Symmetric`, -only a subset of the eigenvalues by specifying either a -eigenvalues, or a pair `vl` and `vu` for the lower and upper -boundaries of the eigenvalues. -For general non-symmetric matrices it is possible to specify how -the matrix is balanced before the eigenvector calculation. The -option `permute=true` permutes the matrix to become closer to -upper triangular, and `scale=true` scales the matrix by its -diagonal elements to make rows and columns more equal in norm. The -default is `true` for both options. + Returns the eigenvalues of "A". If "A" is "Symmetric", + "Hermitian" or "SymTridiagonal", it is possible to calculate + only a subset of the eigenvalues by specifying either a + "UnitRange" "irange" covering indices of the sorted + eigenvalues, or a pair "vl" and "vu" for the lower and upper + boundaries of the eigenvalues. + + For general non-symmetric matrices it is possible to specify how + the matrix is balanced before the eigenvector calculation. The + option "permute=true" permutes the matrix to become closer to + upper triangular, and "scale=true" scales the matrix by its + diagonal elements to make rows and columns more equal in norm. The + default is "true" for both options. +``` """ eigvals doc""" - eigmax(A) +```rst +eigmax(A) -Returns the largest eigenvalue of `A`. + Returns the largest eigenvalue of "A". +``` """ eigmax doc""" - eigmin(A) +```rst +eigmin(A) -Returns the smallest eigenvalue of `A`. + Returns the smallest eigenvalue of "A". +``` """ eigmin doc""" - eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix +```rst +eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + + Returns a matrix "M" whose columns are the eigenvectors of "A". + (The "k"th eigenvector can be obtained from the slice "M[:, + k]".) The "permute" and "scale" keywords are the same as for + "eigfact()". -Returns a matrix `M` whose columns are the eigenvectors of `A`. -k]`.) The `permute` and `scale` keywords are the same as for -For `SymTridiagonal` matrices, if the optional vector of -eigenvalues `eigvals` is specified, returns the specific -corresponding eigenvectors. + For "SymTridiagonal" matrices, if the optional vector of + eigenvalues "eigvals" is specified, returns the specific + corresponding eigenvectors. +``` """ eigvecs doc""" - eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen +```rst +eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of "A", returning an + "Eigen" factorization object "F" which contains the eigenvalues + in "F[:values]" and the eigenvectors in the columns of the matrix + "F[:vectors]". (The "k"th eigenvector can be obtained from the + slice "F[:vectors][:, k]".) + + The following functions are available for "Eigen" objects: + "inv", "det". -Computes the eigenvalue decomposition of `A`, returning an -in `F[:values]` and the eigenvectors in the columns of the matrix -slice `F[:vectors][:, k]`.) -The following functions are available for `Eigen` objects: -If `A` is `Symmetric`, `Hermitian` or `SymTridiagonal`, it -is possible to calculate only a subset of the eigenvalues by -specifying either a `UnitRange` `irange` covering indices of -the sorted eigenvalues or a pair `vl` and `vu` for the lower -and upper boundaries of the eigenvalues. -For general nonsymmetric matrices it is possible to specify how the -matrix is balanced before the eigenvector calculation. The option -triangular, and `scale=true` scales the matrix by its diagonal -elements to make rows and columns more equal in norm. The default -is `true` for both options. + If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it + is possible to calculate only a subset of the eigenvalues by + specifying either a "UnitRange" "irange" covering indices of + the sorted eigenvalues or a pair "vl" and "vu" for the lower + and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the + matrix is balanced before the eigenvector calculation. The option + "permute=true" permutes the matrix to become closer to upper + triangular, and "scale=true" scales the matrix by its diagonal + elements to make rows and columns more equal in norm. The default + is "true" for both options. +``` """ eigfact doc""" - eigfact(A, B) -> GeneralizedEigen +```rst +eigfact(A, B) -> GeneralizedEigen -Computes the generalized eigenvalue decomposition of `A` and -which contains the generalized eigenvalues in `F[:values]` and -the generalized eigenvectors in the columns of the matrix -obtained from the slice `F[:vectors][:, k]`.) + Computes the generalized eigenvalue decomposition of "A" and + "B", returning a "GeneralizedEigen" factorization object "F" + which contains the generalized eigenvalues in "F[:values]" and + the generalized eigenvectors in the columns of the matrix + "F[:vectors]". (The "k"th generalized eigenvector can be + obtained from the slice "F[:vectors][:, k]".) +``` """ eigfact doc""" - eigfact!(A[, B]) +```rst +eigfact!(A[, B]) -Same as `eigfact()`, but saves space by overwriting the input + Same as "eigfact()", but saves space by overwriting the input + "A" (and "B"), instead of creating a copy. +``` """ eigfact! doc""" - hessfact(A) +```rst +hessfact(A) -Compute the Hessenberg decomposition of `A` and return a -unitary matrix can be accessed with `F[:Q]` and the Hessenberg -matrix with `F[:H]`. When `Q` is extracted, the resulting type -is the `HessenbergQ` object, and may be converted to a regular -matrix with `full()`. + Compute the Hessenberg decomposition of "A" and return a + "Hessenberg" object. If "F" is the factorization object, the + unitary matrix can be accessed with "F[:Q]" and the Hessenberg + matrix with "F[:H]". When "Q" is extracted, the resulting type + is the "HessenbergQ" object, and may be converted to a regular + matrix with "full()". +``` """ hessfact doc""" - hessfact!(A) +```rst +hessfact!(A) -overwriting the input A, instead of creating a copy. + "hessfact!" is the same as "hessfact()", but saves space by + overwriting the input A, instead of creating a copy. +``` """ hessfact! doc""" - schurfact(A) -> Schur +```rst +schurfact(A) -> Schur -Computes the Schur factorization of the matrix `A`. The (quasi) -triangular Schur factor can be obtained from the `Schur` object -unitary/orthogonal Schur vectors can be obtained with -can be obtained with `F[:values]`. + Computes the Schur factorization of the matrix "A". The (quasi) + triangular Schur factor can be obtained from the "Schur" object + "F" with either "F[:Schur]" or "F[:T]" and the + unitary/orthogonal Schur vectors can be obtained with + "F[:vectors]" or "F[:Z]" such that + "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" + can be obtained with "F[:values]". +``` """ schurfact doc""" - schurfact!(A) +```rst +schurfact!(A) -Computes the Schur factorization of `A`, overwriting `A` in the -process. See `schurfact()` + Computes the Schur factorization of "A", overwriting "A" in the + process. See "schurfact()" +``` """ schurfact! doc""" - schur(A) -> Schur[:T], Schur[:Z], Schur[:values] +```rst +schur(A) -> Schur[:T], Schur[:Z], Schur[:values] -See `schurfact()` + See "schurfact()" +``` """ schur doc""" - ordschur(Q, T, select) -> Schur +```rst +ordschur(Q, T, select) -> Schur -Reorders the Schur factorization of a real matrix `A=Q*T*Q'` -according to the logical array `select` returning a Schur object -right invariant subspace. A complex conjugate pair of eigenvalues -must be either both included or excluded via `select`. + Reorders the Schur factorization of a real matrix "A=Q*T*Q'" + according to the logical array "select" returning a Schur object + "F". The selected eigenvalues appear in the leading diagonal of + "F[:Schur]" and the the corresponding leading columns of + "F[:vectors]" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via "select". +``` """ ordschur doc""" - ordschur!(Q, T, select) -> Schur +```rst +ordschur!(Q, T, select) -> Schur -Reorders the Schur factorization of a real matrix `A=Q*T*Q'`, -overwriting `Q` and `T` in the process. See `ordschur()` + Reorders the Schur factorization of a real matrix "A=Q*T*Q'", + overwriting "Q" and "T" in the process. See "ordschur()" +``` """ ordschur! doc""" - ordschur(S, select) -> Schur +```rst +ordschur(S, select) -> Schur -Reorders the Schur factorization `S` of type `Schur`. + Reorders the Schur factorization "S" of type "Schur". +``` """ ordschur doc""" - ordschur!(S, select) -> Schur +```rst +ordschur!(S, select) -> Schur -Reorders the Schur factorization `S` of type `Schur`, -overwriting `S` in the process. See `ordschur()` + Reorders the Schur factorization "S" of type "Schur", + overwriting "S" in the process. See "ordschur()" +``` """ ordschur! doc""" - schurfact(A, B) -> GeneralizedSchur +```rst +schurfact(A, B) -> GeneralizedSchur -Computes the Generalized Schur (or QZ) factorization of the -matrices `A` and `B`. The (quasi) triangular Schur factors can -be obtained from the `Schur` object `F` with `F[:S]` and -obtained with `F[:left]` or `F[:Q]` and the right -unitary/orthogonal Schur vectors can be obtained with `F[:right]` -or `F[:Z]` such that `A=F[:left]*F[:S]*F[:right]'` and + Computes the Generalized Schur (or QZ) factorization of the + matrices "A" and "B". The (quasi) triangular Schur factors can + be obtained from the "Schur" object "F" with "F[:S]" and + "F[:T]", the left unitary/orthogonal Schur vectors can be + obtained with "F[:left]" or "F[:Q]" and the right + unitary/orthogonal Schur vectors can be obtained with "F[:right]" + or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and + "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of + "A" and "B" can be obtained with "F[:alpha]./F[:beta]". +``` """ schurfact doc""" - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] +```rst +schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] -See `schurfact()` + See "schurfact()" +``` """ schur doc""" - ordschur(S, T, Q, Z, select) -> GeneralizedSchur +```rst +ordschur(S, T, Q, Z, select) -> GeneralizedSchur -Reorders the Generalized Schur factorization of a matrix `(A, B) = -and returns a GeneralizedSchur object `GS`. The selected -eigenvalues appear in the leading diagonal of both`(GS[:S], -GS[:T])` and the left and right unitary/orthogonal Schur vectors -are also reordered such that `(A, B) = GS[:Q]*(GS[:S], -GS[:T])*GS[:Z]^{H}` still holds and the generalized eigenvalues of + Reorders the Generalized Schur factorization of a matrix "(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" + and returns a GeneralizedSchur object "GS". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that "(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of + "A" and "B" can still be obtained with + "GS[:alpha]./GS[:beta]". +``` """ ordschur doc""" - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur +```rst +ordschur!(S, T, Q, Z, select) -> GeneralizedSchur -Reorders the Generalized Schur factorization of a matrix by -overwriting the matrices `(S, T, Q, Z)` in the process. See + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices "(S, T, Q, Z)" in the process. See + "ordschur()". +``` """ ordschur! doc""" - ordschur(GS, select) -> GeneralizedSchur +```rst +ordschur(GS, select) -> GeneralizedSchur -Reorders the Generalized Schur factorization of a Generalized Schur -object. See `ordschur()`. + Reorders the Generalized Schur factorization of a Generalized Schur + object. See "ordschur()". +``` """ ordschur doc""" - ordschur!(GS, select) -> GeneralizedSchur +```rst +ordschur!(GS, select) -> GeneralizedSchur -Reorders the Generalized Schur factorization of a Generalized Schur -object by overwriting the object with the new factorization. See + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + "ordschur()". +``` """ ordschur! doc""" - svdfact(A[, thin=true]) -> SVD +```rst +svdfact(A[, thin=true]) -> SVD -Compute the Singular Value Decomposition (SVD) of `A` and return -an `SVD` object. `U`, `S`, `V` and `Vt` can be obtained -from the factorization `F` with `F[:U]`, `F[:S]`, `F[:V]` -and `F[:Vt]`, such that `A = U*diagm(S)*Vt`. If `thin` is -produces `Vt` and hence `Vt` is more efficient to extract than + Compute the Singular Value Decomposition (SVD) of "A" and return + an "SVD" object. "U", "S", "V" and "Vt" can be obtained + from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" + and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is + "true", an economy mode decomposition is returned. The algorithm + produces "Vt" and hence "Vt" is more efficient to extract than + "V". The default is to produce a thin decomposition. +``` """ svdfact doc""" - svdfact!(A[, thin=true]) -> SVD +```rst +svdfact!(A[, thin=true]) -> SVD -overwriting the input A, instead of creating a copy. If `thin` is -to produce a thin decomposition. + "svdfact!" is the same as "svdfact()", but saves space by + overwriting the input A, instead of creating a copy. If "thin" is + "true", an economy mode decomposition is returned. The default is + to produce a thin decomposition. +``` """ svdfact! doc""" - svd(A[, thin=true]) -> U, S, V +```rst +svd(A[, thin=true]) -> U, S, V -Wrapper around `svdfact` extracting all parts the factorization -to a tuple. Direct use of `svdfact` is therefore generally more -efficient. Computes the SVD of A, returning `U`, vector `S`, -and `V` such that `A == U*diagm(S)*V'`. If `thin` is -to produce a thin decomposition. + Wrapper around "svdfact" extracting all parts the factorization + to a tuple. Direct use of "svdfact" is therefore generally more + efficient. Computes the SVD of A, returning "U", vector "S", + and "V" such that "A == U*diagm(S)*V'". If "thin" is + "true", an economy mode decomposition is returned. The default is + to produce a thin decomposition. +``` """ svd doc""" - svdvals(A) +```rst +svdvals(A) -Returns the singular values of `A`. + Returns the singular values of "A". +``` """ svdvals doc""" - svdvals!(A) +```rst +svdvals!(A) -Returns the singular values of `A`, while saving space by -overwriting the input. + Returns the singular values of "A", while saving space by + overwriting the input. +``` """ svdvals! doc""" - svdfact(A, B) -> GeneralizedSVD +```rst +svdfact(A, B) -> GeneralizedSVD -Compute the generalized SVD of `A` and `B`, returning a -F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = -F[:V]*F[:D2]*F[:R0]*F[:Q]'`. + Compute the generalized SVD of "A" and "B", returning a + "GeneralizedSVD" Factorization object "F", such that "A = + F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = + F[:V]*F[:D2]*F[:R0]*F[:Q]'". +``` """ svdfact doc""" - svd(A, B) -> U, V, Q, D1, D2, R0 +```rst +svd(A, B) -> U, V, Q, D1, D2, R0 -Wrapper around `svdfact` extracting all parts the factorization -to a tuple. Direct use of `svdfact` is therefore generally more -efficient. The function returns the generalized SVD of `A` and -such that `A = U*D1*R0*Q'` and `B = V*D2*R0*Q'`. + Wrapper around "svdfact" extracting all parts the factorization + to a tuple. Direct use of "svdfact" is therefore generally more + efficient. The function returns the generalized SVD of "A" and + "B", returning "U", "V", "Q", "D1", "D2", and "R0" + such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". +``` """ svd doc""" - svdvals(A, B) +```rst +svdvals(A, B) -Return only the singular values from the generalized singular value -decomposition of `A` and `B`. + Return only the singular values from the generalized singular value + decomposition of "A" and "B". +``` """ svdvals doc""" - triu(M) +```rst +triu(M) -Upper triangle of a matrix. + Upper triangle of a matrix. +``` """ triu doc""" - triu(M, k) +```rst +triu(M, k) -Returns the upper triangle of `M` starting from the `k`th -superdiagonal. + Returns the upper triangle of "M" starting from the "k"th + superdiagonal. +``` """ triu doc""" - triu!(M) +```rst +triu!(M) -Upper triangle of a matrix, overwriting `M` in the process. + Upper triangle of a matrix, overwriting "M" in the process. +``` """ triu! doc""" - triu!(M, k) +```rst +triu!(M, k) -Returns the upper triangle of `M` starting from the `k`th -superdiagonal, overwriting `M` in the process. + Returns the upper triangle of "M" starting from the "k"th + superdiagonal, overwriting "M" in the process. +``` """ triu! doc""" - tril(M) +```rst +tril(M) -Lower triangle of a matrix. + Lower triangle of a matrix. +``` """ tril doc""" - tril(M, k) +```rst +tril(M, k) -Returns the lower triangle of `M` starting from the `k`th -subdiagonal. + Returns the lower triangle of "M" starting from the "k"th + subdiagonal. +``` """ tril doc""" - tril!(M) +```rst +tril!(M) -Lower triangle of a matrix, overwriting `M` in the process. + Lower triangle of a matrix, overwriting "M" in the process. +``` """ tril! doc""" - tril!(M, k) +```rst +tril!(M, k) -Returns the lower triangle of `M` starting from the `k`th -subdiagonal, overwriting `M` in the process. + Returns the lower triangle of "M" starting from the "k"th + subdiagonal, overwriting "M" in the process. +``` """ tril! doc""" - diagind(M[, k]) +```rst +diagind(M[, k]) -A `Range` giving the indices of the `k`th diagonal of the -matrix `M`. + A "Range" giving the indices of the "k"th diagonal of the + matrix "M". +``` """ diagind doc""" - diag(M[, k]) +```rst +diag(M[, k]) -The `k`th diagonal of a matrix, as a vector. Use `diagm` to -construct a diagonal matrix. + The "k"th diagonal of a matrix, as a vector. Use "diagm" to + construct a diagonal matrix. +``` """ diag doc""" - diagm(v[, k]) +```rst +diagm(v[, k]) -Construct a diagonal matrix and place `v` on the `k`th -diagonal. + Construct a diagonal matrix and place "v" on the "k"th + diagonal. +``` """ diagm doc""" - scale(A, b) - +```rst +scale(A, b) +``` """ scale doc""" - scale(b, A) +```rst +scale(b, A) + + Scale an array "A" by a scalar "b", returning a new array. -Scale an array `A` by a scalar `b`, returning a new array. -If `A` is a matrix and `b` is a vector, then `scale(A,b)` -scales each column `i` of `A` by `b[i]` (similar to -array. -Note: for large `A`, `scale` can be much faster than `A .* b` -or `b .* A`, due to the use of BLAS. + If "A" is a matrix and "b" is a vector, then "scale(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), returning a new + array. + + Note: for large "A", "scale" can be much faster than "A .* b" + or "b .* A", due to the use of BLAS. +``` """ scale doc""" - scale!(A, b) - +```rst +scale!(A, b) +``` """ scale! doc""" - scale!(b, A) +```rst +scale!(b, A) + + Scale an array "A" by a scalar "b", similar to "scale()" but + overwriting "A" in-place. -Scale an array `A` by a scalar `b`, similar to `scale()` but -overwriting `A` in-place. -If `A` is a matrix and `b` is a vector, then `scale!(A,b)` -scales each column `i` of `A` by `b[i]` (similar to -place on `A`. + If "A" is a matrix and "b" is a vector, then "scale!(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- + place on "A". +``` """ scale! doc""" - Tridiagonal(dl, d, du) +```rst +Tridiagonal(dl, d, du) -Construct a tridiagonal matrix from the lower diagonal, diagonal, -and upper diagonal, respectively. The result is of type -but may be converted into a regular matrix with `full()`. + Construct a tridiagonal matrix from the lower diagonal, diagonal, + and upper diagonal, respectively. The result is of type + "Tridiagonal" and provides efficient specialized linear solvers, + but may be converted into a regular matrix with "full()". +``` """ Tridiagonal doc""" - Bidiagonal(dv, ev, isupper) +```rst +Bidiagonal(dv, ev, isupper) -Constructs an upper (`isupper=true`) or lower (`isupper=false`) -bidiagonal matrix using the given diagonal (`dv`) and off- -diagonal (`ev`) vectors. The result is of type `Bidiagonal` -and provides efficient specialized linear solvers, but may be -converted into a regular matrix with `full()`. + Constructs an upper ("isupper=true") or lower ("isupper=false") + bidiagonal matrix using the given diagonal ("dv") and off- + diagonal ("ev") vectors. The result is of type "Bidiagonal" + and provides efficient specialized linear solvers, but may be + converted into a regular matrix with "full()". +``` """ Bidiagonal doc""" - SymTridiagonal(d, du) +```rst +SymTridiagonal(d, du) -Construct a real symmetric tridiagonal matrix from the diagonal and -upper diagonal, respectively. The result is of type -but may be converted into a regular matrix with `full()`. + Construct a real symmetric tridiagonal matrix from the diagonal and + upper diagonal, respectively. The result is of type + "SymTridiagonal" and provides efficient specialized eigensolvers, + but may be converted into a regular matrix with "full()". +``` """ SymTridiagonal doc""" - rank(M) +```rst +rank(M) -Compute the rank of a matrix. + Compute the rank of a matrix. +``` """ rank doc""" - norm(A[, p]) +```rst +norm(A[, p]) -Compute the `p`-norm of a vector or the operator norm of a matrix -For vectors, `p` can assume any numeric value (even though not -all values produce a mathematically valid vector norm). In -particular, `norm(A, Inf)` returns the largest value in -For matrices, valid values of `p` are `1`, `2`, or `Inf`. -implemented.) Use `vecnorm()` to compute the Frobenius norm. + Compute the "p"-norm of a vector or the operator norm of a matrix + "A", defaulting to the "p=2"-norm. + + For vectors, "p" can assume any numeric value (even though not + all values produce a mathematically valid vector norm). In + particular, "norm(A, Inf)" returns the largest value in + "abs(A)", whereas "norm(A, -Inf)" returns the smallest. + + For matrices, valid values of "p" are "1", "2", or "Inf". + (Note that for sparse matrices, "p=2" is currently not + implemented.) Use "vecnorm()" to compute the Frobenius norm. +``` """ norm doc""" - vecnorm(A[, p]) +```rst +vecnorm(A[, p]) -For any iterable container `A` (including arrays of any -dimension) of numbers (or any element type for which `norm` is -defined), compute the `p`-norm (defaulting to `p=2`) as if -`A` were a vector of the corresponding length. + For any iterable container "A" (including arrays of any + dimension) of numbers (or any element type for which "norm" is + defined), compute the "p"-norm (defaulting to "p=2") as if + "A" were a vector of the corresponding length. -For example, if `A` is a matrix and `p=2`, then this is -equivalent to the Frobenius norm. + For example, if "A" is a matrix and "p=2", then this is + equivalent to the Frobenius norm. +``` """ vecnorm doc""" - cond(M[, p]) +```rst +cond(M[, p]) -Condition number of the matrix `M`, computed using the operator + Condition number of the matrix "M", computed using the operator + "p"-norm. Valid values for "p" are "1", "2" (default), or + "Inf". +``` """ cond doc""" - condskeel(M[, x, p]) +```rst +condskeel(M[, x, p]) + + \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \right\Vert_p \\ + \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \left\vert x \right\vert + \right\Vert_p -Skeel condition number \kappa_S of the matrix `M`, optionally -with respect to the vector `x`, as computed using the operator -values for `p` are `1`, `2`, or `Inf`. -This quantity is also known in the literature as the Bauer -condition number, relative condition number, or componentwise -relative condition number. + Skeel condition number \kappa_S of the matrix "M", optionally + with respect to the vector "x", as computed using the operator + "p"-norm. "p" is "Inf" by default, if not provided. Valid + values for "p" are "1", "2", or "Inf". + + This quantity is also known in the literature as the Bauer + condition number, relative condition number, or componentwise + relative condition number. +``` """ condskeel doc""" - trace(M) +```rst +trace(M) -Matrix trace + Matrix trace +``` """ trace doc""" - det(M) +```rst +det(M) -Matrix determinant + Matrix determinant +``` """ det doc""" - logdet(M) +```rst +logdet(M) -Log of matrix determinant. Equivalent to `log(det(M))`, but may -provide increased accuracy and/or speed. + Log of matrix determinant. Equivalent to "log(det(M))", but may + provide increased accuracy and/or speed. +``` """ logdet doc""" - logabsdet(M) +```rst +logabsdet(M) -Log of absolute value of determinant of real matrix. Equivalent to -`(log(abs(det(M))), sign(det(M)))`, but may provide increased -accuracy and/or speed. + Log of absolute value of determinant of real matrix. Equivalent to + "(log(abs(det(M))), sign(det(M)))", but may provide increased + accuracy and/or speed. +``` """ -logdet - +logabsdet doc""" - inv(M) +```rst +inv(M) -Matrix inverse + Matrix inverse +``` """ inv doc""" - pinv(M[, tol]) +```rst +pinv(M[, tol]) + + Computes the Moore-Penrose pseudoinverse. + + For matrices "M" with floating point elements, it is convenient + to compute the pseudoinverse by inverting only singular values + above a given threshold, "tol". + + The optimal choice of "tol" varies both with the value of "M" + and the intended application of the pseudoinverse. The default + value of "tol" is + "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is + essentially machine epsilon for the real part of a matrix element + multiplied by the larger matrix dimension. For inverting dense ill- + conditioned matrices in a least-squares sense, "tol = + sqrt(eps(real(float(one(eltype(M))))))" is recommended. + + For more information, see [8859], [B96], [S84], [KY88]. -Computes the Moore-Penrose pseudoinverse. -For matrices `M` with floating point elements, it is convenient -to compute the pseudoinverse by inverting only singular values -above a given threshold, `tol`. -The optimal choice of `tol` varies both with the value of `M` -and the intended application of the pseudoinverse. The default -value of `tol` is -essentially machine epsilon for the real part of a matrix element -multiplied by the larger matrix dimension. For inverting dense ill- -conditioned matrices in a least-squares sense, `tol = -sqrt(eps(real(float(one(eltype(M))))))` is recommended. -For more information, see [8859], [B96], [S84], [KY88]. + [8859] Issue 8859, "Fix least squares", + https://github.com/JuliaLang/julia/pull/8859 + + [B96] Åke Björck, "Numerical Methods for Least Squares + Problems", SIAM Press, Philadelphia, 1996, "Other Titles in + Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 + + [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 + + [KY88] Konstantinos Konstantinides and Kung Yao, + "Statistical analysis of effective singular values in + matrix rank determination", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 +``` """ pinv doc""" - nullspace(M) +```rst +nullspace(M) -Basis for nullspace of `M`. + Basis for nullspace of "M". +``` """ nullspace doc""" - repmat(A, n, m) +```rst +repmat(A, n, m) -Construct a matrix by repeating the given matrix `n` times in -dimension 1 and `m` times in dimension 2. + Construct a matrix by repeating the given matrix "n" times in + dimension 1 and "m" times in dimension 2. +``` """ repmat doc""" - repeat(A, inner = Int[], outer = Int[]) +```rst +repeat(A, inner = Int[], outer = Int[]) -Construct an array by repeating the entries of `A`. The i-th -element of `inner` specifies the number of times that the -individual entries of the i-th dimension of `A` should be -repeated. The i-th element of `outer` specifies the number of -times that a slice along the i-th dimension of `A` should be -repeated. + Construct an array by repeating the entries of "A". The i-th + element of "inner" specifies the number of times that the + individual entries of the i-th dimension of "A" should be + repeated. The i-th element of "outer" specifies the number of + times that a slice along the i-th dimension of "A" should be + repeated. +``` """ repeat doc""" - kron(A, B) +```rst +kron(A, B) -Kronecker tensor product of two vectors or two matrices. + Kronecker tensor product of two vectors or two matrices. +``` """ kron doc""" - blkdiag(A...) +```rst +blkdiag(A...) -Concatenate matrices block-diagonally. Currently only implemented -for sparse matrices. + Concatenate matrices block-diagonally. Currently only implemented + for sparse matrices. +``` """ blkdiag doc""" - linreg(x, y) -> [a; b] +```rst +linreg(x, y) -> [a; b] -Linear Regression. Returns `a` and `b` such that `a+b*x` is -the closest line to the given points `(x,y)`. In other words, -this function determines parameters `[a, b]` that minimize the -squared error between `y` and `a+b*x`. + Linear Regression. Returns "a" and "b" such that "a+b*x" is + the closest line to the given points "(x,y)". In other words, + this function determines parameters "[a, b]" that minimize the + squared error between "y" and "a+b*x". + + **Example**: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression +``` """ linreg doc""" - linreg(x, y, w) +```rst +linreg(x, y, w) -Weighted least-squares linear regression. + Weighted least-squares linear regression. +``` """ linreg doc""" - expm(A) +```rst +expm(A) -Matrix exponential. + Matrix exponential. +``` """ expm doc""" - lyap(A, C) +```rst +lyap(A, C) -Computes the solution `X` to the continuous Lyapunov equation -part and no two eigenvalues are negative complex conjugates of each -other. + Computes the solution "X" to the continuous Lyapunov equation + "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real + part and no two eigenvalues are negative complex conjugates of each + other. +``` """ lyap doc""" - sylvester(A, B, C) +```rst +sylvester(A, B, C) -Computes the solution `X` to the Sylvester equation `AX + XB + C + Computes the solution "X" to the Sylvester equation "AX + XB + C + = 0", where "A", "B" and "C" have compatible dimensions and + "A" and "-B" have no eigenvalues with equal real part. +``` """ sylvester doc""" - issym(A) -> Bool +```rst +issym(A) -> Bool -Test whether a matrix is symmetric. + Test whether a matrix is symmetric. +``` """ issym doc""" - isposdef(A) -> Bool +```rst +isposdef(A) -> Bool -Test whether a matrix is positive definite. + Test whether a matrix is positive definite. +``` """ isposdef doc""" - isposdef!(A) -> Bool +```rst +isposdef!(A) -> Bool -Test whether a matrix is positive definite, overwriting `A` in -the processes. + Test whether a matrix is positive definite, overwriting "A" in + the processes. +``` """ isposdef! doc""" - istril(A) -> Bool +```rst +istril(A) -> Bool -Test whether a matrix is lower triangular. + Test whether a matrix is lower triangular. +``` """ istril doc""" - istriu(A) -> Bool +```rst +istriu(A) -> Bool -Test whether a matrix is upper triangular. + Test whether a matrix is upper triangular. +``` """ istriu doc""" - isdiag(A) -> Bool +```rst +isdiag(A) -> Bool -Test whether a matrix is diagonal. + Test whether a matrix is diagonal. +``` """ isdiag doc""" - ishermitian(A) -> Bool +```rst +ishermitian(A) -> Bool -Test whether a matrix is Hermitian. + Test whether a matrix is Hermitian. +``` """ ishermitian doc""" - transpose(A) +```rst +transpose(A) -The transposition operator (`.'`). + The transposition operator (".'"). +``` """ transpose doc""" - transpose!(dest, src) +```rst +transpose!(dest, src) -Transpose array `src` and store the result in the preallocated -array `dest`, which should have a size corresponding to -supported and unexpected results will happen if *src* and *dest* -have overlapping memory regions. + Transpose array "src" and store the result in the preallocated + array "dest", which should have a size corresponding to + "(size(src,2),size(src,1))". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. +``` """ transpose! doc""" - ctranspose(A) +```rst +ctranspose(A) -The conjugate transposition operator (`'`). + The conjugate transposition operator ("'"). +``` """ ctranspose doc""" - ctranspose!(dest, src) +```rst +ctranspose!(dest, src) -Conjugate transpose array `src` and store the result in the -preallocated array `dest`, which should have a size corresponding -to `(size(src,2),size(src,1))`. No in-place transposition is -supported and unexpected results will happen if *src* and *dest* -have overlapping memory regions. + Conjugate transpose array "src" and store the result in the + preallocated array "dest", which should have a size corresponding + to "(size(src,2),size(src,1))". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. +``` """ ctranspose! doc""" - eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - -Computes eigenvalues `d` of `A` using Lanczos or Arnoldi -iterations for real symmetric or general nonsymmetric matrices -respectively. If `B` is provided, the generalized eigenproblem is -solved. -The following keyword arguments are supported: -corresponding Ritz vectors `v` (only if `ritzvec=true`), the -number of converged eigenvalues `nconv`, the number of iterations -Note: The `sigma` and `which` keywords interact: the +```rst +eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) + + Computes eigenvalues "d" of "A" using Lanczos or Arnoldi + iterations for real symmetric or general nonsymmetric matrices + respectively. If "B" is provided, the generalized eigenproblem is + solved. + + The following keyword arguments are supported: + * "nev": Number of eigenvalues + + * "ncv": Number of Krylov vectors used in the computation; + should satisfy + + "nev+1 <= ncv <= n" for real symmetric problems and + "nev+2 <= ncv <= n" for other problems, where "n" is + the size of the input matrix "A". The default is "ncv = + max(20,2*nev+1)". Note that these restrictions limit the + input matrix "A" to be of dimension at least 2. + + * "which": type of eigenvalues to compute. See the note + below. + + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \"which\" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LM\" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SM\" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LR\" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SR\" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + + * "tol": tolerance (tol \le 0.0 defaults to + "DLAMCH('EPS')") + + * "maxiter": Maximum number of iterations (default = 300) + + * "sigma": Specifies the level shift used in inverse + iteration. If "nothing" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + "sigma" using shift and invert iterations. + + * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) + if "true" + + * "v0": starting vector from which to start the iterations + + "eigs" returns the "nev" requested eigenvalues in "d", the + corresponding Ritz vectors "v" (only if "ritzvec=true"), the + number of converged eigenvalues "nconv", the number of iterations + "niter" and the number of matrix vector multiplications + "nmult", as well as the final residual vector "resid". + + Note: The "sigma" and "which" keywords interact: the + description of eigenvalues searched for by "which" do _not_ + necessarily refer to the eigenvalues of "A", but rather the + linear operator constructed by the specification of the iteration + mode implied by "sigma". + + +-----------------+------------------------------------+------------------------------------+ + | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | + +-----------------+------------------------------------+------------------------------------+ + | \"nothing\" | ordinary (forward) | A | + +-----------------+------------------------------------+------------------------------------+ + | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | + +-----------------+------------------------------------+------------------------------------+ +``` """ eigs doc""" - svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) +```rst +svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) -Lanczos or Arnoldi iterations. Uses `eigs()` underneath. -Inputs are: + "svds" computes largest singular values "s" of "A" using + Lanczos or Arnoldi iterations. Uses "eigs()" underneath. + + Inputs are: + * "A": Linear operator. It can either subtype of + "AbstractArray" (e.g., sparse matrix) or duck typed. For + duck typing "A" has to support "size(A)", "eltype(A)", + "A * vector" and "A' * vector". + + * "nsv": Number of singular values. + + * "ritzvec": Whether to return the left and right singular + vectors "left_sv" and "right_sv", default is "true". If + "false" the singular vectors are omitted from the output. + + * "tol": tolerance, see "eigs()". + + * "maxiter": Maximum number of iterations, see "eigs()". + + **Example**: + + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) +``` """ svds doc""" - peakflops(n; parallel=false) +```rst +peakflops(n; parallel=false) -double precision `Base.LinAlg.BLAS.gemm!()`. By default, if no -arguments are specified, it multiplies a matrix of size `n x n`, -where `n = 2000`. If the underlying BLAS is using multiple -threads, higher flop rates are realized. The number of BLAS threads -can be set with `blas_set_num_threads(n)`. -If the keyword argument `parallel` is set to `true`, -flop rate of the entire parallel computer is returned. When running -in parallel, only 1 BLAS thread is used. The argument `n` still -refers to the size of the problem that is solved on each processor. + "peakflops" computes the peak flop rate of the computer by using + double precision "Base.LinAlg.BLAS.gemm!()". By default, if no + arguments are specified, it multiplies a matrix of size "n x n", + where "n = 2000". If the underlying BLAS is using multiple + threads, higher flop rates are realized. The number of BLAS threads + can be set with "blas_set_num_threads(n)". + + If the keyword argument "parallel" is set to "true", + "peakflops" is run in parallel on all the worker processors. The + flop rate of the entire parallel computer is returned. When running + in parallel, only 1 BLAS thread is used. The argument "n" still + refers to the size of the problem that is solved on each processor. +``` """ peakflops doc""" - dot(n, X, incx, Y, incy) +```rst +dot(n, X, incx, Y, incy) -Dot product of two vectors consisting of `n` elements of array -stride `incy`. + Dot product of two vectors consisting of "n" elements of array + "X" with stride "incx" and "n" elements of array "Y" with + stride "incy". +``` """ Base.LinAlg.BLAS.dot doc""" - dotu(n, X, incx, Y, incy) +```rst +dotu(n, X, incx, Y, incy) -Dot function for two complex vectors. + Dot function for two complex vectors. +``` """ Base.LinAlg.BLAS.dotu doc""" - dotc(n, X, incx, U, incy) +```rst +dotc(n, X, incx, U, incy) -Dot function for two complex vectors conjugating the first vector. + Dot function for two complex vectors conjugating the first vector. +``` """ Base.LinAlg.BLAS.dotc doc""" - blascopy!(n, X, incx, Y, incy) +```rst +blascopy!(n, X, incx, Y, incy) -Copy `n` elements of array `X` with stride `incx` to array + Copy "n" elements of array "X" with stride "incx" to array + "Y" with stride "incy". Returns "Y". +``` """ Base.LinAlg.BLAS.blascopy! doc""" - nrm2(n, X, incx) +```rst +nrm2(n, X, incx) -2-norm of a vector consisting of `n` elements of array `X` with -stride `incx`. + 2-norm of a vector consisting of "n" elements of array "X" with + stride "incx". +``` """ Base.LinAlg.BLAS.nrm2 doc""" - asum(n, X, incx) +```rst +asum(n, X, incx) -sum of the absolute values of the first `n` elements of array + sum of the absolute values of the first "n" elements of array + "X" with stride "incx". +``` """ Base.LinAlg.BLAS.asum doc""" - axpy!(a, X, Y) +```rst +axpy!(a, X, Y) -Overwrite `Y` with `a*X + Y`. Returns `Y`. + Overwrite "Y" with "a*X + Y". Returns "Y". +``` """ Base.LinAlg.BLAS.axpy! doc""" - scal!(n, a, X, incx) +```rst +scal!(n, a, X, incx) -Overwrite `X` with `a*X`. Returns `X`. + Overwrite "X" with "a*X". Returns "X". +``` """ Base.LinAlg.BLAS.scal! doc""" - scal(n, a, X, incx) +```rst +scal(n, a, X, incx) -Returns `a*X`. + Returns "a*X". +``` """ Base.LinAlg.BLAS.scal doc""" - ger!(alpha, x, y, A) +```rst +ger!(alpha, x, y, A) -Rank-1 update of the matrix `A` with vectors `x` and `y` as -`alpha*x*y' + A`. + Rank-1 update of the matrix "A" with vectors "x" and "y" as + "alpha*x*y' + A". +``` """ Base.LinAlg.BLAS.ger! doc""" - syr!(uplo, alpha, x, A) +```rst +syr!(uplo, alpha, x, A) -Rank-1 update of the symmetric matrix `A` with vector `x` as -`alpha*x*x.' + A`. When `uplo` is 'U' the upper triangle of -`A` is updated ('L' for lower triangle). Returns `A`. + Rank-1 update of the symmetric matrix "A" with vector "x" as + "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of + "A" is updated ('L' for lower triangle). Returns "A". +``` """ Base.LinAlg.BLAS.syr! doc""" - syrk!(uplo, trans, alpha, A, beta, C) +```rst +syrk!(uplo, trans, alpha, A, beta, C) -Rank-k update of the symmetric matrix `C` as `alpha*A*A.' + -beta*C` or `alpha*A.'*A + beta*C` according to whether `trans` -is 'N' or 'T'. When `uplo` is 'U' the upper triangle of `C` is -updated ('L' for lower triangle). Returns `C`. + Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + + beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" + is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is + updated ('L' for lower triangle). Returns "C". +``` """ Base.LinAlg.BLAS.syrk! doc""" - syrk(uplo, trans, alpha, A) +```rst +syrk(uplo, trans, alpha, A) -Returns either the upper triangle or the lower triangle, according -to `uplo` ('U' or 'L'), of `alpha*A*A.'` or `alpha*A.'*A`, -according to `trans` ('N' or 'T'). + Returns either the upper triangle or the lower triangle, according + to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", + according to "trans" ('N' or 'T'). +``` """ Base.LinAlg.BLAS.syrk doc""" - her!(uplo, alpha, x, A) +```rst +her!(uplo, alpha, x, A) -Methods for complex arrays only. Rank-1 update of the Hermitian -matrix `A` with vector `x` as `alpha*x*x' + A`. When -`uplo` is 'U' the upper triangle of `A` is updated ('L' for -lower triangle). Returns `A`. + Methods for complex arrays only. Rank-1 update of the Hermitian + matrix "A" with vector "x" as "alpha*x*x' + A". When + "uplo" is 'U' the upper triangle of "A" is updated ('L' for + lower triangle). Returns "A". +``` """ Base.LinAlg.BLAS.her! doc""" - herk!(uplo, trans, alpha, A, beta, C) +```rst +herk!(uplo, trans, alpha, A, beta, C) -Methods for complex arrays only. Rank-k update of the Hermitian -matrix `C` as `alpha*A*A' + beta*C` or `alpha*A'*A + beta*C` -according to whether `trans` is 'N' or 'T'. When `uplo` is 'U' -the upper triangle of `C` is updated ('L' for lower triangle). -Returns `C`. + Methods for complex arrays only. Rank-k update of the Hermitian + matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" + according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' + the upper triangle of "C" is updated ('L' for lower triangle). + Returns "C". +``` """ Base.LinAlg.BLAS.herk! doc""" - herk(uplo, trans, alpha, A) +```rst +herk(uplo, trans, alpha, A) -Methods for complex arrays only. Returns either the upper triangle -or the lower triangle, according to `uplo` ('U' or 'L'), of + Methods for complex arrays only. Returns either the upper triangle + or the lower triangle, according to "uplo" ('U' or 'L'), of + "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or + 'T'). +``` """ Base.LinAlg.BLAS.herk doc""" - gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) +```rst +gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) -Update vector `y` as `alpha*A*x + beta*y` or `alpha*A'*x + -beta*y` according to `trans` ('N' or 'T'). The matrix `A` is -a general band matrix of dimension `m` by `size(A,2)` with -updated `y`. + Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + + beta*y" according to "trans" ('N' or 'T'). The matrix "A" is + a general band matrix of dimension "m" by "size(A,2)" with + "kl" sub-diagonals and "ku" super-diagonals. Returns the + updated "y". +``` """ Base.LinAlg.BLAS.gbmv! doc""" - gbmv(trans, m, kl, ku, alpha, A, x, beta, y) +```rst +gbmv(trans, m, kl, ku, alpha, A, x, beta, y) -Returns `alpha*A*x` or `alpha*A'*x` according to `trans` ('N' -or 'T'). The matrix `A` is a general band matrix of dimension -diagonals. + Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' + or 'T'). The matrix "A" is a general band matrix of dimension + "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- + diagonals. +``` """ Base.LinAlg.BLAS.gbmv doc""" - sbmv!(uplo, k, alpha, A, x, beta, y) +```rst +sbmv!(uplo, k, alpha, A, x, beta, y) + + Update vector "y" as "alpha*A*x + beta*y" where "A" is a a + symmetric band matrix of order "size(A,2)" with "k" super- + diagonals stored in the argument "A". The storage layout for + "A" is described the reference BLAS module, level-2 BLAS at + http://www.netlib.org/lapack/explore-html/. -Update vector `y` as `alpha*A*x + beta*y` where `A` is a a -symmetric band matrix of order `size(A,2)` with `k` super- -diagonals stored in the argument `A`. The storage layout for -http://www.netlib.org/lapack/explore-html/. -Returns the updated `y`. + Returns the updated "y". +``` """ Base.LinAlg.BLAS.sbmv! doc""" - sbmv(uplo, k, alpha, A, x) +```rst +sbmv(uplo, k, alpha, A, x) -Returns `alpha*A*x` where `A` is a symmetric band matrix of -order `size(A,2)` with `k` super-diagonals stored in the -argument `A`. + Returns "alpha*A*x" where "A" is a symmetric band matrix of + order "size(A,2)" with "k" super-diagonals stored in the + argument "A". +``` """ Base.LinAlg.BLAS.sbmv doc""" - sbmv(uplo, k, A, x) +```rst +sbmv(uplo, k, A, x) -Returns `A*x` where `A` is a symmetric band matrix of order + Returns "A*x" where "A" is a symmetric band matrix of order + "size(A,2)" with "k" super-diagonals stored in the argument + "A". +``` """ Base.LinAlg.BLAS.sbmv doc""" - gemm!(tA, tB, alpha, A, B, beta, C) +```rst +gemm!(tA, tB, alpha, A, B, beta, C) -Update `C` as `alpha*A*B + beta*C` or the other three variants -according to `tA` (transpose `A`) and `tB`. Returns the -updated `C`. + Update "C" as "alpha*A*B + beta*C" or the other three variants + according to "tA" (transpose "A") and "tB". Returns the + updated "C". +``` """ Base.LinAlg.BLAS.gemm! doc""" - gemm(tA, tB, alpha, A, B) +```rst +gemm(tA, tB, alpha, A, B) -Returns `alpha*A*B` or the other three variants according to + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". +``` """ Base.LinAlg.BLAS.gemm doc""" - gemm(tA, tB, A, B) +```rst +gemm(tA, tB, A, B) -Returns `A*B` or the other three variants according to `tA` + Returns "A*B" or the other three variants according to "tA" + (transpose "A") and "tB". +``` """ Base.LinAlg.BLAS.gemm doc""" - gemv!(tA, alpha, A, x, beta, y) +```rst +gemv!(tA, alpha, A, x, beta, y) -Update the vector `y` as `alpha*A*x + beta*y` or `alpha*A'x + -beta*y` according to `tA` (transpose `A`). Returns the updated + Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + + beta*y" according to "tA" (transpose "A"). Returns the updated + "y". +``` """ Base.LinAlg.BLAS.gemv! doc""" - gemv(tA, alpha, A, x) +```rst +gemv(tA, alpha, A, x) -Returns `alpha*A*x` or `alpha*A'x` according to `tA` + Returns "alpha*A*x" or "alpha*A'x" according to "tA" + (transpose "A"). +``` """ Base.LinAlg.BLAS.gemv doc""" - gemv(tA, A, x) +```rst +gemv(tA, A, x) -Returns `A*x` or `A'x` according to `tA` (transpose `A`). + Returns "A*x" or "A'x" according to "tA" (transpose "A"). +``` """ Base.LinAlg.BLAS.gemv doc""" - symm!(side, ul, alpha, A, B, beta, C) +```rst +symm!(side, ul, alpha, A, B, beta, C) -Update `C` as `alpha*A*B + beta*C` or `alpha*B*A + beta*C` -according to `side`. `A` is assumed to be symmetric. Only the + Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" + according to "side". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. Returns the updated "C". +``` """ Base.LinAlg.BLAS.symm! doc""" - symm(side, ul, alpha, A, B) +```rst +symm(side, ul, alpha, A, B) -Returns `alpha*A*B` or `alpha*B*A` according to `side`. `A` -is assumed to be symmetric. Only the `ul` triangle of `A` is -used. + Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" + is assumed to be symmetric. Only the "ul" triangle of "A" is + used. +``` """ Base.LinAlg.BLAS.symm doc""" - symm(side, ul, A, B) +```rst +symm(side, ul, A, B) -Returns `A*B` or `B*A` according to `side`. `A` is assumed -to be symmetric. Only the `ul` triangle of `A` is used. + Returns "A*B" or "B*A" according to "side". "A" is assumed + to be symmetric. Only the "ul" triangle of "A" is used. +``` """ Base.LinAlg.BLAS.symm doc""" - symm(tA, tB, alpha, A, B) +```rst +symm(tA, tB, alpha, A, B) -Returns `alpha*A*B` or the other three variants according to + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". +``` """ Base.LinAlg.BLAS.symm doc""" - symv!(ul, alpha, A, x, beta, y) +```rst +symv!(ul, alpha, A, x, beta, y) -Update the vector `y` as `alpha*A*x + beta*y`. `A` is assumed -to be symmetric. Only the `ul` triangle of `A` is used. -Returns the updated `y`. + Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed + to be symmetric. Only the "ul" triangle of "A" is used. + Returns the updated "y". +``` """ Base.LinAlg.BLAS.symv! doc""" - symv(ul, alpha, A, x) +```rst +symv(ul, alpha, A, x) -Returns `alpha*A*x`. `A` is assumed to be symmetric. Only the + Returns "alpha*A*x". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. +``` """ Base.LinAlg.BLAS.symv doc""" - symv(ul, A, x) +```rst +symv(ul, A, x) -Returns `A*x`. `A` is assumed to be symmetric. Only the + Returns "A*x". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. +``` """ Base.LinAlg.BLAS.symv doc""" - trmm!(side, ul, tA, dA, alpha, A, B) +```rst +trmm!(side, ul, tA, dA, alpha, A, B) -Update `B` as `alpha*A*B` or one of the other three variants -determined by `side` (A on left or right) and `tA` (transpose -A). Only the `ul` triangle of `A` is used. `dA` indicates if -Returns the updated `B`. + Update "B" as "alpha*A*B" or one of the other three variants + determined by "side" (A on left or right) and "tA" (transpose + A). Only the "ul" triangle of "A" is used. "dA" indicates if + "A" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated "B". +``` """ Base.LinAlg.BLAS.trmm! doc""" - trmm(side, ul, tA, dA, alpha, A, B) +```rst +trmm(side, ul, tA, dA, alpha, A, B) -Returns `alpha*A*B` or one of the other three variants determined -by `side` (A on left or right) and `tA` (transpose A). Only the -unit-triangular (the diagonal is assumed to be all ones). + Returns "alpha*A*B" or one of the other three variants determined + by "side" (A on left or right) and "tA" (transpose A). Only the + "ul" triangle of "A" is used. "dA" indicates if "A" is + unit-triangular (the diagonal is assumed to be all ones). +``` """ Base.LinAlg.BLAS.trmm doc""" - trsm!(side, ul, tA, dA, alpha, A, B) +```rst +trsm!(side, ul, tA, dA, alpha, A, B) -Overwrite `B` with the solution to `A*X = alpha*B` or one of -the other three variants determined by `side` (A on left or right -of `X`) and `tA` (transpose A). Only the `ul` triangle of -diagonal is assumed to be all ones). Returns the updated `B`. + Overwrite "B" with the solution to "A*X = alpha*B" or one of + the other three variants determined by "side" (A on left or right + of "X") and "tA" (transpose A). Only the "ul" triangle of + "A" is used. "dA" indicates if "A" is unit-triangular (the + diagonal is assumed to be all ones). Returns the updated "B". +``` """ Base.LinAlg.BLAS.trsm! doc""" - trsm(side, ul, tA, dA, alpha, A, B) +```rst +trsm(side, ul, tA, dA, alpha, A, B) -Returns the solution to `A*X = alpha*B` or one of the other three -variants determined by `side` (A on left or right of `X`) and -assumed to be all ones). + Returns the solution to "A*X = alpha*B" or one of the other three + variants determined by "side" (A on left or right of "X") and + "tA" (transpose A). Only the "ul" triangle of "A" is used. + "dA" indicates if "A" is unit-triangular (the diagonal is + assumed to be all ones). +``` """ Base.LinAlg.BLAS.trsm doc""" - trmv!(side, ul, tA, dA, alpha, A, b) +```rst +trmv!(side, ul, tA, dA, alpha, A, b) -Update `b` as `alpha*A*b` or one of the other three variants -determined by `side` (A on left or right) and `tA` (transpose -A). Only the `ul` triangle of `A` is used. `dA` indicates if -Returns the updated `b`. + Update "b" as "alpha*A*b" or one of the other three variants + determined by "side" (A on left or right) and "tA" (transpose + A). Only the "ul" triangle of "A" is used. "dA" indicates if + "A" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated "b". +``` """ Base.LinAlg.BLAS.trmv! doc""" - trmv(side, ul, tA, dA, alpha, A, b) +```rst +trmv(side, ul, tA, dA, alpha, A, b) -Returns `alpha*A*b` or one of the other three variants determined -by `side` (A on left or right) and `tA` (transpose A). Only the -unit-triangular (the diagonal is assumed to be all ones). + Returns "alpha*A*b" or one of the other three variants determined + by "side" (A on left or right) and "tA" (transpose A). Only the + "ul" triangle of "A" is used. "dA" indicates if "A" is + unit-triangular (the diagonal is assumed to be all ones). +``` """ Base.LinAlg.BLAS.trmv doc""" - trsv!(ul, tA, dA, A, b) +```rst +trsv!(ul, tA, dA, A, b) -Overwrite `b` with the solution to `A*x = b` or one of the -other two variants determined by `tA` (transpose A) and `ul` -triangular (the diagonal is assumed to be all ones). Returns the -updated `b`. + Overwrite "b" with the solution to "A*x = b" or one of the + other two variants determined by "tA" (transpose A) and "ul" + (triangle of "A" used). "dA" indicates if "A" is unit- + triangular (the diagonal is assumed to be all ones). Returns the + updated "b". +``` """ Base.LinAlg.BLAS.trsv! doc""" - trsv(ul, tA, dA, A, b) +```rst +trsv(ul, tA, dA, A, b) -Returns the solution to `A*x = b` or one of the other two -variants determined by `tA` (transpose A) and `ul` (triangle of -diagonal is assumed to be all ones). + Returns the solution to "A*x = b" or one of the other two + variants determined by "tA" (transpose A) and "ul" (triangle of + "A" is used.) "dA" indicates if "A" is unit-triangular (the + diagonal is assumed to be all ones). +``` """ Base.LinAlg.BLAS.trsv doc""" - blas_set_num_threads(n) +```rst +blas_set_num_threads(n) -Set the number of threads the BLAS library should use. + Set the number of threads the BLAS library should use. +``` """ Base.LinAlg.BLAS.blas_set_num_threads doc""" - I +```rst +I -An object of type `UniformScaling`, representing an identity -matrix of any size. + An object of type "UniformScaling", representing an identity + matrix of any size. +``` """ Base.LinAlg.BLAS.I doc""" - -(x) +```rst +-(x) -Unary minus operator. + Unary minus operator. +``` """ - doc""" - +(x, y...) +```rst ++(x, y...) -Addition operator. `x+y+z+...` calls this function with all -arguments, i.e. `+(x, y, z, ...)`. + Addition operator. "x+y+z+..." calls this function with all + arguments, i.e. "+(x, y, z, ...)". +``` """ + doc""" - -(x, y) +```rst +-(x, y) -Subtraction operator. + Subtraction operator. +``` """ - doc""" - *(x, y...) +```rst +*(x, y...) -Multiplication operator. `x*y*z*...` calls this function with all -arguments, i.e. `*(x, y, z, ...)`. + Multiplication operator. "x*y*z*..." calls this function with all + arguments, i.e. "*(x, y, z, ...)". +``` """ Base.(:(*)) doc""" - /(x, y) +```rst +/(x, y) -Right division operator: multiplication of `x` by the inverse of -arguments. + Right division operator: multiplication of "x" by the inverse of + "y" on the right. Gives floating-point results for integer + arguments. +``` """ Base.(:(/)) doc""" - \(x, y) +```rst +\(x, y) -Left division operator: multiplication of `y` by the inverse of -arguments. + Left division operator: multiplication of "y" by the inverse of + "x" on the left. Gives floating-point results for integer + arguments. +``` """ Base.(:(\)) doc""" - ^(x, y) +```rst +^(x, y) -Exponentiation operator. + Exponentiation operator. +``` """ Base.(:(^)) doc""" - .+(x, y) +```rst +.+(x, y) -Element-wise addition operator. + Element-wise addition operator. +``` """ Base.(:(.+)) doc""" - .-(x, y) +```rst +.-(x, y) -Element-wise subtraction operator. + Element-wise subtraction operator. +``` """ Base.(:(.-)) doc""" - .*(x, y) +```rst +.*(x, y) -Element-wise multiplication operator. + Element-wise multiplication operator. +``` """ Base.(:(.*)) doc""" - ./(x, y) +```rst +./(x, y) -Element-wise right division operator. + Element-wise right division operator. +``` """ Base.(:(./)) doc""" - .\(x, y) +```rst +.\(x, y) -Element-wise left division operator. + Element-wise left division operator. +``` """ Base.(:(.\)) doc""" - .^(x, y) +```rst +.^(x, y) -Element-wise exponentiation operator. + Element-wise exponentiation operator. +``` """ Base.(:(.^)) doc""" - fma(x, y, z) +```rst +fma(x, y, z) -Computes `x*y+z` without rounding the intermediate result -algorithms. See `muladd`. + Computes "x*y+z" without rounding the intermediate result + "x*y". On some systems this is significantly more expensive than + "x*y+z". "fma" is used to improve accuracy in certain + algorithms. See "muladd". +``` """ fma doc""" - muladd(x, y, z) +```rst +muladd(x, y, z) -Combined multiply-add, computes `x*y+z` in an efficient manner. -This may on some systems be equivalent to `x*y+z`, or to + Combined multiply-add, computes "x*y+z" in an efficient manner. + This may on some systems be equivalent to "x*y+z", or to + "fma(x,y,z)". "muladd" is used to improve performance. See + "fma". +``` """ muladd doc""" - div(x, y) +```rst +div(x, y) +÷(x, y) -The quotient from Euclidean division. Computes `x/y`, truncated -to an integer. + The quotient from Euclidean division. Computes "x/y", truncated + to an integer. +``` """ div doc""" - fld(x, y) +```rst +fld(x, y) -Largest integer less than or equal to `x/y`. + Largest integer less than or equal to "x/y". +``` """ fld doc""" - cld(x, y) +```rst +cld(x, y) -Smallest integer larger than or equal to `x/y`. + Smallest integer larger than or equal to "x/y". +``` """ cld doc""" - mod(x, y) +```rst +mod(x, y) -Modulus after division, returning in the range [0,`y`), if `y` -is positive, or (`y`,0] if `y` is negative. + Modulus after division, returning in the range [0,``y``), if "y" + is positive, or ("y",0] if "y" is negative. +``` """ mod doc""" - mod2pi(x) +```rst +mod2pi(x) + + Modulus after division by 2pi, returning in the range [0,2pi). -Modulus after division by 2pi, returning in the range [0,2pi). -This function computes a floating point representation of the -modulus after division by numerically exact 2pi, and is therefore -not exactly the same as mod(x,2pi), which would compute the modulus -of x relative to division by the floating-point number 2pi. + This function computes a floating point representation of the + modulus after division by numerically exact 2pi, and is therefore + not exactly the same as mod(x,2pi), which would compute the modulus + of x relative to division by the floating-point number 2pi. +``` """ mod2pi doc""" - rem(x, y) +```rst +rem(x, y) +%(x, y) -Remainder from Euclidean division, returning a value of the same -sign as`x`, and smaller in magnitude than `y`. This value is -always exact. + Remainder from Euclidean division, returning a value of the same + sign as``x``, and smaller in magnitude than "y". This value is + always exact. +``` """ rem doc""" - divrem(x, y) +```rst +divrem(x, y) -The quotient and remainder from Euclidean division. Equivalent to + The quotient and remainder from Euclidean division. Equivalent to + "(x÷y, x%y)". +``` """ divrem doc""" - fldmod(x, y) +```rst +fldmod(x, y) -The floored quotient and modulus after division. Equivalent to + The floored quotient and modulus after division. Equivalent to + "(fld(x,y), mod(x,y))". +``` """ fldmod doc""" - mod1(x, m) +```rst +mod1(x, m) -Modulus after division, returning in the range (0,m] + Modulus after division, returning in the range (0,m] +``` """ mod1 doc""" - rem1(x, m) +```rst +rem1(x, m) -Remainder after division, returning in the range (0,m] + Remainder after division, returning in the range (0,m] +``` """ rem1 doc""" - //(num, den) +```rst +//(num, den) -Divide two integers or rational numbers, giving a `Rational` -result. + Divide two integers or rational numbers, giving a "Rational" + result. +``` """ Base.(:(//)) doc""" - rationalize([Type=Int], x; tol=eps(x)) +```rst +rationalize([Type=Int], x; tol=eps(x)) -Approximate floating point number `x` as a Rational number with -components of the given integer type. The result will differ from + Approximate floating point number "x" as a Rational number with + components of the given integer type. The result will differ from + "x" by no more than "tol". +``` """ rationalize doc""" - num(x) +```rst +num(x) -Numerator of the rational representation of `x` + Numerator of the rational representation of "x" +``` """ num doc""" - den(x) +```rst +den(x) -Denominator of the rational representation of `x` + Denominator of the rational representation of "x" +``` """ den doc""" - <<(x, n) +```rst +<<(x, n) -Left bit shift operator. + Left bit shift operator. +``` """ Base.(:(<<)) doc""" - >>(x, n) +```rst +>>(x, n) -Right bit shift operator, preserving the sign of `x`. + Right bit shift operator, preserving the sign of "x". +``` """ Base.(:(>>)) doc""" - >>>(x, n) +```rst +>>>(x, n) -Unsigned right bit shift operator. + Unsigned right bit shift operator. +``` """ Base.(:(>>>)) doc""" - :(start[, step], stop) +```rst +:(start[, step], stop) -Range operator. `a:b` constructs a range from `a` to `b` with -a step size of 1, and `a:s:b` is similar but uses a step size of -also used in indexing to select whole dimensions. + Range operator. "a:b" constructs a range from "a" to "b" with + a step size of 1, and "a:s:b" is similar but uses a step size of + "s". These syntaxes call the function "colon". The colon is + also used in indexing to select whole dimensions. +``` """ -:(:) +Base.(:(:)) doc""" - colon(start[, step], stop) +```rst +colon(start[, step], stop) -Called by `:` syntax for constructing ranges. + Called by ":" syntax for constructing ranges. +``` """ colon doc""" - range(start[, step], length) +```rst +range(start[, step], length) -Construct a range by length, given a starting value and optional -step (defaults to 1). + Construct a range by length, given a starting value and optional + step (defaults to 1). +``` """ range doc""" - ==(x, y) +```rst +==(x, y) + + Generic equality operator, giving a single "Bool" result. Falls + back to "===". Should be implemented for all types with a notion + of equality, based on the abstract value that an instance + represents. For example, all numeric types are compared by numeric + value, ignoring type. Strings are compared as sequences of + characters, ignoring encoding. + + Follows IEEE semantics for floating-point numbers. + + Collections should generally implement "==" by calling "==" + recursively on all contents. -Generic equality operator, giving a single `Bool` result. Falls -back to `===`. Should be implemented for all types with a notion -of equality, based on the abstract value that an instance -represents. For example, all numeric types are compared by numeric -value, ignoring type. Strings are compared as sequences of -characters, ignoring encoding. -Follows IEEE semantics for floating-point numbers. -Collections should generally implement `==` by calling `==` -recursively on all contents. -New numeric types should implement this function for two arguments -of the new type, and handle comparison to other types via promotion -rules where possible. + New numeric types should implement this function for two arguments + of the new type, and handle comparison to other types via promotion + rules where possible. +``` """ Base.(:(==)) doc""" - !=(x, y) +```rst +!=(x, y) +≠(x, y) -Not-equals comparison operator. Always gives the opposite answer as -the fallback definition `!=(x,y) = !(x==y)` instead. + Not-equals comparison operator. Always gives the opposite answer as + "==". New types should generally not implement this, and rely on + the fallback definition "!=(x,y) = !(x==y)" instead. +``` """ Base.(:(!=)) doc""" - ===(x, y) +```rst +===(x, y) +≡(x, y) -See the `is()` operator + See the "is()" operator +``` """ Base.(:(===)) doc""" - !==(x, y) +```rst +!==(x, y) +≢(x, y) -Equivalent to `!is(x, y)` + Equivalent to "!is(x, y)" +``` """ Base.(:(!==)) doc""" - <(x, y) +```rst +<(x, y) -Less-than comparison operator. New numeric types should implement -this function for two arguments of the new type. Because of the -behavior of floating-point NaN values, `<` implements a partial -order. Types with a canonical partial order should implement `<`, -and types with a canonical total order should implement `isless`. + Less-than comparison operator. New numeric types should implement + this function for two arguments of the new type. Because of the + behavior of floating-point NaN values, "<" implements a partial + order. Types with a canonical partial order should implement "<", + and types with a canonical total order should implement "isless". +``` """ Base.(:(<)) doc""" - <=(x, y) +```rst +<=(x, y) +≤(x, y) -Less-than-or-equals comparison operator. + Less-than-or-equals comparison operator. +``` """ Base.(:(<=)) doc""" - >(x, y) +```rst +>(x, y) -Greater-than comparison operator. Generally, new types should -implement `<` instead of this function, and rely on the fallback -definition `>(x,y) = y(x,y) = y)) doc""" - >=(x, y) +```rst +>=(x, y) +≥(x, y) -Greater-than-or-equals comparison operator. + Greater-than-or-equals comparison operator. +``` """ Base.(:(>=)) doc""" - .==(x, y) +```rst +.==(x, y) -Element-wise equality comparison operator. + Element-wise equality comparison operator. +``` """ Base.(:(.==)) doc""" - .!=(x, y) +```rst +.!=(x, y) +.≠(x, y) -Element-wise not-equals comparison operator. + Element-wise not-equals comparison operator. +``` """ Base.(:(.!=)) doc""" - .<(x, y) +```rst +.<(x, y) -Element-wise less-than comparison operator. + Element-wise less-than comparison operator. +``` """ Base.(:(.<)) doc""" - .<=(x, y) +```rst +.<=(x, y) +.≤(x, y) -Element-wise less-than-or-equals comparison operator. + Element-wise less-than-or-equals comparison operator. +``` """ Base.(:(.<=)) doc""" - .>(x, y) +```rst +.>(x, y) -Element-wise greater-than comparison operator. + Element-wise greater-than comparison operator. +``` """ Base.(:(.>)) doc""" - .>=(x, y) +```rst +.>=(x, y) +.≥(x, y) -Element-wise greater-than-or-equals comparison operator. + Element-wise greater-than-or-equals comparison operator. +``` """ Base.(:(.>=)) doc""" - cmp(x, y) +```rst +cmp(x, y) -Return -1, 0, or 1 depending on whether `x` is less than, equal -to, or greater than `y`, respectively. Uses the total order -implemented by `isless`. For floating-point numbers, uses `<` -but throws an error for unordered arguments. + Return -1, 0, or 1 depending on whether "x" is less than, equal + to, or greater than "y", respectively. Uses the total order + implemented by "isless". For floating-point numbers, uses "<" + but throws an error for unordered arguments. +``` """ cmp doc""" - ~(x) +```rst +~(x) -Bitwise not + Bitwise not +``` """ ~ doc""" - &(x, y) +```rst +&(x, y) -Bitwise and + Bitwise and +``` """ & doc""" - |(x, y) +```rst +|(x, y) -Bitwise or + Bitwise or +``` """ Base.(:(|)) doc""" - \$(x, y) +```rst +\$(x, y) -Bitwise exclusive or + Bitwise exclusive or +``` """ $ doc""" - !(x) +```rst +!(x) -Boolean not + Boolean not +``` """ ! doc""" - A_ldiv_Bc(a, b) +```rst +A_ldiv_Bc(a, b) -Matrix operator A \ B^H + Matrix operator A \ B^H +``` """ A_ldiv_Bc doc""" - A_ldiv_Bt(a, b) +```rst +A_ldiv_Bt(a, b) -Matrix operator A \ B^T + Matrix operator A \ B^T +``` """ A_ldiv_Bt doc""" - A_mul_B!(Y, A, B) -> Y +```rst +A_mul_B!(Y, A, B) -> Y -Calculates the matrix-matrix or matrix-vector product *A B* and -stores the result in *Y*, overwriting the existing value of *Y*. + Calculates the matrix-matrix or matrix-vector product *A B* and + stores the result in *Y*, overwriting the existing value of *Y*. + + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); + + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 +``` """ A_mul_B! doc""" - A_mul_Bc(...) +```rst +A_mul_Bc(...) -Matrix operator A B^H + Matrix operator A B^H +``` """ A_mul_Bc doc""" - A_mul_Bt(...) +```rst +A_mul_Bt(...) -Matrix operator A B^T + Matrix operator A B^T +``` """ A_mul_Bt doc""" - A_rdiv_Bc(...) +```rst +A_rdiv_Bc(...) -Matrix operator A / B^H + Matrix operator A / B^H +``` """ A_rdiv_Bc doc""" - A_rdiv_Bt(a, b) +```rst +A_rdiv_Bt(a, b) -Matrix operator A / B^T + Matrix operator A / B^T +``` """ A_rdiv_Bt doc""" - Ac_ldiv_B(...) +```rst +Ac_ldiv_B(...) -Matrix operator A^H \ B + Matrix operator A^H \ B +``` """ Ac_ldiv_B doc""" - Ac_ldiv_Bc(...) +```rst +Ac_ldiv_Bc(...) -Matrix operator A^H \ B^H + Matrix operator A^H \ B^H +``` """ Ac_ldiv_Bc doc""" - Ac_mul_B(...) +```rst +Ac_mul_B(...) -Matrix operator A^H B + Matrix operator A^H B +``` """ Ac_mul_B doc""" - Ac_mul_Bc(...) +```rst +Ac_mul_Bc(...) -Matrix operator A^H B^H + Matrix operator A^H B^H +``` """ Ac_mul_Bc doc""" - Ac_rdiv_B(a, b) +```rst +Ac_rdiv_B(a, b) -Matrix operator A^H / B + Matrix operator A^H / B +``` """ Ac_rdiv_B doc""" - Ac_rdiv_Bc(a, b) +```rst +Ac_rdiv_Bc(a, b) -Matrix operator A^H / B^H + Matrix operator A^H / B^H +``` """ Ac_rdiv_Bc doc""" - At_ldiv_B(...) +```rst +At_ldiv_B(...) -Matrix operator A^T \ B + Matrix operator A^T \ B +``` """ At_ldiv_B doc""" - At_ldiv_Bt(...) +```rst +At_ldiv_Bt(...) -Matrix operator A^T \ B^T + Matrix operator A^T \ B^T +``` """ At_ldiv_Bt doc""" - At_mul_B(...) +```rst +At_mul_B(...) -Matrix operator A^T B + Matrix operator A^T B +``` """ At_mul_B doc""" - At_mul_Bt(...) +```rst +At_mul_Bt(...) -Matrix operator A^T B^T + Matrix operator A^T B^T +``` """ At_mul_Bt doc""" - At_rdiv_B(a, b) +```rst +At_rdiv_B(a, b) -Matrix operator A^T / B + Matrix operator A^T / B +``` """ At_rdiv_B doc""" - At_rdiv_Bt(a, b) +```rst +At_rdiv_Bt(a, b) -Matrix operator A^T / B^T + Matrix operator A^T / B^T +``` """ At_rdiv_Bt doc""" - isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) +```rst +isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + + Inexact equality comparison - behaves slightly different depending + on types of input args: + + * For "FloatingPoint" numbers, "isapprox" returns "true" if + "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". + + * For "Integer" and "Rational" numbers, "isapprox" returns + "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. + If one of "x" and "y" is "FloatingPoint", the other is + promoted, and the method above is called instead. + + * For "Complex" numbers, the distance in the complex plane is + compared, using the same criterion as above. -Inexact equality comparison - behaves slightly different depending -on types of input args: -For default tolerance arguments, `maxeps = max(eps(abs(x)), -eps(abs(y)))`. + For default tolerance arguments, "maxeps = max(eps(abs(x)), + eps(abs(y)))". +``` """ isapprox doc""" - sin(x) +```rst +sin(x) -Compute sine of `x`, where `x` is in radians + Compute sine of "x", where "x" is in radians +``` """ sin doc""" - cos(x) +```rst +cos(x) -Compute cosine of `x`, where `x` is in radians + Compute cosine of "x", where "x" is in radians +``` """ cos doc""" - tan(x) +```rst +tan(x) -Compute tangent of `x`, where `x` is in radians + Compute tangent of "x", where "x" is in radians +``` """ tan doc""" - sind(x) +```rst +sind(x) -Compute sine of `x`, where `x` is in degrees + Compute sine of "x", where "x" is in degrees +``` """ sind doc""" - cosd(x) +```rst +cosd(x) -Compute cosine of `x`, where `x` is in degrees + Compute cosine of "x", where "x" is in degrees +``` """ cosd doc""" - tand(x) +```rst +tand(x) -Compute tangent of `x`, where `x` is in degrees + Compute tangent of "x", where "x" is in degrees +``` """ tand doc""" - sinpi(x) +```rst +sinpi(x) -Compute \sin(\pi x) more accurately than `sin(pi*x)`, -especially for large `x`. + Compute \sin(\pi x) more accurately than "sin(pi*x)", + especially for large "x". +``` """ sinpi doc""" - cospi(x) +```rst +cospi(x) -Compute \cos(\pi x) more accurately than `cos(pi*x)`, -especially for large `x`. + Compute \cos(\pi x) more accurately than "cos(pi*x)", + especially for large "x". +``` """ cospi doc""" - sinh(x) +```rst +sinh(x) -Compute hyperbolic sine of `x` + Compute hyperbolic sine of "x" +``` """ sinh doc""" - cosh(x) +```rst +cosh(x) -Compute hyperbolic cosine of `x` + Compute hyperbolic cosine of "x" +``` """ cosh doc""" - tanh(x) +```rst +tanh(x) -Compute hyperbolic tangent of `x` + Compute hyperbolic tangent of "x" +``` """ tanh doc""" - asin(x) +```rst +asin(x) -Compute the inverse sine of `x`, where the output is in radians + Compute the inverse sine of "x", where the output is in radians +``` """ asin doc""" - acos(x) +```rst +acos(x) -Compute the inverse cosine of `x`, where the output is in radians + Compute the inverse cosine of "x", where the output is in radians +``` """ acos doc""" - atan(x) +```rst +atan(x) -Compute the inverse tangent of `x`, where the output is in -radians + Compute the inverse tangent of "x", where the output is in + radians +``` """ atan doc""" - atan2(y, x) +```rst +atan2(y, x) -Compute the inverse tangent of `y/x`, using the signs of both + Compute the inverse tangent of "y/x", using the signs of both + "x" and "y" to determine the quadrant of the return value. +``` """ atan2 doc""" - asind(x) +```rst +asind(x) -Compute the inverse sine of `x`, where the output is in degrees + Compute the inverse sine of "x", where the output is in degrees +``` """ asind doc""" - acosd(x) +```rst +acosd(x) -Compute the inverse cosine of `x`, where the output is in degrees + Compute the inverse cosine of "x", where the output is in degrees +``` """ acosd doc""" - atand(x) +```rst +atand(x) -Compute the inverse tangent of `x`, where the output is in -degrees + Compute the inverse tangent of "x", where the output is in + degrees +``` """ atand doc""" - sec(x) +```rst +sec(x) -Compute the secant of `x`, where `x` is in radians + Compute the secant of "x", where "x" is in radians +``` """ sec doc""" - csc(x) +```rst +csc(x) -Compute the cosecant of `x`, where `x` is in radians + Compute the cosecant of "x", where "x" is in radians +``` """ csc doc""" - cot(x) +```rst +cot(x) -Compute the cotangent of `x`, where `x` is in radians + Compute the cotangent of "x", where "x" is in radians +``` """ cot doc""" - secd(x) +```rst +secd(x) -Compute the secant of `x`, where `x` is in degrees + Compute the secant of "x", where "x" is in degrees +``` """ secd doc""" - cscd(x) +```rst +cscd(x) -Compute the cosecant of `x`, where `x` is in degrees + Compute the cosecant of "x", where "x" is in degrees +``` """ cscd doc""" - cotd(x) +```rst +cotd(x) -Compute the cotangent of `x`, where `x` is in degrees + Compute the cotangent of "x", where "x" is in degrees +``` """ cotd doc""" - asec(x) +```rst +asec(x) -Compute the inverse secant of `x`, where the output is in radians + Compute the inverse secant of "x", where the output is in radians +``` """ asec doc""" - acsc(x) +```rst +acsc(x) -Compute the inverse cosecant of `x`, where the output is in -radians + Compute the inverse cosecant of "x", where the output is in + radians +``` """ acsc doc""" - acot(x) +```rst +acot(x) -Compute the inverse cotangent of `x`, where the output is in -radians + Compute the inverse cotangent of "x", where the output is in + radians +``` """ acot doc""" - asecd(x) +```rst +asecd(x) -Compute the inverse secant of `x`, where the output is in degrees + Compute the inverse secant of "x", where the output is in degrees +``` """ asecd doc""" - acscd(x) +```rst +acscd(x) -Compute the inverse cosecant of `x`, where the output is in -degrees + Compute the inverse cosecant of "x", where the output is in + degrees +``` """ acscd doc""" - acotd(x) +```rst +acotd(x) -Compute the inverse cotangent of `x`, where the output is in -degrees + Compute the inverse cotangent of "x", where the output is in + degrees +``` """ acotd doc""" - sech(x) +```rst +sech(x) -Compute the hyperbolic secant of `x` + Compute the hyperbolic secant of "x" +``` """ sech doc""" - csch(x) +```rst +csch(x) -Compute the hyperbolic cosecant of `x` + Compute the hyperbolic cosecant of "x" +``` """ csch doc""" - coth(x) +```rst +coth(x) -Compute the hyperbolic cotangent of `x` + Compute the hyperbolic cotangent of "x" +``` """ coth doc""" - asinh(x) +```rst +asinh(x) -Compute the inverse hyperbolic sine of `x` + Compute the inverse hyperbolic sine of "x" +``` """ asinh doc""" - acosh(x) +```rst +acosh(x) -Compute the inverse hyperbolic cosine of `x` + Compute the inverse hyperbolic cosine of "x" +``` """ acosh doc""" - atanh(x) +```rst +atanh(x) -Compute the inverse hyperbolic tangent of `x` + Compute the inverse hyperbolic tangent of "x" +``` """ atanh doc""" - asech(x) +```rst +asech(x) -Compute the inverse hyperbolic secant of `x` + Compute the inverse hyperbolic secant of "x" +``` """ asech doc""" - acsch(x) +```rst +acsch(x) -Compute the inverse hyperbolic cosecant of `x` + Compute the inverse hyperbolic cosecant of "x" +``` """ acsch doc""" - acoth(x) +```rst +acoth(x) -Compute the inverse hyperbolic cotangent of `x` + Compute the inverse hyperbolic cotangent of "x" +``` """ acoth doc""" - sinc(x) +```rst +sinc(x) -Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. + Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. +``` """ sinc doc""" - cosc(x) +```rst +cosc(x) -Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq -0, and 0 if x = 0. This is the derivative of `sinc(x)`. + Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq + 0, and 0 if x = 0. This is the derivative of "sinc(x)". +``` """ cosc doc""" - deg2rad(x) +```rst +deg2rad(x) -Convert `x` from degrees to radians + Convert "x" from degrees to radians +``` """ deg2rad doc""" - rad2deg(x) +```rst +rad2deg(x) -Convert `x` from radians to degrees + Convert "x" from radians to degrees +``` """ rad2deg doc""" - hypot(x, y) +```rst +hypot(x, y) -Compute the \sqrt{x^2+y^2} avoiding overflow and underflow + Compute the \sqrt{x^2+y^2} avoiding overflow and underflow +``` """ hypot doc""" - log(x) +```rst +log(x) -Compute the natural logarithm of `x`. Throws `DomainError` for -negative `Real` arguments. Use complex negative arguments to -obtain complex results. + Compute the natural logarithm of "x". Throws "DomainError" for + negative "Real" arguments. Use complex negative arguments to + obtain complex results. -There is an experimental variant in the `Base.Math.JuliaLibm` -module, which is typically faster and more accurate. + There is an experimental variant in the "Base.Math.JuliaLibm" + module, which is typically faster and more accurate. +``` """ log doc""" - log(b, x) +```rst +log(b, x) -Compute the base `b` logarithm of `x`. Throws `DomainError` -for negative `Real` arguments. + Compute the base "b" logarithm of "x". Throws "DomainError" + for negative "Real" arguments. +``` """ log doc""" - log2(x) +```rst +log2(x) -Compute the logarithm of `x` to base 2. Throws `DomainError` -for negative `Real` arguments. + Compute the logarithm of "x" to base 2. Throws "DomainError" + for negative "Real" arguments. +``` """ log2 doc""" - log10(x) +```rst +log10(x) -Compute the logarithm of `x` to base 10. Throws `DomainError` -for negative `Real` arguments. + Compute the logarithm of "x" to base 10. Throws "DomainError" + for negative "Real" arguments. +``` """ log10 doc""" - log1p(x) +```rst +log1p(x) -Accurate natural logarithm of `1+x`. Throws `DomainError` for -There is an experimental variant in the `Base.Math.JuliaLibm` -module, which is typically faster and more accurate. + Accurate natural logarithm of "1+x". Throws "DomainError" for + "Real" arguments less than -1. + + There is an experimental variant in the "Base.Math.JuliaLibm" + module, which is typically faster and more accurate. +``` """ log1p doc""" - frexp(val) +```rst +frexp(val) -Return `(x,exp)` such that `x` has a magnitude in the interval + Return "(x,exp)" such that "x" has a magnitude in the interval + "[1/2, 1)" or 0, and val = x \times 2^{exp}. +``` """ frexp doc""" - exp(x) +```rst +exp(x) -Compute e^x + Compute e^x +``` """ exp doc""" - exp2(x) +```rst +exp2(x) -Compute 2^x + Compute 2^x +``` """ exp2 doc""" - exp10(x) +```rst +exp10(x) -Compute 10^x + Compute 10^x +``` """ exp10 doc""" - ldexp(x, n) +```rst +ldexp(x, n) -Compute x \times 2^n + Compute x \times 2^n +``` """ ldexp doc""" - modf(x) +```rst +modf(x) -Return a tuple (fpart,ipart) of the fractional and integral parts -of a number. Both parts have the same sign as the argument. + Return a tuple (fpart,ipart) of the fractional and integral parts + of a number. Both parts have the same sign as the argument. +``` """ modf doc""" - expm1(x) +```rst +expm1(x) -Accurately compute e^x-1 + Accurately compute e^x-1 +``` """ expm1 doc""" - round([T], x[, digits[, base]][, r::RoundingMode]) +```rst +round([T], x[, digits[, base]][, r::RoundingMode]) + + "round(x)" rounds "x" to an integer value according to the + default rounding mode (see "get_rounding()"), returning a value + of the same type as "x". By default ("RoundNearest"), this will + round to the nearest integer, with ties (fractional values of 0.5) + being rounded to the even integer. + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional "RoundingMode" argument will change how the number + gets rounded. -default rounding mode (see `get_rounding()`), returning a value -of the same type as `x`. By default (`RoundNearest`), this will -round to the nearest integer, with ties (fractional values of 0.5) -being rounded to the even integer. -The optional `RoundingMode` argument will change how the number -gets rounded. -representable. -the decimal place (or before if negative). `round(x, digits, -base)` rounds using a base other than 10. -Note: Rounding to specified digits in bases other than 2 can be + "round(T, x, [r::RoundingMode])" converts the result to type + "T", throwing an "InexactError" if the value is not + representable. + + "round(x, digits)" rounds to the specified number of digits after + the decimal place (or before if negative). "round(x, digits, + base)" rounds using a base other than 10. + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the "Float64" value represented by "1.15" is + actually *less* than 1.15, yet will be rounded to 1.2. + + julia> x = 1.15 + 1.15 + + julia> @sprintf "%.20f" x + "1.14999999999999991118" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 +``` """ round doc""" - RoundingMode +```rst +RoundingMode + + A type which controls rounding behavior. Currently supported + rounding modes are: + + * "RoundNearest" (default) + + * "RoundNearestTiesAway" + + * "RoundNearestTiesUp" -A type which controls rounding behavior. Currently supported -rounding modes are: + * "RoundToZero" + + * "RoundUp" + + * "RoundDown" +``` """ RoundingMode doc""" - RoundNearest +```rst +RoundNearest -The default rounding mode. Rounds to the nearest integer, with ties -integer. + The default rounding mode. Rounds to the nearest integer, with ties + (fractional values of 0.5) being rounded to the nearest even + integer. +``` """ RoundNearest doc""" - RoundNearestTiesAway +```rst +RoundNearestTiesAway -Rounds to nearest integer, with ties rounded away from zero (C/C++ + Rounds to nearest integer, with ties rounded away from zero (C/C++ + "round()" behaviour). +``` """ RoundNearestTiesAway doc""" - RoundNearestTiesUp +```rst +RoundNearestTiesUp -Rounds to nearest integer, with ties rounded toward positive -infinity (Java/JavaScript `round()` behaviour). + Rounds to nearest integer, with ties rounded toward positive + infinity (Java/JavaScript "round()" behaviour). +``` """ RoundNearestTiesUp doc""" - RoundToZero +```rst +RoundToZero + "round()" using this rounding mode is an alias for "trunc()". +``` """ RoundToZero doc""" - RoundUp +```rst +RoundUp + "round()" using this rounding mode is an alias for "ceil()". +``` """ RoundUp doc""" - RoundDown +```rst +RoundDown + "round()" using this rounding mode is an alias for "floor()". +``` """ RoundDown doc""" - round(z, RoundingModeReal, RoundingModeImaginary) +```rst +round(z, RoundingModeReal, RoundingModeImaginary) -Returns the nearest integral value of the same type as the complex- -valued `z` to `z`, breaking ties using the specified -the real components while the second is used for rounding the -imaginary components. + Returns the nearest integral value of the same type as the complex- + valued "z" to "z", breaking ties using the specified + "RoundingMode"s. The first "RoundingMode" is used for rounding + the real components while the second is used for rounding the + imaginary components. +``` """ round doc""" - ceil([T], x[, digits[, base]]) +```rst +ceil([T], x[, digits[, base]]) + + "ceil(x)" returns the nearest integral value of the same type as + "x" that is greater than or equal to "x". + "ceil(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". +``` """ ceil doc""" - floor([T], x[, digits[, base]]) +```rst +floor([T], x[, digits[, base]]) + + "floor(x)" returns the nearest integral value of the same type as + "x" that is less than or equal to "x". + + "floor(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + "digits" and "base" work as for "round()". +``` """ floor doc""" - trunc([T], x[, digits[, base]]) +```rst +trunc([T], x[, digits[, base]]) + "trunc(x)" returns the nearest integral value of the same type as + "x" whose absolute value is less than or equal to "x". + + "trunc(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". +``` """ trunc doc""" - unsafe_trunc(T, x) +```rst +unsafe_trunc(T, x) -value is not representable by `T`, an arbitrary value will be -returned. + "unsafe_trunc(T, x)" returns the nearest integral value of type + "T" whose absolute value is less than or equal to "x". If the + value is not representable by "T", an arbitrary value will be + returned. +``` """ unsafe_trunc doc""" - signif(x, digits[, base]) +```rst +signif(x, digits[, base]) -Rounds (in the sense of `round`) `x` so that there are -representation, default 10. E.g., `signif(123.456, 2)` is + Rounds (in the sense of "round") "x" so that there are + "digits" significant digits, under a base "base" + representation, default 10. E.g., "signif(123.456, 2)" is + "120.0", and "signif(357.913, 4, 2)" is "352.0". +``` """ signif doc""" - min(x, y, ...) +```rst +min(x, y, ...) -Return the minimum of the arguments. Operates elementwise over -arrays. + Return the minimum of the arguments. Operates elementwise over + arrays. +``` """ min doc""" - max(x, y, ...) +```rst +max(x, y, ...) -Return the maximum of the arguments. Operates elementwise over -arrays. + Return the maximum of the arguments. Operates elementwise over + arrays. +``` """ max doc""" - minmax(x, y) +```rst +minmax(x, y) -Return `(min(x,y), max(x,y))`. See also: `extrema()` that -returns `(minimum(x), maximum(x))` + Return "(min(x,y), max(x,y))". See also: "extrema()" that + returns "(minimum(x), maximum(x))" +``` """ minmax doc""" - clamp(x, lo, hi) +```rst +clamp(x, lo, hi) -Return x if `lo <= x <= hi`. If `x < lo`, return `lo`. If `x -Operates elementwise over `x` if it is an array. + Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x + > hi", return "hi". Arguments are promoted to a common type. + Operates elementwise over "x" if it is an array. +``` """ clamp doc""" - abs(x) +```rst +abs(x) -Absolute value of `x` + Absolute value of "x" +``` """ abs doc""" - abs2(x) +```rst +abs2(x) -Squared absolute value of `x` + Squared absolute value of "x" +``` """ abs2 doc""" - copysign(x, y) +```rst +copysign(x, y) -Return `x` such that it has the same sign as `y` + Return "x" such that it has the same sign as "y" +``` """ copysign doc""" - sign(x) +```rst +sign(x) -Return `+1` if `x` is positive, `0` if `x == 0`, and `-1` -if `x` is negative. + Return "+1" if "x" is positive, "0" if "x == 0", and "-1" + if "x" is negative. +``` """ sign doc""" - signbit(x) +```rst +signbit(x) -Returns `true` if the value of the sign of `x` is negative, -otherwise `false`. + Returns "true" if the value of the sign of "x" is negative, + otherwise "false". +``` """ signbit doc""" - flipsign(x, y) +```rst +flipsign(x, y) -Return `x` with its sign flipped if `y` is negative. For -example `abs(x) = flipsign(x,x)`. + Return "x" with its sign flipped if "y" is negative. For + example "abs(x) = flipsign(x,x)". +``` """ flipsign doc""" - sqrt(x) +```rst +sqrt(x) -Return \sqrt{x}. Throws `DomainError` for negative `Real` -arguments. Use complex negative arguments instead. The prefix -operator `√` is equivalent to `sqrt`. + Return \sqrt{x}. Throws "DomainError" for negative "Real" + arguments. Use complex negative arguments instead. The prefix + operator "√" is equivalent to "sqrt". +``` """ sqrt doc""" - isqrt(n) +```rst +isqrt(n) -Integer square root: the largest integer `m` such that `m*m <= -n`. + Integer square root: the largest integer "m" such that "m*m <= + n". +``` """ isqrt doc""" - cbrt(x) +```rst +cbrt(x) -Return x^{1/3}. The prefix operator `∛` is equivalent to + Return x^{1/3}. The prefix operator "∛" is equivalent to + "cbrt". +``` """ cbrt doc""" - erf(x) +```rst +erf(x) -Compute the error function of `x`, defined by + Compute the error function of "x", defined by + \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex + "x". +``` """ erf doc""" - erfc(x) +```rst +erfc(x) -Compute the complementary error function of `x`, defined by 1 - + Compute the complementary error function of "x", defined by 1 - + \operatorname{erf}(x). +``` """ erfc doc""" - erfcx(x) +```rst +erfcx(x) -Compute the scaled complementary error function of `x`, defined -by e^{x^2} \operatorname{erfc}(x). Note also that + Compute the scaled complementary error function of "x", defined + by e^{x^2} \operatorname{erfc}(x). Note also that + \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). +``` """ erfcx doc""" - erfi(x) +```rst +erfi(x) -Compute the imaginary error function of `x`, defined by -i + Compute the imaginary error function of "x", defined by -i + \operatorname{erf}(ix). +``` """ erfi doc""" - dawson(x) +```rst +dawson(x) -Compute the Dawson function (scaled imaginary error function) of + Compute the Dawson function (scaled imaginary error function) of + "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} + \operatorname{erfi}(x). +``` """ dawson doc""" - erfinv(x) +```rst +erfinv(x) -Compute the inverse error function of a real `x`, defined by + Compute the inverse error function of a real "x", defined by + \operatorname{erf}(\operatorname{erfinv}(x)) = x. +``` """ erfinv doc""" - erfcinv(x) +```rst +erfcinv(x) -Compute the inverse error complementary function of a real `x`, -defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. + Compute the inverse error complementary function of a real "x", + defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. +``` """ erfcinv doc""" - real(z) +```rst +real(z) -Return the real part of the complex number `z` + Return the real part of the complex number "z" +``` """ real doc""" - imag(z) +```rst +imag(z) -Return the imaginary part of the complex number `z` + Return the imaginary part of the complex number "z" +``` """ imag doc""" - reim(z) +```rst +reim(z) -Return both the real and imaginary parts of the complex number + Return both the real and imaginary parts of the complex number + "z" +``` """ reim doc""" - conj(z) +```rst +conj(z) -Compute the complex conjugate of a complex number `z` + Compute the complex conjugate of a complex number "z" +``` """ conj doc""" - angle(z) +```rst +angle(z) -Compute the phase angle in radians of a complex number `z` + Compute the phase angle in radians of a complex number "z" +``` """ angle doc""" - cis(z) +```rst +cis(z) -Return \exp(iz). + Return \exp(iz). +``` """ cis doc""" - binomial(n, k) +```rst +binomial(n, k) -Number of ways to choose `k` out of `n` items + Number of ways to choose "k" out of "n" items +``` """ binomial doc""" - factorial(n) +```rst +factorial(n) -Factorial of `n`. If `n` is an `Integer`, the factorial is -computed as an integer (promoted to at least 64 bits). Note that -this may overflow if `n` is not small, but you can use -precision. If `n` is not an `Integer`, `factorial(n)` is -equivalent to `gamma(n+1)`. + Factorial of "n". If "n" is an "Integer", the factorial is + computed as an integer (promoted to at least 64 bits). Note that + this may overflow if "n" is not small, but you can use + "factorial(big(n))" to compute the result exactly in arbitrary + precision. If "n" is not an "Integer", "factorial(n)" is + equivalent to "gamma(n+1)". +``` """ factorial doc""" - factorial(n, k) +```rst +factorial(n, k) -Compute `factorial(n)/factorial(k)` + Compute "factorial(n)/factorial(k)" +``` """ factorial doc""" - factor(n) -> Dict +```rst +factor(n) -> Dict -Compute the prime factorization of an integer `n`. Returns a -dictionary. The keys of the dictionary correspond to the factors, -and hence are of the same type as `n`. The value associated with -each key indicates the number of times the factor appears in the -factorization. + Compute the prime factorization of an integer "n". Returns a + dictionary. The keys of the dictionary correspond to the factors, + and hence are of the same type as "n". The value associated with + each key indicates the number of times the factor appears in the + factorization. + + julia> factor(100) # == 2*2*5*5 + Dict{Int64,Int64} with 2 entries: + 2 => 2 + 5 => 2 +``` """ factor doc""" - gcd(x, y) +```rst +gcd(x, y) -Greatest common (positive) divisor (or zero if x and y are both -zero). + Greatest common (positive) divisor (or zero if x and y are both + zero). +``` """ gcd doc""" - lcm(x, y) +```rst +lcm(x, y) -Least common (non-negative) multiple. + Least common (non-negative) multiple. +``` """ lcm doc""" - gcdx(x, y) +```rst +gcdx(x, y) + + Computes the greatest common (positive) divisor of "x" and "y" + and their Bézout coefficients, i.e. the integer coefficients "u" + and "v" that satisfy ux+vy = d = gcd(x,y). -Computes the greatest common (positive) divisor of `x` and `y` -and their Bézout coefficients, i.e. the integer coefficients `u` -and `v` that satisfy ux+vy = d = gcd(x,y). -Note: Bézout coefficients are *not* uniquely defined. `gcdx` + julia> gcdx(12, 42) + (6,-3,1) + + julia> gcdx(240, 46) + (2,-9,47) + + Note: Bézout coefficients are *not* uniquely defined. "gcdx" + returns the minimal Bézout coefficients that are computed by the + extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, + Algorithm X.) These coefficients "u" and "v" are minimal in + the sense that |u| < |\frac y d and |v| < |\frac x d. + Furthermore, the signs of "u" and "v" are chosen so that + "d" is positive. +``` """ gcdx doc""" - ispow2(n) -> Bool +```rst +ispow2(n) -> Bool -Test whether `n` is a power of two + Test whether "n" is a power of two +``` """ ispow2 doc""" - nextpow2(n) +```rst +nextpow2(n) -The smallest power of two not less than `n`. Returns 0 for + The smallest power of two not less than "n". Returns 0 for + "n==0", and returns "-nextpow2(-n)" for negative arguments. +``` """ nextpow2 doc""" - prevpow2(n) +```rst +prevpow2(n) -The largest power of two not greater than `n`. Returns 0 for + The largest power of two not greater than "n". Returns 0 for + "n==0", and returns "-prevpow2(-n)" for negative arguments. +``` """ prevpow2 doc""" - nextpow(a, x) +```rst +nextpow(a, x) -The smallest `a^n` not less than `x`, where `n` is a non- -negative integer. `a` must be greater than 1, and `x` must be -greater than 0. + The smallest "a^n" not less than "x", where "n" is a non- + negative integer. "a" must be greater than 1, and "x" must be + greater than 0. +``` """ nextpow doc""" - prevpow(a, x) +```rst +prevpow(a, x) -The largest `a^n` not greater than `x`, where `n` is a non- -negative integer. `a` must be greater than 1, and `x` must not -be less than 1. + The largest "a^n" not greater than "x", where "n" is a non- + negative integer. "a" must be greater than 1, and "x" must not + be less than 1. +``` """ prevpow doc""" - nextprod([k_1, k_2, ...], n) +```rst +nextprod([k_1, k_2, ...], n) -Next integer not less than `n` that can be written as \prod -k_i^{p_i} for integers p_1, p_2, etc. + Next integer not less than "n" that can be written as \prod + k_i^{p_i} for integers p_1, p_2, etc. +``` """ nextprod doc""" - prevprod([k_1, k_2, ...], n) +```rst +prevprod([k_1, k_2, ...], n) -Previous integer not greater than `n` that can be written as + Previous integer not greater than "n" that can be written as + \prod k_i^{p_i} for integers p_1, p_2, etc. +``` """ prevprod doc""" - invmod(x, m) +```rst +invmod(x, m) -Take the inverse of `x` modulo `m`: `y` such that xy = 1 + Take the inverse of "x" modulo "m": "y" such that xy = 1 + \pmod m +``` """ invmod doc""" - powermod(x, p, m) +```rst +powermod(x, p, m) -Compute x^p \pmod m + Compute x^p \pmod m +``` """ powermod doc""" - gamma(x) +```rst +gamma(x) -Compute the gamma function of `x` + Compute the gamma function of "x" +``` """ gamma doc""" - lgamma(x) +```rst +lgamma(x) -Compute the logarithm of the absolute value of `gamma()` for -logarithm of `gamma(x)`. + Compute the logarithm of the absolute value of "gamma()" for + "Real" "x", while for "Complex" "x" it computes the + logarithm of "gamma(x)". +``` """ lgamma doc""" - lfact(x) +```rst +lfact(x) -Compute the logarithmic factorial of `x` + Compute the logarithmic factorial of "x" +``` """ lfact doc""" - digamma(x) +```rst +digamma(x) -Compute the digamma function of `x` (the logarithmic derivative -of `gamma(x)`) + Compute the digamma function of "x" (the logarithmic derivative + of "gamma(x)") +``` """ digamma doc""" - invdigamma(x) +```rst +invdigamma(x) -Compute the inverse digamma function of `x`. + Compute the inverse digamma function of "x". +``` """ invdigamma doc""" - trigamma(x) +```rst +trigamma(x) -Compute the trigamma function of `x` (the logarithmic second -derivative of `gamma(x)`) + Compute the trigamma function of "x" (the logarithmic second + derivative of "gamma(x)") +``` """ trigamma doc""" - polygamma(m, x) +```rst +polygamma(m, x) -Compute the polygamma function of order `m` of argument `x` + Compute the polygamma function of order "m" of argument "x" + (the "(m+1)th" derivative of the logarithm of "gamma(x)") +``` """ polygamma doc""" - airy(k, x) +```rst +airy(k, x) -kth derivative of the Airy function \operatorname{Ai}(x). + kth derivative of the Airy function \operatorname{Ai}(x). +``` """ airy doc""" - airyai(x) +```rst +airyai(x) -Airy function \operatorname{Ai}(x). + Airy function \operatorname{Ai}(x). +``` """ airyai doc""" - airyprime(x) +```rst +airyprime(x) -Airy function derivative \operatorname{Ai}'(x). + Airy function derivative \operatorname{Ai}'(x). +``` """ airyprime doc""" - airyaiprime(x) +```rst +airyaiprime(x) -Airy function derivative \operatorname{Ai}'(x). + Airy function derivative \operatorname{Ai}'(x). +``` """ airyaiprime doc""" - airybi(x) +```rst +airybi(x) -Airy function \operatorname{Bi}(x). + Airy function \operatorname{Bi}(x). +``` """ airybi doc""" - airybiprime(x) +```rst +airybiprime(x) -Airy function derivative \operatorname{Bi}'(x). + Airy function derivative \operatorname{Bi}'(x). +``` """ airybiprime doc""" - airyx(k, x) +```rst +airyx(k, x) -scaled kth derivative of the Airy function, return -k == 1`, and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} -k == 3`. + scaled kth derivative of the Airy function, return + \operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || + k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} + \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || + k == 3". +``` """ airyx doc""" - besselj0(x) +```rst +besselj0(x) -Bessel function of the first kind of order 0, J_0(x). + Bessel function of the first kind of order 0, J_0(x). +``` """ besselj0 doc""" - besselj1(x) +```rst +besselj1(x) -Bessel function of the first kind of order 1, J_1(x). + Bessel function of the first kind of order 1, J_1(x). +``` """ besselj1 doc""" - besselj(nu, x) +```rst +besselj(nu, x) -Bessel function of the first kind of order `nu`, J_\nu(x). + Bessel function of the first kind of order "nu", J_\nu(x). +``` """ besselj doc""" - besseljx(nu, x) +```rst +besseljx(nu, x) -Scaled Bessel function of the first kind of order `nu`, J_\nu(x) -e^{- | \operatorname{Im}(x) |}. + Scaled Bessel function of the first kind of order "nu", J_\nu(x) + e^{- | \operatorname{Im}(x) |}. +``` """ besseljx doc""" - bessely0(x) +```rst +bessely0(x) -Bessel function of the second kind of order 0, Y_0(x). + Bessel function of the second kind of order 0, Y_0(x). +``` """ bessely0 doc""" - bessely1(x) +```rst +bessely1(x) -Bessel function of the second kind of order 1, Y_1(x). + Bessel function of the second kind of order 1, Y_1(x). +``` """ bessely1 doc""" - bessely(nu, x) +```rst +bessely(nu, x) -Bessel function of the second kind of order `nu`, Y_\nu(x). + Bessel function of the second kind of order "nu", Y_\nu(x). +``` """ bessely doc""" - besselyx(nu, x) +```rst +besselyx(nu, x) -Scaled Bessel function of the second kind of order `nu`, -Y_\nu(x) e^{- | \operatorname{Im}(x) |}. + Scaled Bessel function of the second kind of order "nu", + Y_\nu(x) e^{- | \operatorname{Im}(x) |}. +``` """ besselyx doc""" - hankelh1(nu, x) +```rst +hankelh1(nu, x) -Bessel function of the third kind of order `nu`, H^{(1)}_\nu(x). + Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). +``` """ hankelh1 doc""" - hankelh1x(nu, x) +```rst +hankelh1x(nu, x) -Scaled Bessel function of the third kind of order `nu`, -H^{(1)}_\nu(x) e^{-x i}. + Scaled Bessel function of the third kind of order "nu", + H^{(1)}_\nu(x) e^{-x i}. +``` """ hankelh1x doc""" - hankelh2(nu, x) +```rst +hankelh2(nu, x) -Bessel function of the third kind of order `nu`, H^{(2)}_\nu(x). + Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). +``` """ hankelh2 doc""" - hankelh2x(nu, x) +```rst +hankelh2x(nu, x) -Scaled Bessel function of the third kind of order `nu`, -H^{(2)}_\nu(x) e^{x i}. + Scaled Bessel function of the third kind of order "nu", + H^{(2)}_\nu(x) e^{x i}. +``` """ hankelh2x doc""" - besselh(nu, k, x) +```rst +besselh(nu, k, x) -Bessel function of the third kind of order `nu` (Hankel -function). `k` is either 1 or 2, selecting `hankelh1` or + Bessel function of the third kind of order "nu" (Hankel + function). "k" is either 1 or 2, selecting "hankelh1" or + "hankelh2", respectively. +``` """ besselh doc""" - besseli(nu, x) +```rst +besseli(nu, x) -Modified Bessel function of the first kind of order `nu`, -I_\nu(x). + Modified Bessel function of the first kind of order "nu", + I_\nu(x). +``` """ besseli doc""" - besselix(nu, x) +```rst +besselix(nu, x) -Scaled modified Bessel function of the first kind of order `nu`, -I_\nu(x) e^{- | \operatorname{Re}(x) |}. + Scaled modified Bessel function of the first kind of order "nu", + I_\nu(x) e^{- | \operatorname{Re}(x) |}. +``` """ besselix doc""" - besselk(nu, x) +```rst +besselk(nu, x) -Modified Bessel function of the second kind of order `nu`, -K_\nu(x). + Modified Bessel function of the second kind of order "nu", + K_\nu(x). +``` """ besselk doc""" - besselkx(nu, x) +```rst +besselkx(nu, x) -Scaled modified Bessel function of the second kind of order `nu`, -K_\nu(x) e^x. + Scaled modified Bessel function of the second kind of order "nu", + K_\nu(x) e^x. +``` """ besselkx doc""" - beta(x, y) +```rst +beta(x, y) -Euler integral of the first kind \operatorname{B}(x,y) = + Euler integral of the first kind \operatorname{B}(x,y) = + \Gamma(x)\Gamma(y)/\Gamma(x+y). +``` """ beta doc""" - lbeta(x, y) +```rst +lbeta(x, y) -Natural logarithm of the absolute value of the beta function + Natural logarithm of the absolute value of the beta function + \log(|\operatorname{B}(x,y)|). +``` """ lbeta doc""" - eta(x) +```rst +eta(x) -Dirichlet eta function \eta(s) = + Dirichlet eta function \eta(s) = + \sum^\infty_{n=1}(-)^{n-1}/n^{s}. +``` """ eta doc""" - zeta(s) +```rst +zeta(s) -Riemann zeta function \zeta(s). + Riemann zeta function \zeta(s). +``` """ zeta doc""" - zeta(s, z) +```rst +zeta(s, z) -Hurwitz zeta function \zeta(s, z). (This is equivalent to the -Riemann zeta function \zeta(s) for the case of `z=1`.) + Hurwitz zeta function \zeta(s, z). (This is equivalent to the + Riemann zeta function \zeta(s) for the case of "z=1".) +``` """ zeta doc""" - ndigits(n, b) +```rst +ndigits(n, b) -Compute the number of digits in number `n` written in base `b`. + Compute the number of digits in number "n" written in base "b". +``` """ ndigits doc""" - widemul(x, y) +```rst +widemul(x, y) -Multiply `x` and `y`, giving the result as a larger type. + Multiply "x" and "y", giving the result as a larger type. +``` """ widemul doc""" - @evalpoly(z, c...) +```rst +@evalpoly(z, c...) -Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients -ascending order by power of `z`. This macro expands to efficient -inline code that uses either Horner's method or, for complex `z`, -a more efficient Goertzel-like algorithm. + Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients + "c[1]", "c[2]", ...; that is, the coefficients are given in + ascending order by power of "z". This macro expands to efficient + inline code that uses either Horner's method or, for complex "z", + a more efficient Goertzel-like algorithm. +``` """ @evalpoly doc""" - mean(v[, region]) +```rst +mean(v[, region]) -Compute the mean of whole array `v`, or optionally along the -dimensions in `region`. Note: Julia does not ignore `NaN` -values in the computation. For applications requiring the handling -of missing data, the `DataArray` package is recommended. + Compute the mean of whole array "v", or optionally along the + dimensions in "region". Note: Julia does not ignore "NaN" + values in the computation. For applications requiring the handling + of missing data, the "DataArray" package is recommended. +``` """ mean doc""" - mean!(r, v) +```rst +mean!(r, v) -Compute the mean of `v` over the singleton dimensions of `r`, -and write results to `r`. + Compute the mean of "v" over the singleton dimensions of "r", + and write results to "r". +``` """ mean! doc""" - std(v[, region]) +```rst +std(v[, region]) -Compute the sample standard deviation of a vector or array `v`, -optionally along dimensions in `region`. The algorithm returns an -estimator of the generative distribution's standard deviation under -the assumption that each entry of `v` is an IID drawn from that -generative distribution. This computation is equivalent to -calculating `sqrt(sum((v - mean(v)).^2) / (length(v) - 1))`. -Note: Julia does not ignore `NaN` values in the computation. For -applications requiring the handling of missing data, the + Compute the sample standard deviation of a vector or array "v", + optionally along dimensions in "region". The algorithm returns an + estimator of the generative distribution's standard deviation under + the assumption that each entry of "v" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". + Note: Julia does not ignore "NaN" values in the computation. For + applications requiring the handling of missing data, the + "DataArray" package is recommended. +``` """ std doc""" - stdm(v, m) +```rst +stdm(v, m) -Compute the sample standard deviation of a vector `v` with known -mean `m`. Note: Julia does not ignore `NaN` values in the -computation. + Compute the sample standard deviation of a vector "v" with known + mean "m". Note: Julia does not ignore "NaN" values in the + computation. +``` """ stdm doc""" - var(v[, region]) +```rst +var(v[, region]) -Compute the sample variance of a vector or array `v`, optionally -along dimensions in `region`. The algorithm will return an -estimator of the generative distribution's variance under the -assumption that each entry of `v` is an IID drawn from that -generative distribution. This computation is equivalent to -calculating `sum((v - mean(v)).^2) / (length(v) - 1)`. Note: -Julia does not ignore `NaN` values in the computation. For -applications requiring the handling of missing data, the + Compute the sample variance of a vector or array "v", optionally + along dimensions in "region". The algorithm will return an + estimator of the generative distribution's variance under the + assumption that each entry of "v" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: + Julia does not ignore "NaN" values in the computation. For + applications requiring the handling of missing data, the + "DataArray" package is recommended. +``` """ var doc""" - varm(v, m) +```rst +varm(v, m) -Compute the sample variance of a vector `v` with known mean -computation. + Compute the sample variance of a vector "v" with known mean + "m". Note: Julia does not ignore "NaN" values in the + computation. +``` """ varm doc""" - middle(x) +```rst +middle(x) -Compute the middle of a scalar value, which is equivalent to `x` -itself, but of the type of `middle(x, x)` for consistency. + Compute the middle of a scalar value, which is equivalent to "x" + itself, but of the type of "middle(x, x)" for consistency. +``` """ middle doc""" - middle(x, y) +```rst +middle(x, y) -Compute the middle of two reals `x` and `y`, which is -equivalent in both value and type to computing their mean (`(x + -y) / 2`). + Compute the middle of two reals "x" and "y", which is + equivalent in both value and type to computing their mean ("(x + + y) / 2"). +``` """ middle doc""" - middle(range) +```rst +middle(range) -Compute the middle of a range, which consists in computing the mean -of its extrema. Since a range is sorted, the mean is performed with -the first and last element. + Compute the middle of a range, which consists in computing the mean + of its extrema. Since a range is sorted, the mean is performed with + the first and last element. +``` """ middle doc""" - middle(array) +```rst +middle(array) -Compute the middle of an array, which consists in finding its -extrema and then computing their mean. + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. +``` """ middle doc""" - median(v) +```rst +median(v) -Compute the median of a vector `v`. `NaN` is returned if the -data contains any `NaN` values. For applications requiring the -handling of missing data, the `DataArrays` package is -recommended. + Compute the median of a vector "v". "NaN" is returned if the + data contains any "NaN" values. For applications requiring the + handling of missing data, the "DataArrays" package is + recommended. +``` """ median doc""" - median!(v) +```rst +median!(v) -Like `median`, but may overwrite the input vector. + Like "median", but may overwrite the input vector. +``` """ median! doc""" - hist(v[, n]) -> e, counts +```rst +hist(v[, n]) -> e, counts -Compute the histogram of `v`, optionally using approximately -to the edges of the bins, and `counts` containing the number of -elements of `v` in each bin. Note: Julia does not ignore `NaN` -values in the computation. + Compute the histogram of "v", optionally using approximately + "n" bins. The return values are a range "e", which correspond + to the edges of the bins, and "counts" containing the number of + elements of "v" in each bin. Note: Julia does not ignore "NaN" + values in the computation. +``` """ hist doc""" - hist(v, e) -> e, counts +```rst +hist(v, e) -> e, counts -Compute the histogram of `v` using a vector/range `e` as the -edges for the bins. The result will be a vector of length -satisfies `sum(e[i] .< v .<= e[i+1])`. Note: Julia does not -ignore `NaN` values in the computation. + Compute the histogram of "v" using a vector/range "e" as the + edges for the bins. The result will be a vector of length + "length(e) - 1", such that the element at location "i" + satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not + ignore "NaN" values in the computation. +``` """ hist doc""" - hist!(counts, v, e) -> e, counts +```rst +hist!(counts, v, e) -> e, counts -Compute the histogram of `v`, using a vector/range `e` as the -edges for the bins. This function writes the resultant counts to a -pre-allocated array `counts`. + Compute the histogram of "v", using a vector/range "e" as the + edges for the bins. This function writes the resultant counts to a + pre-allocated array "counts". +``` """ hist! doc""" - hist2d(M, e1, e2) -> (edge1, edge2, counts) +```rst +hist2d(M, e1, e2) -> (edge1, edge2, counts) -Compute a `2d histogram` of a set of N points specified by N-by-2 -matrix `M`. Arguments `e1` and `e2` are bins for each -dimension, specified either as integer bin counts or vectors of bin -edges. The result is a tuple of `edge1` (the bin edges used in -the first dimension), `edge2` (the bin edges used in the second -dimension), and `counts`, a histogram matrix of size + Compute a "2d histogram" of a set of N points specified by N-by-2 + matrix "M". Arguments "e1" and "e2" are bins for each + dimension, specified either as integer bin counts or vectors of bin + edges. The result is a tuple of "edge1" (the bin edges used in + the first dimension), "edge2" (the bin edges used in the second + dimension), and "counts", a histogram matrix of size + "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore + "NaN" values in the computation. +``` """ hist2d doc""" - hist2d!(counts, M, e1, e2) -> (e1, e2, counts) +```rst +hist2d!(counts, M, e1, e2) -> (e1, e2, counts) -Compute a `2d histogram` with respect to the bins delimited by -the edges given in `e1` and `e2`. This function writes the -results to a pre-allocated array `counts`. + Compute a "2d histogram" with respect to the bins delimited by + the edges given in "e1" and "e2". This function writes the + results to a pre-allocated array "counts". +``` """ hist2d! doc""" - histrange(v, n) +```rst +histrange(v, n) -Compute *nice* bin ranges for the edges of a histogram of `v`, -using approximately `n` bins. The resulting step sizes will be 1, -2 or 5 multiplied by a power of 10. Note: Julia does not ignore + Compute *nice* bin ranges for the edges of a histogram of "v", + using approximately "n" bins. The resulting step sizes will be 1, + 2 or 5 multiplied by a power of 10. Note: Julia does not ignore + "NaN" values in the computation. +``` """ histrange doc""" - midpoints(e) +```rst +midpoints(e) -Compute the midpoints of the bins with edges `e`. The result is a -vector/range of length `length(e) - 1`. Note: Julia does not -ignore `NaN` values in the computation. + Compute the midpoints of the bins with edges "e". The result is a + vector/range of length "length(e) - 1". Note: Julia does not + ignore "NaN" values in the computation. +``` """ midpoints doc""" - quantile(v, p) +```rst +quantile(v, p) -Compute the quantiles of a vector `v` at a specified set of -probability values `p`. Note: Julia does not ignore `NaN` -values in the computation. + Compute the quantiles of a vector "v" at a specified set of + probability values "p". Note: Julia does not ignore "NaN" + values in the computation. +``` """ quantile doc""" - quantile(v, p) +```rst +quantile(v, p) -Compute the quantile of a vector `v` at the probability `p`. -Note: Julia does not ignore `NaN` values in the computation. + Compute the quantile of a vector "v" at the probability "p". + Note: Julia does not ignore "NaN" values in the computation. +``` """ quantile doc""" - quantile!(v, p) +```rst +quantile!(v, p) -Like `quantile`, but overwrites the input vector. + Like "quantile", but overwrites the input vector. +``` """ quantile! doc""" - cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) +```rst +cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + + Compute the Pearson covariance between the vector(s) in "v1" and + "v2". Here, "v1" and "v2" can be either vectors or matrices. -Compute the Pearson covariance between the vector(s) in `v1` and -This function accepts three keyword arguments: -The size of the result depends on the size of `v1` and `v2`. -When both `v1` and `v2` are vectors, it returns the covariance -between them as a scalar. When either one is a matrix, it returns a -covariance matrix of size `(n1, n2)`, where `n1` and `n2` are -the numbers of slices in `v1` and `v2`, which depend on the -setting of `vardim`. -Note: `v2` can be omitted, which indicates `v2 = v1`. + This function accepts three keyword arguments: + + * "vardim": the dimension of variables. When "vardim = 1", + variables are considered in columns while observations in rows; + when "vardim = 2", variables are in rows while observations in + columns. By default, it is set to "1". + + * "corrected": whether to apply Bessel's correction (divide by + "n-1" instead of "n"). By default, it is set to "true". + + * "mean": allow users to supply mean values that are known. By + default, it is set to "nothing", which indicates that the + mean(s) are unknown, and the function will compute the mean. + Users can use "mean=0" to indicate that the input data are + centered, and hence there's no need to subtract the mean. + + The size of the result depends on the size of "v1" and "v2". + When both "v1" and "v2" are vectors, it returns the covariance + between them as a scalar. When either one is a matrix, it returns a + covariance matrix of size "(n1, n2)", where "n1" and "n2" are + the numbers of slices in "v1" and "v2", which depend on the + setting of "vardim". + + Note: "v2" can be omitted, which indicates "v2 = v1". +``` """ cov doc""" - cor(v1[, v2][, vardim=1, mean=nothing]) +```rst +cor(v1[, v2][, vardim=1, mean=nothing]) + + Compute the Pearson correlation between the vector(s) in "v1" and + "v2". -Compute the Pearson correlation between the vector(s) in `v1` and -Users can use the keyword argument `vardim` to specify the -variable dimension, and `mean` to supply pre-computed mean -values. + Users can use the keyword argument "vardim" to specify the + variable dimension, and "mean" to supply pre-computed mean + values. +``` """ cor doc""" - fft(A[, dims]) +```rst +fft(A[, dims]) -Performs a multidimensional FFT of the array `A`. The optional -an integer, range, tuple, or array) to transform along. Most -efficient if the size of `A` along the transformed dimensions is -a product of small primes; see `nextprod()`. See also -A one-dimensional FFT computes the one-dimensional discrete Fourier -transform (DFT) as defined by -A multidimensional FFT simply performs this operation along each -transformed dimension of `A`. -Higher performance is usually possible with multi-threading. Use -processors. + Performs a multidimensional FFT of the array "A". The optional + "dims" argument specifies an iterable subset of dimensions (e.g. + an integer, range, tuple, or array) to transform along. Most + efficient if the size of "A" along the transformed dimensions is + a product of small primes; see "nextprod()". See also + "plan_fft()" for even greater efficiency. + + A one-dimensional FFT computes the one-dimensional discrete Fourier + transform (DFT) as defined by + + \operatorname{DFT}(A)[k] = + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(-i\frac{2\pi + (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. + + A multidimensional FFT simply performs this operation along each + transformed dimension of "A". + + Higher performance is usually possible with multi-threading. Use + *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* + processors. +``` """ fft doc""" - fft!(A[, dims]) +```rst +fft!(A[, dims]) -Same as `fft()`, but operates in-place on `A`, which must be an -array of complex floating-point numbers. + Same as "fft()", but operates in-place on "A", which must be an + array of complex floating-point numbers. +``` """ fft! doc""" - ifft(A[, dims]) +```rst +ifft(A[, dims]) + + Multidimensional inverse FFT. + + A one-dimensional inverse FFT computes -Multidimensional inverse FFT. -A one-dimensional inverse FFT computes -A multidimensional inverse FFT simply performs this operation along -each transformed dimension of `A`. + \operatorname{IDFT}(A)[k] = + \frac{1}{\operatorname{length}(A)} + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(+i\frac{2\pi (n-1)(k-1)} + {\operatorname{length}(A)} \right) A[n]. + + A multidimensional inverse FFT simply performs this operation along + each transformed dimension of "A". +``` """ ifft doc""" - ifft!(A[, dims]) +```rst +ifft!(A[, dims]) -Same as `ifft()`, but operates in-place on `A`. + Same as "ifft()", but operates in-place on "A". +``` """ ifft! doc""" - bfft(A[, dims]) +```rst +bfft(A[, dims]) + + Similar to "ifft()", but computes an unnormalized inverse + (backward) transform, which must be divided by the product of the + sizes of the transformed dimensions in order to obtain the inverse. + (This is slightly more efficient than "ifft()" because it omits a + scaling step, which in some applications can be combined with other + computational steps elsewhere.) -Similar to `ifft()`, but computes an unnormalized inverse -sizes of the transformed dimensions in order to obtain the inverse. -scaling step, which in some applications can be combined with other -computational steps elsewhere.) + \operatorname{BDFT}(A)[k] = \operatorname{length}(A) + \operatorname{IDFT}(A)[k] +``` """ bfft doc""" - bfft!(A[, dims]) +```rst +bfft!(A[, dims]) -Same as `bfft()`, but operates in-place on `A`. + Same as "bfft()", but operates in-place on "A". +``` """ bfft! doc""" - plan_fft(A[, dims[, flags[, timelimit]]]) +```rst +plan_fft(A[, dims[, flags[, timelimit]]]) + + Pre-plan an optimized FFT along given dimensions ("dims") of + arrays matching the shape and type of "A". (The first two + arguments have the same meaning as for "fft()".) Returns a + function "plan(A)" that computes "fft(A, dims)" quickly. -Pre-plan an optimized FFT along given dimensions (`dims`) of -arrays matching the shape and type of `A`. (The first two -arguments have the same meaning as for `fft()`.) Returns a -function `plan(A)` that computes `fft(A, dims)` quickly. -The `flags` argument is a bitwise-or of FFTW planner flags, -defaulting to `FFTW.ESTIMATE`. e.g. passing `FFTW.MEASURE` or -benchmarking different possible FFT algorithms and picking the -fastest one; see the FFTW manual for more information on planner -flags. The optional `timelimit` argument specifies a rough upper -bound on the allowed planning time, in seconds. Passing -that operates in-place on its argument (which must be an array of -complex floating-point numbers). `plan_ifft()` and so on are -similar but produce plans that perform the equivalent of the -inverse transforms `ifft()` and so on. + The "flags" argument is a bitwise-or of FFTW planner flags, + defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or + "FFTW.PATIENT" will instead spend several seconds (or more) + benchmarking different possible FFT algorithms and picking the + fastest one; see the FFTW manual for more information on planner + flags. The optional "timelimit" argument specifies a rough upper + bound on the allowed planning time, in seconds. Passing + "FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array + "A" to be overwritten with zeros during plan creation. + + "plan_fft!()" is the same as "plan_fft()" but creates a plan + that operates in-place on its argument (which must be an array of + complex floating-point numbers). "plan_ifft()" and so on are + similar but produce plans that perform the equivalent of the + inverse transforms "ifft()" and so on. +``` """ plan_fft doc""" - plan_ifft(A[, dims[, flags[, timelimit]]]) +```rst +plan_ifft(A[, dims[, flags[, timelimit]]]) -Same as `plan_fft()`, but produces a plan that performs inverse -transforms `ifft()`. + Same as "plan_fft()", but produces a plan that performs inverse + transforms "ifft()". +``` """ plan_ifft doc""" - plan_bfft(A[, dims[, flags[, timelimit]]]) +```rst +plan_bfft(A[, dims[, flags[, timelimit]]]) -Same as `plan_fft()`, but produces a plan that performs an -unnormalized backwards transform `bfft()`. + Same as "plan_fft()", but produces a plan that performs an + unnormalized backwards transform "bfft()". +``` """ plan_bfft doc""" - plan_fft!(A[, dims[, flags[, timelimit]]]) +```rst +plan_fft!(A[, dims[, flags[, timelimit]]]) -Same as `plan_fft()`, but operates in-place on `A`. + Same as "plan_fft()", but operates in-place on "A". +``` """ plan_fft! doc""" - plan_ifft!(A[, dims[, flags[, timelimit]]]) +```rst +plan_ifft!(A[, dims[, flags[, timelimit]]]) -Same as `plan_ifft()`, but operates in-place on `A`. + Same as "plan_ifft()", but operates in-place on "A". +``` """ plan_ifft! doc""" - plan_bfft!(A[, dims[, flags[, timelimit]]]) +```rst +plan_bfft!(A[, dims[, flags[, timelimit]]]) -Same as `plan_bfft()`, but operates in-place on `A`. + Same as "plan_bfft()", but operates in-place on "A". +``` """ plan_bfft! doc""" - rfft(A[, dims]) +```rst +rfft(A[, dims]) + + Multidimensional FFT of a real array A, exploiting the fact that + the transform has conjugate symmetry in order to save roughly half + the computational time and storage costs compared with "fft()". + If "A" has size "(n_1, ..., n_d)", the result has size + "(floor(n_1/2)+1, ..., n_d)". -Multidimensional FFT of a real array A, exploiting the fact that -the transform has conjugate symmetry in order to save roughly half -the computational time and storage costs compared with `fft()`. -If `A` has size `(n_1, ..., n_d)`, the result has size -The optional `dims` argument specifies an iterable subset of one -or more dimensions of `A` to transform, similar to `fft()`. -Instead of (roughly) halving the first dimension of `A` in the -result, the `dims[1]` dimension is (roughly) halved in the same -way. + The optional "dims" argument specifies an iterable subset of one + or more dimensions of "A" to transform, similar to "fft()". + Instead of (roughly) halving the first dimension of "A" in the + result, the "dims[1]" dimension is (roughly) halved in the same + way. +``` """ rfft doc""" - irfft(A, d[, dims]) +```rst +irfft(A, d[, dims]) + + Inverse of "rfft()": for a complex array "A", gives the + corresponding real array whose FFT yields "A" in the first half. + As for "rfft()", "dims" is an optional subset of dimensions to + transform, defaulting to "1:ndims(A)". -Inverse of `rfft()`: for a complex array `A`, gives the -corresponding real array whose FFT yields `A` in the first half. -As for `rfft()`, `dims` is an optional subset of dimensions to -transform, defaulting to `1:ndims(A)`. -floor(size(A,dims[1])/2)+1`. (This parameter cannot be inferred -from `size(A)` due to the possibility of rounding by the + "d" is the length of the transformed real array along the + "dims[1]" dimension, which must satisfy "d == + floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred + from "size(A)" due to the possibility of rounding by the + "floor" function here.) +``` """ irfft doc""" - brfft(A, d[, dims]) +```rst +brfft(A, d[, dims]) -Similar to `irfft()` but computes an unnormalized inverse -transform (similar to `bfft()`), which must be divided by the -product of the sizes of the transformed dimensions (of the real -output array) in order to obtain the inverse transform. + Similar to "irfft()" but computes an unnormalized inverse + transform (similar to "bfft()"), which must be divided by the + product of the sizes of the transformed dimensions (of the real + output array) in order to obtain the inverse transform. +``` """ brfft doc""" - plan_rfft(A[, dims[, flags[, timelimit]]]) +```rst +plan_rfft(A[, dims[, flags[, timelimit]]]) -Pre-plan an optimized real-input FFT, similar to `plan_fft()` -except for `rfft()` instead of `fft()`. The first two -arguments, and the size of the transformed result, are the same as -for `rfft()`. + Pre-plan an optimized real-input FFT, similar to "plan_fft()" + except for "rfft()" instead of "fft()". The first two + arguments, and the size of the transformed result, are the same as + for "rfft()". +``` """ plan_rfft doc""" - plan_brfft(A, d[, dims[, flags[, timelimit]]]) +```rst +plan_brfft(A, d[, dims[, flags[, timelimit]]]) -Pre-plan an optimized real-input unnormalized transform, similar to -first two arguments and the size of the transformed result, are the -same as for `brfft()`. + Pre-plan an optimized real-input unnormalized transform, similar to + "plan_rfft()" except for "brfft()" instead of "rfft()". The + first two arguments and the size of the transformed result, are the + same as for "brfft()". +``` """ plan_brfft doc""" - plan_irfft(A, d[, dims[, flags[, timelimit]]]) +```rst +plan_irfft(A, d[, dims[, flags[, timelimit]]]) -Pre-plan an optimized inverse real-input FFT, similar to -respectively. The first three arguments have the same meaning as -for `irfft()`. + Pre-plan an optimized inverse real-input FFT, similar to + "plan_rfft()" except for "irfft()" and "brfft()", + respectively. The first three arguments have the same meaning as + for "irfft()". +``` """ plan_irfft doc""" - dct(A[, dims]) +```rst +dct(A[, dims]) -Performs a multidimensional type-II discrete cosine transform (DCT) -of the array `A`, using the unitary normalization of the DCT. The -optional `dims` argument specifies an iterable subset of -dimensions (e.g. an integer, range, tuple, or array) to transform -along. Most efficient if the size of `A` along the transformed -dimensions is a product of small primes; see `nextprod()`. See -also `plan_dct()` for even greater efficiency. + Performs a multidimensional type-II discrete cosine transform (DCT) + of the array "A", using the unitary normalization of the DCT. The + optional "dims" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. Most efficient if the size of "A" along the transformed + dimensions is a product of small primes; see "nextprod()". See + also "plan_dct()" for even greater efficiency. +``` """ dct doc""" - dct!(A[, dims]) +```rst +dct!(A[, dims]) -Same as `dct!()`, except that it operates in-place on `A`, -which must be an array of real or complex floating-point values. + Same as "dct!()", except that it operates in-place on "A", + which must be an array of real or complex floating-point values. +``` """ dct! doc""" - idct(A[, dims]) +```rst +idct(A[, dims]) -Computes the multidimensional inverse discrete cosine transform -unitary normalization). The optional `dims` argument specifies an -iterable subset of dimensions (e.g. an integer, range, tuple, or -array) to transform along. Most efficient if the size of `A` -along the transformed dimensions is a product of small primes; see -efficiency. + Computes the multidimensional inverse discrete cosine transform + (DCT) of the array "A" (technically, a type-III DCT with the + unitary normalization). The optional "dims" argument specifies an + iterable subset of dimensions (e.g. an integer, range, tuple, or + array) to transform along. Most efficient if the size of "A" + along the transformed dimensions is a product of small primes; see + "nextprod()". See also "plan_idct()" for even greater + efficiency. +``` """ idct doc""" - idct!(A[, dims]) +```rst +idct!(A[, dims]) -Same as `idct!()`, but operates in-place on `A`. + Same as "idct!()", but operates in-place on "A". +``` """ idct! doc""" - plan_dct(A[, dims[, flags[, timelimit]]]) +```rst +plan_dct(A[, dims[, flags[, timelimit]]]) -Pre-plan an optimized discrete cosine transform (DCT), similar to -The first two arguments have the same meaning as for `dct()`. + Pre-plan an optimized discrete cosine transform (DCT), similar to + "plan_fft()" except producing a function that computes "dct()". + The first two arguments have the same meaning as for "dct()". +``` """ plan_dct doc""" - plan_dct!(A[, dims[, flags[, timelimit]]]) +```rst +plan_dct!(A[, dims[, flags[, timelimit]]]) -Same as `plan_dct()`, but operates in-place on `A`. + Same as "plan_dct()", but operates in-place on "A". +``` """ plan_dct! doc""" - plan_idct(A[, dims[, flags[, timelimit]]]) +```rst +plan_idct(A[, dims[, flags[, timelimit]]]) -Pre-plan an optimized inverse discrete cosine transform (DCT), -similar to `plan_fft()` except producing a function that computes + Pre-plan an optimized inverse discrete cosine transform (DCT), + similar to "plan_fft()" except producing a function that computes + "idct()". The first two arguments have the same meaning as for + "idct()". +``` """ plan_idct doc""" - plan_idct!(A[, dims[, flags[, timelimit]]]) +```rst +plan_idct!(A[, dims[, flags[, timelimit]]]) -Same as `plan_idct()`, but operates in-place on `A`. + Same as "plan_idct()", but operates in-place on "A". +``` """ plan_idct! doc""" - fftshift(x) +```rst +fftshift(x) -Swap the first and second halves of each dimension of `x`. + Swap the first and second halves of each dimension of "x". +``` """ fftshift doc""" - fftshift(x, dim) +```rst +fftshift(x, dim) -Swap the first and second halves of the given dimension of array + Swap the first and second halves of the given dimension of array + "x". +``` """ fftshift doc""" - ifftshift(x[, dim]) +```rst +ifftshift(x[, dim]) -Undoes the effect of `fftshift`. + Undoes the effect of "fftshift". +``` """ ifftshift doc""" - filt(b, a, x[, si]) +```rst +filt(b, a, x[, si]) -Apply filter described by vectors `a` and `b` to vector `x`, -with an optional initial filter state vector `si` (defaults to -zeros). + Apply filter described by vectors "a" and "b" to vector "x", + with an optional initial filter state vector "si" (defaults to + zeros). +``` """ filt doc""" - filt!(out, b, a, x[, si]) +```rst +filt!(out, b, a, x[, si]) -Same as `filt()` but writes the result into the `out` argument, -which may alias the input `x` to modify it in-place. + Same as "filt()" but writes the result into the "out" argument, + which may alias the input "x" to modify it in-place. +``` """ filt! doc""" - deconv(b, a) +```rst +deconv(b, a) -Construct vector `c` such that `b = conv(a,c) + r`. Equivalent -to polynomial division. + Construct vector "c" such that "b = conv(a,c) + r". Equivalent + to polynomial division. +``` """ deconv doc""" - conv(u, v) +```rst +conv(u, v) -Convolution of two vectors. Uses FFT algorithm. + Convolution of two vectors. Uses FFT algorithm. +``` """ conv doc""" - conv2(u, v, A) +```rst +conv2(u, v, A) -2-D convolution of the matrix `A` with the 2-D separable kernel -generated by the vectors `u` and `v`. Uses 2-D FFT algorithm + 2-D convolution of the matrix "A" with the 2-D separable kernel + generated by the vectors "u" and "v". Uses 2-D FFT algorithm +``` """ conv2 doc""" - conv2(B, A) +```rst +conv2(B, A) -2-D convolution of the matrix `B` with the matrix `A`. Uses -2-D FFT algorithm + 2-D convolution of the matrix "B" with the matrix "A". Uses + 2-D FFT algorithm +``` """ conv2 doc""" - xcorr(u, v) +```rst +xcorr(u, v) -Compute the cross-correlation of two vectors. + Compute the cross-correlation of two vectors. +``` """ xcorr doc""" - r2r(A, kind[, dims]) +```rst +r2r(A, kind[, dims]) -Performs a multidimensional real-input/real-output (r2r) transform -of type `kind` of the array `A`, as defined in the FFTW manual. -types (`FFTW.REDFT00`, `FFTW.REDFT01`, `FFTW.REDFT10`, or -Hartley transform (`FFTW.DHT`). The `kind` argument may be an -array or tuple in order to specify different transform types along -the different dimensions of `A`; `kind[end]` is used for any -unspecified dimensions. See the FFTW manual for precise -definitions of these transform types, at http://www.fftw.org/doc. -The optional `dims` argument specifies an iterable subset of -dimensions (e.g. an integer, range, tuple, or array) to transform -along. `kind[i]` is then the transform type for `dims[i]`, with -See also `plan_r2r()` to pre-plan optimized r2r transforms. + Performs a multidimensional real-input/real-output (r2r) transform + of type "kind" of the array "A", as defined in the FFTW manual. + "kind" specifies either a discrete cosine transform of various + types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or + "FFTW.REDFT11"), a discrete sine transform of various types + ("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or + "FFTW.RODFT11"), a real-input DFT with halfcomplex-format output + ("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete + Hartley transform ("FFTW.DHT"). The "kind" argument may be an + array or tuple in order to specify different transform types along + the different dimensions of "A"; "kind[end]" is used for any + unspecified dimensions. See the FFTW manual for precise + definitions of these transform types, at http://www.fftw.org/doc. + + The optional "dims" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. "kind[i]" is then the transform type for "dims[i]", with + "kind[end]" being used for "i > length(kind)". + + See also "plan_r2r()" to pre-plan optimized r2r transforms. +``` """ Base.FFTW.r2r doc""" - r2r!(A, kind[, dims]) +```rst +r2r!(A, kind[, dims]) -Same as `r2r()`, but operates in-place on `A`, which must be an -array of real or complex floating-point numbers. + Same as "r2r()", but operates in-place on "A", which must be an + array of real or complex floating-point numbers. +``` """ Base.FFTW.r2r! doc""" - plan_r2r(A, kind[, dims[, flags[, timelimit]]]) +```rst +plan_r2r(A, kind[, dims[, flags[, timelimit]]]) -Pre-plan an optimized r2r transform, similar to `Base.plan_fft()` -except that the transforms (and the first three arguments) -correspond to `r2r()` and `r2r!()`, respectively. + Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" + except that the transforms (and the first three arguments) + correspond to "r2r()" and "r2r!()", respectively. +``` """ Base.FFTW.plan_r2r doc""" - plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) +```rst +plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) -Similar to `Base.plan_fft()`, but corresponds to `r2r!()`. + Similar to "Base.plan_fft()", but corresponds to "r2r!()". +``` """ Base.FFTW.plan_r2r! doc""" - quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - -Numerically integrate the function `f(x)` from `a` to `b`, -and optionally over additional intervals `b` to `c` and so on. -Keyword options include a relative error tolerance `reltol` -absolute error tolerance `abstol` (defaults to 0), a maximum -number of function evaluations `maxevals` (defaults to `10^7`), -and the `order` of the integration rule (defaults to 7). -Returns a pair `(I,E)` of the estimated integral `I` and an -estimated upper bound on the absolute error `E`. If `maxevals` -is not exceeded then `E <= max(abstol, reltol*norm(I))` will -hold. (Note that it is useful to specify a positive `abstol` in -cases where `norm(I)` may be zero.) -The endpoints `a` etcetera can also be complex (in which case the -integral is performed over straight-line segments in the complex -plane). If the endpoints are `BigFloat`, then the integration -will be performed in `BigFloat` precision as well (note: it is -advisable to increase the integration `order` in rough proportion -to the precision, for smooth integrands). More generally, the -precision is set by the precision of the integration endpoints -The integrand `f(x)` can return any numeric scalar, vector, or -matrix type, or in fact any type supporting `+`, `-`, -multiplication by real values, and a `norm` (i.e., any normed -vector space). Alternatively, a different norm can be specified by -passing a *norm*-like function as the *norm* keyword argument -multi-dimensional integration (cubature), there are many different -algorithms (often much better than simple nested 1d integrals) and -the optimal choice tends to be very problem-dependent. See the -Julia external-package listing for available algorithms for -multidimensional integration or other specialized tasks (such as -integrals of highly oscillatory or singular functions).] -The algorithm is an adaptive Gauss-Kronrod integration technique: -the integral in each interval is estimated using a Kronrod rule -Gauss rule (`order` points). The interval with the largest -error is then subdivided into two intervals and the process is -repeated until the desired error tolerance is achieved. -These quadrature rules work best for smooth functions within each -interval, so if your function has a known discontinuity or other -singularity, it is best to subdivide your interval to put the -singularity at an endpoint. For example, if `f` has a -discontinuity at `x=0.7` and you want to integrate from 0 to 1, -you should use `quadgk(f, 0,0.7,1)` to subdivide the interval at -the point of discontinuity. The integrand is never evaluated -exactly at the endpoints of the intervals, so it is possible to -integrate functions that diverge at the endpoints as long as the -singularity is integrable (for example, a `log(x)` or -For real-valued endpoints, the starting and/or ending points may be -infinite. (A coordinate transformation is performed internally to -map the infinite interval to a finite one.) +```rst +quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + + Numerically integrate the function "f(x)" from "a" to "b", + and optionally over additional intervals "b" to "c" and so on. + Keyword options include a relative error tolerance "reltol" + (defaults to "sqrt(eps)" in the precision of the endpoints), an + absolute error tolerance "abstol" (defaults to 0), a maximum + number of function evaluations "maxevals" (defaults to "10^7"), + and the "order" of the integration rule (defaults to 7). + + Returns a pair "(I,E)" of the estimated integral "I" and an + estimated upper bound on the absolute error "E". If "maxevals" + is not exceeded then "E <= max(abstol, reltol*norm(I))" will + hold. (Note that it is useful to specify a positive "abstol" in + cases where "norm(I)" may be zero.) + + The endpoints "a" etcetera can also be complex (in which case the + integral is performed over straight-line segments in the complex + plane). If the endpoints are "BigFloat", then the integration + will be performed in "BigFloat" precision as well (note: it is + advisable to increase the integration "order" in rough proportion + to the precision, for smooth integrands). More generally, the + precision is set by the precision of the integration endpoints + (promoted to floating-point types). + + The integrand "f(x)" can return any numeric scalar, vector, or + matrix type, or in fact any type supporting "+", "-", + multiplication by real values, and a "norm" (i.e., any normed + vector space). Alternatively, a different norm can be specified by + passing a *norm*-like function as the *norm* keyword argument + (which defaults to *vecnorm*). + + [Only one-dimensional integrals are provided by this function. For + multi-dimensional integration (cubature), there are many different + algorithms (often much better than simple nested 1d integrals) and + the optimal choice tends to be very problem-dependent. See the + Julia external-package listing for available algorithms for + multidimensional integration or other specialized tasks (such as + integrals of highly oscillatory or singular functions).] + + The algorithm is an adaptive Gauss-Kronrod integration technique: + the integral in each interval is estimated using a Kronrod rule + ("2*order+1" points) and the error is estimated using an embedded + Gauss rule ("order" points). The interval with the largest + error is then subdivided into two intervals and the process is + repeated until the desired error tolerance is achieved. + + These quadrature rules work best for smooth functions within each + interval, so if your function has a known discontinuity or other + singularity, it is best to subdivide your interval to put the + singularity at an endpoint. For example, if "f" has a + discontinuity at "x=0.7" and you want to integrate from 0 to 1, + you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at + the point of discontinuity. The integrand is never evaluated + exactly at the endpoints of the intervals, so it is possible to + integrate functions that diverge at the endpoints as long as the + singularity is integrable (for example, a "log(x)" or + "1/sqrt(x)" singularity). + + For real-valued endpoints, the starting and/or ending points may be + infinite. (A coordinate transformation is performed internally to + map the infinite interval to a finite one.) +``` """ quadgk doc""" - bin(n[, pad]) +```rst +bin(n[, pad]) -Convert an integer to a binary string, optionally specifying a -number of digits to pad to. + Convert an integer to a binary string, optionally specifying a + number of digits to pad to. +``` """ bin doc""" - hex(n[, pad]) +```rst +hex(n[, pad]) -Convert an integer to a hexadecimal string, optionally specifying a -number of digits to pad to. + Convert an integer to a hexadecimal string, optionally specifying a + number of digits to pad to. +``` """ hex doc""" - dec(n[, pad]) +```rst +dec(n[, pad]) -Convert an integer to a decimal string, optionally specifying a -number of digits to pad to. + Convert an integer to a decimal string, optionally specifying a + number of digits to pad to. +``` """ dec doc""" - oct(n[, pad]) +```rst +oct(n[, pad]) -Convert an integer to an octal string, optionally specifying a -number of digits to pad to. + Convert an integer to an octal string, optionally specifying a + number of digits to pad to. +``` """ oct doc""" - base(base, n[, pad]) +```rst +base(base, n[, pad]) -Convert an integer to a string in the given base, optionally -specifying a number of digits to pad to. The base can be specified -as either an integer, or as a `UInt8` array of character values -to use as digit symbols. + Convert an integer to a string in the given base, optionally + specifying a number of digits to pad to. The base can be specified + as either an integer, or as a "UInt8" array of character values + to use as digit symbols. +``` """ base doc""" - digits(n[, base][, pad]) +```rst +digits(n[, base][, pad]) -Returns an array of the digits of `n` in the given base, -optionally padded with zeros to a specified size. More significant -digits are at higher indexes, such that `n == -sum([digits[k]*base^(k-1) for k=1:length(digits)])`. + Returns an array of the digits of "n" in the given base, + optionally padded with zeros to a specified size. More significant + digits are at higher indexes, such that "n == + sum([digits[k]*base^(k-1) for k=1:length(digits)])". +``` """ digits doc""" - digits!(array, n[, base]) +```rst +digits!(array, n[, base]) -Fills an array of the digits of `n` in the given base. More -significant digits are at higher indexes. If the array length is -insufficient, the least significant digits are filled up to the -array length. If the array length is excessive, the excess portion -is filled with zeros. + Fills an array of the digits of "n" in the given base. More + significant digits are at higher indexes. If the array length is + insufficient, the least significant digits are filled up to the + array length. If the array length is excessive, the excess portion + is filled with zeros. +``` """ digits! doc""" - bits(n) +```rst +bits(n) -A string giving the literal bit representation of a number. + A string giving the literal bit representation of a number. +``` """ bits doc""" - parse(type, str[, base]) +```rst +parse(type, str[, base]) -Parse a string as a number. If the type is an integer type, then a -base can be specified (the default is 10). If the type is a -floating point type, the string is parsed as a decimal floating -point number. If the string does not contain a valid number, an -error is raised. + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. +``` """ parse doc""" - tryparse(type, str[, base]) +```rst +tryparse(type, str[, base]) -Like `parse`, but returns a `Nullable` of the requested type. -The result will be null if the string does not contain a valid -number. + Like "parse", but returns a "Nullable" of the requested type. + The result will be null if the string does not contain a valid + number. +``` """ tryparse doc""" - big(x) +```rst +big(x) -Convert a number to a maximum precision representation (typically -some pitfalls with floating-point numbers. + Convert a number to a maximum precision representation (typically + "BigInt" or "BigFloat"). See "BigFloat" for information about + some pitfalls with floating-point numbers. +``` """ big doc""" - signed(x) +```rst +signed(x) -Convert a number to a signed integer. If the argument is unsigned, -it is reinterpreted as signed without checking for overflow. + Convert a number to a signed integer. If the argument is unsigned, + it is reinterpreted as signed without checking for overflow. +``` """ signed doc""" - unsigned(x) -> Unsigned +```rst +unsigned(x) -> Unsigned -Convert a number to an unsigned integer. If the argument is signed, -it is reinterpreted as unsigned without checking for negative -values. + Convert a number to an unsigned integer. If the argument is signed, + it is reinterpreted as unsigned without checking for negative + values. +``` """ unsigned doc""" - float(x) +```rst +float(x) -Convert a number, array, or string to a `FloatingPoint` data -type. For numeric data, the smallest suitable `FloatingPoint` -type is used. Converts strings to `Float64`. + Convert a number, array, or string to a "FloatingPoint" data + type. For numeric data, the smallest suitable "FloatingPoint" + type is used. Converts strings to "Float64". +``` """ float doc""" - significand(x) +```rst +significand(x) + + Extract the significand(s) (a.k.a. mantissa), in binary + representation, of a floating-point number or array. If "x" is a + non-zero finite number, than the result will be a number of the + same type on the interval [1,2). Otherwise "x" is returned. + + julia> significand(15.2)/15.2 + 0.125 -Extract the significand(s) (a.k.a. mantissa), in binary -representation, of a floating-point number or array. If `x` is a -non-zero finite number, than the result will be a number of the -same type on the interval [1,2). Otherwise `x` is returned. + julia> significand(15.2)*8 + 15.2 +``` """ significand doc""" - exponent(x) -> Int +```rst +exponent(x) -> Int -Get the exponent of a normalized floating-point number. + Get the exponent of a normalized floating-point number. +``` """ exponent doc""" - complex(r[, i]) +```rst +complex(r[, i]) -Convert real numbers or arrays to complex. `i` defaults to zero. + Convert real numbers or arrays to complex. "i" defaults to zero. +``` """ complex doc""" - bswap(n) +```rst +bswap(n) -Byte-swap an integer + Byte-swap an integer +``` """ bswap doc""" - num2hex(f) +```rst +num2hex(f) -Get a hexadecimal string of the binary representation of a floating -point number + Get a hexadecimal string of the binary representation of a floating + point number +``` """ num2hex doc""" - hex2num(str) +```rst +hex2num(str) -Convert a hexadecimal string to the floating point number it -represents + Convert a hexadecimal string to the floating point number it + represents +``` """ hex2num doc""" - hex2bytes(s::ASCIIString) +```rst +hex2bytes(s::ASCIIString) -Convert an arbitrarily long hexadecimal string to its binary -representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. + Convert an arbitrarily long hexadecimal string to its binary + representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. +``` """ hex2bytes doc""" - bytes2hex(bin_arr::Array{UInt8, 1}) +```rst +bytes2hex(bin_arr::Array{UInt8, 1}) -Convert an array of bytes to its hexadecimal representation. All -characters are in lower-case. Returns an ASCIIString. + Convert an array of bytes to its hexadecimal representation. All + characters are in lower-case. Returns an ASCIIString. +``` """ bytes2hex doc""" - one(x) +```rst +one(x) -Get the multiplicative identity element for the type of x (x can -also specify the type itself). For matrices, returns an identity -matrix of the appropriate size and type. + Get the multiplicative identity element for the type of x (x can + also specify the type itself). For matrices, returns an identity + matrix of the appropriate size and type. +``` """ one doc""" - zero(x) +```rst +zero(x) -Get the additive identity element for the type of x (x can also -specify the type itself). + Get the additive identity element for the type of x (x can also + specify the type itself). +``` """ zero doc""" - pi +```rst +pi +π -The constant pi + The constant pi +``` """ pi doc""" - im +```rst +im -The imaginary unit + The imaginary unit +``` """ im doc""" - e +```rst +e +eu -The constant e + The constant e +``` """ e doc""" - catalan +```rst +catalan -Catalan's constant + Catalan's constant +``` """ catalan doc""" - γ +```rst +γ +eulergamma -Euler's constant + Euler's constant +``` """ γ doc""" - φ +```rst +φ +golden -The golden ratio + The golden ratio +``` """ φ doc""" - Inf +```rst +Inf -Positive infinity of type Float64 + Positive infinity of type Float64 +``` """ Inf doc""" - Inf32 +```rst +Inf32 -Positive infinity of type Float32 + Positive infinity of type Float32 +``` """ Inf32 doc""" - Inf16 +```rst +Inf16 -Positive infinity of type Float16 + Positive infinity of type Float16 +``` """ Inf16 doc""" - NaN +```rst +NaN -A not-a-number value of type Float64 + A not-a-number value of type Float64 +``` """ NaN doc""" - NaN32 +```rst +NaN32 -A not-a-number value of type Float32 + A not-a-number value of type Float32 +``` """ NaN32 doc""" - NaN16 +```rst +NaN16 -A not-a-number value of type Float16 + A not-a-number value of type Float16 +``` """ NaN16 doc""" - issubnormal(f) -> Bool +```rst +issubnormal(f) -> Bool -Test whether a floating point number is subnormal + Test whether a floating point number is subnormal +``` """ issubnormal doc""" - isfinite(f) -> Bool +```rst +isfinite(f) -> Bool -Test whether a number is finite + Test whether a number is finite +``` """ isfinite doc""" - isinf(f) -> Bool +```rst +isinf(f) -> Bool -Test whether a number is infinite + Test whether a number is infinite +``` """ isinf doc""" - isnan(f) -> Bool +```rst +isnan(f) -> Bool -Test whether a floating point number is not a number (NaN) + Test whether a floating point number is not a number (NaN) +``` """ isnan doc""" - inf(f) +```rst +inf(f) -Returns positive infinity of the floating point type `f` or of -the same floating point type as `f` + Returns positive infinity of the floating point type "f" or of + the same floating point type as "f" +``` """ inf doc""" - nan(f) +```rst +nan(f) -Returns NaN (not-a-number) of the floating point type `f` or of -the same floating point type as `f` + Returns NaN (not-a-number) of the floating point type "f" or of + the same floating point type as "f" +``` """ nan doc""" - nextfloat(f) +```rst +nextfloat(f) -Get the next floating point number in lexicographic order + Get the next floating point number in lexicographic order +``` """ nextfloat doc""" - prevfloat(f) -> FloatingPoint +```rst +prevfloat(f) -> FloatingPoint -Get the previous floating point number in lexicographic order + Get the previous floating point number in lexicographic order +``` """ prevfloat doc""" - isinteger(x) -> Bool +```rst +isinteger(x) -> Bool -Test whether `x` or all its elements are numerically equal to -some integer + Test whether "x" or all its elements are numerically equal to + some integer +``` """ isinteger doc""" - isreal(x) -> Bool +```rst +isreal(x) -> Bool -Test whether `x` or all its elements are numerically equal to -some real number + Test whether "x" or all its elements are numerically equal to + some real number +``` """ isreal doc""" - Float32(x[, mode::RoundingMode]) +```rst +Float32(x[, mode::RoundingMode]) + + Create a Float32 from "x". If "x" is not exactly representable + then "mode" determines how "x" is rounded. + + julia> Float32(1/3, RoundDown) + 0.3333333f0 + + julia> Float32(1/3, RoundUp) + 0.33333334f0 -Create a Float32 from `x`. If `x` is not exactly representable -then `mode` determines how `x` is rounded. -See `get_rounding` for available rounding modes. + See "get_rounding" for available rounding modes. +``` """ Float32 doc""" - Float64(x[, mode::RoundingMode]) +```rst +Float64(x[, mode::RoundingMode]) -Create a Float64 from `x`. If `x` is not exactly representable -then `mode` determines how `x` is rounded. -See `get_rounding` for available rounding modes. + Create a Float64 from "x". If "x" is not exactly representable + then "mode" determines how "x" is rounded. + + julia> Float64(pi, RoundDown) + 3.141592653589793 + + julia> Float64(pi, RoundUp) + 3.1415926535897936 + + See "get_rounding" for available rounding modes. +``` """ Float64 doc""" - BigInt(x) +```rst +BigInt(x) -Create an arbitrary precision integer. `x` may be an `Int` (or -anything that can be converted to an `Int`). The usual -mathematical operators are defined for this type, and results are -promoted to a `BigInt`. + Create an arbitrary precision integer. "x" may be an "Int" (or + anything that can be converted to an "Int"). The usual + mathematical operators are defined for this type, and results are + promoted to a "BigInt". -Instances can be constructed from strings via `parse()`, or using -the `big` string literal. + Instances can be constructed from strings via "parse()", or using + the "big" string literal. +``` """ BigInt doc""" - BigFloat(x) +```rst +BigFloat(x) -Create an arbitrary precision floating point number. `x` may be -an `Integer`, a `Float64` or a `BigInt`. The usual -mathematical operators are defined for this type, and results are -promoted to a `BigFloat`. + Create an arbitrary precision floating point number. "x" may be + an "Integer", a "Float64" or a "BigInt". The usual + mathematical operators are defined for this type, and results are + promoted to a "BigFloat". -Note that because decimal literals are converted to floating point -numbers when parsed, `BigFloat(2.1)` may not yield what you -expect. You may instead prefer to initialize constants from strings -via `parse()`, or using the `big` string literal. + Note that because decimal literals are converted to floating point + numbers when parsed, "BigFloat(2.1)" may not yield what you + expect. You may instead prefer to initialize constants from strings + via "parse()", or using the "big" string literal. - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision +``` """ BigFloat doc""" - get_rounding(T) +```rst +get_rounding(T) -Get the current floating point rounding mode for type `T`, -controlling the rounding of basic arithmetic functions (`+()`, -Valid modes are `RoundNearest`, `RoundToZero`, `RoundUp`, + Get the current floating point rounding mode for type "T", + controlling the rounding of basic arithmetic functions ("+()", + "-()", "*()", "/()" and "sqrt()") and type conversion. + + Valid modes are "RoundNearest", "RoundToZero", "RoundUp", + "RoundDown", and "RoundFromZero" ("BigFloat" only). +``` """ get_rounding doc""" - set_rounding(T, mode) +```rst +set_rounding(T, mode) + + Set the rounding mode of floating point type "T", controlling the + rounding of basic arithmetic functions ("+()", "-()", "*()", + "/()" and "sqrt()") and type conversion. -Set the rounding mode of floating point type `T`, controlling the -rounding of basic arithmetic functions (`+()`, `-()`, `*()`, -Note that this may affect other types, for instance changing the -rounding mode of `Float64` will change the rounding mode of + Note that this may affect other types, for instance changing the + rounding mode of "Float64" will change the rounding mode of + "Float32". See "get_rounding" for available modes +``` """ set_rounding doc""" - with_rounding(f::Function, T, mode) +```rst +with_rounding(f::Function, T, mode) + + Change the rounding mode of floating point type "T" for the + duration of "f". It is logically equivalent to: -Change the rounding mode of floating point type `T` for the -duration of `f`. It is logically equivalent to: -See `get_rounding` for available rounding modes. + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) + + See "get_rounding" for available rounding modes. +``` """ with_rounding doc""" - count_ones(x::Integer) -> Integer +```rst +count_ones(x::Integer) -> Integer + + Number of ones in the binary representation of "x". -Number of ones in the binary representation of `x`. + julia> count_ones(7) + 3 +``` """ count_ones doc""" - count_zeros(x::Integer) -> Integer +```rst +count_zeros(x::Integer) -> Integer -Number of zeros in the binary representation of `x`. + Number of zeros in the binary representation of "x". + + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 +``` """ count_zeros doc""" - leading_zeros(x::Integer) -> Integer +```rst +leading_zeros(x::Integer) -> Integer + + Number of zeros leading the binary representation of "x". -Number of zeros leading the binary representation of `x`. + julia> leading_zeros(Int32(1)) + 31 +``` """ leading_zeros doc""" - leading_ones(x::Integer) -> Integer +```rst +leading_ones(x::Integer) -> Integer -Number of ones leading the binary representation of `x`. + Number of ones leading the binary representation of "x". + + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 +``` """ leading_ones doc""" - trailing_zeros(x::Integer) -> Integer +```rst +trailing_zeros(x::Integer) -> Integer + + Number of zeros trailing the binary representation of "x". -Number of zeros trailing the binary representation of `x`. + julia> trailing_zeros(2) + 1 +``` """ trailing_zeros doc""" - trailing_ones(x::Integer) -> Integer +```rst +trailing_ones(x::Integer) -> Integer + + Number of ones trailing the binary representation of "x". -Number of ones trailing the binary representation of `x`. + julia> trailing_ones(3) + 2 +``` """ trailing_ones doc""" - isprime(x::Integer) -> Bool +```rst +isprime(x::Integer) -> Bool -Returns `true` if `x` is prime, and `false` otherwise. + Returns "true" if "x" is prime, and "false" otherwise. + + julia> isprime(3) + true +``` """ isprime doc""" - isprime(x::BigInt[, reps = 25]) -> Bool +```rst +isprime(x::BigInt[, reps = 25]) -> Bool -Probabilistic primality test. Returns `true` if `x` is prime; -and `false` if `x` is not prime with high probability. The -false positive rate is about `0.25^reps`. `reps = 25` is -considered safe for cryptographic applications (Knuth, -Seminumerical Algorithms). + Probabilistic primality test. Returns "true" if "x" is prime; + and "false" if "x" is not prime with high probability. The + false positive rate is about "0.25^reps". "reps = 25" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). - julia> isprime(big(3)) - true + julia> isprime(big(3)) + true +``` """ isprime doc""" - primes(n) +```rst +primes(n) -Returns a collection of the prime numbers <= `n`. + Returns a collection of the prime numbers <= "n". +``` """ primes doc""" - isodd(x::Integer) -> Bool +```rst +isodd(x::Integer) -> Bool + + Returns "true" if "x" is odd (that is, not divisible by 2), and + "false" otherwise. + + julia> isodd(9) + true -Returns `true` if `x` is odd (that is, not divisible by 2), and + julia> isodd(10) + false +``` """ isodd doc""" - iseven(x::Integer) -> Bool +```rst +iseven(x::Integer) -> Bool -Returns `true` is `x` is even (that is, divisible by 2), and + Returns "true" is "x" is even (that is, divisible by 2), and + "false" otherwise. + + julia> iseven(9) + false + + julia> iseven(10) + true +``` """ iseven doc""" - precision(num::FloatingPoint) +```rst +precision(num::FloatingPoint) -Get the precision of a floating point number, as defined by the -effective number of bits in the mantissa. + Get the precision of a floating point number, as defined by the + effective number of bits in the mantissa. +``` """ precision doc""" - get_bigfloat_precision() +```rst +get_bigfloat_precision() -Get the precision (in bits) currently used for BigFloat arithmetic. + Get the precision (in bits) currently used for BigFloat arithmetic. +``` """ get_bigfloat_precision doc""" - set_bigfloat_precision(x::Int64) +```rst +set_bigfloat_precision(x::Int64) -Set the precision (in bits) to be used to BigFloat arithmetic. + Set the precision (in bits) to be used to BigFloat arithmetic. +``` """ set_bigfloat_precision doc""" - with_bigfloat_precision(f::Function, precision::Integer) +```rst +with_bigfloat_precision(f::Function, precision::Integer) + + Change the BigFloat arithmetic precision (in bits) for the duration + of "f". It is logically equivalent to: -Change the BigFloat arithmetic precision (in bits) for the duration -of `f`. It is logically equivalent to: + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) +``` """ with_bigfloat_precision doc""" - srand([rng][, seed]) +```rst +srand([rng][, seed]) -Reseed the random number generator. If a `seed` is provided, the -RNG will give a reproducible sequence of numbers, otherwise Julia -will get entropy from the system. For `MersenneTwister`, the -integers or a filename, in which case the seed is read from a file. + Reseed the random number generator. If a "seed" is provided, the + RNG will give a reproducible sequence of numbers, otherwise Julia + will get entropy from the system. For "MersenneTwister", the + "seed" may be a non-negative integer, a vector of "UInt32" + integers or a filename, in which case the seed is read from a file. + "RandomDevice" does not support seeding. +``` """ srand doc""" - MersenneTwister([seed]) +```rst +MersenneTwister([seed]) -Create a `MersenneTwister` RNG object. Different RNG objects can -have their own seeds, which may be useful for generating different -streams of random numbers. + Create a "MersenneTwister" RNG object. Different RNG objects can + have their own seeds, which may be useful for generating different + streams of random numbers. +``` """ MersenneTwister doc""" - RandomDevice() +```rst +RandomDevice() -Create a `RandomDevice` RNG object. Two such objects will always -generate different streams of random numbers. + Create a "RandomDevice" RNG object. Two such objects will always + generate different streams of random numbers. +``` """ RandomDevice doc""" - rand([rng][, S][, dims...]) +```rst +rand([rng][, S][, dims...]) -Pick a random element or array of random elements from the set of -values specified by `S`; `S` can be + Pick a random element or array of random elements from the set of + values specified by "S"; "S" can be + + * an indexable collection (for example "1:n" or + "['x','y','z']"), or + + * a type: the set of values to pick from is then equivalent to + "typemin(S):typemax(S)" for integers (this is not applicable to + "BigInt"), and to [0,1) for floating point numbers; + + "S" defaults to "Float64". +``` """ rand doc""" - rand!([rng], A[, coll]) +```rst +rand!([rng], A[, coll]) -Populate the array A with random values. If the indexable -collection `coll` is specified, the values are picked randomly -from `coll`. This is equivalent to `copy!(A, rand(rng, coll, -size(A)))` or `copy!(A, rand(rng, eltype(A), size(A)))` but -without allocating a new array. + Populate the array A with random values. If the indexable + collection "coll" is specified, the values are picked randomly + from "coll". This is equivalent to "copy!(A, rand(rng, coll, + size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but + without allocating a new array. +``` """ rand! doc""" - bitrand([rng][, dims...]) +```rst +bitrand([rng][, dims...]) -Generate a `BitArray` of random boolean values. + Generate a "BitArray" of random boolean values. +``` """ bitrand doc""" - randn([rng][, dims...]) +```rst +randn([rng][, dims...]) -Generate a normally-distributed random number with mean 0 and -standard deviation 1. Optionally generate an array of normally- -distributed random numbers. + Generate a normally-distributed random number with mean 0 and + standard deviation 1. Optionally generate an array of normally- + distributed random numbers. +``` """ randn doc""" - randn!([rng], A::Array{Float64, N}) +```rst +randn!([rng], A::Array{Float64, N}) -Fill the array A with normally-distributed (mean 0, standard -deviation 1) random numbers. Also see the rand function. + Fill the array A with normally-distributed (mean 0, standard + deviation 1) random numbers. Also see the rand function. +``` """ randn! doc""" - randexp([rng][, dims...]) +```rst +randexp([rng][, dims...]) -Generate a random number according to the exponential distribution -with scale 1. Optionally generate an array of such random numbers. + Generate a random number according to the exponential distribution + with scale 1. Optionally generate an array of such random numbers. +``` """ randexp doc""" - randexp!([rng], A::Array{Float64, N}) +```rst +randexp!([rng], A::Array{Float64, N}) -Fill the array A with random numbers following the exponential -distribution (with scale 1). + Fill the array A with random numbers following the exponential + distribution (with scale 1). +``` """ randexp! doc""" - Task(func) +```rst +Task(func) -Create a `Task` (i.e. thread, or coroutine) to execute the given -function (which must be callable with no arguments). The task exits -when this function returns. + Create a "Task" (i.e. thread, or coroutine) to execute the given + function (which must be callable with no arguments). The task exits + when this function returns. +``` """ Task doc""" - yieldto(task, arg = nothing) +```rst +yieldto(task, arg = nothing) -Switch to the given task. The first time a task is switched to, the -task's function is called with no arguments. On subsequent -switches, `arg` is returned from the task's last call to -considering states or scheduling in any way. Its use is -discouraged. + Switch to the given task. The first time a task is switched to, the + task's function is called with no arguments. On subsequent + switches, "arg" is returned from the task's last call to + "yieldto". This is a low-level call that only switches tasks, not + considering states or scheduling in any way. Its use is + discouraged. +``` """ yieldto doc""" - current_task() +```rst +current_task() -Get the currently running Task. + Get the currently running Task. +``` """ current_task doc""" - istaskdone(task) -> Bool +```rst +istaskdone(task) -> Bool -Tell whether a task has exited. + Tell whether a task has exited. +``` """ istaskdone doc""" - istaskstarted(task) -> Bool +```rst +istaskstarted(task) -> Bool -Tell whether a task has started executing. + Tell whether a task has started executing. +``` """ istaskstarted doc""" - consume(task, values...) +```rst +consume(task, values...) -Receive the next value passed to `produce` by the specified task. -Additional arguments may be passed, to be returned from the last + Receive the next value passed to "produce" by the specified task. + Additional arguments may be passed, to be returned from the last + "produce" call in the producer. +``` """ consume doc""" - produce(value) +```rst +produce(value) -Send the given value to the last `consume` call, switching to the -consumer task. If the next `consume` call passes any values, they -are returned by `produce`. + Send the given value to the last "consume" call, switching to the + consumer task. If the next "consume" call passes any values, they + are returned by "produce". +``` """ produce doc""" - yield() +```rst +yield() -Switch to the scheduler to allow another scheduled task to run. A -task that calls this function is still runnable, and will be -restarted immediately if there are no other runnable tasks. + Switch to the scheduler to allow another scheduled task to run. A + task that calls this function is still runnable, and will be + restarted immediately if there are no other runnable tasks. +``` """ yield doc""" - task_local_storage(symbol) +```rst +task_local_storage(symbol) -Look up the value of a symbol in the current task's task-local -storage. + Look up the value of a symbol in the current task's task-local + storage. +``` """ task_local_storage doc""" - task_local_storage(symbol, value) +```rst +task_local_storage(symbol, value) -Assign a value to a symbol in the current task's task-local -storage. + Assign a value to a symbol in the current task's task-local + storage. +``` """ task_local_storage doc""" - task_local_storage(body, symbol, value) +```rst +task_local_storage(body, symbol, value) -Call the function `body` with a modified task-local storage, in -which `value` is assigned to `symbol`; the previous value of -emulating dynamic scoping. + Call the function "body" with a modified task-local storage, in + which "value" is assigned to "symbol"; the previous value of + "symbol", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. +``` """ task_local_storage doc""" - Condition() +```rst +Condition() -Create an edge-triggered event source that tasks can wait for. -Tasks that call `wait` on a `Condition` are suspended and -queued. Tasks are woken up when `notify` is later called on the -time `notify` is called can be woken up. For level-triggered -notifications, you must keep extra state to keep track of whether a -notification has happened. The `RemoteRef` type does this, and so -can be used for level-triggered events. + Create an edge-triggered event source that tasks can wait for. + Tasks that call "wait" on a "Condition" are suspended and + queued. Tasks are woken up when "notify" is later called on the + "Condition". Edge triggering means that only tasks waiting at the + time "notify" is called can be woken up. For level-triggered + notifications, you must keep extra state to keep track of whether a + notification has happened. The "RemoteRef" type does this, and so + can be used for level-triggered events. +``` """ Condition doc""" - notify(condition, val=nothing; all=true, error=false) +```rst +notify(condition, val=nothing; all=true, error=false) -Wake up tasks waiting for a condition, passing them `val`. If -otherwise only one is. If `error` is true, the passed value is -raised as an exception in the woken tasks. + Wake up tasks waiting for a condition, passing them "val". If + "all" is true (the default), all waiting tasks are woken, + otherwise only one is. If "error" is true, the passed value is + raised as an exception in the woken tasks. +``` """ notify doc""" - schedule(t::Task, [val]; error=false) +```rst +schedule(t::Task, [val]; error=false) -Add a task to the scheduler's queue. This causes the task to run -constantly when the system is otherwise idle, unless the task -performs a blocking operation such as `wait`. -If a second argument is provided, it will be passed to the task -task. + Add a task to the scheduler's queue. This causes the task to run + constantly when the system is otherwise idle, unless the task + performs a blocking operation such as "wait". + + If a second argument is provided, it will be passed to the task + (via the return value of "yieldto") when it runs again. If + "error" is true, the value is raised as an exception in the woken + task. +``` """ schedule doc""" - @schedule() +```rst +@schedule() -Wrap an expression in a Task and add it to the scheduler's queue. + Wrap an expression in a Task and add it to the scheduler's queue. +``` """ @schedule doc""" - @task() +```rst +@task() -Wrap an expression in a Task without executing it, and return the -Task. This only creates a task, and does not run it. + Wrap an expression in a Task without executing it, and return the + Task. This only creates a task, and does not run it. +``` """ @task doc""" - sleep(seconds) +```rst +sleep(seconds) -Block the current task for a specified number of seconds. The -minimum sleep time is 1 millisecond or input of `0.001`. + Block the current task for a specified number of seconds. The + minimum sleep time is 1 millisecond or input of "0.001". +``` """ sleep doc""" - ReentrantLock() +```rst +ReentrantLock() -Creates a reentrant lock. The same task can acquire the lock as -many times as required. Each lock must be matched with an unlock. + Creates a reentrant lock. The same task can acquire the lock as + many times as required. Each lock must be matched with an unlock. +``` """ ReentrantLock doc""" - lock(l::ReentrantLock) +```rst +lock(l::ReentrantLock) -Associates `l` with the current task. If `l` is already locked -by a different task, waits for it to become available. The same -task can acquire the lock multiple times. Each `lock` must be -matched by an `unlock` + Associates "l" with the current task. If "l" is already locked + by a different task, waits for it to become available. The same + task can acquire the lock multiple times. Each "lock" must be + matched by an "unlock" +``` """ lock doc""" - unlock(l::ReentrantLock) +```rst +unlock(l::ReentrantLock) -Releases ownership of the lock by the current task. If the lock had -been acquired before, it just decrements an internal counter and -returns immediately. + Releases ownership of the lock by the current task. If the lock had + been acquired before, it just decrements an internal counter and + returns immediately. +``` """ unlock doc""" - addprocs(n::Integer; exeflags="") -> List of process identifiers +```rst +addprocs(n::Integer; exeflags=``) -> List of process identifiers -Launches workers using the in-built `LocalManager` which only -launches workers on the local host. This can be used to take -advantage of multiple cores. `addprocs(4)` will add 4 processes -on the local machine. + Launches workers using the in-built "LocalManager" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. "addprocs(4)" will add 4 processes + on the local machine. +``` """ addprocs doc""" - addprocs() -> List of process identifiers +```rst +addprocs() -> List of process identifiers -Equivalent to `addprocs(CPU_CORES)` + Equivalent to "addprocs(CPU_CORES)" +``` """ addprocs doc""" - addprocs(machines; tunnel=false, sshflags=`, max_parallel=10, exeflags=`) -> List of process identifiers - -Add processes on remote machines via SSH. Requires julia to be -installed in the same location on each node, or to be available via -a shared file system. -started for each specification. -A machine specification is either a string `machine_spec` or a -tuple - `(machine_spec, count)` -to the standard ssh port. If `[bind_addr[:port]]` is specified, -other workers will connect to this worker at the specified -host. If specified as `:auto` it will launch as many workers as -the number of cores on the specific host. -Keyword arguments: -to the worker from the master process. -connected to in parallel at a host. Defaults to 10. -to the host's current directory (as found by `pwd()`) -may be. - -Environment variables: - -If the master process fails to establish a connection with a newly -launched worker within 60.0 seconds, the worker treats it a fatal -situation and terminates. This timeout can be controlled via -environment variable `JULIA_WORKER_TIMEOUT`. The value of -number of seconds a newly launched worker waits for connection -establishment. +```rst +addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + "machines" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string "machine_spec" or a + tuple - "(machine_spec, count)" + + "machine_spec" is a string of the form "[user@]host[:port] + [bind_addr[:port]]". "user" defaults to current user, "port" + to the standard ssh port. If "[bind_addr[:port]]" is specified, + other workers will connect to this worker at the specified + "bind_addr" and "port". + + "count" is the number of workers to be launched on the specified + host. If specified as ":auto" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + "tunnel" : if "true" then SSH tunneling will be used to connect + to the worker from the master process. + + "sshflags" : specifies additional ssh options, e.g. + "sshflags=`-i /home/foo/bar.pem`" . + + "max_parallel" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + "dir" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + "exename" : name of the julia executable. Defaults to + "\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case + may be. + + "exeflags" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable "JULIA_WORKER_TIMEOUT". The value of + "JULIA_WORKER_TIMEOUT" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. +``` """ addprocs doc""" - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +```rst +addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. -Launches worker processes via the specified cluster manager. -For example Beowulf clusters are supported via a custom cluster -manager implemented in package `ClusterManagers`. + For example Beowulf clusters are supported via a custom cluster + manager implemented in package "ClusterManagers". -The number of seconds a newly launched worker waits for connection -establishment from the master can be specified via variable -`JULIA_WORKER_TIMEOUT` in the worker process's environment. -Relevant only when using TCP/IP as transport. + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + "JULIA_WORKER_TIMEOUT" in the worker process's environment. + Relevant only when using TCP/IP as transport. +``` """ addprocs doc""" - nprocs() +```rst +nprocs() -Get the number of available processes. + Get the number of available processes. +``` """ nprocs doc""" - nworkers() +```rst +nworkers() -Get the number of available worker processes. This is one less than -nprocs(). Equal to nprocs() if nprocs() == 1. + Get the number of available worker processes. This is one less than + nprocs(). Equal to nprocs() if nprocs() == 1. +``` """ nworkers doc""" - procs() +```rst +procs() -Returns a list of all process identifiers. + Returns a list of all process identifiers. +``` """ procs doc""" - workers() +```rst +workers() -Returns a list of all worker process identifiers. + Returns a list of all worker process identifiers. +``` """ workers doc""" - rmprocs(pids...) +```rst +rmprocs(pids...) -Removes the specified workers. + Removes the specified workers. +``` """ rmprocs doc""" - interrupt([pids...]) +```rst +interrupt([pids...]) -Interrupt the current executing task on the specified workers. This -is equivalent to pressing Ctrl-C on the local machine. If no -arguments are given, all workers are interrupted. + Interrupt the current executing task on the specified workers. This + is equivalent to pressing Ctrl-C on the local machine. If no + arguments are given, all workers are interrupted. +``` """ interrupt doc""" - myid() +```rst +myid() -Get the id of the current process. + Get the id of the current process. +``` """ myid doc""" - pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) +```rst +pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) -Transform collections `lsts` by applying `f` to each element in -parallel. If `nprocs() > 1`, the calling process will be -dedicated to assigning tasks. All other available processes will be -used as parallel workers, or on the processes specified by -If `err_retry` is true, it retries a failed application of `f` -on a different worker. If `err_stop` is true, it takes precedence -over the value of `err_retry` and `pmap` stops execution on the -first error. + Transform collections "lsts" by applying "f" to each element in + parallel. If "nprocs() > 1", the calling process will be + dedicated to assigning tasks. All other available processes will be + used as parallel workers, or on the processes specified by + "pids". + + If "err_retry" is true, it retries a failed application of "f" + on a different worker. If "err_stop" is true, it takes precedence + over the value of "err_retry" and "pmap" stops execution on the + first error. +``` """ pmap doc""" - remotecall(id, func, args...) +```rst +remotecall(id, func, args...) -Call a function asynchronously on the given arguments on the -specified process. Returns a `RemoteRef`. + Call a function asynchronously on the given arguments on the + specified process. Returns a "RemoteRef". +``` """ remotecall doc""" - wait([x]) +```rst +wait([x]) + + Block the current task until some event occurs, depending on the + type of the argument: + + * "RemoteRef": Wait for a value to become available for the + specified remote reference. + + * "Condition": Wait for "notify" on a condition. + + * "Process": Wait for a process or process chain to exit. The + "exitcode" field of a process can be used to determine success + or failure. + + * "Task": Wait for a "Task" to finish, returning its result + value. If the task fails with an exception, the exception is + propagated (re-thrown in the task that called "wait"). -Block the current task until some event occurs, depending on the -type of the argument: -If no argument is passed, the task blocks for an undefined period. -If the task's state is set to `:waiting`, it can only be -restarted by an explicit call to `schedule` or `yieldto`. If -the task's state is `:runnable`, it might be restarted -unpredictably. -Often `wait` is called within a `while` loop to ensure a -waited-for condition is met before proceeding. + * "RawFD": Wait for changes on a file descriptor (see *poll_fd* + for keyword arguments and return code) + + If no argument is passed, the task blocks for an undefined period. + If the task's state is set to ":waiting", it can only be + restarted by an explicit call to "schedule" or "yieldto". If + the task's state is ":runnable", it might be restarted + unpredictably. + + Often "wait" is called within a "while" loop to ensure a + waited-for condition is met before proceeding. +``` """ wait doc""" - fetch(RemoteRef) +```rst +fetch(RemoteRef) -Wait for and get the value of a remote reference. + Wait for and get the value of a remote reference. +``` """ fetch doc""" - remotecall_wait(id, func, args...) +```rst +remotecall_wait(id, func, args...) -Perform `wait(remotecall(...))` in one message. + Perform "wait(remotecall(...))" in one message. +``` """ remotecall_wait doc""" - remotecall_fetch(id, func, args...) +```rst +remotecall_fetch(id, func, args...) -Perform `fetch(remotecall(...))` in one message. + Perform "fetch(remotecall(...))" in one message. +``` """ remotecall_fetch doc""" - put!(RemoteRef, value) +```rst +put!(RemoteRef, value) -Store a value to a remote reference. Implements `shared queue of -length 1` semantics: if a value is already present, blocks until -the value is removed with `take!`. Returns its first argument. + Store a value to a remote reference. Implements "shared queue of + length 1" semantics: if a value is already present, blocks until + the value is removed with "take!". Returns its first argument. +``` """ put! doc""" - take!(RemoteRef) +```rst +take!(RemoteRef) -Fetch the value of a remote reference, removing it so that the -reference is empty again. + Fetch the value of a remote reference, removing it so that the + reference is empty again. +``` """ take! doc""" - isready(r::RemoteRef) +```rst +isready(r::RemoteRef) + + Determine whether a "RemoteRef" has a value stored to it. Note + that this function can cause race conditions, since by the time you + receive its result it may no longer be true. It is recommended that + this function only be used on a "RemoteRef" that is assigned + once. -Determine whether a `RemoteRef` has a value stored to it. Note -that this function can cause race conditions, since by the time you -receive its result it may no longer be true. It is recommended that -this function only be used on a `RemoteRef` that is assigned -once. -If the argument `RemoteRef` is owned by a different node, this -call will block to wait for the answer. It is recommended to wait -for `r` in a separate task instead, or to use a local + If the argument "RemoteRef" is owned by a different node, this + call will block to wait for the answer. It is recommended to wait + for "r" in a separate task instead, or to use a local + "RemoteRef" as a proxy: + + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block +``` """ isready doc""" - RemoteRef() +```rst +RemoteRef() -Make an uninitialized remote reference on the local machine. + Make an uninitialized remote reference on the local machine. +``` """ RemoteRef doc""" - RemoteRef(n) +```rst +RemoteRef(n) -Make an uninitialized remote reference on process `n`. + Make an uninitialized remote reference on process "n". +``` """ RemoteRef doc""" - timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) +```rst +timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) -Waits till `testcb` returns `true` or for `secs` seconds, -whichever is earlier. `testcb` is polled every `pollint` -seconds. + Waits till "testcb" returns "true" or for "secs`" seconds, + whichever is earlier. "testcb" is polled every "pollint" + seconds. +``` """ timedwait doc""" - @spawn() +```rst +@spawn() -Execute an expression on an automatically-chosen process, returning -a `RemoteRef` to the result. + Execute an expression on an automatically-chosen process, returning + a "RemoteRef" to the result. +``` """ @spawn doc""" - @spawnat() +```rst +@spawnat() -Accepts two arguments, `p` and an expression, and runs the -expression asynchronously on process `p`, returning a + Accepts two arguments, "p" and an expression, and runs the + expression asynchronously on process "p", returning a + "RemoteRef" to the result. +``` """ @spawnat doc""" - @fetch() +```rst +@fetch() -Equivalent to `fetch(@spawn expr)`. + Equivalent to "fetch(@spawn expr)". +``` """ @fetch doc""" - @fetchfrom() +```rst +@fetchfrom() -Equivalent to `fetch(@spawnat p expr)`. + Equivalent to "fetch(@spawnat p expr)". +``` """ @fetchfrom doc""" - @async() +```rst +@async() -Schedule an expression to run on the local machine, also adding it -to the set of items that the nearest enclosing `@sync` waits for. + Schedule an expression to run on the local machine, also adding it + to the set of items that the nearest enclosing "@sync" waits for. +``` """ @async doc""" - @sync() +```rst +@sync() -Wait until all dynamically-enclosed uses of `@async`, `@spawn`, + Wait until all dynamically-enclosed uses of "@async", "@spawn", + "@spawnat" and "@parallel" are complete. +``` """ @sync doc""" - @parallel() +```rst +@parallel() + + A parallel for loop of the form + + @parallel [reducer] for var = range + body + end -A parallel for loop of the form -The specified range is partitioned and locally executed across all -workers. In case an optional reducer function is specified, -reduction on the calling process. -Note that without a reducer function, @parallel executes -asynchronously, i.e. it spawns independent tasks on all available -workers and returns immediately without waiting for completion. To -wait for completion, prefix the call with `@sync`, like + The specified range is partitioned and locally executed across all + workers. In case an optional reducer function is specified, + @parallel performs local reductions on each worker with a final + reduction on the calling process. + + Note that without a reducer function, @parallel executes + asynchronously, i.e. it spawns independent tasks on all available + workers and returns immediately without waiting for completion. To + wait for completion, prefix the call with "@sync", like + + @sync @parallel for var = range + body + end +``` """ @parallel doc""" - SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) +```rst +SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + + Construct a SharedArray of a bitstype "T" and size "dims" + across the processes specified by "pids" - all of which have to + be on the same host. -Construct a SharedArray of a bitstype `T` and size `dims` -across the processes specified by `pids` - all of which have to -be on the same host. -If `pids` is left unspecified, the shared array will be mapped -across all processes on the current host, including the master. -But, `localindexes` and `indexpids` will only refer to worker -processes. This facilitates work distribution code to use workers -for actual computation with the master process acting as a driver. -If an `init` function of the type `initfn(S::SharedArray)` is -specified, it is called on all the participating workers. + If "pids" is left unspecified, the shared array will be mapped + across all processes on the current host, including the master. + But, "localindexes" and "indexpids" will only refer to worker + processes. This facilitates work distribution code to use workers + for actual computation with the master process acting as a driver. + + If an "init" function of the type "initfn(S::SharedArray)" is + specified, it is called on all the participating workers. +``` """ SharedArray doc""" - procs(S::SharedArray) +```rst +procs(S::SharedArray) -Get the vector of processes that have mapped the shared array + Get the vector of processes that have mapped the shared array +``` """ procs doc""" - sdata(S::SharedArray) +```rst +sdata(S::SharedArray) -Returns the actual `Array` object backing `S` + Returns the actual "Array" object backing "S" +``` """ sdata doc""" - indexpids(S::SharedArray) +```rst +indexpids(S::SharedArray) -Returns the index of the current worker into the `pids` vector, -i.e., the list of workers mapping the SharedArray + Returns the index of the current worker into the "pids" vector, + i.e., the list of workers mapping the SharedArray +``` """ indexpids doc""" - launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) +```rst +launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) -Implemented by cluster managers. For every Julia worker launched by -this function, it should append a `WorkerConfig` entry to -once all workers, requested by `manager` have been launched. -was called with. + Implemented by cluster managers. For every Julia worker launched by + this function, it should append a "WorkerConfig" entry to + "launched" and notify "launch_ntfy". The function MUST exit + once all workers, requested by "manager" have been launched. + "params" is a dictionary of all keyword arguments "addprocs" + was called with. +``` """ launch doc""" - manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) +```rst +manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + + Implemented by cluster managers. It is called on the master + process, during a worker's lifetime, with appropriate "op" + values: + + * with ":register"/":deregister" when a worker is added / + removed from the Julia worker pool. -Implemented by cluster managers. It is called on the master -process, during a worker's lifetime, with appropriate `op` -values: + * with ":interrupt" when "interrupt(workers)" is called. + The "ClusterManager" should signal the appropriate worker + with an interrupt signal. + + * with ":finalize" for cleanup purposes. +``` """ manage doc""" - kill(manager::FooManager, pid::Int, config::WorkerConfig) +```rst +kill(manager::FooManager, pid::Int, config::WorkerConfig) -Implemented by cluster managers. It is called on the master -process, by `rmprocs`. It should cause the remote worker -specified by `pid` to exit. + Implemented by cluster managers. It is called on the master + process, by "rmprocs". It should cause the remote worker + specified by "pid" to exit. + "Base.kill(manager::ClusterManager.....)" executes a remote + "exit()" on "pid" +``` """ kill doc""" - init_worker(manager::FooManager) +```rst +init_worker(manager::FooManager) -Called by cluster managers implementing custom transports. It -initializes a newly launched process as a worker. Command line -argument `--worker` has the effect of initializing a process as a -worker using TCP/IP sockets for transport. + Called by cluster managers implementing custom transports. It + initializes a newly launched process as a worker. Command line + argument "--worker" has the effect of initializing a process as a + worker using TCP/IP sockets for transport. +``` """ init_worker doc""" - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +```rst +connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) -Implemented by cluster managers using custom transports. It should -establish a logical connection to worker with id `pid`, specified -by `config` and return a pair of `AsyncStream` objects. -Messages from `pid` to current process will be read off -messages are delivered and received completely and in order. -socket connections in-between workers. + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id "pid", specified + by "config" and return a pair of "AsyncStream" objects. + Messages from "pid" to current process will be read off + "instrm", while messages to be sent to "pid" will be written to + "outstrm". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + "Base.connect(manager::ClusterManager.....)" sets up TCP/IP + socket connections in-between workers. +``` """ connect doc""" - Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) +```rst +Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) -Called by cluster managers using custom transports. It should be -called when the custom transport implementation receives the first -message from a remote worker. The custom transport must manage a -logical connection to the remote worker and provide two AsyncStream -objects, one for incoming messages and the other for messages -addressed to the remote worker. + Called by cluster managers using custom transports. It should be + called when the custom transport implementation receives the first + message from a remote worker. The custom transport must manage a + logical connection to the remote worker and provide two AsyncStream + objects, one for incoming messages and the other for messages + addressed to the remote worker. +``` """ Base doc""" - dir() -> AbstractString +```rst +dir() -> AbstractString -Returns the absolute path of the package directory. This defaults -to `joinpath(homedir(),`.julia`,`v\$(VERSION.major).\$(VERSION -syntax). If the `JULIA_PKGDIR` environment variable is set, then -that path is used in the returned value as `joinpath(ENV[`JULIA_ -PKGDIR`],`v\$(VERSION.major).\$(VERSION.minor)`)`. If -whatever the current working directory is. + Returns the absolute path of the package directory. This defaults + to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION + .minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell + syntax). If the "JULIA_PKGDIR" environment variable is set, then + that path is used in the returned value as "joinpath(ENV["JULIA_ + PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If + "JULIA_PKGDIR" is a relative path, it is interpreted relative to + whatever the current working directory is. +``` """ Base.Pkg.dir doc""" - dir(names...) -> AbstractString +```rst +dir(names...) -> AbstractString -Equivalent to `normpath(Pkg.dir(),names...)` – i.e. it appends -path components to the package directory and normalizes the -resulting path. In particular, `Pkg.dir(pkg)` returns the path to -the package `pkg`. + Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends + path components to the package directory and normalizes the + resulting path. In particular, "Pkg.dir(pkg)" returns the path to + the package "pkg". +``` """ Base.Pkg.dir doc""" - init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) +```rst +init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) -Initialize `Pkg.dir()` as a package directory. This will be done -automatically when the `JULIA_PKGDIR` is not set and -clones a local METADATA git repository from the site and branch -specified by its arguments, which are typically not provided. -Explicit (non-default) arguments can be used to support a custom -METADATA setup. + Initialize "Pkg.dir()" as a package directory. This will be done + automatically when the "JULIA_PKGDIR" is not set and + "Pkg.dir()" uses its default value. As part of this process, + clones a local METADATA git repository from the site and branch + specified by its arguments, which are typically not provided. + Explicit (non-default) arguments can be used to support a custom + METADATA setup. +``` """ Base.Pkg.init doc""" - resolve() +```rst +resolve() -Determines an optimal, consistent set of package versions to -install or upgrade to. The optimal set of package versions is based -on the contents of `Pkg.dir(`REQUIRE`)` and the state of -installed packages in `Pkg.dir()`, Packages that are no longer -required are moved into `Pkg.dir(`.trash`)`. + Determines an optimal, consistent set of package versions to + install or upgrade to. The optimal set of package versions is based + on the contents of "Pkg.dir("REQUIRE")" and the state of + installed packages in "Pkg.dir()", Packages that are no longer + required are moved into "Pkg.dir(".trash")". +``` """ Base.Pkg.resolve doc""" - edit() +```rst +edit() -Opens `Pkg.dir(`REQUIRE`)` in the editor specified by the -command returns, it runs `Pkg.resolve()` to determine and install -a new optimal set of installed package versions. + Opens "Pkg.dir("REQUIRE")" in the editor specified by the + "VISUAL" or "EDITOR" environment variables; when the editor + command returns, it runs "Pkg.resolve()" to determine and install + a new optimal set of installed package versions. +``` """ Base.Pkg.edit doc""" - add(pkg, vers...) +```rst +add(pkg, vers...) -Add a requirement entry for `pkg` to `Pkg.dir(`REQUIRE`)` and -call `Pkg.resolve()`. If `vers` are given, they must be -intervals for `pkg`. + Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and + call "Pkg.resolve()". If "vers" are given, they must be + "VersionNumber" objects and they specify acceptable version + intervals for "pkg". +``` """ Base.Pkg.add doc""" - rm(pkg) +```rst +rm(pkg) -Remove all requirement entries for `pkg` from + Remove all requirement entries for "pkg" from + "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". +``` """ Base.Pkg.rm doc""" - clone(url[, pkg]) +```rst +clone(url[, pkg]) -Clone a package directly from the git URL `url`. The package does -not need to be a registered in `Pkg.dir(`METADATA`)`. The -package repo is cloned by the name `pkg` if provided; if not -provided, `pkg` is determined automatically from `url`. + Clone a package directly from the git URL "url". The package does + not need to be a registered in "Pkg.dir("METADATA")". The + package repo is cloned by the name "pkg" if provided; if not + provided, "pkg" is determined automatically from "url". +``` """ Base.Pkg.clone doc""" - clone(pkg) +```rst +clone(pkg) -If `pkg` has a URL registered in `Pkg.dir(`METADATA`)`, clone -it from that URL on the default branch. The package does not need -to have any registered versions. + If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone + it from that URL on the default branch. The package does not need + to have any registered versions. +``` """ Base.Pkg.clone doc""" - available() -> Vector{ASCIIString} +```rst +available() -> Vector{ASCIIString} -Returns the names of available packages. + Returns the names of available packages. +``` """ Base.Pkg.available doc""" - available(pkg) -> Vector{VersionNumber} +```rst +available(pkg) -> Vector{VersionNumber} -Returns the version numbers available for package `pkg`. + Returns the version numbers available for package "pkg". +``` """ Base.Pkg.available doc""" - installed() -> Dict{ASCIIString,VersionNumber} +```rst +installed() -> Dict{ASCIIString,VersionNumber} -Returns a dictionary mapping installed package names to the -installed version number of each package. + Returns a dictionary mapping installed package names to the + installed version number of each package. +``` """ Base.Pkg.installed doc""" - installed(pkg) -> Void | VersionNumber +```rst +installed(pkg) -> Void | VersionNumber -If `pkg` is installed, return the installed version number, -otherwise return `nothing`. + If "pkg" is installed, return the installed version number, + otherwise return "nothing". +``` """ Base.Pkg.installed doc""" - status() +```rst +status() -Prints out a summary of what packages are installed and what -version and state they're in. + Prints out a summary of what packages are installed and what + version and state they're in. +``` """ Base.Pkg.status doc""" - update() +```rst +update() -Update package the metadata repo – kept in -safely be pulled from their origin; then call `Pkg.resolve()` to -determine a new optimal set of packages versions. + Update package the metadata repo – kept in + "Pkg.dir("METADATA")" – then update any fixed packages that can + safely be pulled from their origin; then call "Pkg.resolve()" to + determine a new optimal set of packages versions. +``` """ Base.Pkg.update doc""" - checkout(pkg[, branch="master"]) +```rst +checkout(pkg[, branch="master"]) -Checkout the `Pkg.dir(pkg)` repo to the branch `branch`. -Defaults to checking out the `master` branch. To go back to using -the newest compatible released version, use `Pkg.free(pkg)` + Checkout the "Pkg.dir(pkg)" repo to the branch "branch". + Defaults to checking out the "master" branch. To go back to using + the newest compatible released version, use "Pkg.free(pkg)" +``` """ Base.Pkg.checkout doc""" - pin(pkg) +```rst +pin(pkg) -Pin `pkg` at the current version. To go back to using the newest -compatible released version, use `Pkg.free(pkg)` + Pin "pkg" at the current version. To go back to using the newest + compatible released version, use "Pkg.free(pkg)" +``` """ Base.Pkg.pin doc""" - pin(pkg, version) +```rst +pin(pkg, version) -Pin `pkg` at registered version `version`. + Pin "pkg" at registered version "version". +``` """ Base.Pkg.pin doc""" - free(pkg) +```rst +free(pkg) -Free the package `pkg` to be managed by the package manager -again. It calls `Pkg.resolve()` to determine optimal package -versions after. This is an inverse for both `Pkg.checkout` and + Free the package "pkg" to be managed by the package manager + again. It calls "Pkg.resolve()" to determine optimal package + versions after. This is an inverse for both "Pkg.checkout" and + "Pkg.pin". -You can also supply an iterable collection of package names, e.g., -`Pkg.free(("Pkg1", "Pkg2"))` to free multiple packages at -once. + You can also supply an iterable collection of package names, e.g., + "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at + once. +``` """ Base.Pkg.free doc""" - build() +```rst +build() -Run the build scripts for all installed packages in depth-first -recursive order. + Run the build scripts for all installed packages in depth-first + recursive order. +``` """ Base.Pkg.build doc""" - build(pkgs...) +```rst +build(pkgs...) -Run the build script in `deps/build.jl` for each package in -order. This is called automatically by `Pkg.resolve()` on all -installed or updated packages. + Run the build script in "deps/build.jl" for each package in + "pkgs" and all of their dependencies in depth-first recursive + order. This is called automatically by "Pkg.resolve()" on all + installed or updated packages. +``` """ Base.Pkg.build doc""" - generate(pkg, license) +```rst +generate(pkg, license) -Generate a new package named `pkg` with one of these license -keys: `MIT`, `BSD` or `ASL`. If you want to make -a package with a different license, you can edit it afterwards. -Generate creates a git repo at `Pkg.dir(pkg)` for the package and -inside it `LICENSE.md`, `README.md`, the julia entrypoint + Generate a new package named "pkg" with one of these license + keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make + a package with a different license, you can edit it afterwards. + Generate creates a git repo at "Pkg.dir(pkg)" for the package and + inside it "LICENSE.md", "README.md", the julia entrypoint + "\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". +``` """ Base.Pkg.generate doc""" - register(pkg[, url]) +```rst +register(pkg[, url]) -Register `pkg` at the git URL `url`, defaulting to the -configured origin URL of the git repo `Pkg.dir(pkg)`. + Register "pkg" at the git URL "url", defaulting to the + configured origin URL of the git repo "Pkg.dir(pkg)". +``` """ Base.Pkg.register doc""" - tag(pkg[, ver[, commit]]) +```rst +tag(pkg[, ver[, commit]]) -Tag `commit` as version `ver` of package `pkg` and create a -version entry in `METADATA`. If not provided, `commit` defaults -to the current commit of the `pkg` repo. If `ver` is one of the -symbols `:patch`, `:minor`, `:major` the next patch, minor or -major version is used. If `ver` is not provided, it defaults to + Tag "commit" as version "ver" of package "pkg" and create a + version entry in "METADATA". If not provided, "commit" defaults + to the current commit of the "pkg" repo. If "ver" is one of the + symbols ":patch", ":minor", ":major" the next patch, minor or + major version is used. If "ver" is not provided, it defaults to + ":patch". +``` """ Base.Pkg.tag doc""" - publish() +```rst +publish() -For each new package version tagged in `METADATA` not already -published, make sure that the tagged package commits have been -pushed to the repo at the registered URL for the package and if -they all have, open a pull request to `METADATA`. + For each new package version tagged in "METADATA" not already + published, make sure that the tagged package commits have been + pushed to the repo at the registered URL for the package and if + they all have, open a pull request to "METADATA". +``` """ Base.Pkg.publish doc""" - test() +```rst +test() -Run the tests for all installed packages ensuring that each -package's test dependencies are installed for the duration of the -test. A package is tested by running its `test/runtests.jl` file -and test dependencies are specified in `test/REQUIRE`. + Run the tests for all installed packages ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its "test/runtests.jl" file + and test dependencies are specified in "test/REQUIRE". +``` """ Base.Pkg.test doc""" - test(pkgs...) +```rst +test(pkgs...) -Run the tests for each package in `pkgs` ensuring that each -package's test dependencies are installed for the duration of the -test. A package is tested by running its `test/runtests.jl` file -and test dependencies are specified in `test/REQUIRE`. + Run the tests for each package in "pkgs" ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its "test/runtests.jl" file + and test dependencies are specified in "test/REQUIRE". +``` """ Base.Pkg.test doc""" - @profile() +```rst +@profile() -periodic backtraces. These are appended to an internal buffer of -backtraces. + "@profile " runs your expression while taking + periodic backtraces. These are appended to an internal buffer of + backtraces. +``` """ @profile doc""" - clear() +```rst +clear() -Clear any existing backtraces from the internal buffer. + Clear any existing backtraces from the internal buffer. +``` """ Base.Profile.clear doc""" - print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) +```rst +print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) -Prints profiling results to `io` (by default, `STDOUT`). If you -do not supply a `data` vector, the internal buffer of accumulated -backtraces will be used. `format` can be `:tree` or `:flat`. -If `C==true`, backtraces from C and Fortran code are shown. -the same line of code. `cols` controls the width of the display. + Prints profiling results to "io" (by default, "STDOUT"). If you + do not supply a "data" vector, the internal buffer of accumulated + backtraces will be used. "format" can be ":tree" or ":flat". + If "C==true", backtraces from C and Fortran code are shown. + "combine==true" merges instruction pointers that correspond to + the same line of code. "cols" controls the width of the display. +``` """ Base.Profile.print doc""" - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) +```rst +print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) -Prints profiling results to `io`. This variant is used to examine -results exported by a previous call to `retrieve()`. Supply the -vector `data` of backtraces and a dictionary `lidict` of line -information. + Prints profiling results to "io". This variant is used to examine + results exported by a previous call to "retrieve()". Supply the + vector "data" of backtraces and a dictionary "lidict" of line + information. +``` """ Base.Profile.print doc""" - init(; n::Integer, delay::Float64) +```rst +init(; n::Integer, delay::Float64) -Configure the `delay` between backtraces (measured in seconds), -and the number `n` of instruction pointers that may be stored. -Each instruction pointer corresponds to a single line of code; -backtraces generally consist of a long list of instruction -pointers. Default settings can be obtained by calling this function -with no arguments, and each can be set independently using keywords -or in the order `(n, delay)`. + Configure the "delay" between backtraces (measured in seconds), + and the number "n" of instruction pointers that may be stored. + Each instruction pointer corresponds to a single line of code; + backtraces generally consist of a long list of instruction + pointers. Default settings can be obtained by calling this function + with no arguments, and each can be set independently using keywords + or in the order "(n, delay)". +``` """ Base.Profile.init doc""" - fetch() -> data +```rst +fetch() -> data -Returns a reference to the internal buffer of backtraces. Note that -subsequent operations, like `clear()`, can affect `data` unless -you first make a copy. Note that the values in `data` have -meaning only on this machine in the current session, because it -depends on the exact memory addresses used in JIT-compiling. This -function is primarily for internal use; `retrieve()` may be a -better choice for most users. + Returns a reference to the internal buffer of backtraces. Note that + subsequent operations, like "clear()", can affect "data" unless + you first make a copy. Note that the values in "data" have + meaning only on this machine in the current session, because it + depends on the exact memory addresses used in JIT-compiling. This + function is primarily for internal use; "retrieve()" may be a + better choice for most users. +``` """ Base.Profile.fetch doc""" - retrieve() -> data, lidict +```rst +retrieve() -> data, lidict -set of all backtraces (`data`) and a dictionary that maps the -values that store the file name, function name, and line number. -This function allows you to save profiling results for future -analysis. + "Exports" profiling results in a portable format, returning the + set of all backtraces ("data") and a dictionary that maps the + (session-specific) instruction pointers in "data" to "LineInfo" + values that store the file name, function name, and line number. + This function allows you to save profiling results for future + analysis. +``` """ Base.Profile.retrieve doc""" - callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} +```rst +callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} -Given a previous profiling run, determine who called a particular -function. Supplying the filename (and optionally, range of line -numbers over which the function is defined) allows you to -disambiguate an overloaded method. The returned value is a vector -containing a count of the number of calls and line information -about the caller. One can optionally supply backtrace data -obtained from `retrieve()`; otherwise, the current internal -profile buffer is used. + Given a previous profiling run, determine who called a particular + function. Supplying the filename (and optionally, range of line + numbers over which the function is defined) allows you to + disambiguate an overloaded method. The returned value is a vector + containing a count of the number of calls and line information + about the caller. One can optionally supply backtrace data + obtained from "retrieve()"; otherwise, the current internal + profile buffer is used. +``` """ Base.Profile.callers doc""" - clear_malloc_data() +```rst +clear_malloc_data() -Clears any stored memory allocation data when running julia with ` -force JIT-compilation), then call `clear_malloc_data()`. Then -execute your command(s) again, quit Julia, and examine the -resulting `*.mem` files. + Clears any stored memory allocation data when running julia with " + --track-allocation". Execute the command(s) you want to test (to + force JIT-compilation), then call "clear_malloc_data()". Then + execute your command(s) again, quit Julia, and examine the + resulting "*.mem" files. +``` """ Base.Profile.clear_malloc_data doc""" - sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) +```rst +sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) -Sort the vector `v` in place. `QuickSort` is used by default -for numeric arrays while `MergeSort` is used for other arrays. -You can specify an algorithm to use via the `alg` keyword (see -Sorting Algorithms for available algorithms). The `by` keyword -lets you provide a function that will be applied to each element -before comparison; the `lt` keyword allows providing a custom -order. These options are independent and can be used together in -all possible combinations: if both `by` and `lt` are specified, -the `lt` function is applied to the result of the `by` -function; `rev=true` reverses whatever ordering specified via the + Sort the vector "v" in place. "QuickSort" is used by default + for numeric arrays while "MergeSort" is used for other arrays. + You can specify an algorithm to use via the "alg" keyword (see + Sorting Algorithms for available algorithms). The "by" keyword + lets you provide a function that will be applied to each element + before comparison; the "lt" keyword allows providing a custom + "less than" function; use "rev=true" to reverse the sorting + order. These options are independent and can be used together in + all possible combinations: if both "by" and "lt" are specified, + the "lt" function is applied to the result of the "by" + function; "rev=true" reverses whatever ordering specified via the + "by" and "lt" keywords. +``` """ sort! doc""" - sort(v, [alg=,] [by=,] [lt=,] [rev=false]) +```rst +sort(v, [alg=,] [by=,] [lt=,] [rev=false]) -Variant of `sort!` that returns a sorted copy of `v` leaving + Variant of "sort!" that returns a sorted copy of "v" leaving + "v" itself unmodified. +``` """ sort doc""" - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) +```rst +sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) -Sort a multidimensional array `A` along the given dimension. + Sort a multidimensional array "A" along the given dimension. +``` """ sort doc""" - sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) +```rst +sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Return a permutation vector of indices of "v" that puts it in + sorted order. Specify "alg" to choose a particular sorting + algorithm (see Sorting Algorithms). "MergeSort" is used by + default, and since it is stable, the resulting permutation will be + the lexicographically first one that puts the input array into + sorted order – i.e. indices of equal elements appear in ascending + order. If you choose a non-stable sorting algorithm such as + "QuickSort", a different permutation that puts the array into + order may be returned. The order is specified using the same + keywords as "sort!". -Return a permutation vector of indices of `v` that puts it in -sorted order. Specify `alg` to choose a particular sorting -algorithm (see Sorting Algorithms). `MergeSort` is used by -default, and since it is stable, the resulting permutation will be -the lexicographically first one that puts the input array into -sorted order – i.e. indices of equal elements appear in ascending -order. If you choose a non-stable sorting algorithm such as -order may be returned. The order is specified using the same -keywords as `sort!`. -See also `sortperm!()` + See also "sortperm!()" +``` """ sortperm doc""" - sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) +```rst +sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) -Like `sortperm`, but accepts a preallocated index vector `ix`. -If `initialized` is `false` (the default), ix is initialized to -contain the values `1:length(v)`. -See also `sortperm()` + Like "sortperm", but accepts a preallocated index vector "ix". + If "initialized" is "false" (the default), ix is initialized to + contain the values "1:length(v)". + + See also "sortperm()" +``` """ sortperm! doc""" - sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) +```rst +sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) -Sort the rows of matrix `A` lexicographically. + Sort the rows of matrix "A" lexicographically. +``` """ sortrows doc""" - sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) +```rst +sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) -Sort the columns of matrix `A` lexicographically. + Sort the columns of matrix "A" lexicographically. +``` """ sortcols doc""" - issorted(v, [by=,] [lt=,] [rev=false]) +```rst +issorted(v, [by=,] [lt=,] [rev=false]) -Test whether a vector is in sorted order. The `by`, `lt` and -as they do for `sort`. + Test whether a vector is in sorted order. The "by", "lt" and + "rev" keywords modify what order is considered to be sorted just + as they do for "sort". +``` """ issorted doc""" - searchsorted(a, x, [by=,] [lt=,] [rev=false]) +```rst +searchsorted(a, x, [by=,] [lt=,] [rev=false]) -Returns the range of indices of `a` which compare as equal to -order. Returns an empty range located at the insertion point if + Returns the range of indices of "a" which compare as equal to + "x" according to the order specified by the "by", "lt" and + "rev" keywords, assuming that "a" is already sorted in that + order. Returns an empty range located at the insertion point if + "a" does not contain values equal to "x". +``` """ searchsorted doc""" - searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) +```rst +searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) -Returns the index of the first value in `a` greater than or equal -to `x`, according to the specified order. Returns `length(a)+1` -if `x` is greater than all values in `a`. + Returns the index of the first value in "a" greater than or equal + to "x", according to the specified order. Returns "length(a)+1" + if "x" is greater than all values in "a". +``` """ searchsortedfirst doc""" - searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) +```rst +searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) -Returns the index of the last value in `a` less than or equal to -less than all values in `a`. + Returns the index of the last value in "a" less than or equal to + "x", according to the specified order. Returns "0" if "x" is + less than all values in "a". +``` """ searchsortedlast doc""" - select!(v, k, [by=,] [lt=,] [rev=false]) +```rst +select!(v, k, [by=,] [lt=,] [rev=false]) -Partially sort the vector `v` in place, according to the order -specified by `by`, `lt` and `rev` so that the value at index -the position where it would appear if the array were fully sorted -via a non-stable algorithm. If `k` is a single index, that value -is returned; if `k` is a range, an array of values at those -indices is returned. Note that `select!` does not fully sort the -input array. + Partially sort the vector "v" in place, according to the order + specified by "by", "lt" and "rev" so that the value at index + "k" (or range of adjacent values if "k" is a range) occurs at + the position where it would appear if the array were fully sorted + via a non-stable algorithm. If "k" is a single index, that value + is returned; if "k" is a range, an array of values at those + indices is returned. Note that "select!" does not fully sort the + input array. +``` """ select! doc""" - select(v, k, [by=,] [lt=,] [rev=false]) +```rst +select(v, k, [by=,] [lt=,] [rev=false]) -Variant of `select!` which copies `v` before partially sorting -it, thereby returning the same thing as `select!` but leaving + Variant of "select!" which copies "v" before partially sorting + it, thereby returning the same thing as "select!" but leaving + "v" unmodified. +``` """ select doc""" - length(s) +```rst +length(s) -The number of characters in string `s`. + The number of characters in string "s". +``` """ length doc""" - sizeof(s::AbstractString) +```rst +sizeof(s::AbstractString) -The number of bytes in string `s`. + The number of bytes in string "s". +``` """ sizeof doc""" - *(s, t) +```rst +*(s, t) + + Concatenate strings. The "*" operator is an alias to this + function. -Concatenate strings. The `*` operator is an alias to this -function. + julia> "Hello " * "world" + "Hello world" +``` """ Base.(:(*)) doc""" - ^(s, n) +```rst +^(s, n) -Repeat `n` times the string `s`. The `^` operator is an alias -to this function. + Repeat "n" times the string "s". The "^" operator is an alias + to this function. + + julia> "Test "^3 + "Test Test Test " +``` """ Base.(:(^)) doc""" - string(xs...) +```rst +string(xs...) -Create a string from any values using the `print` function. + Create a string from any values using the "print" function. +``` """ string doc""" - repr(x) +```rst +repr(x) -Create a string from any value using the `showall` function. + Create a string from any value using the "showall" function. +``` """ repr doc""" - bytestring(::Ptr{UInt8}[, length]) +```rst +bytestring(::Ptr{UInt8}[, length]) -Create a string from the address of a C (0-terminated) string -encoded in ASCII or UTF-8. A copy is made; the ptr can be safely -freed. If `length` is specified, the string does not have to be -0-terminated. + Create a string from the address of a C (0-terminated) string + encoded in ASCII or UTF-8. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. +``` """ bytestring doc""" - bytestring(s) +```rst +bytestring(s) -Convert a string to a contiguous byte array representation -appropriate for passing it to C functions. The string will be -encoded as either ASCII or UTF-8. + Convert a string to a contiguous byte array representation + appropriate for passing it to C functions. The string will be + encoded as either ASCII or UTF-8. +``` """ bytestring doc""" - ascii(::Array{UInt8, 1}) +```rst +ascii(::Array{UInt8, 1}) -Create an ASCII string from a byte array. + Create an ASCII string from a byte array. +``` """ ascii doc""" - ascii(s) +```rst +ascii(s) -Convert a string to a contiguous ASCII string (all characters must -be valid ASCII characters). + Convert a string to a contiguous ASCII string (all characters must + be valid ASCII characters). +``` """ ascii doc""" - ascii(::Ptr{UInt8}[, length]) +```rst +ascii(::Ptr{UInt8}[, length]) -Create an ASCII string from the address of a C (0-terminated) -string encoded in ASCII. A copy is made; the ptr can be safely -freed. If `length` is specified, the string does not have to be -0-terminated. + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. +``` """ ascii doc""" - utf8(::Array{UInt8, 1}) +```rst +utf8(::Array{UInt8, 1}) -Create a UTF-8 string from a byte array. + Create a UTF-8 string from a byte array. +``` """ utf8 doc""" - utf8(::Ptr{UInt8}[, length]) +```rst +utf8(::Ptr{UInt8}[, length]) -Create a UTF-8 string from the address of a C (0-terminated) string -encoded in UTF-8. A copy is made; the ptr can be safely freed. If -0-terminated. + Create a UTF-8 string from the address of a C (0-terminated) string + encoded in UTF-8. A copy is made; the ptr can be safely freed. If + "length" is specified, the string does not have to be + 0-terminated. +``` """ utf8 doc""" - utf8(s) +```rst +utf8(s) -Convert a string to a contiguous UTF-8 string (all characters must -be valid UTF-8 characters). + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). +``` """ utf8 doc""" - normalize_string(s, normalform::Symbol) - -Normalize the string `s` according to one of the four `normal -forms` of the Unicode standard: `normalform` can be `:NFC`, -composition) and D (canonical decomposition) convert different -visually identical representations of the same abstract string into -a single canonical form, with form C being more compact. Normal -forms KC and KD additionally canonicalize `compatibility -equivalents`: they convert characters that are abstractly similar -but visually distinct into a single canonical choice (e.g. they -expand ligatures into the individual characters), with form KC -being more compact. -Alternatively, finer control and additional transformations may be -be obtained by calling *normalize_string(s; keywords...)*, where -any number of the following boolean keywords options (which all -default to `false` except for `compose`) are specified: -For example, NFKC corresponds to the options `compose=true, -compat=true, stable=true`. +```rst +normalize_string(s, normalform::Symbol) + + Normalize the string "s" according to one of the four "normal + forms" of the Unicode standard: "normalform" can be ":NFC", + ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical + composition) and D (canonical decomposition) convert different + visually identical representations of the same abstract string into + a single canonical form, with form C being more compact. Normal + forms KC and KD additionally canonicalize "compatibility + equivalents": they convert characters that are abstractly similar + but visually distinct into a single canonical choice (e.g. they + expand ligatures into the individual characters), with form KC + being more compact. + + Alternatively, finer control and additional transformations may be + be obtained by calling *normalize_string(s; keywords...)*, where + any number of the following boolean keywords options (which all + default to "false" except for "compose") are specified: + + * "compose=false": do not perform canonical composition + + * "decompose=true": do canonical decomposition instead of + canonical composition ("compose=true" is ignored if present) + + * "compat=true": compatibility equivalents are canonicalized + + * "casefold=true": perform Unicode case folding, e.g. for case- + insensitive string comparison + + * "newline2lf=true", "newline2ls=true", or + "newline2ps=true": convert various newline sequences (LF, CRLF, + CR, NEL) into a linefeed (LF), line-separation (LS), or + paragraph-separation (PS) character, respectively + + * "stripmark=true": strip diacritical marks (e.g. accents) + + * "stripignore=true": strip Unicode's "default ignorable" + characters (e.g. the soft hyphen or the left-to-right marker) + + * "stripcc=true": strip control characters; horizontal tabs and + form feeds are converted to spaces; newlines are also converted + to spaces unless a newline-conversion flag was specified + + * "rejectna=true": throw an error if unassigned code points are + found + + * "stable=true": enforce Unicode Versioning Stability + + For example, NFKC corresponds to the options "compose=true, + compat=true, stable=true". +``` """ normalize_string doc""" - graphemes(s) -> iterator over substrings of s +```rst +graphemes(s) -> iterator over substrings of s -Returns an iterator over substrings of `s` that correspond to the -extended graphemes in the string, as defined by Unicode UAX #29. -even though they may contain more than one codepoint; for example a -letter combined with an accent mark is a single grapheme.) + Returns an iterator over substrings of "s" that correspond to the + extended graphemes in the string, as defined by Unicode UAX #29. + (Roughly, these are what users would perceive as single characters, + even though they may contain more than one codepoint; for example a + letter combined with an accent mark is a single grapheme.) +``` """ graphemes doc""" - isvalid(value) -> Bool +```rst +isvalid(value) -> Bool -Returns true if the given value is valid for its type, which -currently can be one of `Char`, `ASCIIString`, `UTF8String`, + Returns true if the given value is valid for its type, which + currently can be one of "Char", "ASCIIString", "UTF8String", + "UTF16String", or "UTF32String" +``` """ isvalid doc""" - isvalid(T, value) -> Bool +```rst +isvalid(T, value) -> Bool -Returns true if the given value is valid for that type. Types -currently can be `Char`, `ASCIIString`, `UTF8String`, -`UTF16String`, or `UTF32String` Values for `Char` can be of -type `Char` or `UInt32` Values for `ASCIIString` and -`UTF8String` can be of that type, or `Vector{UInt8}` Values for -`UTF16String` can be `UTF16String` or `Vector{UInt16}` Values -for `UTF32String` can be `UTF32String`, `Vector{Char}` or -`Vector{UInt32}`. + Returns true if the given value is valid for that type. Types + currently can be "Char", "ASCIIString", "UTF8String", + "UTF16String", or "UTF32String" Values for "Char" can be of + type "Char" or "UInt32" Values for "ASCIIString" and + "UTF8String" can be of that type, or "Vector{UInt8}" Values for + "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values + for "UTF32String" can be "UTF32String", "Vector{Char}" or + "Vector{UInt32}" +``` """ isvalid doc""" - is_assigned_char(c) -> Bool +```rst +is_assigned_char(c) -> Bool -Returns true if the given char or integer is an assigned Unicode -code point. + Returns true if the given char or integer is an assigned Unicode + code point. +``` """ is_assigned_char doc""" - ismatch(r::Regex, s::AbstractString) -> Bool +```rst +ismatch(r::Regex, s::AbstractString) -> Bool -Test whether a string contains a match of the given regular -expression. + Test whether a string contains a match of the given regular + expression. +``` """ ismatch doc""" - match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) +```rst +match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) -Search for the first match of the regular expression `r` in `s` -and return a RegexMatch object containing the match, or nothing if -the match failed. The matching substring can be retrieved by -accessing `m.match` and the captured sequences can be retrieved -by accessing `m.captures` The optional `idx` argument specifies -an index at which to start the search. + Search for the first match of the regular expression "r" in "s" + and return a RegexMatch object containing the match, or nothing if + the match failed. The matching substring can be retrieved by + accessing "m.match" and the captured sequences can be retrieved + by accessing "m.captures" The optional "idx" argument specifies + an index at which to start the search. +``` """ match doc""" - eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) +```rst +eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) -Search for all matches of a the regular expression `r` in `s` -and return a iterator over the matches. If overlap is true, the -matching sequences are allowed to overlap indices in the original -string, otherwise they must be from distinct character ranges. + Search for all matches of a the regular expression "r" in "s" + and return a iterator over the matches. If overlap is true, the + matching sequences are allowed to overlap indices in the original + string, otherwise they must be from distinct character ranges. +``` """ eachmatch doc""" - matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} +```rst +matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} -Return a vector of the matching substrings from eachmatch. + Return a vector of the matching substrings from eachmatch. +``` """ matchall doc""" - lpad(string, n, p) +```rst +lpad(string, n, p) -Make a string at least `n` columns wide when printed, by padding -on the left with copies of `p`. + Make a string at least "n" columns wide when printed, by padding + on the left with copies of "p". +``` """ lpad doc""" - rpad(string, n, p) +```rst +rpad(string, n, p) -Make a string at least `n` columns wide when printed, by padding -on the right with copies of `p`. + Make a string at least "n" columns wide when printed, by padding + on the right with copies of "p". +``` """ rpad doc""" - search(string, chars[, start]) +```rst +search(string, chars[, start]) + + Search for the first occurrence of the given characters within the + given string. The second argument may be a single character, a + vector or a set of characters, a string, or a regular expression + (though regular expressions are only allowed on contiguous strings, + such as ASCII or UTF-8 strings). The third argument optionally + specifies a starting index. The return value is a range of indexes + where the matching sequence is found, such that "s[search(s,x)] == + x": -Search for the first occurrence of the given characters within the -given string. The second argument may be a single character, a -vector or a set of characters, a string, or a regular expression -such as ASCII or UTF-8 strings). The third argument optionally -specifies a starting index. The return value is a range of indexes -where the matching sequence is found, such that `s[search(s,x)] == -x`: + "search(string, "substring")" = "start:end" such that + "string[start:end] == "substring"", or "0:-1" if unmatched. + + "search(string, 'c')" = "index" such that + "string[index] == 'c'", or "0" if unmatched. +``` """ search doc""" - rsearch(string, chars[, start]) +```rst +rsearch(string, chars[, start]) -Similar to `search`, but returning the last occurrence of the -given characters within the given string, searching in reverse from + Similar to "search", but returning the last occurrence of the + given characters within the given string, searching in reverse from + "start". +``` """ rsearch doc""" - searchindex(string, substring[, start]) +```rst +searchindex(string, substring[, start]) -Similar to `search`, but return only the start index at which the -substring is found, or 0 if it is not. + Similar to "search", but return only the start index at which the + substring is found, or 0 if it is not. +``` """ searchindex doc""" - rsearchindex(string, substring[, start]) +```rst +rsearchindex(string, substring[, start]) -Similar to `rsearch`, but return only the start index at which -the substring is found, or 0 if it is not. + Similar to "rsearch", but return only the start index at which + the substring is found, or 0 if it is not. +``` """ rsearchindex doc""" - contains(haystack, needle) +```rst +contains(haystack, needle) -Determine whether the second argument is a substring of the first. + Determine whether the second argument is a substring of the first. +``` """ contains doc""" - replace(string, pat, r[, n]) +```rst +replace(string, pat, r[, n]) -Search for the given pattern `pat`, and replace each occurrence -with `r`. If `n` is provided, replace at most `n` -occurrences. As with search, the second argument may be a single -character, a vector or a set of characters, a string, or a regular -expression. If `r` is a function, each occurrence is replaced -with `r(s)` where `s` is the matched substring. + Search for the given pattern "pat", and replace each occurrence + with "r". If "n" is provided, replace at most "n" + occurrences. As with search, the second argument may be a single + character, a vector or a set of characters, a string, or a regular + expression. If "r" is a function, each occurrence is replaced + with "r(s)" where "s" is the matched substring. +``` """ replace doc""" - split(string, [chars]; limit=0, keep=true) +```rst +split(string, [chars]; limit=0, keep=true) -Return an array of substrings by splitting the given string on -occurrences of the given character delimiters, which may be -specified in any of the formats allowed by `search`'s second -argument (i.e. a single character, collection of characters, -string, or regular expression). If `chars` is omitted, it -defaults to the set of all space characters, and `keep` is taken -to be false. The two keyword arguments are optional: they are are a -maximum size for the result and a flag determining whether empty -fields should be kept in the result. + Return an array of substrings by splitting the given string on + occurrences of the given character delimiters, which may be + specified in any of the formats allowed by "search"'s second + argument (i.e. a single character, collection of characters, + string, or regular expression). If "chars" is omitted, it + defaults to the set of all space characters, and "keep" is taken + to be false. The two keyword arguments are optional: they are are a + maximum size for the result and a flag determining whether empty + fields should be kept in the result. +``` """ split doc""" - rsplit(string, [chars]; limit=0, keep=true) +```rst +rsplit(string, [chars]; limit=0, keep=true) -Similar to `split`, but starting from the end of the string. + Similar to "split", but starting from the end of the string. +``` """ rsplit doc""" - strip(string[, chars]) +```rst +strip(string[, chars]) -Return `string` with any leading and trailing whitespace removed. -If `chars` (a character, or vector or set of characters) is -provided, instead remove characters contained in it. + Return "string" with any leading and trailing whitespace removed. + If "chars" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. +``` """ strip doc""" - lstrip(string[, chars]) +```rst +lstrip(string[, chars]) -Return `string` with any leading whitespace removed. If `chars` -remove characters contained in it. + Return "string" with any leading whitespace removed. If "chars" + (a character, or vector or set of characters) is provided, instead + remove characters contained in it. +``` """ lstrip doc""" - rstrip(string[, chars]) +```rst +rstrip(string[, chars]) -Return `string` with any trailing whitespace removed. If -provided, instead remove characters contained in it. + Return "string" with any trailing whitespace removed. If + "chars" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. +``` """ rstrip doc""" - startswith(string, prefix | chars) +```rst +startswith(string, prefix | chars) -Returns `true` if `string` starts with `prefix`. If the -second argument is a vector or set of characters, tests whether the -first character of `string` belongs to that set. + Returns "true" if "string" starts with "prefix". If the + second argument is a vector or set of characters, tests whether the + first character of "string" belongs to that set. +``` """ startswith doc""" - endswith(string, suffix | chars) +```rst +endswith(string, suffix | chars) -Returns `true` if `string` ends with `suffix`. If the second -argument is a vector or set of characters, tests whether the last -character of `string` belongs to that set. + Returns "true" if "string" ends with "suffix". If the second + argument is a vector or set of characters, tests whether the last + character of "string" belongs to that set. +``` """ endswith doc""" - uppercase(string) +```rst +uppercase(string) -Returns `string` with all characters converted to uppercase. + Returns "string" with all characters converted to uppercase. +``` """ uppercase doc""" - lowercase(string) +```rst +lowercase(string) -Returns `string` with all characters converted to lowercase. + Returns "string" with all characters converted to lowercase. +``` """ lowercase doc""" - ucfirst(string) +```rst +ucfirst(string) -Returns `string` with the first character converted to uppercase. + Returns "string" with the first character converted to uppercase. +``` """ ucfirst doc""" - lcfirst(string) +```rst +lcfirst(string) -Returns `string` with the first character converted to lowercase. + Returns "string" with the first character converted to lowercase. +``` """ lcfirst doc""" - join(strings, delim[, last]) +```rst +join(strings, delim[, last]) + + Join an array of "strings" into a single string, inserting the + given delimiter between adjacent strings. If "last" is given, it + will be used instead of "delim" between the last two strings. For + example, "join(["apples", "bananas", "pineapples"], ", ", + " and ") == "apples, bananas and pineapples"". -Join an array of `strings` into a single string, inserting the -given delimiter between adjacent strings. If `last` is given, it -will be used instead of `delim` between the last two strings. For -example, `join([`apples`, `bananas`, `pineapples`], `, `, -convertible to strings via `print(io::IOBuffer, x)`. + "strings" can be any iterable over elements "x" which are + convertible to strings via "print(io::IOBuffer, x)". +``` """ join doc""" - chop(string) +```rst +chop(string) -Remove the last character from a string + Remove the last character from a string +``` """ chop doc""" - chomp(string) +```rst +chomp(string) -Remove a trailing newline from a string + Remove a trailing newline from a string +``` """ chomp doc""" - ind2chr(string, i) +```rst +ind2chr(string, i) -Convert a byte index to a character index + Convert a byte index to a character index +``` """ ind2chr doc""" - chr2ind(string, i) +```rst +chr2ind(string, i) -Convert a character index to a byte index + Convert a character index to a byte index +``` """ chr2ind doc""" - isvalid(str, i) +```rst +isvalid(str, i) -Tells whether index `i` is valid for the given string + Tells whether index "i" is valid for the given string +``` """ isvalid doc""" - nextind(str, i) +```rst +nextind(str, i) -Get the next valid string index after `i`. Returns a value -greater than `endof(str)` at or after the end of the string. + Get the next valid string index after "i". Returns a value + greater than "endof(str)" at or after the end of the string. +``` """ nextind doc""" - prevind(str, i) +```rst +prevind(str, i) -Get the previous valid string index before `i`. Returns a value -less than `1` at the beginning of the string. + Get the previous valid string index before "i". Returns a value + less than "1" at the beginning of the string. +``` """ prevind doc""" - randstring([rng], len=8) +```rst +randstring([rng], len=8) -Create a random ASCII string of length `len`, consisting of -upper- and lower-case letters and the digits 0-9. The optional -Numbers*. + Create a random ASCII string of length "len", consisting of + upper- and lower-case letters and the digits 0-9. The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. +``` """ randstring doc""" - charwidth(c) +```rst +charwidth(c) -Gives the number of columns needed to print a character. + Gives the number of columns needed to print a character. +``` """ charwidth doc""" - strwidth(s) +```rst +strwidth(s) -Gives the number of columns needed to print a string. + Gives the number of columns needed to print a string. +``` """ strwidth doc""" - isalnum(c::Union{Char, AbstractString}) -> Bool +```rst +isalnum(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is alphanumeric, or whether this is true -for all elements of a string. A character is classified as -alphabetic if it belongs to the Unicode general category Letter or -Number, i.e. a character whose category code begins with 'L' or + Tests whether a character is alphanumeric, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter or + Number, i.e. a character whose category code begins with 'L' or + 'N'. +``` """ isalnum doc""" - isalpha(c::Union{Char, AbstractString}) -> Bool +```rst +isalpha(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is alphabetic, or whether this is true -for all elements of a string. A character is classified as -alphabetic if it belongs to the Unicode general category Letter, -i.e. a character whose category code begins with 'L'. + Tests whether a character is alphabetic, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter, + i.e. a character whose category code begins with 'L'. +``` """ isalpha doc""" - isascii(c::Union{Char, AbstractString}) -> Bool +```rst +isascii(c::Union{Char, AbstractString}) -> Bool -Tests whether a character belongs to the ASCII character set, or -whether this is true for all elements of a string. + Tests whether a character belongs to the ASCII character set, or + whether this is true for all elements of a string. +``` """ isascii doc""" - iscntrl(c::Union{Char, AbstractString}) -> Bool +```rst +iscntrl(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is a control character, or whether this -is true for all elements of a string. Control characters are the -non-printing characters of the Latin-1 subset of Unicode. + Tests whether a character is a control character, or whether this + is true for all elements of a string. Control characters are the + non-printing characters of the Latin-1 subset of Unicode. +``` """ iscntrl doc""" - isdigit(c::Union{Char, AbstractString}) -> Bool +```rst +isdigit(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is a numeric digit (0-9), or whether this -is true for all elements of a string. + Tests whether a character is a numeric digit (0-9), or whether this + is true for all elements of a string. +``` """ isdigit doc""" - isgraph(c::Union{Char, AbstractString}) -> Bool +```rst +isgraph(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is printable, and not a space, or whether -this is true for all elements of a string. Any character that -would cause a printer to use ink should be classified with -isgraph(c)==true. + Tests whether a character is printable, and not a space, or whether + this is true for all elements of a string. Any character that + would cause a printer to use ink should be classified with + isgraph(c)==true. +``` """ isgraph doc""" - islower(c::Union{Char, AbstractString}) -> Bool +```rst +islower(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is a lowercase letter, or whether this is -true for all elements of a string. A character is classified as -lowercase if it belongs to Unicode category Ll, Letter: Lowercase. + Tests whether a character is a lowercase letter, or whether this is + true for all elements of a string. A character is classified as + lowercase if it belongs to Unicode category Ll, Letter: Lowercase. +``` """ islower doc""" - isnumber(c::Union{Char, AbstractString}) -> Bool +```rst +isnumber(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is numeric, or whether this is true for -all elements of a string. A character is classified as numeric if -it belongs to the Unicode general category Number, i.e. a character -whose category code begins with 'N'. + Tests whether a character is numeric, or whether this is true for + all elements of a string. A character is classified as numeric if + it belongs to the Unicode general category Number, i.e. a character + whose category code begins with 'N'. +``` """ isnumber doc""" - isprint(c::Union{Char, AbstractString}) -> Bool +```rst +isprint(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is printable, including spaces, but not a -control character. For strings, tests whether this is true for all -elements of the string. + Tests whether a character is printable, including spaces, but not a + control character. For strings, tests whether this is true for all + elements of the string. +``` """ isprint doc""" - ispunct(c::Union{Char, AbstractString}) -> Bool +```rst +ispunct(c::Union{Char, AbstractString}) -> Bool -Tests whether a character belongs to the Unicode general category -Punctuation, i.e. a character whose category code begins with 'P'. -For strings, tests whether this is true for all elements of the -string. + Tests whether a character belongs to the Unicode general category + Punctuation, i.e. a character whose category code begins with 'P'. + For strings, tests whether this is true for all elements of the + string. +``` """ ispunct doc""" - isspace(c::Union{Char, AbstractString}) -> Bool +```rst +isspace(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is any whitespace character. Includes -ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', -Latin-1 character U+0085, and characters in Unicode category Zs. -For strings, tests whether this is true for all elements of the -string. + Tests whether a character is any whitespace character. Includes + ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', + Latin-1 character U+0085, and characters in Unicode category Zs. + For strings, tests whether this is true for all elements of the + string. +``` """ isspace doc""" - isupper(c::Union{Char, AbstractString}) -> Bool +```rst +isupper(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is an uppercase letter, or whether this -is true for all elements of a string. A character is classified -as uppercase if it belongs to Unicode category Lu, Letter: -Uppercase, or Lt, Letter: Titlecase. + Tests whether a character is an uppercase letter, or whether this + is true for all elements of a string. A character is classified + as uppercase if it belongs to Unicode category Lu, Letter: + Uppercase, or Lt, Letter: Titlecase. +``` """ isupper doc""" - isxdigit(c::Union{Char, AbstractString}) -> Bool +```rst +isxdigit(c::Union{Char, AbstractString}) -> Bool -Tests whether a character is a valid hexadecimal digit, or whether -this is true for all elements of a string. + Tests whether a character is a valid hexadecimal digit, or whether + this is true for all elements of a string. +``` """ isxdigit doc""" - symbol(x...) -> Symbol +```rst +symbol(x...) -> Symbol -Create a `Symbol` by concatenating the string representations of -the arguments together. + Create a "Symbol" by concatenating the string representations of + the arguments together. +``` """ symbol doc""" - escape_string(str::AbstractString) -> AbstractString +```rst +escape_string(str::AbstractString) -> AbstractString -General escaping of traditional C and Unicode escape sequences. See + General escaping of traditional C and Unicode escape sequences. See + "print_escaped()" for more general escaping. +``` """ escape_string doc""" - unescape_string(s::AbstractString) -> AbstractString +```rst +unescape_string(s::AbstractString) -> AbstractString -General unescaping of traditional C and Unicode escape sequences. -Reverse of `escape_string()`. See also `print_unescaped()`. + General unescaping of traditional C and Unicode escape sequences. + Reverse of "escape_string()". See also "print_unescaped()". +``` """ unescape_string doc""" - utf16(s) +```rst +utf16(s) + + Create a UTF-16 string from a byte array, array of "UInt16", or + any other string type. (Data must be valid UTF-16. Conversions of + byte arrays check for a byte-order marker in the first two bytes, + and do not include it in the resulting string.) -Create a UTF-16 string from a byte array, array of `UInt16`, or -any other string type. (Data must be valid UTF-16. Conversions of -byte arrays check for a byte-order marker in the first two bytes, -and do not include it in the resulting string.) -Note that the resulting `UTF16String` data is terminated by the -NUL codepoint (16-bit zero), which is not treated as a character in -the string (so that it is mostly invisible in Julia); this allows -the string to be passed directly to external functions requiring -NUL-terminated data. This NUL is appended automatically by the -can instead use *UTF16String(A)`* to construct the string without -making a copy of the data and treating the NUL as a terminator -rather than as part of the string. + Note that the resulting "UTF16String" data is terminated by the + NUL codepoint (16-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf16(s)* conversion function. If you have a "UInt16" array + "A" that is already NUL-terminated valid UTF-16 data, then you + can instead use *UTF16String(A)`* to construct the string without + making a copy of the data and treating the NUL as a terminator + rather than as part of the string. +``` """ utf16 doc""" - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) +```rst +utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) -Create a string from the address of a NUL-terminated UTF-16 string. -A copy is made; the pointer can be safely freed. If `length` is -specified, the string does not have to be NUL-terminated. + Create a string from the address of a NUL-terminated UTF-16 string. + A copy is made; the pointer can be safely freed. If "length" is + specified, the string does not have to be NUL-terminated. +``` """ utf16 doc""" - utf32(s) +```rst +utf32(s) -Create a UTF-32 string from a byte array, array of `Char` or -check for a byte-order marker in the first four bytes, and do not -include it in the resulting string.) -Note that the resulting `UTF32String` data is terminated by the -NUL codepoint (32-bit zero), which is not treated as a character in -the string (so that it is mostly invisible in Julia); this allows -the string to be passed directly to external functions requiring -NUL-terminated data. This NUL is appended automatically by the -then you can instead use `UTF32String(A)` to construct the string -without making a copy of the data and treating the NUL as a -terminator rather than as part of the string. + Create a UTF-32 string from a byte array, array of "Char" or + "UInt32", or any other string type. (Conversions of byte arrays + check for a byte-order marker in the first four bytes, and do not + include it in the resulting string.) + + Note that the resulting "UTF32String" data is terminated by the + NUL codepoint (32-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf32(s)* conversion function. If you have a "Char" or + "UInt32" array "A" that is already NUL-terminated UTF-32 data, + then you can instead use *UTF32String(A)`* to construct the string + without making a copy of the data and treating the NUL as a + terminator rather than as part of the string. +``` """ utf32 doc""" - utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) +```rst +utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) -Create a string from the address of a NUL-terminated UTF-32 string. -A copy is made; the pointer can be safely freed. If `length` is -specified, the string does not have to be NUL-terminated. + Create a string from the address of a NUL-terminated UTF-32 string. + A copy is made; the pointer can be safely freed. If "length" is + specified, the string does not have to be NUL-terminated. +``` """ utf32 doc""" - wstring(s) +```rst +wstring(s) -This is a synonym for either `utf32(s)` or `utf16(s)`, -depending on whether `Cwchar_t` is 32 or 16 bits, respectively. -The synonym `WString` for `UTF32String` or `UTF16String` is -also provided. + This is a synonym for either "utf32(s)" or "utf16(s)", + depending on whether "Cwchar_t" is 32 or 16 bits, respectively. + The synonym "WString" for "UTF32String" or "UTF16String" is + also provided. +``` """ wstring doc""" - runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) +```rst +runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) -Run the Julia unit tests listed in `tests`, which can be either a -string or an array of strings, using `numcores` processors. (not -exported) + Run the Julia unit tests listed in "tests", which can be either a + string or an array of strings, using "numcores" processors. (not + exported) +``` """ runtests doc""" - @test(ex) +```rst +@test(ex) -Test the expression `ex` and calls the current handler to handle -the result. + Test the expression "ex" and calls the current handler to handle + the result. +``` """ Base.Test.@test doc""" - @test_throws(extype, ex) +```rst +@test_throws(extype, ex) -Test that the expression `ex` throws an exception of type + Test that the expression "ex" throws an exception of type + "extype" and calls the current handler to handle the result. +``` """ Base.Test.@test_throws doc""" - @test_approx_eq(a, b) +```rst +@test_approx_eq(a, b) -Test two floating point numbers `a` and `b` for equality taking -in account small numerical errors. + Test two floating point numbers "a" and "b" for equality taking + in account small numerical errors. +``` """ Base.Test.@test_approx_eq doc""" - @test_approx_eq_eps(a, b, tol) +```rst +@test_approx_eq_eps(a, b, tol) -Test two floating point numbers `a` and `b` for equality taking -in account a margin of tolerance given by `tol`. + Test two floating point numbers "a" and "b" for equality taking + in account a margin of tolerance given by "tol". +``` """ Base.Test.@test_approx_eq_eps doc""" - with_handler(f, handler) +```rst +with_handler(f, handler) -Run the function `f` using the `handler` as the handler. + Run the function "f" using the "handler" as the handler. +``` """ Base.Test.with_handler - - From 068b7da93b6de77a974870140aea65c136240dd0 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 21:42:22 -0400 Subject: [PATCH 21/27] new manual --- doc/stdlib/arrays.rst | 734 +++++++++++--------- doc/stdlib/base.rst | 924 ++++++++++++++++---------- doc/stdlib/c.rst | 149 ++++- doc/stdlib/collections.rst | 837 +++++++++++++++-------- doc/stdlib/dates.rst | 272 +++++--- doc/stdlib/file.rst | 261 ++++---- doc/stdlib/io-network.rst | 676 ++++++++++++------- doc/stdlib/libc.rst | 74 ++- doc/stdlib/libdl.rst | 40 +- doc/stdlib/linalg.rst | 1056 +++++++++++++++++++++-------- doc/stdlib/math.rst | 1293 +++++++++++++++++++++--------------- doc/stdlib/numbers.rst | 356 ++++++---- doc/stdlib/parallel.rst | 357 ++++++---- doc/stdlib/pkg.rst | 149 +++-- doc/stdlib/profile.rst | 63 +- doc/stdlib/sort.rst | 80 ++- doc/stdlib/strings.rst | 393 +++++++---- doc/stdlib/test.rst | 24 +- 18 files changed, 5023 insertions(+), 2715 deletions(-) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 7ed48ccccecf2..fee28971e8fbf 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -9,41 +9,44 @@ Basic functions .. function:: ndims(A) -> Integer - Returns the number of dimensions of A - + Returns the number of dimensions of A .. function:: size(A[, 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 = rand(2,3,4); + 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> size(A,2) - 3 + julia> A = rand(2,3,4); - julia> size(A,3,2) - (4,3) + julia> size(A, 2) + 3 + julia> size(A,3,2) + (4,3) .. function:: iseltype(A, T) - Tests whether A or its elements are of type T - + Tests whether A or its elements are of type T .. function:: length(s) - The number of characters in string ``s``. - + The number of characters in string "s". .. function:: 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 (like ``Array``), this is simply the range ``1: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 non-integer indices). + 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 (like "Array"), this is + simply the range "1: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 non-integer indices). - Example for a sparse 2-d array: - - :: + Example for a sparse 2-d array: julia> A = sprand(2, 3, 0.5) 2x3 sparse matrix with 4 Float64 entries: @@ -69,7 +72,6 @@ Basic functions (iter.I_1,iter.I_2) = (2,3) A[iter] = 0.8090413606455655 - If you supply more than one ``AbstractArray`` argument, ``eachindex`` will create an iterable object that is fast for all arguments (a ``UnitRange`` if all inputs have fast linear indexing, a @@ -87,138 +89,153 @@ largest range along each dimension. .. function:: countnz(A) - Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use ``nnz``, which returns the number of stored values. - + Counts the number of nonzero values in array A (dense or sparse). + Note that this is not a constant-time operation. For sparse + matrices, one should usually use "nnz", which returns the number + of stored values. .. function:: conj!(A) - Convert an array to its complex conjugate in-place - + Convert an array to its complex conjugate in-place .. function:: stride(A, k) - Returns the distance in memory (in number of elements) between adjacent elements in dimension k - + Returns the distance in memory (in number of elements) between + adjacent elements in dimension k .. function:: strides(A) - Returns a tuple of the memory strides in each dimension - + Returns a tuple of the memory strides in each dimension .. function:: ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` - + Returns a tuple of subscripts into array "a" corresponding to the + linear index "index" .. function:: ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` - + Returns a tuple of subscripts into array "a" corresponding to the + linear index "index" .. function:: sub2ind(dims, i, j, k...) -> index - The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts - + The inverse of "ind2sub", returns the linear index corresponding + to the provided subscripts Constructors ------------ .. function:: Array(dims) - ``Array{T}(dims)`` constructs an uninitialized dense array with element type ``T``. ``dims`` may be a tuple or a series of integer arguments. The syntax ``Array(T, dims)`` is also available, but deprecated. - + "Array{T}(dims)" constructs an uninitialized dense array with + element type "T". "dims" may be a tuple or a series of integer + arguments. The syntax "Array(T, dims)" is also available, but + deprecated. .. function:: 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, ...)``. - + 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, ...)". .. function:: cell(dims) - Construct an uninitialized cell array (heterogeneous array). ``dims`` can be either a tuple or a series of integer arguments. - + Construct an uninitialized cell array (heterogeneous array). + "dims" can be either a tuple or a series of integer arguments. .. function:: zeros(A) - Create an array of all zeros with the same element type and shape as A. - + Create an array of all zeros with the same element type and shape + as A. .. function:: zeros(A) - Create an array of all zeros with the same element type and shape as A. - + Create an array of all zeros with the same element type and shape + as A. .. function:: ones(A) - Create an array of all ones with the same element type and shape as A. - + Create an array of all ones with the same element type and shape as + A. .. function:: ones(A) - Create an array of all ones with the same element type and shape as A. - + Create an array of all ones with the same element type and shape as + A. .. function:: trues(dims) - Create a ``BitArray`` with all values set to true - + Create a "BitArray" with all values set to true .. function:: falses(dims) - Create a ``BitArray`` with all values set to false - + Create a "BitArray" with all values set to false .. function:: fill(x, dims) - Create an array filled with the value ``x``. For example, ``fill(1.0, (10,10))`` returns a 10x10 array of floats, with each element initialized to 1.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 evaluating ``Foo()`` once. + Create an array filled with the value "x". For example, + "fill(1.0, (10,10))" returns a 10x10 array of floats, with each + element initialized to 1.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 evaluating "Foo()" once. .. function:: fill!(A, x) - Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating ``Foo()`` once. - + Fill array "A" with the value "x". If "x" is an object + reference, all elements will refer to the same object. "fill!(A, + Foo())" will return "A" filled with the result of evaluating + "Foo()" once. .. function:: reshape(A, dims) - Create an array with the same data as the given array, but with different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. - + Create an array with the same data as the given array, but with + different dimensions. An implementation for a particular type of + array may choose whether the data is copied or shared. .. function:: similar(array, element_type, dims) - Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The ``dims`` argument may be a tuple or a series of integer arguments. For some special ``AbstractArray`` objects which are not real containers (like ranges), this function returns a standard ``Array`` to allow operating on elements. - + Create an uninitialized array of the same type as the given array, + but with the specified element type and dimensions. The second and + third arguments are both optional. The "dims" argument may be a + tuple or a series of integer arguments. For some special + "AbstractArray" objects which are not real containers (like + ranges), this function returns a standard "Array" to allow + operating on elements. .. function:: reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, ``reinterpret(Float32, UInt32(7))`` interprets the 4 bytes corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. - + Change the type-interpretation of a block of memory. For example, + "reinterpret(Float32, UInt32(7))" interprets the 4 bytes + corresponding to "UInt32(7)" as a "Float32". For arrays, this + constructs an array with the same binary data as the given array, + but with the specified element type. .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. - + Constructs an identity matrix of the same dimensions and type as + "A". .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. - + Constructs an identity matrix of the same dimensions and type as + "A". .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. - + Constructs an identity matrix of the same dimensions and type as + "A". .. function:: linspace(start, stop, n=100) - Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. - + Construct a range of "n" linearly spaced elements from "start" + to "stop". .. function:: logspace(start, stop, n=50) - Construct a vector of ``n`` logarithmically spaced numbers from ``10^start`` to ``10^stop``. - + Construct a vector of "n" logarithmically spaced numbers from + "10^start" to "10^stop". Mathematical operators and functions ------------------------------------ @@ -227,487 +244,563 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) - Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results ``f(as...)`` for each position. - + Broadcasts the arrays "As" to a common size by expanding + singleton dimensions, and returns an array of the results + "f(as...)" for each position. .. function:: broadcast!(f, dest, As...) - Like ``broadcast``, but store the result of ``broadcast(f, As...)`` in the ``dest`` array. Note that ``dest`` is only used to store the result, and does not supply arguments to ``f`` unless it is also listed in the ``As``, as in ``broadcast!(f, A, A, B)`` to perform ``A[:] = broadcast(f, A, B)``. - + Like "broadcast", but store the result of "broadcast(f, As...)" + in the "dest" array. Note that "dest" is only used to store the + result, and does not supply arguments to "f" unless it is also + listed in the "As", as in "broadcast!(f, A, A, B)" to perform + "A[:] = broadcast(f, A, B)". .. function:: bitbroadcast(f, As...) - Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. - + Like "broadcast", but allocates a "BitArray" to store the + result, rather then an "Array". .. function:: broadcast_function(f) - Returns a function ``broadcast_f`` such that ``broadcast_function(f)(As...) === broadcast(f, As...)``. Most useful in the form ``const broadcast_f = broadcast_function(f)``. - + Returns a function "broadcast_f" such that + "broadcast_function(f)(As...) === broadcast(f, As...)". Most + useful in the form "const broadcast_f = broadcast_function(f)". .. function:: broadcast!_function(f) - Like ``broadcast_function``, but for ``broadcast!``. - + Like "broadcast_function", but for "broadcast!". Indexing, Assignment, and Concatenation --------------------------------------- .. function:: 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, ...)``. - + 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, ...)". .. function:: sub(A, inds...) - Like ``getindex()``, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling ``getindex()`` or ``setindex!()`` on the returned ``SubArray`` computes the indices to the parent array on the fly without checking bounds. - + Like "getindex()", but returns a view into the parent array "A" + with the given indices instead of making a copy. Calling + "getindex()" or "setindex!()" on the returned "SubArray" + computes the indices to the parent array on the fly without + checking bounds. .. function:: parent(A) - Returns the ``parent array`` of an array view type (e.g., SubArray), or the array itself if it is not a view - + Returns the "parent array" of an array view type (e.g., + SubArray), or the array itself if it is not a view .. function:: parentindexes(A) - From an array view ``A``, returns the corresponding indexes in the parent - + From an array view "A", returns the corresponding indexes in the + parent .. function:: slicedim(A, d, i) - Return all the data of ``A`` where the index for dimension ``d`` equals ``i``. Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``. - + Return all the data of "A" where the index for dimension "d" + equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is + in position "d". .. function:: slice(A, inds...) - Returns a view of array ``A`` with the given indices like ``sub()``, but drops all dimensions indexed with scalars. - + Returns a view of array "A" with the given indices like + "sub()", but drops all dimensions indexed with scalars. .. function:: 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, ...)``. - + 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, ...)". .. function:: broadcast_getindex(A, inds...) - Broadcasts the ``inds`` arrays to a common size like ``broadcast``, and returns an array of the results ``A[ks...]``, where ``ks`` goes over the positions in the broadcast. - + Broadcasts the "inds" arrays to a common size like "broadcast", + and returns an array of the results "A[ks...]", where "ks" goes + over the positions in the broadcast. .. function:: broadcast_setindex!(A, X, inds...) - Broadcasts the ``X`` and ``inds`` arrays to a common size and stores the value from each position in ``X`` at the indices given by the same positions in ``inds``. - + Broadcasts the "X" and "inds" arrays to a common size and + stores the value from each position in "X" at the indices given + by the same positions in "inds". .. function:: cat(dims, A...) - Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If ``dims`` is an iterable containing several dimensions, this allows to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, block matrix with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. - + Concatenate the input arrays along the specified dimensions in the + iterable "dims". For dimensions not in "dims", all input arrays + should have the same size, which will also be the size of the + output array along that dimension. For dimensions in "dims", the + size of the output array is the sum of the sizes of the input + arrays along that dimension. If "dims" is a single number, the + different arrays are tightly stacked along that dimension. If + "dims" is an iterable containing several dimensions, this allows + to construct block diagonal matrices and their higher-dimensional + 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 with *matrices[1]*, *matrices[2]*, ... as diagonal + blocks and matching zero blocks away from the diagonal. .. function:: vcat(A...) - Concatenate along dimension 1 - + Concatenate along dimension 1 .. function:: hcat(A...) - Concatenate along dimension 2 - + Concatenate along dimension 2 .. function:: 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. For example, ``[a b;c d e]`` calls ``hvcat((2,3),a,b,c,d,e)``. - - If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. + 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. For example, + "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". + If the first argument is a single integer "n", then all block + rows are assumed to have "n" block columns. .. function:: flipdim(A, d) - Reverse ``A`` in dimension ``d``. - + Reverse "A" in dimension "d". .. function:: circshift(A, shifts) - Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. - + Circularly shift the data in an array. The second argument is a + vector giving the amount to shift in each dimension. .. function:: find(f, A) - Return a vector of the linear indexes of ``A`` where ``f`` returns true. - + Return a vector of the linear indexes of "A" where "f" returns + true. .. function:: find(f, A) - Return a vector of the linear indexes of ``A`` where ``f`` returns true. - + Return a vector of the linear indexes of "A" where "f" returns + true. .. function:: findn(A) - Return a vector of indexes for each dimension giving the locations of the non-zeros in ``A`` (determined by ``A[i]!=0``). - + Return a vector of indexes for each dimension giving the locations + of the non-zeros in "A" (determined by "A[i]!=0"). .. function:: findnz(A) - Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and column indexes of the non-zero values in matrix ``A``, and ``V`` is a vector of the non-zero values. - + Return a tuple "(I, J, V)" where "I" and "J" are the row and + column indexes of the non-zero values in matrix "A", and "V" is + a vector of the non-zero values. .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which ``predicate`` returns true. - + Return the index of the first element of "A" for which + "predicate" returns true. .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which ``predicate`` returns true. - + Return the index of the first element of "A" for which + "predicate" returns true. .. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which ``predicate`` returns true. - + Return the index of the first element of "A" for which + "predicate" returns true. .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which ``predicate`` returns true. - + Return the index of the last element of "A" for which + "predicate" returns true. .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which ``predicate`` returns true. - + Return the index of the last element of "A" for which + "predicate" returns true. .. function:: findlast(predicate, A) - Return the index of the last element of ``A`` for which ``predicate`` returns true. - + Return the index of the last element of "A" for which + "predicate" returns true. .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` ``predicate`` returns true, or ``0`` if not found. - + Find the next index >= "i" of an element of "A" equal to "v" + (using "=="), or "0" if not found. .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` ``predicate`` returns true, or ``0`` if not found. - + Find the next index >= "i" of an element of "A" equal to "v" + (using "=="), or "0" if not found. .. function:: findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` ``predicate`` returns true, or ``0`` if not found. - + Find the next index >= "i" of an element of "A" equal to "v" + (using "=="), or "0" if not found. .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. - + Find the previous index <= "i" of an element of "A" equal to + "v" (using "=="), or "0" if not found. .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. - + Find the previous index <= "i" of an element of "A" equal to + "v" (using "=="), or "0" if not found. .. function:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. - + Find the previous index <= "i" of an element of "A" equal to + "v" (using "=="), or "0" if not found. .. function:: permutedims(A, perm) - Permute the dimensions of array ``A``. ``perm`` is a vector specifying a permutation of length ``ndims(A)``. This is a generalization of transpose for multi-dimensional arrays. Transpose is equivalent to ``permutedims(A, [2,1])``. - + Permute the dimensions of array "A". "perm" is a vector + specifying a permutation of length "ndims(A)". This is a + generalization of transpose for multi-dimensional arrays. Transpose + is equivalent to "permutedims(A, [2,1])". .. function:: ipermutedims(A, perm) - Like ``permutedims()``, except the inverse of the given permutation is applied. - + Like "permutedims()", except the inverse of the given permutation + is applied. .. function:: permutedims!(dest, src, perm) - Permute the dimensions of array ``src`` and store the result in the array ``dest``. ``perm`` is a vector specifying a permutation of length ``ndims(src)``. The preallocated array ``dest`` should have ``size(dest) == size(src)[perm]`` and is completely overwritten. No in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. - + Permute the dimensions of array "src" and store the result in the + array "dest". "perm" is a vector specifying a permutation of + length "ndims(src)". The preallocated array "dest" should have + "size(dest) == size(src)[perm]" and is completely overwritten. No + in-place permutation is supported and unexpected results will + happen if *src* and *dest* have overlapping memory regions. .. function:: squeeze(A, dims) - Remove the dimensions specified by ``dims`` from array ``A``. Elements of ``dims`` must be unique and within the range - + Remove the dimensions specified by "dims" from array "A". + Elements of "dims" must be unique and within the range + "1:ndims(A)". .. function:: vec(Array) -> Vector - Vectorize an array using column-major convention. - + Vectorize an array using column-major convention. .. function:: promote_shape(s1, s2) - Check two array shapes for compatibility, allowing trailing singleton dimensions, and return whichever shape has more dimensions. - + Check two array shapes for compatibility, allowing trailing + singleton dimensions, and return whichever shape has more + dimensions. .. function:: checkbounds(array, indexes...) - Throw an error if the specified indexes are not in bounds for the given array. - + Throw an error if the specified indexes are not in bounds for the + given array. .. function:: randsubseq(A, p) -> Vector - Return a vector consisting of a random subsequence of the given array ``A``, where each element of ``A`` is included (in order) with independent probability ``p``. (Complexity is linear in small and ``A`` is large.) Technically, this process is known as - + Return a vector consisting of a random subsequence of the given + array "A", where each element of "A" is included (in order) + with independent probability "p". (Complexity is linear in + "p*length(A)", so this function is efficient even if "p" is + small and "A" is large.) Technically, this process is known as + "Bernoulli sampling" of "A". .. function:: randsubseq!(S, A, p) - Like ``randsubseq``, but the results are stored in ``S`` (which is resized as needed). - + Like "randsubseq", but the results are stored in "S" (which is + resized as needed). Array functions --------------- .. function:: cumprod(A[, dim]) - Cumulative product along a dimension ``dim`` (defaults to 1). See also ``cumprod!()`` to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). - + Cumulative product along a dimension "dim" (defaults to 1). See + also "cumprod!()" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). .. function:: cumprod!(B, A[, dim]) - Cumulative product of ``A`` along a dimension, storing the result in ``B``. The dimension defaults to 1. - + Cumulative product of "A" along a dimension, storing the result + in "B". The dimension defaults to 1. .. function:: cumsum(A[, dim]) - Cumulative sum along a dimension ``dim`` (defaults to 1). See also performance and to control the precision of the output (e.g. to avoid overflow). - + Cumulative sum along a dimension "dim" (defaults to 1). See also + "cumsum!()" to use a preallocated output array, both for + performance and to control the precision of the output (e.g. to + avoid overflow). .. function:: cumsum!(B, A[, dim]) - Cumulative sum of ``A`` along a dimension, storing the result in - + Cumulative sum of "A" along a dimension, storing the result in + "B". The dimension defaults to 1. .. function:: cumsum_kbn(A[, dim]) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1. - + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier + compensated summation algorithm for additional accuracy. The + dimension defaults to 1. .. function:: cummin(A[, dim]) - Cumulative minimum along a dimension. The dimension defaults to 1. - + Cumulative minimum along a dimension. The dimension defaults to 1. .. function:: cummax(A[, dim]) - Cumulative maximum along a dimension. The dimension defaults to 1. - + Cumulative maximum along a dimension. The dimension defaults to 1. .. function:: diff(A[, dim]) - Finite difference operator of matrix or vector. - + Finite difference operator of matrix or vector. .. function:: gradient(F[, h]) - Compute differences along vector ``F``, using ``h`` as the spacing between points. The default spacing is one. - + Compute differences along vector "F", using "h" as the spacing + between points. The default spacing is one. .. function:: rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. - + Rotate matrix "A" 180 degrees an integer "k" number of times. + If "k" is even, this is equivalent to a "copy". .. function:: rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. - + Rotate matrix "A" 180 degrees an integer "k" number of times. + If "k" is even, this is equivalent to a "copy". .. function:: rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + Rotate matrix "A" left 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". .. function:: rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + Rotate matrix "A" left 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". .. function:: rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + Rotate matrix "A" right 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". .. function:: rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. - + Rotate matrix "A" right 90 degrees an integer "k" number of + times. If "k" is zero or a multiple of four, this is equivalent + to a "copy". .. function:: reducedim(f, A, dims[, initial]) - Reduce 2-argument function ``f`` along dimensions of ``A``. The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for ``reduce``. + Reduce 2-argument function "f" along dimensions of "A". + "dims" is a vector specifying the dimensions to reduce, and + "initial" is the initial value to use in the reductions. For *+*, + ***, *max* and *min* the *initial* argument is optional. + The associativity of the reduction is implementation-dependent; if + you need a particular associativity, e.g. left-to-right, you should + write your own loop. See documentation for "reduce". .. function:: mapreducedim(f, op, A, dims[, initial]) - Evaluates to the same as *reducedim(op, map(f, A), dims, f(initial))*, but is generally faster because the intermediate array is avoided. - + Evaluates to the same as *reducedim(op, map(f, A), dims, + f(initial))*, but is generally faster because the intermediate + array is avoided. .. function:: mapslices(f, A, dims) - Transform the given dimensions of array ``A`` using function ``f``. where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if - + Transform the given dimensions of array "A" using function "f". + "f" is called on each slice of "A" of the form + "A[...,:,...,:,...]". "dims" is an integer vector specifying + where the colons go in this expression. The results are + concatenated along the remaining dimensions. For example, if + "dims" is "[1,2]" and A is 4-dimensional, "f" is called on + "A[:,:,i,j]" for all "i" and "j". .. function:: sum_kbn(A) - Returns the sum of all array elements, using the Kahan-Babuska- Neumaier compensated summation algorithm for additional accuracy. - + Returns the sum of all array elements, using the Kahan-Babuska- + Neumaier compensated summation algorithm for additional accuracy. .. function:: cartesianmap(f, dims) - Given a ``dims`` tuple of integers ``(m, n, ...)``, call ``f`` on all combinations of integers in the ranges ``1:m``, ``1:n``, etc. + Given a "dims" tuple of integers "(m, n, ...)", call "f" on + all combinations of integers in the ranges "1:m", "1:n", etc. + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 Combinatorics ------------- .. function:: nthperm(p) - Return the ``k`` that generated permutation ``p``. Note that - + Return the "k" that generated permutation "p". Note that + "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". .. function:: nthperm(p) - Return the ``k`` that generated permutation ``p``. Note that - + Return the "k" that generated permutation "p". Note that + "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". .. function:: nthperm!(v, k) - In-place version of ``nthperm()``. - + In-place version of "nthperm()". .. function:: randperm([rng], n) - Construct a random permutation of length ``n``. The optional Numbers*. - + Construct a random permutation of length "n". The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. .. function:: invperm(v) - Return the inverse permutation of v. - + Return the inverse permutation of v. .. function:: isperm(v) -> Bool - Returns true if v is a valid permutation. - + Returns true if v is a valid permutation. .. function:: permute!(v, p) - Permute vector ``v`` in-place, according to permutation ``p``. No checking is done to verify that ``p`` is a permutation. To return a new permutation, use ``v[p]``. Note that this is generally faster than ``permute!(v,p)`` for large vectors. + Permute vector "v" in-place, according to permutation "p". No + checking is done to verify that "p" is a permutation. + To return a new permutation, use "v[p]". Note that this is + generally faster than "permute!(v,p)" for large vectors. .. function:: ipermute!(v, p) - Like permute!, but the inverse of the given permutation is applied. - + Like permute!, but the inverse of the given permutation is applied. .. function:: randcycle([rng], n) - Construct a random cyclic permutation of length ``n``. The optional Numbers*. - + Construct a random cyclic permutation of length "n". The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. .. function:: shuffle([rng], v) - Return a randomly permuted copy of ``v``. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. - + Return a randomly permuted copy of "v". The optional "rng" + argument specifies a random number generator, see *Random Numbers*. .. function:: shuffle!([rng], v) - In-place version of ``shuffle()``. - + In-place version of "shuffle()". .. function:: reverse(v[, start=1[, stop=length(v)]]) - Return a copy of ``v`` reversed from start to stop. - + Return a copy of "v" reversed from start to stop. .. function:: reverseind(v, i) - Given an index ``i`` in ``reverse(v)``, return the corresponding index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``. string.) - + Given an index "i" in "reverse(v)", return the corresponding + index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". + (This can be nontrivial in the case where "v" is a Unicode + string.) .. function:: reverse!(v[, start=1[, stop=length(v)]]) -> v - In-place version of ``reverse()``. - + In-place version of "reverse()". .. function:: combinations(array, n) - Generate all combinations of ``n`` elements from an indexable object. Because the number of combinations can be very large, this function returns an iterator object. Use combinations. - + Generate all combinations of "n" elements from an indexable + object. Because the number of combinations can be very large, this + function returns an iterator object. Use + "collect(combinations(array,n))" to get an array of all + combinations. .. function:: permutations(array) - Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use ``collect(permutations(array))`` to get an array of all permutations. - + Generate all permutations of an indexable object. Because the + number of permutations can be very large, this function returns an + iterator object. Use "collect(permutations(array))" to get an + array of all permutations. .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use "collect(partitions(array,m))" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using "length(partitions(array,m))". .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use "collect(partitions(array,m))" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using "length(partitions(array,m))". .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use "collect(partitions(array,m))" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using "length(partitions(array,m))". .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``. - + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use "collect(partitions(array,m))" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using "length(partitions(array,m))". BitArrays --------- .. function:: bitpack(A::AbstractArray{T, N}) -> BitArray - Converts a numeric array to a packed boolean array - + Converts a numeric array to a packed boolean array .. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} - Converts a packed boolean array to an array of booleans - + Converts a packed boolean array to an array of booleans .. function:: flipbits!(B::BitArray{N}) -> BitArray{N} - Performs a bitwise not operation on B. See *~ operator*. - + Performs a bitwise not operation on B. See *~ operator*. .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. - + Performs a left rotation operation on B. .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. - + Performs a left rotation operation on B. .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation. - + Performs a left rotation operation. .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. - + Performs a right rotation operation on B. .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. - + Performs a right rotation operation on B. .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation. - + Performs a right rotation operation. .. _stdlib-sparse: @@ -718,101 +811,146 @@ Sparse matrices support much of the same set of operations as dense matrices. Th .. function:: sparse(A) - Convert an AbstractMatrix ``A`` into a sparse matrix. - + Convert an AbstractMatrix "A" into a sparse matrix. .. function:: sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. - + Convert a dense vector "A" into a sparse matrix of size "m x + 1". In julia, sparse vectors are really just sparse matrices with + one column. .. function:: sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. - + Convert a dense vector "A" into a sparse matrix of size "m x + 1". In julia, sparse vectors are really just sparse matrices with + one column. .. function:: issparse(S) - Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. - + Returns "true" if "S" is sparse, and "false" otherwise. .. function:: sparse(A) - Convert an AbstractMatrix ``A`` into a sparse matrix. - + Convert an AbstractMatrix "A" into a sparse matrix. .. function:: sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. - + Convert a dense vector "A" into a sparse matrix of size "m x + 1". In julia, sparse vectors are really just sparse matrices with + one column. .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. + Converts an orthogonal or unitary matrix stored as a + "QRCompactWYQ" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. + Optionally takes a "thin" Boolean argument, which if "true" + omits the columns that span the rows of "R" in the QR + factorization that are zero. The resulting matrix is the "Q" in a + thin QR factorization (sometimes called the reduced QR + factorization). If "false", returns a "Q" that spans all rows + of "R" in its corresponding QR factorization. .. function:: nnz(A) - Returns the number of stored (filled) elements in a sparse matrix. - + Returns the number of stored (filled) elements in a sparse matrix. .. function:: spzeros(m, n) - Create a sparse matrix of size ``m x n``. This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. - + Create a sparse matrix of size "m x n". This sparse matrix will + not contain any nonzero values. No storage will be allocated for + nonzero values during construction. .. function:: spones(S) - Create a sparse matrix with the same structure as that of ``S``, but with every nonzero element having the value ``1.0``. - + Create a sparse matrix with the same structure as that of "S", + but with every nonzero element having the value "1.0". .. function:: speye(type, m[, n]) - Create a sparse identity matrix of specified type of size ``m x m``. In case ``n`` is supplied, create a sparse identity matrix of size ``m x n``. - + Create a sparse identity matrix of specified type of size "m x + m". In case "n" is supplied, create a sparse identity matrix of + size "m x n". .. function:: spdiagm(B, d[, m, n]) - Construct a sparse diagonal matrix. ``B`` is a tuple of vectors containing the diagonals and ``d`` is a tuple containing the positions of the diagonals. In the case the input contains only one diagonaly, ``B`` can be a vector (instead of a tuple) and ``d`` can be the diagonal position (instead of a tuple), defaulting to 0 resulting sparse matrix. - + Construct a sparse diagonal matrix. "B" is a tuple of vectors + containing the diagonals and "d" is a tuple containing the + positions of the diagonals. In the case the input contains only one + diagonaly, "B" can be a vector (instead of a tuple) and "d" can + be the diagonal position (instead of a tuple), defaulting to 0 + (diagonal). Optionally, "m" and "n" specify the size of the + resulting sparse matrix. .. function:: sprand([rng], m, n, p[, rfn]) - Create a random ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by by ``rfn``. The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see *Random Numbers*. - + Create a random "m" by "n" sparse matrix, in which the + probability of any element being nonzero is independently given by + "p" (and hence the mean density of nonzeros is also exactly + "p"). Nonzero values are sampled from the distribution specified + by "rfn". The uniform distribution is used in case "rfn" is not + specified. The optional "rng" argument specifies a random number + generator, see *Random Numbers*. .. function:: sprandn(m, n, p) - Create a random ``m`` by ``n`` sparse matrix with the specified nonzero values are sampled from the normal distribution. - + Create a random "m" by "n" sparse matrix with the specified + (independent) probability "p" of any entry being nonzero, where + nonzero values are sampled from the normal distribution. .. function:: sprandbool(m, n, p) - Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being - + Create a random "m" by "n" sparse boolean matrix with the + specified (independent) probability "p" of any entry being + "true". .. function:: etree(A[, post]) - Compute the elimination tree of a symmetric sparse matrix ``A`` from ``triu(A)`` and, optionally, its post-ordering permutation. - + Compute the elimination tree of a symmetric sparse matrix "A" + from "triu(A)" and, optionally, its post-ordering permutation. .. function:: symperm(A, p) - Return the symmetric permutation of A, which is ``A[p,p]``. A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. - + Return the symmetric permutation of A, which is "A[p,p]". A + should be symmetric and sparse, where only the upper triangular + part of the matrix is stored. This algorithm ignores the lower + triangular part of the matrix. Only the upper triangular part of + the result is returned as well. .. function:: nonzeros(A) - Return a vector of the structural nonzero values in sparse matrix matrix. The returned vector points directly to the internal nonzero storage of ``A``, and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``. - + Return a vector of the structural nonzero values in sparse matrix + "A". This includes zeros that are explicitly stored in the sparse + matrix. The returned vector points directly to the internal nonzero + storage of "A", and any modifications to the returned vector will + mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". .. function:: rowvals(A) - Return a vector of the row indices of ``A``, and any modifications to the returned vector will mutate ``A`` as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See ``nonzeros(A)`` and ``nzrange(A, col)``. - + Return a vector of the row indices of "A", and any modifications + to the returned vector will mutate "A" as well. Given the + internal storage format of sparse matrices, providing access to how + the row indices are stored internally can be useful in conjuction + with iterating over structural nonzero values. See "nonzeros(A)" + and "nzrange(A, col)". .. function:: nzrange(A, col) - Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with ``nonzeros(A)`` and matrix - + Return the range of indices to the structural nonzero values of a + sparse matrix column. In conjunction with "nonzeros(A)" and + "rowvals(A)", 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 diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 29ba74d980638..335f60b0822fd 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -22,83 +22,96 @@ Getting Around .. function:: exit([code]) - Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. - + Quit (or control-D at the prompt). The default exit code is zero, + indicating that the processes completed successfully. .. function:: quit() - Quit the program indicating that the processes completed successfully. This function calls ``exit(0)`` (see ``exit()``). - + Quit the program indicating that the processes completed + successfully. This function calls "exit(0)" (see "exit()"). .. function:: atexit(f) - Register a zero-argument function to be called at exit. - + Register a zero-argument function to be called at exit. .. function:: atreplinit(f) - Register a one-argument function to be called before the REPL interface is initialized in interactive sessions; this is useful to customize the interface. The argument of ``f`` is the REPL object. This function should be called from within the ``.juliarc.jl`` initialization file. - + Register a one-argument function to be called before the REPL + interface is initialized in interactive sessions; this is useful to + customize the interface. The argument of "f" is the REPL object. + This function should be called from within the ".juliarc.jl" + initialization file. .. function:: isinteractive() -> Bool - Determine whether Julia is running an interactive session. - + Determine whether Julia is running an interactive session. .. function:: whos([Module,] [pattern::Regex]) - Print information about exported global variables in a module, optionally restricted to those matching ``pattern``. - + Print information about exported global variables in a module, + optionally restricted to those matching "pattern". .. function:: edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. - + Edit the definition of a function, optionally specifying a tuple of + types to indicate which method to edit. .. function:: edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. - + Edit the definition of a function, optionally specifying a tuple of + types to indicate which method to edit. .. function:: @edit() - Evaluates the arguments to the function call, determines their types, and calls the ``edit`` function on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls the "edit" function on the resulting expression .. function:: less(function[, types]) - Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. - + Show the definition of a function using the default pager, + optionally specifying a tuple of types to indicate which method to + see. .. function:: less(function[, types]) - Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. - + Show the definition of a function using the default pager, + optionally specifying a tuple of types to indicate which method to + see. .. function:: @less() - Evaluates the arguments to the function call, determines their types, and calls the ``less`` function on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls the "less" function on the resulting expression .. function:: clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard - + Return a string with the contents of the operating system clipboard + ("paste"). .. function:: clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard - + Return a string with the contents of the operating system clipboard + ("paste"). .. function:: require(file::AbstractString...) - Load source files once, in the context of the ``Main`` module, on every active node, searching standard locations for files. current ``include`` path but does not use it to search for files library code, and is implicitly called by ``using`` to load packages. When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``, then tries paths in the global array ``LOAD_PATH``. + Load source files once, in the context of the "Main" module, on + every active node, searching standard locations for files. + "require" is considered a top-level operation, so it sets the + current "include" path but does not use it to search for files + (see help for "include"). This function is typically used to load + library code, and is implicitly called by "using" to load + packages. + When searching for files, "require" first looks in the current + working directory, then looks for package code under "Pkg.dir()", + then tries paths in the global array "LOAD_PATH". .. function:: reload(file::AbstractString) - Like ``require``, except forces loading of files regardless of whether they have been loaded before. Typically used when interactively developing libraries. - + Like "require", except forces loading of files regardless of + whether they have been loaded before. Typically used when + interactively developing libraries. .. function:: include("file.jl") @@ -107,8 +120,9 @@ Getting Around .. function:: include_string(code::AbstractString) - Like ``include``, except reads code from the given string rather than from a file. Since there is no file path involved, no path processing or fetching from node 1 is done. - + Like "include", except reads code from the given string rather + than from a file. Since there is no file path involved, no path + processing or fetching from node 1 is done. .. function:: help(name) @@ -120,43 +134,56 @@ Getting Around .. function:: which(symbol) - Return the module in which the binding for the variable referenced by ``symbol`` was created. - + Return the module in which the binding for the variable referenced + by "symbol" was created. .. function:: which(symbol) - Return the module in which the binding for the variable referenced by ``symbol`` was created. - + Return the module in which the binding for the variable referenced + by "symbol" was created. .. function:: @which() - Applied to a function call, it evaluates the arguments to the specified function call, and returns the ``Method`` object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the ``which`` function. - + Applied to a function call, it evaluates the arguments to the + specified function call, and returns the "Method" object for the + method that would be called for those arguments. Applied to a + variable, it returns the module in which the variable was bound. It + calls out to the "which" function. .. function:: methods(f[, types]) - Returns the method table for ``f``. If ``types`` is specified, returns an array of methods whose types match. + Returns the method table for "f". + If "types" is specified, returns an array of methods whose types + match. .. function:: methodswith(typ[, module or function][, showparents]) - Return an array of methods with an argument of type ``typ``. If optional ``showparents`` is ``true``, also return arguments with a parent type of ``typ``, excluding type ``Any``. The optional second argument restricts the search to a particular module or function. + Return an array of methods with an argument of type "typ". If + optional "showparents" is "true", also return arguments with a + parent type of "typ", excluding type "Any". + The optional second argument restricts the search to a particular + module or function. .. function:: @show() - Show an expression and result, returning the result - + Show an expression and result, returning the result .. function:: versioninfo([verbose::Bool]) - Print information about the version of Julia in use. If the as well. - + Print information about the version of Julia in use. If the + "verbose" argument is true, detailed system information is shown + as well. .. function:: workspace() - Replace the top-level module (``Main``) with a new one, providing a clean workspace. The previous ``Main`` module is made available as statement such as ``using LastMain.Package``. This function should only be used interactively. + Replace the top-level module ("Main") with a new one, providing a + clean workspace. The previous "Main" module is made available as + "LastMain". A previously-loaded package can be accessed using a + statement such as "using LastMain.Package". + This function should only be used interactively. .. data:: ans @@ -168,231 +195,348 @@ All Objects .. function:: ===(x, y) - See the ``is()`` operator + See the "is()" operator .. function:: isa(x, type) -> Bool - Determine whether ``x`` is of the given ``type``. - + Determine whether "x" is of the given "type". .. function:: isequal(x, y) - Similar to ``==``, except treats all floating-point ``NaN`` values as equal to each other, and treats ``-0.0`` as unequal to ``0.0``. The default implementation of ``isequal`` calls ``==``, so if you have a type that doesn't have these floating-point subtleties then you probably only need to define ``==``. hash(y)``. This typically means that if you define your own `==`` function then you must define a corresponding ``hash`` (and vice versa). Collections typically implement ``isequal`` by calling ``isequal`` recursively on all contents. Scalar types generally do not need to implement ``isequal`` separate from ``==``, unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on ``isnan``, ``signbit``, and ``==``). + Similar to "==", except treats all floating-point "NaN" values + as equal to each other, and treats "-0.0" as unequal to "0.0". + The default implementation of "isequal" calls "==", so if you + have a type that doesn't have these floating-point subtleties then + you probably only need to define "==". + "isequal" is the comparison function used by hash tables + ("Dict"). "isequal(x,y)" must imply that "hash(x) == + hash(y)". -.. function:: isless(x, y) + This typically means that if you define your own "==" function + then you must define a corresponding "hash" (and vice versa). + Collections typically implement "isequal" by calling "isequal" + recursively on all contents. - Test whether ``x`` is less than ``y``, according to a canonical total order. Values that are normally unordered, such as ``NaN``, are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``. Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as + Scalar types generally do not need to implement "isequal" + separate from "==", unless they represent floating-point numbers + amenable to a more efficient implementation than that provided as a + generic fallback (based on "isnan", "signbit", and "=="). +.. function:: isless(x, y) -.. function:: ifelse(condition::Bool, x, y) + Test whether "x" is less than "y", according to a canonical + total order. Values that are normally unordered, such as "NaN", + are ordered in an arbitrary but consistent fashion. This is the + default comparison used by "sort". Non-numeric types with a + canonical total order should implement this function. Numeric types + only need to implement it if they have special values such as + "NaN". - Return ``x`` if ``condition`` is true, otherwise return ``y``. This differs from ``?`` or ``if`` in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using in generated code and provide higher performance in tight loops. +.. function:: ifelse(condition::Bool, x, y) + Return "x" if "condition" is true, otherwise return "y". This + differs from "?" or "if" in that it is an ordinary function, so + all the arguments are evaluated first. In some cases, using + "ifelse" instead of an "if" statement can eliminate the branch + in generated code and provide higher performance in tight loops. .. function:: lexcmp(x, y) - Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than lexicographically comparable types, and ``lexless`` will call - + Compare "x" and "y" lexicographically and return -1, 0, or 1 + depending on whether "x" is less than, equal to, or greater than + "y", respectively. This function should be defined for + lexicographically comparable types, and "lexless" will call + "lexcmp" by default. .. function:: lexless(x, y) - Determine whether ``x`` is lexicographically less than ``y``. - + Determine whether "x" is lexicographically less than "y". .. function:: typeof(x) - Get the concrete type of ``x``. - + Get the concrete type of "x". .. function:: tuple(xs...) - Construct a tuple of the given objects. - + Construct a tuple of the given objects. .. function:: ntuple(f::Function, n) - Create a tuple of length ``n``, computing each element as ``f(i)``, where ``i`` is the index of the element. - + Create a tuple of length "n", computing each element as "f(i)", + where "i" is the index of the element. .. function:: object_id(x) - Get a unique integer id for ``x``. ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``. - + Get a unique integer id for "x". "object_id(x)==object_id(y)" + if and only if "is(x,y)". .. function:: hash(x[, h]) - Compute an integer hash code such that ``isequal(x,y)`` implies code to be mixed with the result. New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``) to guarantee the property mentioned above. + Compute an integer hash code such that "isequal(x,y)" implies + "hash(x)==hash(y)". The optional second argument "h" is a hash + code to be mixed with the result. + New types should implement the 2-argument form, typically by + calling the 2-argument "hash" method recursively in order to mix + hashes of the contents with each other (and with "h"). + Typically, any type that implements "hash" should also implement + its own "==" (hence "isequal") to guarantee the property + mentioned above. .. function:: finalizer(x, function) - Register a function ``f(x)`` to be called when there are no program-accessible references to ``x``. The behavior of this function is unpredictable if ``x`` is of a bits type. - + Register a function "f(x)" to be called when there are no + program-accessible references to "x". The behavior of this + function is unpredictable if "x" is of a bits type. .. function:: finalize(x) - Immediately run finalizers registered for object ``x``. - + Immediately run finalizers registered for object "x". .. function:: copy(x) - Create a shallow copy of ``x``: the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. - + Create a shallow copy of "x": the outer structure is copied, but + not all internal values. For example, copying an array produces a + new array with identically-same elements as the original. .. function:: deepcopy(x) - Create a deep copy of ``x``: everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling *deepcopy* on an object should generally have the same effect as serializing and then deserializing it. As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``, and the ``dict`` variable should be updated as appropriate before returning. - + Create a deep copy of "x": everything is copied recursively, + resulting in a fully independent object. For example, deep-copying + an array produces a new array whose elements are deep copies of the + original elements. Calling *deepcopy* on an object should generally + have the same effect as serializing and then deserializing it. + + As a special case, functions can only be actually deep-copied if + they are anonymous, otherwise they are just copied. The difference + is only relevant in the case of closures, i.e. functions which may + contain hidden internal references. + + While it isn't normally necessary, user-defined types can override + the default "deepcopy" behavior by defining a specialized version + of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" + (which shouldn't otherwise be used), where "T" is the type to be + specialized for, and "dict" keeps track of objects copied so far + within the recursion. Within the definition, "deepcopy_internal" + should be used in place of "deepcopy", and the "dict" variable + should be updated as appropriate before returning. .. function:: isdefined([object], index | symbol) - Tests whether an assignable location is defined. The arguments can be an array and index, a composite object and field name (as a symbol), or a module and a symbol. With a single symbol argument, tests whether a global variable with that name is defined in - + Tests whether an assignable location is defined. The arguments can + be an array and index, a composite object and field name (as a + symbol), or a module and a symbol. With a single symbol argument, + tests whether a global variable with that name is defined in + "current_module()". .. function:: convert(T, x) - Convert ``x`` to a value of type ``T``. If ``T`` is an ``Integer`` type, an ``InexactError`` will be raised if ``x`` is not representable by ``T``, for example if ``x`` is not integer-valued, or is outside the range supported by ``T``. If ``T`` is a ``FloatingPoint`` or ``Rational`` type, then it will return the closest value to ``x`` representable by ``T``. + Convert "x" to a value of type "T". + If "T" is an "Integer" type, an "InexactError" will be raised + if "x" is not representable by "T", for example if "x" is not + integer-valued, or is outside the range supported by "T". -.. function:: promote(xs...) + julia> convert(Int, 3.0) + 3 - Convert all arguments to their common promotion type (if any), and return them all (as a tuple). + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 + If "T" is a "FloatingPoint" or "Rational" type, then it will + return the closest value to "x" representable by "T". -.. function:: oftype(x, y) + julia> x = 1/3 + 0.3333333333333333 + + julia> convert(Float32, x) + 0.33333334f0 + + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 + +.. function:: promote(xs...) - Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``). + Convert all arguments to their common promotion type (if any), and + return them all (as a tuple). +.. function:: oftype(x, y) + + Convert "y" to the type of "x" ("convert(typeof(x), y)"). .. function:: widen(type | x) - If the argument is a type, return a ``larger`` type (for numeric types, this will be a type with at least as much range and precision as the argument, and usually more). Otherwise the argument ``x`` is converted to ``widen(typeof(x))``. + If the argument is a type, return a "larger" type (for numeric + types, this will be a type with at least as much range and + precision as the argument, and usually more). Otherwise the + argument "x" is converted to "widen(typeof(x))". + julia> widen(Int32) + Int64 -.. function:: identity(x) + julia> widen(1.5f0) + 1.5 - The identity function. Returns its argument. +.. function:: identity(x) + The identity function. Returns its argument. Types ----- .. function:: super(T::DataType) - Return the supertype of DataType T - + Return the supertype of DataType T .. function:: <:(T1, T2) - Subtype operator, equivalent to ``issubtype(T1,T2)``. - + Subtype operator, equivalent to "issubtype(T1,T2)". .. function:: <:(T1, T2) - Subtype operator, equivalent to ``issubtype(T1,T2)``. - + Subtype operator, equivalent to "issubtype(T1,T2)". .. function:: subtypes(T::DataType) - Return a list of immediate subtypes of DataType T. Note that all currently loaded subtypes are included, including those not visible in the current module. - + Return a list of immediate subtypes of DataType T. Note that all + currently loaded subtypes are included, including those not visible + in the current module. .. function:: typemin(type) - The lowest value representable by the given (real) numeric type. - + The lowest value representable by the given (real) numeric type. .. function:: typemax(type) - The highest value representable by the given (real) numeric type. - + The highest value representable by the given (real) numeric type. .. function:: realmin(type) - The smallest in absolute value non-subnormal value representable by the given floating-point type - + The smallest in absolute value non-subnormal value representable by + the given floating-point type .. function:: realmax(type) - The highest finite value representable by the given floating-point type - + The highest finite value representable by the given floating-point + type .. function:: maxintfloat(type) - The largest integer losslessly representable by the given floating- point type - + The largest integer losslessly representable by the given floating- + point type .. function:: sizeof(s::AbstractString) - The number of bytes in string ``s``. - + The number of bytes in string "s". .. function:: eps(::DateTime) -> Millisecond - Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" + for "Date" values. .. function:: eps(::DateTime) -> Millisecond - Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" + for "Date" values. .. function:: promote_type(type1, type2) - Determine a type big enough to hold values of each argument type without loss, whenever possible. In some cases, where no type exists to which both types can be promoted losslessly, some loss is tolerated; for example, ``promote_type(Int64,Float64)`` returns represented exactly as ``Float64`` values. - + Determine a type big enough to hold values of each argument type + without loss, whenever possible. In some cases, where no type + exists to which both types can be promoted losslessly, some loss is + tolerated; for example, "promote_type(Int64,Float64)" returns + "Float64" even though strictly, not all "Int64" values can be + represented exactly as "Float64" values. .. function:: promote_rule(type1, type2) - Specifies what type should be used by ``promote`` when given values of types ``type1`` and ``type2``. This function should not be called directly, but should have definitions added to it for new types as appropriate. - + Specifies what type should be used by "promote" when given values + of types "type1" and "type2". This function should not be + called directly, but should have definitions added to it for new + types as appropriate. .. function:: getfield(value, name::Symbol) - Extract a named field from a value of composite type. The syntax - + Extract a named field from a value of composite type. The syntax + "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls + "getfield(a, b)". .. function:: setfield!(value, name::Symbol, x) - Assign ``x`` to a named field in ``value`` of composite type. The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``, and the syntax - + Assign "x" to a named field in "value" of composite type. The + syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax + "a.(b) = c" calls "setfield!(a, b, c)". .. function:: fieldoffsets(type) - The byte offset of each field of a type relative to the data start. For example, we could use it in the following manner to summarize information about a struct type: - + The byte offset of each field of a type relative to the data start. + For example, we could use it in the following manner to summarize + information about a struct type: + + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; + + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) .. function:: fieldtype(type, name::Symbol | index::Int) - Determine the declared type of a field (specified by name or index) in a composite type. - + Determine the declared type of a field (specified by name or index) + in a composite type. .. function:: isimmutable(v) - True if value ``v`` is immutable. See *Immutable Composite Types* for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of - + True if value "v" is immutable. See *Immutable Composite Types* + for a discussion of immutability. Note that this function works on + values, so if you give it a type, it will tell you that a value of + "DataType" is mutable. .. function:: isbits(T) - True if ``T`` is a ``plain data`` type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as ``UInt8``, ``Float64``, and + True if "T" is a "plain data" type, meaning it is immutable and + contains no references to other values. Typical examples are + numeric types such as "UInt8", "Float64", and + "Complex{Float64}". + julia> isbits(Complex{Float64}) + true -.. function:: isleaftype(T) + julia> isbits(Complex) + false - Determine whether ``T`` is a concrete type that can have instances, meaning its only subtypes are itself and ``None`` (but ``T`` itself is not ``None``). +.. function:: isleaftype(T) + Determine whether "T" is a concrete type that can have instances, + meaning its only subtypes are itself and "None" (but "T" itself + is not "None"). .. function:: typejoin(T, S) - Compute a type that contains both ``T`` and ``S``. - + Compute a type that contains both "T" and "S". .. function:: typeintersect(T, S) - Compute a type that contains the intersection of ``T`` and ``S``. Usually this will be the smallest such type or one close to it. - + Compute a type that contains the intersection of "T" and "S". + Usually this will be the smallest such type or one close to it. .. function:: Val{c} @@ -418,115 +562,165 @@ Types .. function:: instances(T::Type) - Return a collection of all instances of the given type, if applicable. Mostly used for enumerated types (see ``@enum``). - + Return a collection of all instances of the given type, if + applicable. Mostly used for enumerated types (see "@enum"). Generic Functions ----------------- .. function:: method_exists(f, Tuple type) -> Bool - Determine whether the given generic function has a method matching the given ``Tuple`` of argument types. + Determine whether the given generic function has a method matching + the given "Tuple" of argument types. + julia> method_exists(length, Tuple{Array}) + true .. function:: applicable(f, args...) -> Bool - Determine whether the given generic function has a method applicable to the given arguments. + Determine whether the given generic function has a method + applicable to the given arguments. + julia> function f(x, y) + x + y + end; -.. function:: invoke(f, (types...), args...) + julia> applicable(f, 1) + false - Invoke a method for the given generic function matching the specified types (as a tuple), on the specified arguments. The arguments must be compatible with the specified types. This allows invoking a method other than the most specific matching method, which is useful when the behavior of a more general definition is explicitly needed (often as part of the implementation of a more specific method of the same function). + julia> applicable(f, 1, 2) + true +.. function:: invoke(f, (types...), args...) + + Invoke a method for the given generic function matching the + specified types (as a tuple), on the specified arguments. The + arguments must be compatible with the specified types. This allows + invoking a method other than the most specific matching method, + which is useful when the behavior of a more general definition is + explicitly needed (often as part of the implementation of a more + specific method of the same function). .. function:: |>(x, f) - Applies a function to the preceding argument. This allows for easy function chaining. + Applies a function to the preceding argument. This allows for easy + function chaining. + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 .. function:: call(x, args...) - If ``x`` is not a ``Function``, then ``x(args...)`` is equivalent to ``call(x, args...)``. This means that function-like behavior can be added to any type by defining new ``call`` methods. - + If "x" is not a "Function", then "x(args...)" is equivalent + to "call(x, args...)". This means that function-like behavior + can be added to any type by defining new "call" methods. Syntax ------ .. function:: eval([m::Module], expr::Expr) - Evaluate an expression in the given module and return the result. Every module (except those defined with ``baremodule``) has its own 1-argument definition of ``eval``, which evaluates expressions in that module. - + Evaluate an expression in the given module and return the result. + Every module (except those defined with "baremodule") has its own + 1-argument definition of "eval", which evaluates expressions in + that module. .. function:: @eval() - Evaluate an expression and return the value. - + Evaluate an expression and return the value. .. function:: evalfile(path::AbstractString) - Load the file using ``include``, evaluate all expressions, and return the value of the last one. - + Load the file using "include", evaluate all expressions, and + return the value of the last one. .. function:: esc(e::ANY) - Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the *Macros* section of the Metaprogramming chapter of the manual for more details and examples. - + Only valid in the context of an Expr returned from a macro. + Prevents the macro hygiene pass from turning embedded variables + into gensym variables. See the *Macros* section of the + Metaprogramming chapter of the manual for more details and + examples. .. function:: gensym([tag]) - Generates a symbol which will not conflict with other variable names. - + Generates a symbol which will not conflict with other variable + names. .. function:: @gensym() - Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym(``x``); y = gensym(``y``)``. - + Generates a gensym symbol for a variable. For example, "@gensym x + y" is transformed into "x = gensym("x"); y = gensym("y")". .. function:: parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. - + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. .. function:: parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. - + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. Nullables --------- .. function:: Nullable(x) - Wrap value ``x`` in an object of type ``Nullable``, which indicates whether a value is present. ``Nullable(x)`` yields a non-empty wrapper, and ``Nullable{T}()`` yields an empty instance of a wrapper that might contain a value of type ``T``. - + Wrap value "x" in an object of type "Nullable", which indicates + whether a value is present. "Nullable(x)" yields a non-empty + wrapper, and "Nullable{T}()" yields an empty instance of a + wrapper that might contain a value of type "T". .. 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: + 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 .. 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: + 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: -.. function:: isnull(x) + get(dict, key) do + # default value calculated here + time() + end - Is the ``Nullable`` object ``x`` null, i.e. missing a value? +.. function:: isnull(x) + Is the "Nullable" object "x" null, i.e. missing a value? System ------ .. function:: run(command) - Run a command object, constructed with backticks. Throws an error if anything goes wrong, including the process exiting with a non- zero status. - + Run a command object, constructed with backticks. Throws an error + if anything goes wrong, including the process exiting with a non- + zero status. .. function:: spawn(command) - Run a command object asynchronously, returning the resulting - + Run a command object asynchronously, returning the resulting + "Process" object. .. data:: DevNull @@ -535,33 +729,39 @@ System .. function:: success(command) - Run a command object, constructed with backticks, and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started. - + Run a command object, constructed with backticks, and tell whether + it was successful (exited with a code of 0). An exception is raised + if the process cannot be started. .. function:: process_running(p::Process) - Determine whether a process is currently running. - + Determine whether a process is currently running. .. function:: process_exited(p::Process) - Determine whether a process has exited. - + Determine whether a process has exited. .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. - + Implemented by cluster managers. It is called on the master + process, by "rmprocs". It should cause the remote worker + specified by "pid" to exit. + "Base.kill(manager::ClusterManager.....)" executes a remote + "exit()" on "pid" .. function:: open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. + **Example**: "open(readall, "file.txt")" .. function:: open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. + **Example**: "open(readall, "file.txt")" .. function:: Sys.set_process_title(title::AbstractString) @@ -573,108 +773,153 @@ System .. function:: readandwrite(command) - Starts running a command asynchronously, and returns a tuple process, and the process object itself. - + Starts running a command asynchronously, and returns a tuple + (stdout,stdin,process) of the output stream and input stream of the + process, and the process object itself. .. function:: ignorestatus(command) - Mark a command object so that running it will not throw an error if the result code is non-zero. - + Mark a command object so that running it will not throw an error if + the result code is non-zero. .. function:: detach(command) - Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. - + Mark a command object so that it will be run in a new process + group, allowing it to outlive the julia process, and not have + Ctrl-C interrupts passed to it. .. function:: setenv(command, env; dir=working_dir) - Set environment variables to use when running the given command. of strings of the form ``var=val``, or zero or more replace) the existing environment, create ``env`` by ``copy(ENV)`` and then setting ``env[``var``]=val`` as desired, or use The ``dir`` keyword argument can be used to specify a working directory for the command. + Set environment variables to use when running the given command. + "env" is either a dictionary mapping strings to strings, an array + of strings of the form ""var=val"", or zero or more + ""var"=>val" pair arguments. In order to modify (rather than + replace) the existing environment, create "env" by "copy(ENV)" + and then setting "env["var"]=val" as desired, or use + "withenv". + The "dir" keyword argument can be used to specify a working + directory for the command. .. function:: withenv(f::Function, kv::Pair...) - Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``var``=>val` arguments ``kv``. ``withenv`` is generally used via the be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. - + Execute "f()" in an environment that is temporarily modified (not + replaced as in "setenv") by zero or more ""var"=>val" + arguments "kv". "withenv" is generally used via the + "withenv(kv...) do ... end" syntax. A value of "nothing" can + be used to temporarily unset an environment variable (if it is + set). When "withenv" returns, the original environment has been + restored. .. function:: pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. + Redirect I/O to or from the given "command". Keyword arguments + specify which of the command's streams should be redirected. + "append" controls whether file output appends to the file. This + is a more general version of the 2-argument "pipe" function. + "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when + "from" is a command, and to "pipe(to, stdin=from)" when + "from" is another kind of data source. + + **Examples**: + * "run(pipe(`dothings`, stdout="out.txt", + stderr="errs.txt"))" + * "run(pipe(`update`, stdout="log.txt", append=true))" .. function:: pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. is a more general version of the 2-argument ``pipe`` function. + Redirect I/O to or from the given "command". Keyword arguments + specify which of the command's streams should be redirected. + "append" controls whether file output appends to the file. This + is a more general version of the 2-argument "pipe" function. + "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when + "from" is a command, and to "pipe(to, stdin=from)" when + "from" is another kind of data source. + **Examples**: + * "run(pipe(`dothings`, stdout="out.txt", + stderr="errs.txt"))" -.. function:: gethostname() -> AbstractString + * "run(pipe(`update`, stdout="log.txt", append=true))" - Get the local machine's host name. +.. function:: gethostname() -> AbstractString + Get the local machine's host name. .. function:: getipaddr() -> AbstractString - Get the IP address of the local machine, as a string of the form - + Get the IP address of the local machine, as a string of the form + "x.x.x.x". .. function:: getpid() -> Int32 - Get julia's process ID. - + Get julia's process ID. .. function:: time(t::TmStruct) - Converts a ``TmStruct`` struct to a number of seconds since the epoch. - + Converts a "TmStruct" struct to a number of seconds since the + epoch. .. function:: time_ns() - Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. - + Get the time in nanoseconds. The time corresponding to 0 is + undefined, and wraps every 5.8 years. .. function:: tic() - Set a timer to be read by the next call to ``toc()`` or ``toq()``. The macro call ``@time expr`` can also be used to time evaluation. - + Set a timer to be read by the next call to "toc()" or "toq()". + The macro call "@time expr" can also be used to time evaluation. .. function:: toc() - Print and return the time elapsed since the last ``tic()``. - + Print and return the time elapsed since the last "tic()". .. function:: toq() - Return, but do not print, the time elapsed since the last - + Return, but do not print, the time elapsed since the last + "tic()". .. function:: @time() - A macro to execute an expression, printing the time it took to execute, the number of allocations, and the total number of bytes its execution caused to be allocated, before returning the value of the expression. - + A macro to execute an expression, printing the time it took to + execute, the number of allocations, and the total number of bytes + its execution caused to be allocated, before returning the value of + the expression. .. function:: @timev() - This is a verbose version of the ``@time`` macro, it first prints the same information as ``@time``, then any non-zero memory allocation counters, and then returns the value of the expression. - + This is a verbose version of the "@time" macro, it first prints + the same information as "@time", then any non-zero memory + allocation counters, and then returns the value of the expression. .. function:: @timed() - A macro to execute an expression, and return the value of the expression, elapsed time, total bytes allocated, garbage collection time, and an object with various memory allocation counters. - + A macro to execute an expression, and return the value of the + expression, elapsed time, total bytes allocated, garbage collection + time, and an object with various memory allocation counters. .. function:: @elapsed() - A macro to evaluate an expression, discarding the resulting value, instead returning the number of seconds it took to execute as a floating-point number. - + A macro to evaluate an expression, discarding the resulting value, + instead returning the number of seconds it took to execute as a + floating-point number. .. function:: @allocated() - A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the ``@time`` macros, which do not try to adjust for the effects of compilation. - + A macro to evaluate an expression, discarding the resulting value, + instead returning the total number of bytes allocated during + evaluation of the expression. Note: the expression is evaluated + inside a local function, instead of the current context, in order + to eliminate the effects of compilation, however, there still may + be some allocations due to JIT compilation. This also makes the + results inconsistent with the "@time" macros, which do not try to + adjust for the effects of compilation. .. function:: EnvHash() -> EnvHash - A singleton of this type provides a hash table interface to environment variables. - + A singleton of this type provides a hash table interface to + environment variables. .. data:: ENV @@ -682,56 +927,59 @@ System .. function:: @unix() - Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + Given "@unix? a : b", do "a" on Unix systems (including Linux + and OS X) and "b" elsewhere. See documentation for Handling + Platform Variations in the Calling C and Fortran Code section of + the manual. .. function:: @osx() - Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. .. function:: @linux() - Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See + documentation for Handling Platform Variations in the Calling C and + Fortran Code section of the manual. .. function:: @windows() - Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. - + Given "@windows? a : b", do "a" on Windows and "b" elsewhere. + See documentation for Handling Platform Variations in the Calling C + and Fortran Code section of the manual. Errors ------ .. function:: error(message::AbstractString) - Raise an ``ErrorException`` with the given message - + Raise an "ErrorException" with the given message .. function:: throw(e) - Throw an object as an exception - + Throw an object as an exception .. function:: rethrow([e]) - Throw an object without changing the current exception backtrace. The default argument is the current exception (if called within a - + Throw an object without changing the current exception backtrace. + The default argument is the current exception (if called within a + "catch" block). .. function:: backtrace() - Get a backtrace object for the current program point. - + Get a backtrace object for the current program point. .. function:: catch_backtrace() - Get the backtrace of the current exception, for use within - + Get the backtrace of the current exception, for use within + "catch" blocks. .. function:: assert(cond) - Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. - + Throw an "AssertionError" if "cond" is false. Also available as + the macro "@assert expr". .. function:: @assert cond [text] @@ -739,280 +987,278 @@ Errors .. function:: ArgumentError(msg) - The parameters to a function call do not match a valid signature. - + The parameters to a function call do not match a valid signature. .. function:: AssertionError([msg]) - The asserted condition did not evalutate to ``true``. - + The asserted condition did not evalutate to "true". .. function:: BoundsError([a][, i]) - An indexing operation into an array, ``a``, tried to access an out- of-bounds element, ``i``. - + An indexing operation into an array, "a", tried to access an out- + of-bounds element, "i". .. function:: DimensionMismatch([msg]) - The objects called do not have matching dimensionality. - + The objects called do not have matching dimensionality. .. function:: DivideError() - Integer division was attempted with a denominator value of 0. - + Integer division was attempted with a denominator value of 0. .. function:: DomainError() - The arguments to a function or constructor are outside the valid domain. - + The arguments to a function or constructor are outside the valid + domain. .. function:: EOFError() - No more data was available to read from a file or stream. - + No more data was available to read from a file or stream. .. function:: ErrorException(msg) - Generic error type. The error message, in the *.msg* field, may provide more specific details. - + Generic error type. The error message, in the *.msg* field, may + provide more specific details. .. function:: InexactError() - Type conversion cannot be done exactly. - + Type conversion cannot be done exactly. .. function:: InterruptException() - The process was stopped by a terminal interrupt (CTRL+C). - + The process was stopped by a terminal interrupt (CTRL+C). .. function:: KeyError(key) - An indexing operation into an ``Associative`` (``Dict``) or ``Set`` like object tried to access or delete a non-existent element. - + An indexing operation into an "Associative" ("Dict") or "Set" + like object tried to access or delete a non-existent element. .. function:: LoadError(file::AbstractString, line::Int, error) - An error occurred while *including*, *requiring*, or *using* a file. The error specifics should be available in the *.error* field. - + An error occurred while *including*, *requiring*, or *using* a + file. The error specifics should be available in the *.error* + field. .. function:: MethodError(f, args) - A method with the required type signature does not exist in the given generic function. - + A method with the required type signature does not exist in the + given generic function. .. function:: NullException() - An attempted access to a ``Nullable`` with no defined value. - + An attempted access to a "Nullable" with no defined value. .. function:: OutOfMemoryError() - An operation allocated too much memory for either the system or the garbage collector to handle properly. - + An operation allocated too much memory for either the system or the + garbage collector to handle properly. .. function:: ReadOnlyMemoryError() - An operation tried to write to memory that is read-only. - + An operation tried to write to memory that is read-only. .. function:: OverflowError() - The result of an expression is too large for the specified type and will cause a wraparound. - + The result of an expression is too large for the specified type and + will cause a wraparound. .. function:: ParseError(msg) - The expression passed to the *parse* function could not be interpreted as a valid Julia expression. - + The expression passed to the *parse* function could not be + interpreted as a valid Julia expression. .. function:: ProcessExitedException() - After a client Julia process has exited, further attempts to reference the dead child will throw this exception. - + After a client Julia process has exited, further attempts to + reference the dead child will throw this exception. .. function:: StackOverflowError() - The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. - + The function call grew beyond the size of the call stack. This + usually happens when a call recurses infinitely. .. function:: SystemError(prefix::AbstractString[, errnum::Int32]) - A system call failed with an error code (in the ``errno`` global variable). - + A system call failed with an error code (in the "errno" global + variable). .. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) - A type assertion failure, or calling an intrinsic function with an incorrect argument type. - + A type assertion failure, or calling an intrinsic function with an + incorrect argument type. .. function:: UndefRefError() - The item or field is not defined for the given object. - + The item or field is not defined for the given object. .. function:: UndefVarError(var::Symbol) - A symbol in the current scope is not defined. - + A symbol in the current scope is not defined. Events ------ .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling ``wait`` on the timer object) at a specified interval. - + Create a timer that wakes up tasks waiting for it (by calling + "wait" on the timer object) at a specified interval. .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling ``wait`` on the timer object) at a specified interval. - + Create a timer that wakes up tasks waiting for it (by calling + "wait" on the timer object) at a specified interval. Reflection ---------- .. function:: module_name(m::Module) -> Symbol - Get the name of a module as a symbol. - + Get the name of a module as a symbol. .. function:: module_parent(m::Module) -> Module - Get a module's enclosing module. ``Main`` is its own parent. - + Get a module's enclosing module. "Main" is its own parent. .. function:: current_module() -> Module - Get the *dynamically* current module, which is the module code is currently being read from. In general, this is not the same as the module containing the call to this function. - + Get the *dynamically* current module, which is the module code is + currently being read from. In general, this is not the same as the + module containing the call to this function. .. function:: fullname(m::Module) - Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and - + Get the fully-qualified name of a module as a tuple of symbols. For + example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and + "fullname(Main)" gives "()". .. function:: names(x::Module[, all=false[, imported=false]]) - Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. - + Get an array of the names exported by a module, with optionally + more module globals according to the additional parameters. .. function:: nfields(x::DataType) -> Int - Get the number of fields of a data type. - + Get the number of fields of a data type. .. function:: fieldnames(x::DataType) - Get an array of the fields of a data type. - + Get an array of the fields of a data type. .. function:: isconst([m::Module], s::Symbol) -> Bool - Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``. - + Determine whether a global is declared "const" in a given module. + The default module argument is "current_module()". .. function:: isgeneric(f::Function) -> Bool - Determine whether a function is generic. - + Determine whether a function is generic. .. function:: function_name(f::Function) -> Symbol - Get the name of a generic function as a symbol, or ``:anonymous``. - + Get the name of a generic function as a symbol, or ":anonymous". .. function:: function_module(f::Function, types) -> Module - Determine the module containing a given definition of a generic function. - + Determine the module containing a given definition of a generic + function. .. function:: functionloc(m::Method) - Returns a tuple ``(filename,line)`` giving the location of a method definition. - + Returns a tuple "(filename,line)" giving the location of a method + definition. .. function:: functionloc(m::Method) - Returns a tuple ``(filename,line)`` giving the location of a method definition. - + Returns a tuple "(filename,line)" giving the location of a method + definition. Internals --------- .. function:: gc() - Perform garbage collection. This should not generally be used. - + Perform garbage collection. This should not generally be used. .. function:: gc_enable(on::Bool) - Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Returns previous GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. - + Control whether garbage collection is enabled using a boolean + argument (true for enabled, false for disabled). Returns previous + GC state. Disabling garbage collection should be used only with + extreme caution, as it can cause memory use to grow without bound. .. function:: macroexpand(x) - Takes the expression x and returns an equivalent expression with all macros removed (expanded). - + Takes the expression x and returns an equivalent expression with + all macros removed (expanded). .. function:: expand(x) - Takes the expression x and returns an equivalent expression in lowered form - + Takes the expression x and returns an equivalent expression in + lowered form .. function:: code_lowered(f, types) - Returns an array of lowered ASTs for the methods matching the given generic function and type signature. - + Returns an array of lowered ASTs for the methods matching the given + generic function and type signature. .. function:: @code_lowered() - Evaluates the arguments to the function call, determines their types, and calls ``code_lowered()`` on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls "code_lowered()" on the resulting expression .. function:: code_typed(f, types; optimize=true) - Returns an array of lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The keyword argument ``optimize`` controls whether additional optimizations, such as inlining, are also applied. - + Returns an array of lowered and type-inferred ASTs for the methods + matching the given generic function and type signature. The keyword + argument "optimize" controls whether additional optimizations, + such as inlining, are also applied. .. function:: @code_typed() - Evaluates the arguments to the function call, determines their types, and calls ``code_typed()`` on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls "code_typed()" on the resulting expression .. function:: code_warntype(f, types) - Displays lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The ASTs are annotated in such a way as to cause ``non-leaf`` types to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability. Not all non-leaf types are particularly problematic for performance, so the results need to be used judiciously. See *@code_warntype* for more information. - + Displays lowered and type-inferred ASTs for the methods matching + the given generic function and type signature. The ASTs are + annotated in such a way as to cause "non-leaf" types to be + emphasized (if color is available, displayed in red). This serves + as a warning of potential type instability. Not all non-leaf types + are particularly problematic for performance, so the results need + to be used judiciously. See *@code_warntype* for more information. .. function:: @code_warntype() - Evaluates the arguments to the function call, determines their types, and calls ``code_warntype()`` on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls "code_warntype()" on the resulting expression .. function:: code_llvm(f, types) - Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to ``STDOUT``. All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. + Prints the LLVM bitcodes generated for running the method matching + the given generic function and type signature to "STDOUT". + All metadata and dbg.* calls are removed from the printed bitcode. + Use code_llvm_raw for the full IR. .. function:: @code_llvm() - Evaluates the arguments to the function call, determines their types, and calls ``code_llvm()`` on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls "code_llvm()" on the resulting expression .. function:: code_native(f, types) - Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. - + Prints the native assembly instructions generated for running the + method matching the given generic function and type signature to + STDOUT. .. function:: @code_native() - Evaluates the arguments to the function call, determines their types, and calls ``code_native()`` on the resulting expression - + Evaluates the arguments to the function call, determines their + types, and calls "code_native()" on the resulting expression .. function:: precompile(f, args::Tuple{Vararg{Any}}) - Compile the given function ``f`` for the argument tuple (of types) - + Compile the given function "f" for the argument tuple (of types) + "args", but do not execute it. diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index a3bc015f733fc..4807b89147822 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -6,93 +6,188 @@ .. function:: ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - Call function in C-exported shared library, specified by AbstractString or :Symbol. Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. Each ``ArgumentValue`` to the ``ccall`` will be converted to the corresponding ``ArgumentType``, by automatic insertion of calls to ArgumentValue))``. (see also the documentation for each of these functions for further details). In most cases, this simply results in a call to `convert(ArgumentType, ArgumentValue)`` - + Call function in C-exported shared library, specified by + "(function name, library)" tuple, where each component is an + AbstractString or :Symbol. + + Note that the argument type tuple must be a literal tuple, and not + a tuple-valued variable or expression. Alternatively, ccall may + also be used to call a function pointer, such as one returned by + dlsym. + + Each "ArgumentValue" to the "ccall" will be converted to the + corresponding "ArgumentType", by automatic insertion of calls to + "unsafe_convert(ArgumentType, cconvert(ArgumentType, + ArgumentValue))". (see also the documentation for each of these + functions for further details). In most cases, this simply results + in a call to "convert(ArgumentType, ArgumentValue)" .. function:: cglobal((symbol, library)[, type=Void]) - Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ``ccall``. Returns a supplied. The values can be read or written by ``unsafe_load`` or - + Obtain a pointer to a global variable in a C-exported shared + library, specified exactly as in "ccall". Returns a + "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is + supplied. The values can be read or written by "unsafe_load" or + "unsafe_store!", respectively. .. function:: cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically. For example: + Generate C-callable function pointer from Julia function. Type + annotation of the return value in the callback function is a must + for situations where Julia cannot infer the return type + automatically. + + For example: + + function foo() + # body + retval::Float64 + end + + bar = cfunction(foo, Float64, ()) .. function:: unsafe_convert(T, x) - Convert ``x`` to a value of type ``T`` In cases where ``convert`` would need to take a Julia object and turn it into a ``Ptr``, this function should be used to define and perform that conversion. Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. Accordingly, the argument ``x`` to this function should never be an expression, only a variable name or field reference. For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. The ``unsafe`` prefix on this function indicates that using the result of this function after the ``x`` argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time. + Convert "x" to a value of type "T" + + In cases where "convert" would need to take a Julia object and + turn it into a "Ptr", this function should be used to define and + perform that conversion. + Be careful to ensure that a julia reference to "x" exists as long + as the result of this function will be used. Accordingly, the + argument "x" to this function should never be an expression, only + a variable name or field reference. For example, "x=a.b.c" is + acceptable, but "x=[a,b,c]" is not. + + The "unsafe" prefix on this function indicates that using the + result of this function after the "x" argument to this function + is no longer accessible to the program may cause undefined + behavior, including program corruption or segfaults, at any later + time. .. function:: cconvert(T, x) - Convert ``x`` to a value of type ``T``, typically by calling In cases where ``x`` cannot be safely converted to ``T``, unlike from ``T``, which however is suitable for ``unsafe_convert`` to handle. Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``. + Convert "x" to a value of type "T", typically by calling + "convert(T,x)" + + In cases where "x" cannot be safely converted to "T", unlike + "convert", "cconvert" may return an object of a type different + from "T", which however is suitable for "unsafe_convert" to + handle. + Neither "convert" nor "cconvert" should take a Julia object and + turn it into a "Ptr". .. function:: unsafe_load(p::Ptr{T}, i::Integer) - Load a value of type ``T`` from the address of the ith element expression ``p[i-1]``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C. + Load a value of type "T" from the address of the ith element + (1-indexed) starting at "p". This is equivalent to the C + expression "p[i-1]". + The "unsafe" prefix on this function indicates that no validation + is performed on the pointer "p" to ensure that it is valid. + Incorrect usage may segfault your program or return garbage + answers, in the same manner as C. .. function:: unsafe_store!(p::Ptr{T}, x, i::Integer) - Store a value of type ``T`` to the address of the ith element expression ``p[i-1] = x``. The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. + Store a value of type "T" to the address of the ith element + (1-indexed) starting at "p". This is equivalent to the C + expression "p[i-1] = x". + The "unsafe" prefix on this function indicates that no validation + is performed on the pointer "p" to ensure that it is valid. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. + Copy "N" elements from a source array to a destination, starting + at offset "so" in the source and "do" in the destination + (1-indexed). + The "unsafe" prefix on this function indicates that no validation + is performed to ensure that N is inbounds on either array. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. + Copy "N" elements from a source array to a destination, starting + at offset "so" in the source and "do" in the destination + (1-indexed). + The "unsafe" prefix on this function indicates that no validation + is performed to ensure that N is inbounds on either array. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. .. function:: copy!(dest, do, src, so, N) - Copy ``N`` elements from collection ``src`` starting at offset - + Copy "N" elements from collection "src" starting at offset + "so", to array "dest" starting at offset "do". Returns + "dest". .. function:: copy!(dest, do, src, so, N) - Copy ``N`` elements from collection ``src`` starting at offset - + Copy "N" elements from collection "src" starting at offset + "so", to array "dest" starting at offset "do". Returns + "dest". .. function:: pointer(array[, index]) - Get the native address of an array or string element. Be careful to ensure that a julia reference to ``a`` exists as long as this pointer will be used. This function is ``unsafe`` like Calling ``Ref(array[, index])`` is generally preferable to this function. + Get the native address of an array or string element. Be careful to + ensure that a julia reference to "a" exists as long as this + pointer will be used. This function is "unsafe" like + "unsafe_convert". + Calling "Ref(array[, index])" is generally preferable to this + function. .. function:: pointer_to_array(pointer, dims[, take_ownership::Bool]) - Wrap a native pointer as a Julia Array object. The pointer element type determines the array element type. ``own`` optionally specifies whether Julia should take ownership of the memory, calling ``free`` on the pointer when the array is no longer referenced. - + Wrap a native pointer as a Julia Array object. The pointer element + type determines the array element type. "own" optionally + specifies whether Julia should take ownership of the memory, + calling "free" on the pointer when the array is no longer + referenced. .. function:: pointer_from_objref(object_instance) - Get the memory address of a Julia object as a ``Ptr``. The existence of the resulting ``Ptr`` will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that the ``Ptr`` will be used. - + Get the memory address of a Julia object as a "Ptr". The + existence of the resulting "Ptr" will not protect the object from + garbage collection, so you must ensure that the object remains + referenced for the whole time that the "Ptr" will be used. .. function:: unsafe_pointer_to_objref(p::Ptr) - Convert a ``Ptr`` to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined behavior results, hence this function is considered - + Convert a "Ptr" to an object reference. Assumes the pointer + refers to a valid heap-allocated Julia object. If this is not the + case, undefined behavior results, hence this function is considered + "unsafe" and should be used with care. .. function:: disable_sigint(f::Function) - Disable Ctrl-C handler during execution of a function, for calling external code that is not interrupt safe. Intended to be called using ``do`` block syntax as follows: + Disable Ctrl-C handler during execution of a function, for calling + external code that is not interrupt safe. Intended to be called + using "do" block syntax as follows: + disable_sigint() do + # interrupt-unsafe code + ... + end .. function:: reenable_sigint(f::Function) - Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of ``disable_sigint``. - + Re-enable Ctrl-C handler during execution of a function. + Temporarily reverses the effect of "disable_sigint". .. function:: systemerror(sysfunc, iftrue) - Raises a ``SystemError`` for ``errno`` with the descriptive string - + Raises a "SystemError" for "errno" with the descriptive string + "sysfunc" if "bool" is true .. data:: Ptr{T} diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index 15a9f3ac9f027..d6aa0acc55990 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -26,58 +26,71 @@ The ``state`` object may be anything, and should be chosen appropriately for eac .. function:: start(iter) -> state - Get initial iteration state for an iterable object - + Get initial iteration state for an iterable object .. function:: done(iter, state) -> Bool - Test whether we are done iterating - + Test whether we are done iterating .. function:: next(iter, state) -> item, state - For a given iterable object and iteration state, return the current item and the next iteration state - + For a given iterable object and iteration state, return the current + item and the next iteration state .. function:: zip(iters...) - For a set of iterable objects, returns an iterable of tuples, where the ``i``th tuple contains the ``i``th component of each input iterable. Note that ``zip()`` is its own inverse: + For a set of iterable objects, returns an iterable of tuples, where + the "i"th tuple contains the "i"th component of each input + iterable. + Note that "zip()" is its own inverse: + "collect(zip(zip(a...)...)) == collect(a)". .. function:: enumerate(iter) - An iterator that yields ``(i, x)`` where ``i`` is an index starting at 1, and ``x`` is the ``i``th value from the given iterator. It's useful when you need not only the values ``x`` over which you are iterating, but also the index ``i`` of the iterations. + An iterator that yields "(i, x)" where "i" is an index starting + at 1, and "x" is the "i"th value from the given iterator. It's + useful when you need not only the values "x" over which you are + iterating, but also the index "i" of the iterations. + julia> a = ["a", "b", "c"]; -.. function:: rest(iter, state) + julia> for (index, value) in enumerate(a) + println("\$index \$value") + end + 1 a + 2 b + 3 c - An iterator that yields the same elements as ``iter``, but starting at the given ``state``. +.. function:: rest(iter, state) + An iterator that yields the same elements as "iter", but starting + at the given "state". .. function:: countfrom(start=1, step=1) - An iterator that counts forever, starting at ``start`` and incrementing by ``step``. - + An iterator that counts forever, starting at "start" and + incrementing by "step". .. function:: take(iter, n) - An iterator that generates at most the first ``n`` elements of - + An iterator that generates at most the first "n" elements of + "iter". .. function:: drop(iter, n) - An iterator that generates all but the first ``n`` elements of - + An iterator that generates all but the first "n" elements of + "iter". .. function:: cycle(iter) - An iterator that cycles through ``iter`` forever. - + An iterator that cycles through "iter" forever. .. function:: repeated(x[, n::Int]) - An iterator that generates the value ``x`` forever. If ``n`` is specified, generates ``x`` that many times (equivalent to - + An iterator that generates the value "x" forever. If "n" is + specified, generates "x" that many times (equivalent to + "take(repeated(x), n)"). Fully implemented by: @@ -101,23 +114,28 @@ General Collections .. function:: isempty(collection) -> Bool - Determine whether a collection is empty (has no elements). + Determine whether a collection is empty (has no elements). + julia> isempty([]) + true -.. function:: empty!(collection) -> collection + julia> isempty([1 2 3]) + false - Remove all elements from a ``collection``. +.. function:: empty!(collection) -> collection + Remove all elements from a "collection". .. function:: length(s) - The number of characters in string ``s``. - + The number of characters in string "s". .. function:: endof(collection) -> Integer - Returns the last index of the collection. + Returns the last index of the collection. + julia> endof([1,2,4]) + 3 Fully implemented by: @@ -137,361 +155,406 @@ Iterable Collections .. function:: in(item, collection) -> Bool - Determine whether an item is in the given collection, in the sense that it is ``==`` to one of the values generated by iterating over the collection. Some collections need a slightly different definition; for example ``Set``s check whether the item To test for the presence of a key in a dictionary, use ``haskey()`` or ``k in keys(dict)``. + ∋(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)". .. 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 ``(key,value)`` tuple type. The definition that instances can be passed instead of types. However the form that accepts a type argument should be defined for new types. - + Determine the type of the elements generated by iterating a + collection of the given "type". For associative collection types, + this will be a "(key,value)" tuple type. 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. .. 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``. - + 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". .. function:: findin(a, b) - Returns the indices of elements in collection ``a`` that appear in collection ``b`` - + Returns the indices of elements in collection "a" that appear in + collection "b" .. function:: 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``. - + 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". .. function:: 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``. - + 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". .. function:: 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``. - + 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". .. function:: 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 - + 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)"). .. function:: 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 - + 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)"). .. function:: 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 - + 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)"). .. function:: 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 - + 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)"). .. function:: maximum(A, dims) - Compute the maximum value of an array over the given dimensions. - + Compute the maximum value of an array over the given dimensions. .. function:: maximum(A, dims) - Compute the maximum value of an array over the given dimensions. - + Compute the maximum value of an array over the given dimensions. .. function:: maximum!(r, A) - Compute the maximum value of ``A`` over the singleton dimensions of - + Compute the maximum value of "A" over the singleton dimensions of + "r", and write results to "r". .. function:: minimum(A, dims) - Compute the minimum value of an array over the given dimensions. - + Compute the minimum value of an array over the given dimensions. .. function:: minimum(A, dims) - Compute the minimum value of an array over the given dimensions. - + Compute the minimum value of an array over the given dimensions. .. function:: minimum!(r, A) - Compute the minimum value of ``A`` over the singleton dimensions of - + Compute the minimum value of "A" over the singleton dimensions of + "r", and write results to "r". .. function:: extrema(itr) - Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. - + Compute both the minimum and maximum element in a single pass, and + return them as a 2-tuple. .. function:: indmax(itr) -> Integer - Returns the index of the maximum element in a collection. - + Returns the index of the maximum element in a collection. .. function:: indmin(itr) -> Integer - Returns the index of the minimum element in a collection. - + Returns the index of the minimum element in a collection. .. function:: findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over the given dimensions. - + For an array input, returns the value and index of the maximum over + the given dimensions. .. function:: findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over the given dimensions. - + For an array input, returns the value and index of the maximum over + the given dimensions. .. function:: findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over the given dimensions. - + For an array input, returns the value and index of the minimum over + the given dimensions. .. function:: findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over the given dimensions. - + For an array input, returns the value and index of the minimum over + the given dimensions. .. function:: maxabs(A, dims) - Compute the maximum absolute values over given dimensions. - + Compute the maximum absolute values over given dimensions. .. function:: maxabs(A, dims) - Compute the maximum absolute values over given dimensions. - + Compute the maximum absolute values over given dimensions. .. function:: maxabs!(r, A) - Compute the maximum absolute values over the singleton dimensions of ``r``, and write values to ``r``. - + Compute the maximum absolute values over the singleton dimensions + of "r", and write values to "r". .. function:: minabs(A, dims) - Compute the minimum absolute values over given dimensions. - + Compute the minimum absolute values over given dimensions. .. function:: minabs(A, dims) - Compute the minimum absolute values over given dimensions. - + Compute the minimum absolute values over given dimensions. .. function:: minabs!(r, A) - Compute the minimum absolute values over the singleton dimensions of ``r``, and write values to ``r``. - + Compute the minimum absolute values over the singleton dimensions + of "r", and write values to "r". .. function:: sum(f, itr) - Sum the results of calling function ``f`` on each element of - + Sum the results of calling function "f" on each element of + "itr". .. function:: sum(f, itr) - Sum the results of calling function ``f`` on each element of - + Sum the results of calling function "f" on each element of + "itr". .. function:: sum!(r, A) - Sum elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + Sum elements of "A" over the singleton dimensions of "r", and + write results to "r". .. function:: sum(f, itr) - Sum the results of calling function ``f`` on each element of - + Sum the results of calling function "f" on each element of + "itr". .. function:: sumabs(A, dims) - Sum absolute values of elements of an array over the given dimensions. - + Sum absolute values of elements of an array over the given + dimensions. .. function:: sumabs(A, dims) - Sum absolute values of elements of an array over the given dimensions. - + Sum absolute values of elements of an array over the given + dimensions. .. function:: sumabs!(r, A) - Sum absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + Sum absolute values of elements of "A" over the singleton + dimensions of "r", and write results to "r". .. function:: sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given dimensions. - + Sum squared absolute values of elements of an array over the given + dimensions. .. function:: sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given dimensions. - + Sum squared absolute values of elements of an array over the given + dimensions. .. function:: sumabs2!(r, A) - Sum squared absolute values of elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + Sum squared absolute values of elements of "A" over the singleton + dimensions of "r", and write results to "r". .. function:: prod(A, dims) - Multiply elements of an array over the given dimensions. - + Multiply elements of an array over the given dimensions. .. function:: prod(A, dims) - Multiply elements of an array over the given dimensions. - + Multiply elements of an array over the given dimensions. .. function:: prod!(r, A) - Multiply elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. - + Multiply elements of "A" over the singleton dimensions of "r", + and write results to "r". .. function:: any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of - + Determine whether predicate "p" returns true for any elements of + "itr". .. function:: any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of - + Determine whether predicate "p" returns true for any elements of + "itr". .. function:: any!(r, A) - Test whether any values in ``A`` along the singleton dimensions of - + Test whether any values in "A" along the singleton dimensions of + "r" are true, and write results to "r". .. function:: all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of + Determine whether predicate "p" returns true for all elements of + "itr". + julia> all(i->(4<=i<=6), [4,5,6]) + true .. function:: all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of + Determine whether predicate "p" returns true for all elements of + "itr". + julia> all(i->(4<=i<=6), [4,5,6]) + true .. function:: all!(r, A) - Test whether all values in ``A`` along the singleton dimensions of - + Test whether all values in "A" along the singleton dimensions of + "r" are true, and write results to "r". .. function:: count(p, itr) -> Integer - Count the number of elements in ``itr`` for which predicate ``p`` returns true. - + Count the number of elements in "itr" for which predicate "p" + returns true. .. function:: any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of - + Determine whether predicate "p" returns true for any elements of + "itr". .. function:: all(p, itr) -> Bool - Determine whether predicate ``p`` returns true for all elements of + Determine whether predicate "p" returns true for all elements of + "itr". + julia> all(i->(4<=i<=6), [4,5,6]) + true .. function:: map(f, c...) -> collection - Transform collection ``c`` by applying ``f`` to each element. For multiple collection arguments, apply ``f`` elementwise. + 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 -.. function:: map!(function, destination, collection...) + julia> map(+, [1, 2, 3], [10, 20, 30]) + 3-element Array{Int64,1}: + 11 + 22 + 33 - Like ``map()``, but stores the result in ``destination`` rather than a new collection. ``destination`` must be at least as large as the first collection. +.. 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. .. 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. - + Like "map()", but stores the result in "destination" rather + than a new collection. "destination" must be at least as large as + the first collection. .. function:: mapreduce(f, op, itr) - Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). - + Like "mapreduce(f, op, v0, itr)". In general, this cannot be used + with empty collections (see "reduce(op, itr)"). .. function:: mapreduce(f, op, itr) - Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). - + Like "mapreduce(f, op, v0, itr)". In general, this cannot be used + with empty collections (see "reduce(op, itr)"). .. function:: mapfoldl(f, op, itr) - Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(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)"). .. function:: mapfoldl(f, op, itr) - Like ``mapfoldl(f, op, v0, itr)``, but using the first element of collections (see ``reduce(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)"). .. function:: mapfoldr(f, op, itr) - Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(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)"). .. function:: mapfoldr(f, op, itr) - Like ``mapfoldr(f, op, v0, itr)``, but using the first element of collections (see ``reduce(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)"). .. function:: first(coll) - Get the first element of an iterable collection. Returns the start point of a ``Range`` even if it is empty. - + Get the first element of an iterable collection. Returns the start + point of a "Range" even if it is empty. .. 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. - + 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. .. function:: step(r) - Get the step size of a ``Range`` object. - + Get the step size of a "Range" object. .. function:: collect(element_type, collection) - Return an array of type ``Array{element_type,1}`` of all items in a collection. - + Return an array of type "Array{element_type,1}" of all items in a + collection. .. function:: collect(element_type, collection) - Return an array of type ``Array{element_type,1}`` of all items in a collection. - + Return an array of type "Array{element_type,1}" of all items in a + collection. .. function:: issubset(A, S) -> Bool - True if A is a subset of or equal to S. + True if A is a subset of or equal to S. .. function:: filter(function, collection) - Return a copy of ``collection``, removing elements for which passed two arguments (key and value). - + Return a copy of "collection", removing elements for which + "function" is false. For associative collections, the function is + passed two arguments (key and value). .. 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). - + Update "collection", removing elements for which "function" is + false. For associative collections, the function is passed two + arguments (key and value). Indexable Collections --------------------- .. function:: 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, ...)``. - + 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, ...)". .. function:: 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, ...)``. - + 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, ...)". Fully implemented by: @@ -530,103 +593,167 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: Dict([itr]) - 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. Alternatively, a sequence of pair arguments may be passed. + "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. -.. function:: haskey(collection, key) -> Bool + julia> Dict([("A", 1), ("B", 2)]) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 + + Alternatively, a sequence of pair arguments may be passed. - Determine whether a collection has a mapping for a given key. + julia> Dict("A"=>1, "B"=>2) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 +.. function:: haskey(collection, key) -> Bool + + Determine whether a collection has a mapping for a given key. .. 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: + 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 .. 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: + 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 time() end .. function:: 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: + 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 .. function:: 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: + 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 time() end .. function:: getkey(collection, key, default) - Return the key matching argument ``key`` if one exists in - + Return the key matching argument "key" if one exists in + "collection", otherwise return "default". .. function:: delete!(collection, key) - Delete the mapping for the given key in a collection, and return the collection. - + Delete the mapping for the given key in a collection, and return + the collection. .. function:: pop!(collection) -> item - Remove the last item in ``collection`` and return it. + 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 -.. function:: keys(collection) + julia> pop!(A) + 6 - Return an iterator over all keys in a collection. + julia> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 +.. function:: keys(collection) -.. function:: values(collection) + Return an iterator over all keys in a collection. + "collect(keys(d))" returns an array of keys. - Return an iterator over all values in a collection. +.. function:: values(collection) + Return an iterator over all values in a collection. + "collect(values(d))" returns an array of values. .. function:: merge(collection, others...) - 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{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 - - julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "bar" => 4711 - "baz" => 17 - - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 - - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 - + 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{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 + + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 + + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 + + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 .. function:: merge!(collection, others...) - Update collection with pairs from the other collections - + Update collection with pairs from the other collections .. function:: sizehint!(s, n) - Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. - + Suggest that collection "s" reserve capacity for at least "n" + elements. This can improve performance. Fully implemented by: @@ -647,78 +774,84 @@ Set-Like Collections .. function:: 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. - + 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. .. function:: IntSet([itr]) - Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use ``Set`` instead. - + Construct a sorted set of the integers generated by the given + iterable object, or an empty set. Implemented as a bit string, and + therefore designed for dense integer sets. Only non-negative + integers can be stored. If the set will be sparse (for example + holding a single very large integer), use "Set" instead. .. function:: union(s1, s2...) - Construct the union of two or more sets. Maintains order with arrays. + Construct the union of two or more sets. Maintains order with + arrays. .. function:: union!(s, iterable) - Union each element of ``iterable`` into set ``s`` in-place. - + Union each element of "iterable" into set "s" in-place. .. function:: intersect(s1, s2...) - Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. + Construct the intersection of two or more sets. Maintains order and + multiplicity of the first argument for arrays and ranges. .. function:: setdiff(s1, s2) - Construct the set of elements in ``s1`` but not ``s2``. Maintains order with arrays. Note that both arguments must be collections, and both will be iterated over. In particular, - + Construct the set of elements in "s1" but not "s2". 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. .. function:: setdiff!(s, iterable) - Remove each element of ``iterable`` from set ``s`` in-place. - + Remove each element of "iterable" from set "s" in-place. .. function:: symdiff(s1, s2...) - Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. - + Construct the symmetric difference of elements in the passed in + sets or arrays. Maintains order with arrays. .. function:: symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - + Construct the symmetric difference of sets "s1" and "s2", + storing the result in "s1". .. function:: symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - + Construct the symmetric difference of sets "s1" and "s2", + storing the result in "s1". .. function:: symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - + Construct the symmetric difference of sets "s1" and "s2", + storing the result in "s1". .. function:: complement(s) - Returns the set-complement of ``IntSet`` ``s``. - + Returns the set-complement of "IntSet" "s". .. function:: complement!(s) - Mutates ``IntSet`` ``s`` into its set-complement. - + Mutates "IntSet" "s" into its set-complement. .. function:: intersect!(s1, s2) - Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of - + Intersects sets "s1" and "s2" and overwrites the set "s1" + with the result. If needed, "s1" will be expanded to the size of + "s2". .. function:: issubset(A, S) -> Bool - True if A is a subset of or equal to S. + True if A is a subset of or equal to S. Fully implemented by: @@ -734,63 +867,233 @@ Dequeues .. function:: push!(collection, items...) -> collection - Insert one or more ``items`` at the end of ``collection``. Use ``append!()`` to add all the elements of another collection to to ``append!([1, 2, 3], [4, 5, 6])``. + 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])". .. function:: pop!(collection) -> item - Remove the last item in ``collection`` and return it. + 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 .. function:: unshift!(collection, items...) -> collection - Insert one or more ``items`` at the beginning of ``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 .. function:: shift!(collection) -> item - Remove the first ``item`` from ``collection``. + 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 .. function:: insert!(collection, index, item) - Insert an ``item`` into ``collection`` at the given ``index``. + Insert an "item" into "collection" at the given "index". + "index" is the index of "item" in the resulting "collection". + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 .. function:: deleteat!(collection, itr) - Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. + Remove the items at the indices given by "itr", and return the + modified "collection". Subsequent items are shifted to fill the + resulting gap. "itr" must be sorted and unique. + + 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], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 .. function:: deleteat!(collection, itr) - Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. + Remove the items at the indices given by "itr", and return the + modified "collection". Subsequent items are shifted to fill the + resulting gap. "itr" must be sorted and unique. + 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], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 .. function:: splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. + Remove items in the specified index range, and return a collection + containing the removed items. Subsequent items are shifted down 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 .. function:: splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)``. + Remove items in the specified index range, and return a collection + containing the removed items. Subsequent items are shifted down 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)". -.. function:: resize!(collection, n) -> collection + julia> splice!(A, 4:3, 2) + 0-element Array{Int64,1} - Resize ``collection`` 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> A + 8-element Array{Int64,1}: + -1 + -2 + -3 + 2 + 5 + 4 + 3 + -1 +.. function:: resize!(collection, n) -> collection + + Resize "collection" 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 .. function:: append!(collection, collection2) -> collection. - Add the elements of ``collection2`` to the end of ``collection``. 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)``. + 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)". .. function:: prepend!(collection, items) -> collection - Insert the elements of ``items`` to the beginning of + Insert the elements of "items" to the beginning of + "collection". + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 Fully implemented by: @@ -809,23 +1112,24 @@ changed efficiently. .. function:: PriorityQueue(K, V[, ord]) - Construct a new ``PriorityQueue``, with keys of type ``K`` and values/priorites of type ``V``. If an order is not given, the priority queue is min-ordered using the default comparison for - + Construct a new "PriorityQueue", with keys of type "K" and + values/priorites of type "V". If an order is not given, the + priority queue is min-ordered using the default comparison for + "V". .. function:: enqueue!(pq, k, v) - Insert the a key ``k`` into a priority queue ``pq`` with priority - + Insert the a key "k" into a priority queue "pq" with priority + "v". .. function:: dequeue!(pq) - Remove and return the lowest priority key from a priority queue. - + Remove and return the lowest priority key from a priority queue. .. function:: peek(pq) - Return the lowest priority key from a priority queue without removing that key from the queue. - + Return the lowest priority key from a priority queue without + removing that key from the queue. :obj:`PriorityQueue` also behaves similarly to a :obj:`Dict` in that keys can be inserted and priorities accessed or changed using indexing notation. @@ -859,26 +1163,27 @@ is used, so that elements popped from the heap are given in ascending order. .. function:: heapify(v[, ord]) - Return a new vector in binary heap order, optionally using the given ordering. - + Return a new vector in binary heap order, optionally using the + given ordering. .. function:: heapify!(v[, ord]) - In-place ``heapify()``. - + In-place "heapify()". .. function:: isheap(v[, ord]) - Return true iff an array is heap-ordered according to the given order. - + Return true iff an array is heap-ordered according to the given + order. .. function:: heappush!(v, x[, ord]) - Given a binary heap-ordered array, push a new element ``x``, preserving the heap property. For efficiency, this function does not check that the array is indeed heap-ordered. - + Given a binary heap-ordered array, push a new element "x", + preserving the heap property. For efficiency, this function does + not check that the array is indeed heap-ordered. .. function:: heappop!(v[, ord]) - Given a binary heap-ordered array, remove and return the lowest ordered element. For efficiency, this function does not check that the array is indeed heap-ordered. - + Given a binary heap-ordered array, remove and return the lowest + ordered element. For efficiency, this function does not check that + the array is indeed heap-ordered. diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index 87f13fa81d34f..eb07661ac47f1 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -49,28 +49,43 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. .. function:: Dates.DateFormat(format::AbstractString) -> DateFormat @@ -78,226 +93,260 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a ``DateTime``, but passes a more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. - + Similar form as above for parsing a "DateTime", but passes a + "DateFormat" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a "DateFormat" object then use this + method for parsing. .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + Parse a date from a date string "dt" using a "DateFormat" + object "df". .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + Parse a date from a date string "dt" using a "DateFormat" + object "df". .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + Parse a date from a date string "dt" using a "DateFormat" + object "df". .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + Parse a date from a date string "dt" using a "DateFormat" + object "df". .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + Parse a date from a date string "dt" using a "DateFormat" + object "df". .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. - + Parse a date from a date string "dt" using a "DateFormat" + object "df". .. function:: now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as UTC/GMT. - + Returns a DateTime corresponding to the user's system time as + UTC/GMT. .. function:: now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as UTC/GMT. - + Returns a DateTime corresponding to the user's system time as + UTC/GMT. .. function:: eps(::DateTime) -> Millisecond - Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" + for "Date" values. Accessor Functions ~~~~~~~~~~~~~~~~~~ .. function:: year(dt::TimeType) -> Int64 - Return the field part of a Date or DateTime as an ``Int64``. + week(dt::TimeType) -> Int64 + day(dt::TimeType) -> Int64 + hour(dt::TimeType) -> Int64 + minute(dt::TimeType) -> Int64 + second(dt::TimeType) -> Int64 + millisecond(dt::TimeType) -> Int64 + Return the field part of a Date or DateTime as an "Int64". .. function:: Year(v) - Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. + Week(v) + Day(v) + Hour(v) + Minute(v) + Second(v) + Millisecond(v) + Construct a "Period" type with the given "v" value. Input must + be losslessly convertible to an "Int64". .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) - Simultaneously return the year and month parts of a Date or DateTime. - + Simultaneously return the year and month parts of a Date or + DateTime. .. function:: monthday(dt::TimeType) -> (Int64, Int64) - Simultaneously return the month and day parts of a Date or DateTime. - + Simultaneously return the month and day parts of a Date or + DateTime. .. function:: yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - Simultaneously return the year, month, and day parts of a Date or DateTime. - + Simultaneously return the year, month, and day parts of a Date or + DateTime. Query Functions ~~~~~~~~~~~~~~~ .. function:: dayname(dt::TimeType; locale="english") -> AbstractString - Return the full day name corresponding to the day of the week of the Date or DateTime in the given ``locale``. - + Return the full day name corresponding to the day of the week of + the Date or DateTime in the given "locale". .. function:: dayabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated name corresponding to the day of the week of the Date or DateTime in the given ``locale``. - + Return the abbreviated name corresponding to the day of the week of + the Date or DateTime in the given "locale". .. function:: dayofweek(dt::TimeType) -> Int64 - Returns the day of the week as an ``Int64`` with ``1 = Monday, 2 = Tuesday, etc.``. - + Returns the day of the week as an "Int64" with "1 = Monday, 2 = + Tuesday, etc.". .. function:: dayofweekofmonth(dt::TimeType) -> Int - For the day of week of ``dt``, returns which number it is in etc.` In the range 1:5. - + For the day of week of "dt", returns which number it is in + "dt"'s month. So if the day of the week of "dt" is Monday, then + "1 = First Monday of the month, 2 = Second Monday of the month, + etc." In the range 1:5. .. function:: daysofweekinmonth(dt::TimeType) -> Int - For the day of week of ``dt``, returns the total number of that day of the week in ``dt``'s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by including ``dayofweekofmonth(dt) == daysofweekinmonth(dt)`` in the adjuster function. - + For the day of week of "dt", returns the total number of that day + of the week in "dt"'s month. Returns 4 or 5. Useful in temporal + expressions for specifying the last day of a week in a month by + including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the + adjuster function. .. function:: monthname(dt::TimeType; locale="english") -> AbstractString - Return the full name of the month of the Date or DateTime in the given ``locale``. - + Return the full name of the month of the Date or DateTime in the + given "locale". .. function:: monthabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated month name of the Date or DateTime in the given ``locale``. - + Return the abbreviated month name of the Date or DateTime in the + given "locale". .. function:: daysinmonth(dt::TimeType) -> Int - Returns the number of days in the month of ``dt``. Value will be 28, 29, 30, or 31. - + Returns the number of days in the month of "dt". Value will be + 28, 29, 30, or 31. .. function:: isleapyear(dt::TimeType) -> Bool - Returns true if the year of ``dt`` is a leap year. - + Returns true if the year of "dt" is a leap year. .. function:: dayofyear(dt::TimeType) -> Int - Returns the day of the year for ``dt`` with January 1st being day 1. - + Returns the day of the year for "dt" with January 1st being day + 1. .. function:: daysinyear(dt::TimeType) -> Int - Returns 366 if the year of ``dt`` is a leap year, otherwise returns 365. - + Returns 366 if the year of "dt" is a leap year, otherwise returns + 365. .. function:: quarterofyear(dt::TimeType) -> Int - Returns the quarter that ``dt`` resides in. Range of value is 1:4. - + Returns the quarter that "dt" resides in. Range of value is 1:4. .. function:: dayofquarter(dt::TimeType) -> Int - Returns the day of the current quarter of ``dt``. Range of value is 1:92. - + Returns the day of the current quarter of "dt". Range of value is + 1:92. Adjuster Functions ~~~~~~~~~~~~~~~~~~ .. function:: trunc([T], x[, digits[, base]]) + "trunc(x)" returns the nearest integral value of the same type as + "x" whose absolute value is less than or equal to "x". + "trunc(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. -.. function:: firstdayofweek(dt::TimeType) -> TimeType + "digits" and "base" work as for "round()". - Adjusts ``dt`` to the Monday of its week. +.. function:: firstdayofweek(dt::TimeType) -> TimeType + Adjusts "dt" to the Monday of its week. .. function:: lastdayofweek(dt::TimeType) -> TimeType - Adjusts ``dt`` to the Sunday of its week. - + Adjusts "dt" to the Sunday of its week. .. function:: firstdayofmonth(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its month. - + Adjusts "dt" to the first day of its month. .. function:: lastdayofmonth(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its month. - + Adjusts "dt" to the last day of its month. .. function:: firstdayofyear(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its year. - + Adjusts "dt" to the first day of its year. .. function:: lastdayofyear(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its year. - + Adjusts "dt" to the last day of its year. .. function:: firstdayofquarter(dt::TimeType) -> TimeType - Adjusts ``dt`` to the first day of its quarter. - + Adjusts "dt" to the first day of its quarter. .. function:: lastdayofquarter(dt::TimeType) -> TimeType - Adjusts ``dt`` to the last day of its quarter. - + Adjusts "dt" to the last day of its quarter. .. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. .. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. .. function:: tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts ``dt`` to the first ``dow`` of its month. Alternatively, - + Adjusts "dt" to the first "dow" of its month. Alternatively, + "of=Year" will adjust to the first "dow" of the year. .. function:: tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts ``dt`` to the last ``dow`` of its month. Alternatively, - + Adjusts "dt" to the last "dow" of its month. Alternatively, + "of=Year" will adjust to the last "dow" of the year. .. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. .. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. - + Adjusts "dt" by iterating at most "limit" iterations by + "step" increments until "func" returns true. "func" must take + a single "TimeType" argument and return a "Bool". "same" + allows "dt" to be considered in satisfying "func". "negate" + will make the adjustment process terminate when "func" returns + false instead of true. .. function:: recur{T<:TimeType}(func::Function,dr::StepRange{T};negate=false,limit=10000) -> Vector{T} @@ -312,51 +361,58 @@ Periods .. function:: Year(v) - Construct a ``Period`` type with the given ``v`` value. Input must be losslessly convertible to an ``Int64``. + Week(v) + Day(v) + Hour(v) + Minute(v) + Second(v) + Millisecond(v) + Construct a "Period" type with the given "v" value. Input must + be losslessly convertible to an "Int64". .. function:: default(p::Period) -> Period - Returns a sensible ``default`` value for the input Period by returning ``one(p)`` for Year, Month, and Day, and ``zero(p)`` for Hour, Minute, Second, and Millisecond. - + Returns a sensible "default" value for the input Period by + returning "one(p)" for Year, Month, and Day, and "zero(p)" for + Hour, Minute, Second, and Millisecond. Conversion Functions ~~~~~~~~~~~~~~~~~~~~ .. function:: today() -> Date - Returns the date portion of ``now()``. - + Returns the date portion of "now()". .. function:: unix2datetime(x) -> DateTime - Takes the number of seconds since unix epoch - + Takes the number of seconds since unix epoch + "1970-01-01T00:00:00" and converts to the corresponding DateTime. .. function:: datetime2unix(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of seconds since the unix epoch as a ``Float64``. - + Takes the given DateTime and returns the number of seconds since + the unix epoch as a "Float64". .. function:: julian2datetime(julian_days) -> DateTime - Takes the number of Julian calendar days since epoch - + Takes the number of Julian calendar days since epoch + "-4713-11-24T12:00:00" and returns the corresponding DateTime. .. function:: datetime2julian(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of Julian calendar days since the julian epoch as a ``Float64``. - + Takes the given DateTime and returns the number of Julian calendar + days since the julian epoch as a "Float64". .. function:: rata2datetime(days) -> DateTime - Takes the number of Rata Die days since epoch - + Takes the number of Rata Die days since epoch + "0000-12-31T00:00:00" and returns the corresponding DateTime. .. function:: datetime2rata(dt::TimeType) -> Int64 - Returns the number of Rata Die days since epoch from the given Date or DateTime. - + Returns the number of Rata Die days since epoch from the given Date + or DateTime. Constants ~~~~~~~~~ diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index 0c41fac41bdcc..d40a4bc983dd2 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -7,286 +7,325 @@ .. function:: pwd() -> AbstractString - Get the current working directory. - + Get the current working directory. .. function:: cd(f[, dir]) - Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. - + Temporarily changes the current working directory (HOME if not + specified) and applies function f before returning. .. function:: cd(f[, dir]) - Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. - + Temporarily changes the current working directory (HOME if not + specified) and applies function f before returning. .. function:: readdir([dir]) -> Vector{ByteString} - Returns the files and directories in the directory *dir* (or the current working directory if not given). - + Returns the files and directories in the directory *dir* (or the + current working directory if not given). .. function:: mkdir(path[, mode]) - Make a new directory with name ``path`` and permissions ``mode``. mask. - + Make a new directory with name "path" and permissions "mode". + "mode" defaults to 0o777, modified by the current file creation + mask. .. function:: mkpath(path[, mode]) - Create all directories in the given ``path``, with permissions creation mask. - + Create all directories in the given "path", with permissions + "mode". "mode" defaults to 0o777, modified by the current file + creation mask. .. function:: symlink(target, link) - Creates a symbolic link to ``target`` with the name ``link``. Note: This function raises an error under operating systems that + Creates a symbolic link to "target" with the name "link". + Note: This function raises an error under operating systems that + do not support soft symbolic links, such as Windows XP. .. function:: readlink(path) -> AbstractString - Returns the value of a symbolic link ``path``. - + Returns the value of a symbolic link "path". .. function:: chmod(path, mode) - Change the permissions mode of ``path`` to ``mode``. Only integer - + Change the permissions mode of "path" to "mode". Only integer + "mode"s (e.g. 0o777) are currently supported. .. function:: stat(file) - Returns a structure whose fields contain information about the file. The fields of the structure are: - + Returns a structure whose fields contain information about the + file. The fields of the structure are: + + +-----------+------------------------------------------------------------------------+ + | size | The size (in bytes) of the file | + +-----------+------------------------------------------------------------------------+ + | device | ID of the device that contains the file | + +-----------+------------------------------------------------------------------------+ + | inode | The inode number of the file | + +-----------+------------------------------------------------------------------------+ + | mode | The protection mode of the file | + +-----------+------------------------------------------------------------------------+ + | nlink | The number of hard links to the file | + +-----------+------------------------------------------------------------------------+ + | uid | The user id of the owner of the file | + +-----------+------------------------------------------------------------------------+ + | gid | The group id of the file owner | + +-----------+------------------------------------------------------------------------+ + | rdev | If this file refers to a device, the ID of the device it refers to | + +-----------+------------------------------------------------------------------------+ + | blksize | The file-system preferred block size for the file | + +-----------+------------------------------------------------------------------------+ + | blocks | The number of such blocks allocated | + +-----------+------------------------------------------------------------------------+ + | mtime | Unix timestamp of when the file was last modified | + +-----------+------------------------------------------------------------------------+ + | ctime | Unix timestamp of when the file was created | + +-----------+------------------------------------------------------------------------+ .. function:: lstat(file) - Like stat, but for symbolic links gets the info for the link itself rather than the file it refers to. This function must be called on a file path rather than a file object or a file descriptor. - + Like stat, but for symbolic links gets the info for the link itself + rather than the file it refers to. This function must be called on + a file path rather than a file object or a file descriptor. .. function:: ctime(file) - Equivalent to stat(file).ctime - + Equivalent to stat(file).ctime .. function:: mtime(file) - Equivalent to stat(file).mtime - + Equivalent to stat(file).mtime .. function:: filemode(file) - Equivalent to stat(file).mode - + Equivalent to stat(file).mode .. function:: filesize(path...) - Equivalent to stat(file).size - + Equivalent to stat(file).size .. function:: uperm(file) - Gets the permissions of the owner of the file as a bitfield of For allowed arguments, see ``stat``. + Gets the permissions of the owner of the file as a bitfield of + +------+-----------------------+ + | 01 | Execute Permission | + +------+-----------------------+ + | 02 | Write Permission | + +------+-----------------------+ + | 04 | Read Permission | + +------+-----------------------+ -.. function:: gperm(file) + For allowed arguments, see "stat". - Like uperm but gets the permissions of the group owning the file +.. function:: gperm(file) + Like uperm but gets the permissions of the group owning the file .. function:: operm(file) - Like uperm but gets the permissions for people who neither own the file nor are a member of the group owning the file - + Like uperm but gets the permissions for people who neither own the + file nor are a member of the group owning the file .. function:: cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - Copy the file, link, or directory from *src* to *dest*. If *follow_symlinks=false*, and src is a symbolic link, dst will be created as a symbolic link. If *follow_symlinks=true* and src is a symbolic link, dst will be a copy of the file or directory *src* refers to. + Copy the file, link, or directory from *src* to *dest*. + "remove_destination=true" will first remove an existing *dst*. + If *follow_symlinks=false*, and src is a symbolic link, dst will be + created as a symbolic link. If *follow_symlinks=true* and src is a + symbolic link, dst will be a copy of the file or directory *src* + refers to. .. function:: download(url[, localfile]) - Download a file from the given url, optionally renaming it to the given local file name. Note that this function relies on the availability of external tools such as ``curl``, ``wget`` or production use or situations in which more options are need, please use a package that provides the desired functionality instead. - + Download a file from the given url, optionally renaming it to the + given local file name. Note that this function relies on the + availability of external tools such as "curl", "wget" or + "fetch" to download the file and is provided for convenience. For + production use or situations in which more options are need, please + use a package that provides the desired functionality instead. .. function:: mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - Move the file, link, or directory from *src* to *dest*. ``remove_destination=true`` will first remove an existing *dst*. - + Move the file, link, or directory from *src* to *dest*. + "remove_destination=true" will first remove an existing *dst*. .. function:: rm(path::AbstractString; recursive=false) - Delete the file, link, or empty directory at the given path. If contents are removed recursively. - + Delete the file, link, or empty directory at the given path. If + "recursive=true" is passed and the path is a directory, then all + contents are removed recursively. .. function:: touch(path::AbstractString) - Update the last-modified timestamp on a file to the current time. - + Update the last-modified timestamp on a file to the current time. .. function:: tempname() - Generate a unique temporary file path. - + Generate a unique temporary file path. .. function:: tempdir() - Obtain the path of a temporary directory (possibly shared with other processes). - + Obtain the path of a temporary directory (possibly shared with + other processes). .. function:: mktemp([parent=tempdir()]) - Returns ``(path, io)``, where ``path`` is the path of a new temporary file in ``parent`` and ``io`` is an open file object for this path. - + Returns "(path, io)", where "path" is the path of a new + temporary file in "parent" and "io" is an open file object for + this path. .. function:: mktempdir([parent=tempdir()]) - Create a temporary directory in the ``parent`` directory and return its path. - + Create a temporary directory in the "parent" directory and return + its path. .. function:: isblockdev(path) -> Bool - Returns ``true`` if ``path`` is a block device, ``false`` otherwise. - + Returns "true" if "path" is a block device, "false" + otherwise. .. function:: ischardev(path) -> Bool - Returns ``true`` if ``path`` is a character device, ``false`` otherwise. - + Returns "true" if "path" is a character device, "false" + otherwise. .. function:: isdir(path) -> Bool - Returns ``true`` if ``path`` is a directory, ``false`` otherwise. - + Returns "true" if "path" is a directory, "false" otherwise. .. function:: isexecutable(path) -> Bool - Returns ``true`` if the current user has permission to execute - + Returns "true" if the current user has permission to execute + "path", "false" otherwise. .. function:: isfifo(path) -> Bool - Returns ``true`` if ``path`` is a FIFO, ``false`` otherwise. - + Returns "true" if "path" is a FIFO, "false" otherwise. .. function:: isfile(path) -> Bool - Returns ``true`` if ``path`` is a regular file, ``false`` otherwise. - + Returns "true" if "path" is a regular file, "false" + otherwise. .. function:: islink(path) -> Bool - Returns ``true`` if ``path`` is a symbolic link, ``false`` otherwise. - + Returns "true" if "path" is a symbolic link, "false" + otherwise. .. function:: ismount(path) -> Bool - Returns ``true`` if ``path`` is a mount point, ``false`` otherwise. - + Returns "true" if "path" is a mount point, "false" otherwise. .. function:: ispath(path) -> Bool - Returns ``true`` if ``path`` is a valid filesystem path, ``false`` otherwise. - + Returns "true" if "path" is a valid filesystem path, "false" + otherwise. .. function:: isreadable(path) -> Bool - Returns ``true`` if the current user has permission to read - + Returns "true" if the current user has permission to read + "path", "false" otherwise. .. function:: issetgid(path) -> Bool - Returns ``true`` if ``path`` has the setgid flag set, ``false`` otherwise. - + Returns "true" if "path" has the setgid flag set, "false" + otherwise. .. function:: issetuid(path) -> Bool - Returns ``true`` if ``path`` has the setuid flag set, ``false`` otherwise. - + Returns "true" if "path" has the setuid flag set, "false" + otherwise. .. function:: issocket(path) -> Bool - Returns ``true`` if ``path`` is a socket, ``false`` otherwise. - + Returns "true" if "path" is a socket, "false" otherwise. .. function:: issticky(path) -> Bool - Returns ``true`` if ``path`` has the sticky bit set, ``false`` otherwise. - + Returns "true" if "path" has the sticky bit set, "false" + otherwise. .. function:: iswritable(path) -> Bool - Returns ``true`` if the current user has permission to write to - + Returns "true" if the current user has permission to write to + "path", "false" otherwise. .. function:: homedir() -> AbstractString - Return the current user's home directory. - + Return the current user's home directory. .. function:: dirname(path::AbstractString) -> AbstractString - Get the directory part of a path. - + Get the directory part of a path. .. function:: basename(path::AbstractString) -> AbstractString - Get the file name part of a path. - + Get the file name part of a path. .. function:: @__FILE__() -> AbstractString - name of the script being run. Returns ``nothing`` if run from a REPL or an empty string if evaluated by ``julia -e ``. - + "@__FILE__" expands to a string with the absolute path and file + name of the script being run. Returns "nothing" if run from a + REPL or an empty string if evaluated by "julia -e ". .. function:: isabspath(path::AbstractString) -> Bool - Determines whether a path is absolute (begins at the root directory). - + Determines whether a path is absolute (begins at the root + directory). .. function:: isdirpath(path::AbstractString) -> Bool - Determines whether a path refers to a directory (for example, ends with a path separator). - + Determines whether a path refers to a directory (for example, ends + with a path separator). .. function:: joinpath(parts...) -> AbstractString - Join path components into a full path. If some argument is an absolute path, then prior components are dropped. - + Join path components into a full path. If some argument is an + absolute path, then prior components are dropped. .. function:: abspath(path::AbstractString) -> AbstractString - Convert a path to an absolute path by adding the current directory if necessary. - + Convert a path to an absolute path by adding the current directory + if necessary. .. function:: normpath(path::AbstractString) -> AbstractString - Normalize a path, removing ``.`` and ``..`` entries. - + Normalize a path, removing "." and ".." entries. .. function:: realpath(path::AbstractString) -> AbstractString - Canonicalize a path by expanding symbolic links and removing ``.`` and ``..`` entries. - + Canonicalize a path by expanding symbolic links and removing "." + and ".." entries. .. function:: relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - Return a relative filepath to path either from the current directory or from an optional start directory. This is a path computation: the filesystem is not accessed to confirm the existence or nature of path or startpath. - + Return a relative filepath to path either from the current + directory or from an optional start directory. This is a path + computation: the filesystem is not accessed to confirm the + existence or nature of path or startpath. .. function:: expanduser(path::AbstractString) -> AbstractString - On Unix systems, replace a tilde character at the start of a path with the current user's home directory. - + On Unix systems, replace a tilde character at the start of a path + with the current user's home directory. .. function:: splitdir(path::AbstractString) -> (AbstractString, AbstractString) - Split a path into a tuple of the directory name and file name. - + Split a path into a tuple of the directory name and file name. .. function:: splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - On Windows, split a path into the drive letter part and the path part. On Unix systems, the first component is always the empty string. - + On Windows, split a path into the drive letter part and the path + part. On Unix systems, the first component is always the empty + string. .. function:: splitext(path::AbstractString) -> (AbstractString, AbstractString) - If the last component of a path contains a dot, split the path into everything before the dot and everything including and after the dot. Otherwise, return a tuple of the argument unmodified and the empty string. - + If the last component of a path contains a dot, split the path into + everything before the dot and everything including and after the + dot. Otherwise, return a tuple of the argument unmodified and the + empty string. diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 25dbbbccc98dd..45b96f1392472 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -21,416 +21,495 @@ General I/O .. function:: open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. + **Example**: "open(readall, "file.txt")" .. function:: open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. + **Example**: "open(readall, "file.txt")" .. function:: open(f::function, args...) - Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and + close the resulting file descriptor upon completion. + **Example**: "open(readall, "file.txt")" .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. - + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. .. function:: takebuf_array(b::IOBuffer) - Obtain the contents of an ``IOBuffer`` as an array, without copying. Afterwards, the IOBuffer is reset to its initial state. - + Obtain the contents of an "IOBuffer" as an array, without + copying. Afterwards, the IOBuffer is reset to its initial state. .. function:: takebuf_string(b::IOBuffer) - Obtain the contents of an ``IOBuffer`` as a string, without copying. Afterwards, the IOBuffer is reset to its initial state. - + Obtain the contents of an "IOBuffer" as a string, without + copying. Afterwards, the IOBuffer is reset to its initial state. .. function:: fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - Create an ``IOStream`` object from an integer file descriptor. If descriptor. By default, an ``IOStream`` is closed when it is garbage collected. ``name`` allows you to associate the descriptor with a named file. - + Create an "IOStream" object from an integer file descriptor. If + "own" is true, closing this object will close the underlying + descriptor. By default, an "IOStream" is closed when it is + garbage collected. "name" allows you to associate the descriptor + with a named file. .. function:: flush(stream) - Commit all currently buffered writes to the given stream. - + Commit all currently buffered writes to the given stream. .. function:: close(stream) - Close an I/O stream. Performs a ``flush`` first. - + Close an I/O stream. Performs a "flush" first. .. function:: write(stream, x) - Write the canonical binary representation of a value to the given stream. - + Write the canonical binary representation of a value to the given + stream. .. function:: read(stream, type, dims) - Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. - + Read a series of values of the given type from a stream, in + canonical binary representation. "dims" is either a tuple or a + series of integer arguments specifying the size of "Array" to + return. .. function:: read(stream, type, dims) - Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. - + Read a series of values of the given type from a stream, in + canonical binary representation. "dims" is either a tuple or a + series of integer arguments specifying the size of "Array" to + return. .. function:: read!(stream, array::Array) - Read binary data from a stream, filling in the argument ``array``. - + Read binary data from a stream, filling in the argument "array". .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - Read at most ``nb`` bytes from the stream into ``b``, returning the number of bytes read (increasing the size of ``b`` as needed). - + Read at most "nb" bytes from the stream into "b", returning the + number of bytes read (increasing the size of "b" as needed). .. function:: readbytes(stream, nb=typemax(Int)) - Read at most ``nb`` bytes from the stream, returning a - + Read at most "nb" bytes from the stream, returning a + "Vector{UInt8}" of the bytes read. .. function:: position(s) - Get the current position of a stream. - + Get the current position of a stream. .. function:: seek(s, pos) - Seek a stream to the given position. - + Seek a stream to the given position. .. function:: seekstart(s) - Seek a stream to its beginning. - + Seek a stream to its beginning. .. function:: seekend(s) - Seek a stream to its end. - + Seek a stream to its end. .. function:: skip(s, offset) - Seek a stream relative to the current position. - + Seek a stream relative to the current position. .. function:: mark(s) - Add a mark at the current position of stream ``s``. Returns the marked position. See also ``unmark()``, ``reset()``, ``ismarked()`` + Add a mark at the current position of stream "s". Returns the + marked position. + See also "unmark()", "reset()", "ismarked()" .. function:: unmark(s) - Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. See also ``mark()``, ``reset()``, ``ismarked()`` + Remove a mark from stream "s". Returns "true" if the stream was + marked, "false" otherwise. + See also "mark()", "reset()", "ismarked()" .. function:: reset(s) - Reset a stream ``s`` to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked. See also ``mark()``, ``unmark()``, ``ismarked()`` + Reset a stream "s" to a previously marked position, and remove + the mark. Returns the previously marked position. Throws an error + if the stream is not marked. + See also "mark()", "unmark()", "ismarked()" .. function:: ismarked(s) - Returns true if stream ``s`` is marked. See also ``mark()``, ``unmark()``, ``reset()`` + Returns true if stream "s" is marked. + See also "mark()", "unmark()", "reset()" .. function:: eof(stream) -> Bool - Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return ``false``. Therefore it is always safe to read one byte after seeing ``eof`` return ``false``. ``eof`` will return ``false`` as long as buffered data is still available, even if the remote end of a connection is closed. - + Tests whether an I/O stream is at end-of-file. If the stream is not + yet exhausted, this function will block to wait for more data if + necessary, and then return "false". Therefore it is always safe + to read one byte after seeing "eof" return "false". "eof" + will return "false" as long as buffered data is still available, + even if the remote end of a connection is closed. .. function:: isreadonly(stream) -> Bool - Determine whether a stream is read-only. - + Determine whether a stream is read-only. .. function:: isopen(stream) -> Bool - Determine whether a stream is open (i.e. has not been closed yet). If the connection has been closed remotely (in case of e.g. a socket), ``isopen`` will return ``false`` even though buffered data may still be available. Use ``eof`` to check if necessary. - + Determine whether a stream is open (i.e. has not been closed yet). + If the connection has been closed remotely (in case of e.g. a + socket), "isopen" will return "false" even though buffered data + may still be available. Use "eof" to check if necessary. .. function:: serialize(stream, value) - Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``. The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. - + Write an arbitrary value to a stream in an opaque format, such that + it can be read back by "deserialize". The read-back value will be + as identical as possible to the original. In general, this process + will not work if the reading and writing are done by different + versions of Julia, or an instance of Julia with a different system + image. .. function:: deserialize(stream) - Read a value written by ``serialize``. - + Read a value written by "serialize". .. function:: print_escaped(io, str::AbstractString, esc::AbstractString) - General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). - + General escaping of traditional C and Unicode escape sequences, + plus any characters in esc are also escaped (with a backslash). .. function:: print_unescaped(io, s::AbstractString) - General unescaping of traditional C and Unicode escape sequences. Reverse of ``print_escaped()``. - + General unescaping of traditional C and Unicode escape sequences. + Reverse of "print_escaped()". .. function:: print_joined(io, items, delim[, last]) - Print elements of ``items`` to ``io`` with ``delim`` between them. If ``last`` is specified, it is used as the final delimiter instead of ``delim``. - + Print elements of "items" to "io" with "delim" between them. + If "last" is specified, it is used as the final delimiter instead + of "delim". .. function:: print_shortest(io, x) - Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number ``x``, ensuring that it would parse to the exact same number. - + Print the shortest possible representation, with the minimum number + of consecutive non-zero digits, of number "x", ensuring that it + would parse to the exact same number. .. function:: fd(stream) - Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. - + Returns the file descriptor backing the stream or file. Note that + this function only applies to synchronous *File*'s and *IOStream*'s + not to any of the asynchronous streams. .. function:: redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - + Replace STDOUT by stream for all C and julia level output to + STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. .. function:: redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - + Replace STDOUT by stream for all C and julia level output to + STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. .. function:: redirect_stderr([stream]) - Like redirect_stdout, but for STDERR - + Like redirect_stdout, but for STDERR .. function:: redirect_stdin([stream]) - Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read from STDIN, may be written to wr. - + Like redirect_stdout, but for STDIN. Note that the order of the + return tuple is still (rd,wr), i.e. data to be read from STDIN, may + be written to wr. .. function:: readchomp(x) - Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). - + Read the entirety of x as a string but remove trailing newlines. + Equivalent to chomp(readall(x)). .. function:: truncate(file, n) - Resize the file or buffer given by the first argument to exactly file or buffer is grown - + Resize the file or buffer given by the first argument to exactly + *n* bytes, filling previously unallocated space with '\0' if the + file or buffer is grown .. function:: skipchars(stream, predicate; linecomment::Char) - Advance the stream until before the first character for which isspace)` will skip all whitespace. If keyword argument through the end of a line will also be skipped. - + Advance the stream until before the first character for which + "predicate" returns false. For example "skipchars(stream, + isspace)" will skip all whitespace. If keyword argument + "linecomment" is specified, characters from that character + through the end of a line will also be skipped. .. function:: countlines(io[, eol::Char]) - Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first argument. EOL markers other than '\n' are supported by passing them as the second argument. - + Read io until the end of the stream/file and count the number of + non-empty lines. To specify a file pass the filename as the first + argument. EOL markers other than '\n' are supported by passing + them as the second argument. .. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. - + Create a PipeBuffer to operate on a data vector, optionally + specifying a size beyond which the underlying Array may not be + grown. .. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. - + Create a PipeBuffer to operate on a data vector, optionally + specifying a size beyond which the underlying Array may not be + grown. .. function:: readavailable(stream) - Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``. - + Read all available data on the stream, blocking the task only if no + data is available. The result is a "Vector{UInt8,1}". Text I/O -------- .. function:: show(x) - Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. The representation used by ``show`` generally includes Julia-specific formatting and type information. - + Write an informative text representation of a value to the current + output stream. New types should overload "show(io, x)" where the + first argument is a stream. The representation used by "show" + generally includes Julia-specific formatting and type information. .. function:: showcompact(x) - Show a more compact representation of a value. This is used for printing array elements. If a new type has a different compact representation, it should overload ``showcompact(io, x)`` where the first argument is a stream. - + Show a more compact representation of a value. This is used for + printing array elements. If a new type has a different compact + representation, it should overload "showcompact(io, x)" where the + first argument is a stream. .. function:: showall(x) - Similar to ``show``, except shows all elements of arrays. - + Similar to "show", except shows all elements of arrays. .. function:: summary(x) - Return a string giving a brief description of a value. By default returns ``string(typeof(x))``. For arrays, returns strings like - + Return a string giving a brief description of a value. By default + returns "string(typeof(x))". For arrays, returns strings like + "2x2 Float64 Array". .. function:: print(x) - Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call formatting and tries to avoid Julia-specific details. - + Write (to the default output stream) a canonical (un-decorated) + text representation of a value if there is one, otherwise call + "show". The representation used by "print" includes minimal + formatting and tries to avoid Julia-specific details. .. function:: println(x) - Print (using ``print()``) ``x`` followed by a newline. - + Print (using "print()") "x" followed by a newline. .. function:: print_with_color(color::Symbol[, io], strings...) - Print strings in a color specified as a symbol, for example - + Print strings in a color specified as a symbol, for example + ":red" or ":blue". .. function:: info(msg) - Display an informational message. - + Display an informational message. .. function:: warn(msg) - Display a warning. - + Display a warning. .. function:: @printf([io::IOStream], "%Fmt", args...) - Print arg(s) using C ``printf()`` style format specification string. Optionally, an IOStream may be passed as the first argument to redirect output. - + Print arg(s) using C "printf()" style format specification + string. Optionally, an IOStream may be passed as the first argument + to redirect output. .. function:: @sprintf("%Fmt", args...) - Return ``@printf`` formatted output as string. - + Return "@printf" formatted output as string. .. function:: sprint(f::Function, args...) - Call the given function with an I/O stream and the supplied extra arguments. Everything written to this I/O stream is returned as a string. - + Call the given function with an I/O stream and the supplied extra + arguments. Everything written to this I/O stream is returned as a + string. .. function:: showerror(io, e) - Show a descriptive representation of an exception object. - + Show a descriptive representation of an exception object. .. function:: dump(x) - Show all user-visible structure of a value. - + Show all user-visible structure of a value. .. function:: xdump(x) - Show all structure of a value, including all fields of objects. - + Show all structure of a value, including all fields of objects. .. function:: readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. - + Open "filename", read the entire contents as a string, then close + the file. Equivalent to "open(readall, filename)". .. function:: readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. - + Open "filename", read the entire contents as a string, then close + the file. Equivalent to "open(readall, filename)". .. function:: readline(stream=STDIN) - Read a single line of text, including a trailing newline character - + Read a single line of text, including a trailing newline character + (if one is reached before the end of the input), from the given + "stream" (defaults to "STDIN"), .. function:: readuntil(stream, delim) - Read a string, up to and including the given delimiter byte. - + Read a string, up to and including the given delimiter byte. .. function:: readlines(stream) - Read all lines as an array. - + Read all lines as an array. .. function:: eachline(stream) - Create an iterable object that will yield each line from a stream. - + Create an iterable object that will yield each line from a stream. .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as "\n". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. .. function:: writedlm(f, A, delim='\t') - Write ``A`` (a vector, matrix or an iterable collection of iterable rows) as text to ``f`` (either a filename string or an ``IO`` stream) using the given delimeter ``delim`` (which defaults to tab, but can be any printable Julia object, typically a ``Char`` or For example, two vectors ``x`` and ``y`` of the same length can be written as two columns of tab-delimited text to ``f`` by either + Write "A" (a vector, matrix or an iterable collection of iterable + rows) as text to "f" (either a filename string or an "IO" + stream) using the given delimeter "delim" (which defaults to tab, + but can be any printable Julia object, typically a "Char" or + "AbstractString"). + For example, two vectors "x" and "y" of the same length can be + written as two columns of tab-delimited text to "f" by either + "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". .. function:: readcsv(source, [T::Type]; options...) - Equivalent to ``readdlm`` with ``delim`` set to comma. - + Equivalent to "readdlm" with "delim" set to comma. .. function:: writecsv(filename, A) - Equivalent to ``writedlm`` with ``delim`` set to comma. - + Equivalent to "writedlm" with "delim" set to comma. .. function:: Base64EncodePipe(ostream) - Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to necessary to complete the encoding (but does not close - + Returns a new write-only I/O stream, which converts any bytes + written to it into base64-encoded ASCII bytes written to + "ostream". Calling "close" on the "Base64Pipe" stream is + necessary to complete the encoding (but does not close + "ostream"). .. function:: Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded data read from ``istream``. - + Returns a new read-only I/O stream, which decodes base64-encoded + data read from "istream". .. function:: base64encode(writefunc, args...) - Given a ``write``-like function ``writefunc``, which takes an I/O stream as its first argument, ``base64(writefunc, args...)`` calls returns the string. ``base64(args...)`` is equivalent to using the standard ``write`` functions and returns the base64-encoded string. + Given a "write"-like function "writefunc", which takes an I/O + stream as its first argument, "base64(writefunc, args...)" calls + "writefunc" to write "args..." to a base64-encoded string, and + returns the string. "base64(args...)" is equivalent to + "base64(write, args...)": it converts its arguments into bytes + using the standard "write" functions and returns the + base64-encoded string. .. function:: base64decode(string) - Decodes the base64-encoded ``string`` and returns a ``Vector{UInt8}`` of the decoded bytes. - + Decodes the base64-encoded "string" and returns a + "Vector{UInt8}" of the decoded bytes. Multimedia I/O -------------- @@ -455,38 +534,101 @@ Julia environments (such as the IPython-based IJulia notebook). .. function:: display(x) - Display ``x`` using the topmost applicable display in the display stack, typically using the richest supported multimedia output for display ``d`` only, throwing a ``MethodError`` if ``d`` cannot display objects of this type. There are also two variants with a ``mime`` argument (a MIME type string, such as ``image/png``), which attempt to display ``x`` using the requested MIME type *only*, throwing a ``MethodError`` if this type is not supported by either the display(s) or by ``x``. With these variants, one can also supply the ``raw`` data in the requested MIME type by passing ``x::AbstractString`` (for MIME types with text-based storage, such as text/html or application/postscript) or ``x::Vector{UInt8}`` (for binary MIME types). - + display(mime, x) + display(d::Display, mime, x) + + Display "x" using the topmost applicable display in the display + stack, typically using the richest supported multimedia output for + "x", with plain-text "STDOUT" output as a fallback. The + "display(d, x)" variant attempts to display "x" on the given + display "d" only, throwing a "MethodError" if "d" cannot + display objects of this type. + + There are also two variants with a "mime" argument (a MIME type + string, such as ""image/png""), which attempt to display "x" + using the requested MIME type *only*, throwing a "MethodError" if + this type is not supported by either the display(s) or by "x". + With these variants, one can also supply the "raw" data in the + requested MIME type by passing "x::AbstractString" (for MIME + types with text-based storage, such as text/html or + application/postscript) or "x::Vector{UInt8}" (for binary MIME + types). .. function:: redisplay(x) - By default, the ``redisplay`` functions simply call ``display``. However, some display backends may override ``redisplay`` to modify an existing display of ``x`` (if any). Using ``redisplay`` is also a hint to the backend that ``x`` may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt. + redisplay(mime, x) + redisplay(d::Display, mime, x) + By default, the "redisplay" functions simply call "display". + However, some display backends may override "redisplay" to modify + an existing display of "x" (if any). Using "redisplay" is + also a hint to the backend that "x" may be redisplayed several + times, and the backend may choose to defer the display until (for + example) the next interactive prompt. .. function:: displayable(mime) -> Bool - Returns a boolean value indicating whether the given ``mime`` type display stack, or specifically by the display ``d`` in the second variant. + Returns a boolean value indicating whether the given "mime" type + (string) is displayable by any of the displays in the current + display stack, or specifically by the display "d" in the second + variant. .. function:: writemime(stream, mime, x) - The ``display`` functions ultimately call ``writemime`` in order to write an object ``x`` as a given ``mime`` type to a given I/O provide a rich multimedia representation of a user-defined type for ``T``, via: ``writemime(stream, ::MIME"mime", x::T) = ...``, where ``mime`` is a MIME-type string and the function body calls literal strings; to construct ``MIME`` types in a more flexible manner use ``MIME{symbol("")}``.) For example, if you define a ``MyImage`` type and know how to write it to a PNG file, you could define a function ``writemime(stream, be displayed on any PNG-capable `Display`` (such as IJulia). As usual, be sure to ``import Base.writemime`` in order to add new methods to the built-in Julia function ``writemime``. Technically, the ``MIME"mime"`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. - + The "display" functions ultimately call "writemime" in order to + write an object "x" as a given "mime" type to a given I/O + "stream" (usually a memory buffer), if possible. In order to + provide a rich multimedia representation of a user-defined type + "T", it is only necessary to define a new "writemime" method + for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", + where "mime" is a MIME-type string and the function body calls + "write" (or similar) to write that representation of "x" to + "stream". (Note that the "MIME""" notation only supports + literal strings; to construct "MIME" types in a more flexible + manner use "MIME{symbol("")}".) + + For example, if you define a "MyImage" type and know how to write + it to a PNG file, you could define a function "writemime(stream, + ::MIME"image/png", x::MyImage) = ...`" to allow your images to + be displayed on any PNG-capable "Display" (such as IJulia). As + usual, be sure to "import Base.writemime" in order to add new + methods to the built-in Julia function "writemime". + + Technically, the "MIME"mime"" macro defines a singleton type + for the given "mime" string, which allows us to exploit Julia's + dispatch mechanisms in determining how to display objects of any + given type. .. function:: mimewritable(mime, x) - Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding - + Returns a boolean value indicating whether or not the object "x" + can be written as the given "mime" type. (By default, this is + determined automatically by the existence of the corresponding + "writemime" function for "typeof(x)".) .. function:: reprmime(mime, x) - Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the representation of ``x`` in the requested ``mime`` type, as written by ``writemime`` (throwing a ``MethodError`` if no appropriate MIME types with textual representations (such as ``text/html`` or ``application/postscript``), whereas binary data is returned as ``Vector{UInt8}``. (The function ``istext(mime)`` returns whether or not Julia treats a given ``mime`` type as text.) As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) or a ``Vector{UInt8}`` (for binary MIME types), the requested ``mime`` format and simply returns ``x``. + Returns an "AbstractString" or "Vector{UInt8}" containing the + representation of "x" in the requested "mime" type, as written + by "writemime" (throwing a "MethodError" if no appropriate + "writemime" is available). An "AbstractString" is returned for + MIME types with textual representations (such as ""text/html"" + or ""application/postscript""), whereas binary data is returned + as "Vector{UInt8}". (The function "istext(mime)" returns + whether or not Julia treats a given "mime" type as text.) + As a special case, if "x" is an "AbstractString" (for textual + MIME types) or a "Vector{UInt8}" (for binary MIME types), the + "reprmime" function assumes that "x" is already in the + requested "mime" format and simply returns "x". .. function:: stringmime(mime, x) - Returns an ``AbstractString`` containing the representation of string. - + Returns an "AbstractString" containing the representation of + "x" in the requested "mime" type. This is similar to + "reprmime" except that binary data is base64-encoded as an ASCII + string. As mentioned above, one can also define new display backends. For example, a module that can display PNG images in a window can register @@ -516,159 +658,249 @@ stack with: .. function:: pushdisplay(d::Display) - Pushes a new display ``d`` on top of the global display-backend stack. Calling ``display(x)`` or ``display(mime, x)`` will display topmost backend that does not throw a ``MethodError``). - + Pushes a new display "d" on top of the global display-backend + stack. Calling "display(x)" or "display(mime, x)" will display + "x" on the topmost compatible backend in the stack (i.e., the + topmost backend that does not throw a "MethodError"). .. function:: popdisplay() - Pop the topmost backend off of the display-backend stack, or the topmost copy of ``d`` in the second variant. + Pop the topmost backend off of the display-backend stack, or the + topmost copy of "d" in the second variant. .. function:: TextDisplay(stream) - Returns a ``TextDisplay <: Display``, which can display any object as the text/plain MIME type (only), writing the text representation to the given I/O stream. (The text representation is the same as the way an object is printed in the Julia REPL.) - + Returns a "TextDisplay <: Display", which can display any object + as the text/plain MIME type (only), writing the text representation + to the given I/O stream. (The text representation is the same as + the way an object is printed in the Julia REPL.) .. function:: istext(m::MIME) - Determine whether a MIME type is text data. - + Determine whether a MIME type is text data. Memory-mapped I/O ----------------- .. function:: mmap_array(type, dims, stream[, offset]) - Create an ``Array`` whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory. The type determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). The file is passed via the stream argument. When you initialize the stream, use ``r`` for a ``read-only`` array, and ``w+`` to create a new array used to write values to disk. Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position. For example, the following code: creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. A more portable file would need to encode the word size–-32 bit or 64 bit–-and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 + Create an "Array" whose values are linked to a file, using + memory-mapping. This provides a convenient way of working with data + too large to fit in the computer's memory. + + The type determines how the bytes of the array are interpreted. + Note that the file must be stored in binary format, and no format + conversions are possible (this is a limitation of operating + systems, not Julia). + + "dims" is a tuple specifying the size of the array. + + The file is passed via the stream argument. When you initialize + the stream, use ""r"" for a "read-only" array, and ""w+"" + to create a new array used to write values to disk. + + Optionally, you can specify an offset (in bytes) if, for example, + you want to skip over a header in the file. The default value for + the offset is the current stream position. + For example, the following code: + + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) + + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) + + creates a "m"-by-"n" "Matrix{Int}", linked to the file + associated with stream "s". + + A more portable file would need to encode the word size---32 bit or + 64 bit---and endianness information in the header. In practice, + consider encoding binary data using standard formats like HDF5 + (which can be used with memory-mapping). .. function:: mmap_bitarray([type], dims, stream[, offset]) - Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as ``mmap_array()``, but the byte representation is different. The ``type`` parameter is optional, and must be ``Bool`` if given. This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. + Create a "BitArray" whose values are linked to a file, using + memory-mapping; it has the same purpose, works in the same way, and + has the same arguments, as "mmap_array()", but the byte + representation is different. The "type" parameter is optional, + and must be "Bool" if given. + **Example**: "B = mmap_bitarray((25,30000), s)" + + This would create a 25-by-30000 "BitArray", linked to the file + associated with stream "s". .. function:: msync(ptr, len[, flags]) - Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + Forces synchronization of the "mmap()"ped memory region from + "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a + combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See + your platform man page for specifics. The flags argument is not + valid on Windows. + You may not need to call "msync", because synchronization is + performed at intervals automatically by the operating system. + However, you can call this directly if, for example, you are + concerned about losing the result of a long-running calculation. Network I/O ----------- .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. - + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id "pid", specified + by "config" and return a pair of "AsyncStream" objects. + Messages from "pid" to current process will be read off + "instrm", while messages to be sent to "pid" will be written to + "outstrm". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + "Base.connect(manager::ClusterManager.....)" sets up TCP/IP + socket connections in-between workers. .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. - + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id "pid", specified + by "config" and return a pair of "AsyncStream" objects. + Messages from "pid" to current process will be read off + "instrm", while messages to be sent to "pid" will be written to + "outstrm". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + "Base.connect(manager::ClusterManager.....)" sets up TCP/IP + socket connections in-between workers. .. function:: listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket - + Listens on/Creates a Named Pipe/Domain Socket .. function:: listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket - + Listens on/Creates a Named Pipe/Domain Socket .. function:: getaddrinfo(host) - Gets the IP address of the ``host`` (may have to do a DNS lookup) - + Gets the IP address of the "host" (may have to do a DNS lookup) .. function:: parseip(addr) - Parse a string specifying an IPv4 or IPv6 ip address. - + Parse a string specifying an IPv4 or IPv6 ip address. .. function:: IPv4(host::Integer) -> IPv4 - Returns IPv4 object from ip address formatted as Integer - + Returns IPv4 object from ip address formatted as Integer .. function:: IPv6(host::Integer) -> IPv6 - Returns IPv6 object from ip address formatted as Integer - + Returns IPv6 object from ip address formatted as Integer .. function:: nb_available(stream) - Returns the number of bytes available for reading before a read from this stream or buffer will block. - + Returns the number of bytes available for reading before a read + from this stream or buffer will block. .. function:: accept(server[, client]) - Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. - + Accepts a connection on the given server and returns a connection + to the client. An uninitialized client stream may be provided, in + which case it will be used instead of creating a new stream. .. function:: listenany(port_hint) -> (UInt16, TcpServer) - Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server was created on and the server itself. - + Create a TcpServer on any port, using hint as a starting point. + Returns a tuple of the actual port that the server was created on + and the server itself. .. function:: watch_file(cb=false, s; poll=false) - Watch file or directory ``s`` and run callback ``cb`` when ``s`` is modified. The ``poll`` parameter specifies whether to use file system event monitoring or polling. The callback function ``cb`` should accept 3 arguments: ``(filename, events, status)`` where an object with boolean fields ``changed`` and ``renamed`` when using file system event monitoring, or ``readable`` and - + Watch file or directory "s" and run callback "cb" when "s" is + modified. The "poll" parameter specifies whether to use file + system event monitoring or polling. The callback function "cb" + should accept 3 arguments: "(filename, events, status)" where + "filename" is the name of file that was modified, "events" is + an object with boolean fields "changed" and "renamed" when + using file system event monitoring, or "readable" and + "writable" when using polling, and "status" is always 0. Pass + "false" for "cb" to not use a callback function. .. function:: poll_fd(fd, seconds::Real; readable=false, writable=false) - Poll a file descriptor fd for changes in the read or write availability and with a timeout given by the second argument. If the timeout is not needed, use ``wait(fd)`` instead. The keyword arguments determine which of read and/or write status should be monitored and at least one of them needs to be set to true. The returned value is an object with boolean fields ``readable``, - + Poll a file descriptor fd for changes in the read or write + availability and with a timeout given by the second argument. If + the timeout is not needed, use "wait(fd)" instead. The keyword + arguments determine which of read and/or write status should be + monitored and at least one of them needs to be set to true. The + returned value is an object with boolean fields "readable", + "writable", and "timedout", giving the result of the polling. .. function:: poll_file(s, interval_seconds::Real, seconds::Real) - Monitor a file for changes by polling every *interval_seconds* seconds for *seconds* seconds. A return value of true indicates the file changed, a return value of false indicates a timeout. - + Monitor a file for changes by polling every *interval_seconds* + seconds for *seconds* seconds. A return value of true indicates the + file changed, a return value of false indicates a timeout. .. function:: bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - Bind ``socket`` to the given ``host:port``. Note that *0.0.0.0* will listen on all devices. - + Bind "socket" to the given "host:port". Note that *0.0.0.0* + will listen on all devices. .. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) - Send ``msg`` over ``socket to `host:port``. - + Send "msg" over "socket to ``host:port". .. function:: recv(socket::UDPSocket) - Read a UDP packet from the specified socket, and return the bytes received. This call blocks. - + Read a UDP packet from the specified socket, and return the bytes + received. This call blocks. .. function:: recvfrom(socket::UDPSocket) -> (address, data) - Read a UDP packet from the specified socket, returning a tuple of appropriate. - + Read a UDP packet from the specified socket, returning a tuple of + (address, data), where address will be either IPv4 or IPv6 as + appropriate. .. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - Set UDP socket options. ``multicast_loop``: loopback for multicast packets (default: true). ``multicast_ttl``: TTL for multicast packets. ``enable_broadcast``: flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). ``ttl``: Time-to-live of packets sent on the socket. - + Set UDP socket options. "multicast_loop": loopback for multicast + packets (default: true). "multicast_ttl": TTL for multicast + packets. "enable_broadcast": flag must be set to true if socket + will be used for broadcast messages, or else the UDP system will + return an access error (default: false). "ttl": Time-to-live of + packets sent on the socket. .. function:: ntoh(x) - Converts the endianness of a value from Network byte order (big- endian) to that used by the Host. - + Converts the endianness of a value from Network byte order (big- + endian) to that used by the Host. .. function:: hton(x) - Converts the endianness of a value from that used by the Host to Network byte order (big-endian). - + Converts the endianness of a value from that used by the Host to + Network byte order (big-endian). .. function:: ltoh(x) - Converts the endianness of a value from Little-endian to that used by the Host. - + Converts the endianness of a value from Little-endian to that used + by the Host. .. function:: htol(x) - Converts the endianness of a value from that used by the Host to Little-endian. - + Converts the endianness of a value from that used by the Host to + Little-endian. .. data:: ENDIAN_BOM diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index c98bd72c9e445..6b9663f2dc446 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -6,63 +6,87 @@ .. function:: malloc(size::Integer) -> Ptr{Void} - Call ``malloc`` from the C standard library. - + Call "malloc" from the C standard library. .. function:: calloc(num::Integer, size::Integer) -> Ptr{Void} - Call ``calloc`` from the C standard library. - + Call "calloc" from the C standard library. .. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void} - Call ``realloc`` from the C standard library. See warning in the documentation for ``free`` regarding only using this on memory originally obtained from ``malloc``. + Call "realloc" from the C standard library. + See warning in the documentation for "free" regarding only using + this on memory originally obtained from "malloc". .. function:: free(addr::Ptr) - Call ``free`` from the C standard library. Only use this on memory obtained from ``malloc``, not on pointers retrieved from other C libraries. ``Ptr`` objects obtained from C libraries should be freed by the free functions defined in that library, to avoid assertion failures if multiple ``libc`` libraries exist on the system. - + Call "free" from the C standard library. Only use this on memory + obtained from "malloc", not on pointers retrieved from other C + libraries. "Ptr" objects obtained from C libraries should be + freed by the free functions defined in that library, to avoid + assertion failures if multiple "libc" libraries exist on the + system. .. function:: errno([code]) - Get the value of the C library's ``errno``. If an argument is specified, it is used to set the value of ``errno``. The value of ``errno`` is only valid immediately after a ``ccall`` to a C library routine that sets it. Specifically, you cannot call executed between prompts. + Get the value of the C library's "errno". If an argument is + specified, it is used to set the value of "errno". + The value of "errno" is only valid immediately after a "ccall" + to a C library routine that sets it. Specifically, you cannot call + "errno" at the next prompt in a REPL, because lots of code is + executed between prompts. .. function:: strerror(n) - Convert a system call error code to a descriptive string - + Convert a system call error code to a descriptive string .. function:: time(t::TmStruct) - Converts a ``TmStruct`` struct to a number of seconds since the epoch. - + Converts a "TmStruct" struct to a number of seconds since the + epoch. .. function:: strftime([format], time) - Convert time, given as a number of seconds since the epoch or a Supported formats are the same as those in the standard C library. - + Convert time, given as a number of seconds since the epoch or a + "TmStruct", to a formatted string using the given format. + Supported formats are the same as those in the standard C library. .. function:: strptime([format], timestr) - Parse a formatted time string into a ``TmStruct`` giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to ``time`` to convert it to seconds since the epoch, the will tell the C library to use the current system settings to determine the timezone. - + Parse a formatted time string into a "TmStruct" giving the + seconds, minute, hour, date, etc. Supported formats are the same as + those in the standard C library. On some platforms, timezones will + not be parsed correctly. If the result of this function will be + passed to "time" to convert it to seconds since the epoch, the + "isdst" field should be filled in manually. Setting it to "-1" + will tell the C library to use the current system settings to + determine the timezone. .. function:: TmStruct([seconds]) - Convert a number of seconds since the epoch to broken-down format, with fields ``sec``, ``min``, ``hour``, ``mday``, ``month``, - + Convert a number of seconds since the epoch to broken-down format, + with fields "sec", "min", "hour", "mday", "month", + "year", "wday", "yday", and "isdst". .. function:: flush_cstdio() - Flushes the C ``stdout`` and ``stderr`` streams (which may have been written to by external C code). - + Flushes the C "stdout" and "stderr" streams (which may have + been written to by external C code). .. function:: msync(ptr, len[, flags]) - Forces synchronization of the ``mmap()``ped memory region from combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + Forces synchronization of the "mmap()"ped memory region from + "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a + combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See + your platform man page for specifics. The flags argument is not + valid on Windows. + You may not need to call "msync", because synchronization is + performed at intervals automatically by the operating system. + However, you can call this directly if, for example, you are + concerned about losing the result of a long-running calculation. .. data:: MS_ASYNC @@ -78,11 +102,11 @@ .. function:: mmap(len, prot, flags, fd, offset) - Low-level interface to the ``mmap`` system call. See the man page. - + Low-level interface to the "mmap" system call. See the man page. .. function:: munmap(pointer, len) - Low-level interface for unmapping memory (see the man page). With is unmapped for you when the array goes out of scope. - + Low-level interface for unmapping memory (see the man page). With + "mmap_array()" you do not need to call this directly; the memory + is unmapped for you when the array goes out of scope. diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index c5e5538223a46..9788d78ba13d5 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -6,13 +6,25 @@ .. function:: dlopen(libfile::AbstractString[, flags::Integer]) - Load a shared library, returning an opaque handle. The optional flags argument is a bitwise-or of zero or more of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default is these flags, on POSIX platforms, is to specify symbols to be available for usage in other shared libraries, in situations where there are dependencies between shared libraries. - + Load a shared library, returning an opaque handle. + + The optional flags argument is a bitwise-or of zero or more of + "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", + "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and + "RTLD_FIRST". These are converted to the corresponding flags of + the POSIX (and/or GNU libc and/or MacOS) dlopen command, if + possible, or are ignored if the specified functionality is not + available on the current platform. The default is + "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of + these flags, on POSIX platforms, is to specify + "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's + symbols to be available for usage in other shared libraries, in + situations where there are dependencies between shared libraries. .. function:: dlopen_e(libfile::AbstractString[, flags::Integer]) - Similar to ``dlopen()``, except returns a ``NULL`` pointer instead of raising errors. - + Similar to "dlopen()", except returns a "NULL" pointer instead + of raising errors. .. data:: RTLD_DEEPBIND @@ -48,23 +60,27 @@ .. function:: dlsym(handle, sym) - Look up a symbol from a shared library handle, return callable function pointer on success. - + Look up a symbol from a shared library handle, return callable + function pointer on success. .. function:: dlsym_e(handle, sym) - Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. - + Look up a symbol from a shared library handle, silently return NULL + pointer on lookup failure. .. function:: dlclose(handle) - Close shared library referenced by handle. - + Close shared library referenced by handle. .. function:: find_library(names, locations) - Searches for the first library in ``names`` in the paths in the that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a - + Searches for the first library in "names" in the paths in the + "locations" list, "DL_LOAD_PATH", or system library paths (in + that order) which can successfully be dlopen'd. On success, the + return value will be one of the names (potentially prefixed by one + of the paths in locations). This string can be assigned to a + "global const" and used as the library name in future + "ccall"'s. On failure, it returns the empty string. .. data:: DL_LOAD_PATH diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index d7c9a1e29cb4a..f7f1500895fcd 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -15,8 +15,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. + Concatenate strings. The "*" operator is an alias to this + function. + julia> "Hello " * "world" + "Hello world" .. function:: \\(A, B) :noindex: @@ -27,551 +30,983 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: dot(x, y) - Compute the dot product. For complex vectors, the first vector is conjugated. + Compute the dot product. For complex vectors, the first vector is + conjugated. .. function:: vecdot(x, y) - For any iterable containers ``x`` and ``y`` (including arrays of any dimension) of numbers (or any element type for which ``dot`` is defined), compute the Euclidean dot product (the sum of ``dot(x[i],y[i])``) as if they were vectors. - + For any iterable containers "x" and "y" (including arrays of + any dimension) of numbers (or any element type for which "dot" is + defined), compute the Euclidean dot product (the sum of + "dot(x[i],y[i])") as if they were vectors. .. function:: cross(x, y) - Compute the cross product of two 3-vectors. + Compute the cross product of two 3-vectors. .. function:: factorize(A) - Compute a convenient factorization (including LU, Cholesky, Bunch- Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: - + Compute a convenient factorization (including LU, Cholesky, Bunch- + Kaufman, LowerTriangular, UpperTriangular) of A, based upon the + type of the input matrix. The return value can then be reused for + efficient solving of multiple systems. For example: + "A=factorize(A); x=A\\b; y=A\\C". .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. + Converts an orthogonal or unitary matrix stored as a + "QRCompactWYQ" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. + Optionally takes a "thin" Boolean argument, which if "true" + omits the columns that span the rows of "R" in the QR + factorization that are zero. The resulting matrix is the "Q" in a + thin QR factorization (sometimes called the reduced QR + factorization). If "false", returns a "Q" that spans all rows + of "R" in its corresponding QR factorization. Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. .. function:: lu(A) -> L, U, p - Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. - + Compute the LU factorization of "A", such that "A[p,:] = L*U". .. function:: lufact(A[, pivot=Val{true}]) -> F - Compute the LU factorization of ``A``. The return type of ``F`` depends on the type of ``A``. In most cases, if ``A`` is a subtype pivoting is chosen (default) the element type should also support examples are shown in the table below. The individual components of the factorization ``F`` can be accessed by indexing: - + Compute the LU factorization of "A". The return type of "F" + depends on the type of "A". In most cases, if "A" is a subtype + "S" of AbstractMatrix with an element type "T`" supporting + "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If + pivoting is chosen (default) the element type should also support + "abs" and "<". When "A" is sparse and have element of type + "Float32", "Float64", "Complex{Float32}", or + "Complex{Float64}" the return type is "UmfpackLU". Some + examples are shown in the table below. + + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input "A" | Type of output "F" | Relationship between "F" and "A" | + +-------------------------+---------------------------+----------------------------------------------+ + | "Matrix()" | "LU" | "F[:L]*F[:U] == A[F[:p], :]" | + +-------------------------+---------------------------+----------------------------------------------+ + | "Tridiagonal()" | "LU{T,Tridiagonal{T}}" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | "SparseMatrixCSC()" | "UmfpackLU" | "F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]" | + +-------------------------+---------------------------+----------------------------------------------+ + + The individual components of the factorization "F" can be + accessed by indexing: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | "LU" | "LU{T,Tridiagonal{T}}" | "UmfpackLU" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:L]" | "L" (lower triangular) part of "LU" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:U]" | "U" (upper triangular) part of "LU" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:p]" | (right) permutation "Vector" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:P]" | (right) permutation "Matrix" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:q]" | left permutation "Vector" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:Rs]" | "Vector" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:(:)]" | "(L,U,p,q,Rs)" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | "LU" | "LU{T,Tridiagonal{T}}" | "UmfpackLU" | + +--------------------+--------+--------------------------+---------------+ + | "/" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | "\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | "cond" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | "det" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | "logdet" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | "logabsdet" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | "size" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ .. function:: lufact!(A) -> LU - overwriting the input A, instead of creating a copy. For sparse 1-based indices to 0-based indices. - + "lufact!" is the same as "lufact()", but saves space by + overwriting the input A, instead of creating a copy. For sparse + "A" the "nzval" field is not overwritten but the index fields, + "colptr" and "rowval" are decremented in place, converting from + 1-based indices to 0-based indices. .. function:: chol(A[, LU]) -> F - Compute the Cholesky factorization of a symmetric positive definite matrix ``A`` and return the matrix ``F``. If ``LU`` is ``Val{:U}`` (Upper), ``F`` is of type ``UpperTriangular`` and ``A = F'*F``. If ``LU`` is ``Val{:L}`` (Lower), ``F`` is of type ``LowerTriangular`` and ``A = F*F'``. ``LU`` defaults to ``Val{:U}``. - + Compute the Cholesky factorization of a symmetric positive definite + matrix "A" and return the matrix "F". If "LU" is "Val{:U}" + (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If + "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" + and "A = F*F'". "LU" defaults to "Val{:U}". .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). - - Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). - - The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + Compute the Cholesky factorization of a sparse positive definite + matrix "A". A fill-reducing permutation is used. "F = + cholfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors + from "F", using "F[:L]". However, since pivoting is on by + default, the factorization is internally represented as "A == + P'*L*L'*P" with a permutation matrix "P"; using just "L" + without accounting for "P" will give incorrect answers. To + include the effects of permutation, it's typically preferable to + extact "combined" factors like "PtL = F[:PtL]" (the equivalent + of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations with ``F\\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from ``F``, using ``F[:L]``. However, since pivoting is on by default, the factorization is internally represented as ``A == P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact ``combined`` factors like ``PtL = F[:PtL]`` (the equivalent of ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). - - Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). - - The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + Compute the Cholesky factorization of a sparse positive definite + matrix "A". A fill-reducing permutation is used. "F = + cholfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors + from "F", using "F[:L]". However, since pivoting is on by + default, the factorization is internally represented as "A == + P'*L*L'*P" with a permutation matrix "P"; using just "L" + without accounting for "P" will give incorrect answers. To + include the effects of permutation, it's typically preferable to + extact "combined" factors like "PtL = F[:PtL]" (the equivalent + of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. .. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - ``cholfact!`` is the same as ``cholfact()``, but saves space by overwriting the input ``A``, instead of creating a copy. ``cholfact!`` can also reuse the symbolic factorization from a different matrix ``F`` with the same structure when used as: ``cholfact!(F::CholmodFactor, A)``. - + "cholfact!" is the same as "cholfact()", but saves space by + overwriting the input "A", instead of creating a copy. + "cholfact!" can also reuse the symbolic factorization from a + different matrix "F" with the same structure when used as: + "cholfact!(F::CholmodFactor, A)". .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix "A". A fill-reducing permutation is used. "F = + ldltfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors from + "F", using "F[:L]". However, since pivoting is on by default, + the factorization is internally represented as "A == P'*L*D*L'*P" + with a permutation matrix "P"; using just "L" without + accounting for "P" will give incorrect answers. To include the + effects of permutation, it's typically preferable to extact + "combined" factors like "PtL = F[:PtL]" (the equivalent of + "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The + complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, + :DU, :PtLD, :DUP". + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` are defined for ``F``. You can also extract individual factors from the factorization is internally represented as ``A == P'*L*D*L'*P`` with a permutation matrix ``P``; using just ``L`` without accounting for ``P`` will give incorrect answers. To include the effects of permutation, it's typically preferable to extact complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, Setting optional `shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. - + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix "A". A fill-reducing permutation is used. "F = + ldltfact(A)" is most frequently used to solve systems of equations + with "F\b", but also the methods "diag", "det", "logdet" + are defined for "F". You can also extract individual factors from + "F", using "F[:L]". However, since pivoting is on by default, + the factorization is internally represented as "A == P'*L*D*L'*P" + with a permutation matrix "P"; using just "L" without + accounting for "P" will give incorrect answers. To include the + effects of permutation, it's typically preferable to extact + "combined" factors like "PtL = F[:PtL]" (the equivalent of + "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The + complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, + :DU, :PtLD, :DUP". + + Setting optional "shift" keyword argument computes the + factorization of "A+shift*I" instead of "A". If the "perm" + argument is nonempty, it should be a permutation of *1:size(A,1)* + giving the ordering to use (instead of CHOLMOD's default AMD + ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. .. function:: qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - Compute the (pivoted) QR factorization of ``A`` such that either is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. - + Compute the (pivoted) QR factorization of "A" such that either + "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default + is to compute a thin factorization. Note that "R" is not extended + with zeros when the full "Q" is requested. .. function:: qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. - + Compute the QR factorization of a sparse matrix "A". A fill- + reducing permutation is used. The main application of this type is + to solve least squares problems with "". The function calls the + C library SPQR and a few additional functions from the library are + wrapped but not exported. .. function:: qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix ``A``. A fill- reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. - + Compute the QR factorization of a sparse matrix "A". A fill- + reducing permutation is used. The main application of this type is + to solve least squares problems with "". The function calls the + C library SPQR and a few additional functions from the library are + wrapped but not exported. .. function:: qrfact!(A[, pivot=Val{false}]) - instead of creating a copy. - + "qrfact!" is the same as "qrfact()" when A is a subtype of + "StridedMatrix", but saves space by overwriting the input "A", + instead of creating a copy. .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the columns that span the rows of ``R`` in the QR factorization that are zero. The resulting matrix is the ``Q`` in a thin QR factorization (sometimes called the reduced QR factorization). If ``false``, returns a ``Q`` that spans all rows of ``R`` in its corresponding QR factorization. + Converts an orthogonal or unitary matrix stored as a + "QRCompactWYQ" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. + Optionally takes a "thin" Boolean argument, which if "true" + omits the columns that span the rows of "R" in the QR + factorization that are zero. The resulting matrix is the "Q" in a + thin QR factorization (sometimes called the reduced QR + factorization). If "false", returns a "Q" that spans all rows + of "R" in its corresponding QR factorization. .. function:: bkfact(A) -> BunchKaufman - Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix ``A`` and return a - + Compute the Bunch-Kaufman [Bunch1977] factorization of a real + symmetric or complex Hermitian matrix "A" and return a + "BunchKaufman" object. The following functions are available for + "BunchKaufman" objects: "size", "", "inv", "issym", + "ishermitian". .. [Bunch1977] J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. `url `_. .. function:: bkfact!(A) -> BunchKaufman - overwriting the input ``A``, instead of creating a copy. - + "bkfact!" is the same as "bkfact()", but saves space by + overwriting the input "A", instead of creating a copy. .. function:: sqrtm(A) - Compute the matrix square root of ``A``. If ``B = sqrtm(A)``, then using Schur factorizations (``schurfact()``) unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition (``eigfact()``). In the latter situation for positive definite matrices, the matrix square root has ``Real`` elements, otherwise it has ``Complex`` elements. + Compute the matrix square root of "A". If "B = sqrtm(A)", then + "B*B == A" within roundoff error. + "sqrtm" uses a polyalgorithm, computing the matrix square root + using Schur factorizations ("schurfact()") unless it detects the + matrix to be Hermitian or real symmetric, in which case it computes + the matrix square root from an eigendecomposition ("eigfact()"). + In the latter situation for positive definite matrices, the matrix + square root has "Real" elements, otherwise it has "Complex" + elements. .. function:: eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. + Computes generalized eigenvalues and vectors of "A" with respect + to "B". + "eig" is a wrapper around "eigfact()", extracting all parts of + the factorization to a tuple; where possible, using "eigfact()" + is recommended. .. function:: eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. + Computes generalized eigenvalues and vectors of "A" with respect + to "B". + "eig" is a wrapper around "eigfact()", extracting all parts of + the factorization to a tuple; where possible, using "eigfact()" + is recommended. .. function:: eigvals(A,[irange,][vl,][vu]) - Returns the eigenvalues of ``A``. If ``A`` is ``Symmetric``, only a subset of the eigenvalues by specifying either a eigenvalues, or a pair ``vl`` and ``vu`` for the lower and upper boundaries of the eigenvalues. For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option ``permute=true`` permutes the matrix to become closer to upper triangular, and ``scale=true`` scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is ``true`` for both options. + Returns the eigenvalues of "A". If "A" is "Symmetric", + "Hermitian" or "SymTridiagonal", it is possible to calculate + only a subset of the eigenvalues by specifying either a + "UnitRange" "irange" covering indices of the sorted + eigenvalues, or a pair "vl" and "vu" for the lower and upper + boundaries of the eigenvalues. + For general non-symmetric matrices it is possible to specify how + the matrix is balanced before the eigenvector calculation. The + option "permute=true" permutes the matrix to become closer to + upper triangular, and "scale=true" scales the matrix by its + diagonal elements to make rows and columns more equal in norm. The + default is "true" for both options. .. function:: eigmax(A) - Returns the largest eigenvalue of ``A``. - + Returns the largest eigenvalue of "A". .. function:: eigmin(A) - Returns the smallest eigenvalue of ``A``. - + Returns the smallest eigenvalue of "A". .. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - Returns a matrix ``M`` whose columns are the eigenvectors of ``A``. k]``.) The `permute`` and ``scale`` keywords are the same as for For ``SymTridiagonal`` matrices, if the optional vector of eigenvalues ``eigvals`` is specified, returns the specific corresponding eigenvectors. + Returns a matrix "M" whose columns are the eigenvectors of "A". + (The "k"th eigenvector can be obtained from the slice "M[:, + k]".) The "permute" and "scale" keywords are the same as for + "eigfact()". + For "SymTridiagonal" matrices, if the optional vector of + eigenvalues "eigvals" is specified, returns the specific + corresponding eigenvectors. .. function:: eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) - + Computes the generalized eigenvalue decomposition of "A" and + "B", returning a "GeneralizedEigen" factorization object "F" + which contains the generalized eigenvalues in "F[:values]" and + the generalized eigenvectors in the columns of the matrix + "F[:vectors]". (The "k"th generalized eigenvector can be + obtained from the slice "F[:vectors][:, k]".) .. function:: eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of ``A`` and which contains the generalized eigenvalues in ``F[:values]`` and the generalized eigenvectors in the columns of the matrix obtained from the slice ``F[:vectors][:, k]``.) - + Computes the generalized eigenvalue decomposition of "A" and + "B", returning a "GeneralizedEigen" factorization object "F" + which contains the generalized eigenvalues in "F[:values]" and + the generalized eigenvectors in the columns of the matrix + "F[:vectors]". (The "k"th generalized eigenvector can be + obtained from the slice "F[:vectors][:, k]".) .. function:: eigfact!(A[, B]) - Same as ``eigfact()``, but saves space by overwriting the input - + Same as "eigfact()", but saves space by overwriting the input + "A" (and "B"), instead of creating a copy. .. function:: hessfact(A) - Compute the Hessenberg decomposition of ``A`` and return a unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``. When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with ``full()``. - + Compute the Hessenberg decomposition of "A" and return a + "Hessenberg" object. If "F" is the factorization object, the + unitary matrix can be accessed with "F[:Q]" and the Hessenberg + matrix with "F[:H]". When "Q" is extracted, the resulting type + is the "HessenbergQ" object, and may be converted to a regular + matrix with "full()". .. function:: hessfact!(A) - overwriting the input A, instead of creating a copy. - + "hessfact!" is the same as "hessfact()", but saves space by + overwriting the input A, instead of creating a copy. .. function:: schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and - + Computes the Generalized Schur (or QZ) factorization of the + matrices "A" and "B". The (quasi) triangular Schur factors can + be obtained from the "Schur" object "F" with "F[:S]" and + "F[:T]", the left unitary/orthogonal Schur vectors can be + obtained with "F[:left]" or "F[:Q]" and the right + unitary/orthogonal Schur vectors can be obtained with "F[:right]" + or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and + "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of + "A" and "B" can be obtained with "F[:alpha]./F[:beta]". .. function:: schurfact!(A) - Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See ``schurfact()`` - + Computes the Schur factorization of "A", overwriting "A" in the + process. See "schurfact()" .. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See ``schurfact()`` - + See "schurfact()" .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + Reorders the Generalized Schur factorization of a Generalized Schur + object. See "ordschur()". .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + "ordschur()". .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + Reorders the Generalized Schur factorization of a Generalized Schur + object. See "ordschur()". .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + "ordschur()". .. function:: schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and - + Computes the Generalized Schur (or QZ) factorization of the + matrices "A" and "B". The (quasi) triangular Schur factors can + be obtained from the "Schur" object "F" with "F[:S]" and + "F[:T]", the left unitary/orthogonal Schur vectors can be + obtained with "F[:left]" or "F[:Q]" and the right + unitary/orthogonal Schur vectors can be obtained with "F[:right]" + or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and + "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of + "A" and "B" can be obtained with "F[:alpha]./F[:beta]". .. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See ``schurfact()`` - + See "schurfact()" .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + Reorders the Generalized Schur factorization of a Generalized Schur + object. See "ordschur()". .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + "ordschur()". .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - + Reorders the Generalized Schur factorization of a Generalized Schur + object. See "ordschur()". .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + "ordschur()". .. function:: svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. - + Compute the generalized SVD of "A" and "B", returning a + "GeneralizedSVD" Factorization object "F", such that "A = + F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = + F[:V]*F[:D2]*F[:R0]*F[:Q]'". .. function:: svdfact!(A[, thin=true]) -> SVD - overwriting the input A, instead of creating a copy. If ``thin`` is to produce a thin decomposition. - + "svdfact!" is the same as "svdfact()", but saves space by + overwriting the input A, instead of creating a copy. If "thin" is + "true", an economy mode decomposition is returned. The default is + to produce a thin decomposition. .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. - + Wrapper around "svdfact" extracting all parts the factorization + to a tuple. Direct use of "svdfact" is therefore generally more + efficient. The function returns the generalized SVD of "A" and + "B", returning "U", "V", "Q", "D1", "D2", and "R0" + such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". .. function:: svdvals(A, B) - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. - + Return only the singular values from the generalized singular value + decomposition of "A" and "B". .. function:: svdvals!(A) - Returns the singular values of ``A``, while saving space by overwriting the input. - + Returns the singular values of "A", while saving space by + overwriting the input. .. function:: svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a F[:U]*F[:D1]*F[:R0]*F[:Q]'` and `B = F[:V]*F[:D2]*F[:R0]*F[:Q]'`. - + Compute the generalized SVD of "A" and "B", returning a + "GeneralizedSVD" Factorization object "F", such that "A = + F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = + F[:V]*F[:D2]*F[:R0]*F[:Q]'". .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. - + Wrapper around "svdfact" extracting all parts the factorization + to a tuple. Direct use of "svdfact" is therefore generally more + efficient. The function returns the generalized SVD of "A" and + "B", returning "U", "V", "Q", "D1", "D2", and "R0" + such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". .. function:: svdvals(A, B) - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. - + Return only the singular values from the generalized singular value + decomposition of "A" and "B". .. function:: triu(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. - + Returns the upper triangle of "M" starting from the "k"th + superdiagonal. .. function:: triu(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal. - + Returns the upper triangle of "M" starting from the "k"th + superdiagonal. .. function:: triu!(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. - + Returns the upper triangle of "M" starting from the "k"th + superdiagonal, overwriting "M" in the process. .. function:: triu!(M, k) - Returns the upper triangle of ``M`` starting from the ``k``th superdiagonal, overwriting ``M`` in the process. - + Returns the upper triangle of "M" starting from the "k"th + superdiagonal, overwriting "M" in the process. .. function:: tril(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. - + Returns the lower triangle of "M" starting from the "k"th + subdiagonal. .. function:: tril(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal. - + Returns the lower triangle of "M" starting from the "k"th + subdiagonal. .. function:: tril!(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. - + Returns the lower triangle of "M" starting from the "k"th + subdiagonal, overwriting "M" in the process. .. function:: tril!(M, k) - Returns the lower triangle of ``M`` starting from the ``k``th subdiagonal, overwriting ``M`` in the process. - + Returns the lower triangle of "M" starting from the "k"th + subdiagonal, overwriting "M" in the process. .. function:: diagind(M[, k]) - A ``Range`` giving the indices of the ``k``th diagonal of the matrix ``M``. - + A "Range" giving the indices of the "k"th diagonal of the + matrix "M". .. function:: diag(M[, k]) - The ``k``th diagonal of a matrix, as a vector. Use ``diagm`` to construct a diagonal matrix. - + The "k"th diagonal of a matrix, as a vector. Use "diagm" to + construct a diagonal matrix. .. function:: diagm(v[, k]) - Construct a diagonal matrix and place ``v`` on the ``k``th diagonal. - + Construct a diagonal matrix and place "v" on the "k"th + diagonal. .. function:: scale(b, A) - Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. + Scale an array "A" by a scalar "b", returning a new array. + If "A" is a matrix and "b" is a vector, then "scale(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), returning a new + array. + + Note: for large "A", "scale" can be much faster than "A .* b" + or "b .* A", due to the use of BLAS. .. function:: scale(b, A) - Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to array. Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or ``b .* A``, due to the use of BLAS. + Scale an array "A" by a scalar "b", returning a new array. + + If "A" is a matrix and "b" is a vector, then "scale(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), returning a new + array. + Note: for large "A", "scale" can be much faster than "A .* b" + or "b .* A", due to the use of BLAS. .. function:: scale!(b, A) - Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. + Scale an array "A" by a scalar "b", similar to "scale()" but + overwriting "A" in-place. + If "A" is a matrix and "b" is a vector, then "scale!(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- + place on "A". .. function:: scale!(b, A) - Scale an array ``A`` by a scalar ``b``, similar to ``scale()`` but overwriting ``A`` in-place. If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to place on ``A``. + Scale an array "A" by a scalar "b", similar to "scale()" but + overwriting "A" in-place. + If "A" is a matrix and "b" is a vector, then "scale!(A,b)" + scales each column "i" of "A" by "b[i]" (similar to + "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of + "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- + place on "A". .. function:: Tridiagonal(dl, d, du) - Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. - + Construct a tridiagonal matrix from the lower diagonal, diagonal, + and upper diagonal, respectively. The result is of type + "Tridiagonal" and provides efficient specialized linear solvers, + but may be converted into a regular matrix with "full()". .. function:: Bidiagonal(dv, ev, isupper) - Constructs an upper (``isupper=true``) or lower (``isupper=false``) bidiagonal matrix using the given diagonal (``dv``) and off- diagonal (``ev``) vectors. The result is of type ``Bidiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with ``full()``. - + Constructs an upper ("isupper=true") or lower ("isupper=false") + bidiagonal matrix using the given diagonal ("dv") and off- + diagonal ("ev") vectors. The result is of type "Bidiagonal" + and provides efficient specialized linear solvers, but may be + converted into a regular matrix with "full()". .. function:: SymTridiagonal(d, du) - Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type but may be converted into a regular matrix with ``full()``. - + Construct a real symmetric tridiagonal matrix from the diagonal and + upper diagonal, respectively. The result is of type + "SymTridiagonal" and provides efficient specialized eigensolvers, + but may be converted into a regular matrix with "full()". .. function:: rank(M) - Compute the rank of a matrix. - + Compute the rank of a matrix. .. function:: norm(A[, p]) - Compute the ``p``-norm of a vector or the operator norm of a matrix For vectors, ``p`` can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, ``norm(A, Inf)`` returns the largest value in For matrices, valid values of ``p`` are ``1``, ``2``, or ``Inf``. implemented.) Use ``vecnorm()`` to compute the Frobenius norm. + Compute the "p"-norm of a vector or the operator norm of a matrix + "A", defaulting to the "p=2"-norm. + For vectors, "p" can assume any numeric value (even though not + all values produce a mathematically valid vector norm). In + particular, "norm(A, Inf)" returns the largest value in + "abs(A)", whereas "norm(A, -Inf)" returns the smallest. -.. function:: vecnorm(A[, p]) + For matrices, valid values of "p" are "1", "2", or "Inf". + (Note that for sparse matrices, "p=2" is currently not + implemented.) Use "vecnorm()" to compute the Frobenius norm. - For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``-norm (defaulting to ``p=2``) as if ``A`` were a vector of the corresponding length. +.. function:: vecnorm(A[, p]) - For example, if ``A`` is a matrix and ``p=2``, then this is equivalent to the Frobenius norm. + For any iterable container "A" (including arrays of any + dimension) of numbers (or any element type for which "norm" is + defined), compute the "p"-norm (defaulting to "p=2") as if + "A" were a vector of the corresponding length. + For example, if "A" is a matrix and "p=2", then this is + equivalent to the Frobenius norm. .. function:: cond(M[, p]) - Condition number of the matrix ``M``, computed using the operator - + Condition number of the matrix "M", computed using the operator + "p"-norm. Valid values for "p" are "1", "2" (default), or + "Inf". .. function:: condskeel(M[, x, p]) - Skeel condition number \kappa_S of the matrix ``M``, optionally with respect to the vector ``x``, as computed using the operator values for ``p`` are ``1``, ``2``, or ``Inf``. This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. + \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \right\Vert_p \\ + \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \left\vert x \right\vert + \right\Vert_p + Skeel condition number \kappa_S of the matrix "M", optionally + with respect to the vector "x", as computed using the operator + "p"-norm. "p" is "Inf" by default, if not provided. Valid + values for "p" are "1", "2", or "Inf". -.. function:: trace(M) + This quantity is also known in the literature as the Bauer + condition number, relative condition number, or componentwise + relative condition number. - Matrix trace +.. function:: trace(M) + Matrix trace .. function:: det(M) - Matrix determinant - + Matrix determinant .. function:: logabsdet(M) - Log of absolute value of determinant of real matrix. Equivalent to ``(log(abs(det(M))), sign(det(M)))``, but may provide increased accuracy and/or speed. - + Log of absolute value of determinant of real matrix. Equivalent to + "(log(abs(det(M))), sign(det(M)))", but may provide increased + accuracy and/or speed. .. function:: logabsdet(M) - Log of absolute value of determinant of real matrix. Equivalent to ``(log(abs(det(M))), sign(det(M)))``, but may provide increased accuracy and/or speed. + Log of absolute value of determinant of real matrix. Equivalent to + "(log(abs(det(M))), sign(det(M)))", but may provide increased + accuracy and/or speed. .. function:: inv(M) - Matrix inverse - + Matrix inverse .. function:: pinv(M[, tol]) - Computes the Moore-Penrose pseudoinverse. For matrices ``M`` with floating point elements, it is convenient to compute the pseudoinverse by inverting only singular values above a given threshold, ``tol``. The optimal choice of ``tol`` varies both with the value of ``M`` and the intended application of the pseudoinverse. The default value of ``tol`` is essentially machine epsilon for the real part of a matrix element multiplied by the larger matrix dimension. For inverting dense ill- conditioned matrices in a least-squares sense, ``tol = sqrt(eps(real(float(one(eltype(M))))))`` is recommended. For more information, see [8859], [B96], [S84], [KY88]. + Computes the Moore-Penrose pseudoinverse. + For matrices "M" with floating point elements, it is convenient + to compute the pseudoinverse by inverting only singular values + above a given threshold, "tol". -.. function:: nullspace(M) + The optimal choice of "tol" varies both with the value of "M" + and the intended application of the pseudoinverse. The default + value of "tol" is + "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is + essentially machine epsilon for the real part of a matrix element + multiplied by the larger matrix dimension. For inverting dense ill- + conditioned matrices in a least-squares sense, "tol = + sqrt(eps(real(float(one(eltype(M))))))" is recommended. - Basis for nullspace of ``M``. + For more information, see [8859], [B96], [S84], [KY88]. + [8859] Issue 8859, "Fix least squares", + https://github.com/JuliaLang/julia/pull/8859 -.. function:: repmat(A, n, m) + [B96] Åke Björck, "Numerical Methods for Least Squares + Problems", SIAM Press, Philadelphia, 1996, "Other Titles in + Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 - Construct a matrix by repeating the given matrix ``n`` times in dimension 1 and ``m`` times in dimension 2. + [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 + [KY88] Konstantinos Konstantinides and Kung Yao, + "Statistical analysis of effective singular values in + matrix rank determination", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 -.. function:: repeat(A, inner = Int[], outer = Int[]) +.. function:: nullspace(M) - Construct an array by repeating the entries of ``A``. The i-th element of ``inner`` specifies the number of times that the individual entries of the i-th dimension of ``A`` should be repeated. The i-th element of ``outer`` specifies the number of times that a slice along the i-th dimension of ``A`` should be repeated. + Basis for nullspace of "M". +.. function:: repmat(A, n, m) -.. function:: kron(A, B) + Construct a matrix by repeating the given matrix "n" times in + dimension 1 and "m" times in dimension 2. - Kronecker tensor product of two vectors or two matrices. +.. function:: repeat(A, inner = Int[], outer = Int[]) + Construct an array by repeating the entries of "A". The i-th + element of "inner" specifies the number of times that the + individual entries of the i-th dimension of "A" should be + repeated. The i-th element of "outer" specifies the number of + times that a slice along the i-th dimension of "A" should be + repeated. -.. function:: blkdiag(A...) +.. function:: kron(A, B) - Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. + Kronecker tensor product of two vectors or two matrices. +.. function:: blkdiag(A...) -.. function:: linreg(x, y, w) + Concatenate matrices block-diagonally. Currently only implemented + for sparse matrices. - Weighted least-squares linear regression. +.. function:: linreg(x, y, w) + Weighted least-squares linear regression. .. function:: linreg(x, y, w) - Weighted least-squares linear regression. - + Weighted least-squares linear regression. .. function:: expm(A) - Matrix exponential. - + Matrix exponential. .. function:: lyap(A, C) - Computes the solution ``X`` to the continuous Lyapunov equation part and no two eigenvalues are negative complex conjugates of each other. - + Computes the solution "X" to the continuous Lyapunov equation + "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real + part and no two eigenvalues are negative complex conjugates of each + other. .. function:: sylvester(A, B, C) - Computes the solution ``X`` to the Sylvester equation `AX + XB + C - + Computes the solution "X" to the Sylvester equation "AX + XB + C + = 0", where "A", "B" and "C" have compatible dimensions and + "A" and "-B" have no eigenvalues with equal real part. .. function:: issym(A) -> Bool - Test whether a matrix is symmetric. - + Test whether a matrix is symmetric. .. function:: isposdef(A) -> Bool - Test whether a matrix is positive definite. - + Test whether a matrix is positive definite. .. function:: isposdef!(A) -> Bool - Test whether a matrix is positive definite, overwriting ``A`` in the processes. - + Test whether a matrix is positive definite, overwriting "A" in + the processes. .. function:: istril(A) -> Bool - Test whether a matrix is lower triangular. - + Test whether a matrix is lower triangular. .. function:: istriu(A) -> Bool - Test whether a matrix is upper triangular. - + Test whether a matrix is upper triangular. .. function:: isdiag(A) -> Bool - Test whether a matrix is diagonal. - + Test whether a matrix is diagonal. .. function:: ishermitian(A) -> Bool - Test whether a matrix is Hermitian. - + Test whether a matrix is Hermitian. .. function:: transpose(A) - The transposition operator (``.'``). - + The transposition operator (".'"). .. function:: transpose!(dest, src) - Transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. - + Transpose array "src" and store the result in the preallocated + array "dest", which should have a size corresponding to + "(size(src,2),size(src,1))". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. .. function:: ctranspose(A) - The conjugate transposition operator (``'``). - + The conjugate transposition operator ("'"). .. function:: ctranspose!(dest, src) - Conjugate transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. - + Conjugate transpose array "src" and store the result in the + preallocated array "dest", which should have a size corresponding + to "(size(src,2),size(src,1))". No in-place transposition is + supported and unexpected results will happen if *src* and *dest* + have overlapping memory regions. .. function:: eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - Computes eigenvalues ``d`` of ``A`` using Lanczos or Arnoldi iterations for real symmetric or general nonsymmetric matrices respectively. If ``B`` is provided, the generalized eigenproblem is solved. The following keyword arguments are supported: corresponding Ritz vectors ``v`` (only if ``ritzvec=true``), the number of converged eigenvalues ``nconv``, the number of iterations Note: The ``sigma`` and ``which`` keywords interact: the - + Computes eigenvalues "d" of "A" using Lanczos or Arnoldi + iterations for real symmetric or general nonsymmetric matrices + respectively. If "B" is provided, the generalized eigenproblem is + solved. + + The following keyword arguments are supported: + * "nev": Number of eigenvalues + + * "ncv": Number of Krylov vectors used in the computation; + should satisfy + + "nev+1 <= ncv <= n" for real symmetric problems and + "nev+2 <= ncv <= n" for other problems, where "n" is + the size of the input matrix "A". The default is "ncv = + max(20,2*nev+1)". Note that these restrictions limit the + input matrix "A" to be of dimension at least 2. + + * "which": type of eigenvalues to compute. See the note + below. + + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | "which" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":LM" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":SM" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":LR" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":SR" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":LI" | eigenvalues of largest imaginary part (nonsymmetric or complex "A" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":SI" | eigenvalues of smallest imaginary part (nonsymmetric or complex "A" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":BE" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric "A" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + + * "tol": tolerance (tol \le 0.0 defaults to + "DLAMCH('EPS')") + + * "maxiter": Maximum number of iterations (default = 300) + + * "sigma": Specifies the level shift used in inverse + iteration. If "nothing" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + "sigma" using shift and invert iterations. + + * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) + if "true" + + * "v0": starting vector from which to start the iterations + + "eigs" returns the "nev" requested eigenvalues in "d", the + corresponding Ritz vectors "v" (only if "ritzvec=true"), the + number of converged eigenvalues "nconv", the number of iterations + "niter" and the number of matrix vector multiplications + "nmult", as well as the final residual vector "resid". + + Note: The "sigma" and "which" keywords interact: the + description of eigenvalues searched for by "which" do _not_ + necessarily refer to the eigenvalues of "A", but rather the + linear operator constructed by the specification of the iteration + mode implied by "sigma". + + +-----------------+------------------------------------+------------------------------------+ + | "sigma" | iteration mode | "which" refers to eigenvalues of | + +-----------------+------------------------------------+------------------------------------+ + | "nothing" | ordinary (forward) | A | + +-----------------+------------------------------------+------------------------------------+ + | real or complex | inverse with level shift "sigma" | (A - \\sigma I )^{-1} | + +-----------------+------------------------------------+------------------------------------+ .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - Lanczos or Arnoldi iterations. Uses ``eigs()`` underneath. Inputs are: + "svds" computes largest singular values "s" of "A" using + Lanczos or Arnoldi iterations. Uses "eigs()" underneath. + + Inputs are: + * "A": Linear operator. It can either subtype of + "AbstractArray" (e.g., sparse matrix) or duck typed. For + duck typing "A" has to support "size(A)", "eltype(A)", + "A * vector" and "A' * vector". + + * "nsv": Number of singular values. + * "ritzvec": Whether to return the left and right singular + vectors "left_sv" and "right_sv", default is "true". If + "false" the singular vectors are omitted from the output. + + * "tol": tolerance, see "eigs()". + + * "maxiter": Maximum number of iterations, see "eigs()". + + **Example**: + + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) .. function:: peakflops(n; parallel=false) - double precision ``Base.LinAlg.BLAS.gemm!()``. By default, if no arguments are specified, it multiplies a matrix of size ``n x n``, where ``n = 2000``. If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with ``blas_set_num_threads(n)``. If the keyword argument ``parallel`` is set to ``true``, flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument ``n`` still refers to the size of the problem that is solved on each processor. + "peakflops" computes the peak flop rate of the computer by using + double precision "Base.LinAlg.BLAS.gemm!()". By default, if no + arguments are specified, it multiplies a matrix of size "n x n", + where "n = 2000". If the underlying BLAS is using multiple + threads, higher flop rates are realized. The number of BLAS threads + can be set with "blas_set_num_threads(n)". + If the keyword argument "parallel" is set to "true", + "peakflops" is run in parallel on all the worker processors. The + flop rate of the entire parallel computer is returned. When running + in parallel, only 1 BLAS thread is used. The argument "n" still + refers to the size of the problem that is solved on each processor. BLAS Functions -------------- @@ -589,218 +1024,259 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: dot(n, X, incx, Y, incy) - Dot product of two vectors consisting of ``n`` elements of array stride ``incy``. - + Dot product of two vectors consisting of "n" elements of array + "X" with stride "incx" and "n" elements of array "Y" with + stride "incy". .. function:: dotu(n, X, incx, Y, incy) - Dot function for two complex vectors. - + Dot function for two complex vectors. .. function:: dotc(n, X, incx, U, incy) - Dot function for two complex vectors conjugating the first vector. - + Dot function for two complex vectors conjugating the first vector. .. function:: blascopy!(n, X, incx, Y, incy) - Copy ``n`` elements of array ``X`` with stride ``incx`` to array - + Copy "n" elements of array "X" with stride "incx" to array + "Y" with stride "incy". Returns "Y". .. function:: nrm2(n, X, incx) - 2-norm of a vector consisting of ``n`` elements of array ``X`` with stride ``incx``. - + 2-norm of a vector consisting of "n" elements of array "X" with + stride "incx". .. function:: asum(n, X, incx) - sum of the absolute values of the first ``n`` elements of array - + sum of the absolute values of the first "n" elements of array + "X" with stride "incx". .. function:: axpy!(a, X, Y) - Overwrite ``Y`` with ``a*X + Y``. Returns ``Y``. - + Overwrite "Y" with "a*X + Y". Returns "Y". .. function:: scal!(n, a, X, incx) - Overwrite ``X`` with ``a*X``. Returns ``X``. - + Overwrite "X" with "a*X". Returns "X". .. function:: scal(n, a, X, incx) - Returns ``a*X``. - + Returns "a*X". .. function:: ger!(alpha, x, y, A) - Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as ``alpha*x*y' + A``. - + Rank-1 update of the matrix "A" with vectors "x" and "y" as + "alpha*x*y' + A". .. function:: syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix ``A`` with vector ``x`` as ``alpha*x*x.' + A``. When ``uplo`` is 'U' the upper triangle of ``A`` is updated ('L' for lower triangle). Returns ``A``. - + Rank-1 update of the symmetric matrix "A" with vector "x" as + "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of + "A" is updated ('L' for lower triangle). Returns "A". .. function:: syrk!(uplo, trans, alpha, A, beta, C) - Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. - + Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + + beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" + is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is + updated ('L' for lower triangle). Returns "C". .. function:: syrk(uplo, trans, alpha, A) - Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``, according to ``trans`` ('N' or 'T'). - + Returns either the upper triangle or the lower triangle, according + to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", + according to "trans" ('N' or 'T'). .. function:: her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When ``uplo`` is 'U' the upper triangle of ``A`` is updated ('L' for lower triangle). Returns ``A``. - + Methods for complex arrays only. Rank-1 update of the Hermitian + matrix "A" with vector "x" as "alpha*x*x' + A". When + "uplo" is 'U' the upper triangle of "A" is updated ('L' for + lower triangle). Returns "A". .. function:: herk!(uplo, trans, alpha, A, beta, C) - Methods for complex arrays only. Rank-k update of the Hermitian matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``. - + Methods for complex arrays only. Rank-k update of the Hermitian + matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" + according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' + the upper triangle of "C" is updated ('L' for lower triangle). + Returns "C". .. function:: herk(uplo, trans, alpha, A) - Methods for complex arrays only. Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of - + Methods for complex arrays only. Returns either the upper triangle + or the lower triangle, according to "uplo" ('U' or 'L'), of + "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or + 'T'). .. function:: gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - Update vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'*x + beta*y`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension ``m`` by ``size(A,2)`` with updated ``y``. - + Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + + beta*y" according to "trans" ('N' or 'T'). The matrix "A" is + a general band matrix of dimension "m" by "size(A,2)" with + "kl" sub-diagonals and "ku" super-diagonals. Returns the + updated "y". .. function:: gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - Returns ``alpha*A*x`` or ``alpha*A'*x`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension diagonals. - + Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' + or 'T'). The matrix "A" is a general band matrix of dimension + "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- + diagonals. .. function:: sbmv!(uplo, k, alpha, A, x, beta, y) - Update vector ``y`` as ``alpha*A*x + beta*y`` where ``A`` is a a symmetric band matrix of order ``size(A,2)`` with ``k`` super- diagonals stored in the argument ``A``. The storage layout for http://www.netlib.org/lapack/explore-html/. Returns the updated ``y``. + Update vector "y" as "alpha*A*x + beta*y" where "A" is a a + symmetric band matrix of order "size(A,2)" with "k" super- + diagonals stored in the argument "A". The storage layout for + "A" is described the reference BLAS module, level-2 BLAS at + http://www.netlib.org/lapack/explore-html/. + Returns the updated "y". .. function:: sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of order - + Returns "A*x" where "A" is a symmetric band matrix of order + "size(A,2)" with "k" super-diagonals stored in the argument + "A". .. function:: sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of order - + Returns "A*x" where "A" is a symmetric band matrix of order + "size(A,2)" with "k" super-diagonals stored in the argument + "A". .. function:: gemm!(tA, tB, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. Returns the updated ``C``. - + Update "C" as "alpha*A*B + beta*C" or the other three variants + according to "tA" (transpose "A") and "tB". Returns the + updated "C". .. function:: gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants according to ``tA`` - + Returns "A*B" or the other three variants according to "tA" + (transpose "A") and "tB". .. function:: gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants according to ``tA`` - + Returns "A*B" or the other three variants according to "tA" + (transpose "A") and "tB". .. function:: gemv!(tA, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``). Returns the updated - + Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + + beta*y" according to "tA" (transpose "A"). Returns the updated + "y". .. function:: gemv(tA, A, x) - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). - + Returns "A*x" or "A'x" according to "tA" (transpose "A"). .. function:: gemv(tA, A, x) - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). - + Returns "A*x" or "A'x" according to "tA" (transpose "A"). .. function:: symm!(side, ul, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` according to ``side``. ``A`` is assumed to be symmetric. Only the - + Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" + according to "side". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. Returns the updated "C". .. function:: symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants according to - + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". .. function:: symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants according to - + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". .. function:: symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants according to - + Returns "alpha*A*B" or the other three variants according to + "tA" (transpose "A") and "tB". .. function:: symv!(ul, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. Returns the updated ``y``. - + Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed + to be symmetric. Only the "ul" triangle of "A" is used. + Returns the updated "y". .. function:: symv(ul, A, x) - Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - + Returns "A*x". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. .. function:: symv(ul, A, x) - Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - + Returns "A*x". "A" is assumed to be symmetric. Only the + "ul" triangle of "A" is used. .. function:: trmm!(side, ul, tA, dA, alpha, A, B) - Update ``B`` as ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``B``. - + Update "B" as "alpha*A*B" or one of the other three variants + determined by "side" (A on left or right) and "tA" (transpose + A). Only the "ul" triangle of "A" is used. "dA" indicates if + "A" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated "B". .. function:: trmm(side, ul, tA, dA, alpha, A, B) - Returns ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). - + Returns "alpha*A*B" or one of the other three variants determined + by "side" (A on left or right) and "tA" (transpose A). Only the + "ul" triangle of "A" is used. "dA" indicates if "A" is + unit-triangular (the diagonal is assumed to be all ones). .. function:: trsm!(side, ul, tA, dA, alpha, A, B) - Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and ``tA`` (transpose A). Only the ``ul`` triangle of diagonal is assumed to be all ones). Returns the updated ``B``. - + Overwrite "B" with the solution to "A*X = alpha*B" or one of + the other three variants determined by "side" (A on left or right + of "X") and "tA" (transpose A). Only the "ul" triangle of + "A" is used. "dA" indicates if "A" is unit-triangular (the + diagonal is assumed to be all ones). Returns the updated "B". .. function:: trsm(side, ul, tA, dA, alpha, A, B) - Returns the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``) and assumed to be all ones). - + Returns the solution to "A*X = alpha*B" or one of the other three + variants determined by "side" (A on left or right of "X") and + "tA" (transpose A). Only the "ul" triangle of "A" is used. + "dA" indicates if "A" is unit-triangular (the diagonal is + assumed to be all ones). .. function:: trmv!(side, ul, tA, dA, alpha, A, b) - Update ``b`` as ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if Returns the updated ``b``. - + Update "b" as "alpha*A*b" or one of the other three variants + determined by "side" (A on left or right) and "tA" (transpose + A). Only the "ul" triangle of "A" is used. "dA" indicates if + "A" is unit-triangular (the diagonal is assumed to be all ones). + Returns the updated "b". .. function:: trmv(side, ul, tA, dA, alpha, A, b) - Returns ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose A). Only the unit-triangular (the diagonal is assumed to be all ones). - + Returns "alpha*A*b" or one of the other three variants determined + by "side" (A on left or right) and "tA" (transpose A). Only the + "ul" triangle of "A" is used. "dA" indicates if "A" is + unit-triangular (the diagonal is assumed to be all ones). .. function:: trsv!(ul, tA, dA, A, b) - Overwrite ``b`` with the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` triangular (the diagonal is assumed to be all ones). Returns the updated ``b``. - + Overwrite "b" with the solution to "A*x = b" or one of the + other two variants determined by "tA" (transpose A) and "ul" + (triangle of "A" used). "dA" indicates if "A" is unit- + triangular (the diagonal is assumed to be all ones). Returns the + updated "b". .. function:: trsv(ul, tA, dA, A, b) - Returns the solution to ``A*x = b`` or one of the other two variants determined by ``tA`` (transpose A) and ``ul`` (triangle of diagonal is assumed to be all ones). - + Returns the solution to "A*x = b" or one of the other two + variants determined by "tA" (transpose A) and "ul" (triangle of + "A" is used.) "dA" indicates if "A" is unit-triangular (the + diagonal is assumed to be all ones). .. function:: blas_set_num_threads(n) - Set the number of threads the BLAS library should use. - + Set the number of threads the BLAS library should use. .. data:: I diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index 2c8bb04e65f26..d6ac9da293a68 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -11,32 +11,34 @@ Mathematical Operators .. function:: -(x, y) - Subtraction operator. - + Subtraction operator. .. _+: .. function:: +(x, y...) - Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. ``+(x, y, z, ...)``. - + Addition operator. "x+y+z+..." calls this function with all + arguments, i.e. "+(x, y, z, ...)". .. _-: .. function:: -(x, y) - Subtraction operator. - + Subtraction operator. .. _*: .. function:: *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. + Concatenate strings. The "*" operator is an alias to this + function. + julia> "Hello " * "world" + "Hello world" .. _/: .. function:: /(x, y) - Right division operator: multiplication of ``x`` by the inverse of arguments. - + Right division operator: multiplication of "x" by the inverse of + "y" on the right. Gives floating-point results for integer + arguments. .. _\\: .. function:: \\(x, y) @@ -47,32 +49,31 @@ Mathematical Operators .. _^: .. function:: ^(s, n) - Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. + Repeat "n" times the string "s". The "^" operator is an alias + to this function. + julia> "Test "^3 + "Test Test Test " .. _.+: .. function:: .+(x, y) - Element-wise addition operator. - + Element-wise addition operator. .. _.-: .. function:: .-(x, y) - Element-wise subtraction operator. - + Element-wise subtraction operator. .. _.*: .. function:: .*(x, y) - Element-wise multiplication operator. - + Element-wise multiplication operator. .. _./: .. function:: ./(x, y) - Element-wise right division operator. - + Element-wise right division operator. .. _.\\: .. function:: .\\(x, y) @@ -82,107 +83,109 @@ Mathematical Operators .. _.^: .. function:: .^(x, y) - Element-wise exponentiation operator. - + Element-wise exponentiation operator. .. function:: fma(x, y, z) - Computes ``x*y+z`` without rounding the intermediate result algorithms. See ``muladd``. - + Computes "x*y+z" without rounding the intermediate result + "x*y". On some systems this is significantly more expensive than + "x*y+z". "fma" is used to improve accuracy in certain + algorithms. See "muladd". .. function:: muladd(x, y, z) - Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``, or to - + Combined multiply-add, computes "x*y+z" in an efficient manner. + This may on some systems be equivalent to "x*y+z", or to + "fma(x,y,z)". "muladd" is used to improve performance. See + "fma". .. function:: div(x, y) - The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. + The quotient from Euclidean division. Computes "x/y", truncated + to an integer. .. function:: fld(x, y) - Largest integer less than or equal to ``x/y``. - + Largest integer less than or equal to "x/y". .. function:: cld(x, y) - Smallest integer larger than or equal to ``x/y``. - + Smallest integer larger than or equal to "x/y". .. function:: mod(x, y) - Modulus after division, returning in the range [0,``y``), if ``y`` is positive, or (``y``,0] if ``y`` is negative. - + Modulus after division, returning in the range [0,``y``), if "y" + is positive, or ("y",0] if "y" is negative. .. function:: mod2pi(x) - Modulus after division by 2pi, returning in the range [0,2pi). This function computes a floating point representation of the modulus after division by numerically exact 2pi, and is therefore not exactly the same as mod(x,2pi), which would compute the modulus of x relative to division by the floating-point number 2pi. + Modulus after division by 2pi, returning in the range [0,2pi). + This function computes a floating point representation of the + modulus after division by numerically exact 2pi, and is therefore + not exactly the same as mod(x,2pi), which would compute the modulus + of x relative to division by the floating-point number 2pi. .. function:: rem(x, y) - Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than ``y``. This value is always exact. + Remainder from Euclidean division, returning a value of the same + sign as``x``, and smaller in magnitude than "y". This value is + always exact. .. function:: divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to - + The quotient and remainder from Euclidean division. Equivalent to + "(x÷y, x%y)". .. function:: fldmod(x, y) - The floored quotient and modulus after division. Equivalent to - + The floored quotient and modulus after division. Equivalent to + "(fld(x,y), mod(x,y))". .. function:: mod1(x, m) - Modulus after division, returning in the range (0,m] - + Modulus after division, returning in the range (0,m] .. function:: rem1(x, m) - Remainder after division, returning in the range (0,m] - + Remainder after division, returning in the range (0,m] .. _//: .. function:: //(num, den) - Divide two integers or rational numbers, giving a ``Rational`` result. - + Divide two integers or rational numbers, giving a "Rational" + result. .. function:: rationalize([Type=Int], x; tol=eps(x)) - Approximate floating point number ``x`` as a Rational number with components of the given integer type. The result will differ from - + Approximate floating point number "x" as a Rational number with + components of the given integer type. The result will differ from + "x" by no more than "tol". .. function:: num(x) - Numerator of the rational representation of ``x`` - + Numerator of the rational representation of "x" .. function:: den(x) - Denominator of the rational representation of ``x`` - + Denominator of the rational representation of "x" .. _<<: .. function:: <<(x, n) - Left bit shift operator. - + Left bit shift operator. .. _>>: .. function:: >>(x, n) - Right bit shift operator, preserving the sign of ``x``. - + Right bit shift operator, preserving the sign of "x". .. _>>>: .. function:: >>>(x, n) - Unsigned right bit shift operator. - + Unsigned right bit shift operator. .. _\:: .. function:: \:(start, [step], stop) @@ -194,120 +197,134 @@ Mathematical Operators .. function:: colon(start[, step], stop) - Called by ``:`` syntax for constructing ranges. - + Called by ":" syntax for constructing ranges. .. function:: range(start[, step], length) - Construct a range by length, given a starting value and optional step (defaults to 1). - + Construct a range by length, given a starting value and optional + step (defaults to 1). .. _==: .. function:: ==(x, y) - Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``. Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. Follows IEEE semantics for floating-point numbers. Collections should generally implement ``==`` by calling ``==`` recursively on all contents. New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible. + Generic equality operator, giving a single "Bool" result. Falls + back to "===". Should be implemented for all types with a notion + of equality, based on the abstract value that an instance + represents. For example, all numeric types are compared by numeric + value, ignoring type. Strings are compared as sequences of + characters, ignoring encoding. + + Follows IEEE semantics for floating-point numbers. + Collections should generally implement "==" by calling "==" + recursively on all contents. + + New numeric types should implement this function for two arguments + of the new type, and handle comparison to other types via promotion + rules where possible. .. _!=: .. function:: !=(x, y) - Not-equals comparison operator. Always gives the opposite answer as the fallback definition ``!=(x,y) = !(x==y)`` instead. + Not-equals comparison operator. Always gives the opposite answer as + "==". New types should generally not implement this, and rely on + the fallback definition "!=(x,y) = !(x==y)" instead. .. _===: .. function:: ===(x, y) - See the ``is()`` operator + See the "is()" operator .. _!==: .. function:: !==(x, y) - Equivalent to ``!is(x, y)`` + Equivalent to "!is(x, y)" .. _<: .. function:: <(x, y) - Less-than comparison operator. New numeric types should implement this function for two arguments of the new type. Because of the behavior of floating-point NaN values, ``<`` implements a partial order. Types with a canonical partial order should implement ``<``, and types with a canonical total order should implement ``isless``. - + Less-than comparison operator. New numeric types should implement + this function for two arguments of the new type. Because of the + behavior of floating-point NaN values, "<" implements a partial + order. Types with a canonical partial order should implement "<", + and types with a canonical total order should implement "isless". .. _<=: .. function:: <=(x, y) - Less-than-or-equals comparison operator. + Less-than-or-equals comparison operator. .. _>: .. function:: >(x, y) - Greater-than comparison operator. Generally, new types should implement ``<`` instead of this function, and rely on the fallback definition ``>(x,y) = y(x,y) = y=: .. function:: >=(x, y) - Greater-than-or-equals comparison operator. + Greater-than-or-equals comparison operator. .. _.==: .. function:: .==(x, y) - Element-wise equality comparison operator. - + Element-wise equality comparison operator. .. _.!=: .. function:: .!=(x, y) - Element-wise not-equals comparison operator. + Element-wise not-equals comparison operator. .. _.<: .. function:: .<(x, y) - Element-wise less-than comparison operator. - + Element-wise less-than comparison operator. .. _.<=: .. function:: .<=(x, y) - Element-wise less-than-or-equals comparison operator. + Element-wise less-than-or-equals comparison operator. .. _.>: .. function:: .>(x, y) - Element-wise greater-than comparison operator. - + Element-wise greater-than comparison operator. .. _.>=: .. function:: .>=(x, y) - Element-wise greater-than-or-equals comparison operator. + Element-wise greater-than-or-equals comparison operator. .. function:: cmp(x, y) - Return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``, respectively. Uses the total order implemented by ``isless``. For floating-point numbers, uses ``<`` but throws an error for unordered arguments. - + Return -1, 0, or 1 depending on whether "x" is less than, equal + to, or greater than "y", respectively. Uses the total order + implemented by "isless". For floating-point numbers, uses "<" + but throws an error for unordered arguments. .. _~: .. function:: ~(x) - Bitwise not - + Bitwise not .. _&: .. function:: &(x, y) - Bitwise and - + Bitwise and .. _|: .. function:: |(x, y) - Bitwise or - + Bitwise or .. _$: .. function:: \$(x, y) @@ -318,8 +335,7 @@ Mathematical Operators .. _!: .. function:: !(x) - Boolean not - + Boolean not .. _&&: .. function:: x && y @@ -333,391 +349,361 @@ Mathematical Operators .. function:: A_ldiv_Bc(a, b) - Matrix operator A \ B^H - + Matrix operator A \ B^H .. function:: A_ldiv_Bt(a, b) - Matrix operator A \ B^T - + Matrix operator A \ B^T .. function:: A_mul_B!(Y, A, B) -> Y - Calculates the matrix-matrix or matrix-vector product *A B* and stores the result in *Y*, overwriting the existing value of *Y*. + Calculates the matrix-matrix or matrix-vector product *A B* and + stores the result in *Y*, overwriting the existing value of *Y*. + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); -.. function:: A_mul_Bc(...) + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 - Matrix operator A B^H +.. function:: A_mul_Bc(...) + Matrix operator A B^H .. function:: A_mul_Bt(...) - Matrix operator A B^T - + Matrix operator A B^T .. function:: A_rdiv_Bc(...) - Matrix operator A / B^H - + Matrix operator A / B^H .. function:: A_rdiv_Bt(a, b) - Matrix operator A / B^T - + Matrix operator A / B^T .. function:: Ac_ldiv_B(...) - Matrix operator A^H \ B - + Matrix operator A^H \ B .. function:: Ac_ldiv_Bc(...) - Matrix operator A^H \ B^H - + Matrix operator A^H \ B^H .. function:: Ac_mul_B(...) - Matrix operator A^H B - + Matrix operator A^H B .. function:: Ac_mul_Bc(...) - Matrix operator A^H B^H - + Matrix operator A^H B^H .. function:: Ac_rdiv_B(a, b) - Matrix operator A^H / B - + Matrix operator A^H / B .. function:: Ac_rdiv_Bc(a, b) - Matrix operator A^H / B^H - + Matrix operator A^H / B^H .. function:: At_ldiv_B(...) - Matrix operator A^T \ B - + Matrix operator A^T \ B .. function:: At_ldiv_Bt(...) - Matrix operator A^T \ B^T - + Matrix operator A^T \ B^T .. function:: At_mul_B(...) - Matrix operator A^T B - + Matrix operator A^T B .. function:: At_mul_Bt(...) - Matrix operator A^T B^T - + Matrix operator A^T B^T .. function:: At_rdiv_B(a, b) - Matrix operator A^T / B - + Matrix operator A^T / B .. function:: At_rdiv_Bt(a, b) - Matrix operator A^T / B^T - + Matrix operator A^T / B^T Mathematical Functions ---------------------- .. function:: isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - Inexact equality comparison - behaves slightly different depending on types of input args: For default tolerance arguments, ``maxeps = max(eps(abs(x)), eps(abs(y)))``. + Inexact equality comparison - behaves slightly different depending + on types of input args: + * For "FloatingPoint" numbers, "isapprox" returns "true" if + "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". -.. function:: sin(x) + * For "Integer" and "Rational" numbers, "isapprox" returns + "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. + If one of "x" and "y" is "FloatingPoint", the other is + promoted, and the method above is called instead. - Compute sine of ``x``, where ``x`` is in radians + * For "Complex" numbers, the distance in the complex plane is + compared, using the same criterion as above. + For default tolerance arguments, "maxeps = max(eps(abs(x)), + eps(abs(y)))". -.. function:: cos(x) +.. function:: sin(x) + + Compute sine of "x", where "x" is in radians - Compute cosine of ``x``, where ``x`` is in radians +.. function:: cos(x) + Compute cosine of "x", where "x" is in radians .. function:: tan(x) - Compute tangent of ``x``, where ``x`` is in radians - + Compute tangent of "x", where "x" is in radians .. function:: sind(x) - Compute sine of ``x``, where ``x`` is in degrees - + Compute sine of "x", where "x" is in degrees .. function:: cosd(x) - Compute cosine of ``x``, where ``x`` is in degrees - + Compute cosine of "x", where "x" is in degrees .. function:: tand(x) - Compute tangent of ``x``, where ``x`` is in degrees - + Compute tangent of "x", where "x" is in degrees .. function:: sinpi(x) - Compute \sin(\pi x) more accurately than ``sin(pi*x)``, especially for large ``x``. - + Compute \sin(\pi x) more accurately than "sin(pi*x)", + especially for large "x". .. function:: cospi(x) - Compute \cos(\pi x) more accurately than ``cos(pi*x)``, especially for large ``x``. - + Compute \cos(\pi x) more accurately than "cos(pi*x)", + especially for large "x". .. function:: sinh(x) - Compute hyperbolic sine of ``x`` - + Compute hyperbolic sine of "x" .. function:: cosh(x) - Compute hyperbolic cosine of ``x`` - + Compute hyperbolic cosine of "x" .. function:: tanh(x) - Compute hyperbolic tangent of ``x`` - + Compute hyperbolic tangent of "x" .. function:: asin(x) - Compute the inverse sine of ``x``, where the output is in radians - + Compute the inverse sine of "x", where the output is in radians .. function:: acos(x) - Compute the inverse cosine of ``x``, where the output is in radians - + Compute the inverse cosine of "x", where the output is in radians .. function:: atan(x) - Compute the inverse tangent of ``x``, where the output is in radians - + Compute the inverse tangent of "x", where the output is in + radians .. function:: atan2(y, x) - Compute the inverse tangent of ``y/x``, using the signs of both - + Compute the inverse tangent of "y/x", using the signs of both + "x" and "y" to determine the quadrant of the return value. .. function:: asind(x) - Compute the inverse sine of ``x``, where the output is in degrees - + Compute the inverse sine of "x", where the output is in degrees .. function:: acosd(x) - Compute the inverse cosine of ``x``, where the output is in degrees - + Compute the inverse cosine of "x", where the output is in degrees .. function:: atand(x) - Compute the inverse tangent of ``x``, where the output is in degrees - + Compute the inverse tangent of "x", where the output is in + degrees .. function:: sec(x) - Compute the secant of ``x``, where ``x`` is in radians - + Compute the secant of "x", where "x" is in radians .. function:: csc(x) - Compute the cosecant of ``x``, where ``x`` is in radians - + Compute the cosecant of "x", where "x" is in radians .. function:: cot(x) - Compute the cotangent of ``x``, where ``x`` is in radians - + Compute the cotangent of "x", where "x" is in radians .. function:: secd(x) - Compute the secant of ``x``, where ``x`` is in degrees - + Compute the secant of "x", where "x" is in degrees .. function:: cscd(x) - Compute the cosecant of ``x``, where ``x`` is in degrees - + Compute the cosecant of "x", where "x" is in degrees .. function:: cotd(x) - Compute the cotangent of ``x``, where ``x`` is in degrees - + Compute the cotangent of "x", where "x" is in degrees .. function:: asec(x) - Compute the inverse secant of ``x``, where the output is in radians - + Compute the inverse secant of "x", where the output is in radians .. function:: acsc(x) - Compute the inverse cosecant of ``x``, where the output is in radians - + Compute the inverse cosecant of "x", where the output is in + radians .. function:: acot(x) - Compute the inverse cotangent of ``x``, where the output is in radians - + Compute the inverse cotangent of "x", where the output is in + radians .. function:: asecd(x) - Compute the inverse secant of ``x``, where the output is in degrees - + Compute the inverse secant of "x", where the output is in degrees .. function:: acscd(x) - Compute the inverse cosecant of ``x``, where the output is in degrees - + Compute the inverse cosecant of "x", where the output is in + degrees .. function:: acotd(x) - Compute the inverse cotangent of ``x``, where the output is in degrees - + Compute the inverse cotangent of "x", where the output is in + degrees .. function:: sech(x) - Compute the hyperbolic secant of ``x`` - + Compute the hyperbolic secant of "x" .. function:: csch(x) - Compute the hyperbolic cosecant of ``x`` - + Compute the hyperbolic cosecant of "x" .. function:: coth(x) - Compute the hyperbolic cotangent of ``x`` - + Compute the hyperbolic cotangent of "x" .. function:: asinh(x) - Compute the inverse hyperbolic sine of ``x`` - + Compute the inverse hyperbolic sine of "x" .. function:: acosh(x) - Compute the inverse hyperbolic cosine of ``x`` - + Compute the inverse hyperbolic cosine of "x" .. function:: atanh(x) - Compute the inverse hyperbolic tangent of ``x`` - + Compute the inverse hyperbolic tangent of "x" .. function:: asech(x) - Compute the inverse hyperbolic secant of ``x`` - + Compute the inverse hyperbolic secant of "x" .. function:: acsch(x) - Compute the inverse hyperbolic cosecant of ``x`` - + Compute the inverse hyperbolic cosecant of "x" .. function:: acoth(x) - Compute the inverse hyperbolic cotangent of ``x`` - + Compute the inverse hyperbolic cotangent of "x" .. function:: sinc(x) - Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. - + Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. .. function:: cosc(x) - Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq 0, and 0 if x = 0. This is the derivative of ``sinc(x)``. - + Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq + 0, and 0 if x = 0. This is the derivative of "sinc(x)". .. function:: deg2rad(x) - Convert ``x`` from degrees to radians - + Convert "x" from degrees to radians .. function:: rad2deg(x) - Convert ``x`` from radians to degrees - + Convert "x" from radians to degrees .. function:: hypot(x, y) - Compute the \sqrt{x^2+y^2} avoiding overflow and underflow - + Compute the \sqrt{x^2+y^2} avoiding overflow and underflow .. function:: log(b, x) - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. - + Compute the base "b" logarithm of "x". Throws "DomainError" + for negative "Real" arguments. .. function:: log(b, x) - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. - + Compute the base "b" logarithm of "x". Throws "DomainError" + for negative "Real" arguments. .. function:: log2(x) - Compute the logarithm of ``x`` to base 2. Throws ``DomainError`` for negative ``Real`` arguments. - + Compute the logarithm of "x" to base 2. Throws "DomainError" + for negative "Real" arguments. .. function:: log10(x) - Compute the logarithm of ``x`` to base 10. Throws ``DomainError`` for negative ``Real`` arguments. - + Compute the logarithm of "x" to base 10. Throws "DomainError" + for negative "Real" arguments. .. function:: log1p(x) - Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. + Accurate natural logarithm of "1+x". Throws "DomainError" for + "Real" arguments less than -1. + There is an experimental variant in the "Base.Math.JuliaLibm" + module, which is typically faster and more accurate. .. function:: frexp(val) - Return ``(x,exp)`` such that ``x`` has a magnitude in the interval - + Return "(x,exp)" such that "x" has a magnitude in the interval + "[1/2, 1)" or 0, and val = x \times 2^{exp}. .. function:: exp(x) - Compute e^x - + Compute e^x .. function:: exp2(x) - Compute 2^x - + Compute 2^x .. function:: exp10(x) - Compute 10^x - + Compute 10^x .. function:: ldexp(x, n) - Compute x \times 2^n - + Compute x \times 2^n .. function:: modf(x) - Return a tuple (fpart,ipart) of the fractional and integral parts of a number. Both parts have the same sign as the argument. - + Return a tuple (fpart,ipart) of the fractional and integral parts + of a number. Both parts have the same sign as the argument. .. function:: expm1(x) - Accurately compute e^x-1 - + Accurately compute e^x-1 .. function:: round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. - + Returns the nearest integral value of the same type as the complex- + valued "z" to "z", breaking ties using the specified + "RoundingMode"s. The first "RoundingMode" is used for rounding + the real components while the second is used for rounding the + imaginary components. julia> round(pi, 2) 3.14 @@ -786,558 +772,652 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- valued ``z`` to ``z``, breaking ties using the specified the real components while the second is used for rounding the imaginary components. - + Returns the nearest integral value of the same type as the complex- + valued "z" to "z", breaking ties using the specified + "RoundingMode"s. The first "RoundingMode" is used for rounding + the real components while the second is used for rounding the + imaginary components. .. function:: ceil([T], x[, digits[, base]]) + "ceil(x)" returns the nearest integral value of the same type as + "x" that is greater than or equal to "x". + + "ceil(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + "digits" and "base" work as for "round()". .. function:: floor([T], x[, digits[, base]]) + "floor(x)" returns the nearest integral value of the same type as + "x" that is less than or equal to "x". + "floor(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". .. function:: trunc([T], x[, digits[, base]]) + "trunc(x)" returns the nearest integral value of the same type as + "x" whose absolute value is less than or equal to "x". + "trunc(T, x)" converts the result to type "T", throwing an + "InexactError" if the value is not representable. -.. function:: unsafe_trunc(T, x) + "digits" and "base" work as for "round()". - value is not representable by ``T``, an arbitrary value will be returned. +.. function:: unsafe_trunc(T, x) + "unsafe_trunc(T, x)" returns the nearest integral value of type + "T" whose absolute value is less than or equal to "x". If the + value is not representable by "T", an arbitrary value will be + returned. .. function:: signif(x, digits[, base]) - Rounds (in the sense of ``round``) ``x`` so that there are representation, default 10. E.g., ``signif(123.456, 2)`` is - + Rounds (in the sense of "round") "x" so that there are + "digits" significant digits, under a base "base" + representation, default 10. E.g., "signif(123.456, 2)" is + "120.0", and "signif(357.913, 4, 2)" is "352.0". .. function:: min(x, y, ...) - Return the minimum of the arguments. Operates elementwise over arrays. - + Return the minimum of the arguments. Operates elementwise over + arrays. .. function:: max(x, y, ...) - Return the maximum of the arguments. Operates elementwise over arrays. - + Return the maximum of the arguments. Operates elementwise over + arrays. .. function:: minmax(x, y) - Return ``(min(x,y), max(x,y))``. See also: ``extrema()`` that returns ``(minimum(x), maximum(x))`` - + Return "(min(x,y), max(x,y))". See also: "extrema()" that + returns "(minimum(x), maximum(x))" .. function:: clamp(x, lo, hi) - Return x if ``lo <= x <= hi``. If ``x < lo``, return ``lo``. If ``x Operates elementwise over `x`` if it is an array. - + Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x + > hi", return "hi". Arguments are promoted to a common type. + Operates elementwise over "x" if it is an array. .. function:: abs(x) - Absolute value of ``x`` - + Absolute value of "x" .. function:: abs2(x) - Squared absolute value of ``x`` - + Squared absolute value of "x" .. function:: copysign(x, y) - Return ``x`` such that it has the same sign as ``y`` - + Return "x" such that it has the same sign as "y" .. function:: sign(x) - Return ``+1`` if ``x`` is positive, ``0`` if ``x == 0``, and ``-1`` if ``x`` is negative. - + Return "+1" if "x" is positive, "0" if "x == 0", and "-1" + if "x" is negative. .. function:: signbit(x) - Returns ``true`` if the value of the sign of ``x`` is negative, otherwise ``false``. - + Returns "true" if the value of the sign of "x" is negative, + otherwise "false". .. function:: flipsign(x, y) - Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``. - + Return "x" with its sign flipped if "y" is negative. For + example "abs(x) = flipsign(x,x)". .. function:: sqrt(x) - Return \sqrt{x}. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. The prefix operator ``√`` is equivalent to ``sqrt``. - + Return \sqrt{x}. Throws "DomainError" for negative "Real" + arguments. Use complex negative arguments instead. The prefix + operator "√" is equivalent to "sqrt". .. function:: isqrt(n) - Integer square root: the largest integer ``m`` such that ``m*m <= n``. - + Integer square root: the largest integer "m" such that "m*m <= + n". .. function:: cbrt(x) - Return x^{1/3}. The prefix operator ``∛`` is equivalent to - + Return x^{1/3}. The prefix operator "∛" is equivalent to + "cbrt". .. function:: erf(x) - Compute the error function of ``x``, defined by - + Compute the error function of "x", defined by + \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex + "x". .. function:: erfc(x) - Compute the complementary error function of ``x``, defined by 1 - - + Compute the complementary error function of "x", defined by 1 - + \operatorname{erf}(x). .. function:: erfcx(x) - Compute the scaled complementary error function of ``x``, defined by e^{x^2} \operatorname{erfc}(x). Note also that - + Compute the scaled complementary error function of "x", defined + by e^{x^2} \operatorname{erfc}(x). Note also that + \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). .. function:: erfi(x) - Compute the imaginary error function of ``x``, defined by -i - + Compute the imaginary error function of "x", defined by -i + \operatorname{erf}(ix). .. function:: dawson(x) - Compute the Dawson function (scaled imaginary error function) of - + Compute the Dawson function (scaled imaginary error function) of + "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} + \operatorname{erfi}(x). .. function:: erfinv(x) - Compute the inverse error function of a real ``x``, defined by - + Compute the inverse error function of a real "x", defined by + \operatorname{erf}(\operatorname{erfinv}(x)) = x. .. function:: erfcinv(x) - Compute the inverse error complementary function of a real ``x``, defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. - + Compute the inverse error complementary function of a real "x", + defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. .. function:: real(z) - Return the real part of the complex number ``z`` - + Return the real part of the complex number "z" .. function:: imag(z) - Return the imaginary part of the complex number ``z`` - + Return the imaginary part of the complex number "z" .. function:: reim(z) - Return both the real and imaginary parts of the complex number - + Return both the real and imaginary parts of the complex number + "z" .. function:: conj(z) - Compute the complex conjugate of a complex number ``z`` - + Compute the complex conjugate of a complex number "z" .. function:: angle(z) - Compute the phase angle in radians of a complex number ``z`` - + Compute the phase angle in radians of a complex number "z" .. function:: cis(z) - Return \exp(iz). - + Return \exp(iz). .. function:: binomial(n, k) - Number of ways to choose ``k`` out of ``n`` items - + Number of ways to choose "k" out of "n" items .. function:: factorial(n, k) - Compute ``factorial(n)/factorial(k)`` - + Compute "factorial(n)/factorial(k)" .. function:: factorial(n, k) - Compute ``factorial(n)/factorial(k)`` - + Compute "factorial(n)/factorial(k)" .. function:: factor(n) -> Dict - Compute the prime factorization of an integer ``n``. Returns a dictionary. The keys of the dictionary correspond to the factors, and hence are of the same type as ``n``. The value associated with each key indicates the number of times the factor appears in the factorization. + Compute the prime factorization of an integer "n". Returns a + dictionary. The keys of the dictionary correspond to the factors, + and hence are of the same type as "n". The value associated with + each key indicates the number of times the factor appears in the + factorization. + julia> factor(100) # == 2*2*5*5 + Dict{Int64,Int64} with 2 entries: + 2 => 2 + 5 => 2 .. function:: gcd(x, y) - Greatest common (positive) divisor (or zero if x and y are both zero). - + Greatest common (positive) divisor (or zero if x and y are both + zero). .. function:: lcm(x, y) - Least common (non-negative) multiple. - + Least common (non-negative) multiple. .. function:: gcdx(x, y) - Computes the greatest common (positive) divisor of ``x`` and ``y`` and their Bézout coefficients, i.e. the integer coefficients ``u`` and ``v`` that satisfy ux+vy = d = gcd(x,y). Note: Bézout coefficients are *not* uniquely defined. ``gcdx`` + Computes the greatest common (positive) divisor of "x" and "y" + and their Bézout coefficients, i.e. the integer coefficients "u" + and "v" that satisfy ux+vy = d = gcd(x,y). + julia> gcdx(12, 42) + (6,-3,1) -.. function:: ispow2(n) -> Bool + julia> gcdx(240, 46) + (2,-9,47) - Test whether ``n`` is a power of two + Note: Bézout coefficients are *not* uniquely defined. "gcdx" + returns the minimal Bézout coefficients that are computed by the + extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, + Algorithm X.) These coefficients "u" and "v" are minimal in + the sense that |u| < |\frac y d and |v| < |\frac x d. + Furthermore, the signs of "u" and "v" are chosen so that + "d" is positive. +.. function:: ispow2(n) -> Bool -.. function:: nextpow2(n) + Test whether "n" is a power of two - The smallest power of two not less than ``n``. Returns 0 for +.. function:: nextpow2(n) + The smallest power of two not less than "n". Returns 0 for + "n==0", and returns "-nextpow2(-n)" for negative arguments. .. function:: prevpow2(n) - The largest power of two not greater than ``n``. Returns 0 for - + The largest power of two not greater than "n". Returns 0 for + "n==0", and returns "-prevpow2(-n)" for negative arguments. .. function:: nextpow(a, x) - The smallest ``a^n`` not less than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must be greater than 0. - + The smallest "a^n" not less than "x", where "n" is a non- + negative integer. "a" must be greater than 1, and "x" must be + greater than 0. .. function:: prevpow(a, x) - The largest ``a^n`` not greater than ``x``, where ``n`` is a non- negative integer. ``a`` must be greater than 1, and ``x`` must not be less than 1. - + The largest "a^n" not greater than "x", where "n" is a non- + negative integer. "a" must be greater than 1, and "x" must not + be less than 1. .. function:: nextprod([k_1, k_2, ...], n) - Next integer not less than ``n`` that can be written as \prod k_i^{p_i} for integers p_1, p_2, etc. - + Next integer not less than "n" that can be written as \prod + k_i^{p_i} for integers p_1, p_2, etc. .. function:: prevprod([k_1, k_2, ...], n) - Previous integer not greater than ``n`` that can be written as - + Previous integer not greater than "n" that can be written as + \prod k_i^{p_i} for integers p_1, p_2, etc. .. function:: invmod(x, m) - Take the inverse of ``x`` modulo ``m``: ``y`` such that xy = 1 - + Take the inverse of "x" modulo "m": "y" such that xy = 1 + \pmod m .. function:: powermod(x, p, m) - Compute x^p \pmod m - + Compute x^p \pmod m .. function:: gamma(x) - Compute the gamma function of ``x`` - + Compute the gamma function of "x" .. function:: lgamma(x) - Compute the logarithm of the absolute value of ``gamma()`` for logarithm of ``gamma(x)``. - + Compute the logarithm of the absolute value of "gamma()" for + "Real" "x", while for "Complex" "x" it computes the + logarithm of "gamma(x)". .. function:: lfact(x) - Compute the logarithmic factorial of ``x`` - + Compute the logarithmic factorial of "x" .. function:: digamma(x) - Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(x)``) - + Compute the digamma function of "x" (the logarithmic derivative + of "gamma(x)") .. function:: invdigamma(x) - Compute the inverse digamma function of ``x``. - + Compute the inverse digamma function of "x". .. function:: trigamma(x) - Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``) - + Compute the trigamma function of "x" (the logarithmic second + derivative of "gamma(x)") .. function:: polygamma(m, x) - Compute the polygamma function of order ``m`` of argument ``x`` - + Compute the polygamma function of order "m" of argument "x" + (the "(m+1)th" derivative of the logarithm of "gamma(x)") .. function:: airy(k, x) - kth derivative of the Airy function \operatorname{Ai}(x). - + kth derivative of the Airy function \operatorname{Ai}(x). .. function:: airyai(x) - Airy function \operatorname{Ai}(x). - + Airy function \operatorname{Ai}(x). .. function:: airyprime(x) - Airy function derivative \operatorname{Ai}'(x). - + Airy function derivative \operatorname{Ai}'(x). .. function:: airyaiprime(x) - Airy function derivative \operatorname{Ai}'(x). - + Airy function derivative \operatorname{Ai}'(x). .. function:: airybi(x) - Airy function \operatorname{Bi}(x). - + Airy function \operatorname{Bi}(x). .. function:: airybiprime(x) - Airy function derivative \operatorname{Bi}'(x). - + Airy function derivative \operatorname{Bi}'(x). .. function:: airyx(k, x) - scaled kth derivative of the Airy function, return k == 1``, and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} k == 3``. - + scaled kth derivative of the Airy function, return + \operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || + k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} + \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || + k == 3". .. function:: besselj0(x) - Bessel function of the first kind of order 0, J_0(x). - + Bessel function of the first kind of order 0, J_0(x). .. function:: besselj1(x) - Bessel function of the first kind of order 1, J_1(x). - + Bessel function of the first kind of order 1, J_1(x). .. function:: besselj(nu, x) - Bessel function of the first kind of order ``nu``, J_\nu(x). - + Bessel function of the first kind of order "nu", J_\nu(x). .. function:: besseljx(nu, x) - Scaled Bessel function of the first kind of order ``nu``, J_\nu(x) e^{- | \operatorname{Im}(x) |}. - + Scaled Bessel function of the first kind of order "nu", J_\nu(x) + e^{- | \operatorname{Im}(x) |}. .. function:: bessely0(x) - Bessel function of the second kind of order 0, Y_0(x). - + Bessel function of the second kind of order 0, Y_0(x). .. function:: bessely1(x) - Bessel function of the second kind of order 1, Y_1(x). - + Bessel function of the second kind of order 1, Y_1(x). .. function:: bessely(nu, x) - Bessel function of the second kind of order ``nu``, Y_\nu(x). - + Bessel function of the second kind of order "nu", Y_\nu(x). .. function:: besselyx(nu, x) - Scaled Bessel function of the second kind of order ``nu``, Y_\nu(x) e^{- | \operatorname{Im}(x) |}. - + Scaled Bessel function of the second kind of order "nu", + Y_\nu(x) e^{- | \operatorname{Im}(x) |}. .. function:: hankelh1(nu, x) - Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x). - + Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). .. function:: hankelh1x(nu, x) - Scaled Bessel function of the third kind of order ``nu``, H^{(1)}_\nu(x) e^{-x i}. - + Scaled Bessel function of the third kind of order "nu", + H^{(1)}_\nu(x) e^{-x i}. .. function:: hankelh2(nu, x) - Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x). - + Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). .. function:: hankelh2x(nu, x) - Scaled Bessel function of the third kind of order ``nu``, H^{(2)}_\nu(x) e^{x i}. - + Scaled Bessel function of the third kind of order "nu", + H^{(2)}_\nu(x) e^{x i}. .. function:: besselh(nu, k, x) - Bessel function of the third kind of order ``nu`` (Hankel function). ``k`` is either 1 or 2, selecting ``hankelh1`` or - + Bessel function of the third kind of order "nu" (Hankel + function). "k" is either 1 or 2, selecting "hankelh1" or + "hankelh2", respectively. .. function:: besseli(nu, x) - Modified Bessel function of the first kind of order ``nu``, I_\nu(x). - + Modified Bessel function of the first kind of order "nu", + I_\nu(x). .. function:: besselix(nu, x) - Scaled modified Bessel function of the first kind of order ``nu``, I_\nu(x) e^{- | \operatorname{Re}(x) |}. - + Scaled modified Bessel function of the first kind of order "nu", + I_\nu(x) e^{- | \operatorname{Re}(x) |}. .. function:: besselk(nu, x) - Modified Bessel function of the second kind of order ``nu``, K_\nu(x). - + Modified Bessel function of the second kind of order "nu", + K_\nu(x). .. function:: besselkx(nu, x) - Scaled modified Bessel function of the second kind of order ``nu``, K_\nu(x) e^x. - + Scaled modified Bessel function of the second kind of order "nu", + K_\nu(x) e^x. .. function:: beta(x, y) - Euler integral of the first kind \operatorname{B}(x,y) = - + Euler integral of the first kind \operatorname{B}(x,y) = + \Gamma(x)\Gamma(y)/\Gamma(x+y). .. function:: lbeta(x, y) - Natural logarithm of the absolute value of the beta function - + Natural logarithm of the absolute value of the beta function + \log(|\operatorname{B}(x,y)|). .. function:: eta(x) - Dirichlet eta function \eta(s) = - + Dirichlet eta function \eta(s) = + \sum^\infty_{n=1}(-)^{n-1}/n^{s}. .. function:: zeta(s, z) - Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) - + Hurwitz zeta function \zeta(s, z). (This is equivalent to the + Riemann zeta function \zeta(s) for the case of "z=1".) .. function:: zeta(s, z) - Hurwitz zeta function \zeta(s, z). (This is equivalent to the Riemann zeta function \zeta(s) for the case of ``z=1``.) - + Hurwitz zeta function \zeta(s, z). (This is equivalent to the + Riemann zeta function \zeta(s) for the case of "z=1".) .. function:: ndigits(n, b) - Compute the number of digits in number ``n`` written in base ``b``. - + Compute the number of digits in number "n" written in base "b". .. function:: widemul(x, y) - Multiply ``x`` and ``y``, giving the result as a larger type. - + Multiply "x" and "y", giving the result as a larger type. .. function:: @evalpoly(z, c...) - Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients ascending order by power of ``z``. This macro expands to efficient inline code that uses either Horner's method or, for complex ``z``, a more efficient Goertzel-like algorithm. - + Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients + "c[1]", "c[2]", ...; that is, the coefficients are given in + ascending order by power of "z". This macro expands to efficient + inline code that uses either Horner's method or, for complex "z", + a more efficient Goertzel-like algorithm. Statistics ---------- .. function:: mean(v[, region]) - Compute the mean of whole array ``v``, or optionally along the dimensions in ``region``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. - + Compute the mean of whole array "v", or optionally along the + dimensions in "region". Note: Julia does not ignore "NaN" + values in the computation. For applications requiring the handling + of missing data, the "DataArray" package is recommended. .. function:: mean!(r, v) - Compute the mean of ``v`` over the singleton dimensions of ``r``, and write results to ``r``. - + Compute the mean of "v" over the singleton dimensions of "r", + and write results to "r". .. function:: std(v[, region]) - Compute the sample standard deviation of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the - + Compute the sample standard deviation of a vector or array "v", + optionally along dimensions in "region". The algorithm returns an + estimator of the generative distribution's standard deviation under + the assumption that each entry of "v" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". + Note: Julia does not ignore "NaN" values in the computation. For + applications requiring the handling of missing data, the + "DataArray" package is recommended. .. function:: stdm(v, m) - Compute the sample standard deviation of a vector ``v`` with known mean ``m``. Note: Julia does not ignore ``NaN`` values in the computation. - + Compute the sample standard deviation of a vector "v" with known + mean "m". Note: Julia does not ignore "NaN" values in the + computation. .. function:: var(v[, region]) - Compute the sample variance of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``. Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the - + Compute the sample variance of a vector or array "v", optionally + along dimensions in "region". The algorithm will return an + estimator of the generative distribution's variance under the + assumption that each entry of "v" is an IID drawn from that + generative distribution. This computation is equivalent to + calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: + Julia does not ignore "NaN" values in the computation. For + applications requiring the handling of missing data, the + "DataArray" package is recommended. .. function:: varm(v, m) - Compute the sample variance of a vector ``v`` with known mean computation. - + Compute the sample variance of a vector "v" with known mean + "m". Note: Julia does not ignore "NaN" values in the + computation. .. function:: middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. .. function:: middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. .. function:: middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. .. function:: middle(array) - Compute the middle of an array, which consists in finding its extrema and then computing their mean. - + Compute the middle of an array, which consists in finding its + extrema and then computing their mean. .. function:: median(v) - Compute the median of a vector ``v``. ``NaN`` is returned if the data contains any ``NaN`` values. For applications requiring the handling of missing data, the ``DataArrays`` package is recommended. - + Compute the median of a vector "v". "NaN" is returned if the + data contains any "NaN" values. For applications requiring the + handling of missing data, the "DataArrays" package is + recommended. .. function:: median!(v) - Like ``median``, but may overwrite the input vector. - + Like "median", but may overwrite the input vector. .. function:: hist(v, e) -> e, counts - Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. - + Compute the histogram of "v" using a vector/range "e" as the + edges for the bins. The result will be a vector of length + "length(e) - 1", such that the element at location "i" + satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not + ignore "NaN" values in the computation. .. function:: hist(v, e) -> e, counts - Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length satisfies ``sum(e[i] .< v .<= e[i+1])``. Note: Julia does not ignore ``NaN`` values in the computation. - + Compute the histogram of "v" using a vector/range "e" as the + edges for the bins. The result will be a vector of length + "length(e) - 1", such that the element at location "i" + satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not + ignore "NaN" values in the computation. .. function:: hist!(counts, v, e) -> e, counts - Compute the histogram of ``v``, using a vector/range ``e`` as the edges for the bins. This function writes the resultant counts to a pre-allocated array ``counts``. - + Compute the histogram of "v", using a vector/range "e" as the + edges for the bins. This function writes the resultant counts to a + pre-allocated array "counts". .. function:: hist2d(M, e1, e2) -> (edge1, edge2, counts) - Compute a ``2d histogram`` of a set of N points specified by N-by-2 matrix ``M``. Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as integer bin counts or vectors of bin edges. The result is a tuple of ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges used in the second dimension), and ``counts``, a histogram matrix of size - + Compute a "2d histogram" of a set of N points specified by N-by-2 + matrix "M". Arguments "e1" and "e2" are bins for each + dimension, specified either as integer bin counts or vectors of bin + edges. The result is a tuple of "edge1" (the bin edges used in + the first dimension), "edge2" (the bin edges used in the second + dimension), and "counts", a histogram matrix of size + "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore + "NaN" values in the computation. .. function:: hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - Compute a ``2d histogram`` with respect to the bins delimited by the edges given in ``e1`` and ``e2``. This function writes the results to a pre-allocated array ``counts``. - + Compute a "2d histogram" with respect to the bins delimited by + the edges given in "e1" and "e2". This function writes the + results to a pre-allocated array "counts". .. function:: histrange(v, n) - Compute *nice* bin ranges for the edges of a histogram of ``v``, using approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - + Compute *nice* bin ranges for the edges of a histogram of "v", + using approximately "n" bins. The resulting step sizes will be 1, + 2 or 5 multiplied by a power of 10. Note: Julia does not ignore + "NaN" values in the computation. .. function:: midpoints(e) - Compute the midpoints of the bins with edges ``e``. The result is a vector/range of length ``length(e) - 1``. Note: Julia does not ignore ``NaN`` values in the computation. + Compute the midpoints of the bins with edges "e". The result is a + vector/range of length "length(e) - 1". Note: Julia does not + ignore "NaN" values in the computation. +.. function:: quantile(v, p) + + Compute the quantile of a vector "v" at the probability "p". + Note: Julia does not ignore "NaN" values in the computation. .. function:: quantile(v, p) - Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. + Compute the quantile of a vector "v" at the probability "p". + Note: Julia does not ignore "NaN" values in the computation. +.. function:: quantile!(v, p) -.. function:: quantile(v, p) + Like "quantile", but overwrites the input vector. - Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. +.. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + Compute the Pearson covariance between the vector(s) in "v1" and + "v2". Here, "v1" and "v2" can be either vectors or matrices. -.. function:: quantile!(v, p) + This function accepts three keyword arguments: - Like ``quantile``, but overwrites the input vector. + * "vardim": the dimension of variables. When "vardim = 1", + variables are considered in columns while observations in rows; + when "vardim = 2", variables are in rows while observations in + columns. By default, it is set to "1". + * "corrected": whether to apply Bessel's correction (divide by + "n-1" instead of "n"). By default, it is set to "true". -.. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + * "mean": allow users to supply mean values that are known. By + default, it is set to "nothing", which indicates that the + mean(s) are unknown, and the function will compute the mean. + Users can use "mean=0" to indicate that the input data are + centered, and hence there's no need to subtract the mean. - Compute the Pearson covariance between the vector(s) in ``v1`` and This function accepts three keyword arguments: The size of the result depends on the size of ``v1`` and ``v2``. When both ``v1`` and ``v2`` are vectors, it returns the covariance between them as a scalar. When either one is a matrix, it returns a covariance matrix of size ``(n1, n2)``, where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and ``v2``, which depend on the setting of ``vardim``. Note: ``v2`` can be omitted, which indicates ``v2 = v1``. + The size of the result depends on the size of "v1" and "v2". + When both "v1" and "v2" are vectors, it returns the covariance + between them as a scalar. When either one is a matrix, it returns a + covariance matrix of size "(n1, n2)", where "n1" and "n2" are + the numbers of slices in "v1" and "v2", which depend on the + setting of "vardim". + Note: "v2" can be omitted, which indicates "v2 = v1". .. function:: cor(v1[, v2][, vardim=1, mean=nothing]) - Compute the Pearson correlation between the vector(s) in ``v1`` and Users can use the keyword argument ``vardim`` to specify the variable dimension, and ``mean`` to supply pre-computed mean values. + Compute the Pearson correlation between the vector(s) in "v1" and + "v2". + Users can use the keyword argument "vardim" to specify the + variable dimension, and "mean" to supply pre-computed mean + values. Signal Processing ----------------- @@ -1350,183 +1430,266 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: fft(A[, dims]) - Performs a multidimensional FFT of the array ``A``. The optional an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also A one-dimensional FFT computes the one-dimensional discrete Fourier transform (DFT) as defined by A multidimensional FFT simply performs this operation along each transformed dimension of ``A``. Higher performance is usually possible with multi-threading. Use processors. + Performs a multidimensional FFT of the array "A". The optional + "dims" argument specifies an iterable subset of dimensions (e.g. + an integer, range, tuple, or array) to transform along. Most + efficient if the size of "A" along the transformed dimensions is + a product of small primes; see "nextprod()". See also + "plan_fft()" for even greater efficiency. + A one-dimensional FFT computes the one-dimensional discrete Fourier + transform (DFT) as defined by -.. function:: fft!(A[, dims]) + \operatorname{DFT}(A)[k] = + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(-i\frac{2\pi + (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. + + A multidimensional FFT simply performs this operation along each + transformed dimension of "A". - Same as ``fft()``, but operates in-place on ``A``, which must be an array of complex floating-point numbers. + Higher performance is usually possible with multi-threading. Use + *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* + processors. + +.. function:: fft!(A[, dims]) + Same as "fft()", but operates in-place on "A", which must be an + array of complex floating-point numbers. .. function:: ifft(A[, dims]) - Multidimensional inverse FFT. A one-dimensional inverse FFT computes A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``. + Multidimensional inverse FFT. + A one-dimensional inverse FFT computes -.. function:: ifft!(A[, dims]) + \operatorname{IDFT}(A)[k] = + \frac{1}{\operatorname{length}(A)} + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(+i\frac{2\pi (n-1)(k-1)} + {\operatorname{length}(A)} \right) A[n]. + + A multidimensional inverse FFT simply performs this operation along + each transformed dimension of "A". - Same as ``ifft()``, but operates in-place on ``A``. +.. function:: ifft!(A[, dims]) + Same as "ifft()", but operates in-place on "A". .. function:: bfft(A[, dims]) - Similar to ``ifft()``, but computes an unnormalized inverse sizes of the transformed dimensions in order to obtain the inverse. scaling step, which in some applications can be combined with other computational steps elsewhere.) + Similar to "ifft()", but computes an unnormalized inverse + (backward) transform, which must be divided by the product of the + sizes of the transformed dimensions in order to obtain the inverse. + (This is slightly more efficient than "ifft()" because it omits a + scaling step, which in some applications can be combined with other + computational steps elsewhere.) + \operatorname{BDFT}(A)[k] = \operatorname{length}(A) + \operatorname{IDFT}(A)[k] .. function:: bfft!(A[, dims]) - Same as ``bfft()``, but operates in-place on ``A``. - + Same as "bfft()", but operates in-place on "A". .. function:: plan_fft(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized FFT along given dimensions (``dims``) of arrays matching the shape and type of ``A``. (The first two arguments have the same meaning as for ``fft()``.) Returns a function ``plan(A)`` that computes ``fft(A, dims)`` quickly. The ``flags`` argument is a bitwise-or of FFTW planner flags, defaulting to ``FFTW.ESTIMATE``. e.g. passing ``FFTW.MEASURE`` or benchmarking different possible FFT algorithms and picking the fastest one; see the FFTW manual for more information on planner flags. The optional ``timelimit`` argument specifies a rough upper bound on the allowed planning time, in seconds. Passing that operates in-place on its argument (which must be an array of complex floating-point numbers). ``plan_ifft()`` and so on are similar but produce plans that perform the equivalent of the inverse transforms ``ifft()`` and so on. - + Pre-plan an optimized FFT along given dimensions ("dims") of + arrays matching the shape and type of "A". (The first two + arguments have the same meaning as for "fft()".) Returns a + function "plan(A)" that computes "fft(A, dims)" quickly. + + The "flags" argument is a bitwise-or of FFTW planner flags, + defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or + "FFTW.PATIENT" will instead spend several seconds (or more) + benchmarking different possible FFT algorithms and picking the + fastest one; see the FFTW manual for more information on planner + flags. The optional "timelimit" argument specifies a rough upper + bound on the allowed planning time, in seconds. Passing + "FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array + "A" to be overwritten with zeros during plan creation. + + "plan_fft!()" is the same as "plan_fft()" but creates a plan + that operates in-place on its argument (which must be an array of + complex floating-point numbers). "plan_ifft()" and so on are + similar but produce plans that perform the equivalent of the + inverse transforms "ifft()" and so on. .. function:: plan_ifft(A[, dims[, flags[, timelimit]]]) - Same as ``plan_fft()``, but produces a plan that performs inverse transforms ``ifft()``. - + Same as "plan_fft()", but produces a plan that performs inverse + transforms "ifft()". .. function:: plan_bfft(A[, dims[, flags[, timelimit]]]) - Same as ``plan_fft()``, but produces a plan that performs an unnormalized backwards transform ``bfft()``. - + Same as "plan_fft()", but produces a plan that performs an + unnormalized backwards transform "bfft()". .. function:: plan_fft!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_fft()``, but operates in-place on ``A``. - + Same as "plan_fft()", but operates in-place on "A". .. function:: plan_ifft!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_ifft()``, but operates in-place on ``A``. - + Same as "plan_ifft()", but operates in-place on "A". .. function:: plan_bfft!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_bfft()``, but operates in-place on ``A``. - + Same as "plan_bfft()", but operates in-place on "A". .. function:: rfft(A[, dims]) - Multidimensional FFT of a real array A, exploiting the fact that the transform has conjugate symmetry in order to save roughly half the computational time and storage costs compared with ``fft()``. If ``A`` has size ``(n_1, ..., n_d)``, the result has size The optional ``dims`` argument specifies an iterable subset of one or more dimensions of ``A`` to transform, similar to ``fft()``. Instead of (roughly) halving the first dimension of ``A`` in the result, the ``dims[1]`` dimension is (roughly) halved in the same way. + Multidimensional FFT of a real array A, exploiting the fact that + the transform has conjugate symmetry in order to save roughly half + the computational time and storage costs compared with "fft()". + If "A" has size "(n_1, ..., n_d)", the result has size + "(floor(n_1/2)+1, ..., n_d)". + The optional "dims" argument specifies an iterable subset of one + or more dimensions of "A" to transform, similar to "fft()". + Instead of (roughly) halving the first dimension of "A" in the + result, the "dims[1]" dimension is (roughly) halved in the same + way. .. function:: irfft(A, d[, dims]) - Inverse of ``rfft()``: for a complex array ``A``, gives the corresponding real array whose FFT yields ``A`` in the first half. As for ``rfft()``, ``dims`` is an optional subset of dimensions to transform, defaulting to ``1:ndims(A)``. floor(size(A,dims[1])/2)+1``. (This parameter cannot be inferred from `size(A)`` due to the possibility of rounding by the + Inverse of "rfft()": for a complex array "A", gives the + corresponding real array whose FFT yields "A" in the first half. + As for "rfft()", "dims" is an optional subset of dimensions to + transform, defaulting to "1:ndims(A)". + "d" is the length of the transformed real array along the + "dims[1]" dimension, which must satisfy "d == + floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred + from "size(A)" due to the possibility of rounding by the + "floor" function here.) .. function:: brfft(A, d[, dims]) - Similar to ``irfft()`` but computes an unnormalized inverse transform (similar to ``bfft()``), which must be divided by the product of the sizes of the transformed dimensions (of the real output array) in order to obtain the inverse transform. - + Similar to "irfft()" but computes an unnormalized inverse + transform (similar to "bfft()"), which must be divided by the + product of the sizes of the transformed dimensions (of the real + output array) in order to obtain the inverse transform. .. function:: plan_rfft(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized real-input FFT, similar to ``plan_fft()`` except for ``rfft()`` instead of ``fft()``. The first two arguments, and the size of the transformed result, are the same as for ``rfft()``. - + Pre-plan an optimized real-input FFT, similar to "plan_fft()" + except for "rfft()" instead of "fft()". The first two + arguments, and the size of the transformed result, are the same as + for "rfft()". .. function:: plan_brfft(A, d[, dims[, flags[, timelimit]]]) - Pre-plan an optimized real-input unnormalized transform, similar to first two arguments and the size of the transformed result, are the same as for ``brfft()``. - + Pre-plan an optimized real-input unnormalized transform, similar to + "plan_rfft()" except for "brfft()" instead of "rfft()". The + first two arguments and the size of the transformed result, are the + same as for "brfft()". .. function:: plan_irfft(A, d[, dims[, flags[, timelimit]]]) - Pre-plan an optimized inverse real-input FFT, similar to respectively. The first three arguments have the same meaning as for ``irfft()``. - + Pre-plan an optimized inverse real-input FFT, similar to + "plan_rfft()" except for "irfft()" and "brfft()", + respectively. The first three arguments have the same meaning as + for "irfft()". .. function:: dct(A[, dims]) - Performs a multidimensional type-II discrete cosine transform (DCT) of the array ``A``, using the unitary normalization of the DCT. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see ``nextprod()``. See also ``plan_dct()`` for even greater efficiency. - + Performs a multidimensional type-II discrete cosine transform (DCT) + of the array "A", using the unitary normalization of the DCT. The + optional "dims" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. Most efficient if the size of "A" along the transformed + dimensions is a product of small primes; see "nextprod()". See + also "plan_dct()" for even greater efficiency. .. function:: dct!(A[, dims]) - Same as ``dct!()``, except that it operates in-place on ``A``, which must be an array of real or complex floating-point values. - + Same as "dct!()", except that it operates in-place on "A", + which must be an array of real or complex floating-point values. .. function:: idct(A[, dims]) - Computes the multidimensional inverse discrete cosine transform unitary normalization). The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. Most efficient if the size of ``A`` along the transformed dimensions is a product of small primes; see efficiency. - + Computes the multidimensional inverse discrete cosine transform + (DCT) of the array "A" (technically, a type-III DCT with the + unitary normalization). The optional "dims" argument specifies an + iterable subset of dimensions (e.g. an integer, range, tuple, or + array) to transform along. Most efficient if the size of "A" + along the transformed dimensions is a product of small primes; see + "nextprod()". See also "plan_idct()" for even greater + efficiency. .. function:: idct!(A[, dims]) - Same as ``idct!()``, but operates in-place on ``A``. - + Same as "idct!()", but operates in-place on "A". .. function:: plan_dct(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized discrete cosine transform (DCT), similar to The first two arguments have the same meaning as for ``dct()``. - + Pre-plan an optimized discrete cosine transform (DCT), similar to + "plan_fft()" except producing a function that computes "dct()". + The first two arguments have the same meaning as for "dct()". .. function:: plan_dct!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_dct()``, but operates in-place on ``A``. - + Same as "plan_dct()", but operates in-place on "A". .. function:: plan_idct(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized inverse discrete cosine transform (DCT), similar to ``plan_fft()`` except producing a function that computes - + Pre-plan an optimized inverse discrete cosine transform (DCT), + similar to "plan_fft()" except producing a function that computes + "idct()". The first two arguments have the same meaning as for + "idct()". .. function:: plan_idct!(A[, dims[, flags[, timelimit]]]) - Same as ``plan_idct()``, but operates in-place on ``A``. - + Same as "plan_idct()", but operates in-place on "A". .. function:: fftshift(x, dim) - Swap the first and second halves of the given dimension of array - + Swap the first and second halves of the given dimension of array + "x". .. function:: fftshift(x, dim) - Swap the first and second halves of the given dimension of array - + Swap the first and second halves of the given dimension of array + "x". .. function:: ifftshift(x[, dim]) - Undoes the effect of ``fftshift``. - + Undoes the effect of "fftshift". .. function:: filt(b, a, x[, si]) - Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an optional initial filter state vector ``si`` (defaults to zeros). - + Apply filter described by vectors "a" and "b" to vector "x", + with an optional initial filter state vector "si" (defaults to + zeros). .. function:: filt!(out, b, a, x[, si]) - Same as ``filt()`` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. - + Same as "filt()" but writes the result into the "out" argument, + which may alias the input "x" to modify it in-place. .. function:: deconv(b, a) - Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. - + Construct vector "c" such that "b = conv(a,c) + r". Equivalent + to polynomial division. .. function:: conv(u, v) - Convolution of two vectors. Uses FFT algorithm. - + Convolution of two vectors. Uses FFT algorithm. .. function:: conv2(B, A) - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm - + 2-D convolution of the matrix "B" with the matrix "A". Uses + 2-D FFT algorithm .. function:: conv2(B, A) - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm - + 2-D convolution of the matrix "B" with the matrix "A". Uses + 2-D FFT algorithm .. function:: xcorr(u, v) - Compute the cross-correlation of two vectors. - + Compute the cross-correlation of two vectors. The following functions are defined within the ``Base.FFTW`` module. @@ -1534,23 +1697,41 @@ The following functions are defined within the ``Base.FFTW`` module. .. function:: r2r(A, kind[, dims]) - Performs a multidimensional real-input/real-output (r2r) transform of type ``kind`` of the array ``A``, as defined in the FFTW manual. types (``FFTW.REDFT00``, ``FFTW.REDFT01``, ``FFTW.REDFT10``, or Hartley transform (``FFTW.DHT``). The ``kind`` argument may be an array or tuple in order to specify different transform types along the different dimensions of ``A``; ``kind[end]`` is used for any unspecified dimensions. See the FFTW manual for precise definitions of these transform types, at http://www.fftw.org/doc. The optional ``dims`` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to transform along. ``kind[i]`` is then the transform type for ``dims[i]``, with See also ``plan_r2r()`` to pre-plan optimized r2r transforms. - + Performs a multidimensional real-input/real-output (r2r) transform + of type "kind" of the array "A", as defined in the FFTW manual. + "kind" specifies either a discrete cosine transform of various + types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or + "FFTW.REDFT11"), a discrete sine transform of various types + ("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or + "FFTW.RODFT11"), a real-input DFT with halfcomplex-format output + ("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete + Hartley transform ("FFTW.DHT"). The "kind" argument may be an + array or tuple in order to specify different transform types along + the different dimensions of "A"; "kind[end]" is used for any + unspecified dimensions. See the FFTW manual for precise + definitions of these transform types, at http://www.fftw.org/doc. + + The optional "dims" argument specifies an iterable subset of + dimensions (e.g. an integer, range, tuple, or array) to transform + along. "kind[i]" is then the transform type for "dims[i]", with + "kind[end]" being used for "i > length(kind)". + + See also "plan_r2r()" to pre-plan optimized r2r transforms. .. function:: r2r!(A, kind[, dims]) - Same as ``r2r()``, but operates in-place on ``A``, which must be an array of real or complex floating-point numbers. - + Same as "r2r()", but operates in-place on "A", which must be an + array of real or complex floating-point numbers. .. function:: plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - Pre-plan an optimized r2r transform, similar to ``Base.plan_fft()`` except that the transforms (and the first three arguments) correspond to ``r2r()`` and ``r2r!()``, respectively. - + Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" + except that the transforms (and the first three arguments) + correspond to "r2r()" and "r2r!()", respectively. .. function:: plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) - Similar to ``Base.plan_fft()``, but corresponds to ``r2r!()``. - + Similar to "Base.plan_fft()", but corresponds to "r2r!()". .. currentmodule:: Base Numerical Integration @@ -1562,6 +1743,64 @@ some built-in integration support in Julia. .. function:: quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - Numerically integrate the function ``f(x)`` from ``a`` to ``b``, and optionally over additional intervals ``b`` to ``c`` and so on. Keyword options include a relative error tolerance ``reltol`` absolute error tolerance ``abstol`` (defaults to 0), a maximum number of function evaluations ``maxevals`` (defaults to ``10^7``), and the ``order`` of the integration rule (defaults to 7). Returns a pair ``(I,E)`` of the estimated integral ``I`` and an estimated upper bound on the absolute error ``E``. If ``maxevals`` is not exceeded then ``E <= max(abstol, reltol*norm(I))`` will hold. (Note that it is useful to specify a positive ``abstol`` in cases where ``norm(I)`` may be zero.) The endpoints ``a`` etcetera can also be complex (in which case the integral is performed over straight-line segments in the complex plane). If the endpoints are ``BigFloat``, then the integration will be performed in ``BigFloat`` precision as well (note: it is advisable to increase the integration ``order`` in rough proportion to the precision, for smooth integrands). More generally, the precision is set by the precision of the integration endpoints The integrand ``f(x)`` can return any numeric scalar, vector, or matrix type, or in fact any type supporting ``+``, ``-``, multiplication by real values, and a ``norm`` (i.e., any normed vector space). Alternatively, a different norm can be specified by passing a *norm*-like function as the *norm* keyword argument multi-dimensional integration (cubature), there are many different algorithms (often much better than simple nested 1d integrals) and the optimal choice tends to be very problem-dependent. See the Julia external-package listing for available algorithms for multidimensional integration or other specialized tasks (such as integrals of highly oscillatory or singular functions).] The algorithm is an adaptive Gauss-Kronrod integration technique: the integral in each interval is estimated using a Kronrod rule Gauss rule (``order`` points). The interval with the largest error is then subdivided into two intervals and the process is repeated until the desired error tolerance is achieved. These quadrature rules work best for smooth functions within each interval, so if your function has a known discontinuity or other singularity, it is best to subdivide your interval to put the singularity at an endpoint. For example, if ``f`` has a discontinuity at ``x=0.7`` and you want to integrate from 0 to 1, you should use ``quadgk(f, 0,0.7,1)`` to subdivide the interval at the point of discontinuity. The integrand is never evaluated exactly at the endpoints of the intervals, so it is possible to integrate functions that diverge at the endpoints as long as the singularity is integrable (for example, a ``log(x)`` or For real-valued endpoints, the starting and/or ending points may be infinite. (A coordinate transformation is performed internally to map the infinite interval to a finite one.) - + Numerically integrate the function "f(x)" from "a" to "b", + and optionally over additional intervals "b" to "c" and so on. + Keyword options include a relative error tolerance "reltol" + (defaults to "sqrt(eps)" in the precision of the endpoints), an + absolute error tolerance "abstol" (defaults to 0), a maximum + number of function evaluations "maxevals" (defaults to "10^7"), + and the "order" of the integration rule (defaults to 7). + + Returns a pair "(I,E)" of the estimated integral "I" and an + estimated upper bound on the absolute error "E". If "maxevals" + is not exceeded then "E <= max(abstol, reltol*norm(I))" will + hold. (Note that it is useful to specify a positive "abstol" in + cases where "norm(I)" may be zero.) + + The endpoints "a" etcetera can also be complex (in which case the + integral is performed over straight-line segments in the complex + plane). If the endpoints are "BigFloat", then the integration + will be performed in "BigFloat" precision as well (note: it is + advisable to increase the integration "order" in rough proportion + to the precision, for smooth integrands). More generally, the + precision is set by the precision of the integration endpoints + (promoted to floating-point types). + + The integrand "f(x)" can return any numeric scalar, vector, or + matrix type, or in fact any type supporting "+", "-", + multiplication by real values, and a "norm" (i.e., any normed + vector space). Alternatively, a different norm can be specified by + passing a *norm*-like function as the *norm* keyword argument + (which defaults to *vecnorm*). + + [Only one-dimensional integrals are provided by this function. For + multi-dimensional integration (cubature), there are many different + algorithms (often much better than simple nested 1d integrals) and + the optimal choice tends to be very problem-dependent. See the + Julia external-package listing for available algorithms for + multidimensional integration or other specialized tasks (such as + integrals of highly oscillatory or singular functions).] + + The algorithm is an adaptive Gauss-Kronrod integration technique: + the integral in each interval is estimated using a Kronrod rule + ("2*order+1" points) and the error is estimated using an embedded + Gauss rule ("order" points). The interval with the largest + error is then subdivided into two intervals and the process is + repeated until the desired error tolerance is achieved. + + These quadrature rules work best for smooth functions within each + interval, so if your function has a known discontinuity or other + singularity, it is best to subdivide your interval to put the + singularity at an endpoint. For example, if "f" has a + discontinuity at "x=0.7" and you want to integrate from 0 to 1, + you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at + the point of discontinuity. The integrand is never evaluated + exactly at the endpoints of the intervals, so it is possible to + integrate functions that diverge at the endpoints as long as the + singularity is integrable (for example, a "log(x)" or + "1/sqrt(x)" singularity). + + For real-valued endpoints, the starting and/or ending points may be + infinite. (A coordinate transformation is performed internally to + map the infinite interval to a finite one.) diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 5a0d031f7a9cf..9e4499c4136e3 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -14,126 +14,145 @@ Data Formats .. function:: bin(n[, pad]) - Convert an integer to a binary string, optionally specifying a number of digits to pad to. - + Convert an integer to a binary string, optionally specifying a + number of digits to pad to. .. function:: hex(n[, pad]) - Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. - + Convert an integer to a hexadecimal string, optionally specifying a + number of digits to pad to. .. function:: dec(n[, pad]) - Convert an integer to a decimal string, optionally specifying a number of digits to pad to. - + Convert an integer to a decimal string, optionally specifying a + number of digits to pad to. .. function:: oct(n[, pad]) - Convert an integer to an octal string, optionally specifying a number of digits to pad to. - + Convert an integer to an octal string, optionally specifying a + number of digits to pad to. .. function:: base(base, n[, pad]) - Convert an integer to a string in the given base, optionally specifying a number of digits to pad to. The base can be specified as either an integer, or as a ``UInt8`` array of character values to use as digit symbols. - + Convert an integer to a string in the given base, optionally + specifying a number of digits to pad to. The base can be specified + as either an integer, or as a "UInt8" array of character values + to use as digit symbols. .. function:: digits(n[, base][, pad]) - Returns an array of the digits of ``n`` in the given base, optionally padded with zeros to a specified size. More significant digits are at higher indexes, such that ``n == sum([digits[k]*base^(k-1) for k=1:length(digits)])``. - + Returns an array of the digits of "n" in the given base, + optionally padded with zeros to a specified size. More significant + digits are at higher indexes, such that "n == + sum([digits[k]*base^(k-1) for k=1:length(digits)])". .. function:: digits!(array, n[, base]) - Fills an array of the digits of ``n`` in the given base. More significant digits are at higher indexes. If the array length is insufficient, the least significant digits are filled up to the array length. If the array length is excessive, the excess portion is filled with zeros. - + Fills an array of the digits of "n" in the given base. More + significant digits are at higher indexes. If the array length is + insufficient, the least significant digits are filled up to the + array length. If the array length is excessive, the excess portion + is filled with zeros. .. function:: bits(n) - A string giving the literal bit representation of a number. - + A string giving the literal bit representation of a number. .. function:: parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. - + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. .. function:: tryparse(type, str[, base]) - Like ``parse``, but returns a ``Nullable`` of the requested type. The result will be null if the string does not contain a valid number. - + Like "parse", but returns a "Nullable" of the requested type. + The result will be null if the string does not contain a valid + number. .. function:: big(x) - Convert a number to a maximum precision representation (typically some pitfalls with floating-point numbers. - + Convert a number to a maximum precision representation (typically + "BigInt" or "BigFloat"). See "BigFloat" for information about + some pitfalls with floating-point numbers. .. function:: signed(x) - Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. - + Convert a number to a signed integer. If the argument is unsigned, + it is reinterpreted as signed without checking for overflow. .. function:: unsigned(x) -> Unsigned - Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as unsigned without checking for negative values. - + Convert a number to an unsigned integer. If the argument is signed, + it is reinterpreted as unsigned without checking for negative + values. .. function:: float(x) - Convert a number, array, or string to a ``FloatingPoint`` data type. For numeric data, the smallest suitable ``FloatingPoint`` type is used. Converts strings to ``Float64``. - + Convert a number, array, or string to a "FloatingPoint" data + type. For numeric data, the smallest suitable "FloatingPoint" + type is used. Converts strings to "Float64". .. function:: significand(x) - Extract the significand(s) (a.k.a. mantissa), in binary representation, of a floating-point number or array. If ``x`` is a non-zero finite number, than the result will be a number of the same type on the interval [1,2). Otherwise ``x`` is returned. + Extract the significand(s) (a.k.a. mantissa), in binary + representation, of a floating-point number or array. If "x" is a + non-zero finite number, than the result will be a number of the + same type on the interval [1,2). Otherwise "x" is returned. + julia> significand(15.2)/15.2 + 0.125 -.. function:: exponent(x) -> Int + julia> significand(15.2)*8 + 15.2 - Get the exponent of a normalized floating-point number. +.. function:: exponent(x) -> Int + Get the exponent of a normalized floating-point number. .. function:: complex(r[, i]) - Convert real numbers or arrays to complex. ``i`` defaults to zero. - + Convert real numbers or arrays to complex. "i" defaults to zero. .. function:: bswap(n) - Byte-swap an integer - + Byte-swap an integer .. function:: num2hex(f) - Get a hexadecimal string of the binary representation of a floating point number - + Get a hexadecimal string of the binary representation of a floating + point number .. function:: hex2num(str) - Convert a hexadecimal string to the floating point number it represents - + Convert a hexadecimal string to the floating point number it + represents .. function:: hex2bytes(s::ASCIIString) - Convert an arbitrarily long hexadecimal string to its binary representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. - + Convert an arbitrarily long hexadecimal string to its binary + representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. .. function:: bytes2hex(bin_arr::Array{UInt8, 1}) - Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. - + Convert an array of bytes to its hexadecimal representation. All + characters are in lower-case. Returns an ASCIIString. General Number Functions and Constants -------------------------------------- .. function:: one(x) - Get the multiplicative identity element for the type of x (x can also specify the type itself). For matrices, returns an identity matrix of the appropriate size and type. - + Get the multiplicative identity element for the type of x (x can + also specify the type itself). For matrices, returns an identity + matrix of the appropriate size and type. .. function:: zero(x) - Get the additive identity element for the type of x (x can also specify the type itself). - + Get the additive identity element for the type of x (x can also + specify the type itself). .. data:: pi π @@ -189,165 +208,222 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool - Test whether a floating point number is subnormal - + Test whether a floating point number is subnormal .. function:: isfinite(f) -> Bool - Test whether a number is finite - + Test whether a number is finite .. function:: isinf(f) -> Bool - Test whether a number is infinite - + Test whether a number is infinite .. function:: isnan(f) -> Bool - Test whether a floating point number is not a number (NaN) - + Test whether a floating point number is not a number (NaN) .. function:: inf(f) - Returns positive infinity of the floating point type ``f`` or of the same floating point type as ``f`` - + Returns positive infinity of the floating point type "f" or of + the same floating point type as "f" .. function:: nan(f) - Returns NaN (not-a-number) of the floating point type ``f`` or of the same floating point type as ``f`` - + Returns NaN (not-a-number) of the floating point type "f" or of + the same floating point type as "f" .. function:: nextfloat(f) - Get the next floating point number in lexicographic order - + Get the next floating point number in lexicographic order .. function:: prevfloat(f) -> FloatingPoint - Get the previous floating point number in lexicographic order - + Get the previous floating point number in lexicographic order .. function:: isinteger(x) -> Bool - Test whether ``x`` or all its elements are numerically equal to some integer - + Test whether "x" or all its elements are numerically equal to + some integer .. function:: isreal(x) -> Bool - Test whether ``x`` or all its elements are numerically equal to some real number - + Test whether "x" or all its elements are numerically equal to + some real number .. function:: Float32(x[, mode::RoundingMode]) - Create a Float32 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. + Create a Float32 from "x". If "x" is not exactly representable + then "mode" determines how "x" is rounded. + julia> Float32(1/3, RoundDown) + 0.3333333f0 -.. function:: Float64(x[, mode::RoundingMode]) + julia> Float32(1/3, RoundUp) + 0.33333334f0 + + See "get_rounding" for available rounding modes. - Create a Float64 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. See ``get_rounding`` for available rounding modes. +.. function:: Float64(x[, mode::RoundingMode]) + Create a Float64 from "x". If "x" is not exactly representable + then "mode" determines how "x" is rounded. -.. function:: BigInt(x) + julia> Float64(pi, RoundDown) + 3.141592653589793 - Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``). The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. + julia> Float64(pi, RoundUp) + 3.1415926535897936 - Instances can be constructed from strings via ``parse()``, or using the ``big`` string literal. + See "get_rounding" for available rounding modes. +.. function:: BigInt(x) -.. function:: BigFloat(x) + Create an arbitrary precision integer. "x" may be an "Int" (or + anything that can be converted to an "Int"). The usual + mathematical operators are defined for this type, and results are + promoted to a "BigInt". - Create an arbitrary precision floating point number. ``x`` may be an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results are promoted to a ``BigFloat``. + Instances can be constructed from strings via "parse()", or using + the "big" string literal. - Note that because decimal literals are converted to floating point numbers when parsed, ``BigFloat(2.1)`` may not yield what you expect. You may instead prefer to initialize constants from strings via ``parse()``, or using the ``big`` string literal. +.. function:: BigFloat(x) - :: + Create an arbitrary precision floating point number. "x" may be + an "Integer", a "Float64" or a "BigInt". The usual + mathematical operators are defined for this type, and results are + promoted to a "BigFloat". - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision + Note that because decimal literals are converted to floating point + numbers when parsed, "BigFloat(2.1)" may not yield what you + expect. You may instead prefer to initialize constants from strings + via "parse()", or using the "big" string literal. + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision .. function:: get_rounding(T) - Get the current floating point rounding mode for type ``T``, controlling the rounding of basic arithmetic functions (``+()``, Valid modes are ``RoundNearest``, ``RoundToZero``, ``RoundUp``, + Get the current floating point rounding mode for type "T", + controlling the rounding of basic arithmetic functions ("+()", + "-()", "*()", "/()" and "sqrt()") and type conversion. + Valid modes are "RoundNearest", "RoundToZero", "RoundUp", + "RoundDown", and "RoundFromZero" ("BigFloat" only). .. function:: set_rounding(T, mode) - Set the rounding mode of floating point type ``T``, controlling the rounding of basic arithmetic functions (``+()``, ``-()``, ``*()``, Note that this may affect other types, for instance changing the rounding mode of ``Float64`` will change the rounding mode of + Set the rounding mode of floating point type "T", controlling the + rounding of basic arithmetic functions ("+()", "-()", "*()", + "/()" and "sqrt()") and type conversion. + Note that this may affect other types, for instance changing the + rounding mode of "Float64" will change the rounding mode of + "Float32". See "get_rounding" for available modes .. function:: with_rounding(f::Function, T, mode) - Change the rounding mode of floating point type ``T`` for the duration of ``f``. It is logically equivalent to: See ``get_rounding`` for available rounding modes. + Change the rounding mode of floating point type "T" for the + duration of "f". It is logically equivalent to: + + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) + See "get_rounding" for available rounding modes. Integers ~~~~~~~~ .. function:: count_ones(x::Integer) -> Integer - Number of ones in the binary representation of ``x``. + Number of ones in the binary representation of "x". + julia> count_ones(7) + 3 .. function:: count_zeros(x::Integer) -> Integer - Number of zeros in the binary representation of ``x``. + Number of zeros in the binary representation of "x". + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 .. function:: leading_zeros(x::Integer) -> Integer - Number of zeros leading the binary representation of ``x``. + Number of zeros leading the binary representation of "x". + julia> leading_zeros(Int32(1)) + 31 .. function:: leading_ones(x::Integer) -> Integer - Number of ones leading the binary representation of ``x``. + Number of ones leading the binary representation of "x". + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 .. function:: trailing_zeros(x::Integer) -> Integer - Number of zeros trailing the binary representation of ``x``. + Number of zeros trailing the binary representation of "x". + julia> trailing_zeros(2) + 1 .. function:: trailing_ones(x::Integer) -> Integer - Number of ones trailing the binary representation of ``x``. + Number of ones trailing the binary representation of "x". + julia> trailing_ones(3) + 2 .. function:: isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). - - :: - - julia> isprime(big(3)) - true + Probabilistic primality test. Returns "true" if "x" is prime; + and "false" if "x" is not prime with high probability. The + false positive rate is about "0.25^reps". "reps = 25" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). + julia> isprime(big(3)) + true .. function:: isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). - - :: - - julia> isprime(big(3)) - true + Probabilistic primality test. Returns "true" if "x" is prime; + and "false" if "x" is not prime with high probability. The + false positive rate is about "0.25^reps". "reps = 25" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). + julia> isprime(big(3)) + true .. function:: primes(n) - Returns a collection of the prime numbers <= ``n``. - + Returns a collection of the prime numbers <= "n". .. function:: isodd(x::Integer) -> Bool - Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and + Returns "true" if "x" is odd (that is, not divisible by 2), and + "false" otherwise. + + julia> isodd(9) + true + julia> isodd(10) + false .. function:: iseven(x::Integer) -> Bool - Returns ``true`` is ``x`` is even (that is, divisible by 2), and + Returns "true" is "x" is even (that is, divisible by 2), and + "false" otherwise. + julia> iseven(9) + false + + julia> iseven(10) + true BigFloats --------- @@ -355,23 +431,26 @@ The `BigFloat` type implements arbitrary-precision floating-point arithmetic usi .. function:: precision(num::FloatingPoint) - Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. - + Get the precision of a floating point number, as defined by the + effective number of bits in the mantissa. .. function:: get_bigfloat_precision() - Get the precision (in bits) currently used for BigFloat arithmetic. - + Get the precision (in bits) currently used for BigFloat arithmetic. .. function:: set_bigfloat_precision(x::Int64) - Set the precision (in bits) to be used to BigFloat arithmetic. - + Set the precision (in bits) to be used to BigFloat arithmetic. .. function:: with_bigfloat_precision(f::Function, precision::Integer) - Change the BigFloat arithmetic precision (in bits) for the duration of ``f``. It is logically equivalent to: + Change the BigFloat arithmetic precision (in bits) for the duration + of "f". It is logically equivalent to: + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) .. _random-numbers: @@ -394,51 +473,68 @@ As ``BigInt`` represents unbounded integers, the interval must be specified (e.g .. function:: srand([rng][, seed]) - Reseed the random number generator. If a ``seed`` is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. For ``MersenneTwister``, the integers or a filename, in which case the seed is read from a file. - + Reseed the random number generator. If a "seed" is provided, the + RNG will give a reproducible sequence of numbers, otherwise Julia + will get entropy from the system. For "MersenneTwister", the + "seed" may be a non-negative integer, a vector of "UInt32" + integers or a filename, in which case the seed is read from a file. + "RandomDevice" does not support seeding. .. function:: MersenneTwister([seed]) - Create a ``MersenneTwister`` RNG object. Different RNG objects can have their own seeds, which may be useful for generating different streams of random numbers. - + Create a "MersenneTwister" RNG object. Different RNG objects can + have their own seeds, which may be useful for generating different + streams of random numbers. .. function:: RandomDevice() - Create a ``RandomDevice`` RNG object. Two such objects will always generate different streams of random numbers. - + Create a "RandomDevice" RNG object. Two such objects will always + generate different streams of random numbers. .. function:: rand([rng][, S][, dims...]) - Pick a random element or array of random elements from the set of values specified by ``S``; ``S`` can be + Pick a random element or array of random elements from the set of + values specified by "S"; "S" can be + * an indexable collection (for example "1:n" or + "['x','y','z']"), or -.. function:: rand!([rng], A[, coll]) + * a type: the set of values to pick from is then equivalent to + "typemin(S):typemax(S)" for integers (this is not applicable to + "BigInt"), and to [0,1) for floating point numbers; - Populate the array A with random values. If the indexable collection ``coll`` is specified, the values are picked randomly from ``coll``. This is equivalent to ``copy!(A, rand(rng, coll, size(A)))`` or ``copy!(A, rand(rng, eltype(A), size(A)))`` but without allocating a new array. + "S" defaults to "Float64". +.. function:: rand!([rng], A[, coll]) -.. function:: bitrand([rng][, dims...]) + Populate the array A with random values. If the indexable + collection "coll" is specified, the values are picked randomly + from "coll". This is equivalent to "copy!(A, rand(rng, coll, + size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but + without allocating a new array. - Generate a ``BitArray`` of random boolean values. +.. function:: bitrand([rng][, dims...]) + Generate a "BitArray" of random boolean values. .. function:: randn([rng][, dims...]) - Generate a normally-distributed random number with mean 0 and standard deviation 1. Optionally generate an array of normally- distributed random numbers. - + Generate a normally-distributed random number with mean 0 and + standard deviation 1. Optionally generate an array of normally- + distributed random numbers. .. function:: randn!([rng], A::Array{Float64, N}) - Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand function. - + Fill the array A with normally-distributed (mean 0, standard + deviation 1) random numbers. Also see the rand function. .. function:: randexp([rng][, dims...]) - Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. - + Generate a random number according to the exponential distribution + with scale 1. Optionally generate an array of such random numbers. .. function:: randexp!([rng], A::Array{Float64, N}) - Fill the array A with random numbers following the exponential distribution (with scale 1). - + Fill the array A with random numbers following the exponential + distribution (with scale 1). diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index ce12c1929a650..03a5844413af6 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -9,287 +9,396 @@ Tasks .. function:: Task(func) - Create a ``Task`` (i.e. thread, or coroutine) to execute the given function (which must be callable with no arguments). The task exits when this function returns. - + Create a "Task" (i.e. thread, or coroutine) to execute the given + function (which must be callable with no arguments). The task exits + when this function returns. .. function:: yieldto(task, arg = nothing) - Switch to the given task. The first time a task is switched to, the task's function is called with no arguments. On subsequent switches, ``arg`` is returned from the task's last call to considering states or scheduling in any way. Its use is discouraged. - + Switch to the given task. The first time a task is switched to, the + task's function is called with no arguments. On subsequent + switches, "arg" is returned from the task's last call to + "yieldto". This is a low-level call that only switches tasks, not + considering states or scheduling in any way. Its use is + discouraged. .. function:: current_task() - Get the currently running Task. - + Get the currently running Task. .. function:: istaskdone(task) -> Bool - Tell whether a task has exited. - + Tell whether a task has exited. .. function:: istaskstarted(task) -> Bool - Tell whether a task has started executing. - + Tell whether a task has started executing. .. function:: consume(task, values...) - Receive the next value passed to ``produce`` by the specified task. Additional arguments may be passed, to be returned from the last - + Receive the next value passed to "produce" by the specified task. + Additional arguments may be passed, to be returned from the last + "produce" call in the producer. .. function:: produce(value) - Send the given value to the last ``consume`` call, switching to the consumer task. If the next ``consume`` call passes any values, they are returned by ``produce``. - + Send the given value to the last "consume" call, switching to the + consumer task. If the next "consume" call passes any values, they + are returned by "produce". .. function:: yield() - Switch to the scheduler to allow another scheduled task to run. A task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. - + Switch to the scheduler to allow another scheduled task to run. A + task that calls this function is still runnable, and will be + restarted immediately if there are no other runnable tasks. .. function:: task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. - + Call the function "body" with a modified task-local storage, in + which "value" is assigned to "symbol"; the previous value of + "symbol", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. .. function:: task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. - + Call the function "body" with a modified task-local storage, in + which "value" is assigned to "symbol"; the previous value of + "symbol", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. .. function:: task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of emulating dynamic scoping. - + Call the function "body" with a modified task-local storage, in + which "value" is assigned to "symbol"; the previous value of + "symbol", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. .. function:: Condition() - Create an edge-triggered event source that tasks can wait for. Tasks that call ``wait`` on a ``Condition`` are suspended and queued. Tasks are woken up when ``notify`` is later called on the time ``notify`` is called can be woken up. For level-triggered notifications, you must keep extra state to keep track of whether a notification has happened. The ``RemoteRef`` type does this, and so can be used for level-triggered events. - + Create an edge-triggered event source that tasks can wait for. + Tasks that call "wait" on a "Condition" are suspended and + queued. Tasks are woken up when "notify" is later called on the + "Condition". Edge triggering means that only tasks waiting at the + time "notify" is called can be woken up. For level-triggered + notifications, you must keep extra state to keep track of whether a + notification has happened. The "RemoteRef" type does this, and so + can be used for level-triggered events. .. function:: notify(condition, val=nothing; all=true, error=false) - Wake up tasks waiting for a condition, passing them ``val``. If otherwise only one is. If ``error`` is true, the passed value is raised as an exception in the woken tasks. - + Wake up tasks waiting for a condition, passing them "val". If + "all" is true (the default), all waiting tasks are woken, + otherwise only one is. If "error" is true, the passed value is + raised as an exception in the woken tasks. .. function:: schedule(t::Task, [val]; error=false) - Add a task to the scheduler's queue. This causes the task to run constantly when the system is otherwise idle, unless the task performs a blocking operation such as ``wait``. If a second argument is provided, it will be passed to the task task. + Add a task to the scheduler's queue. This causes the task to run + constantly when the system is otherwise idle, unless the task + performs a blocking operation such as "wait". + If a second argument is provided, it will be passed to the task + (via the return value of "yieldto") when it runs again. If + "error" is true, the value is raised as an exception in the woken + task. .. function:: @schedule() - Wrap an expression in a Task and add it to the scheduler's queue. - + Wrap an expression in a Task and add it to the scheduler's queue. .. function:: @task() - Wrap an expression in a Task without executing it, and return the Task. This only creates a task, and does not run it. - + Wrap an expression in a Task without executing it, and return the + Task. This only creates a task, and does not run it. .. function:: sleep(seconds) - Block the current task for a specified number of seconds. The minimum sleep time is 1 millisecond or input of ``0.001``. - + Block the current task for a specified number of seconds. The + minimum sleep time is 1 millisecond or input of "0.001". .. function:: ReentrantLock() - Creates a reentrant lock. The same task can acquire the lock as many times as required. Each lock must be matched with an unlock. - + Creates a reentrant lock. The same task can acquire the lock as + many times as required. Each lock must be matched with an unlock. .. function:: lock(l::ReentrantLock) - Associates ``l`` with the current task. If ``l`` is already locked by a different task, waits for it to become available. The same task can acquire the lock multiple times. Each ``lock`` must be matched by an ``unlock`` - + Associates "l" with the current task. If "l" is already locked + by a different task, waits for it to become available. The same + task can acquire the lock multiple times. Each "lock" must be + matched by an "unlock" .. function:: unlock(l::ReentrantLock) - Releases ownership of the lock by the current task. If the lock had been acquired before, it just decrements an internal counter and returns immediately. - + Releases ownership of the lock by the current task. If the lock had + been acquired before, it just decrements an internal counter and + returns immediately. General Parallel Computing Support ---------------------------------- .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + Launches worker processes via the specified cluster manager. - The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. + For example Beowulf clusters are supported via a custom cluster + manager implemented in package "ClusterManagers". + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + "JULIA_WORKER_TIMEOUT" in the worker process's environment. + Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + Launches worker processes via the specified cluster manager. - The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. + For example Beowulf clusters are supported via a custom cluster + manager implemented in package "ClusterManagers". + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + "JULIA_WORKER_TIMEOUT" in the worker process's environment. + Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + Launches worker processes via the specified cluster manager. - The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. + For example Beowulf clusters are supported via a custom cluster + manager implemented in package "ClusterManagers". + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + "JULIA_WORKER_TIMEOUT" in the worker process's environment. + Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented in package ``ClusterManagers``. + Launches worker processes via the specified cluster manager. - The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. + For example Beowulf clusters are supported via a custom cluster + manager implemented in package "ClusterManagers". + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + "JULIA_WORKER_TIMEOUT" in the worker process's environment. + Relevant only when using TCP/IP as transport. .. function:: nprocs() - Get the number of available processes. - + Get the number of available processes. .. function:: nworkers() - Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. - + Get the number of available worker processes. This is one less than + nprocs(). Equal to nprocs() if nprocs() == 1. .. function:: procs(S::SharedArray) - Get the vector of processes that have mapped the shared array - + Get the vector of processes that have mapped the shared array .. function:: workers() - Returns a list of all worker process identifiers. - + Returns a list of all worker process identifiers. .. function:: rmprocs(pids...) - Removes the specified workers. - + Removes the specified workers. .. function:: interrupt([pids...]) - Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted. - + Interrupt the current executing task on the specified workers. This + is equivalent to pressing Ctrl-C on the local machine. If no + arguments are given, all workers are interrupted. .. function:: myid() - Get the id of the current process. - + Get the id of the current process. .. function:: pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - Transform collections ``lsts`` by applying ``f`` to each element in parallel. If ``nprocs() > 1``, the calling process will be dedicated to assigning tasks. All other available processes will be used as parallel workers, or on the processes specified by If ``err_retry`` is true, it retries a failed application of ``f`` on a different worker. If ``err_stop`` is true, it takes precedence over the value of ``err_retry`` and ``pmap`` stops execution on the first error. + Transform collections "lsts" by applying "f" to each element in + parallel. If "nprocs() > 1", the calling process will be + dedicated to assigning tasks. All other available processes will be + used as parallel workers, or on the processes specified by + "pids". + If "err_retry" is true, it retries a failed application of "f" + on a different worker. If "err_stop" is true, it takes precedence + over the value of "err_retry" and "pmap" stops execution on the + first error. .. function:: remotecall(id, func, args...) - Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. - + Call a function asynchronously on the given arguments on the + specified process. Returns a "RemoteRef". .. function:: wait([x]) - Block the current task until some event occurs, depending on the type of the argument: If no argument is passed, the task blocks for an undefined period. If the task's state is set to ``:waiting``, it can only be restarted by an explicit call to ``schedule`` or ``yieldto``. If the task's state is ``:runnable``, it might be restarted unpredictably. Often ``wait`` is called within a ``while`` loop to ensure a waited-for condition is met before proceeding. + Block the current task until some event occurs, depending on the + type of the argument: + * "RemoteRef": Wait for a value to become available for the + specified remote reference. -.. function:: fetch(RemoteRef) + * "Condition": Wait for "notify" on a condition. - Wait for and get the value of a remote reference. + * "Process": Wait for a process or process chain to exit. The + "exitcode" field of a process can be used to determine success + or failure. + * "Task": Wait for a "Task" to finish, returning its result + value. If the task fails with an exception, the exception is + propagated (re-thrown in the task that called "wait"). -.. function:: remotecall_wait(id, func, args...) + * "RawFD": Wait for changes on a file descriptor (see *poll_fd* + for keyword arguments and return code) - Perform ``wait(remotecall(...))`` in one message. + If no argument is passed, the task blocks for an undefined period. + If the task's state is set to ":waiting", it can only be + restarted by an explicit call to "schedule" or "yieldto". If + the task's state is ":runnable", it might be restarted + unpredictably. + Often "wait" is called within a "while" loop to ensure a + waited-for condition is met before proceeding. -.. function:: remotecall_fetch(id, func, args...) +.. function:: fetch(RemoteRef) - Perform ``fetch(remotecall(...))`` in one message. + Wait for and get the value of a remote reference. +.. function:: remotecall_wait(id, func, args...) -.. function:: put!(RemoteRef, value) + Perform "wait(remotecall(...))" in one message. - Store a value to a remote reference. Implements ``shared queue of length 1`` semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. +.. function:: remotecall_fetch(id, func, args...) + Perform "fetch(remotecall(...))" in one message. -.. function:: take!(RemoteRef) +.. function:: put!(RemoteRef, value) + + Store a value to a remote reference. Implements "shared queue of + length 1" semantics: if a value is already present, blocks until + the value is removed with "take!". Returns its first argument. - Fetch the value of a remote reference, removing it so that the reference is empty again. +.. function:: take!(RemoteRef) + Fetch the value of a remote reference, removing it so that the + reference is empty again. .. function:: isready(r::RemoteRef) - Determine whether a ``RemoteRef`` has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. It is recommended that this function only be used on a ``RemoteRef`` that is assigned once. If the argument ``RemoteRef`` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for ``r`` in a separate task instead, or to use a local + Determine whether a "RemoteRef" has a value stored to it. Note + that this function can cause race conditions, since by the time you + receive its result it may no longer be true. It is recommended that + this function only be used on a "RemoteRef" that is assigned + once. + If the argument "RemoteRef" is owned by a different node, this + call will block to wait for the answer. It is recommended to wait + for "r" in a separate task instead, or to use a local + "RemoteRef" as a proxy: -.. function:: RemoteRef(n) + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block - Make an uninitialized remote reference on process ``n``. +.. function:: RemoteRef(n) + Make an uninitialized remote reference on process "n". .. function:: RemoteRef(n) - Make an uninitialized remote reference on process ``n``. - + Make an uninitialized remote reference on process "n". .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - Waits till ``testcb`` returns ``true`` or for ``secs`` seconds, whichever is earlier. ``testcb`` is polled every ``pollint`` seconds. - + Waits till "testcb" returns "true" or for "secs`" seconds, + whichever is earlier. "testcb" is polled every "pollint" + seconds. .. function:: @spawn() - Execute an expression on an automatically-chosen process, returning a ``RemoteRef`` to the result. - + Execute an expression on an automatically-chosen process, returning + a "RemoteRef" to the result. .. function:: @spawnat() - Accepts two arguments, ``p`` and an expression, and runs the expression asynchronously on process ``p``, returning a - + Accepts two arguments, "p" and an expression, and runs the + expression asynchronously on process "p", returning a + "RemoteRef" to the result. .. function:: @fetch() - Equivalent to ``fetch(@spawn expr)``. - + Equivalent to "fetch(@spawn expr)". .. function:: @fetchfrom() - Equivalent to ``fetch(@spawnat p expr)``. - + Equivalent to "fetch(@spawnat p expr)". .. function:: @async() - Schedule an expression to run on the local machine, also adding it to the set of items that the nearest enclosing ``@sync`` waits for. - + Schedule an expression to run on the local machine, also adding it + to the set of items that the nearest enclosing "@sync" waits for. .. function:: @sync() - Wait until all dynamically-enclosed uses of ``@async``, ``@spawn``, - + Wait until all dynamically-enclosed uses of "@async", "@spawn", + "@spawnat" and "@parallel" are complete. .. function:: @parallel() - A parallel for loop of the form The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, reduction on the calling process. Note that without a reducer function, @parallel executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with ``@sync``, like + A parallel for loop of the form + + @parallel [reducer] for var = range + body + end + + The specified range is partitioned and locally executed across all + workers. In case an optional reducer function is specified, + @parallel performs local reductions on each worker with a final + reduction on the calling process. + Note that without a reducer function, @parallel executes + asynchronously, i.e. it spawns independent tasks on all available + workers and returns immediately without waiting for completion. To + wait for completion, prefix the call with "@sync", like + + @sync @parallel for var = range + body + end Shared Arrays (Experimental, UNIX-only feature) ----------------------------------------------- .. function:: SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - Construct a SharedArray of a bitstype ``T`` and size ``dims`` across the processes specified by ``pids`` - all of which have to be on the same host. If ``pids`` is left unspecified, the shared array will be mapped across all processes on the current host, including the master. But, ``localindexes`` and ``indexpids`` will only refer to worker processes. This facilitates work distribution code to use workers for actual computation with the master process acting as a driver. If an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, it is called on all the participating workers. + Construct a SharedArray of a bitstype "T" and size "dims" + across the processes specified by "pids" - all of which have to + be on the same host. + If "pids" is left unspecified, the shared array will be mapped + across all processes on the current host, including the master. + But, "localindexes" and "indexpids" will only refer to worker + processes. This facilitates work distribution code to use workers + for actual computation with the master process acting as a driver. -.. function:: procs(S::SharedArray) + If an "init" function of the type "initfn(S::SharedArray)" is + specified, it is called on all the participating workers. - Get the vector of processes that have mapped the shared array +.. function:: procs(S::SharedArray) + Get the vector of processes that have mapped the shared array .. function:: sdata(S::SharedArray) - Returns the actual ``Array`` object backing ``S`` - + Returns the actual "Array" object backing "S" .. function:: indexpids(S::SharedArray) - Returns the index of the current worker into the ``pids`` vector, i.e., the list of workers mapping the SharedArray - + Returns the index of the current worker into the "pids" vector, + i.e., the list of workers mapping the SharedArray Cluster Manager Interface ------------------------- @@ -300,28 +409,54 @@ Cluster Manager Interface .. function:: launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - Implemented by cluster managers. For every Julia worker launched by this function, it should append a ``WorkerConfig`` entry to once all workers, requested by ``manager`` have been launched. was called with. - + Implemented by cluster managers. For every Julia worker launched by + this function, it should append a "WorkerConfig" entry to + "launched" and notify "launch_ntfy". The function MUST exit + once all workers, requested by "manager" have been launched. + "params" is a dictionary of all keyword arguments "addprocs" + was called with. .. function:: manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - Implemented by cluster managers. It is called on the master process, during a worker's lifetime, with appropriate ``op`` values: + Implemented by cluster managers. It is called on the master + process, during a worker's lifetime, with appropriate "op" + values: + * with ":register"/":deregister" when a worker is added / + removed from the Julia worker pool. -.. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) + * with ":interrupt" when "interrupt(workers)" is called. + The "ClusterManager" should signal the appropriate worker + with an interrupt signal. - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. + * with ":finalize" for cleanup purposes. +.. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) -.. function:: init_worker(manager::FooManager) + Implemented by cluster managers. It is called on the master + process, by "rmprocs". It should cause the remote worker + specified by "pid" to exit. + "Base.kill(manager::ClusterManager.....)" executes a remote + "exit()" on "pid" - Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets for transport. +.. function:: init_worker(manager::FooManager) + Called by cluster managers implementing custom transports. It + initializes a newly launched process as a worker. Command line + argument "--worker" has the effect of initializing a process as a + worker using TCP/IP sockets for transport. .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off messages are delivered and received completely and in order. socket connections in-between workers. - + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id "pid", specified + by "config" and return a pair of "AsyncStream" objects. + Messages from "pid" to current process will be read off + "instrm", while messages to be sent to "pid" will be written to + "outstrm". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + "Base.connect(manager::ClusterManager.....)" sets up TCP/IP + socket connections in-between workers. .. function:: Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index bc606244aa15c..63bb29c76e59f 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -9,138 +9,177 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, .. function:: dir(names...) -> AbstractString - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. - + Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends + path components to the package directory and normalizes the + resulting path. In particular, "Pkg.dir(pkg)" returns the path to + the package "pkg". .. function:: dir(names...) -> AbstractString - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. - + Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends + path components to the package directory and normalizes the + resulting path. In particular, "Pkg.dir(pkg)" returns the path to + the package "pkg". .. function:: init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - Initialize ``Pkg.dir()`` as a package directory. This will be done automatically when the ``JULIA_PKGDIR`` is not set and clones a local METADATA git repository from the site and branch specified by its arguments, which are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. - + Initialize "Pkg.dir()" as a package directory. This will be done + automatically when the "JULIA_PKGDIR" is not set and + "Pkg.dir()" uses its default value. As part of this process, + clones a local METADATA git repository from the site and branch + specified by its arguments, which are typically not provided. + Explicit (non-default) arguments can be used to support a custom + METADATA setup. .. function:: resolve() - Determines an optimal, consistent set of package versions to install or upgrade to. The optimal set of package versions is based on the contents of ``Pkg.dir(``REQUIRE``)`` and the state of installed packages in ``Pkg.dir()``, Packages that are no longer required are moved into ``Pkg.dir(``.trash``)``. - + Determines an optimal, consistent set of package versions to + install or upgrade to. The optimal set of package versions is based + on the contents of "Pkg.dir("REQUIRE")" and the state of + installed packages in "Pkg.dir()", Packages that are no longer + required are moved into "Pkg.dir(".trash")". .. function:: edit() - Opens ``Pkg.dir(``REQUIRE``)`` in the editor specified by the command returns, it runs ``Pkg.resolve()`` to determine and install a new optimal set of installed package versions. - + Opens "Pkg.dir("REQUIRE")" in the editor specified by the + "VISUAL" or "EDITOR" environment variables; when the editor + command returns, it runs "Pkg.resolve()" to determine and install + a new optimal set of installed package versions. .. function:: add(pkg, vers...) - Add a requirement entry for ``pkg`` to ``Pkg.dir(``REQUIRE``)`` and call ``Pkg.resolve()``. If ``vers`` are given, they must be intervals for ``pkg``. - + Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and + call "Pkg.resolve()". If "vers" are given, they must be + "VersionNumber" objects and they specify acceptable version + intervals for "pkg". .. function:: rm(pkg) - Remove all requirement entries for ``pkg`` from - + Remove all requirement entries for "pkg" from + "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". .. function:: clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. - + If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone + it from that URL on the default branch. The package does not need + to have any registered versions. .. function:: clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir(``METADATA``)``, clone it from that URL on the default branch. The package does not need to have any registered versions. - + If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone + it from that URL on the default branch. The package does not need + to have any registered versions. .. function:: available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package ``pkg``. - + Returns the version numbers available for package "pkg". .. function:: available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package ``pkg``. - + Returns the version numbers available for package "pkg". .. function:: installed(pkg) -> Void | VersionNumber - If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. - + If "pkg" is installed, return the installed version number, + otherwise return "nothing". .. function:: installed(pkg) -> Void | VersionNumber - If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. - + If "pkg" is installed, return the installed version number, + otherwise return "nothing". .. function:: status() - Prints out a summary of what packages are installed and what version and state they're in. - + Prints out a summary of what packages are installed and what + version and state they're in. .. function:: update() - Update package the metadata repo – kept in safely be pulled from their origin; then call ``Pkg.resolve()`` to determine a new optimal set of packages versions. - + Update package the metadata repo – kept in + "Pkg.dir("METADATA")" – then update any fixed packages that can + safely be pulled from their origin; then call "Pkg.resolve()" to + determine a new optimal set of packages versions. .. function:: checkout(pkg[, branch="master"]) - Checkout the ``Pkg.dir(pkg)`` repo to the branch ``branch``. Defaults to checking out the ``master`` branch. To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` - + Checkout the "Pkg.dir(pkg)" repo to the branch "branch". + Defaults to checking out the "master" branch. To go back to using + the newest compatible released version, use "Pkg.free(pkg)" .. function:: pin(pkg, version) - Pin ``pkg`` at registered version ``version``. - + Pin "pkg" at registered version "version". .. function:: pin(pkg, version) - Pin ``pkg`` at registered version ``version``. - + Pin "pkg" at registered version "version". .. function:: free(pkg) - Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and - - You can also supply an iterable collection of package names, e.g., ``Pkg.free(("Pkg1", "Pkg2"))`` to free multiple packages at once. + Free the package "pkg" to be managed by the package manager + again. It calls "Pkg.resolve()" to determine optimal package + versions after. This is an inverse for both "Pkg.checkout" and + "Pkg.pin". + You can also supply an iterable collection of package names, e.g., + "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at + once. .. function:: build(pkgs...) - Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. - + Run the build script in "deps/build.jl" for each package in + "pkgs" and all of their dependencies in depth-first recursive + order. This is called automatically by "Pkg.resolve()" on all + installed or updated packages. .. function:: build(pkgs...) - Run the build script in ``deps/build.jl`` for each package in order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. - + Run the build script in "deps/build.jl" for each package in + "pkgs" and all of their dependencies in depth-first recursive + order. This is called automatically by "Pkg.resolve()" on all + installed or updated packages. .. function:: generate(pkg, license) - Generate a new package named ``pkg`` with one of these license keys: ``MIT``, ``BSD`` or ``ASL``. If you want to make a package with a different license, you can edit it afterwards. Generate creates a git repo at ``Pkg.dir(pkg)`` for the package and inside it ``LICENSE.md``, ``README.md``, the julia entrypoint - + Generate a new package named "pkg" with one of these license + keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make + a package with a different license, you can edit it afterwards. + Generate creates a git repo at "Pkg.dir(pkg)" for the package and + inside it "LICENSE.md", "README.md", the julia entrypoint + "\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". .. function:: register(pkg[, url]) - Register ``pkg`` at the git URL ``url``, defaulting to the configured origin URL of the git repo ``Pkg.dir(pkg)``. - + Register "pkg" at the git URL "url", defaulting to the + configured origin URL of the git repo "Pkg.dir(pkg)". .. function:: tag(pkg[, ver[, commit]]) - Tag ``commit`` as version ``ver`` of package ``pkg`` and create a version entry in ``METADATA``. If not provided, ``commit`` defaults to the current commit of the ``pkg`` repo. If ``ver`` is one of the symbols ``:patch``, ``:minor``, ``:major`` the next patch, minor or major version is used. If ``ver`` is not provided, it defaults to - + Tag "commit" as version "ver" of package "pkg" and create a + version entry in "METADATA". If not provided, "commit" defaults + to the current commit of the "pkg" repo. If "ver" is one of the + symbols ":patch", ":minor", ":major" the next patch, minor or + major version is used. If "ver" is not provided, it defaults to + ":patch". .. function:: publish() - For each new package version tagged in ``METADATA`` not already published, make sure that the tagged package commits have been pushed to the repo at the registered URL for the package and if they all have, open a pull request to ``METADATA``. - + For each new package version tagged in "METADATA" not already + published, make sure that the tagged package commits have been + pushed to the repo at the registered URL for the package and if + they all have, open a pull request to "METADATA". .. function:: test(pkgs...) - Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. - + Run the tests for each package in "pkgs" ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its "test/runtests.jl" file + and test dependencies are specified in "test/REQUIRE". .. function:: test(pkgs...) - Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. - + Run the tests for each package in "pkgs" ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its "test/runtests.jl" file + and test dependencies are specified in "test/REQUIRE". diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 4e11d1152943f..517c1cddaae03 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -10,49 +10,76 @@ .. function:: @profile() - periodic backtraces. These are appended to an internal buffer of backtraces. - + "@profile " runs your expression while taking + periodic backtraces. These are appended to an internal buffer of + backtraces. .. currentmodule:: Base.Profile The methods in :mod:`Base.Profile` are not exported and need to be called e.g. as ``Profile.print()``. .. function:: clear() - Clear any existing backtraces from the internal buffer. - + Clear any existing backtraces from the internal buffer. .. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. - + Prints profiling results to "io". This variant is used to examine + results exported by a previous call to "retrieve()". Supply the + vector "data" of backtraces and a dictionary "lidict" of line + information. .. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to ``retrieve()``. Supply the vector ``data`` of backtraces and a dictionary ``lidict`` of line information. - + Prints profiling results to "io". This variant is used to examine + results exported by a previous call to "retrieve()". Supply the + vector "data" of backtraces and a dictionary "lidict" of line + information. .. function:: init(; n::Integer, delay::Float64) - Configure the ``delay`` between backtraces (measured in seconds), and the number ``n`` of instruction pointers that may be stored. Each instruction pointer corresponds to a single line of code; backtraces generally consist of a long list of instruction pointers. Default settings can be obtained by calling this function with no arguments, and each can be set independently using keywords or in the order ``(n, delay)``. - + Configure the "delay" between backtraces (measured in seconds), + and the number "n" of instruction pointers that may be stored. + Each instruction pointer corresponds to a single line of code; + backtraces generally consist of a long list of instruction + pointers. Default settings can be obtained by calling this function + with no arguments, and each can be set independently using keywords + or in the order "(n, delay)". .. function:: fetch() -> data - Returns a reference to the internal buffer of backtraces. Note that subsequent operations, like ``clear()``, can affect ``data`` unless you first make a copy. Note that the values in ``data`` have meaning only on this machine in the current session, because it depends on the exact memory addresses used in JIT-compiling. This function is primarily for internal use; ``retrieve()`` may be a better choice for most users. - + Returns a reference to the internal buffer of backtraces. Note that + subsequent operations, like "clear()", can affect "data" unless + you first make a copy. Note that the values in "data" have + meaning only on this machine in the current session, because it + depends on the exact memory addresses used in JIT-compiling. This + function is primarily for internal use; "retrieve()" may be a + better choice for most users. .. function:: retrieve() -> data, lidict - set of all backtraces (``data``) and a dictionary that maps the values that store the file name, function name, and line number. This function allows you to save profiling results for future analysis. - + "Exports" profiling results in a portable format, returning the + set of all backtraces ("data") and a dictionary that maps the + (session-specific) instruction pointers in "data" to "LineInfo" + values that store the file name, function name, and line number. + This function allows you to save profiling results for future + analysis. .. function:: callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - Given a previous profiling run, determine who called a particular function. Supplying the filename (and optionally, range of line numbers over which the function is defined) allows you to disambiguate an overloaded method. The returned value is a vector containing a count of the number of calls and line information about the caller. One can optionally supply backtrace data obtained from ``retrieve()``; otherwise, the current internal profile buffer is used. - + Given a previous profiling run, determine who called a particular + function. Supplying the filename (and optionally, range of line + numbers over which the function is defined) allows you to + disambiguate an overloaded method. The returned value is a vector + containing a count of the number of calls and line information + about the caller. One can optionally supply backtrace data + obtained from "retrieve()"; otherwise, the current internal + profile buffer is used. .. function:: clear_malloc_data() - Clears any stored memory allocation data when running julia with ` force JIT-compilation), then call ``clear_malloc_data()``. Then execute your command(s) again, quit Julia, and examine the resulting ``*.mem`` files. - + Clears any stored memory allocation data when running julia with " + --track-allocation". Execute the command(s) you want to test (to + force JIT-compilation), then call "clear_malloc_data()". Then + execute your command(s) again, quit Julia, and examine the + resulting "*.mem" files. diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 9a73bc3f9589c..5f6c96b57edeb 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -119,71 +119,103 @@ Sorting Functions .. function:: sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the vector ``v`` in place. ``QuickSort`` is used by default for numeric arrays while ``MergeSort`` is used for other arrays. You can specify an algorithm to use via the ``alg`` keyword (see Sorting Algorithms for available algorithms). The ``by`` keyword lets you provide a function that will be applied to each element before comparison; the ``lt`` keyword allows providing a custom order. These options are independent and can be used together in all possible combinations: if both ``by`` and ``lt`` are specified, the ``lt`` function is applied to the result of the ``by`` function; ``rev=true`` reverses whatever ordering specified via the - + Sort the vector "v" in place. "QuickSort" is used by default + for numeric arrays while "MergeSort" is used for other arrays. + You can specify an algorithm to use via the "alg" keyword (see + Sorting Algorithms for available algorithms). The "by" keyword + lets you provide a function that will be applied to each element + before comparison; the "lt" keyword allows providing a custom + "less than" function; use "rev=true" to reverse the sorting + order. These options are independent and can be used together in + all possible combinations: if both "by" and "lt" are specified, + the "lt" function is applied to the result of the "by" + function; "rev=true" reverses whatever ordering specified via the + "by" and "lt" keywords. .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array ``A`` along the given dimension. - + Sort a multidimensional array "A" along the given dimension. .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array ``A`` along the given dimension. - + Sort a multidimensional array "A" along the given dimension. .. function:: sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - Return a permutation vector of indices of ``v`` that puts it in sorted order. Specify ``alg`` to choose a particular sorting algorithm (see Sorting Algorithms). ``MergeSort`` is used by default, and since it is stable, the resulting permutation will be the lexicographically first one that puts the input array into sorted order – i.e. indices of equal elements appear in ascending order. If you choose a non-stable sorting algorithm such as order may be returned. The order is specified using the same keywords as ``sort!``. See also ``sortperm!()`` + Return a permutation vector of indices of "v" that puts it in + sorted order. Specify "alg" to choose a particular sorting + algorithm (see Sorting Algorithms). "MergeSort" is used by + default, and since it is stable, the resulting permutation will be + the lexicographically first one that puts the input array into + sorted order – i.e. indices of equal elements appear in ascending + order. If you choose a non-stable sorting algorithm such as + "QuickSort", a different permutation that puts the array into + order may be returned. The order is specified using the same + keywords as "sort!". + See also "sortperm!()" .. function:: sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - Like ``sortperm``, but accepts a preallocated index vector ``ix``. If ``initialized`` is ``false`` (the default), ix is initialized to contain the values ``1:length(v)``. See also ``sortperm()`` + Like "sortperm", but accepts a preallocated index vector "ix". + If "initialized" is "false" (the default), ix is initialized to + contain the values "1:length(v)". + See also "sortperm()" .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the rows of matrix ``A`` lexicographically. - + Sort the rows of matrix "A" lexicographically. .. function:: sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the columns of matrix ``A`` lexicographically. - + Sort the columns of matrix "A" lexicographically. Order-Related Functions ----------------------- .. function:: issorted(v, [by=,] [lt=,] [rev=false]) - Test whether a vector is in sorted order. The ``by``, ``lt`` and as they do for ``sort``. - + Test whether a vector is in sorted order. The "by", "lt" and + "rev" keywords modify what order is considered to be sorted just + as they do for "sort". .. function:: searchsorted(a, x, [by=,] [lt=,] [rev=false]) - Returns the range of indices of ``a`` which compare as equal to order. Returns an empty range located at the insertion point if - + Returns the range of indices of "a" which compare as equal to + "x" according to the order specified by the "by", "lt" and + "rev" keywords, assuming that "a" is already sorted in that + order. Returns an empty range located at the insertion point if + "a" does not contain values equal to "x". .. function:: searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the first value in ``a`` greater than or equal to ``x``, according to the specified order. Returns ``length(a)+1`` if ``x`` is greater than all values in ``a``. - + Returns the index of the first value in "a" greater than or equal + to "x", according to the specified order. Returns "length(a)+1" + if "x" is greater than all values in "a". .. function:: searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the last value in ``a`` less than or equal to less than all values in ``a``. - + Returns the index of the last value in "a" less than or equal to + "x", according to the specified order. Returns "0" if "x" is + less than all values in "a". .. function:: select!(v, k, [by=,] [lt=,] [rev=false]) - Partially sort the vector ``v`` in place, according to the order specified by ``by``, ``lt`` and ``rev`` so that the value at index the position where it would appear if the array were fully sorted via a non-stable algorithm. If ``k`` is a single index, that value is returned; if ``k`` is a range, an array of values at those indices is returned. Note that ``select!`` does not fully sort the input array. - + Partially sort the vector "v" in place, according to the order + specified by "by", "lt" and "rev" so that the value at index + "k" (or range of adjacent values if "k" is a range) occurs at + the position where it would appear if the array were fully sorted + via a non-stable algorithm. If "k" is a single index, that value + is returned; if "k" is a range, an array of values at those + indices is returned. Note that "select!" does not fully sort the + input array. .. function:: select(v, k, [by=,] [lt=,] [rev=false]) - Variant of ``select!`` which copies ``v`` before partially sorting it, thereby returning the same thing as ``select!`` but leaving - + Variant of "select!" which copies "v" before partially sorting + it, thereby returning the same thing as "select!" but leaving + "v" unmodified. Sorting Algorithms ------------------ diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index 79d994b6cebf3..06a5104e0c3fc 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,374 +6,487 @@ .. function:: length(s) - The number of characters in string ``s``. - + The number of characters in string "s". .. function:: sizeof(s::AbstractString) - The number of bytes in string ``s``. - + The number of bytes in string "s". .. function:: *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. + Concatenate strings. The "*" operator is an alias to this + function. + julia> "Hello " * "world" + "Hello world" julia> "Hello " * "world" "Hello world" .. function:: ^(s, n) - Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. + Repeat "n" times the string "s". The "^" operator is an alias + to this function. + julia> "Test "^3 + "Test Test Test " .. function:: string(xs...) - Create a string from any values using the ``print`` function. - + Create a string from any values using the "print" function. .. function:: repr(x) - Create a string from any value using the ``showall`` function. - + Create a string from any value using the "showall" function. .. function:: bytestring(s) - Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. - + Convert a string to a contiguous byte array representation + appropriate for passing it to C functions. The string will be + encoded as either ASCII or UTF-8. .. function:: bytestring(s) - Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. - + Convert a string to a contiguous byte array representation + appropriate for passing it to C functions. The string will be + encoded as either ASCII or UTF-8. .. function:: ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. + +.. function:: ascii(::Ptr{UInt8}[, length]) + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. .. function:: ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If "length" is specified, the string does not have to be + 0-terminated. +.. function:: utf8(s) -.. function:: ascii(::Ptr{UInt8}[, length]) + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). - Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. +.. function:: utf8(s) + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). .. function:: utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). +.. function:: normalize_string(s, normalform::Symbol) -.. function:: utf8(s) + Normalize the string "s" according to one of the four "normal + forms" of the Unicode standard: "normalform" can be ":NFC", + ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical + composition) and D (canonical decomposition) convert different + visually identical representations of the same abstract string into + a single canonical form, with form C being more compact. Normal + forms KC and KD additionally canonicalize "compatibility + equivalents": they convert characters that are abstractly similar + but visually distinct into a single canonical choice (e.g. they + expand ligatures into the individual characters), with form KC + being more compact. - Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + Alternatively, finer control and additional transformations may be + be obtained by calling *normalize_string(s; keywords...)*, where + any number of the following boolean keywords options (which all + default to "false" except for "compose") are specified: + * "compose=false": do not perform canonical composition -.. function:: utf8(s) + * "decompose=true": do canonical decomposition instead of + canonical composition ("compose=true" is ignored if present) - Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + * "compat=true": compatibility equivalents are canonicalized + * "casefold=true": perform Unicode case folding, e.g. for case- + insensitive string comparison -.. function:: normalize_string(s, normalform::Symbol) + * "newline2lf=true", "newline2ls=true", or + "newline2ps=true": convert various newline sequences (LF, CRLF, + CR, NEL) into a linefeed (LF), line-separation (LS), or + paragraph-separation (PS) character, respectively - Normalize the string ``s`` according to one of the four ``normal forms`` of the Unicode standard: ``normalform`` can be ``:NFC``, composition) and D (canonical decomposition) convert different visually identical representations of the same abstract string into a single canonical form, with form C being more compact. Normal forms KC and KD additionally canonicalize ``compatibility equivalents``: they convert characters that are abstractly similar but visually distinct into a single canonical choice (e.g. they expand ligatures into the individual characters), with form KC being more compact. Alternatively, finer control and additional transformations may be be obtained by calling *normalize_string(s; keywords...)*, where any number of the following boolean keywords options (which all default to ``false`` except for ``compose``) are specified: For example, NFKC corresponds to the options ``compose=true, compat=true, stable=true``. + * "stripmark=true": strip diacritical marks (e.g. accents) + * "stripignore=true": strip Unicode's "default ignorable" + characters (e.g. the soft hyphen or the left-to-right marker) -.. function:: graphemes(s) -> iterator over substrings of s + * "stripcc=true": strip control characters; horizontal tabs and + form feeds are converted to spaces; newlines are also converted + to spaces unless a newline-conversion flag was specified - Returns an iterator over substrings of ``s`` that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) + * "rejectna=true": throw an error if unassigned code points are + found + * "stable=true": enforce Unicode Versioning Stability -.. function:: isvalid(str, i) + For example, NFKC corresponds to the options "compose=true, + compat=true, stable=true". - Tells whether index ``i`` is valid for the given string +.. function:: graphemes(s) -> iterator over substrings of s + Returns an iterator over substrings of "s" that correspond to the + extended graphemes in the string, as defined by Unicode UAX #29. + (Roughly, these are what users would perceive as single characters, + even though they may contain more than one codepoint; for example a + letter combined with an accent mark is a single grapheme.) .. function:: isvalid(str, i) - Tells whether index ``i`` is valid for the given string + Tells whether index "i" is valid for the given string + +.. function:: isvalid(str, i) + Tells whether index "i" is valid for the given string .. function:: is_assigned_char(c) -> Bool - Returns true if the given char or integer is an assigned Unicode code point. - + Returns true if the given char or integer is an assigned Unicode + code point. .. function:: ismatch(r::Regex, s::AbstractString) -> Bool - Test whether a string contains a match of the given regular expression. - + Test whether a string contains a match of the given regular + expression. .. function:: match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - Search for the first match of the regular expression ``r`` in ``s`` and return a RegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessing ``m.match`` and the captured sequences can be retrieved by accessing ``m.captures`` The optional ``idx`` argument specifies an index at which to start the search. - + Search for the first match of the regular expression "r" in "s" + and return a RegexMatch object containing the match, or nothing if + the match failed. The matching substring can be retrieved by + accessing "m.match" and the captured sequences can be retrieved + by accessing "m.captures" The optional "idx" argument specifies + an index at which to start the search. .. function:: eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - Search for all matches of a the regular expression ``r`` in ``s`` and return a iterator over the matches. If overlap is true, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges. - + Search for all matches of a the regular expression "r" in "s" + and return a iterator over the matches. If overlap is true, the + matching sequences are allowed to overlap indices in the original + string, otherwise they must be from distinct character ranges. .. function:: matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - Return a vector of the matching substrings from eachmatch. - + Return a vector of the matching substrings from eachmatch. .. function:: lpad(string, n, p) - Make a string at least ``n`` columns wide when printed, by padding on the left with copies of ``p``. - + Make a string at least "n" columns wide when printed, by padding + on the left with copies of "p". .. function:: rpad(string, n, p) - Make a string at least ``n`` columns wide when printed, by padding on the right with copies of ``p``. - + Make a string at least "n" columns wide when printed, by padding + on the right with copies of "p". .. function:: search(string, chars[, start]) - Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that ``s[search(s,x)] == x``: + Search for the first occurrence of the given characters within the + given string. The second argument may be a single character, a + vector or a set of characters, a string, or a regular expression + (though regular expressions are only allowed on contiguous strings, + such as ASCII or UTF-8 strings). The third argument optionally + specifies a starting index. The return value is a range of indexes + where the matching sequence is found, such that "s[search(s,x)] == + x": + "search(string, "substring")" = "start:end" such that + "string[start:end] == "substring"", or "0:-1" if unmatched. -.. function:: rsearch(string, chars[, start]) + "search(string, 'c')" = "index" such that + "string[index] == 'c'", or "0" if unmatched. - Similar to ``search``, but returning the last occurrence of the given characters within the given string, searching in reverse from +.. function:: rsearch(string, chars[, start]) + Similar to "search", but returning the last occurrence of the + given characters within the given string, searching in reverse from + "start". .. function:: searchindex(string, substring[, start]) - Similar to ``search``, but return only the start index at which the substring is found, or 0 if it is not. - + Similar to "search", but return only the start index at which the + substring is found, or 0 if it is not. .. function:: rsearchindex(string, substring[, start]) - Similar to ``rsearch``, but return only the start index at which the substring is found, or 0 if it is not. - + Similar to "rsearch", but return only the start index at which + the substring is found, or 0 if it is not. .. function:: contains(haystack, needle) - Determine whether the second argument is a substring of the first. - + Determine whether the second argument is a substring of the first. .. function:: replace(string, pat, r[, n]) - Search for the given pattern ``pat``, and replace each occurrence with ``r``. If ``n`` is provided, replace at most ``n`` occurrences. As with search, the second argument may be a single character, a vector or a set of characters, a string, or a regular expression. If ``r`` is a function, each occurrence is replaced with ``r(s)`` where ``s`` is the matched substring. - + Search for the given pattern "pat", and replace each occurrence + with "r". If "n" is provided, replace at most "n" + occurrences. As with search, the second argument may be a single + character, a vector or a set of characters, a string, or a regular + expression. If "r" is a function, each occurrence is replaced + with "r(s)" where "s" is the matched substring. .. function:: split(string, [chars]; limit=0, keep=true) - Return an array of substrings by splitting the given string on occurrences of the given character delimiters, which may be specified in any of the formats allowed by ``search``'s second argument (i.e. a single character, collection of characters, string, or regular expression). If ``chars`` is omitted, it defaults to the set of all space characters, and ``keep`` is taken to be false. The two keyword arguments are optional: they are are a maximum size for the result and a flag determining whether empty fields should be kept in the result. - + Return an array of substrings by splitting the given string on + occurrences of the given character delimiters, which may be + specified in any of the formats allowed by "search"'s second + argument (i.e. a single character, collection of characters, + string, or regular expression). If "chars" is omitted, it + defaults to the set of all space characters, and "keep" is taken + to be false. The two keyword arguments are optional: they are are a + maximum size for the result and a flag determining whether empty + fields should be kept in the result. .. function:: rsplit(string, [chars]; limit=0, keep=true) - Similar to ``split``, but starting from the end of the string. - + Similar to "split", but starting from the end of the string. .. function:: strip(string[, chars]) - Return ``string`` with any leading and trailing whitespace removed. If ``chars`` (a character, or vector or set of characters) is provided, instead remove characters contained in it. - + Return "string" with any leading and trailing whitespace removed. + If "chars" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. .. function:: lstrip(string[, chars]) - Return ``string`` with any leading whitespace removed. If ``chars`` remove characters contained in it. - + Return "string" with any leading whitespace removed. If "chars" + (a character, or vector or set of characters) is provided, instead + remove characters contained in it. .. function:: rstrip(string[, chars]) - Return ``string`` with any trailing whitespace removed. If provided, instead remove characters contained in it. - + Return "string" with any trailing whitespace removed. If + "chars" (a character, or vector or set of characters) is + provided, instead remove characters contained in it. .. function:: startswith(string, prefix | chars) - Returns ``true`` if ``string`` starts with ``prefix``. If the second argument is a vector or set of characters, tests whether the first character of ``string`` belongs to that set. - + Returns "true" if "string" starts with "prefix". If the + second argument is a vector or set of characters, tests whether the + first character of "string" belongs to that set. .. function:: endswith(string, suffix | chars) - Returns ``true`` if ``string`` ends with ``suffix``. If the second argument is a vector or set of characters, tests whether the last character of ``string`` belongs to that set. - + Returns "true" if "string" ends with "suffix". If the second + argument is a vector or set of characters, tests whether the last + character of "string" belongs to that set. .. function:: uppercase(string) - Returns ``string`` with all characters converted to uppercase. - + Returns "string" with all characters converted to uppercase. .. function:: lowercase(string) - Returns ``string`` with all characters converted to lowercase. - + Returns "string" with all characters converted to lowercase. .. function:: ucfirst(string) - Returns ``string`` with the first character converted to uppercase. - + Returns "string" with the first character converted to uppercase. .. function:: lcfirst(string) - Returns ``string`` with the first character converted to lowercase. - + Returns "string" with the first character converted to lowercase. .. function:: join(strings, delim[, last]) - Join an array of ``strings`` into a single string, inserting the given delimiter between adjacent strings. If ``last`` is given, it will be used instead of ``delim`` between the last two strings. For example, ``join([``apples``, `bananas``, ``pineapples``], ``, `, convertible to strings via `print(io::IOBuffer, x)``. + Join an array of "strings" into a single string, inserting the + given delimiter between adjacent strings. If "last" is given, it + will be used instead of "delim" between the last two strings. For + example, "join(["apples", "bananas", "pineapples"], ", ", + " and ") == "apples, bananas and pineapples"". + "strings" can be any iterable over elements "x" which are + convertible to strings via "print(io::IOBuffer, x)". .. function:: chop(string) - Remove the last character from a string - + Remove the last character from a string .. function:: chomp(string) - Remove a trailing newline from a string - + Remove a trailing newline from a string .. function:: ind2chr(string, i) - Convert a byte index to a character index - + Convert a byte index to a character index .. function:: chr2ind(string, i) - Convert a character index to a byte index - + Convert a character index to a byte index .. function:: isvalid(str, i) - Tells whether index ``i`` is valid for the given string - + Tells whether index "i" is valid for the given string .. function:: nextind(str, i) - Get the next valid string index after ``i``. Returns a value greater than ``endof(str)`` at or after the end of the string. - + Get the next valid string index after "i". Returns a value + greater than "endof(str)" at or after the end of the string. .. function:: prevind(str, i) - Get the previous valid string index before ``i``. Returns a value less than ``1`` at the beginning of the string. - + Get the previous valid string index before "i". Returns a value + less than "1" at the beginning of the string. .. function:: randstring([rng], len=8) - Create a random ASCII string of length ``len``, consisting of upper- and lower-case letters and the digits 0-9. The optional Numbers*. - + Create a random ASCII string of length "len", consisting of + upper- and lower-case letters and the digits 0-9. The optional + "rng" argument specifies a random number generator, see *Random + Numbers*. .. function:: charwidth(c) - Gives the number of columns needed to print a character. - + Gives the number of columns needed to print a character. .. function:: strwidth(s) - Gives the number of columns needed to print a string. - + Gives the number of columns needed to print a string. .. function:: isalnum(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphanumeric, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter or Number, i.e. a character whose category code begins with 'L' or - + Tests whether a character is alphanumeric, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter or + Number, i.e. a character whose category code begins with 'L' or + 'N'. .. function:: isalpha(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphabetic, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'. - + Tests whether a character is alphabetic, or whether this is true + for all elements of a string. A character is classified as + alphabetic if it belongs to the Unicode general category Letter, + i.e. a character whose category code begins with 'L'. .. function:: isascii(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the ASCII character set, or whether this is true for all elements of a string. - + Tests whether a character belongs to the ASCII character set, or + whether this is true for all elements of a string. .. function:: iscntrl(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a control character, or whether this is true for all elements of a string. Control characters are the non-printing characters of the Latin-1 subset of Unicode. - + Tests whether a character is a control character, or whether this + is true for all elements of a string. Control characters are the + non-printing characters of the Latin-1 subset of Unicode. .. function:: isdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a numeric digit (0-9), or whether this is true for all elements of a string. - + Tests whether a character is a numeric digit (0-9), or whether this + is true for all elements of a string. .. function:: isgraph(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, and not a space, or whether this is true for all elements of a string. Any character that would cause a printer to use ink should be classified with isgraph(c)==true. - + Tests whether a character is printable, and not a space, or whether + this is true for all elements of a string. Any character that + would cause a printer to use ink should be classified with + isgraph(c)==true. .. function:: islower(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a lowercase letter, or whether this is true for all elements of a string. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase. - + Tests whether a character is a lowercase letter, or whether this is + true for all elements of a string. A character is classified as + lowercase if it belongs to Unicode category Ll, Letter: Lowercase. .. function:: isnumber(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is numeric, or whether this is true for all elements of a string. A character is classified as numeric if it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'. - + Tests whether a character is numeric, or whether this is true for + all elements of a string. A character is classified as numeric if + it belongs to the Unicode general category Number, i.e. a character + whose category code begins with 'N'. .. function:: isprint(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, including spaces, but not a control character. For strings, tests whether this is true for all elements of the string. - + Tests whether a character is printable, including spaces, but not a + control character. For strings, tests whether this is true for all + elements of the string. .. function:: ispunct(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the Unicode general category Punctuation, i.e. a character whose category code begins with 'P'. For strings, tests whether this is true for all elements of the string. - + Tests whether a character belongs to the Unicode general category + Punctuation, i.e. a character whose category code begins with 'P'. + For strings, tests whether this is true for all elements of the + string. .. function:: isspace(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is any whitespace character. Includes ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs. For strings, tests whether this is true for all elements of the string. - + Tests whether a character is any whitespace character. Includes + ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', + Latin-1 character U+0085, and characters in Unicode category Zs. + For strings, tests whether this is true for all elements of the + string. .. function:: isupper(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is an uppercase letter, or whether this is true for all elements of a string. A character is classified as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. - + Tests whether a character is an uppercase letter, or whether this + is true for all elements of a string. A character is classified + as uppercase if it belongs to Unicode category Lu, Letter: + Uppercase, or Lt, Letter: Titlecase. .. function:: isxdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a valid hexadecimal digit, or whether this is true for all elements of a string. - + Tests whether a character is a valid hexadecimal digit, or whether + this is true for all elements of a string. .. function:: symbol(x...) -> Symbol - Create a ``Symbol`` by concatenating the string representations of the arguments together. - + Create a "Symbol" by concatenating the string representations of + the arguments together. .. function:: escape_string(str::AbstractString) -> AbstractString - General escaping of traditional C and Unicode escape sequences. See - + General escaping of traditional C and Unicode escape sequences. See + "print_escaped()" for more general escaping. .. function:: unescape_string(s::AbstractString) -> AbstractString - General unescaping of traditional C and Unicode escape sequences. Reverse of ``escape_string()``. See also ``print_unescaped()``. - + General unescaping of traditional C and Unicode escape sequences. + Reverse of "escape_string()". See also "print_unescaped()". .. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. - + Create a string from the address of a NUL-terminated UTF-16 string. + A copy is made; the pointer can be safely freed. If "length" is + specified, the string does not have to be NUL-terminated. .. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. - + Create a string from the address of a NUL-terminated UTF-16 string. + A copy is made; the pointer can be safely freed. If "length" is + specified, the string does not have to be NUL-terminated. .. function:: wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - + This is a synonym for either "utf32(s)" or "utf16(s)", + depending on whether "Cwchar_t" is 32 or 16 bits, respectively. + The synonym "WString" for "UTF32String" or "UTF16String" is + also provided. .. function:: wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - + This is a synonym for either "utf32(s)" or "utf16(s)", + depending on whether "Cwchar_t" is 32 or 16 bits, respectively. + The synonym "WString" for "UTF32String" or "UTF16String" is + also provided. .. function:: wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - + This is a synonym for either "utf32(s)" or "utf16(s)", + depending on whether "Cwchar_t" is 32 or 16 bits, respectively. + The synonym "WString" for "UTF32String" or "UTF16String" is + also provided. diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst index e97aa5b87697d..f923ec028a058 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -14,8 +14,9 @@ binary install, you can run the test suite using ``Base.runtests()``. .. function:: runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) - Run the Julia unit tests listed in ``tests``, which can be either a string or an array of strings, using ``numcores`` processors. (not exported) - + Run the Julia unit tests listed in "tests", which can be either a + string or an array of strings, using "numcores" processors. (not + exported) .. module:: Base.Test Test Framework @@ -131,29 +132,28 @@ Macros .. function:: @test(ex) - Test the expression ``ex`` and calls the current handler to handle the result. - + Test the expression "ex" and calls the current handler to handle + the result. .. function:: @test_throws(extype, ex) - Test that the expression ``ex`` throws an exception of type - + Test that the expression "ex" throws an exception of type + "extype" and calls the current handler to handle the result. .. function:: @test_approx_eq(a, b) - Test two floating point numbers ``a`` and ``b`` for equality taking in account small numerical errors. - + Test two floating point numbers "a" and "b" for equality taking + in account small numerical errors. .. function:: @test_approx_eq_eps(a, b, tol) - Test two floating point numbers ``a`` and ``b`` for equality taking in account a margin of tolerance given by ``tol``. - + Test two floating point numbers "a" and "b" for equality taking + in account a margin of tolerance given by "tol". Functions --------- .. function:: with_handler(f, handler) - Run the function ``f`` using the ``handler`` as the handler. - + Run the function "f" using the "handler" as the handler. From 1e882074815dee8aad808a6327af56a431f8855e Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 22:16:09 -0400 Subject: [PATCH 22/27] convert to markdown, again --- base/docs/helpdb.jl | 16461 +++++++++++++++++------------------------- doc/markdown.jl | 25 + 2 files changed, 6752 insertions(+), 9734 deletions(-) create mode 100644 doc/markdown.jl diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index bcae513ed6e17..c0a9aac92482d 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -1,6310 +1,5225 @@ doc""" -```rst -ndims(A) -> Integer + ndims(A) -> Integer - Returns the number of dimensions of A -``` +Returns the number of dimensions of A """ ndims doc""" -```rst -size(A[, dim...]) + size(A[, 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.: +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 = rand(2,3,4); + julia> A = rand(2,3,4); - julia> size(A, 2) - 3 + julia> size(A, 2) + 3 - julia> size(A,3,2) - (4,3) -``` + julia> size(A,3,2) + (4,3) """ size doc""" -```rst -iseltype(A, T) + iseltype(A, T) - Tests whether A or its elements are of type T -``` +Tests whether A or its elements are of type T """ iseltype doc""" -```rst -length(A) -> Integer + length(A) -> Integer - Returns the number of elements in A -``` +Returns the number of elements in A """ length doc""" -```rst -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 (like "Array"), this is - simply the range "1: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 non-integer indices). - - Example for a sparse 2-d array: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 -``` + 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 (like "Array"), this is +simply the range "1: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 non-integer indices). + +Example for a sparse 2-d array: + + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 """ eachindex doc""" -```rst -Base.linearindexing(A) + Base.linearindexing(A) - "linearindexing" defines how an AbstractArray most efficiently - accesses its elements. If "Base.linearindexing(A)" returns - "Base.LinearFast()", this means that linear indexing with only - one index is an efficient operation. If it instead returns - "Base.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 - traits-based mechanism to enable efficient generic code for all - array types. +"linearindexing" defines how an AbstractArray most efficiently +accesses its elements. If "Base.linearindexing(A)" returns +"Base.LinearFast()", this means that linear indexing with only +one index is an efficient operation. If it instead returns +"Base.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 +traits-based 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 define "linearindexing" in the - type-domain: +An abstract array subtype "MyArray" that wishes to opt into fast +linear indexing behaviors should define "linearindexing" in the +type-domain: - Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() -``` + Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() """ -Base +linearindexing doc""" -```rst -countnz(A) + countnz(A) - Counts the number of nonzero values in array A (dense or sparse). - Note that this is not a constant-time operation. For sparse - matrices, one should usually use "nnz", which returns the number - of stored values. -``` +Counts the number of nonzero values in array A (dense or sparse). +Note that this is not a constant-time operation. For sparse +matrices, one should usually use "nnz", which returns the number +of stored values. """ countnz doc""" -```rst -conj!(A) + conj!(A) - Convert an array to its complex conjugate in-place -``` +Convert an array to its complex conjugate in-place """ conj! doc""" -```rst -stride(A, k) + stride(A, k) - Returns the distance in memory (in number of elements) between - adjacent elements in dimension k -``` +Returns the distance in memory (in number of elements) between +adjacent elements in dimension k """ stride doc""" -```rst -strides(A) + strides(A) - Returns a tuple of the memory strides in each dimension -``` +Returns a tuple of the memory strides in each dimension """ strides doc""" -```rst -ind2sub(dims, index) -> subscripts + ind2sub(dims, index) -> subscripts - Returns a tuple of subscripts into an array with dimensions - "dims", corresponding to the linear index "index" +Returns a tuple of subscripts into an array with dimensions +"dims", corresponding to the linear index "index" - **Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides - the indices of the maximum element -``` +**Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides +the indices of the maximum element """ ind2sub doc""" -```rst -ind2sub(a, index) -> subscripts + ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array "a" corresponding to the - linear index "index" -``` +Returns a tuple of subscripts into array "a" corresponding to the +linear index "index" """ ind2sub doc""" -```rst -sub2ind(dims, i, j, k...) -> index + sub2ind(dims, i, j, k...) -> index - The inverse of "ind2sub", returns the linear index corresponding - to the provided subscripts -``` +The inverse of "ind2sub", returns the linear index corresponding +to the provided subscripts """ sub2ind doc""" -```rst -Array(dims) + Array(dims) - "Array{T}(dims)" constructs an uninitialized dense array with - element type "T". "dims" may be a tuple or a series of integer - arguments. The syntax "Array(T, dims)" is also available, but - deprecated. -``` +"Array{T}(dims)" constructs an uninitialized dense array with +element type "T". "dims" may be a tuple or a series of integer +arguments. The syntax "Array(T, dims)" is also available, but +deprecated. """ Array doc""" -```rst -getindex(type[, elements...]) + getindex(type[, elements...]) - Construct a 1-d array of the specified type. This is usually called - with the syntax "Type[]". Element values can be specified using - "Type[a,b,c,...]". -``` +Construct a 1-d array of the specified type. This is usually called +with the syntax "Type[]". Element values can be specified using +"Type[a,b,c,...]". """ getindex doc""" -```rst -cell(dims) + cell(dims) - Construct an uninitialized cell array (heterogeneous array). - "dims" can be either a tuple or a series of integer arguments. -``` +Construct an uninitialized cell array (heterogeneous array). +"dims" can be either a tuple or a series of integer arguments. """ cell doc""" -```rst -zeros(type, dims) + zeros(type, dims) - Create an array of all zeros of specified type. The type defaults - to Float64 if not specified. -``` +Create an array of all zeros of specified type. The type defaults +to Float64 if not specified. """ zeros doc""" -```rst -zeros(A) + zeros(A) - Create an array of all zeros with the same element type and shape - as A. -``` +Create an array of all zeros with the same element type and shape +as A. """ zeros doc""" -```rst -ones(type, dims) + ones(type, dims) - Create an array of all ones of specified type. The type defaults to - Float64 if not specified. -``` +Create an array of all ones of specified type. The type defaults to +Float64 if not specified. """ ones doc""" -```rst -ones(A) + ones(A) - Create an array of all ones with the same element type and shape as - A. -``` +Create an array of all ones with the same element type and shape as +A. """ ones doc""" -```rst -trues(dims) + trues(dims) - Create a "BitArray" with all values set to true -``` +Create a "BitArray" with all values set to true """ trues doc""" -```rst -falses(dims) + falses(dims) - Create a "BitArray" with all values set to false -``` +Create a "BitArray" with all values set to false """ falses doc""" -```rst -fill(x, dims) + fill(x, dims) - Create an array filled with the value "x". For example, - "fill(1.0, (10,10))" returns a 10x10 array of floats, with each - element initialized to 1.0. +Create an array filled with the value "x". For example, +"fill(1.0, (10,10))" returns a 10x10 array of floats, with each +element initialized to 1.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 evaluating "Foo()" once. -``` +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 evaluating "Foo()" once. """ fill doc""" -```rst -fill!(A, x) + fill!(A, x) - Fill array "A" with the value "x". If "x" is an object - reference, all elements will refer to the same object. "fill!(A, - Foo())" will return "A" filled with the result of evaluating - "Foo()" once. -``` +Fill array "A" with the value "x". If "x" is an object +reference, all elements will refer to the same object. "fill!(A, +Foo())" will return "A" filled with the result of evaluating +"Foo()" once. """ fill! doc""" -```rst -reshape(A, dims) + reshape(A, dims) - Create an array with the same data as the given array, but with - different dimensions. An implementation for a particular type of - array may choose whether the data is copied or shared. -``` +Create an array with the same data as the given array, but with +different dimensions. An implementation for a particular type of +array may choose whether the data is copied or shared. """ reshape doc""" -```rst -similar(array, element_type, dims) + similar(array, element_type, dims) - Create an uninitialized array of the same type as the given array, - but with the specified element type and dimensions. The second and - third arguments are both optional. The "dims" argument may be a - tuple or a series of integer arguments. For some special - "AbstractArray" objects which are not real containers (like - ranges), this function returns a standard "Array" to allow - operating on elements. -``` +Create an uninitialized array of the same type as the given array, +but with the specified element type and dimensions. The second and +third arguments are both optional. The "dims" argument may be a +tuple or a series of integer arguments. For some special +"AbstractArray" objects which are not real containers (like +ranges), this function returns a standard "Array" to allow +operating on elements. """ similar doc""" -```rst -reinterpret(type, A) + reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, - "reinterpret(Float32, UInt32(7))" interprets the 4 bytes - corresponding to "UInt32(7)" as a "Float32". For arrays, this - constructs an array with the same binary data as the given array, - but with the specified element type. -``` +Change the type-interpretation of a block of memory. For example, +"reinterpret(Float32, UInt32(7))" interprets the 4 bytes +corresponding to "UInt32(7)" as a "Float32". For arrays, this +constructs an array with the same binary data as the given array, +but with the specified element type. """ reinterpret doc""" -```rst -eye(n) + eye(n) - n-by-n identity matrix -``` +n-by-n identity matrix """ eye doc""" -```rst -eye(m, n) + eye(m, n) - m-by-n identity matrix -``` +m-by-n identity matrix """ eye doc""" -```rst -eye(A) + eye(A) - Constructs an identity matrix of the same dimensions and type as - "A". -``` +Constructs an identity matrix of the same dimensions and type as +"A". """ eye doc""" -```rst -linspace(start, stop, n=100) + linspace(start, stop, n=100) - Construct a range of "n" linearly spaced elements from "start" - to "stop". -``` +Construct a range of "n" linearly spaced elements from "start" +to "stop". """ linspace doc""" -```rst -logspace(start, stop, n=50) + logspace(start, stop, n=50) - Construct a vector of "n" logarithmically spaced numbers from - "10^start" to "10^stop". -``` +Construct a vector of "n" logarithmically spaced numbers from +"10^start" to "10^stop". """ logspace doc""" -```rst -broadcast(f, As...) + broadcast(f, As...) - Broadcasts the arrays "As" to a common size by expanding - singleton dimensions, and returns an array of the results - "f(as...)" for each position. -``` +Broadcasts the arrays "As" to a common size by expanding +singleton dimensions, and returns an array of the results +"f(as...)" for each position. """ broadcast doc""" -```rst -broadcast!(f, dest, As...) + broadcast!(f, dest, As...) - Like "broadcast", but store the result of "broadcast(f, As...)" - in the "dest" array. Note that "dest" is only used to store the - result, and does not supply arguments to "f" unless it is also - listed in the "As", as in "broadcast!(f, A, A, B)" to perform - "A[:] = broadcast(f, A, B)". -``` +Like "broadcast", but store the result of "broadcast(f, As...)" +in the "dest" array. Note that "dest" is only used to store the +result, and does not supply arguments to "f" unless it is also +listed in the "As", as in "broadcast!(f, A, A, B)" to perform +"A[:] = broadcast(f, A, B)". """ broadcast! doc""" -```rst -bitbroadcast(f, As...) + bitbroadcast(f, As...) - Like "broadcast", but allocates a "BitArray" to store the - result, rather then an "Array". -``` +Like "broadcast", but allocates a "BitArray" to store the +result, rather then an "Array". """ bitbroadcast doc""" -```rst -broadcast_function(f) + broadcast_function(f) - Returns a function "broadcast_f" such that - "broadcast_function(f)(As...) === broadcast(f, As...)". Most - useful in the form "const broadcast_f = broadcast_function(f)". -``` +Returns a function "broadcast_f" such that +"broadcast_function(f)(As...) === broadcast(f, As...)". Most +useful in the form "const broadcast_f = broadcast_function(f)". """ broadcast_function doc""" -```rst -broadcast!_function(f) + broadcast!_function(f) - Like "broadcast_function", but for "broadcast!". -``` +Like "broadcast_function", but for "broadcast!". """ broadcast!_function doc""" -```rst -getindex(A, inds...) + getindex(A, inds...) - Returns a subset of array "A" as specified by "inds", where - each "ind" may be an "Int", a "Range", or a "Vector". See - the manual section on *array indexing* for details. -``` +Returns a subset of array "A" as specified by "inds", where +each "ind" may be an "Int", a "Range", or a "Vector". See +the manual section on *array indexing* for details. """ getindex doc""" -```rst -sub(A, inds...) + sub(A, inds...) - Like "getindex()", but returns a view into the parent array "A" - with the given indices instead of making a copy. Calling - "getindex()" or "setindex!()" on the returned "SubArray" - computes the indices to the parent array on the fly without - checking bounds. -``` +Like "getindex()", but returns a view into the parent array "A" +with the given indices instead of making a copy. Calling +"getindex()" or "setindex!()" on the returned "SubArray" +computes the indices to the parent array on the fly without +checking bounds. """ sub doc""" -```rst -parent(A) + parent(A) - Returns the "parent array" of an array view type (e.g., - SubArray), or the array itself if it is not a view -``` +Returns the "parent array" of an array view type (e.g., +SubArray), or the array itself if it is not a view """ parent doc""" -```rst -parentindexes(A) + parentindexes(A) - From an array view "A", returns the corresponding indexes in the - parent -``` +From an array view "A", returns the corresponding indexes in the +parent """ parentindexes doc""" -```rst -slicedim(A, d, i) + slicedim(A, d, i) - Return all the data of "A" where the index for dimension "d" - equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is - in position "d". -``` +Return all the data of "A" where the index for dimension "d" +equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is +in position "d". """ slicedim doc""" -```rst -slice(A, inds...) + slice(A, inds...) - Returns a view of array "A" with the given indices like - "sub()", but drops all dimensions indexed with scalars. -``` +Returns a view of array "A" with the given indices like +"sub()", but drops all dimensions indexed with scalars. """ slice doc""" -```rst -setindex!(A, X, inds...) + setindex!(A, X, inds...) - Store values from array "X" within some subset of "A" as - specified by "inds". -``` +Store values from array "X" within some subset of "A" as +specified by "inds". """ setindex! doc""" -```rst -broadcast_getindex(A, inds...) + broadcast_getindex(A, inds...) - Broadcasts the "inds" arrays to a common size like "broadcast", - and returns an array of the results "A[ks...]", where "ks" goes - over the positions in the broadcast. -``` +Broadcasts the "inds" arrays to a common size like "broadcast", +and returns an array of the results "A[ks...]", where "ks" goes +over the positions in the broadcast. """ broadcast_getindex doc""" -```rst -broadcast_setindex!(A, X, inds...) + broadcast_setindex!(A, X, inds...) - Broadcasts the "X" and "inds" arrays to a common size and - stores the value from each position in "X" at the indices given - by the same positions in "inds". -``` +Broadcasts the "X" and "inds" arrays to a common size and +stores the value from each position in "X" at the indices given +by the same positions in "inds". """ broadcast_setindex! doc""" -```rst -cat(dims, A...) - - Concatenate the input arrays along the specified dimensions in the - iterable "dims". For dimensions not in "dims", all input arrays - should have the same size, which will also be the size of the - output array along that dimension. For dimensions in "dims", the - size of the output array is the sum of the sizes of the input - arrays along that dimension. If "dims" is a single number, the - different arrays are tightly stacked along that dimension. If - "dims" is an iterable containing several dimensions, this allows - to construct block diagonal matrices and their higher-dimensional - 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 with *matrices[1]*, *matrices[2]*, ... as diagonal - blocks and matching zero blocks away from the diagonal. -``` + cat(dims, A...) + +Concatenate the input arrays along the specified dimensions in the +iterable "dims". For dimensions not in "dims", all input arrays +should have the same size, which will also be the size of the +output array along that dimension. For dimensions in "dims", the +size of the output array is the sum of the sizes of the input +arrays along that dimension. If "dims" is a single number, the +different arrays are tightly stacked along that dimension. If +"dims" is an iterable containing several dimensions, this allows +to construct block diagonal matrices and their higher-dimensional +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 with *matrices[1]*, *matrices[2]*, ... as diagonal +blocks and matching zero blocks away from the diagonal. """ cat doc""" -```rst -vcat(A...) + vcat(A...) - Concatenate along dimension 1 -``` +Concatenate along dimension 1 """ vcat doc""" -```rst -hcat(A...) + hcat(A...) - Concatenate along dimension 2 -``` +Concatenate along dimension 2 """ hcat doc""" -```rst -hvcat(rows::Tuple{Vararg{Int}}, values...) + 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. For example, - "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". +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. For example, +"[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". - If the first argument is a single integer "n", then all block - rows are assumed to have "n" block columns. -``` +If the first argument is a single integer "n", then all block +rows are assumed to have "n" block columns. """ hvcat doc""" -```rst -flipdim(A, d) + flipdim(A, d) - Reverse "A" in dimension "d". -``` +Reverse "A" in dimension "d". """ flipdim doc""" -```rst -circshift(A, shifts) + circshift(A, shifts) - Circularly shift the data in an array. The second argument is a - vector giving the amount to shift in each dimension. -``` +Circularly shift the data in an array. The second argument is a +vector giving the amount to shift in each dimension. """ circshift doc""" -```rst -find(A) + find(A) - Return a vector of the linear indexes of the non-zeros in "A" - (determined by "A[i]!=0"). A common use of this is to convert a - boolean array to an array of indexes of the "true" elements. -``` +Return a vector of the linear indexes of the non-zeros in "A" +(determined by "A[i]!=0"). A common use of this is to convert a +boolean array to an array of indexes of the "true" elements. """ find doc""" -```rst -find(f, A) + find(f, A) - Return a vector of the linear indexes of "A" where "f" returns - true. -``` +Return a vector of the linear indexes of "A" where "f" returns +true. """ find doc""" -```rst -findn(A) + findn(A) - Return a vector of indexes for each dimension giving the locations - of the non-zeros in "A" (determined by "A[i]!=0"). -``` +Return a vector of indexes for each dimension giving the locations +of the non-zeros in "A" (determined by "A[i]!=0"). """ findn doc""" -```rst -findnz(A) + findnz(A) - Return a tuple "(I, J, V)" where "I" and "J" are the row and - column indexes of the non-zero values in matrix "A", and "V" is - a vector of the non-zero values. -``` +Return a tuple "(I, J, V)" where "I" and "J" are the row and +column indexes of the non-zero values in matrix "A", and "V" is +a vector of the non-zero values. """ findnz doc""" -```rst -findfirst(A) + findfirst(A) - Return the index of the first non-zero value in "A" (determined - by "A[i]!=0"). -``` +Return the index of the first non-zero value in "A" (determined +by "A[i]!=0"). """ findfirst doc""" -```rst -findfirst(A, v) + findfirst(A, v) - Return the index of the first element equal to "v" in "A". -``` +Return the index of the first element equal to "v" in "A". """ findfirst doc""" -```rst -findfirst(predicate, A) + findfirst(predicate, A) - Return the index of the first element of "A" for which - "predicate" returns true. -``` +Return the index of the first element of "A" for which +"predicate" returns true. """ findfirst doc""" -```rst -findlast(A) + findlast(A) - Return the index of the last non-zero value in "A" (determined by - "A[i]!=0"). -``` +Return the index of the last non-zero value in "A" (determined by +"A[i]!=0"). """ findlast doc""" -```rst -findlast(A, v) + findlast(A, v) - Return the index of the last element equal to "v" in "A". -``` +Return the index of the last element equal to "v" in "A". """ findlast doc""" -```rst -findlast(predicate, A) + findlast(predicate, A) - Return the index of the last element of "A" for which - "predicate" returns true. -``` +Return the index of the last element of "A" for which +"predicate" returns true. """ findlast doc""" -```rst -findnext(A, i) + findnext(A, i) - Find the next index >= "i" of a non-zero element of "A", or - "0" if not found. -``` +Find the next index >= "i" of a non-zero element of "A", or +"0" if not found. """ findnext doc""" -```rst -findnext(predicate, A, i) + findnext(predicate, A, i) - Find the next index >= "i" of an element of "A" for which - "predicate" returns true, or "0" if not found. -``` +Find the next index >= "i" of an element of "A" for which +"predicate" returns true, or "0" if not found. """ findnext doc""" -```rst -findnext(A, v, i) + findnext(A, v, i) - Find the next index >= "i" of an element of "A" equal to "v" - (using "=="), or "0" if not found. -``` +Find the next index >= "i" of an element of "A" equal to "v" +(using "=="), or "0" if not found. """ findnext doc""" -```rst -findprev(A, i) + findprev(A, i) - Find the previous index <= "i" of a non-zero element of "A", or - 0 if not found. -``` +Find the previous index <= "i" of a non-zero element of "A", or +0 if not found. """ findprev doc""" -```rst -findprev(predicate, A, i) + findprev(predicate, A, i) - Find the previous index <= "i" of an element of "A" for which - "predicate" returns true, or "0" if not found. -``` +Find the previous index <= "i" of an element of "A" for which +"predicate" returns true, or "0" if not found. """ findprev doc""" -```rst -findprev(A, v, i) + findprev(A, v, i) - Find the previous index <= "i" of an element of "A" equal to - "v" (using "=="), or "0" if not found. -``` +Find the previous index <= "i" of an element of "A" equal to +"v" (using "=="), or "0" if not found. """ findprev doc""" -```rst -permutedims(A, perm) + permutedims(A, perm) - Permute the dimensions of array "A". "perm" is a vector - specifying a permutation of length "ndims(A)". This is a - generalization of transpose for multi-dimensional arrays. Transpose - is equivalent to "permutedims(A, [2,1])". -``` +Permute the dimensions of array "A". "perm" is a vector +specifying a permutation of length "ndims(A)". This is a +generalization of transpose for multi-dimensional arrays. Transpose +is equivalent to "permutedims(A, [2,1])". """ permutedims doc""" -```rst -ipermutedims(A, perm) + ipermutedims(A, perm) - Like "permutedims()", except the inverse of the given permutation - is applied. -``` +Like "permutedims()", except the inverse of the given permutation +is applied. """ ipermutedims doc""" -```rst -permutedims!(dest, src, perm) + permutedims!(dest, src, perm) - Permute the dimensions of array "src" and store the result in the - array "dest". "perm" is a vector specifying a permutation of - length "ndims(src)". The preallocated array "dest" should have - "size(dest) == size(src)[perm]" and is completely overwritten. No - in-place permutation is supported and unexpected results will - happen if *src* and *dest* have overlapping memory regions. -``` +Permute the dimensions of array "src" and store the result in the +array "dest". "perm" is a vector specifying a permutation of +length "ndims(src)". The preallocated array "dest" should have +"size(dest) == size(src)[perm]" and is completely overwritten. No +in-place permutation is supported and unexpected results will +happen if *src* and *dest* have overlapping memory regions. """ permutedims! doc""" -```rst -squeeze(A, dims) + squeeze(A, dims) - Remove the dimensions specified by "dims" from array "A". - Elements of "dims" must be unique and within the range - "1:ndims(A)". -``` +Remove the dimensions specified by "dims" from array "A". +Elements of "dims" must be unique and within the range +"1:ndims(A)". """ squeeze doc""" -```rst -vec(Array) -> Vector + vec(Array) -> Vector - Vectorize an array using column-major convention. -``` +Vectorize an array using column-major convention. """ vec doc""" -```rst -promote_shape(s1, s2) + promote_shape(s1, s2) - Check two array shapes for compatibility, allowing trailing - singleton dimensions, and return whichever shape has more - dimensions. -``` +Check two array shapes for compatibility, allowing trailing +singleton dimensions, and return whichever shape has more +dimensions. """ promote_shape doc""" -```rst -checkbounds(array, indexes...) + checkbounds(array, indexes...) - Throw an error if the specified indexes are not in bounds for the - given array. -``` +Throw an error if the specified indexes are not in bounds for the +given array. """ checkbounds doc""" -```rst -randsubseq(A, p) -> Vector + randsubseq(A, p) -> Vector - Return a vector consisting of a random subsequence of the given - array "A", where each element of "A" is included (in order) - with independent probability "p". (Complexity is linear in - "p*length(A)", so this function is efficient even if "p" is - small and "A" is large.) Technically, this process is known as - "Bernoulli sampling" of "A". -``` +Return a vector consisting of a random subsequence of the given +array "A", where each element of "A" is included (in order) +with independent probability "p". (Complexity is linear in +"p*length(A)", so this function is efficient even if "p" is +small and "A" is large.) Technically, this process is known as +"Bernoulli sampling" of "A". """ randsubseq doc""" -```rst -randsubseq!(S, A, p) + randsubseq!(S, A, p) - Like "randsubseq", but the results are stored in "S" (which is - resized as needed). -``` +Like "randsubseq", but the results are stored in "S" (which is +resized as needed). """ randsubseq! doc""" -```rst -cumprod(A[, dim]) + cumprod(A[, dim]) - Cumulative product along a dimension "dim" (defaults to 1). See - also "cumprod!()" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). -``` +Cumulative product along a dimension "dim" (defaults to 1). See +also "cumprod!()" to use a preallocated output array, both for +performance and to control the precision of the output (e.g. to +avoid overflow). """ cumprod doc""" -```rst -cumprod!(B, A[, dim]) + cumprod!(B, A[, dim]) - Cumulative product of "A" along a dimension, storing the result - in "B". The dimension defaults to 1. -``` +Cumulative product of "A" along a dimension, storing the result +in "B". The dimension defaults to 1. """ cumprod! doc""" -```rst -cumsum(A[, dim]) + cumsum(A[, dim]) - Cumulative sum along a dimension "dim" (defaults to 1). See also - "cumsum!()" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). -``` +Cumulative sum along a dimension "dim" (defaults to 1). See also +"cumsum!()" to use a preallocated output array, both for +performance and to control the precision of the output (e.g. to +avoid overflow). """ cumsum doc""" -```rst -cumsum!(B, A[, dim]) + cumsum!(B, A[, dim]) - Cumulative sum of "A" along a dimension, storing the result in - "B". The dimension defaults to 1. -``` +Cumulative sum of "A" along a dimension, storing the result in +"B". The dimension defaults to 1. """ cumsum! doc""" -```rst -cumsum_kbn(A[, dim]) + cumsum_kbn(A[, dim]) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. The - dimension defaults to 1. -``` +Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier +compensated summation algorithm for additional accuracy. The +dimension defaults to 1. """ cumsum_kbn doc""" -```rst -cummin(A[, dim]) + cummin(A[, dim]) - Cumulative minimum along a dimension. The dimension defaults to 1. -``` +Cumulative minimum along a dimension. The dimension defaults to 1. """ cummin doc""" -```rst -cummax(A[, dim]) + cummax(A[, dim]) - Cumulative maximum along a dimension. The dimension defaults to 1. -``` +Cumulative maximum along a dimension. The dimension defaults to 1. """ cummax doc""" -```rst -diff(A[, dim]) + diff(A[, dim]) - Finite difference operator of matrix or vector. -``` +Finite difference operator of matrix or vector. """ diff doc""" -```rst -gradient(F[, h]) + gradient(F[, h]) - Compute differences along vector "F", using "h" as the spacing - between points. The default spacing is one. -``` +Compute differences along vector "F", using "h" as the spacing +between points. The default spacing is one. """ gradient doc""" -```rst -rot180(A) + rot180(A) - Rotate matrix "A" 180 degrees. -``` +Rotate matrix "A" 180 degrees. """ rot180 doc""" -```rst -rot180(A, k) + rot180(A, k) - Rotate matrix "A" 180 degrees an integer "k" number of times. - If "k" is even, this is equivalent to a "copy". -``` +Rotate matrix "A" 180 degrees an integer "k" number of times. +If "k" is even, this is equivalent to a "copy". """ rot180 doc""" -```rst -rotl90(A) + rotl90(A) - Rotate matrix "A" left 90 degrees. -``` +Rotate matrix "A" left 90 degrees. """ rotl90 doc""" -```rst -rotl90(A, k) + rotl90(A, k) - Rotate matrix "A" left 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". -``` +Rotate matrix "A" left 90 degrees an integer "k" number of +times. If "k" is zero or a multiple of four, this is equivalent +to a "copy". """ rotl90 doc""" -```rst -rotr90(A) + rotr90(A) - Rotate matrix "A" right 90 degrees. -``` +Rotate matrix "A" right 90 degrees. """ rotr90 doc""" -```rst -rotr90(A, k) + rotr90(A, k) - Rotate matrix "A" right 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". -``` +Rotate matrix "A" right 90 degrees an integer "k" number of +times. If "k" is zero or a multiple of four, this is equivalent +to a "copy". """ rotr90 doc""" -```rst -reducedim(f, A, dims[, initial]) + reducedim(f, A, dims[, initial]) - Reduce 2-argument function "f" along dimensions of "A". - "dims" is a vector specifying the dimensions to reduce, and - "initial" is the initial value to use in the reductions. For *+*, - ***, *max* and *min* the *initial* argument is optional. +Reduce 2-argument function "f" along dimensions of "A". +"dims" is a vector specifying the dimensions to reduce, and +"initial" is the initial value to use in the reductions. For *+*, +***, *max* and *min* the *initial* argument is optional. - The associativity of the reduction is implementation-dependent; if - you need a particular associativity, e.g. left-to-right, you should - write your own loop. See documentation for "reduce". -``` +The associativity of the reduction is implementation-dependent; if +you need a particular associativity, e.g. left-to-right, you should +write your own loop. See documentation for "reduce". """ reducedim doc""" -```rst -mapreducedim(f, op, A, dims[, initial]) + mapreducedim(f, op, A, dims[, initial]) - Evaluates to the same as *reducedim(op, map(f, A), dims, - f(initial))*, but is generally faster because the intermediate - array is avoided. -``` +Evaluates to the same as *reducedim(op, map(f, A), dims, +f(initial))*, but is generally faster because the intermediate +array is avoided. """ mapreducedim doc""" -```rst -mapslices(f, A, dims) + mapslices(f, A, dims) - Transform the given dimensions of array "A" using function "f". - "f" is called on each slice of "A" of the form - "A[...,:,...,:,...]". "dims" is an integer vector specifying - where the colons go in this expression. The results are - concatenated along the remaining dimensions. For example, if - "dims" is "[1,2]" and A is 4-dimensional, "f" is called on - "A[:,:,i,j]" for all "i" and "j". -``` +Transform the given dimensions of array "A" using function "f". +"f" is called on each slice of "A" of the form +"A[...,:,...,:,...]". "dims" is an integer vector specifying +where the colons go in this expression. The results are +concatenated along the remaining dimensions. For example, if +"dims" is "[1,2]" and A is 4-dimensional, "f" is called on +"A[:,:,i,j]" for all "i" and "j". """ mapslices doc""" -```rst -sum_kbn(A) + sum_kbn(A) - Returns the sum of all array elements, using the Kahan-Babuska- - Neumaier compensated summation algorithm for additional accuracy. -``` +Returns the sum of all array elements, using the Kahan-Babuska- +Neumaier compensated summation algorithm for additional accuracy. """ sum_kbn doc""" -```rst -cartesianmap(f, dims) + cartesianmap(f, dims) - Given a "dims" tuple of integers "(m, n, ...)", call "f" on - all combinations of integers in the ranges "1:m", "1:n", etc. +Given a "dims" tuple of integers "(m, n, ...)", call "f" on +all combinations of integers in the ranges "1:m", "1:n", etc. - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 -``` + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 """ cartesianmap doc""" -```rst -nthperm(v, k) + nthperm(v, k) - Compute the kth lexicographic permutation of a vector. -``` +Compute the kth lexicographic permutation of a vector. """ nthperm doc""" -```rst -nthperm(p) + nthperm(p) - Return the "k" that generated permutation "p". Note that - "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". -``` +Return the "k" that generated permutation "p". Note that +"nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". """ nthperm doc""" -```rst -nthperm!(v, k) + nthperm!(v, k) - In-place version of "nthperm()". -``` +In-place version of "nthperm()". """ nthperm! doc""" -```rst -randperm([rng], n) + randperm([rng], n) - Construct a random permutation of length "n". The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. -``` +Construct a random permutation of length "n". The optional +"rng" argument specifies a random number generator, see *Random +Numbers*. """ randperm doc""" -```rst -invperm(v) + invperm(v) - Return the inverse permutation of v. -``` +Return the inverse permutation of v. """ invperm doc""" -```rst -isperm(v) -> Bool + isperm(v) -> Bool - Returns true if v is a valid permutation. -``` +Returns true if v is a valid permutation. """ isperm doc""" -```rst -permute!(v, p) + permute!(v, p) - Permute vector "v" in-place, according to permutation "p". No - checking is done to verify that "p" is a permutation. +Permute vector "v" in-place, according to permutation "p". No +checking is done to verify that "p" is a permutation. - To return a new permutation, use "v[p]". Note that this is - generally faster than "permute!(v,p)" for large vectors. -``` +To return a new permutation, use "v[p]". Note that this is +generally faster than "permute!(v,p)" for large vectors. """ permute! doc""" -```rst -ipermute!(v, p) + ipermute!(v, p) - Like permute!, but the inverse of the given permutation is applied. -``` +Like permute!, but the inverse of the given permutation is applied. """ ipermute! doc""" -```rst -randcycle([rng], n) + randcycle([rng], n) - Construct a random cyclic permutation of length "n". The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. -``` +Construct a random cyclic permutation of length "n". The optional +"rng" argument specifies a random number generator, see *Random +Numbers*. """ randcycle doc""" -```rst -shuffle([rng], v) + shuffle([rng], v) - Return a randomly permuted copy of "v". The optional "rng" - argument specifies a random number generator, see *Random Numbers*. -``` +Return a randomly permuted copy of "v". The optional "rng" +argument specifies a random number generator, see *Random Numbers*. """ shuffle doc""" -```rst -shuffle!([rng], v) + shuffle!([rng], v) - In-place version of "shuffle()". -``` +In-place version of "shuffle()". """ shuffle! doc""" -```rst -reverse(v[, start=1[, stop=length(v)]]) + reverse(v[, start=1[, stop=length(v)]]) - Return a copy of "v" reversed from start to stop. -``` +Return a copy of "v" reversed from start to stop. """ reverse doc""" -```rst -reverseind(v, i) + reverseind(v, i) - Given an index "i" in "reverse(v)", return the corresponding - index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". - (This can be nontrivial in the case where "v" is a Unicode - string.) -``` +Given an index "i" in "reverse(v)", return the corresponding +index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". +(This can be nontrivial in the case where "v" is a Unicode +string.) """ reverseind doc""" -```rst -reverse!(v[, start=1[, stop=length(v)]]) -> v + reverse!(v[, start=1[, stop=length(v)]]) -> v - In-place version of "reverse()". -``` +In-place version of "reverse()". """ reverse! doc""" -```rst -combinations(array, n) + combinations(array, n) - Generate all combinations of "n" elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - "collect(combinations(array,n))" to get an array of all - combinations. -``` +Generate all combinations of "n" elements from an indexable +object. Because the number of combinations can be very large, this +function returns an iterator object. Use +"collect(combinations(array,n))" to get an array of all +combinations. """ combinations doc""" -```rst -permutations(array) + permutations(array) - Generate all permutations of an indexable object. Because the - number of permutations can be very large, this function returns an - iterator object. Use "collect(permutations(array))" to get an - array of all permutations. -``` +Generate all permutations of an indexable object. Because the +number of permutations can be very large, this function returns an +iterator object. Use "collect(permutations(array))" to get an +array of all permutations. """ permutations doc""" -```rst -partitions(n) + partitions(n) - Generate all integer arrays that sum to "n". Because the number - of partitions can be very large, this function returns an iterator - object. Use "collect(partitions(n))" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using "length(partitions(n))". -``` +Generate all integer arrays that sum to "n". Because the number +of partitions can be very large, this function returns an iterator +object. Use "collect(partitions(n))" to get an array of all +partitions. The number of partitions to generate can be efficiently +computed using "length(partitions(n))". """ partitions doc""" -```rst -partitions(n, m) + partitions(n, m) - Generate all arrays of "m" integers that sum to "n". Because - the number of partitions can be very large, this function returns - an iterator object. Use "collect(partitions(n,m))" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using "length(partitions(n,m))". -``` +Generate all arrays of "m" integers that sum to "n". Because +the number of partitions can be very large, this function returns +an iterator object. Use "collect(partitions(n,m))" to get an +array of all partitions. The number of partitions to generate can +be efficiently computed using "length(partitions(n,m))". """ partitions doc""" -```rst -partitions(array) + partitions(array) - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - "collect(partitions(array))" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using "length(partitions(array))". -``` +Generate all set partitions of the elements of an array, +represented as arrays of arrays. Because the number of partitions +can be very large, this function returns an iterator object. Use +"collect(partitions(array))" to get an array of all partitions. +The number of partitions to generate can be efficiently computed +using "length(partitions(array))". """ partitions doc""" -```rst -partitions(array, m) + partitions(array, m) - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use "collect(partitions(array,m))" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using "length(partitions(array,m))". -``` +Generate all set partitions of the elements of an array into +exactly m subsets, represented as arrays of arrays. Because the +number of partitions can be very large, this function returns an +iterator object. Use "collect(partitions(array,m))" to get an +array of all partitions. The number of partitions into m subsets is +equal to the Stirling number of the second kind and can be +efficiently computed using "length(partitions(array,m))". """ partitions doc""" -```rst -bitpack(A::AbstractArray{T, N}) -> BitArray + bitpack(A::AbstractArray{T, N}) -> BitArray - Converts a numeric array to a packed boolean array -``` +Converts a numeric array to a packed boolean array """ bitpack doc""" -```rst -bitunpack(B::BitArray{N}) -> Array{Bool,N} + bitunpack(B::BitArray{N}) -> Array{Bool,N} - Converts a packed boolean array to an array of booleans -``` +Converts a packed boolean array to an array of booleans """ bitunpack doc""" -```rst -flipbits!(B::BitArray{N}) -> BitArray{N} + flipbits!(B::BitArray{N}) -> BitArray{N} - Performs a bitwise not operation on B. See *~ operator*. -``` +Performs a bitwise not operation on B. See *~ operator*. """ flipbits! doc""" -```rst -rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on "src" and put the result - into "dest". -``` +Performs a left rotation operation on "src" and put the result +into "dest". """ rol! doc""" -```rst -rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. -``` +Performs a left rotation operation on B. """ rol! doc""" -```rst -rol(B::BitArray{1}, i::Integer) -> BitArray{1} + rol(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation. -``` +Performs a left rotation operation. """ rol doc""" -```rst -ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on "src" and put the result - into "dest". -``` +Performs a right rotation operation on "src" and put the result +into "dest". """ ror! doc""" -```rst -ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. -``` +Performs a right rotation operation on B. """ ror! doc""" -```rst -ror(B::BitArray{1}, i::Integer) -> BitArray{1} + ror(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation. -``` +Performs a right rotation operation. """ ror doc""" -```rst -sparse(I, J, V[, m, n, combine]) + sparse(I, J, V[, m, n, combine]) - Create a sparse matrix "S" of dimensions "m x n" such that - "S[I[k], J[k]] = V[k]". The "combine" function is used to - combine duplicates. If "m" and "n" are not specified, they are - set to "max(I)" and "max(J)" respectively. If the "combine" - function is not supplied, duplicates are added by default. -``` +Create a sparse matrix "S" of dimensions "m x n" such that +"S[I[k], J[k]] = V[k]". The "combine" function is used to +combine duplicates. If "m" and "n" are not specified, they are +set to "max(I)" and "max(J)" respectively. If the "combine" +function is not supplied, duplicates are added by default. """ sparse doc""" -```rst -sparsevec(I, V[, m, combine]) + sparsevec(I, V[, m, combine]) - Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] - = V[k]". Duplicates are combined using the "combine" function, - which defaults to "+" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. -``` +Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] += V[k]". Duplicates are combined using the "combine" function, +which defaults to "+" if it is not provided. In julia, sparse +vectors are really just sparse matrices with one column. Given +Julia's Compressed Sparse Columns (CSC) storage format, a sparse +column matrix with one column is sparse, whereas a sparse row +matrix with one row ends up being dense. """ sparsevec doc""" -```rst -sparsevec(D::Dict[, m]) + sparsevec(D::Dict[, m]) - Create a sparse matrix of size "m x 1" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. -``` +Create a sparse matrix of size "m x 1" where the row values are +keys from the dictionary, and the nonzero values are the values +from the dictionary. """ sparsevec doc""" -```rst -issparse(S) + issparse(S) - Returns "true" if "S" is sparse, and "false" otherwise. -``` +Returns "true" if "S" is sparse, and "false" otherwise. """ issparse doc""" -```rst -sparse(A) + sparse(A) - Convert an AbstractMatrix "A" into a sparse matrix. -``` +Convert an AbstractMatrix "A" into a sparse matrix. """ sparse doc""" -```rst -sparsevec(A) + sparsevec(A) - Convert a dense vector "A" into a sparse matrix of size "m x - 1". In julia, sparse vectors are really just sparse matrices with - one column. -``` +Convert a dense vector "A" into a sparse matrix of size "m x +1". In julia, sparse vectors are really just sparse matrices with +one column. """ sparsevec doc""" -```rst -full(S) + full(S) - Convert a sparse matrix "S" into a dense matrix. -``` +Convert a sparse matrix "S" into a dense matrix. """ full doc""" -```rst -nnz(A) + nnz(A) - Returns the number of stored (filled) elements in a sparse matrix. -``` +Returns the number of stored (filled) elements in a sparse matrix. """ nnz doc""" -```rst -spzeros(m, n) + spzeros(m, n) - Create a sparse matrix of size "m x n". This sparse matrix will - not contain any nonzero values. No storage will be allocated for - nonzero values during construction. -``` +Create a sparse matrix of size "m x n". This sparse matrix will +not contain any nonzero values. No storage will be allocated for +nonzero values during construction. """ spzeros doc""" -```rst -spones(S) + spones(S) - Create a sparse matrix with the same structure as that of "S", - but with every nonzero element having the value "1.0". -``` +Create a sparse matrix with the same structure as that of "S", +but with every nonzero element having the value "1.0". """ spones doc""" -```rst -speye(type, m[, n]) + speye(type, m[, n]) - Create a sparse identity matrix of specified type of size "m x - m". In case "n" is supplied, create a sparse identity matrix of - size "m x n". -``` +Create a sparse identity matrix of specified type of size "m x +m". In case "n" is supplied, create a sparse identity matrix of +size "m x n". """ speye doc""" -```rst -spdiagm(B, d[, m, n]) + spdiagm(B, d[, m, n]) - Construct a sparse diagonal matrix. "B" is a tuple of vectors - containing the diagonals and "d" is a tuple containing the - positions of the diagonals. In the case the input contains only one - diagonaly, "B" can be a vector (instead of a tuple) and "d" can - be the diagonal position (instead of a tuple), defaulting to 0 - (diagonal). Optionally, "m" and "n" specify the size of the - resulting sparse matrix. -``` +Construct a sparse diagonal matrix. "B" is a tuple of vectors +containing the diagonals and "d" is a tuple containing the +positions of the diagonals. In the case the input contains only one +diagonaly, "B" can be a vector (instead of a tuple) and "d" can +be the diagonal position (instead of a tuple), defaulting to 0 +(diagonal). Optionally, "m" and "n" specify the size of the +resulting sparse matrix. """ spdiagm doc""" -```rst -sprand([rng], m, n, p[, rfn]) + sprand([rng], m, n, p[, rfn]) - Create a random "m" by "n" sparse matrix, in which the - probability of any element being nonzero is independently given by - "p" (and hence the mean density of nonzeros is also exactly - "p"). Nonzero values are sampled from the distribution specified - by "rfn". The uniform distribution is used in case "rfn" is not - specified. The optional "rng" argument specifies a random number - generator, see *Random Numbers*. -``` +Create a random "m" by "n" sparse matrix, in which the +probability of any element being nonzero is independently given by +"p" (and hence the mean density of nonzeros is also exactly +"p"). Nonzero values are sampled from the distribution specified +by "rfn". The uniform distribution is used in case "rfn" is not +specified. The optional "rng" argument specifies a random number +generator, see *Random Numbers*. """ sprand doc""" -```rst -sprandn(m, n, p) + sprandn(m, n, p) - Create a random "m" by "n" sparse matrix with the specified - (independent) probability "p" of any entry being nonzero, where - nonzero values are sampled from the normal distribution. -``` +Create a random "m" by "n" sparse matrix with the specified +(independent) probability "p" of any entry being nonzero, where +nonzero values are sampled from the normal distribution. """ sprandn doc""" -```rst -sprandbool(m, n, p) + sprandbool(m, n, p) - Create a random "m" by "n" sparse boolean matrix with the - specified (independent) probability "p" of any entry being - "true". -``` +Create a random "m" by "n" sparse boolean matrix with the +specified (independent) probability "p" of any entry being +"true". """ sprandbool doc""" -```rst -etree(A[, post]) + etree(A[, post]) - Compute the elimination tree of a symmetric sparse matrix "A" - from "triu(A)" and, optionally, its post-ordering permutation. -``` +Compute the elimination tree of a symmetric sparse matrix "A" +from "triu(A)" and, optionally, its post-ordering permutation. """ etree doc""" -```rst -symperm(A, p) + symperm(A, p) - Return the symmetric permutation of A, which is "A[p,p]". A - should be symmetric and sparse, where only the upper triangular - part of the matrix is stored. This algorithm ignores the lower - triangular part of the matrix. Only the upper triangular part of - the result is returned as well. -``` +Return the symmetric permutation of A, which is "A[p,p]". A +should be symmetric and sparse, where only the upper triangular +part of the matrix is stored. This algorithm ignores the lower +triangular part of the matrix. Only the upper triangular part of +the result is returned as well. """ symperm doc""" -```rst -nonzeros(A) + nonzeros(A) - Return a vector of the structural nonzero values in sparse matrix - "A". This includes zeros that are explicitly stored in the sparse - matrix. The returned vector points directly to the internal nonzero - storage of "A", and any modifications to the returned vector will - mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". -``` +Return a vector of the structural nonzero values in sparse matrix +"A". This includes zeros that are explicitly stored in the sparse +matrix. The returned vector points directly to the internal nonzero +storage of "A", and any modifications to the returned vector will +mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". """ nonzeros doc""" -```rst -rowvals(A) + rowvals(A) - Return a vector of the row indices of "A", and any modifications - to the returned vector will mutate "A" as well. Given the - internal storage format of sparse matrices, providing access to how - the row indices are stored internally can be useful in conjuction - with iterating over structural nonzero values. See "nonzeros(A)" - and "nzrange(A, col)". -``` +Return a vector of the row indices of "A", and any modifications +to the returned vector will mutate "A" as well. Given the +internal storage format of sparse matrices, providing access to how +the row indices are stored internally can be useful in conjuction +with iterating over structural nonzero values. See "nonzeros(A)" +and "nzrange(A, col)". """ rowvals doc""" -```rst -nzrange(A, col) + nzrange(A, col) - Return the range of indices to the structural nonzero values of a - sparse matrix column. In conjunction with "nonzeros(A)" and - "rowvals(A)", this allows for convenient iterating over a sparse - matrix +Return the range of indices to the structural nonzero values of a +sparse matrix column. In conjunction with "nonzeros(A)" and +"rowvals(A)", 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 -``` + 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 """ nzrange doc""" -```rst -exit([code]) + exit([code]) - Quit (or control-D at the prompt). The default exit code is zero, - indicating that the processes completed successfully. -``` +Quit (or control-D at the prompt). The default exit code is zero, +indicating that the processes completed successfully. """ exit doc""" -```rst -quit() + quit() - Quit the program indicating that the processes completed - successfully. This function calls "exit(0)" (see "exit()"). -``` +Quit the program indicating that the processes completed +successfully. This function calls "exit(0)" (see "exit()"). """ quit doc""" -```rst -atexit(f) + atexit(f) - Register a zero-argument function to be called at exit. -``` +Register a zero-argument function to be called at exit. """ atexit doc""" -```rst -atreplinit(f) + atreplinit(f) - Register a one-argument function to be called before the REPL - interface is initialized in interactive sessions; this is useful to - customize the interface. The argument of "f" is the REPL object. - This function should be called from within the ".juliarc.jl" - initialization file. -``` +Register a one-argument function to be called before the REPL +interface is initialized in interactive sessions; this is useful to +customize the interface. The argument of "f" is the REPL object. +This function should be called from within the ".juliarc.jl" +initialization file. """ atreplinit doc""" -```rst -isinteractive() -> Bool + isinteractive() -> Bool - Determine whether Julia is running an interactive session. -``` +Determine whether Julia is running an interactive session. """ isinteractive doc""" -```rst -whos([Module,] [pattern::Regex]) + whos([Module,] [pattern::Regex]) - Print information about exported global variables in a module, - optionally restricted to those matching "pattern". -``` +Print information about exported global variables in a module, +optionally restricted to those matching "pattern". """ whos doc""" -```rst -edit(file::AbstractString[, line]) + edit(file::AbstractString[, line]) - Edit a file optionally providing a line number to edit at. Returns - to the julia prompt when you quit the editor. -``` +Edit a file optionally providing a line number to edit at. Returns +to the julia prompt when you quit the editor. """ edit doc""" -```rst -edit(function[, types]) + edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. -``` +Edit the definition of a function, optionally specifying a tuple of +types to indicate which method to edit. """ edit doc""" -```rst -@edit() + @edit() - Evaluates the arguments to the function call, determines their - types, and calls the "edit" function on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls the "edit" function on the resulting expression """ @edit doc""" -```rst -less(file::AbstractString[, line]) + less(file::AbstractString[, line]) - Show a file using the default pager, optionally providing a - starting line number. Returns to the julia prompt when you quit the - pager. -``` +Show a file using the default pager, optionally providing a +starting line number. Returns to the julia prompt when you quit the +pager. """ less doc""" -```rst -less(function[, types]) + less(function[, types]) - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. -``` +Show the definition of a function using the default pager, +optionally specifying a tuple of types to indicate which method to +see. """ less doc""" -```rst -@less() + @less() - Evaluates the arguments to the function call, determines their - types, and calls the "less" function on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls the "less" function on the resulting expression """ @less doc""" -```rst -clipboard(x) + clipboard(x) - Send a printed form of "x" to the operating system clipboard - ("copy"). -``` +Send a printed form of "x" to the operating system clipboard +("copy"). """ clipboard doc""" -```rst -clipboard() -> AbstractString + clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard - ("paste"). -``` +Return a string with the contents of the operating system clipboard +("paste"). """ clipboard doc""" -```rst -require(file::AbstractString...) + require(file::AbstractString...) - Load source files once, in the context of the "Main" module, on - every active node, searching standard locations for files. - "require" is considered a top-level operation, so it sets the - current "include" path but does not use it to search for files - (see help for "include"). This function is typically used to load - library code, and is implicitly called by "using" to load - packages. +Load source files once, in the context of the "Main" module, on +every active node, searching standard locations for files. +"require" is considered a top-level operation, so it sets the +current "include" path but does not use it to search for files +(see help for "include"). This function is typically used to load +library code, and is implicitly called by "using" to load +packages. - When searching for files, "require" first looks in the current - working directory, then looks for package code under "Pkg.dir()", - then tries paths in the global array "LOAD_PATH". -``` +When searching for files, "require" first looks in the current +working directory, then looks for package code under "Pkg.dir()", +then tries paths in the global array "LOAD_PATH". """ require doc""" -```rst -reload(file::AbstractString) + reload(file::AbstractString) - Like "require", except forces loading of files regardless of - whether they have been loaded before. Typically used when - interactively developing libraries. -``` +Like "require", except forces loading of files regardless of +whether they have been loaded before. Typically used when +interactively developing libraries. """ reload doc""" -```rst -include(path::AbstractString) + include(path::AbstractString) - Evaluate the contents of a source file in the current context. - During including, a task-local include path is set to the directory - containing the file. Nested calls to "include" will search - relative to that path. All paths refer to files on node 1 when - running in parallel, and files will be fetched from node 1. This - function is typically used to load source interactively, or to - combine files in packages that are broken into multiple source - files. -``` +Evaluate the contents of a source file in the current context. +During including, a task-local include path is set to the directory +containing the file. Nested calls to "include" will search +relative to that path. All paths refer to files on node 1 when +running in parallel, and files will be fetched from node 1. This +function is typically used to load source interactively, or to +combine files in packages that are broken into multiple source +files. """ include doc""" -```rst -include_string(code::AbstractString) + include_string(code::AbstractString) - Like "include", except reads code from the given string rather - than from a file. Since there is no file path involved, no path - processing or fetching from node 1 is done. -``` +Like "include", except reads code from the given string rather +than from a file. Since there is no file path involved, no path +processing or fetching from node 1 is done. """ include_string doc""" -```rst -which(f, types) + which(f, types) - Returns the method of "f" (a "Method" object) that would be - called for arguments of the given types. +Returns the method of "f" (a "Method" object) that would be +called for arguments of the given types. - If "types" is an abstract type, then the method that would be - called by "invoke" is returned. -``` +If "types" is an abstract type, then the method that would be +called by "invoke" is returned. """ which doc""" -```rst -which(symbol) + which(symbol) - Return the module in which the binding for the variable referenced - by "symbol" was created. -``` +Return the module in which the binding for the variable referenced +by "symbol" was created. """ which doc""" -```rst -@which() + @which() - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the "Method" object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the "which" function. -``` +Applied to a function call, it evaluates the arguments to the +specified function call, and returns the "Method" object for the +method that would be called for those arguments. Applied to a +variable, it returns the module in which the variable was bound. It +calls out to the "which" function. """ @which doc""" -```rst -methods(f[, types]) + methods(f[, types]) - Returns the method table for "f". +Returns the method table for "f". - If "types" is specified, returns an array of methods whose types - match. -``` +If "types" is specified, returns an array of methods whose types +match. """ methods doc""" -```rst -methodswith(typ[, module or function][, showparents]) + methodswith(typ[, module or function][, showparents]) - Return an array of methods with an argument of type "typ". If - optional "showparents" is "true", also return arguments with a - parent type of "typ", excluding type "Any". +Return an array of methods with an argument of type "typ". If +optional "showparents" is "true", also return arguments with a +parent type of "typ", excluding type "Any". - The optional second argument restricts the search to a particular - module or function. -``` +The optional second argument restricts the search to a particular +module or function. """ methodswith doc""" -```rst -@show() + @show() - Show an expression and result, returning the result -``` +Show an expression and result, returning the result """ @show doc""" -```rst -versioninfo([verbose::Bool]) + versioninfo([verbose::Bool]) - Print information about the version of Julia in use. If the - "verbose" argument is true, detailed system information is shown - as well. -``` +Print information about the version of Julia in use. If the +"verbose" argument is true, detailed system information is shown +as well. """ versioninfo doc""" -```rst -workspace() + workspace() - Replace the top-level module ("Main") with a new one, providing a - clean workspace. The previous "Main" module is made available as - "LastMain". A previously-loaded package can be accessed using a - statement such as "using LastMain.Package". +Replace the top-level module ("Main") with a new one, providing a +clean workspace. The previous "Main" module is made available as +"LastMain". A previously-loaded package can be accessed using a +statement such as "using LastMain.Package". - This function should only be used interactively. -``` +This function should only be used interactively. """ workspace doc""" -```rst -is(x, y) -> Bool + is(x, y) -> Bool ===(x, y) -> Bool ≡(x, y) -> Bool - Determine whether "x" and "y" are identical, in the sense that - no program could distinguish them. Compares mutable objects by - address in memory, and compares immutable objects (such as numbers) - by contents at the bit level. This function is sometimes called - "egal". -``` +Determine whether "x" and "y" are identical, in the sense that +no program could distinguish them. Compares mutable objects by +address in memory, and compares immutable objects (such as numbers) +by contents at the bit level. This function is sometimes called +"egal". """ is doc""" -```rst -isa(x, type) -> Bool + isa(x, type) -> Bool - Determine whether "x" is of the given "type". -``` +Determine whether "x" is of the given "type". """ isa doc""" -```rst -isequal(x, y) + isequal(x, y) - Similar to "==", except treats all floating-point "NaN" values - as equal to each other, and treats "-0.0" as unequal to "0.0". - The default implementation of "isequal" calls "==", so if you - have a type that doesn't have these floating-point subtleties then - you probably only need to define "==". +Similar to "==", except treats all floating-point "NaN" values +as equal to each other, and treats "-0.0" as unequal to "0.0". +The default implementation of "isequal" calls "==", so if you +have a type that doesn't have these floating-point subtleties then +you probably only need to define "==". - "isequal" is the comparison function used by hash tables - ("Dict"). "isequal(x,y)" must imply that "hash(x) == - hash(y)". +"isequal" is the comparison function used by hash tables +("Dict"). "isequal(x,y)" must imply that "hash(x) == +hash(y)". - This typically means that if you define your own "==" function - then you must define a corresponding "hash" (and vice versa). - Collections typically implement "isequal" by calling "isequal" - recursively on all contents. +This typically means that if you define your own "==" function +then you must define a corresponding "hash" (and vice versa). +Collections typically implement "isequal" by calling "isequal" +recursively on all contents. - Scalar types generally do not need to implement "isequal" - separate from "==", unless they represent floating-point numbers - amenable to a more efficient implementation than that provided as a - generic fallback (based on "isnan", "signbit", and "=="). -``` +Scalar types generally do not need to implement "isequal" +separate from "==", unless they represent floating-point numbers +amenable to a more efficient implementation than that provided as a +generic fallback (based on "isnan", "signbit", and "=="). """ isequal doc""" -```rst -isless(x, y) + isless(x, y) - Test whether "x" is less than "y", according to a canonical - total order. Values that are normally unordered, such as "NaN", - are ordered in an arbitrary but consistent fashion. This is the - default comparison used by "sort". Non-numeric types with a - canonical total order should implement this function. Numeric types - only need to implement it if they have special values such as - "NaN". -``` +Test whether "x" is less than "y", according to a canonical +total order. Values that are normally unordered, such as "NaN", +are ordered in an arbitrary but consistent fashion. This is the +default comparison used by "sort". Non-numeric types with a +canonical total order should implement this function. Numeric types +only need to implement it if they have special values such as +"NaN". """ isless doc""" -```rst -ifelse(condition::Bool, x, y) + ifelse(condition::Bool, x, y) - Return "x" if "condition" is true, otherwise return "y". This - differs from "?" or "if" in that it is an ordinary function, so - all the arguments are evaluated first. In some cases, using - "ifelse" instead of an "if" statement can eliminate the branch - in generated code and provide higher performance in tight loops. -``` +Return "x" if "condition" is true, otherwise return "y". This +differs from "?" or "if" in that it is an ordinary function, so +all the arguments are evaluated first. In some cases, using +"ifelse" instead of an "if" statement can eliminate the branch +in generated code and provide higher performance in tight loops. """ ifelse doc""" -```rst -lexcmp(x, y) + lexcmp(x, y) - Compare "x" and "y" lexicographically and return -1, 0, or 1 - depending on whether "x" is less than, equal to, or greater than - "y", respectively. This function should be defined for - lexicographically comparable types, and "lexless" will call - "lexcmp" by default. -``` +Compare "x" and "y" lexicographically and return -1, 0, or 1 +depending on whether "x" is less than, equal to, or greater than +"y", respectively. This function should be defined for +lexicographically comparable types, and "lexless" will call +"lexcmp" by default. """ lexcmp doc""" -```rst -lexless(x, y) + lexless(x, y) - Determine whether "x" is lexicographically less than "y". -``` +Determine whether "x" is lexicographically less than "y". """ lexless doc""" -```rst -typeof(x) + typeof(x) - Get the concrete type of "x". -``` +Get the concrete type of "x". """ typeof doc""" -```rst -tuple(xs...) + tuple(xs...) - Construct a tuple of the given objects. -``` +Construct a tuple of the given objects. """ tuple doc""" -```rst -ntuple(f::Function, n) + ntuple(f::Function, n) - Create a tuple of length "n", computing each element as "f(i)", - where "i" is the index of the element. -``` +Create a tuple of length "n", computing each element as "f(i)", +where "i" is the index of the element. """ ntuple doc""" -```rst -object_id(x) + object_id(x) - Get a unique integer id for "x". "object_id(x)==object_id(y)" - if and only if "is(x,y)". -``` +Get a unique integer id for "x". "object_id(x)==object_id(y)" +if and only if "is(x,y)". """ object_id doc""" -```rst -hash(x[, h]) + hash(x[, h]) - Compute an integer hash code such that "isequal(x,y)" implies - "hash(x)==hash(y)". The optional second argument "h" is a hash - code to be mixed with the result. +Compute an integer hash code such that "isequal(x,y)" implies +"hash(x)==hash(y)". The optional second argument "h" is a hash +code to be mixed with the result. - New types should implement the 2-argument form, typically by - calling the 2-argument "hash" method recursively in order to mix - hashes of the contents with each other (and with "h"). - Typically, any type that implements "hash" should also implement - its own "==" (hence "isequal") to guarantee the property - mentioned above. -``` +New types should implement the 2-argument form, typically by +calling the 2-argument "hash" method recursively in order to mix +hashes of the contents with each other (and with "h"). +Typically, any type that implements "hash" should also implement +its own "==" (hence "isequal") to guarantee the property +mentioned above. """ hash doc""" -```rst -finalizer(x, function) + finalizer(x, function) - Register a function "f(x)" to be called when there are no - program-accessible references to "x". The behavior of this - function is unpredictable if "x" is of a bits type. -``` +Register a function "f(x)" to be called when there are no +program-accessible references to "x". The behavior of this +function is unpredictable if "x" is of a bits type. """ finalizer doc""" -```rst -finalize(x) + finalize(x) - Immediately run finalizers registered for object "x". -``` +Immediately run finalizers registered for object "x". """ finalize doc""" -```rst -copy(x) + copy(x) - Create a shallow copy of "x": the outer structure is copied, but - not all internal values. For example, copying an array produces a - new array with identically-same elements as the original. -``` +Create a shallow copy of "x": the outer structure is copied, but +not all internal values. For example, copying an array produces a +new array with identically-same elements as the original. """ copy doc""" -```rst -deepcopy(x) + deepcopy(x) - Create a deep copy of "x": everything is copied recursively, - resulting in a fully independent object. For example, deep-copying - an array produces a new array whose elements are deep copies of the - original elements. Calling *deepcopy* on an object should generally - have the same effect as serializing and then deserializing it. +Create a deep copy of "x": everything is copied recursively, +resulting in a fully independent object. For example, deep-copying +an array produces a new array whose elements are deep copies of the +original elements. Calling *deepcopy* on an object should generally +have the same effect as serializing and then deserializing it. - As a special case, functions can only be actually deep-copied if - they are anonymous, otherwise they are just copied. The difference - is only relevant in the case of closures, i.e. functions which may - contain hidden internal references. +As a special case, functions can only be actually deep-copied if +they are anonymous, otherwise they are just copied. The difference +is only relevant in the case of closures, i.e. functions which may +contain hidden internal references. - While it isn't normally necessary, user-defined types can override - the default "deepcopy" behavior by defining a specialized version - of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" - (which shouldn't otherwise be used), where "T" is the type to be - specialized for, and "dict" keeps track of objects copied so far - within the recursion. Within the definition, "deepcopy_internal" - should be used in place of "deepcopy", and the "dict" variable - should be updated as appropriate before returning. -``` +While it isn't normally necessary, user-defined types can override +the default "deepcopy" behavior by defining a specialized version +of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" +(which shouldn't otherwise be used), where "T" is the type to be +specialized for, and "dict" keeps track of objects copied so far +within the recursion. Within the definition, "deepcopy_internal" +should be used in place of "deepcopy", and the "dict" variable +should be updated as appropriate before returning. """ deepcopy doc""" -```rst -isdefined([object], index | symbol) + isdefined([object], index | symbol) - Tests whether an assignable location is defined. The arguments can - be an array and index, a composite object and field name (as a - symbol), or a module and a symbol. With a single symbol argument, - tests whether a global variable with that name is defined in - "current_module()". -``` +Tests whether an assignable location is defined. The arguments can +be an array and index, a composite object and field name (as a +symbol), or a module and a symbol. With a single symbol argument, +tests whether a global variable with that name is defined in +"current_module()". """ isdefined doc""" -```rst -convert(T, x) + convert(T, x) - Convert "x" to a value of type "T". +Convert "x" to a value of type "T". - If "T" is an "Integer" type, an "InexactError" will be raised - if "x" is not representable by "T", for example if "x" is not - integer-valued, or is outside the range supported by "T". +If "T" is an "Integer" type, an "InexactError" will be raised +if "x" is not representable by "T", for example if "x" is not +integer-valued, or is outside the range supported by "T". - julia> convert(Int, 3.0) - 3 + julia> convert(Int, 3.0) + 3 - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 - If "T" is a "FloatingPoint" or "Rational" type, then it will - return the closest value to "x" representable by "T". +If "T" is a "FloatingPoint" or "Rational" type, then it will +return the closest value to "x" representable by "T". - julia> x = 1/3 - 0.3333333333333333 + julia> x = 1/3 + 0.3333333333333333 - julia> convert(Float32, x) - 0.33333334f0 + julia> convert(Float32, x) + 0.33333334f0 - julia> convert(Rational{Int32}, x) - 1//3 + julia> convert(Rational{Int32}, x) + 1//3 - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 -``` + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 """ convert doc""" -```rst -promote(xs...) + promote(xs...) - Convert all arguments to their common promotion type (if any), and - return them all (as a tuple). -``` +Convert all arguments to their common promotion type (if any), and +return them all (as a tuple). """ promote doc""" -```rst -oftype(x, y) + oftype(x, y) - Convert "y" to the type of "x" ("convert(typeof(x), y)"). -``` +Convert "y" to the type of "x" ("convert(typeof(x), y)"). """ oftype doc""" -```rst -widen(type | x) + widen(type | x) - If the argument is a type, return a "larger" type (for numeric - types, this will be a type with at least as much range and - precision as the argument, and usually more). Otherwise the - argument "x" is converted to "widen(typeof(x))". +If the argument is a type, return a "larger" type (for numeric +types, this will be a type with at least as much range and +precision as the argument, and usually more). Otherwise the +argument "x" is converted to "widen(typeof(x))". - julia> widen(Int32) - Int64 + julia> widen(Int32) + Int64 - julia> widen(1.5f0) - 1.5 -``` + julia> widen(1.5f0) + 1.5 """ widen doc""" -```rst -identity(x) + identity(x) - The identity function. Returns its argument. -``` +The identity function. Returns its argument. """ identity doc""" -```rst -super(T::DataType) + super(T::DataType) - Return the supertype of DataType T -``` +Return the supertype of DataType T """ super doc""" -```rst -issubtype(type1, type2) + issubtype(type1, type2) - True if and only if all values of "type1" are also of "type2". - Can also be written using the "<:" infix operator as "type1 <: - type2". -``` +True if and only if all values of "type1" are also of "type2". +Can also be written using the "<:" infix operator as "type1 <: +type2". """ issubtype doc""" -```rst -<:(T1, T2) + <:(T1, T2) - Subtype operator, equivalent to "issubtype(T1,T2)". -``` +Subtype operator, equivalent to "issubtype(T1,T2)". """ Base.(:(<:)) doc""" -```rst -subtypes(T::DataType) + subtypes(T::DataType) - Return a list of immediate subtypes of DataType T. Note that all - currently loaded subtypes are included, including those not visible - in the current module. -``` +Return a list of immediate subtypes of DataType T. Note that all +currently loaded subtypes are included, including those not visible +in the current module. """ subtypes doc""" -```rst -typemin(type) + typemin(type) - The lowest value representable by the given (real) numeric type. -``` +The lowest value representable by the given (real) numeric type. """ typemin doc""" -```rst -typemax(type) + typemax(type) - The highest value representable by the given (real) numeric type. -``` +The highest value representable by the given (real) numeric type. """ typemax doc""" -```rst -realmin(type) + realmin(type) - The smallest in absolute value non-subnormal value representable by - the given floating-point type -``` +The smallest in absolute value non-subnormal value representable by +the given floating-point type """ realmin doc""" -```rst -realmax(type) + realmax(type) - The highest finite value representable by the given floating-point - type -``` +The highest finite value representable by the given floating-point +type """ realmax doc""" -```rst -maxintfloat(type) + maxintfloat(type) - The largest integer losslessly representable by the given floating- - point type -``` +The largest integer losslessly representable by the given floating- +point type """ maxintfloat doc""" -```rst -sizeof(type) + sizeof(type) - Size, in bytes, of the canonical binary representation of the given - type, if any. -``` +Size, in bytes, of the canonical binary representation of the given +type, if any. """ sizeof doc""" -```rst -eps([type]) + eps([type]) - The distance between 1.0 and the next larger representable - floating-point value of "type". Only floating-point types are - sensible arguments. If "type" is omitted, then "eps(Float64)" - is returned. -``` +The distance between 1.0 and the next larger representable +floating-point value of "type". Only floating-point types are +sensible arguments. If "type" is omitted, then "eps(Float64)" +is returned. """ eps doc""" -```rst -eps(x) + eps(x) - The distance between "x" and the next larger representable - floating-point value of the same type as "x". -``` +The distance between "x" and the next larger representable +floating-point value of the same type as "x". """ eps doc""" -```rst -promote_type(type1, type2) + promote_type(type1, type2) - Determine a type big enough to hold values of each argument type - without loss, whenever possible. In some cases, where no type - exists to which both types can be promoted losslessly, some loss is - tolerated; for example, "promote_type(Int64,Float64)" returns - "Float64" even though strictly, not all "Int64" values can be - represented exactly as "Float64" values. -``` +Determine a type big enough to hold values of each argument type +without loss, whenever possible. In some cases, where no type +exists to which both types can be promoted losslessly, some loss is +tolerated; for example, "promote_type(Int64,Float64)" returns +"Float64" even though strictly, not all "Int64" values can be +represented exactly as "Float64" values. """ promote_type doc""" -```rst -promote_rule(type1, type2) + promote_rule(type1, type2) - Specifies what type should be used by "promote" when given values - of types "type1" and "type2". This function should not be - called directly, but should have definitions added to it for new - types as appropriate. -``` +Specifies what type should be used by "promote" when given values +of types "type1" and "type2". This function should not be +called directly, but should have definitions added to it for new +types as appropriate. """ promote_rule doc""" -```rst -getfield(value, name::Symbol) + getfield(value, name::Symbol) - Extract a named field from a value of composite type. The syntax - "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls - "getfield(a, b)". -``` +Extract a named field from a value of composite type. The syntax +"a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls +"getfield(a, b)". """ getfield doc""" -```rst -setfield!(value, name::Symbol, x) + setfield!(value, name::Symbol, x) - Assign "x" to a named field in "value" of composite type. The - syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax - "a.(b) = c" calls "setfield!(a, b, c)". -``` +Assign "x" to a named field in "value" of composite type. The +syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax +"a.(b) = c" calls "setfield!(a, b, c)". """ setfield! doc""" -```rst -fieldoffsets(type) + fieldoffsets(type) - The byte offset of each field of a type relative to the data start. - For example, we could use it in the following manner to summarize - information about a struct type: +The byte offset of each field of a type relative to the data start. +For example, we could use it in the following manner to summarize +information about a struct type: - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) -``` + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) """ fieldoffsets doc""" -```rst -fieldtype(type, name::Symbol | index::Int) + fieldtype(type, name::Symbol | index::Int) - Determine the declared type of a field (specified by name or index) - in a composite type. -``` +Determine the declared type of a field (specified by name or index) +in a composite type. """ fieldtype doc""" -```rst -isimmutable(v) + isimmutable(v) - True if value "v" is immutable. See *Immutable Composite Types* - for a discussion of immutability. Note that this function works on - values, so if you give it a type, it will tell you that a value of - "DataType" is mutable. -``` +True if value "v" is immutable. See *Immutable Composite Types* +for a discussion of immutability. Note that this function works on +values, so if you give it a type, it will tell you that a value of +"DataType" is mutable. """ isimmutable doc""" -```rst -isbits(T) + isbits(T) - True if "T" is a "plain data" type, meaning it is immutable and - contains no references to other values. Typical examples are - numeric types such as "UInt8", "Float64", and - "Complex{Float64}". +True if "T" is a "plain data" type, meaning it is immutable and +contains no references to other values. Typical examples are +numeric types such as "UInt8", "Float64", and +"Complex{Float64}". - julia> isbits(Complex{Float64}) - true + julia> isbits(Complex{Float64}) + true - julia> isbits(Complex) - false -``` + julia> isbits(Complex) + false """ isbits doc""" -```rst -isleaftype(T) + isleaftype(T) - Determine whether "T" is a concrete type that can have instances, - meaning its only subtypes are itself and "None" (but "T" itself - is not "None"). -``` +Determine whether "T" is a concrete type that can have instances, +meaning its only subtypes are itself and "None" (but "T" itself +is not "None"). """ isleaftype doc""" -```rst -typejoin(T, S) + typejoin(T, S) - Compute a type that contains both "T" and "S". -``` +Compute a type that contains both "T" and "S". """ typejoin doc""" -```rst -typeintersect(T, S) + typeintersect(T, S) - Compute a type that contains the intersection of "T" and "S". - Usually this will be the smallest such type or one close to it. -``` +Compute a type that contains the intersection of "T" and "S". +Usually this will be the smallest such type or one close to it. """ typeintersect doc""" -```rst -instances(T::Type) + instances(T::Type) - Return a collection of all instances of the given type, if - applicable. Mostly used for enumerated types (see "@enum"). -``` +Return a collection of all instances of the given type, if +applicable. Mostly used for enumerated types (see "@enum"). """ instances doc""" -```rst -method_exists(f, Tuple type) -> Bool + method_exists(f, Tuple type) -> Bool - Determine whether the given generic function has a method matching - the given "Tuple" of argument types. +Determine whether the given generic function has a method matching +the given "Tuple" of argument types. - julia> method_exists(length, Tuple{Array}) - true -``` + julia> method_exists(length, Tuple{Array}) + true """ method_exists doc""" -```rst -applicable(f, args...) -> Bool + applicable(f, args...) -> Bool - Determine whether the given generic function has a method - applicable to the given arguments. +Determine whether the given generic function has a method +applicable to the given arguments. - julia> function f(x, y) - x + y - end; + julia> function f(x, y) + x + y + end; - julia> applicable(f, 1) - false + julia> applicable(f, 1) + false - julia> applicable(f, 1, 2) - true -``` + julia> applicable(f, 1, 2) + true """ applicable doc""" -```rst -invoke(f, (types...), args...) + invoke(f, (types...), args...) - Invoke a method for the given generic function matching the - specified types (as a tuple), on the specified arguments. The - arguments must be compatible with the specified types. This allows - invoking a method other than the most specific matching method, - which is useful when the behavior of a more general definition is - explicitly needed (often as part of the implementation of a more - specific method of the same function). -``` +Invoke a method for the given generic function matching the +specified types (as a tuple), on the specified arguments. The +arguments must be compatible with the specified types. This allows +invoking a method other than the most specific matching method, +which is useful when the behavior of a more general definition is +explicitly needed (often as part of the implementation of a more +specific method of the same function). """ invoke doc""" -```rst -|>(x, f) + |>(x, f) - Applies a function to the preceding argument. This allows for easy - function chaining. +Applies a function to the preceding argument. This allows for easy +function chaining. - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 -``` + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 """ Base.(:(|>)) doc""" -```rst -call(x, args...) + call(x, args...) - If "x" is not a "Function", then "x(args...)" is equivalent - to "call(x, args...)". This means that function-like behavior - can be added to any type by defining new "call" methods. -``` +If "x" is not a "Function", then "x(args...)" is equivalent +to "call(x, args...)". This means that function-like behavior +can be added to any type by defining new "call" methods. """ call doc""" -```rst -eval([m::Module], expr::Expr) + eval([m::Module], expr::Expr) - Evaluate an expression in the given module and return the result. - Every module (except those defined with "baremodule") has its own - 1-argument definition of "eval", which evaluates expressions in - that module. -``` +Evaluate an expression in the given module and return the result. +Every module (except those defined with "baremodule") has its own +1-argument definition of "eval", which evaluates expressions in +that module. """ eval doc""" -```rst -@eval() + @eval() - Evaluate an expression and return the value. -``` +Evaluate an expression and return the value. """ @eval doc""" -```rst -evalfile(path::AbstractString) + evalfile(path::AbstractString) - Load the file using "include", evaluate all expressions, and - return the value of the last one. -``` +Load the file using "include", evaluate all expressions, and +return the value of the last one. """ evalfile doc""" -```rst -esc(e::ANY) + esc(e::ANY) - Only valid in the context of an Expr returned from a macro. - Prevents the macro hygiene pass from turning embedded variables - into gensym variables. See the *Macros* section of the - Metaprogramming chapter of the manual for more details and - examples. -``` +Only valid in the context of an Expr returned from a macro. +Prevents the macro hygiene pass from turning embedded variables +into gensym variables. See the *Macros* section of the +Metaprogramming chapter of the manual for more details and +examples. """ esc doc""" -```rst -gensym([tag]) + gensym([tag]) - Generates a symbol which will not conflict with other variable - names. -``` +Generates a symbol which will not conflict with other variable +names. """ gensym doc""" -```rst -@gensym() + @gensym() - Generates a gensym symbol for a variable. For example, "@gensym x - y" is transformed into "x = gensym("x"); y = gensym("y")". -``` +Generates a gensym symbol for a variable. For example, "@gensym x +y" is transformed into "x = gensym("x"); y = gensym("y")". """ @gensym doc""" -```rst -parse(str, start; greedy=true, raise=true) + parse(str, start; greedy=true, raise=true) - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If "greedy" is true (default), - "parse" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return "Expr(:incomplete, "(error message)")". If "raise" is - true (default), syntax errors other than incomplete expressions - will raise an error. If "raise" is false, "parse" will return - an expression that will raise an error upon evaluation. -``` +Parse the expression string and return an expression (which could +later be passed to eval for execution). Start is the index of the +first character to start parsing. If "greedy" is true (default), +"parse" will try to consume as much input as it can; otherwise, +it will stop as soon as it has parsed a valid expression. +Incomplete but otherwise syntactically valid expressions will +return "Expr(:incomplete, "(error message)")". If "raise" is +true (default), syntax errors other than incomplete expressions +will raise an error. If "raise" is false, "parse" will return +an expression that will raise an error upon evaluation. """ parse doc""" -```rst -parse(str; raise=true) + parse(str; raise=true) - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If "raise" is true (default), syntax errors will - raise an error; otherwise, "parse" will return an expression that - will raise an error upon evaluation. -``` +Parse the whole string greedily, returning a single expression. An +error is thrown if there are additional characters after the first +expression. If "raise" is true (default), syntax errors will +raise an error; otherwise, "parse" will return an expression that +will raise an error upon evaluation. """ parse doc""" -```rst -Nullable(x) + Nullable(x) - Wrap value "x" in an object of type "Nullable", which indicates - whether a value is present. "Nullable(x)" yields a non-empty - wrapper, and "Nullable{T}()" yields an empty instance of a - wrapper that might contain a value of type "T". -``` +Wrap value "x" in an object of type "Nullable", which indicates +whether a value is present. "Nullable(x)" yields a non-empty +wrapper, and "Nullable{T}()" yields an empty instance of a +wrapper that might contain a value of type "T". """ Nullable doc""" -```rst -get(x) + get(x) - Attempt to access the value of the "Nullable" object, "x". - Returns the value if it is present; otherwise, throws a - "NullException". -``` +Attempt to access the value of the "Nullable" object, "x". +Returns the value if it is present; otherwise, throws a +"NullException". """ get doc""" -```rst -get(x, y) + get(x, y) - Attempt to access the value of the "Nullable{T}" object, "x". - Returns the value if it is present; otherwise, returns "convert(T, - y)". -``` +Attempt to access the value of the "Nullable{T}" object, "x". +Returns the value if it is present; otherwise, returns "convert(T, +y)". """ get doc""" -```rst -isnull(x) + isnull(x) - Is the "Nullable" object "x" null, i.e. missing a value? -``` +Is the "Nullable" object "x" null, i.e. missing a value? """ isnull doc""" -```rst -run(command) + run(command) - Run a command object, constructed with backticks. Throws an error - if anything goes wrong, including the process exiting with a non- - zero status. -``` +Run a command object, constructed with backticks. Throws an error +if anything goes wrong, including the process exiting with a non- +zero status. """ run doc""" -```rst -spawn(command) + spawn(command) - Run a command object asynchronously, returning the resulting - "Process" object. -``` +Run a command object asynchronously, returning the resulting +"Process" object. """ spawn doc""" -```rst -DevNull + DevNull - Used in a stream redirect to discard all data written to it. - Essentially equivalent to /dev/null on Unix or NUL on Windows. - Usage: "run(`cat test.txt` |> DevNull)" -``` +Used in a stream redirect to discard all data written to it. +Essentially equivalent to /dev/null on Unix or NUL on Windows. +Usage: "run(`cat test.txt` |> DevNull)" """ DevNull doc""" -```rst -success(command) + success(command) - Run a command object, constructed with backticks, and tell whether - it was successful (exited with a code of 0). An exception is raised - if the process cannot be started. -``` +Run a command object, constructed with backticks, and tell whether +it was successful (exited with a code of 0). An exception is raised +if the process cannot be started. """ success doc""" -```rst -process_running(p::Process) + process_running(p::Process) - Determine whether a process is currently running. -``` +Determine whether a process is currently running. """ process_running doc""" -```rst -process_exited(p::Process) + process_exited(p::Process) - Determine whether a process has exited. -``` +Determine whether a process has exited. """ process_exited doc""" -```rst -kill(p::Process, signum=SIGTERM) + kill(p::Process, signum=SIGTERM) - Send a signal to a process. The default is to terminate the - process. -``` +Send a signal to a process. The default is to terminate the +process. """ kill doc""" -```rst -open(command, mode::AbstractString="r", stdio=DevNull) + open(command, mode::AbstractString="r", stdio=DevNull) - Start running "command" asynchronously, and return a tuple - "(stream,process)". If "mode" is ""r"", then "stream" - reads from the process's standard output and "stdio" optionally - specifies the process's standard input stream. If "mode" is - ""w"", then "stream" writes to the process's standard input - and "stdio" optionally specifies the process's standard output - stream. -``` +Start running "command" asynchronously, and return a tuple +"(stream,process)". If "mode" is ""r"", then "stream" +reads from the process's standard output and "stdio" optionally +specifies the process's standard input stream. If "mode" is +""w"", then "stream" writes to the process's standard input +and "stdio" optionally specifies the process's standard output +stream. """ open doc""" -```rst -open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) - Similar to "open(command, mode, stdio)", but calls "f(stream)" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - "f". -``` +Similar to "open(command, mode, stdio)", but calls "f(stream)" +on the resulting read or write stream, then closes the stream and +waits for the process to complete. Returns the value returned by +"f". """ open doc""" -```rst -Sys.set_process_title(title::AbstractString) + Sys.set_process_title(title::AbstractString) - Set the process title. No-op on some operating systems. (not - exported) -``` +Set the process title. No-op on some operating systems. (not +exported) """ Sys doc""" -```rst -Sys.get_process_title() + Sys.get_process_title() - Get the process title. On some systems, will always return empty - string. (not exported) -``` +Get the process title. On some systems, will always return empty +string. (not exported) """ Sys doc""" -```rst -readandwrite(command) + readandwrite(command) - Starts running a command asynchronously, and returns a tuple - (stdout,stdin,process) of the output stream and input stream of the - process, and the process object itself. -``` +Starts running a command asynchronously, and returns a tuple +(stdout,stdin,process) of the output stream and input stream of the +process, and the process object itself. """ readandwrite doc""" -```rst -ignorestatus(command) + ignorestatus(command) - Mark a command object so that running it will not throw an error if - the result code is non-zero. -``` +Mark a command object so that running it will not throw an error if +the result code is non-zero. """ ignorestatus doc""" -```rst -detach(command) + detach(command) - Mark a command object so that it will be run in a new process - group, allowing it to outlive the julia process, and not have - Ctrl-C interrupts passed to it. -``` +Mark a command object so that it will be run in a new process +group, allowing it to outlive the julia process, and not have +Ctrl-C interrupts passed to it. """ detach doc""" -```rst -setenv(command, env; dir=working_dir) + setenv(command, env; dir=working_dir) - Set environment variables to use when running the given command. - "env" is either a dictionary mapping strings to strings, an array - of strings of the form ""var=val"", or zero or more - ""var"=>val" pair arguments. In order to modify (rather than - replace) the existing environment, create "env" by "copy(ENV)" - and then setting "env["var"]=val" as desired, or use - "withenv". +Set environment variables to use when running the given command. +"env" is either a dictionary mapping strings to strings, an array +of strings of the form ""var=val"", or zero or more +""var"=>val" pair arguments. In order to modify (rather than +replace) the existing environment, create "env" by "copy(ENV)" +and then setting "env["var"]=val" as desired, or use +"withenv". - The "dir" keyword argument can be used to specify a working - directory for the command. -``` +The "dir" keyword argument can be used to specify a working +directory for the command. """ setenv doc""" -```rst -withenv(f::Function, kv::Pair...) + withenv(f::Function, kv::Pair...) - Execute "f()" in an environment that is temporarily modified (not - replaced as in "setenv") by zero or more ""var"=>val" - arguments "kv". "withenv" is generally used via the - "withenv(kv...) do ... end" syntax. A value of "nothing" can - be used to temporarily unset an environment variable (if it is - set). When "withenv" returns, the original environment has been - restored. -``` +Execute "f()" in an environment that is temporarily modified (not +replaced as in "setenv") by zero or more ""var"=>val" +arguments "kv". "withenv" is generally used via the +"withenv(kv...) do ... end" syntax. A value of "nothing" can +be used to temporarily unset an environment variable (if it is +set). When "withenv" returns, the original environment has been +restored. """ withenv doc""" -```rst -pipe(from, to, ...) + pipe(from, to, ...) - Create a pipeline from a data source to a destination. The source - and destination can be commands, I/O streams, strings, or results - of other "pipe" calls. At least one argument must be a command. - Strings refer to filenames. When called with more than two - arguments, they are chained together from left to right. For - example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". - This provides a more concise way to specify multi-stage pipelines. +Create a pipeline from a data source to a destination. The source +and destination can be commands, I/O streams, strings, or results +of other "pipe" calls. At least one argument must be a command. +Strings refer to filenames. When called with more than two +arguments, they are chained together from left to right. For +example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". +This provides a more concise way to specify multi-stage pipelines. - **Examples**: - * "run(pipe(`ls`, `grep xyz`))" +**Examples**: + * "run(pipe(`ls`, `grep xyz`))" - * "run(pipe(`ls`, "out.txt"))" + * "run(pipe(`ls`, "out.txt"))" - * "run(pipe("out.txt", `grep xyz`))" -``` + * "run(pipe("out.txt", `grep xyz`))" """ pipe doc""" -```rst -pipe(command; stdin, stdout, stderr, append=false) + pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given "command". Keyword arguments - specify which of the command's streams should be redirected. - "append" controls whether file output appends to the file. This - is a more general version of the 2-argument "pipe" function. - "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when - "from" is a command, and to "pipe(to, stdin=from)" when - "from" is another kind of data source. +Redirect I/O to or from the given "command". Keyword arguments +specify which of the command's streams should be redirected. +"append" controls whether file output appends to the file. This +is a more general version of the 2-argument "pipe" function. +"pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when +"from" is a command, and to "pipe(to, stdin=from)" when +"from" is another kind of data source. - **Examples**: - * "run(pipe(`dothings`, stdout="out.txt", - stderr="errs.txt"))" +**Examples**: + * "run(pipe(`dothings`, stdout="out.txt", + stderr="errs.txt"))" - * "run(pipe(`update`, stdout="log.txt", append=true))" -``` + * "run(pipe(`update`, stdout="log.txt", append=true))" """ pipe doc""" -```rst -gethostname() -> AbstractString + gethostname() -> AbstractString - Get the local machine's host name. -``` +Get the local machine's host name. """ gethostname doc""" -```rst -getipaddr() -> AbstractString + getipaddr() -> AbstractString - Get the IP address of the local machine, as a string of the form - "x.x.x.x". -``` +Get the IP address of the local machine, as a string of the form +"x.x.x.x". """ getipaddr doc""" -```rst -getpid() -> Int32 + getpid() -> Int32 - Get julia's process ID. -``` +Get julia's process ID. """ getpid doc""" -```rst -time() + time() - Get the system time in seconds since the epoch, with fairly high - (typically, microsecond) resolution. -``` +Get the system time in seconds since the epoch, with fairly high +(typically, microsecond) resolution. """ time doc""" -```rst -time_ns() + time_ns() - Get the time in nanoseconds. The time corresponding to 0 is - undefined, and wraps every 5.8 years. -``` +Get the time in nanoseconds. The time corresponding to 0 is +undefined, and wraps every 5.8 years. """ time_ns doc""" -```rst -tic() + tic() - Set a timer to be read by the next call to "toc()" or "toq()". - The macro call "@time expr" can also be used to time evaluation. -``` +Set a timer to be read by the next call to "toc()" or "toq()". +The macro call "@time expr" can also be used to time evaluation. """ tic doc""" -```rst -toc() + toc() - Print and return the time elapsed since the last "tic()". -``` +Print and return the time elapsed since the last "tic()". """ toc doc""" -```rst -toq() + toq() - Return, but do not print, the time elapsed since the last - "tic()". -``` +Return, but do not print, the time elapsed since the last +"tic()". """ toq doc""" -```rst -@time() + @time() - A macro to execute an expression, printing the time it took to - execute, the number of allocations, and the total number of bytes - its execution caused to be allocated, before returning the value of - the expression. -``` +A macro to execute an expression, printing the time it took to +execute, the number of allocations, and the total number of bytes +its execution caused to be allocated, before returning the value of +the expression. """ @time doc""" -```rst -@timev() + @timev() - This is a verbose version of the "@time" macro, it first prints - the same information as "@time", then any non-zero memory - allocation counters, and then returns the value of the expression. -``` +This is a verbose version of the "@time" macro, it first prints +the same information as "@time", then any non-zero memory +allocation counters, and then returns the value of the expression. """ @timev doc""" -```rst -@timed() + @timed() - A macro to execute an expression, and return the value of the - expression, elapsed time, total bytes allocated, garbage collection - time, and an object with various memory allocation counters. -``` +A macro to execute an expression, and return the value of the +expression, elapsed time, total bytes allocated, garbage collection +time, and an object with various memory allocation counters. """ @timed doc""" -```rst -@elapsed() + @elapsed() - A macro to evaluate an expression, discarding the resulting value, - instead returning the number of seconds it took to execute as a - floating-point number. -``` +A macro to evaluate an expression, discarding the resulting value, +instead returning the number of seconds it took to execute as a +floating-point number. """ @elapsed doc""" -```rst -@allocated() + @allocated() - A macro to evaluate an expression, discarding the resulting value, - instead returning the total number of bytes allocated during - evaluation of the expression. Note: the expression is evaluated - inside a local function, instead of the current context, in order - to eliminate the effects of compilation, however, there still may - be some allocations due to JIT compilation. This also makes the - results inconsistent with the "@time" macros, which do not try to - adjust for the effects of compilation. -``` +A macro to evaluate an expression, discarding the resulting value, +instead returning the total number of bytes allocated during +evaluation of the expression. Note: the expression is evaluated +inside a local function, instead of the current context, in order +to eliminate the effects of compilation, however, there still may +be some allocations due to JIT compilation. This also makes the +results inconsistent with the "@time" macros, which do not try to +adjust for the effects of compilation. """ @allocated doc""" -```rst -EnvHash() -> EnvHash + EnvHash() -> EnvHash - A singleton of this type provides a hash table interface to - environment variables. -``` +A singleton of this type provides a hash table interface to +environment variables. """ EnvHash doc""" -```rst -ENV + ENV - Reference to the singleton "EnvHash", providing a dictionary - interface to system environment variables. -``` +Reference to the singleton "EnvHash", providing a dictionary +interface to system environment variables. """ ENV doc""" -```rst -@unix() + @unix() - Given "@unix? a : b", do "a" on Unix systems (including Linux - and OS X) and "b" elsewhere. See documentation for Handling - Platform Variations in the Calling C and Fortran Code section of - the manual. -``` +Given "@unix? a : b", do "a" on Unix systems (including Linux +and OS X) and "b" elsewhere. See documentation for Handling +Platform Variations in the Calling C and Fortran Code section of +the manual. """ @unix doc""" -```rst -@osx() + @osx() - Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. -``` +Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See +documentation for Handling Platform Variations in the Calling C and +Fortran Code section of the manual. """ @osx doc""" -```rst -@linux() + @linux() - Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. -``` +Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See +documentation for Handling Platform Variations in the Calling C and +Fortran Code section of the manual. """ @linux doc""" -```rst -@windows() + @windows() - Given "@windows? a : b", do "a" on Windows and "b" elsewhere. - See documentation for Handling Platform Variations in the Calling C - and Fortran Code section of the manual. -``` +Given "@windows? a : b", do "a" on Windows and "b" elsewhere. +See documentation for Handling Platform Variations in the Calling C +and Fortran Code section of the manual. """ @windows doc""" -```rst -error(message::AbstractString) + error(message::AbstractString) - Raise an "ErrorException" with the given message -``` +Raise an "ErrorException" with the given message """ error doc""" -```rst -throw(e) + throw(e) - Throw an object as an exception -``` +Throw an object as an exception """ throw doc""" -```rst -rethrow([e]) + rethrow([e]) - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - "catch" block). -``` +Throw an object without changing the current exception backtrace. +The default argument is the current exception (if called within a +"catch" block). """ rethrow doc""" -```rst -backtrace() + backtrace() - Get a backtrace object for the current program point. -``` +Get a backtrace object for the current program point. """ backtrace doc""" -```rst -catch_backtrace() + catch_backtrace() - Get the backtrace of the current exception, for use within - "catch" blocks. -``` +Get the backtrace of the current exception, for use within +"catch" blocks. """ catch_backtrace doc""" -```rst -assert(cond) + assert(cond) - Throw an "AssertionError" if "cond" is false. Also available as - the macro "@assert expr". -``` +Throw an "AssertionError" if "cond" is false. Also available as +the macro "@assert expr". """ assert doc""" -```rst -ArgumentError(msg) + ArgumentError(msg) - The parameters to a function call do not match a valid signature. -``` +The parameters to a function call do not match a valid signature. """ ArgumentError doc""" -```rst -AssertionError([msg]) + AssertionError([msg]) - The asserted condition did not evalutate to "true". -``` +The asserted condition did not evalutate to "true". """ AssertionError doc""" -```rst -BoundsError([a][, i]) + BoundsError([a][, i]) - An indexing operation into an array, "a", tried to access an out- - of-bounds element, "i". -``` +An indexing operation into an array, "a", tried to access an out- +of-bounds element, "i". """ BoundsError doc""" -```rst -DimensionMismatch([msg]) + DimensionMismatch([msg]) - The objects called do not have matching dimensionality. -``` +The objects called do not have matching dimensionality. """ DimensionMismatch doc""" -```rst -DivideError() + DivideError() - Integer division was attempted with a denominator value of 0. -``` +Integer division was attempted with a denominator value of 0. """ DivideError doc""" -```rst -DomainError() + DomainError() - The arguments to a function or constructor are outside the valid - domain. -``` +The arguments to a function or constructor are outside the valid +domain. """ DomainError doc""" -```rst -EOFError() + EOFError() - No more data was available to read from a file or stream. -``` +No more data was available to read from a file or stream. """ EOFError doc""" -```rst -ErrorException(msg) + ErrorException(msg) - Generic error type. The error message, in the *.msg* field, may - provide more specific details. -``` +Generic error type. The error message, in the *.msg* field, may +provide more specific details. """ ErrorException doc""" -```rst -InexactError() + InexactError() - Type conversion cannot be done exactly. -``` +Type conversion cannot be done exactly. """ InexactError doc""" -```rst -InterruptException() + InterruptException() - The process was stopped by a terminal interrupt (CTRL+C). -``` +The process was stopped by a terminal interrupt (CTRL+C). """ InterruptException doc""" -```rst -KeyError(key) + KeyError(key) - An indexing operation into an "Associative" ("Dict") or "Set" - like object tried to access or delete a non-existent element. -``` +An indexing operation into an "Associative" ("Dict") or "Set" +like object tried to access or delete a non-existent element. """ KeyError doc""" -```rst -LoadError(file::AbstractString, line::Int, error) + LoadError(file::AbstractString, line::Int, error) - An error occurred while *including*, *requiring*, or *using* a - file. The error specifics should be available in the *.error* - field. -``` +An error occurred while *including*, *requiring*, or *using* a +file. The error specifics should be available in the *.error* +field. """ LoadError doc""" -```rst -MethodError(f, args) + MethodError(f, args) - A method with the required type signature does not exist in the - given generic function. -``` +A method with the required type signature does not exist in the +given generic function. """ MethodError doc""" -```rst -NullException() + NullException() - An attempted access to a "Nullable" with no defined value. -``` +An attempted access to a "Nullable" with no defined value. """ NullException doc""" -```rst -OutOfMemoryError() + OutOfMemoryError() - An operation allocated too much memory for either the system or the - garbage collector to handle properly. -``` +An operation allocated too much memory for either the system or the +garbage collector to handle properly. """ OutOfMemoryError doc""" -```rst -ReadOnlyMemoryError() + ReadOnlyMemoryError() - An operation tried to write to memory that is read-only. -``` +An operation tried to write to memory that is read-only. """ ReadOnlyMemoryError doc""" -```rst -OverflowError() + OverflowError() - The result of an expression is too large for the specified type and - will cause a wraparound. -``` +The result of an expression is too large for the specified type and +will cause a wraparound. """ OverflowError doc""" -```rst -ParseError(msg) + ParseError(msg) - The expression passed to the *parse* function could not be - interpreted as a valid Julia expression. -``` +The expression passed to the *parse* function could not be +interpreted as a valid Julia expression. """ ParseError doc""" -```rst -ProcessExitedException() + ProcessExitedException() - After a client Julia process has exited, further attempts to - reference the dead child will throw this exception. -``` +After a client Julia process has exited, further attempts to +reference the dead child will throw this exception. """ ProcessExitedException doc""" -```rst -StackOverflowError() + StackOverflowError() - The function call grew beyond the size of the call stack. This - usually happens when a call recurses infinitely. -``` +The function call grew beyond the size of the call stack. This +usually happens when a call recurses infinitely. """ StackOverflowError doc""" -```rst -SystemError(prefix::AbstractString[, errnum::Int32]) + SystemError(prefix::AbstractString[, errnum::Int32]) - A system call failed with an error code (in the "errno" global - variable). -``` +A system call failed with an error code (in the "errno" global +variable). """ SystemError doc""" -```rst -TypeError(func::Symbol, context::AbstractString, expected::Type, got) + TypeError(func::Symbol, context::AbstractString, expected::Type, got) - A type assertion failure, or calling an intrinsic function with an - incorrect argument type. -``` +A type assertion failure, or calling an intrinsic function with an +incorrect argument type. """ TypeError doc""" -```rst -UndefRefError() + UndefRefError() - The item or field is not defined for the given object. -``` +The item or field is not defined for the given object. """ UndefRefError doc""" -```rst -UndefVarError(var::Symbol) + UndefVarError(var::Symbol) - A symbol in the current scope is not defined. -``` +A symbol in the current scope is not defined. """ UndefVarError doc""" -```rst -Timer(callback::Function, delay, repeat=0) + Timer(callback::Function, delay, repeat=0) - Create a timer to call the given callback function. The callback is - passed one argument, the timer object itself. The callback will be - invoked after the specified initial delay, and then repeating with - the given "repeat" interval. If "repeat" is "0", the timer is - only triggered once. Times are in seconds. A timer is stopped and - has its resources freed by calling "close" on it. -``` +Create a timer to call the given callback function. The callback is +passed one argument, the timer object itself. The callback will be +invoked after the specified initial delay, and then repeating with +the given "repeat" interval. If "repeat" is "0", the timer is +only triggered once. Times are in seconds. A timer is stopped and +has its resources freed by calling "close" on it. """ Timer doc""" -```rst -Timer(delay, repeat=0) + Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling - "wait" on the timer object) at a specified interval. -``` +Create a timer that wakes up tasks waiting for it (by calling +"wait" on the timer object) at a specified interval. """ Timer doc""" -```rst -module_name(m::Module) -> Symbol + module_name(m::Module) -> Symbol - Get the name of a module as a symbol. -``` +Get the name of a module as a symbol. """ module_name doc""" -```rst -module_parent(m::Module) -> Module + module_parent(m::Module) -> Module - Get a module's enclosing module. "Main" is its own parent. -``` +Get a module's enclosing module. "Main" is its own parent. """ module_parent doc""" -```rst -current_module() -> Module + current_module() -> Module - Get the *dynamically* current module, which is the module code is - currently being read from. In general, this is not the same as the - module containing the call to this function. -``` +Get the *dynamically* current module, which is the module code is +currently being read from. In general, this is not the same as the +module containing the call to this function. """ current_module doc""" -```rst -fullname(m::Module) + fullname(m::Module) - Get the fully-qualified name of a module as a tuple of symbols. For - example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and - "fullname(Main)" gives "()". -``` +Get the fully-qualified name of a module as a tuple of symbols. For +example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and +"fullname(Main)" gives "()". """ fullname doc""" -```rst -names(x::Module[, all=false[, imported=false]]) + names(x::Module[, all=false[, imported=false]]) - Get an array of the names exported by a module, with optionally - more module globals according to the additional parameters. -``` +Get an array of the names exported by a module, with optionally +more module globals according to the additional parameters. """ names doc""" -```rst -nfields(x::DataType) -> Int + nfields(x::DataType) -> Int - Get the number of fields of a data type. -``` +Get the number of fields of a data type. """ nfields doc""" -```rst -fieldnames(x::DataType) + fieldnames(x::DataType) - Get an array of the fields of a data type. -``` +Get an array of the fields of a data type. """ fieldnames doc""" -```rst -isconst([m::Module], s::Symbol) -> Bool + isconst([m::Module], s::Symbol) -> Bool - Determine whether a global is declared "const" in a given module. - The default module argument is "current_module()". -``` +Determine whether a global is declared "const" in a given module. +The default module argument is "current_module()". """ isconst doc""" -```rst -isgeneric(f::Function) -> Bool + isgeneric(f::Function) -> Bool - Determine whether a function is generic. -``` +Determine whether a function is generic. """ isgeneric doc""" -```rst -function_name(f::Function) -> Symbol + function_name(f::Function) -> Symbol - Get the name of a generic function as a symbol, or ":anonymous". -``` +Get the name of a generic function as a symbol, or ":anonymous". """ function_name doc""" -```rst -function_module(f::Function, types) -> Module + function_module(f::Function, types) -> Module - Determine the module containing a given definition of a generic - function. -``` +Determine the module containing a given definition of a generic +function. """ function_module doc""" -```rst -functionloc(f::Function, types) + functionloc(f::Function, types) - Returns a tuple "(filename,line)" giving the location of a method - definition. -``` +Returns a tuple "(filename,line)" giving the location of a method +definition. """ functionloc doc""" -```rst -functionloc(m::Method) + functionloc(m::Method) - Returns a tuple "(filename,line)" giving the location of a method - definition. -``` +Returns a tuple "(filename,line)" giving the location of a method +definition. """ functionloc doc""" -```rst -gc() + gc() - Perform garbage collection. This should not generally be used. -``` +Perform garbage collection. This should not generally be used. """ gc doc""" -```rst -gc_enable(on::Bool) + gc_enable(on::Bool) - Control whether garbage collection is enabled using a boolean - argument (true for enabled, false for disabled). Returns previous - GC state. Disabling garbage collection should be used only with - extreme caution, as it can cause memory use to grow without bound. -``` +Control whether garbage collection is enabled using a boolean +argument (true for enabled, false for disabled). Returns previous +GC state. Disabling garbage collection should be used only with +extreme caution, as it can cause memory use to grow without bound. """ gc_enable doc""" -```rst -macroexpand(x) + macroexpand(x) - Takes the expression x and returns an equivalent expression with - all macros removed (expanded). -``` +Takes the expression x and returns an equivalent expression with +all macros removed (expanded). """ macroexpand doc""" -```rst -expand(x) + expand(x) - Takes the expression x and returns an equivalent expression in - lowered form -``` +Takes the expression x and returns an equivalent expression in +lowered form """ expand doc""" -```rst -code_lowered(f, types) + code_lowered(f, types) - Returns an array of lowered ASTs for the methods matching the given - generic function and type signature. -``` +Returns an array of lowered ASTs for the methods matching the given +generic function and type signature. """ code_lowered doc""" -```rst -@code_lowered() + @code_lowered() - Evaluates the arguments to the function call, determines their - types, and calls "code_lowered()" on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls "code_lowered()" on the resulting expression """ @code_lowered doc""" -```rst -code_typed(f, types; optimize=true) + code_typed(f, types; optimize=true) - Returns an array of lowered and type-inferred ASTs for the methods - matching the given generic function and type signature. The keyword - argument "optimize" controls whether additional optimizations, - such as inlining, are also applied. -``` +Returns an array of lowered and type-inferred ASTs for the methods +matching the given generic function and type signature. The keyword +argument "optimize" controls whether additional optimizations, +such as inlining, are also applied. """ code_typed doc""" -```rst -@code_typed() + @code_typed() - Evaluates the arguments to the function call, determines their - types, and calls "code_typed()" on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls "code_typed()" on the resulting expression """ @code_typed doc""" -```rst -code_warntype(f, types) + code_warntype(f, types) - Displays lowered and type-inferred ASTs for the methods matching - the given generic function and type signature. The ASTs are - annotated in such a way as to cause "non-leaf" types to be - emphasized (if color is available, displayed in red). This serves - as a warning of potential type instability. Not all non-leaf types - are particularly problematic for performance, so the results need - to be used judiciously. See *@code_warntype* for more information. -``` +Displays lowered and type-inferred ASTs for the methods matching +the given generic function and type signature. The ASTs are +annotated in such a way as to cause "non-leaf" types to be +emphasized (if color is available, displayed in red). This serves +as a warning of potential type instability. Not all non-leaf types +are particularly problematic for performance, so the results need +to be used judiciously. See *@code_warntype* for more information. """ code_warntype doc""" -```rst -@code_warntype() + @code_warntype() - Evaluates the arguments to the function call, determines their - types, and calls "code_warntype()" on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls "code_warntype()" on the resulting expression """ @code_warntype doc""" -```rst -code_llvm(f, types) + code_llvm(f, types) - Prints the LLVM bitcodes generated for running the method matching - the given generic function and type signature to "STDOUT". +Prints the LLVM bitcodes generated for running the method matching +the given generic function and type signature to "STDOUT". - All metadata and dbg.* calls are removed from the printed bitcode. - Use code_llvm_raw for the full IR. -``` +All metadata and dbg.* calls are removed from the printed bitcode. +Use code_llvm_raw for the full IR. """ code_llvm doc""" -```rst -@code_llvm() + @code_llvm() - Evaluates the arguments to the function call, determines their - types, and calls "code_llvm()" on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls "code_llvm()" on the resulting expression """ @code_llvm doc""" -```rst -code_native(f, types) + code_native(f, types) - Prints the native assembly instructions generated for running the - method matching the given generic function and type signature to - STDOUT. -``` +Prints the native assembly instructions generated for running the +method matching the given generic function and type signature to +STDOUT. """ code_native doc""" -```rst -@code_native() + @code_native() - Evaluates the arguments to the function call, determines their - types, and calls "code_native()" on the resulting expression -``` +Evaluates the arguments to the function call, determines their +types, and calls "code_native()" on the resulting expression """ @code_native doc""" -```rst -precompile(f, args::Tuple{Vararg{Any}}) + precompile(f, args::Tuple{Vararg{Any}}) - Compile the given function "f" for the argument tuple (of types) - "args", but do not execute it. -``` +Compile the given function "f" for the argument tuple (of types) +"args", but do not execute it. """ precompile doc""" -```rst -ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) + ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - Call function in C-exported shared library, specified by - "(function name, library)" tuple, where each component is an - AbstractString or :Symbol. +Call function in C-exported shared library, specified by +"(function name, library)" tuple, where each component is an +AbstractString or :Symbol. - Note that the argument type tuple must be a literal tuple, and not - a tuple-valued variable or expression. Alternatively, ccall may - also be used to call a function pointer, such as one returned by - dlsym. +Note that the argument type tuple must be a literal tuple, and not +a tuple-valued variable or expression. Alternatively, ccall may +also be used to call a function pointer, such as one returned by +dlsym. - Each "ArgumentValue" to the "ccall" will be converted to the - corresponding "ArgumentType", by automatic insertion of calls to - "unsafe_convert(ArgumentType, cconvert(ArgumentType, - ArgumentValue))". (see also the documentation for each of these - functions for further details). In most cases, this simply results - in a call to "convert(ArgumentType, ArgumentValue)" -``` +Each "ArgumentValue" to the "ccall" will be converted to the +corresponding "ArgumentType", by automatic insertion of calls to +"unsafe_convert(ArgumentType, cconvert(ArgumentType, +ArgumentValue))". (see also the documentation for each of these +functions for further details). In most cases, this simply results +in a call to "convert(ArgumentType, ArgumentValue)" """ Base.ccall doc""" -```rst -cglobal((symbol, library)[, type=Void]) + cglobal((symbol, library)[, type=Void]) - Obtain a pointer to a global variable in a C-exported shared - library, specified exactly as in "ccall". Returns a - "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is - supplied. The values can be read or written by "unsafe_load" or - "unsafe_store!", respectively. -``` +Obtain a pointer to a global variable in a C-exported shared +library, specified exactly as in "ccall". Returns a +"Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is +supplied. The values can be read or written by "unsafe_load" or +"unsafe_store!", respectively. """ cglobal doc""" -```rst -cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - Generate C-callable function pointer from Julia function. Type - annotation of the return value in the callback function is a must - for situations where Julia cannot infer the return type - automatically. +Generate C-callable function pointer from Julia function. Type +annotation of the return value in the callback function is a must +for situations where Julia cannot infer the return type +automatically. - For example: +For example: - function foo() - # body + function foo() + # body - retval::Float64 - end + retval::Float64 + end - bar = cfunction(foo, Float64, ()) -``` + bar = cfunction(foo, Float64, ()) """ cfunction doc""" -```rst -unsafe_convert(T, x) + unsafe_convert(T, x) - Convert "x" to a value of type "T" +Convert "x" to a value of type "T" - In cases where "convert" would need to take a Julia object and - turn it into a "Ptr", this function should be used to define and - perform that conversion. +In cases where "convert" would need to take a Julia object and +turn it into a "Ptr", this function should be used to define and +perform that conversion. - Be careful to ensure that a julia reference to "x" exists as long - as the result of this function will be used. Accordingly, the - argument "x" to this function should never be an expression, only - a variable name or field reference. For example, "x=a.b.c" is - acceptable, but "x=[a,b,c]" is not. +Be careful to ensure that a julia reference to "x" exists as long +as the result of this function will be used. Accordingly, the +argument "x" to this function should never be an expression, only +a variable name or field reference. For example, "x=a.b.c" is +acceptable, but "x=[a,b,c]" is not. - The "unsafe" prefix on this function indicates that using the - result of this function after the "x" argument to this function - is no longer accessible to the program may cause undefined - behavior, including program corruption or segfaults, at any later - time. -``` +The "unsafe" prefix on this function indicates that using the +result of this function after the "x" argument to this function +is no longer accessible to the program may cause undefined +behavior, including program corruption or segfaults, at any later +time. """ unsafe_convert doc""" -```rst -cconvert(T, x) + cconvert(T, x) - Convert "x" to a value of type "T", typically by calling - "convert(T,x)" +Convert "x" to a value of type "T", typically by calling +"convert(T,x)" - In cases where "x" cannot be safely converted to "T", unlike - "convert", "cconvert" may return an object of a type different - from "T", which however is suitable for "unsafe_convert" to - handle. +In cases where "x" cannot be safely converted to "T", unlike +"convert", "cconvert" may return an object of a type different +from "T", which however is suitable for "unsafe_convert" to +handle. - Neither "convert" nor "cconvert" should take a Julia object and - turn it into a "Ptr". -``` +Neither "convert" nor "cconvert" should take a Julia object and +turn it into a "Ptr". """ cconvert doc""" -```rst -unsafe_load(p::Ptr{T}, i::Integer) + unsafe_load(p::Ptr{T}, i::Integer) - Load a value of type "T" from the address of the ith element - (1-indexed) starting at "p". This is equivalent to the C - expression "p[i-1]". +Load a value of type "T" from the address of the ith element +(1-indexed) starting at "p". This is equivalent to the C +expression "p[i-1]". - The "unsafe" prefix on this function indicates that no validation - is performed on the pointer "p" to ensure that it is valid. - Incorrect usage may segfault your program or return garbage - answers, in the same manner as C. -``` +The "unsafe" prefix on this function indicates that no validation +is performed on the pointer "p" to ensure that it is valid. +Incorrect usage may segfault your program or return garbage +answers, in the same manner as C. """ unsafe_load doc""" -```rst -unsafe_store!(p::Ptr{T}, x, i::Integer) + unsafe_store!(p::Ptr{T}, x, i::Integer) - Store a value of type "T" to the address of the ith element - (1-indexed) starting at "p". This is equivalent to the C - expression "p[i-1] = x". +Store a value of type "T" to the address of the ith element +(1-indexed) starting at "p". This is equivalent to the C +expression "p[i-1] = x". - The "unsafe" prefix on this function indicates that no validation - is performed on the pointer "p" to ensure that it is valid. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. -``` +The "unsafe" prefix on this function indicates that no validation +is performed on the pointer "p" to ensure that it is valid. +Incorrect usage may corrupt or segfault your program, in the same +manner as C. """ unsafe_store! doc""" -```rst -unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - Copy "N" elements from a source pointer to a destination, with no - checking. The size of an element is determined by the type of the - pointers. +Copy "N" elements from a source pointer to a destination, with no +checking. The size of an element is determined by the type of the +pointers. - The "unsafe" prefix on this function indicates that no validation - is performed on the pointers "dest" and "src" to ensure that - they are valid. Incorrect usage may corrupt or segfault your - program, in the same manner as C. -``` +The "unsafe" prefix on this function indicates that no validation +is performed on the pointers "dest" and "src" to ensure that +they are valid. Incorrect usage may corrupt or segfault your +program, in the same manner as C. """ unsafe_copy! doc""" -```rst -unsafe_copy!(dest::Array, do, src::Array, so, N) + unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy "N" elements from a source array to a destination, starting - at offset "so" in the source and "do" in the destination - (1-indexed). +Copy "N" elements from a source array to a destination, starting +at offset "so" in the source and "do" in the destination +(1-indexed). - The "unsafe" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. -``` +The "unsafe" prefix on this function indicates that no validation +is performed to ensure that N is inbounds on either array. +Incorrect usage may corrupt or segfault your program, in the same +manner as C. """ unsafe_copy! doc""" -```rst -copy!(dest, src) + copy!(dest, src) - Copy all elements from collection "src" to array "dest". - Returns "dest". -``` +Copy all elements from collection "src" to array "dest". +Returns "dest". """ copy! doc""" -```rst -copy!(dest, do, src, so, N) + copy!(dest, do, src, so, N) - Copy "N" elements from collection "src" starting at offset - "so", to array "dest" starting at offset "do". Returns - "dest". -``` +Copy "N" elements from collection "src" starting at offset +"so", to array "dest" starting at offset "do". Returns +"dest". """ copy! doc""" -```rst -pointer(array[, index]) + pointer(array[, index]) - Get the native address of an array or string element. Be careful to - ensure that a julia reference to "a" exists as long as this - pointer will be used. This function is "unsafe" like - "unsafe_convert". +Get the native address of an array or string element. Be careful to +ensure that a julia reference to "a" exists as long as this +pointer will be used. This function is "unsafe" like +"unsafe_convert". - Calling "Ref(array[, index])" is generally preferable to this - function. -``` +Calling "Ref(array[, index])" is generally preferable to this +function. """ pointer doc""" -```rst -pointer_to_array(pointer, dims[, take_ownership::Bool]) + pointer_to_array(pointer, dims[, take_ownership::Bool]) - Wrap a native pointer as a Julia Array object. The pointer element - type determines the array element type. "own" optionally - specifies whether Julia should take ownership of the memory, - calling "free" on the pointer when the array is no longer - referenced. -``` +Wrap a native pointer as a Julia Array object. The pointer element +type determines the array element type. "own" optionally +specifies whether Julia should take ownership of the memory, +calling "free" on the pointer when the array is no longer +referenced. """ pointer_to_array doc""" -```rst -pointer_from_objref(object_instance) + pointer_from_objref(object_instance) - Get the memory address of a Julia object as a "Ptr". The - existence of the resulting "Ptr" will not protect the object from - garbage collection, so you must ensure that the object remains - referenced for the whole time that the "Ptr" will be used. -``` +Get the memory address of a Julia object as a "Ptr". The +existence of the resulting "Ptr" will not protect the object from +garbage collection, so you must ensure that the object remains +referenced for the whole time that the "Ptr" will be used. """ pointer_from_objref doc""" -```rst -unsafe_pointer_to_objref(p::Ptr) + unsafe_pointer_to_objref(p::Ptr) - Convert a "Ptr" to an object reference. Assumes the pointer - refers to a valid heap-allocated Julia object. If this is not the - case, undefined behavior results, hence this function is considered - "unsafe" and should be used with care. -``` +Convert a "Ptr" to an object reference. Assumes the pointer +refers to a valid heap-allocated Julia object. If this is not the +case, undefined behavior results, hence this function is considered +"unsafe" and should be used with care. """ unsafe_pointer_to_objref doc""" -```rst -disable_sigint(f::Function) + disable_sigint(f::Function) - Disable Ctrl-C handler during execution of a function, for calling - external code that is not interrupt safe. Intended to be called - using "do" block syntax as follows: +Disable Ctrl-C handler during execution of a function, for calling +external code that is not interrupt safe. Intended to be called +using "do" block syntax as follows: - disable_sigint() do - # interrupt-unsafe code - ... - end -``` + disable_sigint() do + # interrupt-unsafe code + ... + end """ disable_sigint doc""" -```rst -reenable_sigint(f::Function) + reenable_sigint(f::Function) - Re-enable Ctrl-C handler during execution of a function. - Temporarily reverses the effect of "disable_sigint". -``` +Re-enable Ctrl-C handler during execution of a function. +Temporarily reverses the effect of "disable_sigint". """ reenable_sigint doc""" -```rst -systemerror(sysfunc, iftrue) + systemerror(sysfunc, iftrue) - Raises a "SystemError" for "errno" with the descriptive string - "sysfunc" if "bool" is true -``` +Raises a "SystemError" for "errno" with the descriptive string +"sysfunc" if "bool" is true """ systemerror doc""" -```rst -Cchar + Cchar - Equivalent to the native "char" c-type -``` +Equivalent to the native "char" c-type """ Cchar doc""" -```rst -Cuchar + Cuchar - Equivalent to the native "unsigned char" c-type (UInt8) -``` +Equivalent to the native "unsigned char" c-type (UInt8) """ Cuchar doc""" -```rst -Cshort + Cshort - Equivalent to the native "signed short" c-type (Int16) -``` +Equivalent to the native "signed short" c-type (Int16) """ Cshort doc""" -```rst -Cushort + Cushort - Equivalent to the native "unsigned short" c-type (UInt16) -``` +Equivalent to the native "unsigned short" c-type (UInt16) """ Cushort doc""" -```rst -Cint + Cint - Equivalent to the native "signed int" c-type (Int32) -``` +Equivalent to the native "signed int" c-type (Int32) """ Cint doc""" -```rst -Cuint + Cuint - Equivalent to the native "unsigned int" c-type (UInt32) -``` +Equivalent to the native "unsigned int" c-type (UInt32) """ Cuint doc""" -```rst -Clong + Clong - Equivalent to the native "signed long" c-type -``` +Equivalent to the native "signed long" c-type """ Clong doc""" -```rst -Culong + Culong - Equivalent to the native "unsigned long" c-type -``` +Equivalent to the native "unsigned long" c-type """ Culong doc""" -```rst -Clonglong + Clonglong - Equivalent to the native "signed long long" c-type (Int64) -``` +Equivalent to the native "signed long long" c-type (Int64) """ Clonglong doc""" -```rst -Culonglong + Culonglong - Equivalent to the native "unsigned long long" c-type (UInt64) -``` +Equivalent to the native "unsigned long long" c-type (UInt64) """ Culonglong doc""" -```rst -Cintmax_t + Cintmax_t - Equivalent to the native "intmax_t" c-type (Int64) -``` +Equivalent to the native "intmax_t" c-type (Int64) """ Cintmax_t doc""" -```rst -Cuintmax_t + Cuintmax_t - Equivalent to the native "uintmax_t" c-type (UInt64) -``` +Equivalent to the native "uintmax_t" c-type (UInt64) """ Cuintmax_t doc""" -```rst -Csize_t + Csize_t - Equivalent to the native "size_t" c-type (UInt) -``` +Equivalent to the native "size_t" c-type (UInt) """ Csize_t doc""" -```rst -Cssize_t + Cssize_t - Equivalent to the native "ssize_t" c-type -``` +Equivalent to the native "ssize_t" c-type """ Cssize_t doc""" -```rst -Cptrdiff_t + Cptrdiff_t - Equivalent to the native "ptrdiff_t" c-type (Int) -``` +Equivalent to the native "ptrdiff_t" c-type (Int) """ Cptrdiff_t doc""" -```rst -Coff_t + Coff_t - Equivalent to the native "off_t" c-type -``` +Equivalent to the native "off_t" c-type """ Coff_t doc""" -```rst -Cwchar_t + Cwchar_t - Equivalent to the native "wchar_t" c-type (Int32) -``` +Equivalent to the native "wchar_t" c-type (Int32) """ Cwchar_t doc""" -```rst -Cfloat + Cfloat - Equivalent to the native "float" c-type (Float32) -``` +Equivalent to the native "float" c-type (Float32) """ Cfloat doc""" -```rst -Cdouble + Cdouble - Equivalent to the native "double" c-type (Float64) -``` +Equivalent to the native "double" c-type (Float64) """ Cdouble doc""" -```rst -start(iter) -> state + start(iter) -> state - Get initial iteration state for an iterable object -``` +Get initial iteration state for an iterable object """ start doc""" -```rst -done(iter, state) -> Bool + done(iter, state) -> Bool - Test whether we are done iterating -``` +Test whether we are done iterating """ done doc""" -```rst -next(iter, state) -> item, state + next(iter, state) -> item, state - For a given iterable object and iteration state, return the current - item and the next iteration state -``` +For a given iterable object and iteration state, return the current +item and the next iteration state """ next doc""" -```rst -zip(iters...) + zip(iters...) - For a set of iterable objects, returns an iterable of tuples, where - the "i"th tuple contains the "i"th component of each input - iterable. +For a set of iterable objects, returns an iterable of tuples, where +the "i"th tuple contains the "i"th component of each input +iterable. - Note that "zip()" is its own inverse: - "collect(zip(zip(a...)...)) == collect(a)". -``` +Note that "zip()" is its own inverse: +"collect(zip(zip(a...)...)) == collect(a)". """ zip doc""" -```rst -enumerate(iter) + enumerate(iter) - An iterator that yields "(i, x)" where "i" is an index starting - at 1, and "x" is the "i"th value from the given iterator. It's - useful when you need not only the values "x" over which you are - iterating, but also the index "i" of the iterations. +An iterator that yields "(i, x)" where "i" is an index starting +at 1, and "x" is the "i"th value from the given iterator. It's +useful when you need not only the values "x" over which you are +iterating, but also the index "i" of the iterations. - julia> a = ["a", "b", "c"]; + julia> a = ["a", "b", "c"]; - julia> for (index, value) in enumerate(a) - println("\$index \$value") - end - 1 a - 2 b - 3 c -``` + julia> for (index, value) in enumerate(a) + println("\$index \$value") + end + 1 a + 2 b + 3 c """ enumerate doc""" -```rst -rest(iter, state) + rest(iter, state) - An iterator that yields the same elements as "iter", but starting - at the given "state". -``` +An iterator that yields the same elements as "iter", but starting +at the given "state". """ rest doc""" -```rst -countfrom(start=1, step=1) + countfrom(start=1, step=1) - An iterator that counts forever, starting at "start" and - incrementing by "step". -``` +An iterator that counts forever, starting at "start" and +incrementing by "step". """ countfrom doc""" -```rst -take(iter, n) + take(iter, n) - An iterator that generates at most the first "n" elements of - "iter". -``` +An iterator that generates at most the first "n" elements of +"iter". """ take doc""" -```rst -drop(iter, n) + drop(iter, n) - An iterator that generates all but the first "n" elements of - "iter". -``` +An iterator that generates all but the first "n" elements of +"iter". """ drop doc""" -```rst -cycle(iter) + cycle(iter) - An iterator that cycles through "iter" forever. -``` +An iterator that cycles through "iter" forever. """ cycle doc""" -```rst -repeated(x[, n::Int]) + repeated(x[, n::Int]) - An iterator that generates the value "x" forever. If "n" is - specified, generates "x" that many times (equivalent to - "take(repeated(x), n)"). -``` +An iterator that generates the value "x" forever. If "n" is +specified, generates "x" that many times (equivalent to +"take(repeated(x), n)"). """ repeated doc""" -```rst -isempty(collection) -> Bool + isempty(collection) -> Bool - Determine whether a collection is empty (has no elements). +Determine whether a collection is empty (has no elements). - julia> isempty([]) - true + julia> isempty([]) + true - julia> isempty([1 2 3]) - false -``` + julia> isempty([1 2 3]) + false """ isempty doc""" -```rst -empty!(collection) -> collection + empty!(collection) -> collection - Remove all elements from a "collection". -``` +Remove all elements from a "collection". """ empty! doc""" -```rst -length(collection) -> Integer + length(collection) -> Integer - For ordered, indexable collections, the maximum index "i" for - which "getindex(collection, i)" is valid. For unordered - collections, the number of elements. -``` +For ordered, indexable collections, the maximum index "i" for +which "getindex(collection, i)" is valid. For unordered +collections, the number of elements. """ length doc""" -```rst -endof(collection) -> Integer + endof(collection) -> Integer - Returns the last index of the collection. +Returns the last index of the collection. - julia> endof([1,2,4]) - 3 -``` + julia> endof([1,2,4]) + 3 """ endof doc""" -```rst -in(item, collection) -> Bool + 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)". -``` +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)". """ Base.in doc""" -```rst -eltype(type) + 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 "(key,value)" tuple type. 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. -``` +Determine the type of the elements generated by iterating a +collection of the given "type". For associative collection types, +this will be a "(key,value)" tuple type. 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. """ eltype doc""" -```rst -indexin(a, b) + 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". -``` +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". """ indexin doc""" -```rst -findin(a, b) + findin(a, b) - Returns the indices of elements in collection "a" that appear in - collection "b" -``` +Returns the indices of elements in collection "a" that appear in +collection "b" """ findin doc""" -```rst -unique(itr[, dim]) + 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". -``` +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". """ unique doc""" -```rst -reduce(op, v0, itr) + 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. +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)". +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. +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. -``` +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. """ reduce doc""" -```rst -reduce(op, itr) + 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". -``` +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". """ reduce doc""" -```rst -foldl(op, v0, itr) + foldl(op, v0, itr) - Like "reduce()", but with guaranteed left associativity. "v0" - will be used exactly once. -``` +Like "reduce()", but with guaranteed left associativity. "v0" +will be used exactly once. """ foldl doc""" -```rst -foldl(op, itr) + 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)"). -``` +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)"). """ foldl doc""" -```rst -foldr(op, v0, itr) + foldr(op, v0, itr) - Like "reduce()", but with guaranteed right associativity. "v0" - will be used exactly once. -``` +Like "reduce()", but with guaranteed right associativity. "v0" +will be used exactly once. """ foldr doc""" -```rst -foldr(op, itr) + 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)"). -``` +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)"). """ foldr doc""" -```rst -maximum(itr) + maximum(itr) - Returns the largest element in a collection. -``` +Returns the largest element in a collection. """ maximum doc""" -```rst -maximum(A, dims) + maximum(A, dims) - Compute the maximum value of an array over the given dimensions. -``` +Compute the maximum value of an array over the given dimensions. """ maximum doc""" -```rst -maximum!(r, A) + maximum!(r, A) - Compute the maximum value of "A" over the singleton dimensions of - "r", and write results to "r". -``` +Compute the maximum value of "A" over the singleton dimensions of +"r", and write results to "r". """ maximum! doc""" -```rst -minimum(itr) + minimum(itr) - Returns the smallest element in a collection. -``` +Returns the smallest element in a collection. """ minimum doc""" -```rst -minimum(A, dims) + minimum(A, dims) - Compute the minimum value of an array over the given dimensions. -``` +Compute the minimum value of an array over the given dimensions. """ minimum doc""" -```rst -minimum!(r, A) + minimum!(r, A) - Compute the minimum value of "A" over the singleton dimensions of - "r", and write results to "r". -``` +Compute the minimum value of "A" over the singleton dimensions of +"r", and write results to "r". """ minimum! doc""" -```rst -extrema(itr) + extrema(itr) - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. -``` +Compute both the minimum and maximum element in a single pass, and +return them as a 2-tuple. """ extrema doc""" -```rst -indmax(itr) -> Integer + indmax(itr) -> Integer - Returns the index of the maximum element in a collection. -``` +Returns the index of the maximum element in a collection. """ indmax doc""" -```rst -indmin(itr) -> Integer + indmin(itr) -> Integer - Returns the index of the minimum element in a collection. -``` +Returns the index of the minimum element in a collection. """ indmin doc""" -```rst -findmax(itr) -> (x, index) + findmax(itr) -> (x, index) - Returns the maximum element and its index. -``` +Returns the maximum element and its index. """ findmax doc""" -```rst -findmax(A, dims) -> (maxval, index) + findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over - the given dimensions. -``` +For an array input, returns the value and index of the maximum over +the given dimensions. """ findmax doc""" -```rst -findmin(itr) -> (x, index) + findmin(itr) -> (x, index) - Returns the minimum element and its index. -``` +Returns the minimum element and its index. """ findmin doc""" -```rst -findmin(A, dims) -> (minval, index) + findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over - the given dimensions. -``` +For an array input, returns the value and index of the minimum over +the given dimensions. """ findmin doc""" -```rst -maxabs(itr) + maxabs(itr) - Compute the maximum absolute value of a collection of values. -``` +Compute the maximum absolute value of a collection of values. """ maxabs doc""" -```rst -maxabs(A, dims) + maxabs(A, dims) - Compute the maximum absolute values over given dimensions. -``` +Compute the maximum absolute values over given dimensions. """ maxabs doc""" -```rst -maxabs!(r, A) + maxabs!(r, A) - Compute the maximum absolute values over the singleton dimensions - of "r", and write values to "r". -``` +Compute the maximum absolute values over the singleton dimensions +of "r", and write values to "r". """ maxabs! doc""" -```rst -minabs(itr) + minabs(itr) - Compute the minimum absolute value of a collection of values. -``` +Compute the minimum absolute value of a collection of values. """ minabs doc""" -```rst -minabs(A, dims) + minabs(A, dims) - Compute the minimum absolute values over given dimensions. -``` +Compute the minimum absolute values over given dimensions. """ minabs doc""" -```rst -minabs!(r, A) + minabs!(r, A) - Compute the minimum absolute values over the singleton dimensions - of "r", and write values to "r". -``` +Compute the minimum absolute values over the singleton dimensions +of "r", and write values to "r". """ minabs! doc""" -```rst -sum(itr) + sum(itr) - Returns the sum of all elements in a collection. -``` +Returns the sum of all elements in a collection. """ sum doc""" -```rst -sum(A, dims) + sum(A, dims) - Sum elements of an array over the given dimensions. -``` +Sum elements of an array over the given dimensions. """ sum doc""" -```rst -sum!(r, A) + sum!(r, A) - Sum elements of "A" over the singleton dimensions of "r", and - write results to "r". -``` +Sum elements of "A" over the singleton dimensions of "r", and +write results to "r". """ sum! doc""" -```rst -sum(f, itr) + sum(f, itr) - Sum the results of calling function "f" on each element of - "itr". -``` +Sum the results of calling function "f" on each element of +"itr". """ sum doc""" -```rst -sumabs(itr) + sumabs(itr) - Sum absolute values of all elements in a collection. This is - equivalent to *sum(abs(itr))* but faster. -``` +Sum absolute values of all elements in a collection. This is +equivalent to *sum(abs(itr))* but faster. """ sumabs doc""" -```rst -sumabs(A, dims) + sumabs(A, dims) - Sum absolute values of elements of an array over the given - dimensions. -``` +Sum absolute values of elements of an array over the given +dimensions. """ sumabs doc""" -```rst -sumabs!(r, A) + sumabs!(r, A) - Sum absolute values of elements of "A" over the singleton - dimensions of "r", and write results to "r". -``` +Sum absolute values of elements of "A" over the singleton +dimensions of "r", and write results to "r". """ sumabs! doc""" -```rst -sumabs2(itr) + sumabs2(itr) - Sum squared absolute values of all elements in a collection. This - is equivalent to *sum(abs2(itr))* but faster. -``` +Sum squared absolute values of all elements in a collection. This +is equivalent to *sum(abs2(itr))* but faster. """ sumabs2 doc""" -```rst -sumabs2(A, dims) + sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. -``` +Sum squared absolute values of elements of an array over the given +dimensions. """ sumabs2 doc""" -```rst -sumabs2!(r, A) + sumabs2!(r, A) - Sum squared absolute values of elements of "A" over the singleton - dimensions of "r", and write results to "r". -``` +Sum squared absolute values of elements of "A" over the singleton +dimensions of "r", and write results to "r". """ sumabs2! doc""" -```rst -prod(itr) + prod(itr) - Returns the product of all elements of a collection. -``` +Returns the product of all elements of a collection. """ prod doc""" -```rst -prod(A, dims) + prod(A, dims) - Multiply elements of an array over the given dimensions. -``` +Multiply elements of an array over the given dimensions. """ prod doc""" -```rst -prod!(r, A) + prod!(r, A) - Multiply elements of "A" over the singleton dimensions of "r", - and write results to "r". -``` +Multiply elements of "A" over the singleton dimensions of "r", +and write results to "r". """ prod! doc""" -```rst -any(itr) -> Bool + any(itr) -> Bool - Test whether any elements of a boolean collection are true. -``` +Test whether any elements of a boolean collection are true. """ any doc""" -```rst -any(A, dims) + any(A, dims) - Test whether any values along the given dimensions of an array are - true. -``` +Test whether any values along the given dimensions of an array are +true. """ any doc""" -```rst -any!(r, A) + any!(r, A) - Test whether any values in "A" along the singleton dimensions of - "r" are true, and write results to "r". -``` +Test whether any values in "A" along the singleton dimensions of +"r" are true, and write results to "r". """ any! doc""" -```rst -all(itr) -> Bool + all(itr) -> Bool - Test whether all elements of a boolean collection are true. -``` +Test whether all elements of a boolean collection are true. """ all doc""" -```rst -all(A, dims) + all(A, dims) - Test whether all values along the given dimensions of an array are - true. -``` +Test whether all values along the given dimensions of an array are +true. """ all doc""" -```rst -all!(r, A) + all!(r, A) - Test whether all values in "A" along the singleton dimensions of - "r" are true, and write results to "r". -``` +Test whether all values in "A" along the singleton dimensions of +"r" are true, and write results to "r". """ all! doc""" -```rst -count(p, itr) -> Integer + count(p, itr) -> Integer - Count the number of elements in "itr" for which predicate "p" - returns true. -``` +Count the number of elements in "itr" for which predicate "p" +returns true. """ count doc""" -```rst -any(p, itr) -> Bool + any(p, itr) -> Bool - Determine whether predicate "p" returns true for any elements of - "itr". -``` +Determine whether predicate "p" returns true for any elements of +"itr". """ any doc""" -```rst -all(p, itr) -> Bool + all(p, itr) -> Bool - Determine whether predicate "p" returns true for all elements of - "itr". +Determine whether predicate "p" returns true for all elements of +"itr". - julia> all(i->(4<=i<=6), [4,5,6]) - true -``` + julia> all(i->(4<=i<=6), [4,5,6]) + true """ all doc""" -```rst -map(f, c...) -> collection + map(f, c...) -> collection - Transform collection "c" by applying "f" to each element. For - multiple collection arguments, apply "f" elementwise. +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((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 -``` + julia> map(+, [1, 2, 3], [10, 20, 30]) + 3-element Array{Int64,1}: + 11 + 22 + 33 """ map doc""" -```rst -map!(function, collection) + map!(function, collection) - In-place version of "map()". -``` +In-place version of "map()". """ map! doc""" -```rst -map!(function, destination, collection...) + 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. -``` +Like "map()", but stores the result in "destination" rather +than a new collection. "destination" must be at least as large as +the first collection. """ map! doc""" -```rst -mapreduce(f, op, v0, itr) + 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. +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()". +"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 + 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. -``` +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. """ mapreduce doc""" -```rst -mapreduce(f, op, itr) + mapreduce(f, op, itr) - Like "mapreduce(f, op, v0, itr)". In general, this cannot be used - with empty collections (see "reduce(op, itr)"). -``` +Like "mapreduce(f, op, v0, itr)". In general, this cannot be used +with empty collections (see "reduce(op, itr)"). """ mapreduce doc""" -```rst -mapfoldl(f, op, v0, itr) + mapfoldl(f, op, v0, itr) - Like "mapreduce()", but with guaranteed left associativity. - "v0" will be used exactly once. -``` +Like "mapreduce()", but with guaranteed left associativity. +"v0" will be used exactly once. """ mapfoldl doc""" -```rst -mapfoldl(f, op, itr) + 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)"). -``` +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)"). """ mapfoldl doc""" -```rst -mapfoldr(f, op, v0, itr) + mapfoldr(f, op, v0, itr) - Like "mapreduce()", but with guaranteed right associativity. - "v0" will be used exactly once. -``` +Like "mapreduce()", but with guaranteed right associativity. +"v0" will be used exactly once. """ mapfoldr doc""" -```rst -mapfoldr(f, op, itr) + 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)"). -``` +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)"). """ mapfoldr doc""" -```rst -first(coll) + first(coll) - Get the first element of an iterable collection. Returns the start - point of a "Range" even if it is empty. -``` +Get the first element of an iterable collection. Returns the start +point of a "Range" even if it is empty. """ first doc""" -```rst -last(coll) + 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. -``` +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. """ last doc""" -```rst -step(r) + step(r) - Get the step size of a "Range" object. -``` +Get the step size of a "Range" object. """ step doc""" -```rst -collect(collection) + collect(collection) - Return an array of all items in a collection. For associative - collections, returns (key, value) tuples. -``` +Return an array of all items in a collection. For associative +collections, returns (key, value) tuples. """ collect doc""" -```rst -collect(element_type, collection) + collect(element_type, collection) - Return an array of type "Array{element_type,1}" of all items in a - collection. -``` +Return an array of type "Array{element_type,1}" of all items in a +collection. """ collect doc""" -```rst -issubset(a, b) + issubset(a, b) ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool - Determine whether every element of "a" is also in "b", using - "in()". -``` +Determine whether every element of "a" is also in "b", using +"in()". """ issubset doc""" -```rst -filter(function, collection) + 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). -``` +Return a copy of "collection", removing elements for which +"function" is false. For associative collections, the function is +passed two arguments (key and value). """ filter doc""" -```rst -filter!(function, collection) + filter!(function, collection) - Update "collection", removing elements for which "function" is - false. For associative collections, the function is passed two - arguments (key and value). -``` +Update "collection", removing elements for which "function" is +false. For associative collections, the function is passed two +arguments (key and value). """ filter! doc""" -```rst -getindex(collection, key...) + 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, ...)". -``` +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, ...)". """ getindex doc""" -```rst -setindex!(collection, value, key...) + 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, ...)". -``` +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, ...)". """ setindex! doc""" -```rst -Dict([itr]) + Dict([itr]) - "Dict{K,V}()" constructs a hash table with keys of type "K" and - values of type "V". +"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. +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{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 + julia> Dict([("A", 1), ("B", 2)]) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 - Alternatively, a sequence of pair arguments may be passed. +Alternatively, a sequence of pair arguments may be passed. - julia> Dict("A"=>1, "B"=>2) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 -``` + julia> Dict("A"=>1, "B"=>2) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 """ Dict doc""" -```rst -haskey(collection, key) -> Bool + haskey(collection, key) -> Bool - Determine whether a collection has a mapping for a given key. -``` +Determine whether a collection has a mapping for a given key. """ haskey doc""" -```rst -get(collection, key, default) + 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. -``` +Return the value stored for the given key, or the given default +value if no mapping for the key is present. """ get doc""" -```rst -get(f::Function, collection, key) + 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. +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: +This is intended to be called using "do" block syntax: - get(dict, key) do - # default value calculated here - time() - end -``` + get(dict, key) do + # default value calculated here + time() + end """ get doc""" -```rst -get!(collection, key, default) + 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". -``` +Return the value stored for the given key, or if no mapping for the +key is present, store "key => default", and return "default". """ get! doc""" -```rst -get!(f::Function, collection, key) + 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()". +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: +This is intended to be called using "do" block syntax: - get!(dict, key) do - # default value calculated here - time() - end -``` + get!(dict, key) do + # default value calculated here + time() + end """ get! doc""" -```rst -getkey(collection, key, default) + getkey(collection, key, default) - Return the key matching argument "key" if one exists in - "collection", otherwise return "default". -``` +Return the key matching argument "key" if one exists in +"collection", otherwise return "default". """ getkey doc""" -```rst -delete!(collection, key) + delete!(collection, key) - Delete the mapping for the given key in a collection, and return - the collection. -``` +Delete the mapping for the given key in a collection, and return +the collection. """ delete! doc""" -```rst -pop!(collection, key[, default]) + 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. -``` +Delete and return the mapping for "key" if it exists in +"collection", otherwise return "default", or throw an error if +default is not specified. """ pop! doc""" -```rst -keys(collection) + keys(collection) - Return an iterator over all keys in a collection. - "collect(keys(d))" returns an array of keys. -``` +Return an iterator over all keys in a collection. +"collect(keys(d))" returns an array of keys. """ keys doc""" -```rst -values(collection) + values(collection) - Return an iterator over all values in a collection. - "collect(values(d))" returns an array of values. -``` +Return an iterator over all values in a collection. +"collect(values(d))" returns an array of values. """ values doc""" -```rst -merge(collection, others...) + merge(collection, others...) - 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. +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{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 + julia> a = Dict("foo" => 0.0, "bar" => 42.0) + Dict{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 - julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "bar" => 4711 - "baz" => 17 + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 -``` + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 """ merge doc""" -```rst -merge!(collection, others...) + merge!(collection, others...) - Update collection with pairs from the other collections -``` +Update collection with pairs from the other collections """ merge! doc""" -```rst -sizehint!(s, n) + sizehint!(s, n) - Suggest that collection "s" reserve capacity for at least "n" - elements. This can improve performance. -``` +Suggest that collection "s" reserve capacity for at least "n" +elements. This can improve performance. """ sizehint! doc""" -```rst -Set([itr]) + 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. -``` +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. """ Set doc""" -```rst -IntSet([itr]) + IntSet([itr]) - Construct a sorted set of the integers generated by the given - iterable object, or an empty set. Implemented as a bit string, and - therefore designed for dense integer sets. Only non-negative - integers can be stored. If the set will be sparse (for example - holding a single very large integer), use "Set" instead. -``` +Construct a sorted set of the integers generated by the given +iterable object, or an empty set. Implemented as a bit string, and +therefore designed for dense integer sets. Only non-negative +integers can be stored. If the set will be sparse (for example +holding a single very large integer), use "Set" instead. """ IntSet doc""" -```rst -union(s1, s2...) + union(s1, s2...) ∪(s1, s2) - Construct the union of two or more sets. Maintains order with - arrays. -``` +Construct the union of two or more sets. Maintains order with +arrays. """ union doc""" -```rst -union!(s, iterable) + union!(s, iterable) - Union each element of "iterable" into set "s" in-place. -``` +Union each element of "iterable" into set "s" in-place. """ union! doc""" -```rst -intersect(s1, s2...) + 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. -``` +Construct the intersection of two or more sets. Maintains order and +multiplicity of the first argument for arrays and ranges. """ intersect doc""" -```rst -setdiff(s1, s2) + setdiff(s1, s2) - Construct the set of elements in "s1" but not "s2". 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. -``` +Construct the set of elements in "s1" but not "s2". 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. """ setdiff doc""" -```rst -setdiff!(s, iterable) + setdiff!(s, iterable) - Remove each element of "iterable" from set "s" in-place. -``` +Remove each element of "iterable" from set "s" in-place. """ setdiff! doc""" -```rst -symdiff(s1, s2...) + symdiff(s1, s2...) - Construct the symmetric difference of elements in the passed in - sets or arrays. Maintains order with arrays. -``` +Construct the symmetric difference of elements in the passed in +sets or arrays. Maintains order with arrays. """ symdiff doc""" -```rst -symdiff!(s, n) + symdiff!(s, n) - The set "s" is destructively modified to toggle the inclusion of - integer "n". -``` +The set "s" is destructively modified to toggle the inclusion of +integer "n". """ symdiff! doc""" -```rst -symdiff!(s, itr) + symdiff!(s, itr) - For each element in "itr", destructively toggle its inclusion in - set "s". -``` +For each element in "itr", destructively toggle its inclusion in +set "s". """ symdiff! doc""" -```rst -symdiff!(s1, s2) + symdiff!(s1, s2) - Construct the symmetric difference of sets "s1" and "s2", - storing the result in "s1". -``` +Construct the symmetric difference of sets "s1" and "s2", +storing the result in "s1". """ symdiff! doc""" -```rst -complement(s) + complement(s) - Returns the set-complement of "IntSet" "s". -``` +Returns the set-complement of "IntSet" "s". """ complement doc""" -```rst -complement!(s) + complement!(s) - Mutates "IntSet" "s" into its set-complement. -``` +Mutates "IntSet" "s" into its set-complement. """ complement! doc""" -```rst -intersect!(s1, s2) + intersect!(s1, s2) - Intersects sets "s1" and "s2" and overwrites the set "s1" - with the result. If needed, "s1" will be expanded to the size of - "s2". -``` +Intersects sets "s1" and "s2" and overwrites the set "s1" +with the result. If needed, "s1" will be expanded to the size of +"s2". """ intersect! doc""" -```rst -issubset(A, S) -> Bool + issubset(A, S) -> Bool ⊆(A, S) -> Bool - True if A is a subset of or equal to S. -``` +True if A is a subset of or equal to S. """ issubset doc""" -```rst -push!(collection, items...) -> collection + push!(collection, items...) -> collection - Insert one or more "items" at the end of "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 + 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])". -``` +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])". """ push! doc""" -```rst -pop!(collection) -> item + pop!(collection) -> item - Remove the last item in "collection" and return it. +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> A=[1, 2, 3, 4, 5, 6] + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 - julia> pop!(A) - 6 + julia> pop!(A) + 6 - julia> A - 5-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 -``` + julia> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 """ pop! doc""" -```rst -unshift!(collection, items...) -> collection + unshift!(collection, items...) -> collection - Insert one or more "items" at the beginning of "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 -``` + julia> unshift!([1, 2, 3, 4], 5, 6) + 6-element Array{Int64,1}: + 5 + 6 + 1 + 2 + 3 + 4 """ unshift! doc""" -```rst -shift!(collection) -> item + shift!(collection) -> item - Remove the first "item" from "collection". +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> A = [1, 2, 3, 4, 5, 6] + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 - julia> shift!(A) - 1 + julia> shift!(A) + 1 - julia> A - 5-element Array{Int64,1}: - 2 - 3 - 4 - 5 - 6 -``` + julia> A + 5-element Array{Int64,1}: + 2 + 3 + 4 + 5 + 6 """ shift! doc""" -```rst -insert!(collection, index, item) + insert!(collection, index, item) - Insert an "item" into "collection" at the given "index". - "index" is the index of "item" in the resulting "collection". +Insert an "item" into "collection" at the given "index". +"index" is the index of "item" in the resulting "collection". - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 -``` + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 """ insert! doc""" -```rst -deleteat!(collection, index) + deleteat!(collection, index) - Remove the item at the given "index" and return the modified - "collection". Subsequent items are shifted to fill the resulting - gap. +Remove the item at the given "index" and return the modified +"collection". 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 -``` + julia> deleteat!([6, 5, 4, 3, 2, 1], 2) + 5-element Array{Int64,1}: + 6 + 4 + 3 + 2 + 1 """ deleteat! doc""" -```rst -deleteat!(collection, itr) + deleteat!(collection, itr) - Remove the items at the indices given by "itr", and return the - modified "collection". Subsequent items are shifted to fill the - resulting gap. "itr" must be sorted and unique. +Remove the items at the indices given by "itr", and return the +modified "collection". Subsequent items are shifted to fill the +resulting gap. "itr" must be sorted and unique. - 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], 1:2:5) + 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 - in deleteat! at array.jl:631 -``` + julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 """ deleteat! doc""" -```rst -splice!(collection, index[, replacement]) -> item + splice!(collection, index[, replacement]) -> item - Remove the item at the given index, and return the removed item. - Subsequent items are shifted down to fill the resulting gap. If - specified, replacement values from an ordered collection will be - spliced in place of the removed item. +Remove the item at the given index, and return the removed item. +Subsequent items are shifted down 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 = [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 + 5-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 1 + + julia> splice!(A, 5, -1) + 1 - julia> A - 7-element Array{Int64,1}: - -1 - -2 - -3 - 5 - 4 - 3 - -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)". -``` +To insert "replacement" before an index "n" without removing +any items, use "splice!(collection, n:n-1, replacement)". """ splice! doc""" -```rst -splice!(collection, range[, replacement]) -> items + splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down to - fill the resulting gap. If specified, replacement values from an - ordered collection will be spliced in place of the removed items. +Remove items in the specified index range, and return a collection +containing the removed items. Subsequent items are shifted down 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)". +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> 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 -``` + julia> A + 8-element Array{Int64,1}: + -1 + -2 + -3 + 2 + 5 + 4 + 3 + -1 """ splice! doc""" -```rst -resize!(collection, n) -> collection - - Resize "collection" 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 -``` + resize!(collection, n) -> collection + +Resize "collection" 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 """ resize! doc""" -```rst -append!(collection, collection2) -> collection. + append!(collection, collection2) -> collection. - Add the elements of "collection2" to the end of "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]) + 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 + 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)". -``` +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)". """ append! doc""" -```rst -prepend!(collection, items) -> collection + prepend!(collection, items) -> collection - Insert the elements of "items" to the beginning of - "collection". +Insert the elements of "items" to the beginning of +"collection". - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 -``` + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 """ prepend! doc""" -```rst -PriorityQueue(K, V[, ord]) + PriorityQueue(K, V[, ord]) - Construct a new "PriorityQueue", with keys of type "K" and - values/priorites of type "V". If an order is not given, the - priority queue is min-ordered using the default comparison for - "V". -``` +Construct a new "PriorityQueue", with keys of type "K" and +values/priorites of type "V". If an order is not given, the +priority queue is min-ordered using the default comparison for +"V". """ Base.Collections.PriorityQueue doc""" -```rst -enqueue!(pq, k, v) + enqueue!(pq, k, v) - Insert the a key "k" into a priority queue "pq" with priority - "v". -``` +Insert the a key "k" into a priority queue "pq" with priority +"v". """ Base.Collections.enqueue! doc""" -```rst -dequeue!(pq) + dequeue!(pq) - Remove and return the lowest priority key from a priority queue. -``` +Remove and return the lowest priority key from a priority queue. """ Base.Collections.dequeue! doc""" -```rst -peek(pq) + peek(pq) - Return the lowest priority key from a priority queue without - removing that key from the queue. -``` +Return the lowest priority key from a priority queue without +removing that key from the queue. """ Base.Collections.peek doc""" -```rst -heapify(v[, ord]) + heapify(v[, ord]) - Return a new vector in binary heap order, optionally using the - given ordering. -``` +Return a new vector in binary heap order, optionally using the +given ordering. """ Base.Collections.heapify doc""" -```rst -heapify!(v[, ord]) + heapify!(v[, ord]) - In-place "heapify()". -``` +In-place "heapify()". """ Base.Collections.heapify! doc""" -```rst -isheap(v[, ord]) + isheap(v[, ord]) - Return true iff an array is heap-ordered according to the given - order. -``` +Return true iff an array is heap-ordered according to the given +order. """ Base.Collections.isheap doc""" -```rst -heappush!(v, x[, ord]) + heappush!(v, x[, ord]) - Given a binary heap-ordered array, push a new element "x", - preserving the heap property. For efficiency, this function does - not check that the array is indeed heap-ordered. -``` +Given a binary heap-ordered array, push a new element "x", +preserving the heap property. For efficiency, this function does +not check that the array is indeed heap-ordered. """ Base.Collections.heappush! doc""" -```rst -heappop!(v[, ord]) + heappop!(v[, ord]) - Given a binary heap-ordered array, remove and return the lowest - ordered element. For efficiency, this function does not check that - the array is indeed heap-ordered. -``` +Given a binary heap-ordered array, remove and return the lowest +ordered element. For efficiency, this function does not check that +the array is indeed heap-ordered. """ Base.Collections.heappop! doc""" -```rst -nothing + nothing - The singleton instance of type "Void", used by convention when - there is no value to return (as in a C "void" function). Can be - converted to an empty "Nullable" value. -``` +The singleton instance of type "Void", used by convention when +there is no value to return (as in a C "void" function). Can be +converted to an empty "Nullable" value. """ nothing doc""" -```rst -OS_NAME + OS_NAME - A symbol representing the name of the operating system. Possible - values are ":Linux", ":Darwin" (OS X), or ":Windows". -``` +A symbol representing the name of the operating system. Possible +values are ":Linux", ":Darwin" (OS X), or ":Windows". """ OS_NAME doc""" -```rst -ARGS + ARGS - An array of the command line arguments passed to Julia, as strings. -``` +An array of the command line arguments passed to Julia, as strings. """ ARGS doc""" -```rst -C_NULL + C_NULL - The C null pointer constant, sometimes used when calling external - code. -``` +The C null pointer constant, sometimes used when calling external +code. """ C_NULL doc""" -```rst -WORD_SIZE + WORD_SIZE - Standard word size on the current machine, in bits. -``` +Standard word size on the current machine, in bits. """ WORD_SIZE doc""" -```rst -VERSION + VERSION - An object describing which version of Julia is in use. -``` +An object describing which version of Julia is in use. """ VERSION doc""" -```rst -LOAD_PATH + LOAD_PATH - An array of paths (as strings) where the "require" function looks - for code. -``` +An array of paths (as strings) where the "require" function looks +for code. """ LOAD_PATH doc""" -```rst -ANY + ANY - Equivalent to "Any" for dispatch purposes, but signals the - compiler to skip code generation specialization for that field -``` +Equivalent to "Any" for dispatch purposes, but signals the +compiler to skip code generation specialization for that field """ ANY doc""" -```rst -Period -``` + Period """ Dates.Period doc""" -```rst -Year -``` + Year """ Dates.Year doc""" -```rst -Month -``` + Month """ Dates.Month doc""" -```rst -Week -``` + Week """ Dates.Week doc""" -```rst -Day -``` + Day """ Dates.Day doc""" -```rst -Hour -``` + Hour """ Dates.Hour doc""" -```rst -Minute -``` + Minute """ Dates.Minute doc""" -```rst -Second -``` + Second """ Dates.Second doc""" -```rst -Millisecond + Millisecond - "Period" types represent discrete, human representations of time. -``` +"Period" types represent discrete, human representations of time. """ Dates.Millisecond doc""" -```rst -Instant + Instant - "Instant" types represent integer-based, machine representations - of time as continuous timelines starting from an epoch. -``` +"Instant" types represent integer-based, machine representations +of time as continuous timelines starting from an epoch. """ Dates.Instant doc""" -```rst -TimeType + TimeType - "TimeType" types wrap "Instant" machine instances to provide - human representations of the machine instant. -``` +"TimeType" types wrap "Instant" machine instances to provide +human representations of the machine instant. """ Dates.TimeType doc""" -```rst -DateTime + DateTime - "DateTime" wraps a "UTInstant{Millisecond}" and interprets it - according to the proleptic Gregorian calendar. -``` +"DateTime" wraps a "UTInstant{Millisecond}" and interprets it +according to the proleptic Gregorian calendar. """ Dates.DateTime doc""" -```rst -Date + Date - "Date" wraps a "UTInstant{Day}" and interprets it according to - the proleptic Gregorian calendar. -``` +"Date" wraps a "UTInstant{Day}" and interprets it according to +the proleptic Gregorian calendar. """ Dates.Date doc""" -```rst -DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - Construct a DateTime type by parts. Arguments must be convertible - to "Int64". -``` +Construct a DateTime type by parts. Arguments must be convertible +to "Int64". """ Dates.DateTime doc""" -```rst -DateTime(periods::Period...) -> DateTime + DateTime(periods::Period...) -> DateTime - Constuct a DateTime type by "Period" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of "Dates.default(period)". -``` +Constuct a DateTime type by "Period" type parts. Arguments may be +in any order. DateTime parts not provided will default to the value +of "Dates.default(period)". """ Dates.DateTime doc""" -```rst -DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided "y, m, d..." arguments, and will - be adjusted until "f::Function" returns true. The step size in - adjusting can be provided manually through the "step" keyword. If - "negate=true", then the adjusting will stop when "f::Function" - returns false instead of true. "limit" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that "f::Function" is never - satisfied). -``` +Create a DateTime through the adjuster API. The starting point will +be constructed from the provided "y, m, d..." arguments, and will +be adjusted until "f::Function" returns true. The step size in +adjusting can be provided manually through the "step" keyword. If +"negate=true", then the adjusting will stop when "f::Function" +returns false instead of true. "limit" provides a limit to the +max number of iterations the adjustment API will pursue before +throwing an error (in the case that "f::Function" is never +satisfied). """ Dates.DateTime doc""" -```rst -DateTime(dt::Date) -> DateTime + DateTime(dt::Date) -> DateTime - Converts a "Date" type to a "DateTime". The hour, minute, - second, and millisecond parts of the new "DateTime" are assumed - to be zero. -``` +Converts a "Date" type to a "DateTime". The hour, minute, +second, and millisecond parts of the new "DateTime" are assumed +to be zero. """ Dates.DateTime doc""" -```rst -DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime - - Construct a DateTime type by parsing the "dt" date string - following the pattern given in the "format" string. The following - codes can be used for constructing format strings: - - +-----------------+-----------+-----------------------------------------------------------------+ - | Code | Matches | Comment | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"y\" | 1996, 96 | Returns year of 1996, 0096 | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"m\" | 1, 01 | Matches 1 or 2-digit months | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"U\" | January | Matches full month names according to the \"locale\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"d\" | 1, 01 | Matches 1 or 2-digit days | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"H\" | 00 | Matches hours | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"M\" | 00 | Matches minutes | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"S\" | 00 | Matches seconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"s\" | .500 | Matches milliseconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"e\" | Mon, Tues | Matches abbreviated days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"E\" | Monday | Matches full name days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | - +-----------------+-----------+-----------------------------------------------------------------+ - - All characters not listed above are treated as delimiters between - date and time slots. So a "dt" string of - "1996-01-15T00:00:00.0" would have a "format" string like - "y-m-dTH:M:S.s". -``` + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + +Construct a DateTime type by parsing the "dt" date string +following the pattern given in the "format" string. The following +codes can be used for constructing format strings: + ++-----------------+-----------+-----------------------------------------------------------------+ +| Code | Matches | Comment | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"y\" | 1996, 96 | Returns year of 1996, 0096 | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"m\" | 1, 01 | Matches 1 or 2-digit months | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"U\" | January | Matches full month names according to the \"locale\" keyword | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"d\" | 1, 01 | Matches 1 or 2-digit days | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"H\" | 00 | Matches hours | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"M\" | 00 | Matches minutes | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"S\" | 00 | Matches seconds | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"s\" | .500 | Matches milliseconds | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"e\" | Mon, Tues | Matches abbreviated days of the week | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"E\" | Monday | Matches full name days of the week | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | ++-----------------+-----------+-----------------------------------------------------------------+ + +All characters not listed above are treated as delimiters between +date and time slots. So a "dt" string of +"1996-01-15T00:00:00.0" would have a "format" string like +"y-m-dTH:M:S.s". """ Dates.DateTime doc""" -```rst -Dates.DateFormat(format::AbstractString) -> DateFormat + Dates.DateFormat(format::AbstractString) -> DateFormat - Construct a date formatting object that can be passed repeatedly - for parsing similarly formatted date strings. "format" is a - format string in the form described above (e.g. ""yyyy-mm- - dd""). -``` +Construct a date formatting object that can be passed repeatedly +for parsing similarly formatted date strings. "format" is a +format string in the form described above (e.g. ""yyyy-mm- +dd""). """ Dates.Dates doc""" -```rst -DateTime(dt::AbstractString, df::DateFormat) -> DateTime + DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. -``` +Similar form as above for parsing a "DateTime", but passes a +"DateFormat" object instead of a raw formatting string. It is +more efficient if similarly formatted date strings will be parsed +repeatedly to first create a "DateFormat" object then use this +method for parsing. """ Dates.DateTime doc""" -```rst -Date(y[, m, d]) -> Date + Date(y[, m, d]) -> Date - Construct a "Date" type by parts. Arguments must be convertible - to "Int64". -``` +Construct a "Date" type by parts. Arguments must be convertible +to "Int64". """ Dates.Date doc""" -```rst -Date(period::Period...) -> Date + Date(period::Period...) -> Date - Constuct a Date type by "Period" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - "Dates.default(period)". -``` +Constuct a Date type by "Period" type parts. Arguments may be in +any order. Date parts not provided will default to the value of +"Dates.default(period)". """ Dates.Date doc""" -```rst -Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be - constructed from the provided "y, m" arguments, and will be - adjusted until "f::Function" returns true. The step size in - adjusting can be provided manually through the "step" keyword. If - "negate=true", then the adjusting will stop when "f::Function" - returns false instead of true. "limit" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that "f::Function" is never satisfied). -``` +Create a Date through the adjuster API. The starting point will be +constructed from the provided "y, m" arguments, and will be +adjusted until "f::Function" returns true. The step size in +adjusting can be provided manually through the "step" keyword. If +"negate=true", then the adjusting will stop when "f::Function" +returns false instead of true. "limit" provides a limit to the +max number of iterations the adjustment API will pursue before +throwing an error (given that "f::Function" is never satisfied). """ Dates.Date doc""" -```rst -Date(dt::DateTime) -> Date + Date(dt::DateTime) -> Date - Converts a "DateTime" type to a "Date". The hour, minute, - second, and millisecond parts of the "DateTime" are truncated, so - only the year, month and day parts are used in construction. -``` +Converts a "DateTime" type to a "Date". The hour, minute, +second, and millisecond parts of the "DateTime" are truncated, so +only the year, month and day parts are used in construction. """ Dates.Date doc""" -```rst -Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a "dt" date string following the - pattern given in the "format" string. Follows the same - conventions as "DateTime" above. -``` +Construct a Date type by parsing a "dt" date string following the +pattern given in the "format" string. Follows the same +conventions as "DateTime" above. """ Dates.Date doc""" -```rst -Date(dt::AbstractString, df::DateFormat) -> Date + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". -``` +Parse a date from a date string "dt" using a "DateFormat" +object "df". """ Dates.Date doc""" -```rst -now() -> DateTime + now() -> DateTime - Returns a DateTime corresponding to the user's system time - including the system timezone locale. -``` +Returns a DateTime corresponding to the user's system time +including the system timezone locale. """ Dates.now doc""" -```rst -now(::Type{UTC}) -> DateTime + now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as - UTC/GMT. -``` +Returns a DateTime corresponding to the user's system time as +UTC/GMT. """ Dates.now doc""" -```rst -eps(::DateTime) -> Millisecond + eps(::DateTime) -> Millisecond eps(::Date) -> Day - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" - for "Date" values. -``` +Returns "Millisecond(1)" for "DateTime" values and "Day(1)" +for "Date" values. """ Dates.eps doc""" -```rst -year(dt::TimeType) -> Int64 + year(dt::TimeType) -> Int64 month(dt::TimeType) -> Int64 week(dt::TimeType) -> Int64 day(dt::TimeType) -> Int64 @@ -6313,14 +5228,12 @@ minute(dt::TimeType) -> Int64 second(dt::TimeType) -> Int64 millisecond(dt::TimeType) -> Int64 - Return the field part of a Date or DateTime as an "Int64". -``` +Return the field part of a Date or DateTime as an "Int64". """ Dates.year doc""" -```rst -Year(dt::TimeType) -> Year + Year(dt::TimeType) -> Year Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week Day(dt::TimeType) -> Day @@ -6329,332 +5242,268 @@ Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second Millisecond(dt::TimeType) -> Millisecond - Return the field part of a Date or DateTime as a "Period" type. -``` +Return the field part of a Date or DateTime as a "Period" type. """ Dates.Year doc""" -```rst -yearmonth(dt::TimeType) -> (Int64, Int64) + yearmonth(dt::TimeType) -> (Int64, Int64) - Simultaneously return the year and month parts of a Date or - DateTime. -``` +Simultaneously return the year and month parts of a Date or +DateTime. """ Dates.yearmonth doc""" -```rst -monthday(dt::TimeType) -> (Int64, Int64) + monthday(dt::TimeType) -> (Int64, Int64) - Simultaneously return the month and day parts of a Date or - DateTime. -``` +Simultaneously return the month and day parts of a Date or +DateTime. """ Dates.monthday doc""" -```rst -yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - Simultaneously return the year, month, and day parts of a Date or - DateTime. -``` +Simultaneously return the year, month, and day parts of a Date or +DateTime. """ Dates.yearmonthday doc""" -```rst -dayname(dt::TimeType; locale="english") -> AbstractString + dayname(dt::TimeType; locale="english") -> AbstractString - Return the full day name corresponding to the day of the week of - the Date or DateTime in the given "locale". -``` +Return the full day name corresponding to the day of the week of +the Date or DateTime in the given "locale". """ Dates.dayname doc""" -```rst -dayabbr(dt::TimeType; locale="english") -> AbstractString + dayabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated name corresponding to the day of the week of - the Date or DateTime in the given "locale". -``` +Return the abbreviated name corresponding to the day of the week of +the Date or DateTime in the given "locale". """ Dates.dayabbr doc""" -```rst -dayofweek(dt::TimeType) -> Int64 + dayofweek(dt::TimeType) -> Int64 - Returns the day of the week as an "Int64" with "1 = Monday, 2 = - Tuesday, etc.". -``` +Returns the day of the week as an "Int64" with "1 = Monday, 2 = +Tuesday, etc.". """ Dates.dayofweek doc""" -```rst -dayofweekofmonth(dt::TimeType) -> Int + dayofweekofmonth(dt::TimeType) -> Int - For the day of week of "dt", returns which number it is in - "dt"'s month. So if the day of the week of "dt" is Monday, then - "1 = First Monday of the month, 2 = Second Monday of the month, - etc." In the range 1:5. -``` +For the day of week of "dt", returns which number it is in +"dt"'s month. So if the day of the week of "dt" is Monday, then +"1 = First Monday of the month, 2 = Second Monday of the month, +etc." In the range 1:5. """ Dates.dayofweekofmonth doc""" -```rst -daysofweekinmonth(dt::TimeType) -> Int + daysofweekinmonth(dt::TimeType) -> Int - For the day of week of "dt", returns the total number of that day - of the week in "dt"'s month. Returns 4 or 5. Useful in temporal - expressions for specifying the last day of a week in a month by - including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the - adjuster function. -``` +For the day of week of "dt", returns the total number of that day +of the week in "dt"'s month. Returns 4 or 5. Useful in temporal +expressions for specifying the last day of a week in a month by +including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the +adjuster function. """ Dates.daysofweekinmonth doc""" -```rst -monthname(dt::TimeType; locale="english") -> AbstractString + monthname(dt::TimeType; locale="english") -> AbstractString - Return the full name of the month of the Date or DateTime in the - given "locale". -``` +Return the full name of the month of the Date or DateTime in the +given "locale". """ Dates.monthname doc""" -```rst -monthabbr(dt::TimeType; locale="english") -> AbstractString + monthabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated month name of the Date or DateTime in the - given "locale". -``` +Return the abbreviated month name of the Date or DateTime in the +given "locale". """ Dates.monthabbr doc""" -```rst -daysinmonth(dt::TimeType) -> Int + daysinmonth(dt::TimeType) -> Int - Returns the number of days in the month of "dt". Value will be - 28, 29, 30, or 31. -``` +Returns the number of days in the month of "dt". Value will be +28, 29, 30, or 31. """ Dates.daysinmonth doc""" -```rst -isleapyear(dt::TimeType) -> Bool + isleapyear(dt::TimeType) -> Bool - Returns true if the year of "dt" is a leap year. -``` +Returns true if the year of "dt" is a leap year. """ Dates.isleapyear doc""" -```rst -dayofyear(dt::TimeType) -> Int + dayofyear(dt::TimeType) -> Int - Returns the day of the year for "dt" with January 1st being day - 1. -``` +Returns the day of the year for "dt" with January 1st being day +1. """ Dates.dayofyear doc""" -```rst -daysinyear(dt::TimeType) -> Int + daysinyear(dt::TimeType) -> Int - Returns 366 if the year of "dt" is a leap year, otherwise returns - 365. -``` +Returns 366 if the year of "dt" is a leap year, otherwise returns +365. """ Dates.daysinyear doc""" -```rst -quarterofyear(dt::TimeType) -> Int + quarterofyear(dt::TimeType) -> Int - Returns the quarter that "dt" resides in. Range of value is 1:4. -``` +Returns the quarter that "dt" resides in. Range of value is 1:4. """ Dates.quarterofyear doc""" -```rst -dayofquarter(dt::TimeType) -> Int + dayofquarter(dt::TimeType) -> Int - Returns the day of the current quarter of "dt". Range of value is - 1:92. -``` +Returns the day of the current quarter of "dt". Range of value is +1:92. """ Dates.dayofquarter doc""" -```rst -trunc(dt::TimeType, ::Type{Period}) -> TimeType + trunc(dt::TimeType, ::Type{Period}) -> TimeType - Truncates the value of "dt" according to the provided "Period" - type. E.g. if "dt" is "1996-01-01T12:30:00", then - "trunc(dt,Day) == 1996-01-01T00:00:00". -``` +Truncates the value of "dt" according to the provided "Period" +type. E.g. if "dt" is "1996-01-01T12:30:00", then +"trunc(dt,Day) == 1996-01-01T00:00:00". """ Dates.trunc doc""" -```rst -firstdayofweek(dt::TimeType) -> TimeType + firstdayofweek(dt::TimeType) -> TimeType - Adjusts "dt" to the Monday of its week. -``` +Adjusts "dt" to the Monday of its week. """ Dates.firstdayofweek doc""" -```rst -lastdayofweek(dt::TimeType) -> TimeType + lastdayofweek(dt::TimeType) -> TimeType - Adjusts "dt" to the Sunday of its week. -``` +Adjusts "dt" to the Sunday of its week. """ Dates.lastdayofweek doc""" -```rst -firstdayofmonth(dt::TimeType) -> TimeType + firstdayofmonth(dt::TimeType) -> TimeType - Adjusts "dt" to the first day of its month. -``` +Adjusts "dt" to the first day of its month. """ Dates.firstdayofmonth doc""" -```rst -lastdayofmonth(dt::TimeType) -> TimeType + lastdayofmonth(dt::TimeType) -> TimeType - Adjusts "dt" to the last day of its month. -``` +Adjusts "dt" to the last day of its month. """ Dates.lastdayofmonth doc""" -```rst -firstdayofyear(dt::TimeType) -> TimeType + firstdayofyear(dt::TimeType) -> TimeType - Adjusts "dt" to the first day of its year. -``` +Adjusts "dt" to the first day of its year. """ Dates.firstdayofyear doc""" -```rst -lastdayofyear(dt::TimeType) -> TimeType + lastdayofyear(dt::TimeType) -> TimeType - Adjusts "dt" to the last day of its year. -``` +Adjusts "dt" to the last day of its year. """ Dates.lastdayofyear doc""" -```rst -firstdayofquarter(dt::TimeType) -> TimeType + firstdayofquarter(dt::TimeType) -> TimeType - Adjusts "dt" to the first day of its quarter. -``` +Adjusts "dt" to the first day of its quarter. """ Dates.firstdayofquarter doc""" -```rst -lastdayofquarter(dt::TimeType) -> TimeType + lastdayofquarter(dt::TimeType) -> TimeType - Adjusts "dt" to the last day of its quarter. -``` +Adjusts "dt" to the last day of its quarter. """ Dates.lastdayofquarter doc""" -```rst -tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - Adjusts "dt" to the next day of week corresponding to "dow" - with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows - the current "dt" to be considered as the next "dow", allowing - for no adjustment to occur. -``` +Adjusts "dt" to the next day of week corresponding to "dow" +with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows +the current "dt" to be considered as the next "dow", allowing +for no adjustment to occur. """ Dates.tonext doc""" -```rst -toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - Adjusts "dt" to the previous day of week corresponding to "dow" - with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows - the current "dt" to be considered as the previous "dow", - allowing for no adjustment to occur. -``` +Adjusts "dt" to the previous day of week corresponding to "dow" +with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows +the current "dt" to be considered as the previous "dow", +allowing for no adjustment to occur. """ Dates.toprev doc""" -```rst -tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts "dt" to the first "dow" of its month. Alternatively, - "of=Year" will adjust to the first "dow" of the year. -``` +Adjusts "dt" to the first "dow" of its month. Alternatively, +"of=Year" will adjust to the first "dow" of the year. """ Dates.tofirst doc""" -```rst -tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts "dt" to the last "dow" of its month. Alternatively, - "of=Year" will adjust to the last "dow" of the year. -``` +Adjusts "dt" to the last "dow" of its month. Alternatively, +"of=Year" will adjust to the last "dow" of the year. """ Dates.tolast doc""" -```rst -tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. -``` +Adjusts "dt" by iterating at most "limit" iterations by +"step" increments until "func" returns true. "func" must take +a single "TimeType" argument and return a "Bool". "same" +allows "dt" to be considered in satisfying "func". "negate" +will make the adjustment process terminate when "func" returns +false instead of true. """ Dates.tonext doc""" -```rst -toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. -``` +Adjusts "dt" by iterating at most "limit" iterations by +"step" increments until "func" returns true. "func" must take +a single "TimeType" argument and return a "Bool". "same" +allows "dt" to be considered in satisfying "func". "negate" +will make the adjustment process terminate when "func" returns +false instead of true. """ Dates.toprev doc""" -```rst -Year(v) + Year(v) Month(v) Week(v) Day(v) @@ -6663,10965 +5512,9109 @@ Minute(v) Second(v) Millisecond(v) - Construct a "Period" type with the given "v" value. Input must - be losslessly convertible to an "Int64". -``` +Construct a "Period" type with the given "v" value. Input must +be losslessly convertible to an "Int64". """ Dates.Year doc""" -```rst -default(p::Period) -> Period + default(p::Period) -> Period - Returns a sensible "default" value for the input Period by - returning "one(p)" for Year, Month, and Day, and "zero(p)" for - Hour, Minute, Second, and Millisecond. -``` +Returns a sensible "default" value for the input Period by +returning "one(p)" for Year, Month, and Day, and "zero(p)" for +Hour, Minute, Second, and Millisecond. """ Dates.default doc""" -```rst -today() -> Date + today() -> Date - Returns the date portion of "now()". -``` +Returns the date portion of "now()". """ Dates.today doc""" -```rst -unix2datetime(x) -> DateTime + unix2datetime(x) -> DateTime - Takes the number of seconds since unix epoch - "1970-01-01T00:00:00" and converts to the corresponding DateTime. -``` +Takes the number of seconds since unix epoch +"1970-01-01T00:00:00" and converts to the corresponding DateTime. """ Dates.unix2datetime doc""" -```rst -datetime2unix(dt::DateTime) -> Float64 + datetime2unix(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of seconds since - the unix epoch as a "Float64". -``` +Takes the given DateTime and returns the number of seconds since +the unix epoch as a "Float64". """ Dates.datetime2unix doc""" -```rst -julian2datetime(julian_days) -> DateTime + julian2datetime(julian_days) -> DateTime - Takes the number of Julian calendar days since epoch - "-4713-11-24T12:00:00" and returns the corresponding DateTime. -``` +Takes the number of Julian calendar days since epoch +"-4713-11-24T12:00:00" and returns the corresponding DateTime. """ Dates.julian2datetime doc""" -```rst -datetime2julian(dt::DateTime) -> Float64 + datetime2julian(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of Julian calendar - days since the julian epoch as a "Float64". -``` +Takes the given DateTime and returns the number of Julian calendar +days since the julian epoch as a "Float64". """ Dates.datetime2julian doc""" -```rst -rata2datetime(days) -> DateTime + rata2datetime(days) -> DateTime - Takes the number of Rata Die days since epoch - "0000-12-31T00:00:00" and returns the corresponding DateTime. -``` +Takes the number of Rata Die days since epoch +"0000-12-31T00:00:00" and returns the corresponding DateTime. """ Dates.rata2datetime doc""" -```rst -datetime2rata(dt::TimeType) -> Int64 + datetime2rata(dt::TimeType) -> Int64 - Returns the number of Rata Die days since epoch from the given Date - or DateTime. -``` +Returns the number of Rata Die days since epoch from the given Date +or DateTime. """ Dates.datetime2rata doc""" -```rst -pwd() -> AbstractString + pwd() -> AbstractString - Get the current working directory. -``` +Get the current working directory. """ pwd doc""" -```rst -cd(dir::AbstractString) + cd(dir::AbstractString) - Set the current working directory. -``` +Set the current working directory. """ cd doc""" -```rst -cd(f[, dir]) + cd(f[, dir]) - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. -``` +Temporarily changes the current working directory (HOME if not +specified) and applies function f before returning. """ cd doc""" -```rst -readdir([dir]) -> Vector{ByteString} + readdir([dir]) -> Vector{ByteString} - Returns the files and directories in the directory *dir* (or the - current working directory if not given). -``` +Returns the files and directories in the directory *dir* (or the +current working directory if not given). """ readdir doc""" -```rst -mkdir(path[, mode]) + mkdir(path[, mode]) - Make a new directory with name "path" and permissions "mode". - "mode" defaults to 0o777, modified by the current file creation - mask. -``` +Make a new directory with name "path" and permissions "mode". +"mode" defaults to 0o777, modified by the current file creation +mask. """ mkdir doc""" -```rst -mkpath(path[, mode]) + mkpath(path[, mode]) - Create all directories in the given "path", with permissions - "mode". "mode" defaults to 0o777, modified by the current file - creation mask. -``` +Create all directories in the given "path", with permissions +"mode". "mode" defaults to 0o777, modified by the current file +creation mask. """ mkpath doc""" -```rst -symlink(target, link) + symlink(target, link) - Creates a symbolic link to "target" with the name "link". +Creates a symbolic link to "target" with the name "link". - Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. -``` +Note: This function raises an error under operating systems that + do not support soft symbolic links, such as Windows XP. """ symlink doc""" -```rst -readlink(path) -> AbstractString + readlink(path) -> AbstractString - Returns the value of a symbolic link "path". -``` +Returns the value of a symbolic link "path". """ readlink doc""" -```rst -chmod(path, mode) + chmod(path, mode) - Change the permissions mode of "path" to "mode". Only integer - "mode"s (e.g. 0o777) are currently supported. -``` +Change the permissions mode of "path" to "mode". Only integer +"mode"s (e.g. 0o777) are currently supported. """ chmod doc""" -```rst -stat(file) - - Returns a structure whose fields contain information about the - file. The fields of the structure are: - - +-----------+------------------------------------------------------------------------+ - | size | The size (in bytes) of the file | - +-----------+------------------------------------------------------------------------+ - | device | ID of the device that contains the file | - +-----------+------------------------------------------------------------------------+ - | inode | The inode number of the file | - +-----------+------------------------------------------------------------------------+ - | mode | The protection mode of the file | - +-----------+------------------------------------------------------------------------+ - | nlink | The number of hard links to the file | - +-----------+------------------------------------------------------------------------+ - | uid | The user id of the owner of the file | - +-----------+------------------------------------------------------------------------+ - | gid | The group id of the file owner | - +-----------+------------------------------------------------------------------------+ - | rdev | If this file refers to a device, the ID of the device it refers to | - +-----------+------------------------------------------------------------------------+ - | blksize | The file-system preferred block size for the file | - +-----------+------------------------------------------------------------------------+ - | blocks | The number of such blocks allocated | - +-----------+------------------------------------------------------------------------+ - | mtime | Unix timestamp of when the file was last modified | - +-----------+------------------------------------------------------------------------+ - | ctime | Unix timestamp of when the file was created | - +-----------+------------------------------------------------------------------------+ -``` + stat(file) + +Returns a structure whose fields contain information about the +file. The fields of the structure are: + ++-----------+------------------------------------------------------------------------+ +| size | The size (in bytes) of the file | ++-----------+------------------------------------------------------------------------+ +| device | ID of the device that contains the file | ++-----------+------------------------------------------------------------------------+ +| inode | The inode number of the file | ++-----------+------------------------------------------------------------------------+ +| mode | The protection mode of the file | ++-----------+------------------------------------------------------------------------+ +| nlink | The number of hard links to the file | ++-----------+------------------------------------------------------------------------+ +| uid | The user id of the owner of the file | ++-----------+------------------------------------------------------------------------+ +| gid | The group id of the file owner | ++-----------+------------------------------------------------------------------------+ +| rdev | If this file refers to a device, the ID of the device it refers to | ++-----------+------------------------------------------------------------------------+ +| blksize | The file-system preferred block size for the file | ++-----------+------------------------------------------------------------------------+ +| blocks | The number of such blocks allocated | ++-----------+------------------------------------------------------------------------+ +| mtime | Unix timestamp of when the file was last modified | ++-----------+------------------------------------------------------------------------+ +| ctime | Unix timestamp of when the file was created | ++-----------+------------------------------------------------------------------------+ """ stat doc""" -```rst -lstat(file) + lstat(file) - Like stat, but for symbolic links gets the info for the link itself - rather than the file it refers to. This function must be called on - a file path rather than a file object or a file descriptor. -``` +Like stat, but for symbolic links gets the info for the link itself +rather than the file it refers to. This function must be called on +a file path rather than a file object or a file descriptor. """ lstat doc""" -```rst -ctime(file) + ctime(file) - Equivalent to stat(file).ctime -``` +Equivalent to stat(file).ctime """ ctime doc""" -```rst -mtime(file) + mtime(file) - Equivalent to stat(file).mtime -``` +Equivalent to stat(file).mtime """ mtime doc""" -```rst -filemode(file) + filemode(file) - Equivalent to stat(file).mode -``` +Equivalent to stat(file).mode """ filemode doc""" -```rst -filesize(path...) + filesize(path...) - Equivalent to stat(file).size -``` +Equivalent to stat(file).size """ filesize doc""" -```rst -uperm(file) + uperm(file) - Gets the permissions of the owner of the file as a bitfield of +Gets the permissions of the owner of the file as a bitfield of - +------+-----------------------+ - | 01 | Execute Permission | - +------+-----------------------+ - | 02 | Write Permission | - +------+-----------------------+ - | 04 | Read Permission | - +------+-----------------------+ ++------+-----------------------+ +| 01 | Execute Permission | ++------+-----------------------+ +| 02 | Write Permission | ++------+-----------------------+ +| 04 | Read Permission | ++------+-----------------------+ - For allowed arguments, see "stat". -``` +For allowed arguments, see "stat". """ uperm doc""" -```rst -gperm(file) + gperm(file) - Like uperm but gets the permissions of the group owning the file -``` +Like uperm but gets the permissions of the group owning the file """ gperm doc""" -```rst -operm(file) + operm(file) - Like uperm but gets the permissions for people who neither own the - file nor are a member of the group owning the file -``` +Like uperm but gets the permissions for people who neither own the +file nor are a member of the group owning the file """ operm doc""" -```rst -cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - Copy the file, link, or directory from *src* to *dest*. - "remove_destination=true" will first remove an existing *dst*. +Copy the file, link, or directory from *src* to *dest*. +"remove_destination=true" will first remove an existing *dst*. - If *follow_symlinks=false*, and src is a symbolic link, dst will be - created as a symbolic link. If *follow_symlinks=true* and src is a - symbolic link, dst will be a copy of the file or directory *src* - refers to. -``` +If *follow_symlinks=false*, and src is a symbolic link, dst will be +created as a symbolic link. If *follow_symlinks=true* and src is a +symbolic link, dst will be a copy of the file or directory *src* +refers to. """ cp doc""" -```rst -download(url[, localfile]) + download(url[, localfile]) - Download a file from the given url, optionally renaming it to the - given local file name. Note that this function relies on the - availability of external tools such as "curl", "wget" or - "fetch" to download the file and is provided for convenience. For - production use or situations in which more options are need, please - use a package that provides the desired functionality instead. -``` +Download a file from the given url, optionally renaming it to the +given local file name. Note that this function relies on the +availability of external tools such as "curl", "wget" or +"fetch" to download the file and is provided for convenience. For +production use or situations in which more options are need, please +use a package that provides the desired functionality instead. """ download doc""" -```rst -mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - Move the file, link, or directory from *src* to *dest*. - "remove_destination=true" will first remove an existing *dst*. -``` +Move the file, link, or directory from *src* to *dest*. +"remove_destination=true" will first remove an existing *dst*. """ mv doc""" -```rst -rm(path::AbstractString; recursive=false) + rm(path::AbstractString; recursive=false) - Delete the file, link, or empty directory at the given path. If - "recursive=true" is passed and the path is a directory, then all - contents are removed recursively. -``` +Delete the file, link, or empty directory at the given path. If +"recursive=true" is passed and the path is a directory, then all +contents are removed recursively. """ rm doc""" -```rst -touch(path::AbstractString) + touch(path::AbstractString) - Update the last-modified timestamp on a file to the current time. -``` +Update the last-modified timestamp on a file to the current time. """ touch doc""" -```rst -tempname() + tempname() - Generate a unique temporary file path. -``` +Generate a unique temporary file path. """ tempname doc""" -```rst -tempdir() + tempdir() - Obtain the path of a temporary directory (possibly shared with - other processes). -``` +Obtain the path of a temporary directory (possibly shared with +other processes). """ tempdir doc""" -```rst -mktemp([parent=tempdir()]) + mktemp([parent=tempdir()]) - Returns "(path, io)", where "path" is the path of a new - temporary file in "parent" and "io" is an open file object for - this path. -``` +Returns "(path, io)", where "path" is the path of a new +temporary file in "parent" and "io" is an open file object for +this path. """ mktemp doc""" -```rst -mktempdir([parent=tempdir()]) + mktempdir([parent=tempdir()]) - Create a temporary directory in the "parent" directory and return - its path. -``` +Create a temporary directory in the "parent" directory and return +its path. """ mktempdir doc""" -```rst -isblockdev(path) -> Bool + isblockdev(path) -> Bool - Returns "true" if "path" is a block device, "false" - otherwise. -``` +Returns "true" if "path" is a block device, "false" +otherwise. """ isblockdev doc""" -```rst -ischardev(path) -> Bool + ischardev(path) -> Bool - Returns "true" if "path" is a character device, "false" - otherwise. -``` +Returns "true" if "path" is a character device, "false" +otherwise. """ ischardev doc""" -```rst -isdir(path) -> Bool + isdir(path) -> Bool - Returns "true" if "path" is a directory, "false" otherwise. -``` +Returns "true" if "path" is a directory, "false" otherwise. """ isdir doc""" -```rst -isexecutable(path) -> Bool + isexecutable(path) -> Bool - Returns "true" if the current user has permission to execute - "path", "false" otherwise. -``` +Returns "true" if the current user has permission to execute +"path", "false" otherwise. """ isexecutable doc""" -```rst -isfifo(path) -> Bool + isfifo(path) -> Bool - Returns "true" if "path" is a FIFO, "false" otherwise. -``` +Returns "true" if "path" is a FIFO, "false" otherwise. """ isfifo doc""" -```rst -isfile(path) -> Bool + isfile(path) -> Bool - Returns "true" if "path" is a regular file, "false" - otherwise. -``` +Returns "true" if "path" is a regular file, "false" +otherwise. """ isfile doc""" -```rst -islink(path) -> Bool + islink(path) -> Bool - Returns "true" if "path" is a symbolic link, "false" - otherwise. -``` +Returns "true" if "path" is a symbolic link, "false" +otherwise. """ islink doc""" -```rst -ismount(path) -> Bool + ismount(path) -> Bool - Returns "true" if "path" is a mount point, "false" otherwise. -``` +Returns "true" if "path" is a mount point, "false" otherwise. """ ismount doc""" -```rst -ispath(path) -> Bool + ispath(path) -> Bool - Returns "true" if "path" is a valid filesystem path, "false" - otherwise. -``` +Returns "true" if "path" is a valid filesystem path, "false" +otherwise. """ ispath doc""" -```rst -isreadable(path) -> Bool + isreadable(path) -> Bool - Returns "true" if the current user has permission to read - "path", "false" otherwise. -``` +Returns "true" if the current user has permission to read +"path", "false" otherwise. """ isreadable doc""" -```rst -issetgid(path) -> Bool + issetgid(path) -> Bool - Returns "true" if "path" has the setgid flag set, "false" - otherwise. -``` +Returns "true" if "path" has the setgid flag set, "false" +otherwise. """ issetgid doc""" -```rst -issetuid(path) -> Bool + issetuid(path) -> Bool - Returns "true" if "path" has the setuid flag set, "false" - otherwise. -``` +Returns "true" if "path" has the setuid flag set, "false" +otherwise. """ issetuid doc""" -```rst -issocket(path) -> Bool + issocket(path) -> Bool - Returns "true" if "path" is a socket, "false" otherwise. -``` +Returns "true" if "path" is a socket, "false" otherwise. """ issocket doc""" -```rst -issticky(path) -> Bool + issticky(path) -> Bool - Returns "true" if "path" has the sticky bit set, "false" - otherwise. -``` +Returns "true" if "path" has the sticky bit set, "false" +otherwise. """ issticky doc""" -```rst -iswritable(path) -> Bool + iswritable(path) -> Bool - Returns "true" if the current user has permission to write to - "path", "false" otherwise. -``` +Returns "true" if the current user has permission to write to +"path", "false" otherwise. """ iswritable doc""" -```rst -homedir() -> AbstractString + homedir() -> AbstractString - Return the current user's home directory. -``` +Return the current user's home directory. """ homedir doc""" -```rst -dirname(path::AbstractString) -> AbstractString + dirname(path::AbstractString) -> AbstractString - Get the directory part of a path. -``` +Get the directory part of a path. """ dirname doc""" -```rst -basename(path::AbstractString) -> AbstractString + basename(path::AbstractString) -> AbstractString - Get the file name part of a path. -``` +Get the file name part of a path. """ basename doc""" -```rst -@__FILE__() -> AbstractString + @__FILE__() -> AbstractString - "@__FILE__" expands to a string with the absolute path and file - name of the script being run. Returns "nothing" if run from a - REPL or an empty string if evaluated by "julia -e ". -``` +"@__FILE__" expands to a string with the absolute path and file +name of the script being run. Returns "nothing" if run from a +REPL or an empty string if evaluated by "julia -e ". """ @__FILE__ doc""" -```rst -isabspath(path::AbstractString) -> Bool + isabspath(path::AbstractString) -> Bool - Determines whether a path is absolute (begins at the root - directory). -``` +Determines whether a path is absolute (begins at the root +directory). """ isabspath doc""" -```rst -isdirpath(path::AbstractString) -> Bool + isdirpath(path::AbstractString) -> Bool - Determines whether a path refers to a directory (for example, ends - with a path separator). -``` +Determines whether a path refers to a directory (for example, ends +with a path separator). """ isdirpath doc""" -```rst -joinpath(parts...) -> AbstractString + joinpath(parts...) -> AbstractString - Join path components into a full path. If some argument is an - absolute path, then prior components are dropped. -``` +Join path components into a full path. If some argument is an +absolute path, then prior components are dropped. """ joinpath doc""" -```rst -abspath(path::AbstractString) -> AbstractString + abspath(path::AbstractString) -> AbstractString - Convert a path to an absolute path by adding the current directory - if necessary. -``` +Convert a path to an absolute path by adding the current directory +if necessary. """ abspath doc""" -```rst -normpath(path::AbstractString) -> AbstractString + normpath(path::AbstractString) -> AbstractString - Normalize a path, removing "." and ".." entries. -``` +Normalize a path, removing "." and ".." entries. """ normpath doc""" -```rst -realpath(path::AbstractString) -> AbstractString + realpath(path::AbstractString) -> AbstractString - Canonicalize a path by expanding symbolic links and removing "." - and ".." entries. -``` +Canonicalize a path by expanding symbolic links and removing "." +and ".." entries. """ realpath doc""" -```rst -relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString + relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - Return a relative filepath to path either from the current - directory or from an optional start directory. This is a path - computation: the filesystem is not accessed to confirm the - existence or nature of path or startpath. -``` +Return a relative filepath to path either from the current +directory or from an optional start directory. This is a path +computation: the filesystem is not accessed to confirm the +existence or nature of path or startpath. """ relpath doc""" -```rst -expanduser(path::AbstractString) -> AbstractString + expanduser(path::AbstractString) -> AbstractString - On Unix systems, replace a tilde character at the start of a path - with the current user's home directory. -``` +On Unix systems, replace a tilde character at the start of a path +with the current user's home directory. """ expanduser doc""" -```rst -splitdir(path::AbstractString) -> (AbstractString, AbstractString) + splitdir(path::AbstractString) -> (AbstractString, AbstractString) - Split a path into a tuple of the directory name and file name. -``` +Split a path into a tuple of the directory name and file name. """ splitdir doc""" -```rst -splitdrive(path::AbstractString) -> (AbstractString, AbstractString) + splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - On Windows, split a path into the drive letter part and the path - part. On Unix systems, the first component is always the empty - string. -``` +On Windows, split a path into the drive letter part and the path +part. On Unix systems, the first component is always the empty +string. """ splitdrive doc""" -```rst -splitext(path::AbstractString) -> (AbstractString, AbstractString) + splitext(path::AbstractString) -> (AbstractString, AbstractString) - If the last component of a path contains a dot, split the path into - everything before the dot and everything including and after the - dot. Otherwise, return a tuple of the argument unmodified and the - empty string. -``` +If the last component of a path contains a dot, split the path into +everything before the dot and everything including and after the +dot. Otherwise, return a tuple of the argument unmodified and the +empty string. """ splitext doc""" -```rst -open(file_name[, read, write, create, truncate, append]) -> IOStream + open(file_name[, read, write, create, truncate, append]) -> IOStream - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. -``` +Open a file in a mode specified by five boolean arguments. The +default is to open files for reading only. Returns a stream for +accessing the file. """ open doc""" -```rst -open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of "mode" - correspond to those from "fopen(3)" or Perl "open", and are - equivalent to setting the following boolean groups: - - +------+-----------------------------------+ - | r | read | - +------+-----------------------------------+ - | r+ | read, write | - +------+-----------------------------------+ - | w | write, create, truncate | - +------+-----------------------------------+ - | w+ | read, write, create, truncate | - +------+-----------------------------------+ - | a | write, create, append | - +------+-----------------------------------+ - | a+ | read, write, create, append | - +------+-----------------------------------+ -``` + open(file_name[, mode]) -> IOStream + +Alternate syntax for open, where a string-based mode specifier is +used instead of the five booleans. The values of "mode" +correspond to those from "fopen(3)" or Perl "open", and are +equivalent to setting the following boolean groups: + ++------+-----------------------------------+ +| r | read | ++------+-----------------------------------+ +| r+ | read, write | ++------+-----------------------------------+ +| w | write, create, truncate | ++------+-----------------------------------+ +| w+ | read, write, create, truncate | ++------+-----------------------------------+ +| a | write, create, append | ++------+-----------------------------------+ +| a+ | read, write, create, append | ++------+-----------------------------------+ """ open doc""" -```rst -open(f::function, args...) + open(f::function, args...) - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. +Apply the function "f" to the result of "open(args...)" and +close the resulting file descriptor upon completion. - **Example**: "open(readall, "file.txt")" -``` +**Example**: "open(readall, "file.txt")" """ open doc""" -```rst -IOBuffer() -> IOBuffer + IOBuffer() -> IOBuffer - Create an in-memory I/O stream. -``` +Create an in-memory I/O stream. """ IOBuffer doc""" -```rst -IOBuffer(size::Int) + IOBuffer(size::Int) - Create a fixed size IOBuffer. The buffer will not grow dynamically. -``` +Create a fixed size IOBuffer. The buffer will not grow dynamically. """ IOBuffer doc""" -```rst -IOBuffer(string) + IOBuffer(string) - Create a read-only IOBuffer on the data underlying the given string -``` +Create a read-only IOBuffer on the data underlying the given string """ IOBuffer doc""" -```rst -IOBuffer([data][, readable, writable[, maxsize]]) + IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. -``` +Create an IOBuffer, which may optionally operate on a pre-existing +array. If the readable/writable arguments are given, they restrict +whether or not the buffer may be read from or written to +respectively. By default the buffer is readable but not writable. +The last argument optionally specifies a size beyond which the +buffer may not be grown. """ IOBuffer doc""" -```rst -takebuf_array(b::IOBuffer) + takebuf_array(b::IOBuffer) - Obtain the contents of an "IOBuffer" as an array, without - copying. Afterwards, the IOBuffer is reset to its initial state. -``` +Obtain the contents of an "IOBuffer" as an array, without +copying. Afterwards, the IOBuffer is reset to its initial state. """ takebuf_array doc""" -```rst -takebuf_string(b::IOBuffer) + takebuf_string(b::IOBuffer) - Obtain the contents of an "IOBuffer" as a string, without - copying. Afterwards, the IOBuffer is reset to its initial state. -``` +Obtain the contents of an "IOBuffer" as a string, without +copying. Afterwards, the IOBuffer is reset to its initial state. """ takebuf_string doc""" -```rst -fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - Create an "IOStream" object from an integer file descriptor. If - "own" is true, closing this object will close the underlying - descriptor. By default, an "IOStream" is closed when it is - garbage collected. "name" allows you to associate the descriptor - with a named file. -``` +Create an "IOStream" object from an integer file descriptor. If +"own" is true, closing this object will close the underlying +descriptor. By default, an "IOStream" is closed when it is +garbage collected. "name" allows you to associate the descriptor +with a named file. """ fdio doc""" -```rst -flush(stream) + flush(stream) - Commit all currently buffered writes to the given stream. -``` +Commit all currently buffered writes to the given stream. """ flush doc""" -```rst -close(stream) + close(stream) - Close an I/O stream. Performs a "flush" first. -``` +Close an I/O stream. Performs a "flush" first. """ close doc""" -```rst -write(stream, x) + write(stream, x) - Write the canonical binary representation of a value to the given - stream. -``` +Write the canonical binary representation of a value to the given +stream. """ write doc""" -```rst -read(stream, type) + read(stream, type) - Read a value of the given type from a stream, in canonical binary - representation. -``` +Read a value of the given type from a stream, in canonical binary +representation. """ read doc""" -```rst -read(stream, type, dims) + read(stream, type, dims) - Read a series of values of the given type from a stream, in - canonical binary representation. "dims" is either a tuple or a - series of integer arguments specifying the size of "Array" to - return. -``` +Read a series of values of the given type from a stream, in +canonical binary representation. "dims" is either a tuple or a +series of integer arguments specifying the size of "Array" to +return. """ read doc""" -```rst -read!(stream, array::Array) + read!(stream, array::Array) - Read binary data from a stream, filling in the argument "array". -``` +Read binary data from a stream, filling in the argument "array". """ read! doc""" -```rst -readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - Read at most "nb" bytes from the stream into "b", returning the - number of bytes read (increasing the size of "b" as needed). -``` +Read at most "nb" bytes from the stream into "b", returning the +number of bytes read (increasing the size of "b" as needed). """ readbytes! doc""" -```rst -readbytes(stream, nb=typemax(Int)) + readbytes(stream, nb=typemax(Int)) - Read at most "nb" bytes from the stream, returning a - "Vector{UInt8}" of the bytes read. -``` +Read at most "nb" bytes from the stream, returning a +"Vector{UInt8}" of the bytes read. """ readbytes doc""" -```rst -position(s) + position(s) - Get the current position of a stream. -``` +Get the current position of a stream. """ position doc""" -```rst -seek(s, pos) + seek(s, pos) - Seek a stream to the given position. -``` +Seek a stream to the given position. """ seek doc""" -```rst -seekstart(s) + seekstart(s) - Seek a stream to its beginning. -``` +Seek a stream to its beginning. """ seekstart doc""" -```rst -seekend(s) + seekend(s) - Seek a stream to its end. -``` +Seek a stream to its end. """ seekend doc""" -```rst -skip(s, offset) + skip(s, offset) - Seek a stream relative to the current position. -``` +Seek a stream relative to the current position. """ skip doc""" -```rst -mark(s) + mark(s) - Add a mark at the current position of stream "s". Returns the - marked position. +Add a mark at the current position of stream "s". Returns the +marked position. - See also "unmark()", "reset()", "ismarked()" -``` +See also "unmark()", "reset()", "ismarked()" """ mark doc""" -```rst -unmark(s) + unmark(s) - Remove a mark from stream "s". Returns "true" if the stream was - marked, "false" otherwise. +Remove a mark from stream "s". Returns "true" if the stream was +marked, "false" otherwise. - See also "mark()", "reset()", "ismarked()" -``` +See also "mark()", "reset()", "ismarked()" """ unmark doc""" -```rst -reset(s) + reset(s) - Reset a stream "s" to a previously marked position, and remove - the mark. Returns the previously marked position. Throws an error - if the stream is not marked. +Reset a stream "s" to a previously marked position, and remove +the mark. Returns the previously marked position. Throws an error +if the stream is not marked. - See also "mark()", "unmark()", "ismarked()" -``` +See also "mark()", "unmark()", "ismarked()" """ reset doc""" -```rst -ismarked(s) + ismarked(s) - Returns true if stream "s" is marked. +Returns true if stream "s" is marked. - See also "mark()", "unmark()", "reset()" -``` +See also "mark()", "unmark()", "reset()" """ ismarked doc""" -```rst -eof(stream) -> Bool + eof(stream) -> Bool - Tests whether an I/O stream is at end-of-file. If the stream is not - yet exhausted, this function will block to wait for more data if - necessary, and then return "false". Therefore it is always safe - to read one byte after seeing "eof" return "false". "eof" - will return "false" as long as buffered data is still available, - even if the remote end of a connection is closed. -``` +Tests whether an I/O stream is at end-of-file. If the stream is not +yet exhausted, this function will block to wait for more data if +necessary, and then return "false". Therefore it is always safe +to read one byte after seeing "eof" return "false". "eof" +will return "false" as long as buffered data is still available, +even if the remote end of a connection is closed. """ eof doc""" -```rst -isreadonly(stream) -> Bool + isreadonly(stream) -> Bool - Determine whether a stream is read-only. -``` +Determine whether a stream is read-only. """ isreadonly doc""" -```rst -isopen(stream) -> Bool + isopen(stream) -> Bool - Determine whether a stream is open (i.e. has not been closed yet). - If the connection has been closed remotely (in case of e.g. a - socket), "isopen" will return "false" even though buffered data - may still be available. Use "eof" to check if necessary. -``` +Determine whether a stream is open (i.e. has not been closed yet). +If the connection has been closed remotely (in case of e.g. a +socket), "isopen" will return "false" even though buffered data +may still be available. Use "eof" to check if necessary. """ isopen doc""" -```rst -serialize(stream, value) + serialize(stream, value) - Write an arbitrary value to a stream in an opaque format, such that - it can be read back by "deserialize". The read-back value will be - as identical as possible to the original. In general, this process - will not work if the reading and writing are done by different - versions of Julia, or an instance of Julia with a different system - image. -``` +Write an arbitrary value to a stream in an opaque format, such that +it can be read back by "deserialize". The read-back value will be +as identical as possible to the original. In general, this process +will not work if the reading and writing are done by different +versions of Julia, or an instance of Julia with a different system +image. """ serialize doc""" -```rst -deserialize(stream) + deserialize(stream) - Read a value written by "serialize". -``` +Read a value written by "serialize". """ deserialize doc""" -```rst -print_escaped(io, str::AbstractString, esc::AbstractString) + print_escaped(io, str::AbstractString, esc::AbstractString) - General escaping of traditional C and Unicode escape sequences, - plus any characters in esc are also escaped (with a backslash). -``` +General escaping of traditional C and Unicode escape sequences, +plus any characters in esc are also escaped (with a backslash). """ print_escaped doc""" -```rst -print_unescaped(io, s::AbstractString) + print_unescaped(io, s::AbstractString) - General unescaping of traditional C and Unicode escape sequences. - Reverse of "print_escaped()". -``` +General unescaping of traditional C and Unicode escape sequences. +Reverse of "print_escaped()". """ print_unescaped doc""" -```rst -print_joined(io, items, delim[, last]) + print_joined(io, items, delim[, last]) - Print elements of "items" to "io" with "delim" between them. - If "last" is specified, it is used as the final delimiter instead - of "delim". -``` +Print elements of "items" to "io" with "delim" between them. +If "last" is specified, it is used as the final delimiter instead +of "delim". """ print_joined doc""" -```rst -print_shortest(io, x) + print_shortest(io, x) - Print the shortest possible representation, with the minimum number - of consecutive non-zero digits, of number "x", ensuring that it - would parse to the exact same number. -``` +Print the shortest possible representation, with the minimum number +of consecutive non-zero digits, of number "x", ensuring that it +would parse to the exact same number. """ print_shortest doc""" -```rst -fd(stream) + fd(stream) - Returns the file descriptor backing the stream or file. Note that - this function only applies to synchronous *File*'s and *IOStream*'s - not to any of the asynchronous streams. -``` +Returns the file descriptor backing the stream or file. Note that +this function only applies to synchronous *File*'s and *IOStream*'s +not to any of the asynchronous streams. """ fd doc""" -```rst -redirect_stdout() + redirect_stdout() - Create a pipe to which all C and Julia level STDOUT output will be - redirected. Returns a tuple (rd,wr) representing the pipe ends. - Data written to STDOUT may now be read from the rd end of the pipe. - The wr end is given for convenience in case the old STDOUT object - was cached by the user and needs to be replaced elsewhere. -``` +Create a pipe to which all C and Julia level STDOUT output will be +redirected. Returns a tuple (rd,wr) representing the pipe ends. +Data written to STDOUT may now be read from the rd end of the pipe. +The wr end is given for convenience in case the old STDOUT object +was cached by the user and needs to be replaced elsewhere. """ redirect_stdout doc""" -```rst -redirect_stdout(stream) + redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. -``` +Replace STDOUT by stream for all C and julia level output to +STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. """ redirect_stdout doc""" -```rst -redirect_stderr([stream]) + redirect_stderr([stream]) - Like redirect_stdout, but for STDERR -``` +Like redirect_stdout, but for STDERR """ redirect_stderr doc""" -```rst -redirect_stdin([stream]) + redirect_stdin([stream]) - Like redirect_stdout, but for STDIN. Note that the order of the - return tuple is still (rd,wr), i.e. data to be read from STDIN, may - be written to wr. -``` +Like redirect_stdout, but for STDIN. Note that the order of the +return tuple is still (rd,wr), i.e. data to be read from STDIN, may +be written to wr. """ redirect_stdin doc""" -```rst -readchomp(x) + readchomp(x) - Read the entirety of x as a string but remove trailing newlines. - Equivalent to chomp(readall(x)). -``` +Read the entirety of x as a string but remove trailing newlines. +Equivalent to chomp(readall(x)). """ readchomp doc""" -```rst -truncate(file, n) + truncate(file, n) - Resize the file or buffer given by the first argument to exactly - *n* bytes, filling previously unallocated space with '\0' if the - file or buffer is grown -``` +Resize the file or buffer given by the first argument to exactly +*n* bytes, filling previously unallocated space with '\0' if the +file or buffer is grown """ truncate doc""" -```rst -skipchars(stream, predicate; linecomment::Char) + skipchars(stream, predicate; linecomment::Char) - Advance the stream until before the first character for which - "predicate" returns false. For example "skipchars(stream, - isspace)" will skip all whitespace. If keyword argument - "linecomment" is specified, characters from that character - through the end of a line will also be skipped. -``` +Advance the stream until before the first character for which +"predicate" returns false. For example "skipchars(stream, +isspace)" will skip all whitespace. If keyword argument +"linecomment" is specified, characters from that character +through the end of a line will also be skipped. """ skipchars doc""" -```rst -countlines(io[, eol::Char]) + countlines(io[, eol::Char]) - Read io until the end of the stream/file and count the number of - non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than '\n' are supported by passing - them as the second argument. -``` +Read io until the end of the stream/file and count the number of +non-empty lines. To specify a file pass the filename as the first +argument. EOL markers other than '\n' are supported by passing +them as the second argument. """ countlines doc""" -```rst -PipeBuffer() + PipeBuffer() - An IOBuffer that allows reading and performs writes by appending. - Seeking and truncating are not supported. See IOBuffer for the - available constructors. -``` +An IOBuffer that allows reading and performs writes by appending. +Seeking and truncating are not supported. See IOBuffer for the +available constructors. """ PipeBuffer doc""" -```rst -PipeBuffer(data::Vector{UInt8}[, maxsize]) + PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. -``` +Create a PipeBuffer to operate on a data vector, optionally +specifying a size beyond which the underlying Array may not be +grown. """ PipeBuffer doc""" -```rst -readavailable(stream) + readavailable(stream) - Read all available data on the stream, blocking the task only if no - data is available. The result is a "Vector{UInt8,1}". -``` +Read all available data on the stream, blocking the task only if no +data is available. The result is a "Vector{UInt8,1}". """ readavailable doc""" -```rst -show(x) + show(x) - Write an informative text representation of a value to the current - output stream. New types should overload "show(io, x)" where the - first argument is a stream. The representation used by "show" - generally includes Julia-specific formatting and type information. -``` +Write an informative text representation of a value to the current +output stream. New types should overload "show(io, x)" where the +first argument is a stream. The representation used by "show" +generally includes Julia-specific formatting and type information. """ show doc""" -```rst -showcompact(x) + showcompact(x) - Show a more compact representation of a value. This is used for - printing array elements. If a new type has a different compact - representation, it should overload "showcompact(io, x)" where the - first argument is a stream. -``` +Show a more compact representation of a value. This is used for +printing array elements. If a new type has a different compact +representation, it should overload "showcompact(io, x)" where the +first argument is a stream. """ showcompact doc""" -```rst -showall(x) + showall(x) - Similar to "show", except shows all elements of arrays. -``` +Similar to "show", except shows all elements of arrays. """ showall doc""" -```rst -summary(x) + summary(x) - Return a string giving a brief description of a value. By default - returns "string(typeof(x))". For arrays, returns strings like - "2x2 Float64 Array". -``` +Return a string giving a brief description of a value. By default +returns "string(typeof(x))". For arrays, returns strings like +"2x2 Float64 Array". """ summary doc""" -```rst -print(x) + print(x) - Write (to the default output stream) a canonical (un-decorated) - text representation of a value if there is one, otherwise call - "show". The representation used by "print" includes minimal - formatting and tries to avoid Julia-specific details. -``` +Write (to the default output stream) a canonical (un-decorated) +text representation of a value if there is one, otherwise call +"show". The representation used by "print" includes minimal +formatting and tries to avoid Julia-specific details. """ print doc""" -```rst -println(x) + println(x) - Print (using "print()") "x" followed by a newline. -``` +Print (using "print()") "x" followed by a newline. """ println doc""" -```rst -print_with_color(color::Symbol[, io], strings...) + print_with_color(color::Symbol[, io], strings...) - Print strings in a color specified as a symbol, for example - ":red" or ":blue". -``` +Print strings in a color specified as a symbol, for example +":red" or ":blue". """ print_with_color doc""" -```rst -info(msg) + info(msg) - Display an informational message. -``` +Display an informational message. """ info doc""" -```rst -warn(msg) + warn(msg) - Display a warning. -``` +Display a warning. """ warn doc""" -```rst -@printf([io::IOStream], "%Fmt", args...) + @printf([io::IOStream], "%Fmt", args...) - Print arg(s) using C "printf()" style format specification - string. Optionally, an IOStream may be passed as the first argument - to redirect output. -``` +Print arg(s) using C "printf()" style format specification +string. Optionally, an IOStream may be passed as the first argument +to redirect output. """ @printf doc""" -```rst -@sprintf("%Fmt", args...) + @sprintf("%Fmt", args...) - Return "@printf" formatted output as string. -``` +Return "@printf" formatted output as string. """ @sprintf doc""" -```rst -sprint(f::Function, args...) + sprint(f::Function, args...) - Call the given function with an I/O stream and the supplied extra - arguments. Everything written to this I/O stream is returned as a - string. -``` +Call the given function with an I/O stream and the supplied extra +arguments. Everything written to this I/O stream is returned as a +string. """ sprint doc""" -```rst -showerror(io, e) + showerror(io, e) - Show a descriptive representation of an exception object. -``` +Show a descriptive representation of an exception object. """ showerror doc""" -```rst -dump(x) + dump(x) - Show all user-visible structure of a value. -``` +Show all user-visible structure of a value. """ dump doc""" -```rst -xdump(x) + xdump(x) - Show all structure of a value, including all fields of objects. -``` +Show all structure of a value, including all fields of objects. """ xdump doc""" -```rst -readall(stream::IO) + readall(stream::IO) - Read the entire contents of an I/O stream as a string. -``` +Read the entire contents of an I/O stream as a string. """ readall doc""" -```rst -readall(filename::AbstractString) + readall(filename::AbstractString) - Open "filename", read the entire contents as a string, then close - the file. Equivalent to "open(readall, filename)". -``` +Open "filename", read the entire contents as a string, then close +the file. Equivalent to "open(readall, filename)". """ readall doc""" -```rst -readline(stream=STDIN) + readline(stream=STDIN) - Read a single line of text, including a trailing newline character - (if one is reached before the end of the input), from the given - "stream" (defaults to "STDIN"), -``` +Read a single line of text, including a trailing newline character +(if one is reached before the end of the input), from the given +"stream" (defaults to "STDIN"), """ readline doc""" -```rst -readuntil(stream, delim) + readuntil(stream, delim) - Read a string, up to and including the given delimiter byte. -``` +Read a string, up to and including the given delimiter byte. """ readuntil doc""" -```rst -readlines(stream) + readlines(stream) - Read all lines as an array. -``` +Read all lines as an array. """ readlines doc""" -```rst -eachline(stream) + eachline(stream) - Create an iterable object that will yield each line from a stream. -``` +Create an iterable object that will yield each line from a stream. """ eachline doc""" -```rst -readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by - "eol") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. +Read a matrix from the source where each line (separated by +"eol") gives one row, with elements separated by the given +delimeter. The source can be a text file, stream or byte array. +Memory mapped files can be used by passing the byte array +representation of the mapped segment as source. - If "T" is a numeric type, the result is an array of that type, - with any non-numeric elements as "NaN" for floating-point types, - or zero. Other useful values of "T" include "ASCIIString", - "AbstractString", and "Any". +If "T" is a numeric type, the result is an array of that type, +with any non-numeric elements as "NaN" for floating-point types, +or zero. Other useful values of "T" include "ASCIIString", +"AbstractString", and "Any". - If "header" is "true", the first row of data will be read as - header and the tuple "(data_cells, header_cells)" is returned - instead of only "data_cells". +If "header" is "true", the first row of data will be read as +header and the tuple "(data_cells, header_cells)" is returned +instead of only "data_cells". - Specifying "skipstart" will ignore the corresponding number of - initial lines from the input. +Specifying "skipstart" will ignore the corresponding number of +initial lines from the input. - If "skipblanks" is "true", blank lines in the input will be - ignored. +If "skipblanks" is "true", blank lines in the input will be +ignored. - If "use_mmap" is "true", the file specified by "source" is - memory mapped for potential speedups. Default is "true" except on - Windows. On Windows, you may want to specify "true" if the file - is large, and is only read once and not written to. +If "use_mmap" is "true", the file specified by "source" is +memory mapped for potential speedups. Default is "true" except on +Windows. On Windows, you may want to specify "true" if the file +is large, and is only read once and not written to. - If "ignore_invalid_chars" is "true", bytes in "source" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. +If "ignore_invalid_chars" is "true", bytes in "source" with +invalid character encoding will be ignored. Otherwise an error is +thrown indicating the offending character position. - If "quotes" is "true", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. +If "quotes" is "true", column enclosed within double-quote (``) +characters are allowed to contain new lines and column delimiters. +Double-quote characters within a quoted field must be escaped with +another double-quote. - Specifying "dims" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. +Specifying "dims" as a tuple of the expected rows and columns +(including header, if any) may speed up reading of large files. - If "comments" is "true", lines beginning with "comment_char" - and text following "comment_char" in any line are ignored. -``` +If "comments" is "true", lines beginning with "comment_char" +and text following "comment_char" in any line are ignored. """ readdlm doc""" -```rst -readdlm(source, delim::Char, eol::Char; options...) + readdlm(source, delim::Char, eol::Char; options...) - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. -``` +If all data is numeric, the result will be a numeric array. If some +elements cannot be parsed as numbers, a cell array of numbers and +strings is returned. """ readdlm doc""" -```rst -readdlm(source, delim::Char, T::Type; options...) + readdlm(source, delim::Char, T::Type; options...) - The end of line delimiter is taken as "\n". -``` +The end of line delimiter is taken as "\n". """ readdlm doc""" -```rst -readdlm(source, delim::Char; options...) + readdlm(source, delim::Char; options...) - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. -``` +The end of line delimiter is taken as "\n". If all data is +numeric, the result will be a numeric array. If some elements +cannot be parsed as numbers, a cell array of numbers and strings is +returned. """ readdlm doc""" -```rst -readdlm(source, T::Type; options...) + readdlm(source, T::Type; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". -``` +The columns are assumed to be separated by one or more whitespaces. +The end of line delimiter is taken as "\n". """ readdlm doc""" -```rst -readdlm(source; options...) + readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. -``` +The columns are assumed to be separated by one or more whitespaces. +The end of line delimiter is taken as "\n". If all data is +numeric, the result will be a numeric array. If some elements +cannot be parsed as numbers, a cell array of numbers and strings is +returned. """ readdlm doc""" -```rst -writedlm(f, A, delim='\t') + writedlm(f, A, delim='\t') - Write "A" (a vector, matrix or an iterable collection of iterable - rows) as text to "f" (either a filename string or an "IO" - stream) using the given delimeter "delim" (which defaults to tab, - but can be any printable Julia object, typically a "Char" or - "AbstractString"). +Write "A" (a vector, matrix or an iterable collection of iterable +rows) as text to "f" (either a filename string or an "IO" +stream) using the given delimeter "delim" (which defaults to tab, +but can be any printable Julia object, typically a "Char" or +"AbstractString"). - For example, two vectors "x" and "y" of the same length can be - written as two columns of tab-delimited text to "f" by either - "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". -``` +For example, two vectors "x" and "y" of the same length can be +written as two columns of tab-delimited text to "f" by either +"writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". """ writedlm doc""" -```rst -readcsv(source, [T::Type]; options...) + readcsv(source, [T::Type]; options...) - Equivalent to "readdlm" with "delim" set to comma. -``` +Equivalent to "readdlm" with "delim" set to comma. """ readcsv doc""" -```rst -writecsv(filename, A) + writecsv(filename, A) - Equivalent to "writedlm" with "delim" set to comma. -``` +Equivalent to "writedlm" with "delim" set to comma. """ writecsv doc""" -```rst -Base64EncodePipe(ostream) + Base64EncodePipe(ostream) - Returns a new write-only I/O stream, which converts any bytes - written to it into base64-encoded ASCII bytes written to - "ostream". Calling "close" on the "Base64Pipe" stream is - necessary to complete the encoding (but does not close - "ostream"). -``` +Returns a new write-only I/O stream, which converts any bytes +written to it into base64-encoded ASCII bytes written to +"ostream". Calling "close" on the "Base64Pipe" stream is +necessary to complete the encoding (but does not close +"ostream"). """ Base64EncodePipe doc""" -```rst -Base64DecodePipe(istream) + Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded - data read from "istream". -``` +Returns a new read-only I/O stream, which decodes base64-encoded +data read from "istream". """ Base64DecodePipe doc""" -```rst -base64encode(writefunc, args...) + base64encode(writefunc, args...) base64encode(args...) - Given a "write"-like function "writefunc", which takes an I/O - stream as its first argument, "base64(writefunc, args...)" calls - "writefunc" to write "args..." to a base64-encoded string, and - returns the string. "base64(args...)" is equivalent to - "base64(write, args...)": it converts its arguments into bytes - using the standard "write" functions and returns the - base64-encoded string. -``` +Given a "write"-like function "writefunc", which takes an I/O +stream as its first argument, "base64(writefunc, args...)" calls +"writefunc" to write "args..." to a base64-encoded string, and +returns the string. "base64(args...)" is equivalent to +"base64(write, args...)": it converts its arguments into bytes +using the standard "write" functions and returns the +base64-encoded string. """ base64encode doc""" -```rst -base64decode(string) + base64decode(string) - Decodes the base64-encoded "string" and returns a - "Vector{UInt8}" of the decoded bytes. -``` +Decodes the base64-encoded "string" and returns a +"Vector{UInt8}" of the decoded bytes. """ base64decode doc""" -```rst -display(x) + display(x) display(d::Display, x) display(mime, x) display(d::Display, mime, x) - Display "x" using the topmost applicable display in the display - stack, typically using the richest supported multimedia output for - "x", with plain-text "STDOUT" output as a fallback. The - "display(d, x)" variant attempts to display "x" on the given - display "d" only, throwing a "MethodError" if "d" cannot - display objects of this type. - - There are also two variants with a "mime" argument (a MIME type - string, such as ""image/png""), which attempt to display "x" - using the requested MIME type *only*, throwing a "MethodError" if - this type is not supported by either the display(s) or by "x". - With these variants, one can also supply the "raw" data in the - requested MIME type by passing "x::AbstractString" (for MIME - types with text-based storage, such as text/html or - application/postscript) or "x::Vector{UInt8}" (for binary MIME - types). -``` +Display "x" using the topmost applicable display in the display +stack, typically using the richest supported multimedia output for +"x", with plain-text "STDOUT" output as a fallback. The +"display(d, x)" variant attempts to display "x" on the given +display "d" only, throwing a "MethodError" if "d" cannot +display objects of this type. + +There are also two variants with a "mime" argument (a MIME type +string, such as ""image/png""), which attempt to display "x" +using the requested MIME type *only*, throwing a "MethodError" if +this type is not supported by either the display(s) or by "x". +With these variants, one can also supply the "raw" data in the +requested MIME type by passing "x::AbstractString" (for MIME +types with text-based storage, such as text/html or +application/postscript) or "x::Vector{UInt8}" (for binary MIME +types). """ display doc""" -```rst -redisplay(x) + redisplay(x) redisplay(d::Display, x) redisplay(mime, x) redisplay(d::Display, mime, x) - By default, the "redisplay" functions simply call "display". - However, some display backends may override "redisplay" to modify - an existing display of "x" (if any). Using "redisplay" is - also a hint to the backend that "x" may be redisplayed several - times, and the backend may choose to defer the display until (for - example) the next interactive prompt. -``` +By default, the "redisplay" functions simply call "display". +However, some display backends may override "redisplay" to modify +an existing display of "x" (if any). Using "redisplay" is +also a hint to the backend that "x" may be redisplayed several +times, and the backend may choose to defer the display until (for +example) the next interactive prompt. """ redisplay doc""" -```rst -displayable(mime) -> Bool + displayable(mime) -> Bool displayable(d::Display, mime) -> Bool - Returns a boolean value indicating whether the given "mime" type - (string) is displayable by any of the displays in the current - display stack, or specifically by the display "d" in the second - variant. -``` +Returns a boolean value indicating whether the given "mime" type +(string) is displayable by any of the displays in the current +display stack, or specifically by the display "d" in the second +variant. """ displayable doc""" -```rst -writemime(stream, mime, x) - - The "display" functions ultimately call "writemime" in order to - write an object "x" as a given "mime" type to a given I/O - "stream" (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - "T", it is only necessary to define a new "writemime" method - for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", - where "mime" is a MIME-type string and the function body calls - "write" (or similar) to write that representation of "x" to - "stream". (Note that the "MIME\""" notation only supports - literal strings; to construct "MIME" types in a more flexible - manner use "MIME{symbol("")}".) - - For example, if you define a "MyImage" type and know how to write - it to a PNG file, you could define a function "writemime(stream, - ::MIME"image/png", x::MyImage) = ...`" to allow your images to - be displayed on any PNG-capable "Display" (such as IJulia). As - usual, be sure to "import Base.writemime" in order to add new - methods to the built-in Julia function "writemime". - - Technically, the "MIME"mime"" macro defines a singleton type - for the given "mime" string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. -``` + writemime(stream, mime, x) + +The "display" functions ultimately call "writemime" in order to +write an object "x" as a given "mime" type to a given I/O +"stream" (usually a memory buffer), if possible. In order to +provide a rich multimedia representation of a user-defined type +"T", it is only necessary to define a new "writemime" method +for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", +where "mime" is a MIME-type string and the function body calls +"write" (or similar) to write that representation of "x" to +"stream". (Note that the "MIME\""" notation only supports +literal strings; to construct "MIME" types in a more flexible +manner use "MIME{symbol("")}".) + +For example, if you define a "MyImage" type and know how to write +it to a PNG file, you could define a function "writemime(stream, +::MIME"image/png", x::MyImage) = ...`" to allow your images to +be displayed on any PNG-capable "Display" (such as IJulia). As +usual, be sure to "import Base.writemime" in order to add new +methods to the built-in Julia function "writemime". + +Technically, the "MIME"mime"" macro defines a singleton type +for the given "mime" string, which allows us to exploit Julia's +dispatch mechanisms in determining how to display objects of any +given type. """ writemime doc""" -```rst -mimewritable(mime, x) + mimewritable(mime, x) - Returns a boolean value indicating whether or not the object "x" - can be written as the given "mime" type. (By default, this is - determined automatically by the existence of the corresponding - "writemime" function for "typeof(x)".) -``` +Returns a boolean value indicating whether or not the object "x" +can be written as the given "mime" type. (By default, this is +determined automatically by the existence of the corresponding +"writemime" function for "typeof(x)".) """ mimewritable doc""" -```rst -reprmime(mime, x) + reprmime(mime, x) - Returns an "AbstractString" or "Vector{UInt8}" containing the - representation of "x" in the requested "mime" type, as written - by "writemime" (throwing a "MethodError" if no appropriate - "writemime" is available). An "AbstractString" is returned for - MIME types with textual representations (such as ""text/html"" - or ""application/postscript""), whereas binary data is returned - as "Vector{UInt8}". (The function "istext(mime)" returns - whether or not Julia treats a given "mime" type as text.) +Returns an "AbstractString" or "Vector{UInt8}" containing the +representation of "x" in the requested "mime" type, as written +by "writemime" (throwing a "MethodError" if no appropriate +"writemime" is available). An "AbstractString" is returned for +MIME types with textual representations (such as ""text/html"" +or ""application/postscript""), whereas binary data is returned +as "Vector{UInt8}". (The function "istext(mime)" returns +whether or not Julia treats a given "mime" type as text.) - As a special case, if "x" is an "AbstractString" (for textual - MIME types) or a "Vector{UInt8}" (for binary MIME types), the - "reprmime" function assumes that "x" is already in the - requested "mime" format and simply returns "x". -``` +As a special case, if "x" is an "AbstractString" (for textual +MIME types) or a "Vector{UInt8}" (for binary MIME types), the +"reprmime" function assumes that "x" is already in the +requested "mime" format and simply returns "x". """ reprmime doc""" -```rst -stringmime(mime, x) + stringmime(mime, x) - Returns an "AbstractString" containing the representation of - "x" in the requested "mime" type. This is similar to - "reprmime" except that binary data is base64-encoded as an ASCII - string. -``` +Returns an "AbstractString" containing the representation of +"x" in the requested "mime" type. This is similar to +"reprmime" except that binary data is base64-encoded as an ASCII +string. """ stringmime doc""" -```rst -pushdisplay(d::Display) + pushdisplay(d::Display) - Pushes a new display "d" on top of the global display-backend - stack. Calling "display(x)" or "display(mime, x)" will display - "x" on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a "MethodError"). -``` +Pushes a new display "d" on top of the global display-backend +stack. Calling "display(x)" or "display(mime, x)" will display +"x" on the topmost compatible backend in the stack (i.e., the +topmost backend that does not throw a "MethodError"). """ pushdisplay doc""" -```rst -popdisplay() + popdisplay() popdisplay(d::Display) - Pop the topmost backend off of the display-backend stack, or the - topmost copy of "d" in the second variant. -``` +Pop the topmost backend off of the display-backend stack, or the +topmost copy of "d" in the second variant. """ popdisplay doc""" -```rst -TextDisplay(stream) + TextDisplay(stream) - Returns a "TextDisplay <: Display", which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same as - the way an object is printed in the Julia REPL.) -``` +Returns a "TextDisplay <: Display", which can display any object +as the text/plain MIME type (only), writing the text representation +to the given I/O stream. (The text representation is the same as +the way an object is printed in the Julia REPL.) """ TextDisplay doc""" -```rst -istext(m::MIME) + istext(m::MIME) - Determine whether a MIME type is text data. -``` +Determine whether a MIME type is text data. """ istext doc""" -```rst -mmap_array(type, dims, stream[, offset]) + mmap_array(type, dims, stream[, offset]) - Create an "Array" whose values are linked to a file, using - memory-mapping. This provides a convenient way of working with data - too large to fit in the computer's memory. +Create an "Array" whose values are linked to a file, using +memory-mapping. This provides a convenient way of working with data +too large to fit in the computer's memory. - The type determines how the bytes of the array are interpreted. - Note that the file must be stored in binary format, and no format - conversions are possible (this is a limitation of operating - systems, not Julia). +The type determines how the bytes of the array are interpreted. +Note that the file must be stored in binary format, and no format +conversions are possible (this is a limitation of operating +systems, not Julia). - "dims" is a tuple specifying the size of the array. +"dims" is a tuple specifying the size of the array. - The file is passed via the stream argument. When you initialize - the stream, use ""r"" for a "read-only" array, and ""w+"" - to create a new array used to write values to disk. +The file is passed via the stream argument. When you initialize +the stream, use ""r"" for a "read-only" array, and ""w+"" +to create a new array used to write values to disk. - Optionally, you can specify an offset (in bytes) if, for example, - you want to skip over a header in the file. The default value for - the offset is the current stream position. +Optionally, you can specify an offset (in bytes) if, for example, +you want to skip over a header in the file. The default value for +the offset is the current stream position. - For example, the following code: +For example, the following code: - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open("/tmp/mmap.bin", "w+") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) - # Test by reading it back in - s = open("/tmp/mmap.bin") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) - creates a "m"-by-"n" "Matrix{Int}", linked to the file - associated with stream "s". +creates a "m"-by-"n" "Matrix{Int}", linked to the file +associated with stream "s". - A more portable file would need to encode the word size---32 bit or - 64 bit---and endianness information in the header. In practice, - consider encoding binary data using standard formats like HDF5 - (which can be used with memory-mapping). -``` +A more portable file would need to encode the word size---32 bit or +64 bit---and endianness information in the header. In practice, +consider encoding binary data using standard formats like HDF5 +(which can be used with memory-mapping). """ mmap_array doc""" -```rst -mmap_bitarray([type], dims, stream[, offset]) + mmap_bitarray([type], dims, stream[, offset]) - Create a "BitArray" whose values are linked to a file, using - memory-mapping; it has the same purpose, works in the same way, and - has the same arguments, as "mmap_array()", but the byte - representation is different. The "type" parameter is optional, - and must be "Bool" if given. +Create a "BitArray" whose values are linked to a file, using +memory-mapping; it has the same purpose, works in the same way, and +has the same arguments, as "mmap_array()", but the byte +representation is different. The "type" parameter is optional, +and must be "Bool" if given. - **Example**: "B = mmap_bitarray((25,30000), s)" +**Example**: "B = mmap_bitarray((25,30000), s)" - This would create a 25-by-30000 "BitArray", linked to the file - associated with stream "s". -``` +This would create a 25-by-30000 "BitArray", linked to the file +associated with stream "s". """ mmap_bitarray doc""" -```rst -msync(array) + msync(array) - Forces synchronization between the in-memory version of a memory- - mapped "Array" or "BitArray" and the on-disk version. -``` +Forces synchronization between the in-memory version of a memory- +mapped "Array" or "BitArray" and the on-disk version. """ msync doc""" -```rst -connect([host], port) -> TcpSocket + connect([host], port) -> TcpSocket - Connect to the host "host" on port "port" -``` +Connect to the host "host" on port "port" """ connect doc""" -```rst -connect(path) -> Pipe + connect(path) -> Pipe - Connect to the Named Pipe/Domain Socket at "path" -``` +Connect to the Named Pipe/Domain Socket at "path" """ connect doc""" -```rst -listen([addr], port) -> TcpServer + listen([addr], port) -> TcpServer - Listen on port on the address specified by "addr". By default - this listens on localhost only. To listen on all interfaces pass, - "IPv4(0)" or "IPv6(0)" as appropriate. -``` +Listen on port on the address specified by "addr". By default +this listens on localhost only. To listen on all interfaces pass, +"IPv4(0)" or "IPv6(0)" as appropriate. """ listen doc""" -```rst -listen(path) -> PipeServer + listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket -``` +Listens on/Creates a Named Pipe/Domain Socket """ listen doc""" -```rst -getaddrinfo(host) + getaddrinfo(host) - Gets the IP address of the "host" (may have to do a DNS lookup) -``` +Gets the IP address of the "host" (may have to do a DNS lookup) """ getaddrinfo doc""" -```rst -parseip(addr) + parseip(addr) - Parse a string specifying an IPv4 or IPv6 ip address. -``` +Parse a string specifying an IPv4 or IPv6 ip address. """ parseip doc""" -```rst -IPv4(host::Integer) -> IPv4 + IPv4(host::Integer) -> IPv4 - Returns IPv4 object from ip address formatted as Integer -``` +Returns IPv4 object from ip address formatted as Integer """ IPv4 doc""" -```rst -IPv6(host::Integer) -> IPv6 + IPv6(host::Integer) -> IPv6 - Returns IPv6 object from ip address formatted as Integer -``` +Returns IPv6 object from ip address formatted as Integer """ IPv6 doc""" -```rst -nb_available(stream) + nb_available(stream) - Returns the number of bytes available for reading before a read - from this stream or buffer will block. -``` +Returns the number of bytes available for reading before a read +from this stream or buffer will block. """ nb_available doc""" -```rst -accept(server[, client]) + accept(server[, client]) - Accepts a connection on the given server and returns a connection - to the client. An uninitialized client stream may be provided, in - which case it will be used instead of creating a new stream. -``` +Accepts a connection on the given server and returns a connection +to the client. An uninitialized client stream may be provided, in +which case it will be used instead of creating a new stream. """ accept doc""" -```rst -listenany(port_hint) -> (UInt16, TcpServer) + listenany(port_hint) -> (UInt16, TcpServer) - Create a TcpServer on any port, using hint as a starting point. - Returns a tuple of the actual port that the server was created on - and the server itself. -``` +Create a TcpServer on any port, using hint as a starting point. +Returns a tuple of the actual port that the server was created on +and the server itself. """ listenany doc""" -```rst -watch_file(cb=false, s; poll=false) + watch_file(cb=false, s; poll=false) - Watch file or directory "s" and run callback "cb" when "s" is - modified. The "poll" parameter specifies whether to use file - system event monitoring or polling. The callback function "cb" - should accept 3 arguments: "(filename, events, status)" where - "filename" is the name of file that was modified, "events" is - an object with boolean fields "changed" and "renamed" when - using file system event monitoring, or "readable" and - "writable" when using polling, and "status" is always 0. Pass - "false" for "cb" to not use a callback function. -``` +Watch file or directory "s" and run callback "cb" when "s" is +modified. The "poll" parameter specifies whether to use file +system event monitoring or polling. The callback function "cb" +should accept 3 arguments: "(filename, events, status)" where +"filename" is the name of file that was modified, "events" is +an object with boolean fields "changed" and "renamed" when +using file system event monitoring, or "readable" and +"writable" when using polling, and "status" is always 0. Pass +"false" for "cb" to not use a callback function. """ watch_file doc""" -```rst -poll_fd(fd, seconds::Real; readable=false, writable=false) + poll_fd(fd, seconds::Real; readable=false, writable=false) - Poll a file descriptor fd for changes in the read or write - availability and with a timeout given by the second argument. If - the timeout is not needed, use "wait(fd)" instead. The keyword - arguments determine which of read and/or write status should be - monitored and at least one of them needs to be set to true. The - returned value is an object with boolean fields "readable", - "writable", and "timedout", giving the result of the polling. -``` +Poll a file descriptor fd for changes in the read or write +availability and with a timeout given by the second argument. If +the timeout is not needed, use "wait(fd)" instead. The keyword +arguments determine which of read and/or write status should be +monitored and at least one of them needs to be set to true. The +returned value is an object with boolean fields "readable", +"writable", and "timedout", giving the result of the polling. """ poll_fd doc""" -```rst -poll_file(s, interval_seconds::Real, seconds::Real) + poll_file(s, interval_seconds::Real, seconds::Real) - Monitor a file for changes by polling every *interval_seconds* - seconds for *seconds* seconds. A return value of true indicates the - file changed, a return value of false indicates a timeout. -``` +Monitor a file for changes by polling every *interval_seconds* +seconds for *seconds* seconds. A return value of true indicates the +file changed, a return value of false indicates a timeout. """ poll_file doc""" -```rst -bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - Bind "socket" to the given "host:port". Note that *0.0.0.0* - will listen on all devices. -``` +Bind "socket" to the given "host:port". Note that *0.0.0.0* +will listen on all devices. """ bind doc""" -```rst -send(socket::UDPSocket, host::IPv4, port::Integer, msg) + send(socket::UDPSocket, host::IPv4, port::Integer, msg) - Send "msg" over "socket to ``host:port". -``` +Send "msg" over "socket to ``host:port". """ send doc""" -```rst -recv(socket::UDPSocket) + recv(socket::UDPSocket) - Read a UDP packet from the specified socket, and return the bytes - received. This call blocks. -``` +Read a UDP packet from the specified socket, and return the bytes +received. This call blocks. """ recv doc""" -```rst -recvfrom(socket::UDPSocket) -> (address, data) + recvfrom(socket::UDPSocket) -> (address, data) - Read a UDP packet from the specified socket, returning a tuple of - (address, data), where address will be either IPv4 or IPv6 as - appropriate. -``` +Read a UDP packet from the specified socket, returning a tuple of +(address, data), where address will be either IPv4 or IPv6 as +appropriate. """ recvfrom doc""" -```rst -setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - Set UDP socket options. "multicast_loop": loopback for multicast - packets (default: true). "multicast_ttl": TTL for multicast - packets. "enable_broadcast": flag must be set to true if socket - will be used for broadcast messages, or else the UDP system will - return an access error (default: false). "ttl": Time-to-live of - packets sent on the socket. -``` +Set UDP socket options. "multicast_loop": loopback for multicast +packets (default: true). "multicast_ttl": TTL for multicast +packets. "enable_broadcast": flag must be set to true if socket +will be used for broadcast messages, or else the UDP system will +return an access error (default: false). "ttl": Time-to-live of +packets sent on the socket. """ setopt doc""" -```rst -ntoh(x) + ntoh(x) - Converts the endianness of a value from Network byte order (big- - endian) to that used by the Host. -``` +Converts the endianness of a value from Network byte order (big- +endian) to that used by the Host. """ ntoh doc""" -```rst -hton(x) + hton(x) - Converts the endianness of a value from that used by the Host to - Network byte order (big-endian). -``` +Converts the endianness of a value from that used by the Host to +Network byte order (big-endian). """ hton doc""" -```rst -ltoh(x) + ltoh(x) - Converts the endianness of a value from Little-endian to that used - by the Host. -``` +Converts the endianness of a value from Little-endian to that used +by the Host. """ ltoh doc""" -```rst -htol(x) + htol(x) - Converts the endianness of a value from that used by the Host to - Little-endian. -``` +Converts the endianness of a value from that used by the Host to +Little-endian. """ htol doc""" -```rst -ENDIAN_BOM + ENDIAN_BOM - The 32-bit byte-order-mark indicates the native byte order of the - host machine. Little-endian machines will contain the value - 0x04030201. Big-endian machines will contain the value 0x01020304. -``` +The 32-bit byte-order-mark indicates the native byte order of the +host machine. Little-endian machines will contain the value +0x04030201. Big-endian machines will contain the value 0x01020304. """ ENDIAN_BOM doc""" -```rst -malloc(size::Integer) -> Ptr{Void} + malloc(size::Integer) -> Ptr{Void} - Call "malloc" from the C standard library. -``` +Call "malloc" from the C standard library. """ Libc.malloc doc""" -```rst -calloc(num::Integer, size::Integer) -> Ptr{Void} + calloc(num::Integer, size::Integer) -> Ptr{Void} - Call "calloc" from the C standard library. -``` +Call "calloc" from the C standard library. """ Libc.calloc doc""" -```rst -realloc(addr::Ptr, size::Integer) -> Ptr{Void} + realloc(addr::Ptr, size::Integer) -> Ptr{Void} - Call "realloc" from the C standard library. +Call "realloc" from the C standard library. - See warning in the documentation for "free" regarding only using - this on memory originally obtained from "malloc". -``` +See warning in the documentation for "free" regarding only using +this on memory originally obtained from "malloc". """ Libc.realloc doc""" -```rst -free(addr::Ptr) + free(addr::Ptr) - Call "free" from the C standard library. Only use this on memory - obtained from "malloc", not on pointers retrieved from other C - libraries. "Ptr" objects obtained from C libraries should be - freed by the free functions defined in that library, to avoid - assertion failures if multiple "libc" libraries exist on the - system. -``` +Call "free" from the C standard library. Only use this on memory +obtained from "malloc", not on pointers retrieved from other C +libraries. "Ptr" objects obtained from C libraries should be +freed by the free functions defined in that library, to avoid +assertion failures if multiple "libc" libraries exist on the +system. """ Libc.free doc""" -```rst -errno([code]) + errno([code]) - Get the value of the C library's "errno". If an argument is - specified, it is used to set the value of "errno". +Get the value of the C library's "errno". If an argument is +specified, it is used to set the value of "errno". - The value of "errno" is only valid immediately after a "ccall" - to a C library routine that sets it. Specifically, you cannot call - "errno" at the next prompt in a REPL, because lots of code is - executed between prompts. -``` +The value of "errno" is only valid immediately after a "ccall" +to a C library routine that sets it. Specifically, you cannot call +"errno" at the next prompt in a REPL, because lots of code is +executed between prompts. """ Libc.errno doc""" -```rst -strerror(n) + strerror(n) - Convert a system call error code to a descriptive string -``` +Convert a system call error code to a descriptive string """ Libc.strerror doc""" -```rst -time(t::TmStruct) + time(t::TmStruct) - Converts a "TmStruct" struct to a number of seconds since the - epoch. -``` +Converts a "TmStruct" struct to a number of seconds since the +epoch. """ Libc.time doc""" -```rst -strftime([format], time) + strftime([format], time) - Convert time, given as a number of seconds since the epoch or a - "TmStruct", to a formatted string using the given format. - Supported formats are the same as those in the standard C library. -``` +Convert time, given as a number of seconds since the epoch or a +"TmStruct", to a formatted string using the given format. +Supported formats are the same as those in the standard C library. """ Libc.strftime doc""" -```rst -strptime([format], timestr) + strptime([format], timestr) - Parse a formatted time string into a "TmStruct" giving the - seconds, minute, hour, date, etc. Supported formats are the same as - those in the standard C library. On some platforms, timezones will - not be parsed correctly. If the result of this function will be - passed to "time" to convert it to seconds since the epoch, the - "isdst" field should be filled in manually. Setting it to "-1" - will tell the C library to use the current system settings to - determine the timezone. -``` +Parse a formatted time string into a "TmStruct" giving the +seconds, minute, hour, date, etc. Supported formats are the same as +those in the standard C library. On some platforms, timezones will +not be parsed correctly. If the result of this function will be +passed to "time" to convert it to seconds since the epoch, the +"isdst" field should be filled in manually. Setting it to "-1" +will tell the C library to use the current system settings to +determine the timezone. """ Libc.strptime doc""" -```rst -TmStruct([seconds]) + TmStruct([seconds]) - Convert a number of seconds since the epoch to broken-down format, - with fields "sec", "min", "hour", "mday", "month", - "year", "wday", "yday", and "isdst". -``` +Convert a number of seconds since the epoch to broken-down format, +with fields "sec", "min", "hour", "mday", "month", +"year", "wday", "yday", and "isdst". """ Libc.TmStruct doc""" -```rst -flush_cstdio() + flush_cstdio() - Flushes the C "stdout" and "stderr" streams (which may have - been written to by external C code). -``` +Flushes the C "stdout" and "stderr" streams (which may have +been written to by external C code). """ Libc.flush_cstdio doc""" -```rst -msync(ptr, len[, flags]) + msync(ptr, len[, flags]) - Forces synchronization of the "mmap()"ped memory region from - "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a - combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See - your platform man page for specifics. The flags argument is not - valid on Windows. +Forces synchronization of the "mmap()"ped memory region from +"ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a +combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See +your platform man page for specifics. The flags argument is not +valid on Windows. - You may not need to call "msync", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. -``` +You may not need to call "msync", because synchronization is +performed at intervals automatically by the operating system. +However, you can call this directly if, for example, you are +concerned about losing the result of a long-running calculation. """ Libc.msync doc""" -```rst -MS_ASYNC + MS_ASYNC - Enum constant for "msync()". See your platform man page for - details. (not available on Windows). -``` +Enum constant for "msync()". See your platform man page for +details. (not available on Windows). """ Libc.MS_ASYNC doc""" -```rst -MS_SYNC + MS_SYNC - Enum constant for "msync()". See your platform man page for - details. (not available on Windows). -``` +Enum constant for "msync()". See your platform man page for +details. (not available on Windows). """ Libc.MS_SYNC doc""" -```rst -MS_INVALIDATE + MS_INVALIDATE - Enum constant for "msync()". See your platform man page for - details. (not available on Windows). -``` +Enum constant for "msync()". See your platform man page for +details. (not available on Windows). """ Libc.MS_INVALIDATE doc""" -```rst -mmap(len, prot, flags, fd, offset) + mmap(len, prot, flags, fd, offset) - Low-level interface to the "mmap" system call. See the man page. -``` +Low-level interface to the "mmap" system call. See the man page. """ Libc.mmap doc""" -```rst -munmap(pointer, len) + munmap(pointer, len) - Low-level interface for unmapping memory (see the man page). With - "mmap_array()" you do not need to call this directly; the memory - is unmapped for you when the array goes out of scope. -``` +Low-level interface for unmapping memory (see the man page). With +"mmap_array()" you do not need to call this directly; the memory +is unmapped for you when the array goes out of scope. """ Libc.munmap doc""" -```rst -dlopen(libfile::AbstractString[, flags::Integer]) + dlopen(libfile::AbstractString[, flags::Integer]) - Load a shared library, returning an opaque handle. +Load a shared library, returning an opaque handle. - The optional flags argument is a bitwise-or of zero or more of - "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", - "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and - "RTLD_FIRST". These are converted to the corresponding flags of - the POSIX (and/or GNU libc and/or MacOS) dlopen command, if - possible, or are ignored if the specified functionality is not - available on the current platform. The default is - "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of - these flags, on POSIX platforms, is to specify - "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's - symbols to be available for usage in other shared libraries, in - situations where there are dependencies between shared libraries. -``` +The optional flags argument is a bitwise-or of zero or more of +"RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", +"RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and +"RTLD_FIRST". These are converted to the corresponding flags of +the POSIX (and/or GNU libc and/or MacOS) dlopen command, if +possible, or are ignored if the specified functionality is not +available on the current platform. The default is +"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of +these flags, on POSIX platforms, is to specify +"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's +symbols to be available for usage in other shared libraries, in +situations where there are dependencies between shared libraries. """ Libdl.dlopen doc""" -```rst -dlopen_e(libfile::AbstractString[, flags::Integer]) + dlopen_e(libfile::AbstractString[, flags::Integer]) - Similar to "dlopen()", except returns a "NULL" pointer instead - of raising errors. -``` +Similar to "dlopen()", except returns a "NULL" pointer instead +of raising errors. """ Libdl.dlopen_e doc""" -```rst -RTLD_DEEPBIND + RTLD_DEEPBIND - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_DEEPBIND doc""" -```rst -RTLD_FIRST + RTLD_FIRST - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_FIRST doc""" -```rst -RTLD_GLOBAL + RTLD_GLOBAL - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_GLOBAL doc""" -```rst -RTLD_LAZY + RTLD_LAZY - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_LAZY doc""" -```rst -RTLD_LOCAL + RTLD_LOCAL - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_LOCAL doc""" -```rst -RTLD_NODELETE + RTLD_NODELETE - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_NODELETE doc""" -```rst -RTLD_NOLOAD + RTLD_NOLOAD - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_NOLOAD doc""" -```rst -RTLD_NOW + RTLD_NOW - Enum constant for "dlopen()". See your platform man page for - details, if applicable. -``` +Enum constant for "dlopen()". See your platform man page for +details, if applicable. """ Libdl.RTLD_NOW doc""" -```rst -dlsym(handle, sym) + dlsym(handle, sym) - Look up a symbol from a shared library handle, return callable - function pointer on success. -``` +Look up a symbol from a shared library handle, return callable +function pointer on success. """ Libdl.dlsym doc""" -```rst -dlsym_e(handle, sym) + dlsym_e(handle, sym) - Look up a symbol from a shared library handle, silently return NULL - pointer on lookup failure. -``` +Look up a symbol from a shared library handle, silently return NULL +pointer on lookup failure. """ Libdl.dlsym_e doc""" -```rst -dlclose(handle) + dlclose(handle) - Close shared library referenced by handle. -``` +Close shared library referenced by handle. """ Libdl.dlclose doc""" -```rst -find_library(names, locations) + find_library(names, locations) - Searches for the first library in "names" in the paths in the - "locations" list, "DL_LOAD_PATH", or system library paths (in - that order) which can successfully be dlopen'd. On success, the - return value will be one of the names (potentially prefixed by one - of the paths in locations). This string can be assigned to a - "global const" and used as the library name in future - "ccall"'s. On failure, it returns the empty string. -``` +Searches for the first library in "names" in the paths in the +"locations" list, "DL_LOAD_PATH", or system library paths (in +that order) which can successfully be dlopen'd. On success, the +return value will be one of the names (potentially prefixed by one +of the paths in locations). This string can be assigned to a +"global const" and used as the library name in future +"ccall"'s. On failure, it returns the empty string. """ Libdl.find_library doc""" -```rst -DL_LOAD_PATH + DL_LOAD_PATH - When calling "dlopen", the paths in this list will be searched - first, in order, before searching the system locations for a valid - library handle. -``` +When calling "dlopen", the paths in this list will be searched +first, in order, before searching the system locations for a valid +library handle. """ Libdl.DL_LOAD_PATH doc""" -```rst -*(A, B) + *(A, B) - Matrix multiplication -``` +Matrix multiplication """ Base.(:(*)) doc""" -```rst -\(A, B) + \(A, B) - Matrix division using a polyalgorithm. For input matrices "A" and - "B", the result "X" is such that "A*X == B" when "A" is - square. The solver that is used depends upon the structure of - "A". A direct solver is used for upper- or lower triangular - "A". For Hermitian "A" (equivalent to symmetric "A" for non- - complex "A") the "BunchKaufman" factorization is used. - Otherwise an LU factorization is used. For rectangular "A" the - result is the minimum-norm least squares solution computed by a - pivoted QR factorization of "A" and a rank estimate of A based on - the R factor. +Matrix division using a polyalgorithm. For input matrices "A" and +"B", the result "X" is such that "A*X == B" when "A" is +square. The solver that is used depends upon the structure of +"A". A direct solver is used for upper- or lower triangular +"A". For Hermitian "A" (equivalent to symmetric "A" for non- +complex "A") the "BunchKaufman" factorization is used. +Otherwise an LU factorization is used. For rectangular "A" the +result is the minimum-norm least squares solution computed by a +pivoted QR factorization of "A" and a rank estimate of A based on +the R factor. - When "A" is sparse, a similar polyalgorithm is used. For - indefinite matrices, the LDLt factorization does not use pivoting - during the numerical factorization and therefore the procedure can - fail even for invertible matrices. -``` +When "A" is sparse, a similar polyalgorithm is used. For +indefinite matrices, the LDLt factorization does not use pivoting +during the numerical factorization and therefore the procedure can +fail even for invertible matrices. """ Base.(:(\)) doc""" -```rst -dot(x, y) + dot(x, y) ⋅(x, y) - Compute the dot product. For complex vectors, the first vector is - conjugated. -``` +Compute the dot product. For complex vectors, the first vector is +conjugated. """ dot doc""" -```rst -vecdot(x, y) + vecdot(x, y) - For any iterable containers "x" and "y" (including arrays of - any dimension) of numbers (or any element type for which "dot" is - defined), compute the Euclidean dot product (the sum of - "dot(x[i],y[i])") as if they were vectors. -``` +For any iterable containers "x" and "y" (including arrays of +any dimension) of numbers (or any element type for which "dot" is +defined), compute the Euclidean dot product (the sum of +"dot(x[i],y[i])") as if they were vectors. """ vecdot doc""" -```rst -cross(x, y) + cross(x, y) ×(x, y) - Compute the cross product of two 3-vectors. -``` +Compute the cross product of two 3-vectors. """ cross doc""" -```rst -factorize(A) + factorize(A) - Compute a convenient factorization (including LU, Cholesky, Bunch- - Kaufman, LowerTriangular, UpperTriangular) of A, based upon the - type of the input matrix. The return value can then be reused for - efficient solving of multiple systems. For example: - "A=factorize(A); x=A\\b; y=A\\C". -``` +Compute a convenient factorization (including LU, Cholesky, Bunch- +Kaufman, LowerTriangular, UpperTriangular) of A, based upon the +type of the input matrix. The return value can then be reused for +efficient solving of multiple systems. For example: +"A=factorize(A); x=A\\b; y=A\\C". """ factorize doc""" -```rst -full(F) + full(F) - Reconstruct the matrix "A" from the factorization - "F=factorize(A)". -``` +Reconstruct the matrix "A" from the factorization +"F=factorize(A)". """ full doc""" -```rst -lu(A) -> L, U, p + lu(A) -> L, U, p - Compute the LU factorization of "A", such that "A[p,:] = L*U". -``` +Compute the LU factorization of "A", such that "A[p,:] = L*U". """ lu doc""" -```rst -lufact(A[, pivot=Val{true}]) -> F - - Compute the LU factorization of "A". The return type of "F" - depends on the type of "A". In most cases, if "A" is a subtype - "S" of AbstractMatrix with an element type "T`" supporting - "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If - pivoting is chosen (default) the element type should also support - "abs" and "<". When "A" is sparse and have element of type - "Float32", "Float64", "Complex{Float32}", or - "Complex{Float64}" the return type is "UmfpackLU". Some - examples are shown in the table below. - - +-------------------------+---------------------------+----------------------------------------------+ - | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | - +-------------------------+---------------------------+----------------------------------------------+ - | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | - +-------------------------+---------------------------+----------------------------------------------+ - - The individual components of the factorization "F" can be - accessed by indexing: - - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - - +--------------------+--------+--------------------------+---------------+ - | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +--------------------+--------+--------------------------+---------------+ - | \"/\" | ✓ | | | - +--------------------+--------+--------------------------+---------------+ - | \"\\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"cond\" | ✓ | | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"det\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"logdet\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | \"logabsdet\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | \"size\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ -``` + lufact(A[, pivot=Val{true}]) -> F + +Compute the LU factorization of "A". The return type of "F" +depends on the type of "A". In most cases, if "A" is a subtype +"S" of AbstractMatrix with an element type "T`" supporting +"+", "-", "*" and "/" the return type is "LU{T,S{T}}". If +pivoting is chosen (default) the element type should also support +"abs" and "<". When "A" is sparse and have element of type +"Float32", "Float64", "Complex{Float32}", or +"Complex{Float64}" the return type is "UmfpackLU". Some +examples are shown in the table below. + + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | + +-------------------------+---------------------------+----------------------------------------------+ + +The individual components of the factorization "F" can be +accessed by indexing: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +--------------------+--------+--------------------------+---------------+ + | \"/\" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | \"\\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"cond\" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"det\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"logdet\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \"logabsdet\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \"size\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ """ lufact doc""" -```rst -lufact!(A) -> LU + lufact!(A) -> LU - "lufact!" is the same as "lufact()", but saves space by - overwriting the input A, instead of creating a copy. For sparse - "A" the "nzval" field is not overwritten but the index fields, - "colptr" and "rowval" are decremented in place, converting from - 1-based indices to 0-based indices. -``` +"lufact!" is the same as "lufact()", but saves space by +overwriting the input A, instead of creating a copy. For sparse +"A" the "nzval" field is not overwritten but the index fields, +"colptr" and "rowval" are decremented in place, converting from +1-based indices to 0-based indices. """ lufact! doc""" -```rst -chol(A[, LU]) -> F + chol(A[, LU]) -> F - Compute the Cholesky factorization of a symmetric positive definite - matrix "A" and return the matrix "F". If "LU" is "Val{:U}" - (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If - "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" - and "A = F*F'". "LU" defaults to "Val{:U}". -``` +Compute the Cholesky factorization of a symmetric positive definite +matrix "A" and return the matrix "F". If "LU" is "Val{:U}" +(Upper), "F" is of type "UpperTriangular" and "A = F'*F". If +"LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" +and "A = F*F'". "LU" defaults to "Val{:U}". """ chol doc""" -```rst -cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - - Compute the Cholesky factorization of a dense symmetric positive - (semi)definite matrix "A" and return either a "Cholesky" if - "pivot==Val{false}" or "CholeskyPivoted" if - "pivot==Val{true}". "LU" may be ":L" for using the lower part - or ":U" for the upper part. The default is to use ":U". The - triangular matrix can be obtained from the factorization "F" - with: "F[:L]" and "F[:U]". The following functions are - available for "Cholesky" objects: "size", "\", "inv", - "det". For "CholeskyPivoted" there is also defined a "rank". - If "pivot==Val{false}" a "PosDefException" exception is thrown - in case the matrix is not positive definite. The argument "tol" - determines the tolerance for determining the rank. For negative - values, the tolerance is the machine precision. -``` + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + +Compute the Cholesky factorization of a dense symmetric positive +(semi)definite matrix "A" and return either a "Cholesky" if +"pivot==Val{false}" or "CholeskyPivoted" if +"pivot==Val{true}". "LU" may be ":L" for using the lower part +or ":U" for the upper part. The default is to use ":U". The +triangular matrix can be obtained from the factorization "F" +with: "F[:L]" and "F[:U]". The following functions are +available for "Cholesky" objects: "size", "\", "inv", +"det". For "CholeskyPivoted" there is also defined a "rank". +If "pivot==Val{false}" a "PosDefException" exception is thrown +in case the matrix is not positive definite. The argument "tol" +determines the tolerance for determining the rank. For negative +values, the tolerance is the machine precision. """ cholfact doc""" -```rst -cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the Cholesky factorization of a sparse positive definite - matrix "A". A fill-reducing permutation is used. "F = - cholfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors - from "F", using "F[:L]". However, since pivoting is on by - default, the factorization is internally represented as "A == - P'*L*L'*P" with a permutation matrix "P"; using just "L" - without accounting for "P" will give incorrect answers. To - include the effects of permutation, it's typically preferable to - extact "combined" factors like "PtL = F[:PtL]" (the equivalent - of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. -``` + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + +Compute the Cholesky factorization of a sparse positive definite +matrix "A". A fill-reducing permutation is used. "F = +cholfact(A)" is most frequently used to solve systems of equations +with "F\b", but also the methods "diag", "det", "logdet" +are defined for "F". You can also extract individual factors +from "F", using "F[:L]". However, since pivoting is on by +default, the factorization is internally represented as "A == +P'*L*L'*P" with a permutation matrix "P"; using just "L" +without accounting for "P" will give incorrect answers. To +include the effects of permutation, it's typically preferable to +extact "combined" factors like "PtL = F[:PtL]" (the equivalent +of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + +Setting optional "shift" keyword argument computes the +factorization of "A+shift*I" instead of "A". If the "perm" +argument is nonempty, it should be a permutation of *1:size(A,1)* +giving the ordering to use (instead of CHOLMOD's default AMD +ordering). + +The function calls the C library CHOLMOD and many other functions +from the library are wrapped but not exported. """ cholfact doc""" -```rst -cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - "cholfact!" is the same as "cholfact()", but saves space by - overwriting the input "A", instead of creating a copy. - "cholfact!" can also reuse the symbolic factorization from a - different matrix "F" with the same structure when used as: - "cholfact!(F::CholmodFactor, A)". -``` +"cholfact!" is the same as "cholfact()", but saves space by +overwriting the input "A", instead of creating a copy. +"cholfact!" can also reuse the symbolic factorization from a +different matrix "F" with the same structure when used as: +"cholfact!(F::CholmodFactor, A)". """ cholfact! doc""" -```rst -ldltfact(A) -> LDLtFactorization + ldltfact(A) -> LDLtFactorization - Compute a factorization of a positive definite matrix "A" such - that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular - matrix and "d" is a vector with non-negative elements. -``` +Compute a factorization of a positive definite matrix "A" such +that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular +matrix and "d" is a vector with non-negative elements. """ ldltfact doc""" -```rst -ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix "A". A fill-reducing permutation is used. "F = - ldltfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors from - "F", using "F[:L]". However, since pivoting is on by default, - the factorization is internally represented as "A == P'*L*D*L'*P" - with a permutation matrix "P"; using just "L" without - accounting for "P" will give incorrect answers. To include the - effects of permutation, it's typically preferable to extact - "combined" factors like "PtL = F[:PtL]" (the equivalent of - "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The - complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, - :DU, :PtLD, :DUP". - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. -``` + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + +Compute the LDLt factorization of a sparse symmetric or Hermitian +matrix "A". A fill-reducing permutation is used. "F = +ldltfact(A)" is most frequently used to solve systems of equations +with "F\b", but also the methods "diag", "det", "logdet" +are defined for "F". You can also extract individual factors from +"F", using "F[:L]". However, since pivoting is on by default, +the factorization is internally represented as "A == P'*L*D*L'*P" +with a permutation matrix "P"; using just "L" without +accounting for "P" will give incorrect answers. To include the +effects of permutation, it's typically preferable to extact +"combined" factors like "PtL = F[:PtL]" (the equivalent of +"P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The +complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, +:DU, :PtLD, :DUP". + +Setting optional "shift" keyword argument computes the +factorization of "A+shift*I" instead of "A". If the "perm" +argument is nonempty, it should be a permutation of *1:size(A,1)* +giving the ordering to use (instead of CHOLMOD's default AMD +ordering). + +The function calls the C library CHOLMOD and many other functions +from the library are wrapped but not exported. """ ldltfact doc""" -```rst -qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - Compute the (pivoted) QR factorization of "A" such that either - "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default - is to compute a thin factorization. Note that "R" is not extended - with zeros when the full "Q" is requested. -``` +Compute the (pivoted) QR factorization of "A" such that either +"A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default +is to compute a thin factorization. Note that "R" is not extended +with zeros when the full "Q" is requested. """ qr doc""" -```rst -qrfact(A[, pivot=Val{false}]) -> F - - Computes the QR factorization of "A". The return type of "F" - depends on the element type of "A" and whether pivoting is - specified (with "pivot==Val{true}"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - - "BlasFloat" refers to any of: "Float32", "Float64", - "Complex64" or "Complex128". - - The individual components of the factorization "F" can be - accessed by indexing: - - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:p]\" | pivot \"Vector\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - - The following functions are available for the "QR" objects: - "size", "\". When "A" is rectangular, "\" will return a - least squares solution and if the solution is not unique, the one - with smallest norm is returned. - - Multiplication with respect to either thin or full "Q" is - allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A - "Q" matrix can be converted into a regular matrix with "full()" - which has a named argument "thin". - - Note: "qrfact" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the "Q" and "R" matrices can be stored compactly rather - as two separate dense matrices.The data contained in "QR" or - "QRPivoted" can be used to construct the "QRPackedQ" type, - which is a compact representation of the rotation matrix: - - Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) - - where \tau_i is the scale factor and v_i is the projection - vector associated with the i^{th} Householder elementary - reflector.The data contained in "QRCompactWY" can be used to - construct the "QRCompactWYQ" type, which is a compact - representation of the rotation matrix - - Q = I + Y T Y^T - - where "Y" is m \times r lower trapezoidal and "T" is r - \times r upper triangular. The *compact WY* representation - [Schreiber1989] is not to be confused with the older, *WY* - representation [Bischof1987]. (The LAPACK documentation uses - "V" in lieu of "Y".) - - [Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 - - [Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 -``` + qrfact(A[, pivot=Val{false}]) -> F + +Computes the QR factorization of "A". The return type of "F" +depends on the element type of "A" and whether pivoting is +specified (with "pivot==Val{true}"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + +"BlasFloat" refers to any of: "Float32", "Float64", +"Complex64" or "Complex128". + +The individual components of the factorization "F" can be +accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:p]\" | pivot \"Vector\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + +The following functions are available for the "QR" objects: +"size", "\". When "A" is rectangular, "\" will return a +least squares solution and if the solution is not unique, the one +with smallest norm is returned. + +Multiplication with respect to either thin or full "Q" is +allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A +"Q" matrix can be converted into a regular matrix with "full()" +which has a named argument "thin". + +Note: "qrfact" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the "Q" and "R" matrices can be stored compactly rather + as two separate dense matrices.The data contained in "QR" or + "QRPivoted" can be used to construct the "QRPackedQ" type, + which is a compact representation of the rotation matrix: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where \tau_i is the scale factor and v_i is the projection + vector associated with the i^{th} Householder elementary + reflector.The data contained in "QRCompactWY" can be used to + construct the "QRCompactWYQ" type, which is a compact + representation of the rotation matrix + + Q = I + Y T Y^T + + where "Y" is m \times r lower trapezoidal and "T" is r + \times r upper triangular. The *compact WY* representation + [Schreiber1989] is not to be confused with the older, *WY* + representation [Bischof1987]. (The LAPACK documentation uses + "V" in lieu of "Y".) + +[Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + +[Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 """ qrfact doc""" -```rst -qrfact(A) -> SPQR.Factorization + qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix "A". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with "\". The function calls the - C library SPQR and a few additional functions from the library are - wrapped but not exported. -``` +Compute the QR factorization of a sparse matrix "A". A fill- +reducing permutation is used. The main application of this type is +to solve least squares problems with "\". The function calls the +C library SPQR and a few additional functions from the library are +wrapped but not exported. """ qrfact doc""" -```rst -qrfact!(A[, pivot=Val{false}]) + qrfact!(A[, pivot=Val{false}]) - "qrfact!" is the same as "qrfact()" when A is a subtype of - "StridedMatrix", but saves space by overwriting the input "A", - instead of creating a copy. -``` +"qrfact!" is the same as "qrfact()" when A is a subtype of +"StridedMatrix", but saves space by overwriting the input "A", +instead of creating a copy. """ qrfact! doc""" -```rst -full(QRCompactWYQ[, thin=true]) -> Matrix + full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a - "QRCompactWYQ" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. +Converts an orthogonal or unitary matrix stored as a +"QRCompactWYQ" object, i.e. in the compact WY format +[Bischof1987], to a dense matrix. - Optionally takes a "thin" Boolean argument, which if "true" - omits the columns that span the rows of "R" in the QR - factorization that are zero. The resulting matrix is the "Q" in a - thin QR factorization (sometimes called the reduced QR - factorization). If "false", returns a "Q" that spans all rows - of "R" in its corresponding QR factorization. -``` +Optionally takes a "thin" Boolean argument, which if "true" +omits the columns that span the rows of "R" in the QR +factorization that are zero. The resulting matrix is the "Q" in a +thin QR factorization (sometimes called the reduced QR +factorization). If "false", returns a "Q" that spans all rows +of "R" in its corresponding QR factorization. """ full doc""" -```rst -bkfact(A) -> BunchKaufman + bkfact(A) -> BunchKaufman - Compute the Bunch-Kaufman [Bunch1977] factorization of a real - symmetric or complex Hermitian matrix "A" and return a - "BunchKaufman" object. The following functions are available for - "BunchKaufman" objects: "size", "\", "inv", "issym", - "ishermitian". -``` +Compute the Bunch-Kaufman [Bunch1977] factorization of a real +symmetric or complex Hermitian matrix "A" and return a +"BunchKaufman" object. The following functions are available for +"BunchKaufman" objects: "size", "\", "inv", "issym", +"ishermitian". """ bkfact doc""" -```rst -bkfact!(A) -> BunchKaufman + bkfact!(A) -> BunchKaufman - "bkfact!" is the same as "bkfact()", but saves space by - overwriting the input "A", instead of creating a copy. -``` +"bkfact!" is the same as "bkfact()", but saves space by +overwriting the input "A", instead of creating a copy. """ bkfact! doc""" -```rst -sqrtm(A) + sqrtm(A) - Compute the matrix square root of "A". If "B = sqrtm(A)", then - "B*B == A" within roundoff error. +Compute the matrix square root of "A". If "B = sqrtm(A)", then +"B*B == A" within roundoff error. - "sqrtm" uses a polyalgorithm, computing the matrix square root - using Schur factorizations ("schurfact()") unless it detects the - matrix to be Hermitian or real symmetric, in which case it computes - the matrix square root from an eigendecomposition ("eigfact()"). - In the latter situation for positive definite matrices, the matrix - square root has "Real" elements, otherwise it has "Complex" - elements. -``` +"sqrtm" uses a polyalgorithm, computing the matrix square root +using Schur factorizations ("schurfact()") unless it detects the +matrix to be Hermitian or real symmetric, in which case it computes +the matrix square root from an eigendecomposition ("eigfact()"). +In the latter situation for positive definite matrices, the matrix +square root has "Real" elements, otherwise it has "Complex" +elements. """ sqrtm doc""" -```rst -eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - Computes eigenvalues and eigenvectors of "A". See "eigfact()" - for details on the "balance" keyword argument. +Computes eigenvalues and eigenvectors of "A". See "eigfact()" +for details on the "balance" keyword argument. - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) - "eig" is a wrapper around "eigfact()", extracting all parts of - the factorization to a tuple; where possible, using "eigfact()" - is recommended. -``` +"eig" is a wrapper around "eigfact()", extracting all parts of +the factorization to a tuple; where possible, using "eigfact()" +is recommended. """ eig doc""" -```rst -eig(A, B) -> D, V + eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of "A" with respect - to "B". +Computes generalized eigenvalues and vectors of "A" with respect +to "B". - "eig" is a wrapper around "eigfact()", extracting all parts of - the factorization to a tuple; where possible, using "eigfact()" - is recommended. -``` +"eig" is a wrapper around "eigfact()", extracting all parts of +the factorization to a tuple; where possible, using "eigfact()" +is recommended. """ eig doc""" -```rst -eigvals(A,[irange,][vl,][vu]) + eigvals(A,[irange,][vl,][vu]) - Returns the eigenvalues of "A". If "A" is "Symmetric", - "Hermitian" or "SymTridiagonal", it is possible to calculate - only a subset of the eigenvalues by specifying either a - "UnitRange" "irange" covering indices of the sorted - eigenvalues, or a pair "vl" and "vu" for the lower and upper - boundaries of the eigenvalues. +Returns the eigenvalues of "A". If "A" is "Symmetric", +"Hermitian" or "SymTridiagonal", it is possible to calculate +only a subset of the eigenvalues by specifying either a +"UnitRange" "irange" covering indices of the sorted +eigenvalues, or a pair "vl" and "vu" for the lower and upper +boundaries of the eigenvalues. - For general non-symmetric matrices it is possible to specify how - the matrix is balanced before the eigenvector calculation. The - option "permute=true" permutes the matrix to become closer to - upper triangular, and "scale=true" scales the matrix by its - diagonal elements to make rows and columns more equal in norm. The - default is "true" for both options. -``` +For general non-symmetric matrices it is possible to specify how +the matrix is balanced before the eigenvector calculation. The +option "permute=true" permutes the matrix to become closer to +upper triangular, and "scale=true" scales the matrix by its +diagonal elements to make rows and columns more equal in norm. The +default is "true" for both options. """ eigvals doc""" -```rst -eigmax(A) + eigmax(A) - Returns the largest eigenvalue of "A". -``` +Returns the largest eigenvalue of "A". """ eigmax doc""" -```rst -eigmin(A) + eigmin(A) - Returns the smallest eigenvalue of "A". -``` +Returns the smallest eigenvalue of "A". """ eigmin doc""" -```rst -eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - Returns a matrix "M" whose columns are the eigenvectors of "A". - (The "k"th eigenvector can be obtained from the slice "M[:, - k]".) The "permute" and "scale" keywords are the same as for - "eigfact()". +Returns a matrix "M" whose columns are the eigenvectors of "A". +(The "k"th eigenvector can be obtained from the slice "M[:, +k]".) The "permute" and "scale" keywords are the same as for +"eigfact()". - For "SymTridiagonal" matrices, if the optional vector of - eigenvalues "eigvals" is specified, returns the specific - corresponding eigenvectors. -``` +For "SymTridiagonal" matrices, if the optional vector of +eigenvalues "eigvals" is specified, returns the specific +corresponding eigenvectors. """ eigvecs doc""" -```rst -eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - Computes the eigenvalue decomposition of "A", returning an - "Eigen" factorization object "F" which contains the eigenvalues - in "F[:values]" and the eigenvectors in the columns of the matrix - "F[:vectors]". (The "k"th eigenvector can be obtained from the - slice "F[:vectors][:, k]".) +Computes the eigenvalue decomposition of "A", returning an +"Eigen" factorization object "F" which contains the eigenvalues +in "F[:values]" and the eigenvectors in the columns of the matrix +"F[:vectors]". (The "k"th eigenvector can be obtained from the +slice "F[:vectors][:, k]".) - The following functions are available for "Eigen" objects: - "inv", "det". +The following functions are available for "Eigen" objects: +"inv", "det". - If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it - is possible to calculate only a subset of the eigenvalues by - specifying either a "UnitRange" "irange" covering indices of - the sorted eigenvalues or a pair "vl" and "vu" for the lower - and upper boundaries of the eigenvalues. +If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it +is possible to calculate only a subset of the eigenvalues by +specifying either a "UnitRange" "irange" covering indices of +the sorted eigenvalues or a pair "vl" and "vu" for the lower +and upper boundaries of the eigenvalues. - For general nonsymmetric matrices it is possible to specify how the - matrix is balanced before the eigenvector calculation. The option - "permute=true" permutes the matrix to become closer to upper - triangular, and "scale=true" scales the matrix by its diagonal - elements to make rows and columns more equal in norm. The default - is "true" for both options. -``` +For general nonsymmetric matrices it is possible to specify how the +matrix is balanced before the eigenvector calculation. The option +"permute=true" permutes the matrix to become closer to upper +triangular, and "scale=true" scales the matrix by its diagonal +elements to make rows and columns more equal in norm. The default +is "true" for both options. """ eigfact doc""" -```rst -eigfact(A, B) -> GeneralizedEigen + eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of "A" and - "B", returning a "GeneralizedEigen" factorization object "F" - which contains the generalized eigenvalues in "F[:values]" and - the generalized eigenvectors in the columns of the matrix - "F[:vectors]". (The "k"th generalized eigenvector can be - obtained from the slice "F[:vectors][:, k]".) -``` +Computes the generalized eigenvalue decomposition of "A" and +"B", returning a "GeneralizedEigen" factorization object "F" +which contains the generalized eigenvalues in "F[:values]" and +the generalized eigenvectors in the columns of the matrix +"F[:vectors]". (The "k"th generalized eigenvector can be +obtained from the slice "F[:vectors][:, k]".) """ eigfact doc""" -```rst -eigfact!(A[, B]) + eigfact!(A[, B]) - Same as "eigfact()", but saves space by overwriting the input - "A" (and "B"), instead of creating a copy. -``` +Same as "eigfact()", but saves space by overwriting the input +"A" (and "B"), instead of creating a copy. """ eigfact! doc""" -```rst -hessfact(A) + hessfact(A) - Compute the Hessenberg decomposition of "A" and return a - "Hessenberg" object. If "F" is the factorization object, the - unitary matrix can be accessed with "F[:Q]" and the Hessenberg - matrix with "F[:H]". When "Q" is extracted, the resulting type - is the "HessenbergQ" object, and may be converted to a regular - matrix with "full()". -``` +Compute the Hessenberg decomposition of "A" and return a +"Hessenberg" object. If "F" is the factorization object, the +unitary matrix can be accessed with "F[:Q]" and the Hessenberg +matrix with "F[:H]". When "Q" is extracted, the resulting type +is the "HessenbergQ" object, and may be converted to a regular +matrix with "full()". """ hessfact doc""" -```rst -hessfact!(A) + hessfact!(A) - "hessfact!" is the same as "hessfact()", but saves space by - overwriting the input A, instead of creating a copy. -``` +"hessfact!" is the same as "hessfact()", but saves space by +overwriting the input A, instead of creating a copy. """ hessfact! doc""" -```rst -schurfact(A) -> Schur + schurfact(A) -> Schur - Computes the Schur factorization of the matrix "A". The (quasi) - triangular Schur factor can be obtained from the "Schur" object - "F" with either "F[:Schur]" or "F[:T]" and the - unitary/orthogonal Schur vectors can be obtained with - "F[:vectors]" or "F[:Z]" such that - "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" - can be obtained with "F[:values]". -``` +Computes the Schur factorization of the matrix "A". The (quasi) +triangular Schur factor can be obtained from the "Schur" object +"F" with either "F[:Schur]" or "F[:T]" and the +unitary/orthogonal Schur vectors can be obtained with +"F[:vectors]" or "F[:Z]" such that +"A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" +can be obtained with "F[:values]". """ schurfact doc""" -```rst -schurfact!(A) + schurfact!(A) - Computes the Schur factorization of "A", overwriting "A" in the - process. See "schurfact()" -``` +Computes the Schur factorization of "A", overwriting "A" in the +process. See "schurfact()" """ schurfact! doc""" -```rst -schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + schur(A) -> Schur[:T], Schur[:Z], Schur[:values] - See "schurfact()" -``` +See "schurfact()" """ schur doc""" -```rst -ordschur(Q, T, select) -> Schur + ordschur(Q, T, select) -> Schur - Reorders the Schur factorization of a real matrix "A=Q*T*Q'" - according to the logical array "select" returning a Schur object - "F". The selected eigenvalues appear in the leading diagonal of - "F[:Schur]" and the the corresponding leading columns of - "F[:vectors]" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via "select". -``` +Reorders the Schur factorization of a real matrix "A=Q*T*Q'" +according to the logical array "select" returning a Schur object +"F". The selected eigenvalues appear in the leading diagonal of +"F[:Schur]" and the the corresponding leading columns of +"F[:vectors]" form an orthonormal basis of the corresponding +right invariant subspace. A complex conjugate pair of eigenvalues +must be either both included or excluded via "select". """ ordschur doc""" -```rst -ordschur!(Q, T, select) -> Schur + ordschur!(Q, T, select) -> Schur - Reorders the Schur factorization of a real matrix "A=Q*T*Q'", - overwriting "Q" and "T" in the process. See "ordschur()" -``` +Reorders the Schur factorization of a real matrix "A=Q*T*Q'", +overwriting "Q" and "T" in the process. See "ordschur()" """ ordschur! doc""" -```rst -ordschur(S, select) -> Schur + ordschur(S, select) -> Schur - Reorders the Schur factorization "S" of type "Schur". -``` +Reorders the Schur factorization "S" of type "Schur". """ ordschur doc""" -```rst -ordschur!(S, select) -> Schur + ordschur!(S, select) -> Schur - Reorders the Schur factorization "S" of type "Schur", - overwriting "S" in the process. See "ordschur()" -``` +Reorders the Schur factorization "S" of type "Schur", +overwriting "S" in the process. See "ordschur()" """ ordschur! doc""" -```rst -schurfact(A, B) -> GeneralizedSchur + schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the - matrices "A" and "B". The (quasi) triangular Schur factors can - be obtained from the "Schur" object "F" with "F[:S]" and - "F[:T]", the left unitary/orthogonal Schur vectors can be - obtained with "F[:left]" or "F[:Q]" and the right - unitary/orthogonal Schur vectors can be obtained with "F[:right]" - or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and - "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of - "A" and "B" can be obtained with "F[:alpha]./F[:beta]". -``` +Computes the Generalized Schur (or QZ) factorization of the +matrices "A" and "B". The (quasi) triangular Schur factors can +be obtained from the "Schur" object "F" with "F[:S]" and +"F[:T]", the left unitary/orthogonal Schur vectors can be +obtained with "F[:left]" or "F[:Q]" and the right +unitary/orthogonal Schur vectors can be obtained with "F[:right]" +or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and +"B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of +"A" and "B" can be obtained with "F[:alpha]./F[:beta]". """ schurfact doc""" -```rst -schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See "schurfact()" -``` +See "schurfact()" """ schur doc""" -```rst -ordschur(S, T, Q, Z, select) -> GeneralizedSchur + ordschur(S, T, Q, Z, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a matrix "(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" - and returns a GeneralizedSchur object "GS". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that "(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of - "A" and "B" can still be obtained with - "GS[:alpha]./GS[:beta]". -``` +Reorders the Generalized Schur factorization of a matrix "(A, B) = +(Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" +and returns a GeneralizedSchur object "GS". The selected +eigenvalues appear in the leading diagonal of both``(GS[:S], +GS[:T])`` and the left and right unitary/orthogonal Schur vectors +are also reordered such that "(A, B) = GS[:Q]*(GS[:S], +GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of +"A" and "B" can still be obtained with +"GS[:alpha]./GS[:beta]". """ ordschur doc""" -```rst -ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices "(S, T, Q, Z)" in the process. See - "ordschur()". -``` +Reorders the Generalized Schur factorization of a matrix by +overwriting the matrices "(S, T, Q, Z)" in the process. See +"ordschur()". """ ordschur! doc""" -```rst -ordschur(GS, select) -> GeneralizedSchur + ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object. See "ordschur()". -``` +Reorders the Generalized Schur factorization of a Generalized Schur +object. See "ordschur()". """ ordschur doc""" -```rst -ordschur!(GS, select) -> GeneralizedSchur + ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - "ordschur()". -``` +Reorders the Generalized Schur factorization of a Generalized Schur +object by overwriting the object with the new factorization. See +"ordschur()". """ ordschur! doc""" -```rst -svdfact(A[, thin=true]) -> SVD + svdfact(A[, thin=true]) -> SVD - Compute the Singular Value Decomposition (SVD) of "A" and return - an "SVD" object. "U", "S", "V" and "Vt" can be obtained - from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" - and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is - "true", an economy mode decomposition is returned. The algorithm - produces "Vt" and hence "Vt" is more efficient to extract than - "V". The default is to produce a thin decomposition. -``` +Compute the Singular Value Decomposition (SVD) of "A" and return +an "SVD" object. "U", "S", "V" and "Vt" can be obtained +from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" +and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is +"true", an economy mode decomposition is returned. The algorithm +produces "Vt" and hence "Vt" is more efficient to extract than +"V". The default is to produce a thin decomposition. """ svdfact doc""" -```rst -svdfact!(A[, thin=true]) -> SVD + svdfact!(A[, thin=true]) -> SVD - "svdfact!" is the same as "svdfact()", but saves space by - overwriting the input A, instead of creating a copy. If "thin" is - "true", an economy mode decomposition is returned. The default is - to produce a thin decomposition. -``` +"svdfact!" is the same as "svdfact()", but saves space by +overwriting the input A, instead of creating a copy. If "thin" is +"true", an economy mode decomposition is returned. The default is +to produce a thin decomposition. """ svdfact! doc""" -```rst -svd(A[, thin=true]) -> U, S, V + svd(A[, thin=true]) -> U, S, V - Wrapper around "svdfact" extracting all parts the factorization - to a tuple. Direct use of "svdfact" is therefore generally more - efficient. Computes the SVD of A, returning "U", vector "S", - and "V" such that "A == U*diagm(S)*V'". If "thin" is - "true", an economy mode decomposition is returned. The default is - to produce a thin decomposition. -``` +Wrapper around "svdfact" extracting all parts the factorization +to a tuple. Direct use of "svdfact" is therefore generally more +efficient. Computes the SVD of A, returning "U", vector "S", +and "V" such that "A == U*diagm(S)*V'". If "thin" is +"true", an economy mode decomposition is returned. The default is +to produce a thin decomposition. """ svd doc""" -```rst -svdvals(A) + svdvals(A) - Returns the singular values of "A". -``` +Returns the singular values of "A". """ svdvals doc""" -```rst -svdvals!(A) + svdvals!(A) - Returns the singular values of "A", while saving space by - overwriting the input. -``` +Returns the singular values of "A", while saving space by +overwriting the input. """ svdvals! doc""" -```rst -svdfact(A, B) -> GeneralizedSVD + svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of "A" and "B", returning a - "GeneralizedSVD" Factorization object "F", such that "A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'". -``` +Compute the generalized SVD of "A" and "B", returning a +"GeneralizedSVD" Factorization object "F", such that "A = +F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = +F[:V]*F[:D2]*F[:R0]*F[:Q]'". """ svdfact doc""" -```rst -svd(A, B) -> U, V, Q, D1, D2, R0 + svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around "svdfact" extracting all parts the factorization - to a tuple. Direct use of "svdfact" is therefore generally more - efficient. The function returns the generalized SVD of "A" and - "B", returning "U", "V", "Q", "D1", "D2", and "R0" - such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". -``` +Wrapper around "svdfact" extracting all parts the factorization +to a tuple. Direct use of "svdfact" is therefore generally more +efficient. The function returns the generalized SVD of "A" and +"B", returning "U", "V", "Q", "D1", "D2", and "R0" +such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". """ svd doc""" -```rst -svdvals(A, B) + svdvals(A, B) - Return only the singular values from the generalized singular value - decomposition of "A" and "B". -``` +Return only the singular values from the generalized singular value +decomposition of "A" and "B". """ svdvals doc""" -```rst -triu(M) + triu(M) - Upper triangle of a matrix. -``` +Upper triangle of a matrix. """ triu doc""" -```rst -triu(M, k) + triu(M, k) - Returns the upper triangle of "M" starting from the "k"th - superdiagonal. -``` +Returns the upper triangle of "M" starting from the "k"th +superdiagonal. """ triu doc""" -```rst -triu!(M) + triu!(M) - Upper triangle of a matrix, overwriting "M" in the process. -``` +Upper triangle of a matrix, overwriting "M" in the process. """ triu! doc""" -```rst -triu!(M, k) + triu!(M, k) - Returns the upper triangle of "M" starting from the "k"th - superdiagonal, overwriting "M" in the process. -``` +Returns the upper triangle of "M" starting from the "k"th +superdiagonal, overwriting "M" in the process. """ triu! doc""" -```rst -tril(M) + tril(M) - Lower triangle of a matrix. -``` +Lower triangle of a matrix. """ tril doc""" -```rst -tril(M, k) + tril(M, k) - Returns the lower triangle of "M" starting from the "k"th - subdiagonal. -``` +Returns the lower triangle of "M" starting from the "k"th +subdiagonal. """ tril doc""" -```rst -tril!(M) + tril!(M) - Lower triangle of a matrix, overwriting "M" in the process. -``` +Lower triangle of a matrix, overwriting "M" in the process. """ tril! doc""" -```rst -tril!(M, k) + tril!(M, k) - Returns the lower triangle of "M" starting from the "k"th - subdiagonal, overwriting "M" in the process. -``` +Returns the lower triangle of "M" starting from the "k"th +subdiagonal, overwriting "M" in the process. """ tril! doc""" -```rst -diagind(M[, k]) + diagind(M[, k]) - A "Range" giving the indices of the "k"th diagonal of the - matrix "M". -``` +A "Range" giving the indices of the "k"th diagonal of the +matrix "M". """ diagind doc""" -```rst -diag(M[, k]) + diag(M[, k]) - The "k"th diagonal of a matrix, as a vector. Use "diagm" to - construct a diagonal matrix. -``` +The "k"th diagonal of a matrix, as a vector. Use "diagm" to +construct a diagonal matrix. """ diag doc""" -```rst -diagm(v[, k]) + diagm(v[, k]) - Construct a diagonal matrix and place "v" on the "k"th - diagonal. -``` +Construct a diagonal matrix and place "v" on the "k"th +diagonal. """ diagm doc""" -```rst -scale(A, b) -``` + scale(A, b) """ scale doc""" -```rst -scale(b, A) + scale(b, A) - Scale an array "A" by a scalar "b", returning a new array. +Scale an array "A" by a scalar "b", returning a new array. - If "A" is a matrix and "b" is a vector, then "scale(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), returning a new - array. +If "A" is a matrix and "b" is a vector, then "scale(A,b)" +scales each column "i" of "A" by "b[i]" (similar to +"A*diagm(b)"), while "scale(b,A)" scales each row "i" of +"A" by "b[i]" (similar to "diagm(b)*A"), returning a new +array. - Note: for large "A", "scale" can be much faster than "A .* b" - or "b .* A", due to the use of BLAS. -``` +Note: for large "A", "scale" can be much faster than "A .* b" +or "b .* A", due to the use of BLAS. """ scale doc""" -```rst -scale!(A, b) -``` + scale!(A, b) """ scale! doc""" -```rst -scale!(b, A) + scale!(b, A) - Scale an array "A" by a scalar "b", similar to "scale()" but - overwriting "A" in-place. +Scale an array "A" by a scalar "b", similar to "scale()" but +overwriting "A" in-place. - If "A" is a matrix and "b" is a vector, then "scale!(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- - place on "A". -``` +If "A" is a matrix and "b" is a vector, then "scale!(A,b)" +scales each column "i" of "A" by "b[i]" (similar to +"A*diagm(b)"), while "scale!(b,A)" scales each row "i" of +"A" by "b[i]" (similar to "diagm(b)*A"), again operating in- +place on "A". """ scale! doc""" -```rst -Tridiagonal(dl, d, du) + Tridiagonal(dl, d, du) - Construct a tridiagonal matrix from the lower diagonal, diagonal, - and upper diagonal, respectively. The result is of type - "Tridiagonal" and provides efficient specialized linear solvers, - but may be converted into a regular matrix with "full()". -``` +Construct a tridiagonal matrix from the lower diagonal, diagonal, +and upper diagonal, respectively. The result is of type +"Tridiagonal" and provides efficient specialized linear solvers, +but may be converted into a regular matrix with "full()". """ Tridiagonal doc""" -```rst -Bidiagonal(dv, ev, isupper) + Bidiagonal(dv, ev, isupper) - Constructs an upper ("isupper=true") or lower ("isupper=false") - bidiagonal matrix using the given diagonal ("dv") and off- - diagonal ("ev") vectors. The result is of type "Bidiagonal" - and provides efficient specialized linear solvers, but may be - converted into a regular matrix with "full()". -``` +Constructs an upper ("isupper=true") or lower ("isupper=false") +bidiagonal matrix using the given diagonal ("dv") and off- +diagonal ("ev") vectors. The result is of type "Bidiagonal" +and provides efficient specialized linear solvers, but may be +converted into a regular matrix with "full()". """ Bidiagonal doc""" -```rst -SymTridiagonal(d, du) + SymTridiagonal(d, du) - Construct a real symmetric tridiagonal matrix from the diagonal and - upper diagonal, respectively. The result is of type - "SymTridiagonal" and provides efficient specialized eigensolvers, - but may be converted into a regular matrix with "full()". -``` +Construct a real symmetric tridiagonal matrix from the diagonal and +upper diagonal, respectively. The result is of type +"SymTridiagonal" and provides efficient specialized eigensolvers, +but may be converted into a regular matrix with "full()". """ SymTridiagonal doc""" -```rst -rank(M) + rank(M) - Compute the rank of a matrix. -``` +Compute the rank of a matrix. """ rank doc""" -```rst -norm(A[, p]) + norm(A[, p]) - Compute the "p"-norm of a vector or the operator norm of a matrix - "A", defaulting to the "p=2"-norm. +Compute the "p"-norm of a vector or the operator norm of a matrix +"A", defaulting to the "p=2"-norm. - For vectors, "p" can assume any numeric value (even though not - all values produce a mathematically valid vector norm). In - particular, "norm(A, Inf)" returns the largest value in - "abs(A)", whereas "norm(A, -Inf)" returns the smallest. +For vectors, "p" can assume any numeric value (even though not +all values produce a mathematically valid vector norm). In +particular, "norm(A, Inf)" returns the largest value in +"abs(A)", whereas "norm(A, -Inf)" returns the smallest. - For matrices, valid values of "p" are "1", "2", or "Inf". - (Note that for sparse matrices, "p=2" is currently not - implemented.) Use "vecnorm()" to compute the Frobenius norm. -``` +For matrices, valid values of "p" are "1", "2", or "Inf". +(Note that for sparse matrices, "p=2" is currently not +implemented.) Use "vecnorm()" to compute the Frobenius norm. """ norm doc""" -```rst -vecnorm(A[, p]) + vecnorm(A[, p]) - For any iterable container "A" (including arrays of any - dimension) of numbers (or any element type for which "norm" is - defined), compute the "p"-norm (defaulting to "p=2") as if - "A" were a vector of the corresponding length. +For any iterable container "A" (including arrays of any +dimension) of numbers (or any element type for which "norm" is +defined), compute the "p"-norm (defaulting to "p=2") as if +"A" were a vector of the corresponding length. - For example, if "A" is a matrix and "p=2", then this is - equivalent to the Frobenius norm. -``` +For example, if "A" is a matrix and "p=2", then this is +equivalent to the Frobenius norm. """ vecnorm doc""" -```rst -cond(M[, p]) + cond(M[, p]) - Condition number of the matrix "M", computed using the operator - "p"-norm. Valid values for "p" are "1", "2" (default), or - "Inf". -``` +Condition number of the matrix "M", computed using the operator +"p"-norm. Valid values for "p" are "1", "2" (default), or +"Inf". """ cond doc""" -```rst -condskeel(M[, x, p]) + condskeel(M[, x, p]) - \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \right\Vert_p \\ - \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \left\vert x \right\vert - \right\Vert_p + \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \right\Vert_p \\ + \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \left\vert x \right\vert + \right\Vert_p - Skeel condition number \kappa_S of the matrix "M", optionally - with respect to the vector "x", as computed using the operator - "p"-norm. "p" is "Inf" by default, if not provided. Valid - values for "p" are "1", "2", or "Inf". +Skeel condition number \kappa_S of the matrix "M", optionally +with respect to the vector "x", as computed using the operator +"p"-norm. "p" is "Inf" by default, if not provided. Valid +values for "p" are "1", "2", or "Inf". - This quantity is also known in the literature as the Bauer - condition number, relative condition number, or componentwise - relative condition number. -``` +This quantity is also known in the literature as the Bauer +condition number, relative condition number, or componentwise +relative condition number. """ condskeel doc""" -```rst -trace(M) + trace(M) - Matrix trace -``` +Matrix trace """ trace doc""" -```rst -det(M) + det(M) - Matrix determinant -``` +Matrix determinant """ det doc""" -```rst -logdet(M) + logdet(M) - Log of matrix determinant. Equivalent to "log(det(M))", but may - provide increased accuracy and/or speed. -``` +Log of matrix determinant. Equivalent to "log(det(M))", but may +provide increased accuracy and/or speed. """ logdet doc""" -```rst -logabsdet(M) + logabsdet(M) - Log of absolute value of determinant of real matrix. Equivalent to - "(log(abs(det(M))), sign(det(M)))", but may provide increased - accuracy and/or speed. -``` +Log of absolute value of determinant of real matrix. Equivalent to +"(log(abs(det(M))), sign(det(M)))", but may provide increased +accuracy and/or speed. """ logabsdet doc""" -```rst -inv(M) + inv(M) - Matrix inverse -``` +Matrix inverse """ inv doc""" -```rst -pinv(M[, tol]) + pinv(M[, tol]) - Computes the Moore-Penrose pseudoinverse. +Computes the Moore-Penrose pseudoinverse. - For matrices "M" with floating point elements, it is convenient - to compute the pseudoinverse by inverting only singular values - above a given threshold, "tol". +For matrices "M" with floating point elements, it is convenient +to compute the pseudoinverse by inverting only singular values +above a given threshold, "tol". - The optimal choice of "tol" varies both with the value of "M" - and the intended application of the pseudoinverse. The default - value of "tol" is - "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is - essentially machine epsilon for the real part of a matrix element - multiplied by the larger matrix dimension. For inverting dense ill- - conditioned matrices in a least-squares sense, "tol = - sqrt(eps(real(float(one(eltype(M))))))" is recommended. +The optimal choice of "tol" varies both with the value of "M" +and the intended application of the pseudoinverse. The default +value of "tol" is +"eps(real(float(one(eltype(M)))))*maximum(size(A))", which is +essentially machine epsilon for the real part of a matrix element +multiplied by the larger matrix dimension. For inverting dense ill- +conditioned matrices in a least-squares sense, "tol = +sqrt(eps(real(float(one(eltype(M))))))" is recommended. - For more information, see [8859], [B96], [S84], [KY88]. +For more information, see [8859], [B96], [S84], [KY88]. - [8859] Issue 8859, "Fix least squares", - https://github.com/JuliaLang/julia/pull/8859 +[8859] Issue 8859, "Fix least squares", + https://github.com/JuliaLang/julia/pull/8859 - [B96] Åke Björck, "Numerical Methods for Least Squares - Problems", SIAM Press, Philadelphia, 1996, "Other Titles in - Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 +[B96] Åke Björck, "Numerical Methods for Least Squares + Problems", SIAM Press, Philadelphia, 1996, "Other Titles in + Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 - [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 +[S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 - [KY88] Konstantinos Konstantinides and Kung Yao, - "Statistical analysis of effective singular values in - matrix rank determination", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 -``` +[KY88] Konstantinos Konstantinides and Kung Yao, + "Statistical analysis of effective singular values in + matrix rank determination", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 """ pinv doc""" -```rst -nullspace(M) + nullspace(M) - Basis for nullspace of "M". -``` +Basis for nullspace of "M". """ nullspace doc""" -```rst -repmat(A, n, m) + repmat(A, n, m) - Construct a matrix by repeating the given matrix "n" times in - dimension 1 and "m" times in dimension 2. -``` +Construct a matrix by repeating the given matrix "n" times in +dimension 1 and "m" times in dimension 2. """ repmat doc""" -```rst -repeat(A, inner = Int[], outer = Int[]) + repeat(A, inner = Int[], outer = Int[]) - Construct an array by repeating the entries of "A". The i-th - element of "inner" specifies the number of times that the - individual entries of the i-th dimension of "A" should be - repeated. The i-th element of "outer" specifies the number of - times that a slice along the i-th dimension of "A" should be - repeated. -``` +Construct an array by repeating the entries of "A". The i-th +element of "inner" specifies the number of times that the +individual entries of the i-th dimension of "A" should be +repeated. The i-th element of "outer" specifies the number of +times that a slice along the i-th dimension of "A" should be +repeated. """ repeat doc""" -```rst -kron(A, B) + kron(A, B) - Kronecker tensor product of two vectors or two matrices. -``` +Kronecker tensor product of two vectors or two matrices. """ kron doc""" -```rst -blkdiag(A...) + blkdiag(A...) - Concatenate matrices block-diagonally. Currently only implemented - for sparse matrices. -``` +Concatenate matrices block-diagonally. Currently only implemented +for sparse matrices. """ blkdiag doc""" -```rst -linreg(x, y) -> [a; b] + linreg(x, y) -> [a; b] - Linear Regression. Returns "a" and "b" such that "a+b*x" is - the closest line to the given points "(x,y)". In other words, - this function determines parameters "[a, b]" that minimize the - squared error between "y" and "a+b*x". +Linear Regression. Returns "a" and "b" such that "a+b*x" is +the closest line to the given points "(x,y)". In other words, +this function determines parameters "[a, b]" that minimize the +squared error between "y" and "a+b*x". - **Example**: +**Example**: - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, "o") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression -``` + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression """ linreg doc""" -```rst -linreg(x, y, w) + linreg(x, y, w) - Weighted least-squares linear regression. -``` +Weighted least-squares linear regression. """ linreg doc""" -```rst -expm(A) + expm(A) - Matrix exponential. -``` +Matrix exponential. """ expm doc""" -```rst -lyap(A, C) + lyap(A, C) - Computes the solution "X" to the continuous Lyapunov equation - "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real - part and no two eigenvalues are negative complex conjugates of each - other. -``` +Computes the solution "X" to the continuous Lyapunov equation +"AX + XA' + C = 0", where no eigenvalue of "A" has a zero real +part and no two eigenvalues are negative complex conjugates of each +other. """ lyap doc""" -```rst -sylvester(A, B, C) + sylvester(A, B, C) - Computes the solution "X" to the Sylvester equation "AX + XB + C - = 0", where "A", "B" and "C" have compatible dimensions and - "A" and "-B" have no eigenvalues with equal real part. -``` +Computes the solution "X" to the Sylvester equation "AX + XB + C += 0", where "A", "B" and "C" have compatible dimensions and +"A" and "-B" have no eigenvalues with equal real part. """ sylvester doc""" -```rst -issym(A) -> Bool + issym(A) -> Bool - Test whether a matrix is symmetric. -``` +Test whether a matrix is symmetric. """ issym doc""" -```rst -isposdef(A) -> Bool + isposdef(A) -> Bool - Test whether a matrix is positive definite. -``` +Test whether a matrix is positive definite. """ isposdef doc""" -```rst -isposdef!(A) -> Bool + isposdef!(A) -> Bool - Test whether a matrix is positive definite, overwriting "A" in - the processes. -``` +Test whether a matrix is positive definite, overwriting "A" in +the processes. """ isposdef! doc""" -```rst -istril(A) -> Bool + istril(A) -> Bool - Test whether a matrix is lower triangular. -``` +Test whether a matrix is lower triangular. """ istril doc""" -```rst -istriu(A) -> Bool + istriu(A) -> Bool - Test whether a matrix is upper triangular. -``` +Test whether a matrix is upper triangular. """ istriu doc""" -```rst -isdiag(A) -> Bool + isdiag(A) -> Bool - Test whether a matrix is diagonal. -``` +Test whether a matrix is diagonal. """ isdiag doc""" -```rst -ishermitian(A) -> Bool + ishermitian(A) -> Bool - Test whether a matrix is Hermitian. -``` +Test whether a matrix is Hermitian. """ ishermitian doc""" -```rst -transpose(A) + transpose(A) - The transposition operator (".'"). -``` +The transposition operator (".'"). """ transpose doc""" -```rst -transpose!(dest, src) + transpose!(dest, src) - Transpose array "src" and store the result in the preallocated - array "dest", which should have a size corresponding to - "(size(src,2),size(src,1))". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. -``` +Transpose array "src" and store the result in the preallocated +array "dest", which should have a size corresponding to +"(size(src,2),size(src,1))". No in-place transposition is +supported and unexpected results will happen if *src* and *dest* +have overlapping memory regions. """ transpose! doc""" -```rst -ctranspose(A) + ctranspose(A) - The conjugate transposition operator ("'"). -``` +The conjugate transposition operator ("'"). """ ctranspose doc""" -```rst -ctranspose!(dest, src) + ctranspose!(dest, src) - Conjugate transpose array "src" and store the result in the - preallocated array "dest", which should have a size corresponding - to "(size(src,2),size(src,1))". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. -``` +Conjugate transpose array "src" and store the result in the +preallocated array "dest", which should have a size corresponding +to "(size(src,2),size(src,1))". No in-place transposition is +supported and unexpected results will happen if *src* and *dest* +have overlapping memory regions. """ ctranspose! doc""" -```rst -eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - - Computes eigenvalues "d" of "A" using Lanczos or Arnoldi - iterations for real symmetric or general nonsymmetric matrices - respectively. If "B" is provided, the generalized eigenproblem is - solved. - - The following keyword arguments are supported: - * "nev": Number of eigenvalues - - * "ncv": Number of Krylov vectors used in the computation; - should satisfy - - "nev+1 <= ncv <= n" for real symmetric problems and - "nev+2 <= ncv <= n" for other problems, where "n" is - the size of the input matrix "A". The default is "ncv = - max(20,2*nev+1)". Note that these restrictions limit the - input matrix "A" to be of dimension at least 2. - - * "which": type of eigenvalues to compute. See the note - below. - - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \"which\" | type of eigenvalues | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LM\" | eigenvalues of largest magnitude (default) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SM\" | eigenvalues of smallest magnitude | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LR\" | eigenvalues of largest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SR\" | eigenvalues of smallest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - - * "tol": tolerance (tol \le 0.0 defaults to - "DLAMCH('EPS')") - - * "maxiter": Maximum number of iterations (default = 300) - - * "sigma": Specifies the level shift used in inverse - iteration. If "nothing" (default), defaults to ordinary - (forward) iterations. Otherwise, find eigenvalues close to - "sigma" using shift and invert iterations. - - * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) - if "true" - - * "v0": starting vector from which to start the iterations - - "eigs" returns the "nev" requested eigenvalues in "d", the - corresponding Ritz vectors "v" (only if "ritzvec=true"), the - number of converged eigenvalues "nconv", the number of iterations - "niter" and the number of matrix vector multiplications - "nmult", as well as the final residual vector "resid". - - Note: The "sigma" and "which" keywords interact: the - description of eigenvalues searched for by "which" do _not_ - necessarily refer to the eigenvalues of "A", but rather the - linear operator constructed by the specification of the iteration - mode implied by "sigma". - - +-----------------+------------------------------------+------------------------------------+ - | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | - +-----------------+------------------------------------+------------------------------------+ - | \"nothing\" | ordinary (forward) | A | - +-----------------+------------------------------------+------------------------------------+ - | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | - +-----------------+------------------------------------+------------------------------------+ -``` + eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) + +Computes eigenvalues "d" of "A" using Lanczos or Arnoldi +iterations for real symmetric or general nonsymmetric matrices +respectively. If "B" is provided, the generalized eigenproblem is +solved. + +The following keyword arguments are supported: + * "nev": Number of eigenvalues + + * "ncv": Number of Krylov vectors used in the computation; + should satisfy + + "nev+1 <= ncv <= n" for real symmetric problems and + "nev+2 <= ncv <= n" for other problems, where "n" is + the size of the input matrix "A". The default is "ncv = + max(20,2*nev+1)". Note that these restrictions limit the + input matrix "A" to be of dimension at least 2. + + * "which": type of eigenvalues to compute. See the note + below. + + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \"which\" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LM\" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SM\" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LR\" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SR\" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + + * "tol": tolerance (tol \le 0.0 defaults to + "DLAMCH('EPS')") + + * "maxiter": Maximum number of iterations (default = 300) + + * "sigma": Specifies the level shift used in inverse + iteration. If "nothing" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + "sigma" using shift and invert iterations. + + * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) + if "true" + + * "v0": starting vector from which to start the iterations + +"eigs" returns the "nev" requested eigenvalues in "d", the +corresponding Ritz vectors "v" (only if "ritzvec=true"), the +number of converged eigenvalues "nconv", the number of iterations +"niter" and the number of matrix vector multiplications +"nmult", as well as the final residual vector "resid". + +Note: The "sigma" and "which" keywords interact: the + description of eigenvalues searched for by "which" do _not_ + necessarily refer to the eigenvalues of "A", but rather the + linear operator constructed by the specification of the iteration + mode implied by "sigma". + + +-----------------+------------------------------------+------------------------------------+ + | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | + +-----------------+------------------------------------+------------------------------------+ + | \"nothing\" | ordinary (forward) | A | + +-----------------+------------------------------------+------------------------------------+ + | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | + +-----------------+------------------------------------+------------------------------------+ """ eigs doc""" -```rst -svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - "svds" computes largest singular values "s" of "A" using - Lanczos or Arnoldi iterations. Uses "eigs()" underneath. +"svds" computes largest singular values "s" of "A" using +Lanczos or Arnoldi iterations. Uses "eigs()" underneath. - Inputs are: - * "A": Linear operator. It can either subtype of - "AbstractArray" (e.g., sparse matrix) or duck typed. For - duck typing "A" has to support "size(A)", "eltype(A)", - "A * vector" and "A' * vector". +Inputs are: + * "A": Linear operator. It can either subtype of + "AbstractArray" (e.g., sparse matrix) or duck typed. For + duck typing "A" has to support "size(A)", "eltype(A)", + "A * vector" and "A' * vector". - * "nsv": Number of singular values. + * "nsv": Number of singular values. - * "ritzvec": Whether to return the left and right singular - vectors "left_sv" and "right_sv", default is "true". If - "false" the singular vectors are omitted from the output. + * "ritzvec": Whether to return the left and right singular + vectors "left_sv" and "right_sv", default is "true". If + "false" the singular vectors are omitted from the output. - * "tol": tolerance, see "eigs()". + * "tol": tolerance, see "eigs()". - * "maxiter": Maximum number of iterations, see "eigs()". + * "maxiter": Maximum number of iterations, see "eigs()". - **Example**: +**Example**: - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) -``` + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) """ svds doc""" -```rst -peakflops(n; parallel=false) + peakflops(n; parallel=false) - "peakflops" computes the peak flop rate of the computer by using - double precision "Base.LinAlg.BLAS.gemm!()". By default, if no - arguments are specified, it multiplies a matrix of size "n x n", - where "n = 2000". If the underlying BLAS is using multiple - threads, higher flop rates are realized. The number of BLAS threads - can be set with "blas_set_num_threads(n)". +"peakflops" computes the peak flop rate of the computer by using +double precision "Base.LinAlg.BLAS.gemm!()". By default, if no +arguments are specified, it multiplies a matrix of size "n x n", +where "n = 2000". If the underlying BLAS is using multiple +threads, higher flop rates are realized. The number of BLAS threads +can be set with "blas_set_num_threads(n)". - If the keyword argument "parallel" is set to "true", - "peakflops" is run in parallel on all the worker processors. The - flop rate of the entire parallel computer is returned. When running - in parallel, only 1 BLAS thread is used. The argument "n" still - refers to the size of the problem that is solved on each processor. -``` +If the keyword argument "parallel" is set to "true", +"peakflops" is run in parallel on all the worker processors. The +flop rate of the entire parallel computer is returned. When running +in parallel, only 1 BLAS thread is used. The argument "n" still +refers to the size of the problem that is solved on each processor. """ peakflops doc""" -```rst -dot(n, X, incx, Y, incy) + dot(n, X, incx, Y, incy) - Dot product of two vectors consisting of "n" elements of array - "X" with stride "incx" and "n" elements of array "Y" with - stride "incy". -``` +Dot product of two vectors consisting of "n" elements of array +"X" with stride "incx" and "n" elements of array "Y" with +stride "incy". """ Base.LinAlg.BLAS.dot doc""" -```rst -dotu(n, X, incx, Y, incy) + dotu(n, X, incx, Y, incy) - Dot function for two complex vectors. -``` +Dot function for two complex vectors. """ Base.LinAlg.BLAS.dotu doc""" -```rst -dotc(n, X, incx, U, incy) + dotc(n, X, incx, U, incy) - Dot function for two complex vectors conjugating the first vector. -``` +Dot function for two complex vectors conjugating the first vector. """ Base.LinAlg.BLAS.dotc doc""" -```rst -blascopy!(n, X, incx, Y, incy) + blascopy!(n, X, incx, Y, incy) - Copy "n" elements of array "X" with stride "incx" to array - "Y" with stride "incy". Returns "Y". -``` +Copy "n" elements of array "X" with stride "incx" to array +"Y" with stride "incy". Returns "Y". """ Base.LinAlg.BLAS.blascopy! doc""" -```rst -nrm2(n, X, incx) + nrm2(n, X, incx) - 2-norm of a vector consisting of "n" elements of array "X" with - stride "incx". -``` +2-norm of a vector consisting of "n" elements of array "X" with +stride "incx". """ Base.LinAlg.BLAS.nrm2 doc""" -```rst -asum(n, X, incx) + asum(n, X, incx) - sum of the absolute values of the first "n" elements of array - "X" with stride "incx". -``` +sum of the absolute values of the first "n" elements of array +"X" with stride "incx". """ Base.LinAlg.BLAS.asum doc""" -```rst -axpy!(a, X, Y) + axpy!(a, X, Y) - Overwrite "Y" with "a*X + Y". Returns "Y". -``` +Overwrite "Y" with "a*X + Y". Returns "Y". """ Base.LinAlg.BLAS.axpy! doc""" -```rst -scal!(n, a, X, incx) + scal!(n, a, X, incx) - Overwrite "X" with "a*X". Returns "X". -``` +Overwrite "X" with "a*X". Returns "X". """ Base.LinAlg.BLAS.scal! doc""" -```rst -scal(n, a, X, incx) + scal(n, a, X, incx) - Returns "a*X". -``` +Returns "a*X". """ Base.LinAlg.BLAS.scal doc""" -```rst -ger!(alpha, x, y, A) + ger!(alpha, x, y, A) - Rank-1 update of the matrix "A" with vectors "x" and "y" as - "alpha*x*y' + A". -``` +Rank-1 update of the matrix "A" with vectors "x" and "y" as +"alpha*x*y' + A". """ Base.LinAlg.BLAS.ger! doc""" -```rst -syr!(uplo, alpha, x, A) + syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix "A" with vector "x" as - "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of - "A" is updated ('L' for lower triangle). Returns "A". -``` +Rank-1 update of the symmetric matrix "A" with vector "x" as +"alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of +"A" is updated ('L' for lower triangle). Returns "A". """ Base.LinAlg.BLAS.syr! doc""" -```rst -syrk!(uplo, trans, alpha, A, beta, C) + syrk!(uplo, trans, alpha, A, beta, C) - Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + - beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" - is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is - updated ('L' for lower triangle). Returns "C". -``` +Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + +beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" +is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is +updated ('L' for lower triangle). Returns "C". """ Base.LinAlg.BLAS.syrk! doc""" -```rst -syrk(uplo, trans, alpha, A) + syrk(uplo, trans, alpha, A) - Returns either the upper triangle or the lower triangle, according - to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", - according to "trans" ('N' or 'T'). -``` +Returns either the upper triangle or the lower triangle, according +to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", +according to "trans" ('N' or 'T'). """ Base.LinAlg.BLAS.syrk doc""" -```rst -her!(uplo, alpha, x, A) + her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian - matrix "A" with vector "x" as "alpha*x*x' + A". When - "uplo" is 'U' the upper triangle of "A" is updated ('L' for - lower triangle). Returns "A". -``` +Methods for complex arrays only. Rank-1 update of the Hermitian +matrix "A" with vector "x" as "alpha*x*x' + A". When +"uplo" is 'U' the upper triangle of "A" is updated ('L' for +lower triangle). Returns "A". """ Base.LinAlg.BLAS.her! doc""" -```rst -herk!(uplo, trans, alpha, A, beta, C) + herk!(uplo, trans, alpha, A, beta, C) - Methods for complex arrays only. Rank-k update of the Hermitian - matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" - according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' - the upper triangle of "C" is updated ('L' for lower triangle). - Returns "C". -``` +Methods for complex arrays only. Rank-k update of the Hermitian +matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" +according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' +the upper triangle of "C" is updated ('L' for lower triangle). +Returns "C". """ Base.LinAlg.BLAS.herk! doc""" -```rst -herk(uplo, trans, alpha, A) + herk(uplo, trans, alpha, A) - Methods for complex arrays only. Returns either the upper triangle - or the lower triangle, according to "uplo" ('U' or 'L'), of - "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or - 'T'). -``` +Methods for complex arrays only. Returns either the upper triangle +or the lower triangle, according to "uplo" ('U' or 'L'), of +"alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or +'T'). """ Base.LinAlg.BLAS.herk doc""" -```rst -gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) + gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + - beta*y" according to "trans" ('N' or 'T'). The matrix "A" is - a general band matrix of dimension "m" by "size(A,2)" with - "kl" sub-diagonals and "ku" super-diagonals. Returns the - updated "y". -``` +Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + +beta*y" according to "trans" ('N' or 'T'). The matrix "A" is +a general band matrix of dimension "m" by "size(A,2)" with +"kl" sub-diagonals and "ku" super-diagonals. Returns the +updated "y". """ Base.LinAlg.BLAS.gbmv! doc""" -```rst -gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' - or 'T'). The matrix "A" is a general band matrix of dimension - "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- - diagonals. -``` +Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' +or 'T'). The matrix "A" is a general band matrix of dimension +"m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- +diagonals. """ Base.LinAlg.BLAS.gbmv doc""" -```rst -sbmv!(uplo, k, alpha, A, x, beta, y) + sbmv!(uplo, k, alpha, A, x, beta, y) - Update vector "y" as "alpha*A*x + beta*y" where "A" is a a - symmetric band matrix of order "size(A,2)" with "k" super- - diagonals stored in the argument "A". The storage layout for - "A" is described the reference BLAS module, level-2 BLAS at - http://www.netlib.org/lapack/explore-html/. +Update vector "y" as "alpha*A*x + beta*y" where "A" is a a +symmetric band matrix of order "size(A,2)" with "k" super- +diagonals stored in the argument "A". The storage layout for +"A" is described the reference BLAS module, level-2 BLAS at +http://www.netlib.org/lapack/explore-html/. - Returns the updated "y". -``` +Returns the updated "y". """ Base.LinAlg.BLAS.sbmv! doc""" -```rst -sbmv(uplo, k, alpha, A, x) + sbmv(uplo, k, alpha, A, x) - Returns "alpha*A*x" where "A" is a symmetric band matrix of - order "size(A,2)" with "k" super-diagonals stored in the - argument "A". -``` +Returns "alpha*A*x" where "A" is a symmetric band matrix of +order "size(A,2)" with "k" super-diagonals stored in the +argument "A". """ Base.LinAlg.BLAS.sbmv doc""" -```rst -sbmv(uplo, k, A, x) + sbmv(uplo, k, A, x) - Returns "A*x" where "A" is a symmetric band matrix of order - "size(A,2)" with "k" super-diagonals stored in the argument - "A". -``` +Returns "A*x" where "A" is a symmetric band matrix of order +"size(A,2)" with "k" super-diagonals stored in the argument +"A". """ Base.LinAlg.BLAS.sbmv doc""" -```rst -gemm!(tA, tB, alpha, A, B, beta, C) + gemm!(tA, tB, alpha, A, B, beta, C) - Update "C" as "alpha*A*B + beta*C" or the other three variants - according to "tA" (transpose "A") and "tB". Returns the - updated "C". -``` +Update "C" as "alpha*A*B + beta*C" or the other three variants +according to "tA" (transpose "A") and "tB". Returns the +updated "C". """ Base.LinAlg.BLAS.gemm! doc""" -```rst -gemm(tA, tB, alpha, A, B) + gemm(tA, tB, alpha, A, B) - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". -``` +Returns "alpha*A*B" or the other three variants according to +"tA" (transpose "A") and "tB". """ Base.LinAlg.BLAS.gemm doc""" -```rst -gemm(tA, tB, A, B) + gemm(tA, tB, A, B) - Returns "A*B" or the other three variants according to "tA" - (transpose "A") and "tB". -``` +Returns "A*B" or the other three variants according to "tA" +(transpose "A") and "tB". """ Base.LinAlg.BLAS.gemm doc""" -```rst -gemv!(tA, alpha, A, x, beta, y) + gemv!(tA, alpha, A, x, beta, y) - Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + - beta*y" according to "tA" (transpose "A"). Returns the updated - "y". -``` +Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + +beta*y" according to "tA" (transpose "A"). Returns the updated +"y". """ Base.LinAlg.BLAS.gemv! doc""" -```rst -gemv(tA, alpha, A, x) + gemv(tA, alpha, A, x) - Returns "alpha*A*x" or "alpha*A'x" according to "tA" - (transpose "A"). -``` +Returns "alpha*A*x" or "alpha*A'x" according to "tA" +(transpose "A"). """ Base.LinAlg.BLAS.gemv doc""" -```rst -gemv(tA, A, x) + gemv(tA, A, x) - Returns "A*x" or "A'x" according to "tA" (transpose "A"). -``` +Returns "A*x" or "A'x" according to "tA" (transpose "A"). """ Base.LinAlg.BLAS.gemv doc""" -```rst -symm!(side, ul, alpha, A, B, beta, C) + symm!(side, ul, alpha, A, B, beta, C) - Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" - according to "side". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. Returns the updated "C". -``` +Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" +according to "side". "A" is assumed to be symmetric. Only the +"ul" triangle of "A" is used. Returns the updated "C". """ Base.LinAlg.BLAS.symm! doc""" -```rst -symm(side, ul, alpha, A, B) + symm(side, ul, alpha, A, B) - Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" - is assumed to be symmetric. Only the "ul" triangle of "A" is - used. -``` +Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" +is assumed to be symmetric. Only the "ul" triangle of "A" is +used. """ Base.LinAlg.BLAS.symm doc""" -```rst -symm(side, ul, A, B) + symm(side, ul, A, B) - Returns "A*B" or "B*A" according to "side". "A" is assumed - to be symmetric. Only the "ul" triangle of "A" is used. -``` +Returns "A*B" or "B*A" according to "side". "A" is assumed +to be symmetric. Only the "ul" triangle of "A" is used. """ Base.LinAlg.BLAS.symm doc""" -```rst -symm(tA, tB, alpha, A, B) + symm(tA, tB, alpha, A, B) - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". -``` +Returns "alpha*A*B" or the other three variants according to +"tA" (transpose "A") and "tB". """ Base.LinAlg.BLAS.symm doc""" -```rst -symv!(ul, alpha, A, x, beta, y) + symv!(ul, alpha, A, x, beta, y) - Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed - to be symmetric. Only the "ul" triangle of "A" is used. - Returns the updated "y". -``` +Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed +to be symmetric. Only the "ul" triangle of "A" is used. +Returns the updated "y". """ Base.LinAlg.BLAS.symv! doc""" -```rst -symv(ul, alpha, A, x) + symv(ul, alpha, A, x) - Returns "alpha*A*x". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. -``` +Returns "alpha*A*x". "A" is assumed to be symmetric. Only the +"ul" triangle of "A" is used. """ Base.LinAlg.BLAS.symv doc""" -```rst -symv(ul, A, x) + symv(ul, A, x) - Returns "A*x". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. -``` +Returns "A*x". "A" is assumed to be symmetric. Only the +"ul" triangle of "A" is used. """ Base.LinAlg.BLAS.symv doc""" -```rst -trmm!(side, ul, tA, dA, alpha, A, B) + trmm!(side, ul, tA, dA, alpha, A, B) - Update "B" as "alpha*A*B" or one of the other three variants - determined by "side" (A on left or right) and "tA" (transpose - A). Only the "ul" triangle of "A" is used. "dA" indicates if - "A" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated "B". -``` +Update "B" as "alpha*A*B" or one of the other three variants +determined by "side" (A on left or right) and "tA" (transpose +A). Only the "ul" triangle of "A" is used. "dA" indicates if +"A" is unit-triangular (the diagonal is assumed to be all ones). +Returns the updated "B". """ Base.LinAlg.BLAS.trmm! doc""" -```rst -trmm(side, ul, tA, dA, alpha, A, B) + trmm(side, ul, tA, dA, alpha, A, B) - Returns "alpha*A*B" or one of the other three variants determined - by "side" (A on left or right) and "tA" (transpose A). Only the - "ul" triangle of "A" is used. "dA" indicates if "A" is - unit-triangular (the diagonal is assumed to be all ones). -``` +Returns "alpha*A*B" or one of the other three variants determined +by "side" (A on left or right) and "tA" (transpose A). Only the +"ul" triangle of "A" is used. "dA" indicates if "A" is +unit-triangular (the diagonal is assumed to be all ones). """ Base.LinAlg.BLAS.trmm doc""" -```rst -trsm!(side, ul, tA, dA, alpha, A, B) + trsm!(side, ul, tA, dA, alpha, A, B) - Overwrite "B" with the solution to "A*X = alpha*B" or one of - the other three variants determined by "side" (A on left or right - of "X") and "tA" (transpose A). Only the "ul" triangle of - "A" is used. "dA" indicates if "A" is unit-triangular (the - diagonal is assumed to be all ones). Returns the updated "B". -``` +Overwrite "B" with the solution to "A*X = alpha*B" or one of +the other three variants determined by "side" (A on left or right +of "X") and "tA" (transpose A). Only the "ul" triangle of +"A" is used. "dA" indicates if "A" is unit-triangular (the +diagonal is assumed to be all ones). Returns the updated "B". """ Base.LinAlg.BLAS.trsm! doc""" -```rst -trsm(side, ul, tA, dA, alpha, A, B) + trsm(side, ul, tA, dA, alpha, A, B) - Returns the solution to "A*X = alpha*B" or one of the other three - variants determined by "side" (A on left or right of "X") and - "tA" (transpose A). Only the "ul" triangle of "A" is used. - "dA" indicates if "A" is unit-triangular (the diagonal is - assumed to be all ones). -``` +Returns the solution to "A*X = alpha*B" or one of the other three +variants determined by "side" (A on left or right of "X") and +"tA" (transpose A). Only the "ul" triangle of "A" is used. +"dA" indicates if "A" is unit-triangular (the diagonal is +assumed to be all ones). """ Base.LinAlg.BLAS.trsm doc""" -```rst -trmv!(side, ul, tA, dA, alpha, A, b) + trmv!(side, ul, tA, dA, alpha, A, b) - Update "b" as "alpha*A*b" or one of the other three variants - determined by "side" (A on left or right) and "tA" (transpose - A). Only the "ul" triangle of "A" is used. "dA" indicates if - "A" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated "b". -``` +Update "b" as "alpha*A*b" or one of the other three variants +determined by "side" (A on left or right) and "tA" (transpose +A). Only the "ul" triangle of "A" is used. "dA" indicates if +"A" is unit-triangular (the diagonal is assumed to be all ones). +Returns the updated "b". """ Base.LinAlg.BLAS.trmv! doc""" -```rst -trmv(side, ul, tA, dA, alpha, A, b) + trmv(side, ul, tA, dA, alpha, A, b) - Returns "alpha*A*b" or one of the other three variants determined - by "side" (A on left or right) and "tA" (transpose A). Only the - "ul" triangle of "A" is used. "dA" indicates if "A" is - unit-triangular (the diagonal is assumed to be all ones). -``` +Returns "alpha*A*b" or one of the other three variants determined +by "side" (A on left or right) and "tA" (transpose A). Only the +"ul" triangle of "A" is used. "dA" indicates if "A" is +unit-triangular (the diagonal is assumed to be all ones). """ Base.LinAlg.BLAS.trmv doc""" -```rst -trsv!(ul, tA, dA, A, b) + trsv!(ul, tA, dA, A, b) - Overwrite "b" with the solution to "A*x = b" or one of the - other two variants determined by "tA" (transpose A) and "ul" - (triangle of "A" used). "dA" indicates if "A" is unit- - triangular (the diagonal is assumed to be all ones). Returns the - updated "b". -``` +Overwrite "b" with the solution to "A*x = b" or one of the +other two variants determined by "tA" (transpose A) and "ul" +(triangle of "A" used). "dA" indicates if "A" is unit- +triangular (the diagonal is assumed to be all ones). Returns the +updated "b". """ Base.LinAlg.BLAS.trsv! doc""" -```rst -trsv(ul, tA, dA, A, b) + trsv(ul, tA, dA, A, b) - Returns the solution to "A*x = b" or one of the other two - variants determined by "tA" (transpose A) and "ul" (triangle of - "A" is used.) "dA" indicates if "A" is unit-triangular (the - diagonal is assumed to be all ones). -``` +Returns the solution to "A*x = b" or one of the other two +variants determined by "tA" (transpose A) and "ul" (triangle of +"A" is used.) "dA" indicates if "A" is unit-triangular (the +diagonal is assumed to be all ones). """ Base.LinAlg.BLAS.trsv doc""" -```rst -blas_set_num_threads(n) + blas_set_num_threads(n) - Set the number of threads the BLAS library should use. -``` +Set the number of threads the BLAS library should use. """ Base.LinAlg.BLAS.blas_set_num_threads doc""" -```rst -I + I - An object of type "UniformScaling", representing an identity - matrix of any size. -``` +An object of type "UniformScaling", representing an identity +matrix of any size. """ Base.LinAlg.BLAS.I doc""" -```rst --(x) + -(x) - Unary minus operator. -``` +Unary minus operator. """ - doc""" -```rst -+(x, y...) + +(x, y...) - Addition operator. "x+y+z+..." calls this function with all - arguments, i.e. "+(x, y, z, ...)". -``` +Addition operator. "x+y+z+..." calls this function with all +arguments, i.e. "+(x, y, z, ...)". """ + doc""" -```rst --(x, y) + -(x, y) - Subtraction operator. -``` +Subtraction operator. """ - doc""" -```rst -*(x, y...) + *(x, y...) - Multiplication operator. "x*y*z*..." calls this function with all - arguments, i.e. "*(x, y, z, ...)". -``` +Multiplication operator. "x*y*z*..." calls this function with all +arguments, i.e. "*(x, y, z, ...)". """ Base.(:(*)) doc""" -```rst -/(x, y) + /(x, y) - Right division operator: multiplication of "x" by the inverse of - "y" on the right. Gives floating-point results for integer - arguments. -``` +Right division operator: multiplication of "x" by the inverse of +"y" on the right. Gives floating-point results for integer +arguments. """ Base.(:(/)) doc""" -```rst -\(x, y) + \(x, y) - Left division operator: multiplication of "y" by the inverse of - "x" on the left. Gives floating-point results for integer - arguments. -``` +Left division operator: multiplication of "y" by the inverse of +"x" on the left. Gives floating-point results for integer +arguments. """ Base.(:(\)) doc""" -```rst -^(x, y) + ^(x, y) - Exponentiation operator. -``` +Exponentiation operator. """ Base.(:(^)) doc""" -```rst -.+(x, y) + .+(x, y) - Element-wise addition operator. -``` +Element-wise addition operator. """ Base.(:(.+)) doc""" -```rst -.-(x, y) + .-(x, y) - Element-wise subtraction operator. -``` +Element-wise subtraction operator. """ Base.(:(.-)) doc""" -```rst -.*(x, y) + .*(x, y) - Element-wise multiplication operator. -``` +Element-wise multiplication operator. """ Base.(:(.*)) doc""" -```rst -./(x, y) + ./(x, y) - Element-wise right division operator. -``` +Element-wise right division operator. """ Base.(:(./)) doc""" -```rst -.\(x, y) + .\(x, y) - Element-wise left division operator. -``` +Element-wise left division operator. """ Base.(:(.\)) doc""" -```rst -.^(x, y) + .^(x, y) - Element-wise exponentiation operator. -``` +Element-wise exponentiation operator. """ Base.(:(.^)) doc""" -```rst -fma(x, y, z) + fma(x, y, z) - Computes "x*y+z" without rounding the intermediate result - "x*y". On some systems this is significantly more expensive than - "x*y+z". "fma" is used to improve accuracy in certain - algorithms. See "muladd". -``` +Computes "x*y+z" without rounding the intermediate result +"x*y". On some systems this is significantly more expensive than +"x*y+z". "fma" is used to improve accuracy in certain +algorithms. See "muladd". """ fma doc""" -```rst -muladd(x, y, z) + muladd(x, y, z) - Combined multiply-add, computes "x*y+z" in an efficient manner. - This may on some systems be equivalent to "x*y+z", or to - "fma(x,y,z)". "muladd" is used to improve performance. See - "fma". -``` +Combined multiply-add, computes "x*y+z" in an efficient manner. +This may on some systems be equivalent to "x*y+z", or to +"fma(x,y,z)". "muladd" is used to improve performance. See +"fma". """ muladd doc""" -```rst -div(x, y) + div(x, y) ÷(x, y) - The quotient from Euclidean division. Computes "x/y", truncated - to an integer. -``` +The quotient from Euclidean division. Computes "x/y", truncated +to an integer. """ div doc""" -```rst -fld(x, y) + fld(x, y) - Largest integer less than or equal to "x/y". -``` +Largest integer less than or equal to "x/y". """ fld doc""" -```rst -cld(x, y) + cld(x, y) - Smallest integer larger than or equal to "x/y". -``` +Smallest integer larger than or equal to "x/y". """ cld doc""" -```rst -mod(x, y) + mod(x, y) - Modulus after division, returning in the range [0,``y``), if "y" - is positive, or ("y",0] if "y" is negative. -``` +Modulus after division, returning in the range [0,``y``), if "y" +is positive, or ("y",0] if "y" is negative. """ mod doc""" -```rst -mod2pi(x) + mod2pi(x) - Modulus after division by 2pi, returning in the range [0,2pi). +Modulus after division by 2pi, returning in the range [0,2pi). - This function computes a floating point representation of the - modulus after division by numerically exact 2pi, and is therefore - not exactly the same as mod(x,2pi), which would compute the modulus - of x relative to division by the floating-point number 2pi. -``` +This function computes a floating point representation of the +modulus after division by numerically exact 2pi, and is therefore +not exactly the same as mod(x,2pi), which would compute the modulus +of x relative to division by the floating-point number 2pi. """ mod2pi doc""" -```rst -rem(x, y) + rem(x, y) %(x, y) - Remainder from Euclidean division, returning a value of the same - sign as``x``, and smaller in magnitude than "y". This value is - always exact. -``` +Remainder from Euclidean division, returning a value of the same +sign as``x``, and smaller in magnitude than "y". This value is +always exact. """ rem doc""" -```rst -divrem(x, y) + divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to - "(x÷y, x%y)". -``` +The quotient and remainder from Euclidean division. Equivalent to +"(x÷y, x%y)". """ divrem doc""" -```rst -fldmod(x, y) + fldmod(x, y) - The floored quotient and modulus after division. Equivalent to - "(fld(x,y), mod(x,y))". -``` +The floored quotient and modulus after division. Equivalent to +"(fld(x,y), mod(x,y))". """ fldmod doc""" -```rst -mod1(x, m) + mod1(x, m) - Modulus after division, returning in the range (0,m] -``` +Modulus after division, returning in the range (0,m] """ mod1 doc""" -```rst -rem1(x, m) + rem1(x, m) - Remainder after division, returning in the range (0,m] -``` +Remainder after division, returning in the range (0,m] """ rem1 doc""" -```rst -//(num, den) + //(num, den) - Divide two integers or rational numbers, giving a "Rational" - result. -``` +Divide two integers or rational numbers, giving a "Rational" +result. """ Base.(:(//)) doc""" -```rst -rationalize([Type=Int], x; tol=eps(x)) + rationalize([Type=Int], x; tol=eps(x)) - Approximate floating point number "x" as a Rational number with - components of the given integer type. The result will differ from - "x" by no more than "tol". -``` +Approximate floating point number "x" as a Rational number with +components of the given integer type. The result will differ from +"x" by no more than "tol". """ rationalize doc""" -```rst -num(x) + num(x) - Numerator of the rational representation of "x" -``` +Numerator of the rational representation of "x" """ num doc""" -```rst -den(x) + den(x) - Denominator of the rational representation of "x" -``` +Denominator of the rational representation of "x" """ den doc""" -```rst -<<(x, n) + <<(x, n) - Left bit shift operator. -``` +Left bit shift operator. """ Base.(:(<<)) doc""" -```rst ->>(x, n) + >>(x, n) - Right bit shift operator, preserving the sign of "x". -``` +Right bit shift operator, preserving the sign of "x". """ Base.(:(>>)) doc""" -```rst ->>>(x, n) + >>>(x, n) - Unsigned right bit shift operator. -``` +Unsigned right bit shift operator. """ Base.(:(>>>)) doc""" -```rst -:(start[, step], stop) + :(start[, step], stop) - Range operator. "a:b" constructs a range from "a" to "b" with - a step size of 1, and "a:s:b" is similar but uses a step size of - "s". These syntaxes call the function "colon". The colon is - also used in indexing to select whole dimensions. -``` +Range operator. "a:b" constructs a range from "a" to "b" with +a step size of 1, and "a:s:b" is similar but uses a step size of +"s". These syntaxes call the function "colon". The colon is +also used in indexing to select whole dimensions. """ Base.(:(:)) doc""" -```rst -colon(start[, step], stop) + colon(start[, step], stop) - Called by ":" syntax for constructing ranges. -``` +Called by ":" syntax for constructing ranges. """ colon doc""" -```rst -range(start[, step], length) + range(start[, step], length) - Construct a range by length, given a starting value and optional - step (defaults to 1). -``` +Construct a range by length, given a starting value and optional +step (defaults to 1). """ range doc""" -```rst -==(x, y) + ==(x, y) - Generic equality operator, giving a single "Bool" result. Falls - back to "===". Should be implemented for all types with a notion - of equality, based on the abstract value that an instance - represents. For example, all numeric types are compared by numeric - value, ignoring type. Strings are compared as sequences of - characters, ignoring encoding. +Generic equality operator, giving a single "Bool" result. Falls +back to "===". Should be implemented for all types with a notion +of equality, based on the abstract value that an instance +represents. For example, all numeric types are compared by numeric +value, ignoring type. Strings are compared as sequences of +characters, ignoring encoding. - Follows IEEE semantics for floating-point numbers. +Follows IEEE semantics for floating-point numbers. - Collections should generally implement "==" by calling "==" - recursively on all contents. +Collections should generally implement "==" by calling "==" +recursively on all contents. - New numeric types should implement this function for two arguments - of the new type, and handle comparison to other types via promotion - rules where possible. -``` +New numeric types should implement this function for two arguments +of the new type, and handle comparison to other types via promotion +rules where possible. """ Base.(:(==)) doc""" -```rst -!=(x, y) + !=(x, y) ≠(x, y) - Not-equals comparison operator. Always gives the opposite answer as - "==". New types should generally not implement this, and rely on - the fallback definition "!=(x,y) = !(x==y)" instead. -``` +Not-equals comparison operator. Always gives the opposite answer as +"==". New types should generally not implement this, and rely on +the fallback definition "!=(x,y) = !(x==y)" instead. """ Base.(:(!=)) doc""" -```rst -===(x, y) + ===(x, y) ≡(x, y) - See the "is()" operator -``` +See the "is()" operator """ Base.(:(===)) doc""" -```rst -!==(x, y) + !==(x, y) ≢(x, y) - Equivalent to "!is(x, y)" -``` +Equivalent to "!is(x, y)" """ Base.(:(!==)) doc""" -```rst -<(x, y) + <(x, y) - Less-than comparison operator. New numeric types should implement - this function for two arguments of the new type. Because of the - behavior of floating-point NaN values, "<" implements a partial - order. Types with a canonical partial order should implement "<", - and types with a canonical total order should implement "isless". -``` +Less-than comparison operator. New numeric types should implement +this function for two arguments of the new type. Because of the +behavior of floating-point NaN values, "<" implements a partial +order. Types with a canonical partial order should implement "<", +and types with a canonical total order should implement "isless". """ Base.(:(<)) doc""" -```rst -<=(x, y) + <=(x, y) ≤(x, y) - Less-than-or-equals comparison operator. -``` +Less-than-or-equals comparison operator. """ Base.(:(<=)) doc""" -```rst ->(x, y) + >(x, y) - Greater-than comparison operator. Generally, new types should - implement "<" instead of this function, and rely on the fallback - definition ">(x,y) = y(x,y) = y)) doc""" -```rst ->=(x, y) + >=(x, y) ≥(x, y) - Greater-than-or-equals comparison operator. -``` +Greater-than-or-equals comparison operator. """ Base.(:(>=)) doc""" -```rst -.==(x, y) + .==(x, y) - Element-wise equality comparison operator. -``` +Element-wise equality comparison operator. """ Base.(:(.==)) doc""" -```rst -.!=(x, y) + .!=(x, y) .≠(x, y) - Element-wise not-equals comparison operator. -``` +Element-wise not-equals comparison operator. """ Base.(:(.!=)) doc""" -```rst -.<(x, y) + .<(x, y) - Element-wise less-than comparison operator. -``` +Element-wise less-than comparison operator. """ Base.(:(.<)) doc""" -```rst -.<=(x, y) + .<=(x, y) .≤(x, y) - Element-wise less-than-or-equals comparison operator. -``` +Element-wise less-than-or-equals comparison operator. """ Base.(:(.<=)) doc""" -```rst -.>(x, y) + .>(x, y) - Element-wise greater-than comparison operator. -``` +Element-wise greater-than comparison operator. """ Base.(:(.>)) doc""" -```rst -.>=(x, y) + .>=(x, y) .≥(x, y) - Element-wise greater-than-or-equals comparison operator. -``` +Element-wise greater-than-or-equals comparison operator. """ Base.(:(.>=)) doc""" -```rst -cmp(x, y) + cmp(x, y) - Return -1, 0, or 1 depending on whether "x" is less than, equal - to, or greater than "y", respectively. Uses the total order - implemented by "isless". For floating-point numbers, uses "<" - but throws an error for unordered arguments. -``` +Return -1, 0, or 1 depending on whether "x" is less than, equal +to, or greater than "y", respectively. Uses the total order +implemented by "isless". For floating-point numbers, uses "<" +but throws an error for unordered arguments. """ cmp doc""" -```rst -~(x) + ~(x) - Bitwise not -``` +Bitwise not """ ~ doc""" -```rst -&(x, y) + &(x, y) - Bitwise and -``` +Bitwise and """ & doc""" -```rst -|(x, y) + |(x, y) - Bitwise or -``` +Bitwise or """ Base.(:(|)) doc""" -```rst -\$(x, y) + \$(x, y) - Bitwise exclusive or -``` +Bitwise exclusive or """ $ doc""" -```rst -!(x) + !(x) - Boolean not -``` +Boolean not """ ! doc""" -```rst -A_ldiv_Bc(a, b) + A_ldiv_Bc(a, b) - Matrix operator A \ B^H -``` +Matrix operator A \ B^H """ A_ldiv_Bc doc""" -```rst -A_ldiv_Bt(a, b) + A_ldiv_Bt(a, b) - Matrix operator A \ B^T -``` +Matrix operator A \ B^T """ A_ldiv_Bt doc""" -```rst -A_mul_B!(Y, A, B) -> Y + A_mul_B!(Y, A, B) -> Y - Calculates the matrix-matrix or matrix-vector product *A B* and - stores the result in *Y*, overwriting the existing value of *Y*. +Calculates the matrix-matrix or matrix-vector product *A B* and +stores the result in *Y*, overwriting the existing value of *Y*. - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 -``` + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 """ A_mul_B! doc""" -```rst -A_mul_Bc(...) + A_mul_Bc(...) - Matrix operator A B^H -``` +Matrix operator A B^H """ A_mul_Bc doc""" -```rst -A_mul_Bt(...) + A_mul_Bt(...) - Matrix operator A B^T -``` +Matrix operator A B^T """ A_mul_Bt doc""" -```rst -A_rdiv_Bc(...) + A_rdiv_Bc(...) - Matrix operator A / B^H -``` +Matrix operator A / B^H """ A_rdiv_Bc doc""" -```rst -A_rdiv_Bt(a, b) + A_rdiv_Bt(a, b) - Matrix operator A / B^T -``` +Matrix operator A / B^T """ A_rdiv_Bt doc""" -```rst -Ac_ldiv_B(...) + Ac_ldiv_B(...) - Matrix operator A^H \ B -``` +Matrix operator A^H \ B """ Ac_ldiv_B doc""" -```rst -Ac_ldiv_Bc(...) + Ac_ldiv_Bc(...) - Matrix operator A^H \ B^H -``` +Matrix operator A^H \ B^H """ Ac_ldiv_Bc doc""" -```rst -Ac_mul_B(...) + Ac_mul_B(...) - Matrix operator A^H B -``` +Matrix operator A^H B """ Ac_mul_B doc""" -```rst -Ac_mul_Bc(...) + Ac_mul_Bc(...) - Matrix operator A^H B^H -``` +Matrix operator A^H B^H """ Ac_mul_Bc doc""" -```rst -Ac_rdiv_B(a, b) + Ac_rdiv_B(a, b) - Matrix operator A^H / B -``` +Matrix operator A^H / B """ Ac_rdiv_B doc""" -```rst -Ac_rdiv_Bc(a, b) + Ac_rdiv_Bc(a, b) - Matrix operator A^H / B^H -``` +Matrix operator A^H / B^H """ Ac_rdiv_Bc doc""" -```rst -At_ldiv_B(...) + At_ldiv_B(...) - Matrix operator A^T \ B -``` +Matrix operator A^T \ B """ At_ldiv_B doc""" -```rst -At_ldiv_Bt(...) + At_ldiv_Bt(...) - Matrix operator A^T \ B^T -``` +Matrix operator A^T \ B^T """ At_ldiv_Bt doc""" -```rst -At_mul_B(...) + At_mul_B(...) - Matrix operator A^T B -``` +Matrix operator A^T B """ At_mul_B doc""" -```rst -At_mul_Bt(...) + At_mul_Bt(...) - Matrix operator A^T B^T -``` +Matrix operator A^T B^T """ At_mul_Bt doc""" -```rst -At_rdiv_B(a, b) + At_rdiv_B(a, b) - Matrix operator A^T / B -``` +Matrix operator A^T / B """ At_rdiv_B doc""" -```rst -At_rdiv_Bt(a, b) + At_rdiv_Bt(a, b) - Matrix operator A^T / B^T -``` +Matrix operator A^T / B^T """ At_rdiv_Bt doc""" -```rst -isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - Inexact equality comparison - behaves slightly different depending - on types of input args: +Inexact equality comparison - behaves slightly different depending +on types of input args: - * For "FloatingPoint" numbers, "isapprox" returns "true" if - "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". +* For "FloatingPoint" numbers, "isapprox" returns "true" if + "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". - * For "Integer" and "Rational" numbers, "isapprox" returns - "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. - If one of "x" and "y" is "FloatingPoint", the other is - promoted, and the method above is called instead. +* For "Integer" and "Rational" numbers, "isapprox" returns + "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. + If one of "x" and "y" is "FloatingPoint", the other is + promoted, and the method above is called instead. - * For "Complex" numbers, the distance in the complex plane is - compared, using the same criterion as above. +* For "Complex" numbers, the distance in the complex plane is + compared, using the same criterion as above. - For default tolerance arguments, "maxeps = max(eps(abs(x)), - eps(abs(y)))". -``` +For default tolerance arguments, "maxeps = max(eps(abs(x)), +eps(abs(y)))". """ isapprox doc""" -```rst -sin(x) + sin(x) - Compute sine of "x", where "x" is in radians -``` +Compute sine of "x", where "x" is in radians """ sin doc""" -```rst -cos(x) + cos(x) - Compute cosine of "x", where "x" is in radians -``` +Compute cosine of "x", where "x" is in radians """ cos doc""" -```rst -tan(x) + tan(x) - Compute tangent of "x", where "x" is in radians -``` +Compute tangent of "x", where "x" is in radians """ tan doc""" -```rst -sind(x) + sind(x) - Compute sine of "x", where "x" is in degrees -``` +Compute sine of "x", where "x" is in degrees """ sind doc""" -```rst -cosd(x) + cosd(x) - Compute cosine of "x", where "x" is in degrees -``` +Compute cosine of "x", where "x" is in degrees """ cosd doc""" -```rst -tand(x) + tand(x) - Compute tangent of "x", where "x" is in degrees -``` +Compute tangent of "x", where "x" is in degrees """ tand doc""" -```rst -sinpi(x) + sinpi(x) - Compute \sin(\pi x) more accurately than "sin(pi*x)", - especially for large "x". -``` +Compute \sin(\pi x) more accurately than "sin(pi*x)", +especially for large "x". """ sinpi doc""" -```rst -cospi(x) + cospi(x) - Compute \cos(\pi x) more accurately than "cos(pi*x)", - especially for large "x". -``` +Compute \cos(\pi x) more accurately than "cos(pi*x)", +especially for large "x". """ cospi doc""" -```rst -sinh(x) + sinh(x) - Compute hyperbolic sine of "x" -``` +Compute hyperbolic sine of "x" """ sinh doc""" -```rst -cosh(x) + cosh(x) - Compute hyperbolic cosine of "x" -``` +Compute hyperbolic cosine of "x" """ cosh doc""" -```rst -tanh(x) + tanh(x) - Compute hyperbolic tangent of "x" -``` +Compute hyperbolic tangent of "x" """ tanh doc""" -```rst -asin(x) + asin(x) - Compute the inverse sine of "x", where the output is in radians -``` +Compute the inverse sine of "x", where the output is in radians """ asin doc""" -```rst -acos(x) + acos(x) - Compute the inverse cosine of "x", where the output is in radians -``` +Compute the inverse cosine of "x", where the output is in radians """ acos doc""" -```rst -atan(x) + atan(x) - Compute the inverse tangent of "x", where the output is in - radians -``` +Compute the inverse tangent of "x", where the output is in +radians """ atan doc""" -```rst -atan2(y, x) + atan2(y, x) - Compute the inverse tangent of "y/x", using the signs of both - "x" and "y" to determine the quadrant of the return value. -``` +Compute the inverse tangent of "y/x", using the signs of both +"x" and "y" to determine the quadrant of the return value. """ atan2 doc""" -```rst -asind(x) + asind(x) - Compute the inverse sine of "x", where the output is in degrees -``` +Compute the inverse sine of "x", where the output is in degrees """ asind doc""" -```rst -acosd(x) + acosd(x) - Compute the inverse cosine of "x", where the output is in degrees -``` +Compute the inverse cosine of "x", where the output is in degrees """ acosd doc""" -```rst -atand(x) + atand(x) - Compute the inverse tangent of "x", where the output is in - degrees -``` +Compute the inverse tangent of "x", where the output is in +degrees """ atand doc""" -```rst -sec(x) + sec(x) - Compute the secant of "x", where "x" is in radians -``` +Compute the secant of "x", where "x" is in radians """ sec doc""" -```rst -csc(x) + csc(x) - Compute the cosecant of "x", where "x" is in radians -``` +Compute the cosecant of "x", where "x" is in radians """ csc doc""" -```rst -cot(x) + cot(x) - Compute the cotangent of "x", where "x" is in radians -``` +Compute the cotangent of "x", where "x" is in radians """ cot doc""" -```rst -secd(x) + secd(x) - Compute the secant of "x", where "x" is in degrees -``` +Compute the secant of "x", where "x" is in degrees """ secd doc""" -```rst -cscd(x) + cscd(x) - Compute the cosecant of "x", where "x" is in degrees -``` +Compute the cosecant of "x", where "x" is in degrees """ cscd doc""" -```rst -cotd(x) + cotd(x) - Compute the cotangent of "x", where "x" is in degrees -``` +Compute the cotangent of "x", where "x" is in degrees """ cotd doc""" -```rst -asec(x) + asec(x) - Compute the inverse secant of "x", where the output is in radians -``` +Compute the inverse secant of "x", where the output is in radians """ asec doc""" -```rst -acsc(x) + acsc(x) - Compute the inverse cosecant of "x", where the output is in - radians -``` +Compute the inverse cosecant of "x", where the output is in +radians """ acsc doc""" -```rst -acot(x) + acot(x) - Compute the inverse cotangent of "x", where the output is in - radians -``` +Compute the inverse cotangent of "x", where the output is in +radians """ acot doc""" -```rst -asecd(x) + asecd(x) - Compute the inverse secant of "x", where the output is in degrees -``` +Compute the inverse secant of "x", where the output is in degrees """ asecd doc""" -```rst -acscd(x) + acscd(x) - Compute the inverse cosecant of "x", where the output is in - degrees -``` +Compute the inverse cosecant of "x", where the output is in +degrees """ acscd doc""" -```rst -acotd(x) + acotd(x) - Compute the inverse cotangent of "x", where the output is in - degrees -``` +Compute the inverse cotangent of "x", where the output is in +degrees """ acotd doc""" -```rst -sech(x) + sech(x) - Compute the hyperbolic secant of "x" -``` +Compute the hyperbolic secant of "x" """ sech doc""" -```rst -csch(x) + csch(x) - Compute the hyperbolic cosecant of "x" -``` +Compute the hyperbolic cosecant of "x" """ csch doc""" -```rst -coth(x) + coth(x) - Compute the hyperbolic cotangent of "x" -``` +Compute the hyperbolic cotangent of "x" """ coth doc""" -```rst -asinh(x) + asinh(x) - Compute the inverse hyperbolic sine of "x" -``` +Compute the inverse hyperbolic sine of "x" """ asinh doc""" -```rst -acosh(x) + acosh(x) - Compute the inverse hyperbolic cosine of "x" -``` +Compute the inverse hyperbolic cosine of "x" """ acosh doc""" -```rst -atanh(x) + atanh(x) - Compute the inverse hyperbolic tangent of "x" -``` +Compute the inverse hyperbolic tangent of "x" """ atanh doc""" -```rst -asech(x) + asech(x) - Compute the inverse hyperbolic secant of "x" -``` +Compute the inverse hyperbolic secant of "x" """ asech doc""" -```rst -acsch(x) + acsch(x) - Compute the inverse hyperbolic cosecant of "x" -``` +Compute the inverse hyperbolic cosecant of "x" """ acsch doc""" -```rst -acoth(x) + acoth(x) - Compute the inverse hyperbolic cotangent of "x" -``` +Compute the inverse hyperbolic cotangent of "x" """ acoth doc""" -```rst -sinc(x) + sinc(x) - Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. -``` +Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. """ sinc doc""" -```rst -cosc(x) + cosc(x) - Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq - 0, and 0 if x = 0. This is the derivative of "sinc(x)". -``` +Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq +0, and 0 if x = 0. This is the derivative of "sinc(x)". """ cosc doc""" -```rst -deg2rad(x) + deg2rad(x) - Convert "x" from degrees to radians -``` +Convert "x" from degrees to radians """ deg2rad doc""" -```rst -rad2deg(x) + rad2deg(x) - Convert "x" from radians to degrees -``` +Convert "x" from radians to degrees """ rad2deg doc""" -```rst -hypot(x, y) + hypot(x, y) - Compute the \sqrt{x^2+y^2} avoiding overflow and underflow -``` +Compute the \sqrt{x^2+y^2} avoiding overflow and underflow """ hypot doc""" -```rst -log(x) + log(x) - Compute the natural logarithm of "x". Throws "DomainError" for - negative "Real" arguments. Use complex negative arguments to - obtain complex results. +Compute the natural logarithm of "x". Throws "DomainError" for +negative "Real" arguments. Use complex negative arguments to +obtain complex results. - There is an experimental variant in the "Base.Math.JuliaLibm" - module, which is typically faster and more accurate. -``` +There is an experimental variant in the "Base.Math.JuliaLibm" +module, which is typically faster and more accurate. """ log doc""" -```rst -log(b, x) + log(b, x) - Compute the base "b" logarithm of "x". Throws "DomainError" - for negative "Real" arguments. -``` +Compute the base "b" logarithm of "x". Throws "DomainError" +for negative "Real" arguments. """ log doc""" -```rst -log2(x) + log2(x) - Compute the logarithm of "x" to base 2. Throws "DomainError" - for negative "Real" arguments. -``` +Compute the logarithm of "x" to base 2. Throws "DomainError" +for negative "Real" arguments. """ log2 doc""" -```rst -log10(x) + log10(x) - Compute the logarithm of "x" to base 10. Throws "DomainError" - for negative "Real" arguments. -``` +Compute the logarithm of "x" to base 10. Throws "DomainError" +for negative "Real" arguments. """ log10 doc""" -```rst -log1p(x) + log1p(x) - Accurate natural logarithm of "1+x". Throws "DomainError" for - "Real" arguments less than -1. +Accurate natural logarithm of "1+x". Throws "DomainError" for +"Real" arguments less than -1. - There is an experimental variant in the "Base.Math.JuliaLibm" - module, which is typically faster and more accurate. -``` +There is an experimental variant in the "Base.Math.JuliaLibm" +module, which is typically faster and more accurate. """ log1p doc""" -```rst -frexp(val) + frexp(val) - Return "(x,exp)" such that "x" has a magnitude in the interval - "[1/2, 1)" or 0, and val = x \times 2^{exp}. -``` +Return "(x,exp)" such that "x" has a magnitude in the interval +"[1/2, 1)" or 0, and val = x \times 2^{exp}. """ frexp doc""" -```rst -exp(x) + exp(x) - Compute e^x -``` +Compute e^x """ exp doc""" -```rst -exp2(x) + exp2(x) - Compute 2^x -``` +Compute 2^x """ exp2 doc""" -```rst -exp10(x) + exp10(x) - Compute 10^x -``` +Compute 10^x """ exp10 doc""" -```rst -ldexp(x, n) + ldexp(x, n) - Compute x \times 2^n -``` +Compute x \times 2^n """ ldexp doc""" -```rst -modf(x) + modf(x) - Return a tuple (fpart,ipart) of the fractional and integral parts - of a number. Both parts have the same sign as the argument. -``` +Return a tuple (fpart,ipart) of the fractional and integral parts +of a number. Both parts have the same sign as the argument. """ modf doc""" -```rst -expm1(x) + expm1(x) - Accurately compute e^x-1 -``` +Accurately compute e^x-1 """ expm1 doc""" -```rst -round([T], x[, digits[, base]][, r::RoundingMode]) + round([T], x[, digits[, base]][, r::RoundingMode]) - "round(x)" rounds "x" to an integer value according to the - default rounding mode (see "get_rounding()"), returning a value - of the same type as "x". By default ("RoundNearest"), this will - round to the nearest integer, with ties (fractional values of 0.5) - being rounded to the even integer. +"round(x)" rounds "x" to an integer value according to the +default rounding mode (see "get_rounding()"), returning a value +of the same type as "x". By default ("RoundNearest"), this will +round to the nearest integer, with ties (fractional values of 0.5) +being rounded to the even integer. - julia> round(1.7) - 2.0 + julia> round(1.7) + 2.0 - julia> round(1.5) - 2.0 + julia> round(1.5) + 2.0 - julia> round(2.5) - 2.0 + julia> round(2.5) + 2.0 - The optional "RoundingMode" argument will change how the number - gets rounded. +The optional "RoundingMode" argument will change how the number +gets rounded. - "round(T, x, [r::RoundingMode])" converts the result to type - "T", throwing an "InexactError" if the value is not - representable. +"round(T, x, [r::RoundingMode])" converts the result to type +"T", throwing an "InexactError" if the value is not +representable. - "round(x, digits)" rounds to the specified number of digits after - the decimal place (or before if negative). "round(x, digits, - base)" rounds using a base other than 10. +"round(x, digits)" rounds to the specified number of digits after +the decimal place (or before if negative). "round(x, digits, +base)" rounds using a base other than 10. - julia> round(pi, 2) - 3.14 + julia> round(pi, 2) + 3.14 - julia> round(pi, 3, 2) - 3.125 + julia> round(pi, 3, 2) + 3.125 - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the "Float64" value represented by "1.15" is - actually *less* than 1.15, yet will be rounded to 1.2. +Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the "Float64" value represented by "1.15" is + actually *less* than 1.15, yet will be rounded to 1.2. - julia> x = 1.15 - 1.15 + julia> x = 1.15 + 1.15 - julia> @sprintf "%.20f" x - "1.14999999999999991118" + julia> @sprintf "%.20f" x + "1.14999999999999991118" - julia> x < 115//100 - true + julia> x < 115//100 + true - julia> round(x, 1) - 1.2 -``` + julia> round(x, 1) + 1.2 """ round doc""" -```rst -RoundingMode + RoundingMode - A type which controls rounding behavior. Currently supported - rounding modes are: +A type which controls rounding behavior. Currently supported +rounding modes are: - * "RoundNearest" (default) +* "RoundNearest" (default) - * "RoundNearestTiesAway" +* "RoundNearestTiesAway" - * "RoundNearestTiesUp" +* "RoundNearestTiesUp" - * "RoundToZero" +* "RoundToZero" - * "RoundUp" +* "RoundUp" - * "RoundDown" -``` +* "RoundDown" """ RoundingMode doc""" -```rst -RoundNearest + RoundNearest - The default rounding mode. Rounds to the nearest integer, with ties - (fractional values of 0.5) being rounded to the nearest even - integer. -``` +The default rounding mode. Rounds to the nearest integer, with ties +(fractional values of 0.5) being rounded to the nearest even +integer. """ RoundNearest doc""" -```rst -RoundNearestTiesAway + RoundNearestTiesAway - Rounds to nearest integer, with ties rounded away from zero (C/C++ - "round()" behaviour). -``` +Rounds to nearest integer, with ties rounded away from zero (C/C++ +"round()" behaviour). """ RoundNearestTiesAway doc""" -```rst -RoundNearestTiesUp + RoundNearestTiesUp - Rounds to nearest integer, with ties rounded toward positive - infinity (Java/JavaScript "round()" behaviour). -``` +Rounds to nearest integer, with ties rounded toward positive +infinity (Java/JavaScript "round()" behaviour). """ RoundNearestTiesUp doc""" -```rst -RoundToZero + RoundToZero - "round()" using this rounding mode is an alias for "trunc()". -``` +"round()" using this rounding mode is an alias for "trunc()". """ RoundToZero doc""" -```rst -RoundUp + RoundUp - "round()" using this rounding mode is an alias for "ceil()". -``` +"round()" using this rounding mode is an alias for "ceil()". """ RoundUp doc""" -```rst -RoundDown + RoundDown - "round()" using this rounding mode is an alias for "floor()". -``` +"round()" using this rounding mode is an alias for "floor()". """ RoundDown doc""" -```rst -round(z, RoundingModeReal, RoundingModeImaginary) + round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- - valued "z" to "z", breaking ties using the specified - "RoundingMode"s. The first "RoundingMode" is used for rounding - the real components while the second is used for rounding the - imaginary components. -``` +Returns the nearest integral value of the same type as the complex- +valued "z" to "z", breaking ties using the specified +"RoundingMode"s. The first "RoundingMode" is used for rounding +the real components while the second is used for rounding the +imaginary components. """ round doc""" -```rst -ceil([T], x[, digits[, base]]) + ceil([T], x[, digits[, base]]) - "ceil(x)" returns the nearest integral value of the same type as - "x" that is greater than or equal to "x". +"ceil(x)" returns the nearest integral value of the same type as +"x" that is greater than or equal to "x". - "ceil(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. +"ceil(T, x)" converts the result to type "T", throwing an +"InexactError" if the value is not representable. - "digits" and "base" work as for "round()". -``` +"digits" and "base" work as for "round()". """ ceil doc""" -```rst -floor([T], x[, digits[, base]]) + floor([T], x[, digits[, base]]) - "floor(x)" returns the nearest integral value of the same type as - "x" that is less than or equal to "x". +"floor(x)" returns the nearest integral value of the same type as +"x" that is less than or equal to "x". - "floor(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. +"floor(T, x)" converts the result to type "T", throwing an +"InexactError" if the value is not representable. - "digits" and "base" work as for "round()". -``` +"digits" and "base" work as for "round()". """ floor doc""" -```rst -trunc([T], x[, digits[, base]]) + trunc([T], x[, digits[, base]]) - "trunc(x)" returns the nearest integral value of the same type as - "x" whose absolute value is less than or equal to "x". +"trunc(x)" returns the nearest integral value of the same type as +"x" whose absolute value is less than or equal to "x". - "trunc(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. +"trunc(T, x)" converts the result to type "T", throwing an +"InexactError" if the value is not representable. - "digits" and "base" work as for "round()". -``` +"digits" and "base" work as for "round()". """ trunc doc""" -```rst -unsafe_trunc(T, x) + unsafe_trunc(T, x) - "unsafe_trunc(T, x)" returns the nearest integral value of type - "T" whose absolute value is less than or equal to "x". If the - value is not representable by "T", an arbitrary value will be - returned. -``` +"unsafe_trunc(T, x)" returns the nearest integral value of type +"T" whose absolute value is less than or equal to "x". If the +value is not representable by "T", an arbitrary value will be +returned. """ unsafe_trunc doc""" -```rst -signif(x, digits[, base]) + signif(x, digits[, base]) - Rounds (in the sense of "round") "x" so that there are - "digits" significant digits, under a base "base" - representation, default 10. E.g., "signif(123.456, 2)" is - "120.0", and "signif(357.913, 4, 2)" is "352.0". -``` +Rounds (in the sense of "round") "x" so that there are +"digits" significant digits, under a base "base" +representation, default 10. E.g., "signif(123.456, 2)" is +"120.0", and "signif(357.913, 4, 2)" is "352.0". """ signif doc""" -```rst -min(x, y, ...) + min(x, y, ...) - Return the minimum of the arguments. Operates elementwise over - arrays. -``` +Return the minimum of the arguments. Operates elementwise over +arrays. """ min doc""" -```rst -max(x, y, ...) + max(x, y, ...) - Return the maximum of the arguments. Operates elementwise over - arrays. -``` +Return the maximum of the arguments. Operates elementwise over +arrays. """ max doc""" -```rst -minmax(x, y) + minmax(x, y) - Return "(min(x,y), max(x,y))". See also: "extrema()" that - returns "(minimum(x), maximum(x))" -``` +Return "(min(x,y), max(x,y))". See also: "extrema()" that +returns "(minimum(x), maximum(x))" """ minmax doc""" -```rst -clamp(x, lo, hi) + clamp(x, lo, hi) - Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x - > hi", return "hi". Arguments are promoted to a common type. - Operates elementwise over "x" if it is an array. -``` +Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x +> hi", return "hi". Arguments are promoted to a common type. +Operates elementwise over "x" if it is an array. """ clamp doc""" -```rst -abs(x) + abs(x) - Absolute value of "x" -``` +Absolute value of "x" """ abs doc""" -```rst -abs2(x) + abs2(x) - Squared absolute value of "x" -``` +Squared absolute value of "x" """ abs2 doc""" -```rst -copysign(x, y) + copysign(x, y) - Return "x" such that it has the same sign as "y" -``` +Return "x" such that it has the same sign as "y" """ copysign doc""" -```rst -sign(x) + sign(x) - Return "+1" if "x" is positive, "0" if "x == 0", and "-1" - if "x" is negative. -``` +Return "+1" if "x" is positive, "0" if "x == 0", and "-1" +if "x" is negative. """ sign doc""" -```rst -signbit(x) + signbit(x) - Returns "true" if the value of the sign of "x" is negative, - otherwise "false". -``` +Returns "true" if the value of the sign of "x" is negative, +otherwise "false". """ signbit doc""" -```rst -flipsign(x, y) + flipsign(x, y) - Return "x" with its sign flipped if "y" is negative. For - example "abs(x) = flipsign(x,x)". -``` +Return "x" with its sign flipped if "y" is negative. For +example "abs(x) = flipsign(x,x)". """ flipsign doc""" -```rst -sqrt(x) + sqrt(x) - Return \sqrt{x}. Throws "DomainError" for negative "Real" - arguments. Use complex negative arguments instead. The prefix - operator "√" is equivalent to "sqrt". -``` +Return \sqrt{x}. Throws "DomainError" for negative "Real" +arguments. Use complex negative arguments instead. The prefix +operator "√" is equivalent to "sqrt". """ sqrt doc""" -```rst -isqrt(n) + isqrt(n) - Integer square root: the largest integer "m" such that "m*m <= - n". -``` +Integer square root: the largest integer "m" such that "m*m <= +n". """ isqrt doc""" -```rst -cbrt(x) + cbrt(x) - Return x^{1/3}. The prefix operator "∛" is equivalent to - "cbrt". -``` +Return x^{1/3}. The prefix operator "∛" is equivalent to +"cbrt". """ cbrt doc""" -```rst -erf(x) + erf(x) - Compute the error function of "x", defined by - \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex - "x". -``` +Compute the error function of "x", defined by +\frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex +"x". """ erf doc""" -```rst -erfc(x) + erfc(x) - Compute the complementary error function of "x", defined by 1 - - \operatorname{erf}(x). -``` +Compute the complementary error function of "x", defined by 1 - +\operatorname{erf}(x). """ erfc doc""" -```rst -erfcx(x) + erfcx(x) - Compute the scaled complementary error function of "x", defined - by e^{x^2} \operatorname{erfc}(x). Note also that - \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). -``` +Compute the scaled complementary error function of "x", defined +by e^{x^2} \operatorname{erfc}(x). Note also that +\operatorname{erfcx}(-ix) computes the Faddeeva function w(x). """ erfcx doc""" -```rst -erfi(x) + erfi(x) - Compute the imaginary error function of "x", defined by -i - \operatorname{erf}(ix). -``` +Compute the imaginary error function of "x", defined by -i +\operatorname{erf}(ix). """ erfi doc""" -```rst -dawson(x) + dawson(x) - Compute the Dawson function (scaled imaginary error function) of - "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} - \operatorname{erfi}(x). -``` +Compute the Dawson function (scaled imaginary error function) of +"x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} +\operatorname{erfi}(x). """ dawson doc""" -```rst -erfinv(x) + erfinv(x) - Compute the inverse error function of a real "x", defined by - \operatorname{erf}(\operatorname{erfinv}(x)) = x. -``` +Compute the inverse error function of a real "x", defined by +\operatorname{erf}(\operatorname{erfinv}(x)) = x. """ erfinv doc""" -```rst -erfcinv(x) + erfcinv(x) - Compute the inverse error complementary function of a real "x", - defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. -``` +Compute the inverse error complementary function of a real "x", +defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. """ erfcinv doc""" -```rst -real(z) + real(z) - Return the real part of the complex number "z" -``` +Return the real part of the complex number "z" """ real doc""" -```rst -imag(z) + imag(z) - Return the imaginary part of the complex number "z" -``` +Return the imaginary part of the complex number "z" """ imag doc""" -```rst -reim(z) + reim(z) - Return both the real and imaginary parts of the complex number - "z" -``` +Return both the real and imaginary parts of the complex number +"z" """ reim doc""" -```rst -conj(z) + conj(z) - Compute the complex conjugate of a complex number "z" -``` +Compute the complex conjugate of a complex number "z" """ conj doc""" -```rst -angle(z) + angle(z) - Compute the phase angle in radians of a complex number "z" -``` +Compute the phase angle in radians of a complex number "z" """ angle doc""" -```rst -cis(z) + cis(z) - Return \exp(iz). -``` +Return \exp(iz). """ cis doc""" -```rst -binomial(n, k) + binomial(n, k) - Number of ways to choose "k" out of "n" items -``` +Number of ways to choose "k" out of "n" items """ binomial doc""" -```rst -factorial(n) + factorial(n) - Factorial of "n". If "n" is an "Integer", the factorial is - computed as an integer (promoted to at least 64 bits). Note that - this may overflow if "n" is not small, but you can use - "factorial(big(n))" to compute the result exactly in arbitrary - precision. If "n" is not an "Integer", "factorial(n)" is - equivalent to "gamma(n+1)". -``` +Factorial of "n". If "n" is an "Integer", the factorial is +computed as an integer (promoted to at least 64 bits). Note that +this may overflow if "n" is not small, but you can use +"factorial(big(n))" to compute the result exactly in arbitrary +precision. If "n" is not an "Integer", "factorial(n)" is +equivalent to "gamma(n+1)". """ factorial doc""" -```rst -factorial(n, k) + factorial(n, k) - Compute "factorial(n)/factorial(k)" -``` +Compute "factorial(n)/factorial(k)" """ factorial doc""" -```rst -factor(n) -> Dict + factor(n) -> Dict - Compute the prime factorization of an integer "n". Returns a - dictionary. The keys of the dictionary correspond to the factors, - and hence are of the same type as "n". The value associated with - each key indicates the number of times the factor appears in the - factorization. +Compute the prime factorization of an integer "n". Returns a +dictionary. The keys of the dictionary correspond to the factors, +and hence are of the same type as "n". The value associated with +each key indicates the number of times the factor appears in the +factorization. - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 -``` + julia> factor(100) # == 2*2*5*5 + Dict{Int64,Int64} with 2 entries: + 2 => 2 + 5 => 2 """ factor doc""" -```rst -gcd(x, y) + gcd(x, y) - Greatest common (positive) divisor (or zero if x and y are both - zero). -``` +Greatest common (positive) divisor (or zero if x and y are both +zero). """ gcd doc""" -```rst -lcm(x, y) + lcm(x, y) - Least common (non-negative) multiple. -``` +Least common (non-negative) multiple. """ lcm doc""" -```rst -gcdx(x, y) + gcdx(x, y) - Computes the greatest common (positive) divisor of "x" and "y" - and their Bézout coefficients, i.e. the integer coefficients "u" - and "v" that satisfy ux+vy = d = gcd(x,y). +Computes the greatest common (positive) divisor of "x" and "y" +and their Bézout coefficients, i.e. the integer coefficients "u" +and "v" that satisfy ux+vy = d = gcd(x,y). - julia> gcdx(12, 42) - (6,-3,1) + julia> gcdx(12, 42) + (6,-3,1) - julia> gcdx(240, 46) - (2,-9,47) + julia> gcdx(240, 46) + (2,-9,47) - Note: Bézout coefficients are *not* uniquely defined. "gcdx" - returns the minimal Bézout coefficients that are computed by the - extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, - Algorithm X.) These coefficients "u" and "v" are minimal in - the sense that |u| < |\frac y d and |v| < |\frac x d. - Furthermore, the signs of "u" and "v" are chosen so that - "d" is positive. -``` +Note: Bézout coefficients are *not* uniquely defined. "gcdx" + returns the minimal Bézout coefficients that are computed by the + extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, + Algorithm X.) These coefficients "u" and "v" are minimal in + the sense that |u| < |\frac y d and |v| < |\frac x d. + Furthermore, the signs of "u" and "v" are chosen so that + "d" is positive. """ gcdx doc""" -```rst -ispow2(n) -> Bool + ispow2(n) -> Bool - Test whether "n" is a power of two -``` +Test whether "n" is a power of two """ ispow2 doc""" -```rst -nextpow2(n) + nextpow2(n) - The smallest power of two not less than "n". Returns 0 for - "n==0", and returns "-nextpow2(-n)" for negative arguments. -``` +The smallest power of two not less than "n". Returns 0 for +"n==0", and returns "-nextpow2(-n)" for negative arguments. """ nextpow2 doc""" -```rst -prevpow2(n) + prevpow2(n) - The largest power of two not greater than "n". Returns 0 for - "n==0", and returns "-prevpow2(-n)" for negative arguments. -``` +The largest power of two not greater than "n". Returns 0 for +"n==0", and returns "-prevpow2(-n)" for negative arguments. """ prevpow2 doc""" -```rst -nextpow(a, x) + nextpow(a, x) - The smallest "a^n" not less than "x", where "n" is a non- - negative integer. "a" must be greater than 1, and "x" must be - greater than 0. -``` +The smallest "a^n" not less than "x", where "n" is a non- +negative integer. "a" must be greater than 1, and "x" must be +greater than 0. """ nextpow doc""" -```rst -prevpow(a, x) + prevpow(a, x) - The largest "a^n" not greater than "x", where "n" is a non- - negative integer. "a" must be greater than 1, and "x" must not - be less than 1. -``` +The largest "a^n" not greater than "x", where "n" is a non- +negative integer. "a" must be greater than 1, and "x" must not +be less than 1. """ prevpow doc""" -```rst -nextprod([k_1, k_2, ...], n) + nextprod([k_1, k_2, ...], n) - Next integer not less than "n" that can be written as \prod - k_i^{p_i} for integers p_1, p_2, etc. -``` +Next integer not less than "n" that can be written as \prod +k_i^{p_i} for integers p_1, p_2, etc. """ nextprod doc""" -```rst -prevprod([k_1, k_2, ...], n) + prevprod([k_1, k_2, ...], n) - Previous integer not greater than "n" that can be written as - \prod k_i^{p_i} for integers p_1, p_2, etc. -``` +Previous integer not greater than "n" that can be written as +\prod k_i^{p_i} for integers p_1, p_2, etc. """ prevprod doc""" -```rst -invmod(x, m) + invmod(x, m) - Take the inverse of "x" modulo "m": "y" such that xy = 1 - \pmod m -``` +Take the inverse of "x" modulo "m": "y" such that xy = 1 +\pmod m """ invmod doc""" -```rst -powermod(x, p, m) + powermod(x, p, m) - Compute x^p \pmod m -``` +Compute x^p \pmod m """ powermod doc""" -```rst -gamma(x) + gamma(x) - Compute the gamma function of "x" -``` +Compute the gamma function of "x" """ gamma doc""" -```rst -lgamma(x) + lgamma(x) - Compute the logarithm of the absolute value of "gamma()" for - "Real" "x", while for "Complex" "x" it computes the - logarithm of "gamma(x)". -``` +Compute the logarithm of the absolute value of "gamma()" for +"Real" "x", while for "Complex" "x" it computes the +logarithm of "gamma(x)". """ lgamma doc""" -```rst -lfact(x) + lfact(x) - Compute the logarithmic factorial of "x" -``` +Compute the logarithmic factorial of "x" """ lfact doc""" -```rst -digamma(x) + digamma(x) - Compute the digamma function of "x" (the logarithmic derivative - of "gamma(x)") -``` +Compute the digamma function of "x" (the logarithmic derivative +of "gamma(x)") """ digamma doc""" -```rst -invdigamma(x) + invdigamma(x) - Compute the inverse digamma function of "x". -``` +Compute the inverse digamma function of "x". """ invdigamma doc""" -```rst -trigamma(x) + trigamma(x) - Compute the trigamma function of "x" (the logarithmic second - derivative of "gamma(x)") -``` +Compute the trigamma function of "x" (the logarithmic second +derivative of "gamma(x)") """ trigamma doc""" -```rst -polygamma(m, x) + polygamma(m, x) - Compute the polygamma function of order "m" of argument "x" - (the "(m+1)th" derivative of the logarithm of "gamma(x)") -``` +Compute the polygamma function of order "m" of argument "x" +(the "(m+1)th" derivative of the logarithm of "gamma(x)") """ polygamma doc""" -```rst -airy(k, x) + airy(k, x) - kth derivative of the Airy function \operatorname{Ai}(x). -``` +kth derivative of the Airy function \operatorname{Ai}(x). """ airy doc""" -```rst -airyai(x) + airyai(x) - Airy function \operatorname{Ai}(x). -``` +Airy function \operatorname{Ai}(x). """ airyai doc""" -```rst -airyprime(x) + airyprime(x) - Airy function derivative \operatorname{Ai}'(x). -``` +Airy function derivative \operatorname{Ai}'(x). """ airyprime doc""" -```rst -airyaiprime(x) + airyaiprime(x) - Airy function derivative \operatorname{Ai}'(x). -``` +Airy function derivative \operatorname{Ai}'(x). """ airyaiprime doc""" -```rst -airybi(x) + airybi(x) - Airy function \operatorname{Bi}(x). -``` +Airy function \operatorname{Bi}(x). """ airybi doc""" -```rst -airybiprime(x) + airybiprime(x) - Airy function derivative \operatorname{Bi}'(x). -``` +Airy function derivative \operatorname{Bi}'(x). """ airybiprime doc""" -```rst -airyx(k, x) + airyx(k, x) - scaled kth derivative of the Airy function, return - \operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || - k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} - \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || - k == 3". -``` +scaled kth derivative of the Airy function, return +\operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || +k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} +\left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || +k == 3". """ airyx doc""" -```rst -besselj0(x) + besselj0(x) - Bessel function of the first kind of order 0, J_0(x). -``` +Bessel function of the first kind of order 0, J_0(x). """ besselj0 doc""" -```rst -besselj1(x) + besselj1(x) - Bessel function of the first kind of order 1, J_1(x). -``` +Bessel function of the first kind of order 1, J_1(x). """ besselj1 doc""" -```rst -besselj(nu, x) + besselj(nu, x) - Bessel function of the first kind of order "nu", J_\nu(x). -``` +Bessel function of the first kind of order "nu", J_\nu(x). """ besselj doc""" -```rst -besseljx(nu, x) + besseljx(nu, x) - Scaled Bessel function of the first kind of order "nu", J_\nu(x) - e^{- | \operatorname{Im}(x) |}. -``` +Scaled Bessel function of the first kind of order "nu", J_\nu(x) +e^{- | \operatorname{Im}(x) |}. """ besseljx doc""" -```rst -bessely0(x) + bessely0(x) - Bessel function of the second kind of order 0, Y_0(x). -``` +Bessel function of the second kind of order 0, Y_0(x). """ bessely0 doc""" -```rst -bessely1(x) + bessely1(x) - Bessel function of the second kind of order 1, Y_1(x). -``` +Bessel function of the second kind of order 1, Y_1(x). """ bessely1 doc""" -```rst -bessely(nu, x) + bessely(nu, x) - Bessel function of the second kind of order "nu", Y_\nu(x). -``` +Bessel function of the second kind of order "nu", Y_\nu(x). """ bessely doc""" -```rst -besselyx(nu, x) + besselyx(nu, x) - Scaled Bessel function of the second kind of order "nu", - Y_\nu(x) e^{- | \operatorname{Im}(x) |}. -``` +Scaled Bessel function of the second kind of order "nu", +Y_\nu(x) e^{- | \operatorname{Im}(x) |}. """ besselyx doc""" -```rst -hankelh1(nu, x) + hankelh1(nu, x) - Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). -``` +Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). """ hankelh1 doc""" -```rst -hankelh1x(nu, x) + hankelh1x(nu, x) - Scaled Bessel function of the third kind of order "nu", - H^{(1)}_\nu(x) e^{-x i}. -``` +Scaled Bessel function of the third kind of order "nu", +H^{(1)}_\nu(x) e^{-x i}. """ hankelh1x doc""" -```rst -hankelh2(nu, x) + hankelh2(nu, x) - Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). -``` +Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). """ hankelh2 doc""" -```rst -hankelh2x(nu, x) + hankelh2x(nu, x) - Scaled Bessel function of the third kind of order "nu", - H^{(2)}_\nu(x) e^{x i}. -``` +Scaled Bessel function of the third kind of order "nu", +H^{(2)}_\nu(x) e^{x i}. """ hankelh2x doc""" -```rst -besselh(nu, k, x) + besselh(nu, k, x) - Bessel function of the third kind of order "nu" (Hankel - function). "k" is either 1 or 2, selecting "hankelh1" or - "hankelh2", respectively. -``` +Bessel function of the third kind of order "nu" (Hankel +function). "k" is either 1 or 2, selecting "hankelh1" or +"hankelh2", respectively. """ besselh doc""" -```rst -besseli(nu, x) + besseli(nu, x) - Modified Bessel function of the first kind of order "nu", - I_\nu(x). -``` +Modified Bessel function of the first kind of order "nu", +I_\nu(x). """ besseli doc""" -```rst -besselix(nu, x) + besselix(nu, x) - Scaled modified Bessel function of the first kind of order "nu", - I_\nu(x) e^{- | \operatorname{Re}(x) |}. -``` +Scaled modified Bessel function of the first kind of order "nu", +I_\nu(x) e^{- | \operatorname{Re}(x) |}. """ besselix doc""" -```rst -besselk(nu, x) + besselk(nu, x) - Modified Bessel function of the second kind of order "nu", - K_\nu(x). -``` +Modified Bessel function of the second kind of order "nu", +K_\nu(x). """ besselk doc""" -```rst -besselkx(nu, x) + besselkx(nu, x) - Scaled modified Bessel function of the second kind of order "nu", - K_\nu(x) e^x. -``` +Scaled modified Bessel function of the second kind of order "nu", +K_\nu(x) e^x. """ besselkx doc""" -```rst -beta(x, y) + beta(x, y) - Euler integral of the first kind \operatorname{B}(x,y) = - \Gamma(x)\Gamma(y)/\Gamma(x+y). -``` +Euler integral of the first kind \operatorname{B}(x,y) = +\Gamma(x)\Gamma(y)/\Gamma(x+y). """ beta doc""" -```rst -lbeta(x, y) + lbeta(x, y) - Natural logarithm of the absolute value of the beta function - \log(|\operatorname{B}(x,y)|). -``` +Natural logarithm of the absolute value of the beta function +\log(|\operatorname{B}(x,y)|). """ lbeta doc""" -```rst -eta(x) + eta(x) - Dirichlet eta function \eta(s) = - \sum^\infty_{n=1}(-)^{n-1}/n^{s}. -``` +Dirichlet eta function \eta(s) = +\sum^\infty_{n=1}(-)^{n-1}/n^{s}. """ eta doc""" -```rst -zeta(s) + zeta(s) - Riemann zeta function \zeta(s). -``` +Riemann zeta function \zeta(s). """ zeta doc""" -```rst -zeta(s, z) + zeta(s, z) - Hurwitz zeta function \zeta(s, z). (This is equivalent to the - Riemann zeta function \zeta(s) for the case of "z=1".) -``` +Hurwitz zeta function \zeta(s, z). (This is equivalent to the +Riemann zeta function \zeta(s) for the case of "z=1".) """ zeta doc""" -```rst -ndigits(n, b) + ndigits(n, b) - Compute the number of digits in number "n" written in base "b". -``` +Compute the number of digits in number "n" written in base "b". """ ndigits doc""" -```rst -widemul(x, y) + widemul(x, y) - Multiply "x" and "y", giving the result as a larger type. -``` +Multiply "x" and "y", giving the result as a larger type. """ widemul doc""" -```rst -@evalpoly(z, c...) + @evalpoly(z, c...) - Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients - "c[1]", "c[2]", ...; that is, the coefficients are given in - ascending order by power of "z". This macro expands to efficient - inline code that uses either Horner's method or, for complex "z", - a more efficient Goertzel-like algorithm. -``` +Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients +"c[1]", "c[2]", ...; that is, the coefficients are given in +ascending order by power of "z". This macro expands to efficient +inline code that uses either Horner's method or, for complex "z", +a more efficient Goertzel-like algorithm. """ @evalpoly doc""" -```rst -mean(v[, region]) + mean(v[, region]) - Compute the mean of whole array "v", or optionally along the - dimensions in "region". Note: Julia does not ignore "NaN" - values in the computation. For applications requiring the handling - of missing data, the "DataArray" package is recommended. -``` +Compute the mean of whole array "v", or optionally along the +dimensions in "region". Note: Julia does not ignore "NaN" +values in the computation. For applications requiring the handling +of missing data, the "DataArray" package is recommended. """ mean doc""" -```rst -mean!(r, v) + mean!(r, v) - Compute the mean of "v" over the singleton dimensions of "r", - and write results to "r". -``` +Compute the mean of "v" over the singleton dimensions of "r", +and write results to "r". """ mean! doc""" -```rst -std(v[, region]) + std(v[, region]) - Compute the sample standard deviation of a vector or array "v", - optionally along dimensions in "region". The algorithm returns an - estimator of the generative distribution's standard deviation under - the assumption that each entry of "v" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". - Note: Julia does not ignore "NaN" values in the computation. For - applications requiring the handling of missing data, the - "DataArray" package is recommended. -``` +Compute the sample standard deviation of a vector or array "v", +optionally along dimensions in "region". The algorithm returns an +estimator of the generative distribution's standard deviation under +the assumption that each entry of "v" is an IID drawn from that +generative distribution. This computation is equivalent to +calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". +Note: Julia does not ignore "NaN" values in the computation. For +applications requiring the handling of missing data, the +"DataArray" package is recommended. """ std doc""" -```rst -stdm(v, m) + stdm(v, m) - Compute the sample standard deviation of a vector "v" with known - mean "m". Note: Julia does not ignore "NaN" values in the - computation. -``` +Compute the sample standard deviation of a vector "v" with known +mean "m". Note: Julia does not ignore "NaN" values in the +computation. """ stdm doc""" -```rst -var(v[, region]) + var(v[, region]) - Compute the sample variance of a vector or array "v", optionally - along dimensions in "region". The algorithm will return an - estimator of the generative distribution's variance under the - assumption that each entry of "v" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: - Julia does not ignore "NaN" values in the computation. For - applications requiring the handling of missing data, the - "DataArray" package is recommended. -``` +Compute the sample variance of a vector or array "v", optionally +along dimensions in "region". The algorithm will return an +estimator of the generative distribution's variance under the +assumption that each entry of "v" is an IID drawn from that +generative distribution. This computation is equivalent to +calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: +Julia does not ignore "NaN" values in the computation. For +applications requiring the handling of missing data, the +"DataArray" package is recommended. """ var doc""" -```rst -varm(v, m) + varm(v, m) - Compute the sample variance of a vector "v" with known mean - "m". Note: Julia does not ignore "NaN" values in the - computation. -``` +Compute the sample variance of a vector "v" with known mean +"m". Note: Julia does not ignore "NaN" values in the +computation. """ varm doc""" -```rst -middle(x) + middle(x) - Compute the middle of a scalar value, which is equivalent to "x" - itself, but of the type of "middle(x, x)" for consistency. -``` +Compute the middle of a scalar value, which is equivalent to "x" +itself, but of the type of "middle(x, x)" for consistency. """ middle doc""" -```rst -middle(x, y) + middle(x, y) - Compute the middle of two reals "x" and "y", which is - equivalent in both value and type to computing their mean ("(x + - y) / 2"). -``` +Compute the middle of two reals "x" and "y", which is +equivalent in both value and type to computing their mean ("(x + +y) / 2"). """ middle doc""" -```rst -middle(range) + middle(range) - Compute the middle of a range, which consists in computing the mean - of its extrema. Since a range is sorted, the mean is performed with - the first and last element. -``` +Compute the middle of a range, which consists in computing the mean +of its extrema. Since a range is sorted, the mean is performed with +the first and last element. """ middle doc""" -```rst -middle(array) + middle(array) - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. -``` +Compute the middle of an array, which consists in finding its +extrema and then computing their mean. """ middle doc""" -```rst -median(v) + median(v) - Compute the median of a vector "v". "NaN" is returned if the - data contains any "NaN" values. For applications requiring the - handling of missing data, the "DataArrays" package is - recommended. -``` +Compute the median of a vector "v". "NaN" is returned if the +data contains any "NaN" values. For applications requiring the +handling of missing data, the "DataArrays" package is +recommended. """ median doc""" -```rst -median!(v) + median!(v) - Like "median", but may overwrite the input vector. -``` +Like "median", but may overwrite the input vector. """ median! doc""" -```rst -hist(v[, n]) -> e, counts + hist(v[, n]) -> e, counts - Compute the histogram of "v", optionally using approximately - "n" bins. The return values are a range "e", which correspond - to the edges of the bins, and "counts" containing the number of - elements of "v" in each bin. Note: Julia does not ignore "NaN" - values in the computation. -``` +Compute the histogram of "v", optionally using approximately +"n" bins. The return values are a range "e", which correspond +to the edges of the bins, and "counts" containing the number of +elements of "v" in each bin. Note: Julia does not ignore "NaN" +values in the computation. """ hist doc""" -```rst -hist(v, e) -> e, counts + hist(v, e) -> e, counts - Compute the histogram of "v" using a vector/range "e" as the - edges for the bins. The result will be a vector of length - "length(e) - 1", such that the element at location "i" - satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not - ignore "NaN" values in the computation. -``` +Compute the histogram of "v" using a vector/range "e" as the +edges for the bins. The result will be a vector of length +"length(e) - 1", such that the element at location "i" +satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not +ignore "NaN" values in the computation. """ hist doc""" -```rst -hist!(counts, v, e) -> e, counts + hist!(counts, v, e) -> e, counts - Compute the histogram of "v", using a vector/range "e" as the - edges for the bins. This function writes the resultant counts to a - pre-allocated array "counts". -``` +Compute the histogram of "v", using a vector/range "e" as the +edges for the bins. This function writes the resultant counts to a +pre-allocated array "counts". """ hist! doc""" -```rst -hist2d(M, e1, e2) -> (edge1, edge2, counts) + hist2d(M, e1, e2) -> (edge1, edge2, counts) - Compute a "2d histogram" of a set of N points specified by N-by-2 - matrix "M". Arguments "e1" and "e2" are bins for each - dimension, specified either as integer bin counts or vectors of bin - edges. The result is a tuple of "edge1" (the bin edges used in - the first dimension), "edge2" (the bin edges used in the second - dimension), and "counts", a histogram matrix of size - "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore - "NaN" values in the computation. -``` +Compute a "2d histogram" of a set of N points specified by N-by-2 +matrix "M". Arguments "e1" and "e2" are bins for each +dimension, specified either as integer bin counts or vectors of bin +edges. The result is a tuple of "edge1" (the bin edges used in +the first dimension), "edge2" (the bin edges used in the second +dimension), and "counts", a histogram matrix of size +"(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore +"NaN" values in the computation. """ hist2d doc""" -```rst -hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - Compute a "2d histogram" with respect to the bins delimited by - the edges given in "e1" and "e2". This function writes the - results to a pre-allocated array "counts". -``` +Compute a "2d histogram" with respect to the bins delimited by +the edges given in "e1" and "e2". This function writes the +results to a pre-allocated array "counts". """ hist2d! doc""" -```rst -histrange(v, n) + histrange(v, n) - Compute *nice* bin ranges for the edges of a histogram of "v", - using approximately "n" bins. The resulting step sizes will be 1, - 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - "NaN" values in the computation. -``` +Compute *nice* bin ranges for the edges of a histogram of "v", +using approximately "n" bins. The resulting step sizes will be 1, +2 or 5 multiplied by a power of 10. Note: Julia does not ignore +"NaN" values in the computation. """ histrange doc""" -```rst -midpoints(e) + midpoints(e) - Compute the midpoints of the bins with edges "e". The result is a - vector/range of length "length(e) - 1". Note: Julia does not - ignore "NaN" values in the computation. -``` +Compute the midpoints of the bins with edges "e". The result is a +vector/range of length "length(e) - 1". Note: Julia does not +ignore "NaN" values in the computation. """ midpoints doc""" -```rst -quantile(v, p) + quantile(v, p) - Compute the quantiles of a vector "v" at a specified set of - probability values "p". Note: Julia does not ignore "NaN" - values in the computation. -``` +Compute the quantiles of a vector "v" at a specified set of +probability values "p". Note: Julia does not ignore "NaN" +values in the computation. """ quantile doc""" -```rst -quantile(v, p) + quantile(v, p) - Compute the quantile of a vector "v" at the probability "p". - Note: Julia does not ignore "NaN" values in the computation. -``` +Compute the quantile of a vector "v" at the probability "p". +Note: Julia does not ignore "NaN" values in the computation. """ quantile doc""" -```rst -quantile!(v, p) + quantile!(v, p) - Like "quantile", but overwrites the input vector. -``` +Like "quantile", but overwrites the input vector. """ quantile! doc""" -```rst -cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - Compute the Pearson covariance between the vector(s) in "v1" and - "v2". Here, "v1" and "v2" can be either vectors or matrices. +Compute the Pearson covariance between the vector(s) in "v1" and +"v2". Here, "v1" and "v2" can be either vectors or matrices. - This function accepts three keyword arguments: +This function accepts three keyword arguments: - * "vardim": the dimension of variables. When "vardim = 1", - variables are considered in columns while observations in rows; - when "vardim = 2", variables are in rows while observations in - columns. By default, it is set to "1". +* "vardim": the dimension of variables. When "vardim = 1", + variables are considered in columns while observations in rows; + when "vardim = 2", variables are in rows while observations in + columns. By default, it is set to "1". - * "corrected": whether to apply Bessel's correction (divide by - "n-1" instead of "n"). By default, it is set to "true". +* "corrected": whether to apply Bessel's correction (divide by + "n-1" instead of "n"). By default, it is set to "true". - * "mean": allow users to supply mean values that are known. By - default, it is set to "nothing", which indicates that the - mean(s) are unknown, and the function will compute the mean. - Users can use "mean=0" to indicate that the input data are - centered, and hence there's no need to subtract the mean. +* "mean": allow users to supply mean values that are known. By + default, it is set to "nothing", which indicates that the + mean(s) are unknown, and the function will compute the mean. + Users can use "mean=0" to indicate that the input data are + centered, and hence there's no need to subtract the mean. - The size of the result depends on the size of "v1" and "v2". - When both "v1" and "v2" are vectors, it returns the covariance - between them as a scalar. When either one is a matrix, it returns a - covariance matrix of size "(n1, n2)", where "n1" and "n2" are - the numbers of slices in "v1" and "v2", which depend on the - setting of "vardim". +The size of the result depends on the size of "v1" and "v2". +When both "v1" and "v2" are vectors, it returns the covariance +between them as a scalar. When either one is a matrix, it returns a +covariance matrix of size "(n1, n2)", where "n1" and "n2" are +the numbers of slices in "v1" and "v2", which depend on the +setting of "vardim". - Note: "v2" can be omitted, which indicates "v2 = v1". -``` +Note: "v2" can be omitted, which indicates "v2 = v1". """ cov doc""" -```rst -cor(v1[, v2][, vardim=1, mean=nothing]) + cor(v1[, v2][, vardim=1, mean=nothing]) - Compute the Pearson correlation between the vector(s) in "v1" and - "v2". +Compute the Pearson correlation between the vector(s) in "v1" and +"v2". - Users can use the keyword argument "vardim" to specify the - variable dimension, and "mean" to supply pre-computed mean - values. -``` +Users can use the keyword argument "vardim" to specify the +variable dimension, and "mean" to supply pre-computed mean +values. """ cor doc""" -```rst -fft(A[, dims]) + fft(A[, dims]) - Performs a multidimensional FFT of the array "A". The optional - "dims" argument specifies an iterable subset of dimensions (e.g. - an integer, range, tuple, or array) to transform along. Most - efficient if the size of "A" along the transformed dimensions is - a product of small primes; see "nextprod()". See also - "plan_fft()" for even greater efficiency. +Performs a multidimensional FFT of the array "A". The optional +"dims" argument specifies an iterable subset of dimensions (e.g. +an integer, range, tuple, or array) to transform along. Most +efficient if the size of "A" along the transformed dimensions is +a product of small primes; see "nextprod()". See also +"plan_fft()" for even greater efficiency. - A one-dimensional FFT computes the one-dimensional discrete Fourier - transform (DFT) as defined by +A one-dimensional FFT computes the one-dimensional discrete Fourier +transform (DFT) as defined by - \operatorname{DFT}(A)[k] = - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(-i\frac{2\pi - (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. + \operatorname{DFT}(A)[k] = + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(-i\frac{2\pi + (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. - A multidimensional FFT simply performs this operation along each - transformed dimension of "A". +A multidimensional FFT simply performs this operation along each +transformed dimension of "A". - Higher performance is usually possible with multi-threading. Use - *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* - processors. -``` +Higher performance is usually possible with multi-threading. Use +*FFTW.set_num_threads(np)* to use *np* threads, if you have *np* +processors. """ fft doc""" -```rst -fft!(A[, dims]) + fft!(A[, dims]) - Same as "fft()", but operates in-place on "A", which must be an - array of complex floating-point numbers. -``` +Same as "fft()", but operates in-place on "A", which must be an +array of complex floating-point numbers. """ fft! doc""" -```rst -ifft(A[, dims]) + ifft(A[, dims]) - Multidimensional inverse FFT. +Multidimensional inverse FFT. - A one-dimensional inverse FFT computes +A one-dimensional inverse FFT computes - \operatorname{IDFT}(A)[k] = - \frac{1}{\operatorname{length}(A)} - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(+i\frac{2\pi (n-1)(k-1)} - {\operatorname{length}(A)} \right) A[n]. + \operatorname{IDFT}(A)[k] = + \frac{1}{\operatorname{length}(A)} + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(+i\frac{2\pi (n-1)(k-1)} + {\operatorname{length}(A)} \right) A[n]. - A multidimensional inverse FFT simply performs this operation along - each transformed dimension of "A". -``` +A multidimensional inverse FFT simply performs this operation along +each transformed dimension of "A". """ ifft doc""" -```rst -ifft!(A[, dims]) + ifft!(A[, dims]) - Same as "ifft()", but operates in-place on "A". -``` +Same as "ifft()", but operates in-place on "A". """ ifft! doc""" -```rst -bfft(A[, dims]) + bfft(A[, dims]) - Similar to "ifft()", but computes an unnormalized inverse - (backward) transform, which must be divided by the product of the - sizes of the transformed dimensions in order to obtain the inverse. - (This is slightly more efficient than "ifft()" because it omits a - scaling step, which in some applications can be combined with other - computational steps elsewhere.) +Similar to "ifft()", but computes an unnormalized inverse +(backward) transform, which must be divided by the product of the +sizes of the transformed dimensions in order to obtain the inverse. +(This is slightly more efficient than "ifft()" because it omits a +scaling step, which in some applications can be combined with other +computational steps elsewhere.) - \operatorname{BDFT}(A)[k] = \operatorname{length}(A) - \operatorname{IDFT}(A)[k] -``` + \operatorname{BDFT}(A)[k] = \operatorname{length}(A) + \operatorname{IDFT}(A)[k] """ bfft doc""" -```rst -bfft!(A[, dims]) + bfft!(A[, dims]) - Same as "bfft()", but operates in-place on "A". -``` +Same as "bfft()", but operates in-place on "A". """ bfft! doc""" -```rst -plan_fft(A[, dims[, flags[, timelimit]]]) + plan_fft(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized FFT along given dimensions ("dims") of - arrays matching the shape and type of "A". (The first two - arguments have the same meaning as for "fft()".) Returns a - function "plan(A)" that computes "fft(A, dims)" quickly. +Pre-plan an optimized FFT along given dimensions ("dims") of +arrays matching the shape and type of "A". (The first two +arguments have the same meaning as for "fft()".) Returns a +function "plan(A)" that computes "fft(A, dims)" quickly. - The "flags" argument is a bitwise-or of FFTW planner flags, - defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or - "FFTW.PATIENT" will instead spend several seconds (or more) - benchmarking different possible FFT algorithms and picking the - fastest one; see the FFTW manual for more information on planner - flags. The optional "timelimit" argument specifies a rough upper - bound on the allowed planning time, in seconds. Passing - "FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array - "A" to be overwritten with zeros during plan creation. +The "flags" argument is a bitwise-or of FFTW planner flags, +defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or +"FFTW.PATIENT" will instead spend several seconds (or more) +benchmarking different possible FFT algorithms and picking the +fastest one; see the FFTW manual for more information on planner +flags. The optional "timelimit" argument specifies a rough upper +bound on the allowed planning time, in seconds. Passing +"FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array +"A" to be overwritten with zeros during plan creation. - "plan_fft!()" is the same as "plan_fft()" but creates a plan - that operates in-place on its argument (which must be an array of - complex floating-point numbers). "plan_ifft()" and so on are - similar but produce plans that perform the equivalent of the - inverse transforms "ifft()" and so on. -``` +"plan_fft!()" is the same as "plan_fft()" but creates a plan +that operates in-place on its argument (which must be an array of +complex floating-point numbers). "plan_ifft()" and so on are +similar but produce plans that perform the equivalent of the +inverse transforms "ifft()" and so on. """ plan_fft doc""" -```rst -plan_ifft(A[, dims[, flags[, timelimit]]]) + plan_ifft(A[, dims[, flags[, timelimit]]]) - Same as "plan_fft()", but produces a plan that performs inverse - transforms "ifft()". -``` +Same as "plan_fft()", but produces a plan that performs inverse +transforms "ifft()". """ plan_ifft doc""" -```rst -plan_bfft(A[, dims[, flags[, timelimit]]]) + plan_bfft(A[, dims[, flags[, timelimit]]]) - Same as "plan_fft()", but produces a plan that performs an - unnormalized backwards transform "bfft()". -``` +Same as "plan_fft()", but produces a plan that performs an +unnormalized backwards transform "bfft()". """ plan_bfft doc""" -```rst -plan_fft!(A[, dims[, flags[, timelimit]]]) + plan_fft!(A[, dims[, flags[, timelimit]]]) - Same as "plan_fft()", but operates in-place on "A". -``` +Same as "plan_fft()", but operates in-place on "A". """ plan_fft! doc""" -```rst -plan_ifft!(A[, dims[, flags[, timelimit]]]) + plan_ifft!(A[, dims[, flags[, timelimit]]]) - Same as "plan_ifft()", but operates in-place on "A". -``` +Same as "plan_ifft()", but operates in-place on "A". """ plan_ifft! doc""" -```rst -plan_bfft!(A[, dims[, flags[, timelimit]]]) + plan_bfft!(A[, dims[, flags[, timelimit]]]) - Same as "plan_bfft()", but operates in-place on "A". -``` +Same as "plan_bfft()", but operates in-place on "A". """ plan_bfft! doc""" -```rst -rfft(A[, dims]) + rfft(A[, dims]) - Multidimensional FFT of a real array A, exploiting the fact that - the transform has conjugate symmetry in order to save roughly half - the computational time and storage costs compared with "fft()". - If "A" has size "(n_1, ..., n_d)", the result has size - "(floor(n_1/2)+1, ..., n_d)". +Multidimensional FFT of a real array A, exploiting the fact that +the transform has conjugate symmetry in order to save roughly half +the computational time and storage costs compared with "fft()". +If "A" has size "(n_1, ..., n_d)", the result has size +"(floor(n_1/2)+1, ..., n_d)". - The optional "dims" argument specifies an iterable subset of one - or more dimensions of "A" to transform, similar to "fft()". - Instead of (roughly) halving the first dimension of "A" in the - result, the "dims[1]" dimension is (roughly) halved in the same - way. -``` +The optional "dims" argument specifies an iterable subset of one +or more dimensions of "A" to transform, similar to "fft()". +Instead of (roughly) halving the first dimension of "A" in the +result, the "dims[1]" dimension is (roughly) halved in the same +way. """ rfft doc""" -```rst -irfft(A, d[, dims]) + irfft(A, d[, dims]) - Inverse of "rfft()": for a complex array "A", gives the - corresponding real array whose FFT yields "A" in the first half. - As for "rfft()", "dims" is an optional subset of dimensions to - transform, defaulting to "1:ndims(A)". +Inverse of "rfft()": for a complex array "A", gives the +corresponding real array whose FFT yields "A" in the first half. +As for "rfft()", "dims" is an optional subset of dimensions to +transform, defaulting to "1:ndims(A)". - "d" is the length of the transformed real array along the - "dims[1]" dimension, which must satisfy "d == - floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred - from "size(A)" due to the possibility of rounding by the - "floor" function here.) -``` +"d" is the length of the transformed real array along the +"dims[1]" dimension, which must satisfy "d == +floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred +from "size(A)" due to the possibility of rounding by the +"floor" function here.) """ irfft doc""" -```rst -brfft(A, d[, dims]) + brfft(A, d[, dims]) - Similar to "irfft()" but computes an unnormalized inverse - transform (similar to "bfft()"), which must be divided by the - product of the sizes of the transformed dimensions (of the real - output array) in order to obtain the inverse transform. -``` +Similar to "irfft()" but computes an unnormalized inverse +transform (similar to "bfft()"), which must be divided by the +product of the sizes of the transformed dimensions (of the real +output array) in order to obtain the inverse transform. """ brfft doc""" -```rst -plan_rfft(A[, dims[, flags[, timelimit]]]) + plan_rfft(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized real-input FFT, similar to "plan_fft()" - except for "rfft()" instead of "fft()". The first two - arguments, and the size of the transformed result, are the same as - for "rfft()". -``` +Pre-plan an optimized real-input FFT, similar to "plan_fft()" +except for "rfft()" instead of "fft()". The first two +arguments, and the size of the transformed result, are the same as +for "rfft()". """ plan_rfft doc""" -```rst -plan_brfft(A, d[, dims[, flags[, timelimit]]]) + plan_brfft(A, d[, dims[, flags[, timelimit]]]) - Pre-plan an optimized real-input unnormalized transform, similar to - "plan_rfft()" except for "brfft()" instead of "rfft()". The - first two arguments and the size of the transformed result, are the - same as for "brfft()". -``` +Pre-plan an optimized real-input unnormalized transform, similar to +"plan_rfft()" except for "brfft()" instead of "rfft()". The +first two arguments and the size of the transformed result, are the +same as for "brfft()". """ plan_brfft doc""" -```rst -plan_irfft(A, d[, dims[, flags[, timelimit]]]) + plan_irfft(A, d[, dims[, flags[, timelimit]]]) - Pre-plan an optimized inverse real-input FFT, similar to - "plan_rfft()" except for "irfft()" and "brfft()", - respectively. The first three arguments have the same meaning as - for "irfft()". -``` +Pre-plan an optimized inverse real-input FFT, similar to +"plan_rfft()" except for "irfft()" and "brfft()", +respectively. The first three arguments have the same meaning as +for "irfft()". """ plan_irfft doc""" -```rst -dct(A[, dims]) + dct(A[, dims]) - Performs a multidimensional type-II discrete cosine transform (DCT) - of the array "A", using the unitary normalization of the DCT. The - optional "dims" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of "A" along the transformed - dimensions is a product of small primes; see "nextprod()". See - also "plan_dct()" for even greater efficiency. -``` +Performs a multidimensional type-II discrete cosine transform (DCT) +of the array "A", using the unitary normalization of the DCT. The +optional "dims" argument specifies an iterable subset of +dimensions (e.g. an integer, range, tuple, or array) to transform +along. Most efficient if the size of "A" along the transformed +dimensions is a product of small primes; see "nextprod()". See +also "plan_dct()" for even greater efficiency. """ dct doc""" -```rst -dct!(A[, dims]) + dct!(A[, dims]) - Same as "dct!()", except that it operates in-place on "A", - which must be an array of real or complex floating-point values. -``` +Same as "dct!()", except that it operates in-place on "A", +which must be an array of real or complex floating-point values. """ dct! doc""" -```rst -idct(A[, dims]) + idct(A[, dims]) - Computes the multidimensional inverse discrete cosine transform - (DCT) of the array "A" (technically, a type-III DCT with the - unitary normalization). The optional "dims" argument specifies an - iterable subset of dimensions (e.g. an integer, range, tuple, or - array) to transform along. Most efficient if the size of "A" - along the transformed dimensions is a product of small primes; see - "nextprod()". See also "plan_idct()" for even greater - efficiency. -``` +Computes the multidimensional inverse discrete cosine transform +(DCT) of the array "A" (technically, a type-III DCT with the +unitary normalization). The optional "dims" argument specifies an +iterable subset of dimensions (e.g. an integer, range, tuple, or +array) to transform along. Most efficient if the size of "A" +along the transformed dimensions is a product of small primes; see +"nextprod()". See also "plan_idct()" for even greater +efficiency. """ idct doc""" -```rst -idct!(A[, dims]) + idct!(A[, dims]) - Same as "idct!()", but operates in-place on "A". -``` +Same as "idct!()", but operates in-place on "A". """ idct! doc""" -```rst -plan_dct(A[, dims[, flags[, timelimit]]]) + plan_dct(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized discrete cosine transform (DCT), similar to - "plan_fft()" except producing a function that computes "dct()". - The first two arguments have the same meaning as for "dct()". -``` +Pre-plan an optimized discrete cosine transform (DCT), similar to +"plan_fft()" except producing a function that computes "dct()". +The first two arguments have the same meaning as for "dct()". """ plan_dct doc""" -```rst -plan_dct!(A[, dims[, flags[, timelimit]]]) + plan_dct!(A[, dims[, flags[, timelimit]]]) - Same as "plan_dct()", but operates in-place on "A". -``` +Same as "plan_dct()", but operates in-place on "A". """ plan_dct! doc""" -```rst -plan_idct(A[, dims[, flags[, timelimit]]]) + plan_idct(A[, dims[, flags[, timelimit]]]) - Pre-plan an optimized inverse discrete cosine transform (DCT), - similar to "plan_fft()" except producing a function that computes - "idct()". The first two arguments have the same meaning as for - "idct()". -``` +Pre-plan an optimized inverse discrete cosine transform (DCT), +similar to "plan_fft()" except producing a function that computes +"idct()". The first two arguments have the same meaning as for +"idct()". """ plan_idct doc""" -```rst -plan_idct!(A[, dims[, flags[, timelimit]]]) + plan_idct!(A[, dims[, flags[, timelimit]]]) - Same as "plan_idct()", but operates in-place on "A". -``` +Same as "plan_idct()", but operates in-place on "A". """ plan_idct! doc""" -```rst -fftshift(x) + fftshift(x) - Swap the first and second halves of each dimension of "x". -``` +Swap the first and second halves of each dimension of "x". """ fftshift doc""" -```rst -fftshift(x, dim) + fftshift(x, dim) - Swap the first and second halves of the given dimension of array - "x". -``` +Swap the first and second halves of the given dimension of array +"x". """ fftshift doc""" -```rst -ifftshift(x[, dim]) + ifftshift(x[, dim]) - Undoes the effect of "fftshift". -``` +Undoes the effect of "fftshift". """ ifftshift doc""" -```rst -filt(b, a, x[, si]) + filt(b, a, x[, si]) - Apply filter described by vectors "a" and "b" to vector "x", - with an optional initial filter state vector "si" (defaults to - zeros). -``` +Apply filter described by vectors "a" and "b" to vector "x", +with an optional initial filter state vector "si" (defaults to +zeros). """ filt doc""" -```rst -filt!(out, b, a, x[, si]) + filt!(out, b, a, x[, si]) - Same as "filt()" but writes the result into the "out" argument, - which may alias the input "x" to modify it in-place. -``` +Same as "filt()" but writes the result into the "out" argument, +which may alias the input "x" to modify it in-place. """ filt! doc""" -```rst -deconv(b, a) + deconv(b, a) - Construct vector "c" such that "b = conv(a,c) + r". Equivalent - to polynomial division. -``` +Construct vector "c" such that "b = conv(a,c) + r". Equivalent +to polynomial division. """ deconv doc""" -```rst -conv(u, v) + conv(u, v) - Convolution of two vectors. Uses FFT algorithm. -``` +Convolution of two vectors. Uses FFT algorithm. """ conv doc""" -```rst -conv2(u, v, A) + conv2(u, v, A) - 2-D convolution of the matrix "A" with the 2-D separable kernel - generated by the vectors "u" and "v". Uses 2-D FFT algorithm -``` +2-D convolution of the matrix "A" with the 2-D separable kernel +generated by the vectors "u" and "v". Uses 2-D FFT algorithm """ conv2 doc""" -```rst -conv2(B, A) + conv2(B, A) - 2-D convolution of the matrix "B" with the matrix "A". Uses - 2-D FFT algorithm -``` +2-D convolution of the matrix "B" with the matrix "A". Uses +2-D FFT algorithm """ conv2 doc""" -```rst -xcorr(u, v) + xcorr(u, v) - Compute the cross-correlation of two vectors. -``` +Compute the cross-correlation of two vectors. """ xcorr doc""" -```rst -r2r(A, kind[, dims]) + r2r(A, kind[, dims]) - Performs a multidimensional real-input/real-output (r2r) transform - of type "kind" of the array "A", as defined in the FFTW manual. - "kind" specifies either a discrete cosine transform of various - types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or - "FFTW.REDFT11"), a discrete sine transform of various types - ("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or - "FFTW.RODFT11"), a real-input DFT with halfcomplex-format output - ("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete - Hartley transform ("FFTW.DHT"). The "kind" argument may be an - array or tuple in order to specify different transform types along - the different dimensions of "A"; "kind[end]" is used for any - unspecified dimensions. See the FFTW manual for precise - definitions of these transform types, at http://www.fftw.org/doc. +Performs a multidimensional real-input/real-output (r2r) transform +of type "kind" of the array "A", as defined in the FFTW manual. +"kind" specifies either a discrete cosine transform of various +types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or +"FFTW.REDFT11"), a discrete sine transform of various types +("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or +"FFTW.RODFT11"), a real-input DFT with halfcomplex-format output +("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete +Hartley transform ("FFTW.DHT"). The "kind" argument may be an +array or tuple in order to specify different transform types along +the different dimensions of "A"; "kind[end]" is used for any +unspecified dimensions. See the FFTW manual for precise +definitions of these transform types, at http://www.fftw.org/doc. - The optional "dims" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. "kind[i]" is then the transform type for "dims[i]", with - "kind[end]" being used for "i > length(kind)". +The optional "dims" argument specifies an iterable subset of +dimensions (e.g. an integer, range, tuple, or array) to transform +along. "kind[i]" is then the transform type for "dims[i]", with +"kind[end]" being used for "i > length(kind)". - See also "plan_r2r()" to pre-plan optimized r2r transforms. -``` +See also "plan_r2r()" to pre-plan optimized r2r transforms. """ Base.FFTW.r2r doc""" -```rst -r2r!(A, kind[, dims]) + r2r!(A, kind[, dims]) - Same as "r2r()", but operates in-place on "A", which must be an - array of real or complex floating-point numbers. -``` +Same as "r2r()", but operates in-place on "A", which must be an +array of real or complex floating-point numbers. """ Base.FFTW.r2r! doc""" -```rst -plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" - except that the transforms (and the first three arguments) - correspond to "r2r()" and "r2r!()", respectively. -``` +Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" +except that the transforms (and the first three arguments) +correspond to "r2r()" and "r2r!()", respectively. """ Base.FFTW.plan_r2r doc""" -```rst -plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) - Similar to "Base.plan_fft()", but corresponds to "r2r!()". -``` +Similar to "Base.plan_fft()", but corresponds to "r2r!()". """ Base.FFTW.plan_r2r! doc""" -```rst -quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - - Numerically integrate the function "f(x)" from "a" to "b", - and optionally over additional intervals "b" to "c" and so on. - Keyword options include a relative error tolerance "reltol" - (defaults to "sqrt(eps)" in the precision of the endpoints), an - absolute error tolerance "abstol" (defaults to 0), a maximum - number of function evaluations "maxevals" (defaults to "10^7"), - and the "order" of the integration rule (defaults to 7). - - Returns a pair "(I,E)" of the estimated integral "I" and an - estimated upper bound on the absolute error "E". If "maxevals" - is not exceeded then "E <= max(abstol, reltol*norm(I))" will - hold. (Note that it is useful to specify a positive "abstol" in - cases where "norm(I)" may be zero.) - - The endpoints "a" etcetera can also be complex (in which case the - integral is performed over straight-line segments in the complex - plane). If the endpoints are "BigFloat", then the integration - will be performed in "BigFloat" precision as well (note: it is - advisable to increase the integration "order" in rough proportion - to the precision, for smooth integrands). More generally, the - precision is set by the precision of the integration endpoints - (promoted to floating-point types). - - The integrand "f(x)" can return any numeric scalar, vector, or - matrix type, or in fact any type supporting "+", "-", - multiplication by real values, and a "norm" (i.e., any normed - vector space). Alternatively, a different norm can be specified by - passing a *norm*-like function as the *norm* keyword argument - (which defaults to *vecnorm*). - - [Only one-dimensional integrals are provided by this function. For - multi-dimensional integration (cubature), there are many different - algorithms (often much better than simple nested 1d integrals) and - the optimal choice tends to be very problem-dependent. See the - Julia external-package listing for available algorithms for - multidimensional integration or other specialized tasks (such as - integrals of highly oscillatory or singular functions).] - - The algorithm is an adaptive Gauss-Kronrod integration technique: - the integral in each interval is estimated using a Kronrod rule - ("2*order+1" points) and the error is estimated using an embedded - Gauss rule ("order" points). The interval with the largest - error is then subdivided into two intervals and the process is - repeated until the desired error tolerance is achieved. - - These quadrature rules work best for smooth functions within each - interval, so if your function has a known discontinuity or other - singularity, it is best to subdivide your interval to put the - singularity at an endpoint. For example, if "f" has a - discontinuity at "x=0.7" and you want to integrate from 0 to 1, - you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at - the point of discontinuity. The integrand is never evaluated - exactly at the endpoints of the intervals, so it is possible to - integrate functions that diverge at the endpoints as long as the - singularity is integrable (for example, a "log(x)" or - "1/sqrt(x)" singularity). - - For real-valued endpoints, the starting and/or ending points may be - infinite. (A coordinate transformation is performed internally to - map the infinite interval to a finite one.) -``` + quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + +Numerically integrate the function "f(x)" from "a" to "b", +and optionally over additional intervals "b" to "c" and so on. +Keyword options include a relative error tolerance "reltol" +(defaults to "sqrt(eps)" in the precision of the endpoints), an +absolute error tolerance "abstol" (defaults to 0), a maximum +number of function evaluations "maxevals" (defaults to "10^7"), +and the "order" of the integration rule (defaults to 7). + +Returns a pair "(I,E)" of the estimated integral "I" and an +estimated upper bound on the absolute error "E". If "maxevals" +is not exceeded then "E <= max(abstol, reltol*norm(I))" will +hold. (Note that it is useful to specify a positive "abstol" in +cases where "norm(I)" may be zero.) + +The endpoints "a" etcetera can also be complex (in which case the +integral is performed over straight-line segments in the complex +plane). If the endpoints are "BigFloat", then the integration +will be performed in "BigFloat" precision as well (note: it is +advisable to increase the integration "order" in rough proportion +to the precision, for smooth integrands). More generally, the +precision is set by the precision of the integration endpoints +(promoted to floating-point types). + +The integrand "f(x)" can return any numeric scalar, vector, or +matrix type, or in fact any type supporting "+", "-", +multiplication by real values, and a "norm" (i.e., any normed +vector space). Alternatively, a different norm can be specified by +passing a *norm*-like function as the *norm* keyword argument +(which defaults to *vecnorm*). + +[Only one-dimensional integrals are provided by this function. For +multi-dimensional integration (cubature), there are many different +algorithms (often much better than simple nested 1d integrals) and +the optimal choice tends to be very problem-dependent. See the +Julia external-package listing for available algorithms for +multidimensional integration or other specialized tasks (such as +integrals of highly oscillatory or singular functions).] + +The algorithm is an adaptive Gauss-Kronrod integration technique: +the integral in each interval is estimated using a Kronrod rule +("2*order+1" points) and the error is estimated using an embedded +Gauss rule ("order" points). The interval with the largest +error is then subdivided into two intervals and the process is +repeated until the desired error tolerance is achieved. + +These quadrature rules work best for smooth functions within each +interval, so if your function has a known discontinuity or other +singularity, it is best to subdivide your interval to put the +singularity at an endpoint. For example, if "f" has a +discontinuity at "x=0.7" and you want to integrate from 0 to 1, +you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at +the point of discontinuity. The integrand is never evaluated +exactly at the endpoints of the intervals, so it is possible to +integrate functions that diverge at the endpoints as long as the +singularity is integrable (for example, a "log(x)" or +"1/sqrt(x)" singularity). + +For real-valued endpoints, the starting and/or ending points may be +infinite. (A coordinate transformation is performed internally to +map the infinite interval to a finite one.) """ quadgk doc""" -```rst -bin(n[, pad]) + bin(n[, pad]) - Convert an integer to a binary string, optionally specifying a - number of digits to pad to. -``` +Convert an integer to a binary string, optionally specifying a +number of digits to pad to. """ bin doc""" -```rst -hex(n[, pad]) + hex(n[, pad]) - Convert an integer to a hexadecimal string, optionally specifying a - number of digits to pad to. -``` +Convert an integer to a hexadecimal string, optionally specifying a +number of digits to pad to. """ hex doc""" -```rst -dec(n[, pad]) + dec(n[, pad]) - Convert an integer to a decimal string, optionally specifying a - number of digits to pad to. -``` +Convert an integer to a decimal string, optionally specifying a +number of digits to pad to. """ dec doc""" -```rst -oct(n[, pad]) + oct(n[, pad]) - Convert an integer to an octal string, optionally specifying a - number of digits to pad to. -``` +Convert an integer to an octal string, optionally specifying a +number of digits to pad to. """ oct doc""" -```rst -base(base, n[, pad]) + base(base, n[, pad]) - Convert an integer to a string in the given base, optionally - specifying a number of digits to pad to. The base can be specified - as either an integer, or as a "UInt8" array of character values - to use as digit symbols. -``` +Convert an integer to a string in the given base, optionally +specifying a number of digits to pad to. The base can be specified +as either an integer, or as a "UInt8" array of character values +to use as digit symbols. """ base doc""" -```rst -digits(n[, base][, pad]) + digits(n[, base][, pad]) - Returns an array of the digits of "n" in the given base, - optionally padded with zeros to a specified size. More significant - digits are at higher indexes, such that "n == - sum([digits[k]*base^(k-1) for k=1:length(digits)])". -``` +Returns an array of the digits of "n" in the given base, +optionally padded with zeros to a specified size. More significant +digits are at higher indexes, such that "n == +sum([digits[k]*base^(k-1) for k=1:length(digits)])". """ digits doc""" -```rst -digits!(array, n[, base]) + digits!(array, n[, base]) - Fills an array of the digits of "n" in the given base. More - significant digits are at higher indexes. If the array length is - insufficient, the least significant digits are filled up to the - array length. If the array length is excessive, the excess portion - is filled with zeros. -``` +Fills an array of the digits of "n" in the given base. More +significant digits are at higher indexes. If the array length is +insufficient, the least significant digits are filled up to the +array length. If the array length is excessive, the excess portion +is filled with zeros. """ digits! doc""" -```rst -bits(n) + bits(n) - A string giving the literal bit representation of a number. -``` +A string giving the literal bit representation of a number. """ bits doc""" -```rst -parse(type, str[, base]) + parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. -``` +Parse a string as a number. If the type is an integer type, then a +base can be specified (the default is 10). If the type is a +floating point type, the string is parsed as a decimal floating +point number. If the string does not contain a valid number, an +error is raised. """ parse doc""" -```rst -tryparse(type, str[, base]) + tryparse(type, str[, base]) - Like "parse", but returns a "Nullable" of the requested type. - The result will be null if the string does not contain a valid - number. -``` +Like "parse", but returns a "Nullable" of the requested type. +The result will be null if the string does not contain a valid +number. """ tryparse doc""" -```rst -big(x) + big(x) - Convert a number to a maximum precision representation (typically - "BigInt" or "BigFloat"). See "BigFloat" for information about - some pitfalls with floating-point numbers. -``` +Convert a number to a maximum precision representation (typically +"BigInt" or "BigFloat"). See "BigFloat" for information about +some pitfalls with floating-point numbers. """ big doc""" -```rst -signed(x) + signed(x) - Convert a number to a signed integer. If the argument is unsigned, - it is reinterpreted as signed without checking for overflow. -``` +Convert a number to a signed integer. If the argument is unsigned, +it is reinterpreted as signed without checking for overflow. """ signed doc""" -```rst -unsigned(x) -> Unsigned + unsigned(x) -> Unsigned - Convert a number to an unsigned integer. If the argument is signed, - it is reinterpreted as unsigned without checking for negative - values. -``` +Convert a number to an unsigned integer. If the argument is signed, +it is reinterpreted as unsigned without checking for negative +values. """ unsigned doc""" -```rst -float(x) + float(x) - Convert a number, array, or string to a "FloatingPoint" data - type. For numeric data, the smallest suitable "FloatingPoint" - type is used. Converts strings to "Float64". -``` +Convert a number, array, or string to a "FloatingPoint" data +type. For numeric data, the smallest suitable "FloatingPoint" +type is used. Converts strings to "Float64". """ float doc""" -```rst -significand(x) + significand(x) - Extract the significand(s) (a.k.a. mantissa), in binary - representation, of a floating-point number or array. If "x" is a - non-zero finite number, than the result will be a number of the - same type on the interval [1,2). Otherwise "x" is returned. +Extract the significand(s) (a.k.a. mantissa), in binary +representation, of a floating-point number or array. If "x" is a +non-zero finite number, than the result will be a number of the +same type on the interval [1,2). Otherwise "x" is returned. - julia> significand(15.2)/15.2 - 0.125 + julia> significand(15.2)/15.2 + 0.125 - julia> significand(15.2)*8 - 15.2 -``` + julia> significand(15.2)*8 + 15.2 """ significand doc""" -```rst -exponent(x) -> Int + exponent(x) -> Int - Get the exponent of a normalized floating-point number. -``` +Get the exponent of a normalized floating-point number. """ exponent doc""" -```rst -complex(r[, i]) + complex(r[, i]) - Convert real numbers or arrays to complex. "i" defaults to zero. -``` +Convert real numbers or arrays to complex. "i" defaults to zero. """ complex doc""" -```rst -bswap(n) + bswap(n) - Byte-swap an integer -``` +Byte-swap an integer """ bswap doc""" -```rst -num2hex(f) + num2hex(f) - Get a hexadecimal string of the binary representation of a floating - point number -``` +Get a hexadecimal string of the binary representation of a floating +point number """ num2hex doc""" -```rst -hex2num(str) + hex2num(str) - Convert a hexadecimal string to the floating point number it - represents -``` +Convert a hexadecimal string to the floating point number it +represents """ hex2num doc""" -```rst -hex2bytes(s::ASCIIString) + hex2bytes(s::ASCIIString) - Convert an arbitrarily long hexadecimal string to its binary - representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. -``` +Convert an arbitrarily long hexadecimal string to its binary +representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. """ hex2bytes doc""" -```rst -bytes2hex(bin_arr::Array{UInt8, 1}) + bytes2hex(bin_arr::Array{UInt8, 1}) - Convert an array of bytes to its hexadecimal representation. All - characters are in lower-case. Returns an ASCIIString. -``` +Convert an array of bytes to its hexadecimal representation. All +characters are in lower-case. Returns an ASCIIString. """ bytes2hex doc""" -```rst -one(x) + one(x) - Get the multiplicative identity element for the type of x (x can - also specify the type itself). For matrices, returns an identity - matrix of the appropriate size and type. -``` +Get the multiplicative identity element for the type of x (x can +also specify the type itself). For matrices, returns an identity +matrix of the appropriate size and type. """ one doc""" -```rst -zero(x) + zero(x) - Get the additive identity element for the type of x (x can also - specify the type itself). -``` +Get the additive identity element for the type of x (x can also +specify the type itself). """ zero doc""" -```rst -pi + pi π - The constant pi -``` +The constant pi """ pi doc""" -```rst -im + im - The imaginary unit -``` +The imaginary unit """ im doc""" -```rst -e + e eu - The constant e -``` +The constant e """ e doc""" -```rst -catalan + catalan - Catalan's constant -``` +Catalan's constant """ catalan doc""" -```rst -γ + γ eulergamma - Euler's constant -``` +Euler's constant """ γ doc""" -```rst -φ + φ golden - The golden ratio -``` +The golden ratio """ φ doc""" -```rst -Inf + Inf - Positive infinity of type Float64 -``` +Positive infinity of type Float64 """ Inf doc""" -```rst -Inf32 + Inf32 - Positive infinity of type Float32 -``` +Positive infinity of type Float32 """ Inf32 doc""" -```rst -Inf16 + Inf16 - Positive infinity of type Float16 -``` +Positive infinity of type Float16 """ Inf16 doc""" -```rst -NaN + NaN - A not-a-number value of type Float64 -``` +A not-a-number value of type Float64 """ NaN doc""" -```rst -NaN32 + NaN32 - A not-a-number value of type Float32 -``` +A not-a-number value of type Float32 """ NaN32 doc""" -```rst -NaN16 + NaN16 - A not-a-number value of type Float16 -``` +A not-a-number value of type Float16 """ NaN16 doc""" -```rst -issubnormal(f) -> Bool + issubnormal(f) -> Bool - Test whether a floating point number is subnormal -``` +Test whether a floating point number is subnormal """ issubnormal doc""" -```rst -isfinite(f) -> Bool + isfinite(f) -> Bool - Test whether a number is finite -``` +Test whether a number is finite """ isfinite doc""" -```rst -isinf(f) -> Bool + isinf(f) -> Bool - Test whether a number is infinite -``` +Test whether a number is infinite """ isinf doc""" -```rst -isnan(f) -> Bool + isnan(f) -> Bool - Test whether a floating point number is not a number (NaN) -``` +Test whether a floating point number is not a number (NaN) """ isnan doc""" -```rst -inf(f) + inf(f) - Returns positive infinity of the floating point type "f" or of - the same floating point type as "f" -``` +Returns positive infinity of the floating point type "f" or of +the same floating point type as "f" """ inf doc""" -```rst -nan(f) + nan(f) - Returns NaN (not-a-number) of the floating point type "f" or of - the same floating point type as "f" -``` +Returns NaN (not-a-number) of the floating point type "f" or of +the same floating point type as "f" """ nan doc""" -```rst -nextfloat(f) + nextfloat(f) - Get the next floating point number in lexicographic order -``` +Get the next floating point number in lexicographic order """ nextfloat doc""" -```rst -prevfloat(f) -> FloatingPoint + prevfloat(f) -> FloatingPoint - Get the previous floating point number in lexicographic order -``` +Get the previous floating point number in lexicographic order """ prevfloat doc""" -```rst -isinteger(x) -> Bool + isinteger(x) -> Bool - Test whether "x" or all its elements are numerically equal to - some integer -``` +Test whether "x" or all its elements are numerically equal to +some integer """ isinteger doc""" -```rst -isreal(x) -> Bool + isreal(x) -> Bool - Test whether "x" or all its elements are numerically equal to - some real number -``` +Test whether "x" or all its elements are numerically equal to +some real number """ isreal doc""" -```rst -Float32(x[, mode::RoundingMode]) + Float32(x[, mode::RoundingMode]) - Create a Float32 from "x". If "x" is not exactly representable - then "mode" determines how "x" is rounded. +Create a Float32 from "x". If "x" is not exactly representable +then "mode" determines how "x" is rounded. - julia> Float32(1/3, RoundDown) - 0.3333333f0 + julia> Float32(1/3, RoundDown) + 0.3333333f0 - julia> Float32(1/3, RoundUp) - 0.33333334f0 + julia> Float32(1/3, RoundUp) + 0.33333334f0 - See "get_rounding" for available rounding modes. -``` +See "get_rounding" for available rounding modes. """ Float32 doc""" -```rst -Float64(x[, mode::RoundingMode]) + Float64(x[, mode::RoundingMode]) - Create a Float64 from "x". If "x" is not exactly representable - then "mode" determines how "x" is rounded. +Create a Float64 from "x". If "x" is not exactly representable +then "mode" determines how "x" is rounded. - julia> Float64(pi, RoundDown) - 3.141592653589793 + julia> Float64(pi, RoundDown) + 3.141592653589793 - julia> Float64(pi, RoundUp) - 3.1415926535897936 + julia> Float64(pi, RoundUp) + 3.1415926535897936 - See "get_rounding" for available rounding modes. -``` +See "get_rounding" for available rounding modes. """ Float64 doc""" -```rst -BigInt(x) + BigInt(x) - Create an arbitrary precision integer. "x" may be an "Int" (or - anything that can be converted to an "Int"). The usual - mathematical operators are defined for this type, and results are - promoted to a "BigInt". +Create an arbitrary precision integer. "x" may be an "Int" (or +anything that can be converted to an "Int"). The usual +mathematical operators are defined for this type, and results are +promoted to a "BigInt". - Instances can be constructed from strings via "parse()", or using - the "big" string literal. -``` +Instances can be constructed from strings via "parse()", or using +the "big" string literal. """ BigInt doc""" -```rst -BigFloat(x) + BigFloat(x) - Create an arbitrary precision floating point number. "x" may be - an "Integer", a "Float64" or a "BigInt". The usual - mathematical operators are defined for this type, and results are - promoted to a "BigFloat". +Create an arbitrary precision floating point number. "x" may be +an "Integer", a "Float64" or a "BigInt". The usual +mathematical operators are defined for this type, and results are +promoted to a "BigFloat". - Note that because decimal literals are converted to floating point - numbers when parsed, "BigFloat(2.1)" may not yield what you - expect. You may instead prefer to initialize constants from strings - via "parse()", or using the "big" string literal. +Note that because decimal literals are converted to floating point +numbers when parsed, "BigFloat(2.1)" may not yield what you +expect. You may instead prefer to initialize constants from strings +via "parse()", or using the "big" string literal. - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision -``` + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision """ BigFloat doc""" -```rst -get_rounding(T) + get_rounding(T) - Get the current floating point rounding mode for type "T", - controlling the rounding of basic arithmetic functions ("+()", - "-()", "*()", "/()" and "sqrt()") and type conversion. +Get the current floating point rounding mode for type "T", +controlling the rounding of basic arithmetic functions ("+()", +"-()", "*()", "/()" and "sqrt()") and type conversion. - Valid modes are "RoundNearest", "RoundToZero", "RoundUp", - "RoundDown", and "RoundFromZero" ("BigFloat" only). -``` +Valid modes are "RoundNearest", "RoundToZero", "RoundUp", +"RoundDown", and "RoundFromZero" ("BigFloat" only). """ get_rounding doc""" -```rst -set_rounding(T, mode) + set_rounding(T, mode) - Set the rounding mode of floating point type "T", controlling the - rounding of basic arithmetic functions ("+()", "-()", "*()", - "/()" and "sqrt()") and type conversion. +Set the rounding mode of floating point type "T", controlling the +rounding of basic arithmetic functions ("+()", "-()", "*()", +"/()" and "sqrt()") and type conversion. - Note that this may affect other types, for instance changing the - rounding mode of "Float64" will change the rounding mode of - "Float32". See "get_rounding" for available modes -``` +Note that this may affect other types, for instance changing the +rounding mode of "Float64" will change the rounding mode of +"Float32". See "get_rounding" for available modes """ set_rounding doc""" -```rst -with_rounding(f::Function, T, mode) + with_rounding(f::Function, T, mode) - Change the rounding mode of floating point type "T" for the - duration of "f". It is logically equivalent to: +Change the rounding mode of floating point type "T" for the +duration of "f". It is logically equivalent to: - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) - See "get_rounding" for available rounding modes. -``` +See "get_rounding" for available rounding modes. """ with_rounding doc""" -```rst -count_ones(x::Integer) -> Integer + count_ones(x::Integer) -> Integer - Number of ones in the binary representation of "x". +Number of ones in the binary representation of "x". - julia> count_ones(7) - 3 -``` + julia> count_ones(7) + 3 """ count_ones doc""" -```rst -count_zeros(x::Integer) -> Integer + count_zeros(x::Integer) -> Integer - Number of zeros in the binary representation of "x". +Number of zeros in the binary representation of "x". - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 -``` + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 """ count_zeros doc""" -```rst -leading_zeros(x::Integer) -> Integer + leading_zeros(x::Integer) -> Integer - Number of zeros leading the binary representation of "x". +Number of zeros leading the binary representation of "x". - julia> leading_zeros(Int32(1)) - 31 -``` + julia> leading_zeros(Int32(1)) + 31 """ leading_zeros doc""" -```rst -leading_ones(x::Integer) -> Integer + leading_ones(x::Integer) -> Integer - Number of ones leading the binary representation of "x". +Number of ones leading the binary representation of "x". - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 -``` + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 """ leading_ones doc""" -```rst -trailing_zeros(x::Integer) -> Integer + trailing_zeros(x::Integer) -> Integer - Number of zeros trailing the binary representation of "x". +Number of zeros trailing the binary representation of "x". - julia> trailing_zeros(2) - 1 -``` + julia> trailing_zeros(2) + 1 """ trailing_zeros doc""" -```rst -trailing_ones(x::Integer) -> Integer + trailing_ones(x::Integer) -> Integer - Number of ones trailing the binary representation of "x". +Number of ones trailing the binary representation of "x". - julia> trailing_ones(3) - 2 -``` + julia> trailing_ones(3) + 2 """ trailing_ones doc""" -```rst -isprime(x::Integer) -> Bool + isprime(x::Integer) -> Bool - Returns "true" if "x" is prime, and "false" otherwise. +Returns "true" if "x" is prime, and "false" otherwise. - julia> isprime(3) - true -``` + julia> isprime(3) + true """ isprime doc""" -```rst -isprime(x::BigInt[, reps = 25]) -> Bool + isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns "true" if "x" is prime; - and "false" if "x" is not prime with high probability. The - false positive rate is about "0.25^reps". "reps = 25" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). +Probabilistic primality test. Returns "true" if "x" is prime; +and "false" if "x" is not prime with high probability. The +false positive rate is about "0.25^reps". "reps = 25" is +considered safe for cryptographic applications (Knuth, +Seminumerical Algorithms). - julia> isprime(big(3)) - true -``` + julia> isprime(big(3)) + true """ isprime doc""" -```rst -primes(n) + primes(n) - Returns a collection of the prime numbers <= "n". -``` +Returns a collection of the prime numbers <= "n". """ primes doc""" -```rst -isodd(x::Integer) -> Bool + isodd(x::Integer) -> Bool - Returns "true" if "x" is odd (that is, not divisible by 2), and - "false" otherwise. +Returns "true" if "x" is odd (that is, not divisible by 2), and +"false" otherwise. - julia> isodd(9) - true + julia> isodd(9) + true - julia> isodd(10) - false -``` + julia> isodd(10) + false """ isodd doc""" -```rst -iseven(x::Integer) -> Bool + iseven(x::Integer) -> Bool - Returns "true" is "x" is even (that is, divisible by 2), and - "false" otherwise. +Returns "true" is "x" is even (that is, divisible by 2), and +"false" otherwise. - julia> iseven(9) - false + julia> iseven(9) + false - julia> iseven(10) - true -``` + julia> iseven(10) + true """ iseven doc""" -```rst -precision(num::FloatingPoint) + precision(num::FloatingPoint) - Get the precision of a floating point number, as defined by the - effective number of bits in the mantissa. -``` +Get the precision of a floating point number, as defined by the +effective number of bits in the mantissa. """ precision doc""" -```rst -get_bigfloat_precision() + get_bigfloat_precision() - Get the precision (in bits) currently used for BigFloat arithmetic. -``` +Get the precision (in bits) currently used for BigFloat arithmetic. """ get_bigfloat_precision doc""" -```rst -set_bigfloat_precision(x::Int64) + set_bigfloat_precision(x::Int64) - Set the precision (in bits) to be used to BigFloat arithmetic. -``` +Set the precision (in bits) to be used to BigFloat arithmetic. """ set_bigfloat_precision doc""" -```rst -with_bigfloat_precision(f::Function, precision::Integer) + with_bigfloat_precision(f::Function, precision::Integer) - Change the BigFloat arithmetic precision (in bits) for the duration - of "f". It is logically equivalent to: +Change the BigFloat arithmetic precision (in bits) for the duration +of "f". It is logically equivalent to: - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) -``` + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) """ with_bigfloat_precision doc""" -```rst -srand([rng][, seed]) + srand([rng][, seed]) - Reseed the random number generator. If a "seed" is provided, the - RNG will give a reproducible sequence of numbers, otherwise Julia - will get entropy from the system. For "MersenneTwister", the - "seed" may be a non-negative integer, a vector of "UInt32" - integers or a filename, in which case the seed is read from a file. - "RandomDevice" does not support seeding. -``` +Reseed the random number generator. If a "seed" is provided, the +RNG will give a reproducible sequence of numbers, otherwise Julia +will get entropy from the system. For "MersenneTwister", the +"seed" may be a non-negative integer, a vector of "UInt32" +integers or a filename, in which case the seed is read from a file. +"RandomDevice" does not support seeding. """ srand doc""" -```rst -MersenneTwister([seed]) + MersenneTwister([seed]) - Create a "MersenneTwister" RNG object. Different RNG objects can - have their own seeds, which may be useful for generating different - streams of random numbers. -``` +Create a "MersenneTwister" RNG object. Different RNG objects can +have their own seeds, which may be useful for generating different +streams of random numbers. """ MersenneTwister doc""" -```rst -RandomDevice() + RandomDevice() - Create a "RandomDevice" RNG object. Two such objects will always - generate different streams of random numbers. -``` +Create a "RandomDevice" RNG object. Two such objects will always +generate different streams of random numbers. """ RandomDevice doc""" -```rst -rand([rng][, S][, dims...]) + rand([rng][, S][, dims...]) - Pick a random element or array of random elements from the set of - values specified by "S"; "S" can be +Pick a random element or array of random elements from the set of +values specified by "S"; "S" can be - * an indexable collection (for example "1:n" or - "['x','y','z']"), or +* an indexable collection (for example "1:n" or + "['x','y','z']"), or - * a type: the set of values to pick from is then equivalent to - "typemin(S):typemax(S)" for integers (this is not applicable to - "BigInt"), and to [0,1) for floating point numbers; +* a type: the set of values to pick from is then equivalent to + "typemin(S):typemax(S)" for integers (this is not applicable to + "BigInt"), and to [0,1) for floating point numbers; - "S" defaults to "Float64". -``` +"S" defaults to "Float64". """ rand doc""" -```rst -rand!([rng], A[, coll]) + rand!([rng], A[, coll]) - Populate the array A with random values. If the indexable - collection "coll" is specified, the values are picked randomly - from "coll". This is equivalent to "copy!(A, rand(rng, coll, - size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but - without allocating a new array. -``` +Populate the array A with random values. If the indexable +collection "coll" is specified, the values are picked randomly +from "coll". This is equivalent to "copy!(A, rand(rng, coll, +size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but +without allocating a new array. """ rand! doc""" -```rst -bitrand([rng][, dims...]) + bitrand([rng][, dims...]) - Generate a "BitArray" of random boolean values. -``` +Generate a "BitArray" of random boolean values. """ bitrand doc""" -```rst -randn([rng][, dims...]) + randn([rng][, dims...]) - Generate a normally-distributed random number with mean 0 and - standard deviation 1. Optionally generate an array of normally- - distributed random numbers. -``` +Generate a normally-distributed random number with mean 0 and +standard deviation 1. Optionally generate an array of normally- +distributed random numbers. """ randn doc""" -```rst -randn!([rng], A::Array{Float64, N}) + randn!([rng], A::Array{Float64, N}) - Fill the array A with normally-distributed (mean 0, standard - deviation 1) random numbers. Also see the rand function. -``` +Fill the array A with normally-distributed (mean 0, standard +deviation 1) random numbers. Also see the rand function. """ randn! doc""" -```rst -randexp([rng][, dims...]) + randexp([rng][, dims...]) - Generate a random number according to the exponential distribution - with scale 1. Optionally generate an array of such random numbers. -``` +Generate a random number according to the exponential distribution +with scale 1. Optionally generate an array of such random numbers. """ randexp doc""" -```rst -randexp!([rng], A::Array{Float64, N}) + randexp!([rng], A::Array{Float64, N}) - Fill the array A with random numbers following the exponential - distribution (with scale 1). -``` +Fill the array A with random numbers following the exponential +distribution (with scale 1). """ randexp! doc""" -```rst -Task(func) + Task(func) - Create a "Task" (i.e. thread, or coroutine) to execute the given - function (which must be callable with no arguments). The task exits - when this function returns. -``` +Create a "Task" (i.e. thread, or coroutine) to execute the given +function (which must be callable with no arguments). The task exits +when this function returns. """ Task doc""" -```rst -yieldto(task, arg = nothing) + yieldto(task, arg = nothing) - Switch to the given task. The first time a task is switched to, the - task's function is called with no arguments. On subsequent - switches, "arg" is returned from the task's last call to - "yieldto". This is a low-level call that only switches tasks, not - considering states or scheduling in any way. Its use is - discouraged. -``` +Switch to the given task. The first time a task is switched to, the +task's function is called with no arguments. On subsequent +switches, "arg" is returned from the task's last call to +"yieldto". This is a low-level call that only switches tasks, not +considering states or scheduling in any way. Its use is +discouraged. """ yieldto doc""" -```rst -current_task() + current_task() - Get the currently running Task. -``` +Get the currently running Task. """ current_task doc""" -```rst -istaskdone(task) -> Bool + istaskdone(task) -> Bool - Tell whether a task has exited. -``` +Tell whether a task has exited. """ istaskdone doc""" -```rst -istaskstarted(task) -> Bool + istaskstarted(task) -> Bool - Tell whether a task has started executing. -``` +Tell whether a task has started executing. """ istaskstarted doc""" -```rst -consume(task, values...) + consume(task, values...) - Receive the next value passed to "produce" by the specified task. - Additional arguments may be passed, to be returned from the last - "produce" call in the producer. -``` +Receive the next value passed to "produce" by the specified task. +Additional arguments may be passed, to be returned from the last +"produce" call in the producer. """ consume doc""" -```rst -produce(value) + produce(value) - Send the given value to the last "consume" call, switching to the - consumer task. If the next "consume" call passes any values, they - are returned by "produce". -``` +Send the given value to the last "consume" call, switching to the +consumer task. If the next "consume" call passes any values, they +are returned by "produce". """ produce doc""" -```rst -yield() + yield() - Switch to the scheduler to allow another scheduled task to run. A - task that calls this function is still runnable, and will be - restarted immediately if there are no other runnable tasks. -``` +Switch to the scheduler to allow another scheduled task to run. A +task that calls this function is still runnable, and will be +restarted immediately if there are no other runnable tasks. """ yield doc""" -```rst -task_local_storage(symbol) + task_local_storage(symbol) - Look up the value of a symbol in the current task's task-local - storage. -``` +Look up the value of a symbol in the current task's task-local +storage. """ task_local_storage doc""" -```rst -task_local_storage(symbol, value) + task_local_storage(symbol, value) - Assign a value to a symbol in the current task's task-local - storage. -``` +Assign a value to a symbol in the current task's task-local +storage. """ task_local_storage doc""" -```rst -task_local_storage(body, symbol, value) + task_local_storage(body, symbol, value) - Call the function "body" with a modified task-local storage, in - which "value" is assigned to "symbol"; the previous value of - "symbol", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. -``` +Call the function "body" with a modified task-local storage, in +which "value" is assigned to "symbol"; the previous value of +"symbol", or lack thereof, is restored afterwards. Useful for +emulating dynamic scoping. """ task_local_storage doc""" -```rst -Condition() + Condition() - Create an edge-triggered event source that tasks can wait for. - Tasks that call "wait" on a "Condition" are suspended and - queued. Tasks are woken up when "notify" is later called on the - "Condition". Edge triggering means that only tasks waiting at the - time "notify" is called can be woken up. For level-triggered - notifications, you must keep extra state to keep track of whether a - notification has happened. The "RemoteRef" type does this, and so - can be used for level-triggered events. -``` +Create an edge-triggered event source that tasks can wait for. +Tasks that call "wait" on a "Condition" are suspended and +queued. Tasks are woken up when "notify" is later called on the +"Condition". Edge triggering means that only tasks waiting at the +time "notify" is called can be woken up. For level-triggered +notifications, you must keep extra state to keep track of whether a +notification has happened. The "RemoteRef" type does this, and so +can be used for level-triggered events. """ Condition doc""" -```rst -notify(condition, val=nothing; all=true, error=false) + notify(condition, val=nothing; all=true, error=false) - Wake up tasks waiting for a condition, passing them "val". If - "all" is true (the default), all waiting tasks are woken, - otherwise only one is. If "error" is true, the passed value is - raised as an exception in the woken tasks. -``` +Wake up tasks waiting for a condition, passing them "val". If +"all" is true (the default), all waiting tasks are woken, +otherwise only one is. If "error" is true, the passed value is +raised as an exception in the woken tasks. """ notify doc""" -```rst -schedule(t::Task, [val]; error=false) + schedule(t::Task, [val]; error=false) - Add a task to the scheduler's queue. This causes the task to run - constantly when the system is otherwise idle, unless the task - performs a blocking operation such as "wait". +Add a task to the scheduler's queue. This causes the task to run +constantly when the system is otherwise idle, unless the task +performs a blocking operation such as "wait". - If a second argument is provided, it will be passed to the task - (via the return value of "yieldto") when it runs again. If - "error" is true, the value is raised as an exception in the woken - task. -``` +If a second argument is provided, it will be passed to the task +(via the return value of "yieldto") when it runs again. If +"error" is true, the value is raised as an exception in the woken +task. """ schedule doc""" -```rst -@schedule() + @schedule() - Wrap an expression in a Task and add it to the scheduler's queue. -``` +Wrap an expression in a Task and add it to the scheduler's queue. """ @schedule doc""" -```rst -@task() + @task() - Wrap an expression in a Task without executing it, and return the - Task. This only creates a task, and does not run it. -``` +Wrap an expression in a Task without executing it, and return the +Task. This only creates a task, and does not run it. """ @task doc""" -```rst -sleep(seconds) + sleep(seconds) - Block the current task for a specified number of seconds. The - minimum sleep time is 1 millisecond or input of "0.001". -``` +Block the current task for a specified number of seconds. The +minimum sleep time is 1 millisecond or input of "0.001". """ sleep doc""" -```rst -ReentrantLock() + ReentrantLock() - Creates a reentrant lock. The same task can acquire the lock as - many times as required. Each lock must be matched with an unlock. -``` +Creates a reentrant lock. The same task can acquire the lock as +many times as required. Each lock must be matched with an unlock. """ ReentrantLock doc""" -```rst -lock(l::ReentrantLock) + lock(l::ReentrantLock) - Associates "l" with the current task. If "l" is already locked - by a different task, waits for it to become available. The same - task can acquire the lock multiple times. Each "lock" must be - matched by an "unlock" -``` +Associates "l" with the current task. If "l" is already locked +by a different task, waits for it to become available. The same +task can acquire the lock multiple times. Each "lock" must be +matched by an "unlock" """ lock doc""" -```rst -unlock(l::ReentrantLock) + unlock(l::ReentrantLock) - Releases ownership of the lock by the current task. If the lock had - been acquired before, it just decrements an internal counter and - returns immediately. -``` +Releases ownership of the lock by the current task. If the lock had +been acquired before, it just decrements an internal counter and +returns immediately. """ unlock doc""" -```rst -addprocs(n::Integer; exeflags=``) -> List of process identifiers + addprocs(n::Integer; exeflags=``) -> List of process identifiers - Launches workers using the in-built "LocalManager" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. "addprocs(4)" will add 4 processes - on the local machine. -``` +Launches workers using the in-built "LocalManager" which only +launches workers on the local host. This can be used to take +advantage of multiple cores. "addprocs(4)" will add 4 processes +on the local machine. """ addprocs doc""" -```rst -addprocs() -> List of process identifiers + addprocs() -> List of process identifiers - Equivalent to "addprocs(CPU_CORES)" -``` +Equivalent to "addprocs(CPU_CORES)" """ addprocs doc""" -```rst -addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. +Add processes on remote machines via SSH. Requires julia to be +installed in the same location on each node, or to be available via +a shared file system. - "machines" is a vector of machine specifications. Worker are - started for each specification. +"machines" is a vector of machine specifications. Worker are +started for each specification. - A machine specification is either a string "machine_spec" or a - tuple - "(machine_spec, count)" +A machine specification is either a string "machine_spec" or a +tuple - "(machine_spec, count)" - "machine_spec" is a string of the form "[user@]host[:port] - [bind_addr[:port]]". "user" defaults to current user, "port" - to the standard ssh port. If "[bind_addr[:port]]" is specified, - other workers will connect to this worker at the specified - "bind_addr" and "port". +"machine_spec" is a string of the form "[user@]host[:port] +[bind_addr[:port]]". "user" defaults to current user, "port" +to the standard ssh port. If "[bind_addr[:port]]" is specified, +other workers will connect to this worker at the specified +"bind_addr" and "port". - "count" is the number of workers to be launched on the specified - host. If specified as ":auto" it will launch as many workers as - the number of cores on the specific host. +"count" is the number of workers to be launched on the specified +host. If specified as ":auto" it will launch as many workers as +the number of cores on the specific host. - Keyword arguments: +Keyword arguments: - "tunnel" : if "true" then SSH tunneling will be used to connect - to the worker from the master process. +"tunnel" : if "true" then SSH tunneling will be used to connect +to the worker from the master process. - "sshflags" : specifies additional ssh options, e.g. - "sshflags=`-i /home/foo/bar.pem`" . +"sshflags" : specifies additional ssh options, e.g. +"sshflags=`-i /home/foo/bar.pem`" . - "max_parallel" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. +"max_parallel" : specifies the maximum number of workers +connected to in parallel at a host. Defaults to 10. - "dir" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) +"dir" : specifies the working directory on the workers. Defaults +to the host's current directory (as found by *pwd()*) - "exename" : name of the julia executable. Defaults to - "\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case - may be. +"exename" : name of the julia executable. Defaults to +"\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case +may be. - "exeflags" : additional flags passed to the worker processes. +"exeflags" : additional flags passed to the worker processes. - Environment variables : +Environment variables : - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable "JULIA_WORKER_TIMEOUT". The value of - "JULIA_WORKER_TIMEOUT" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. -``` +If the master process fails to establish a connection with a newly +launched worker within 60.0 seconds, the worker treats it a fatal +situation and terminates. This timeout can be controlled via +environment variable "JULIA_WORKER_TIMEOUT". The value of +"JULIA_WORKER_TIMEOUT" on the master process, specifies the +number of seconds a newly launched worker waits for connection +establishment. """ addprocs doc""" -```rst -addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. +Launches worker processes via the specified cluster manager. - For example Beowulf clusters are supported via a custom cluster - manager implemented in package "ClusterManagers". +For example Beowulf clusters are supported via a custom cluster +manager implemented in package "ClusterManagers". - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - "JULIA_WORKER_TIMEOUT" in the worker process's environment. - Relevant only when using TCP/IP as transport. -``` +The number of seconds a newly launched worker waits for connection +establishment from the master can be specified via variable +"JULIA_WORKER_TIMEOUT" in the worker process's environment. +Relevant only when using TCP/IP as transport. """ addprocs doc""" -```rst -nprocs() + nprocs() - Get the number of available processes. -``` +Get the number of available processes. """ nprocs doc""" -```rst -nworkers() + nworkers() - Get the number of available worker processes. This is one less than - nprocs(). Equal to nprocs() if nprocs() == 1. -``` +Get the number of available worker processes. This is one less than +nprocs(). Equal to nprocs() if nprocs() == 1. """ nworkers doc""" -```rst -procs() + procs() - Returns a list of all process identifiers. -``` +Returns a list of all process identifiers. """ procs doc""" -```rst -workers() + workers() - Returns a list of all worker process identifiers. -``` +Returns a list of all worker process identifiers. """ workers doc""" -```rst -rmprocs(pids...) + rmprocs(pids...) - Removes the specified workers. -``` +Removes the specified workers. """ rmprocs doc""" -```rst -interrupt([pids...]) + interrupt([pids...]) - Interrupt the current executing task on the specified workers. This - is equivalent to pressing Ctrl-C on the local machine. If no - arguments are given, all workers are interrupted. -``` +Interrupt the current executing task on the specified workers. This +is equivalent to pressing Ctrl-C on the local machine. If no +arguments are given, all workers are interrupted. """ interrupt doc""" -```rst -myid() + myid() - Get the id of the current process. -``` +Get the id of the current process. """ myid doc""" -```rst -pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - Transform collections "lsts" by applying "f" to each element in - parallel. If "nprocs() > 1", the calling process will be - dedicated to assigning tasks. All other available processes will be - used as parallel workers, or on the processes specified by - "pids". +Transform collections "lsts" by applying "f" to each element in +parallel. If "nprocs() > 1", the calling process will be +dedicated to assigning tasks. All other available processes will be +used as parallel workers, or on the processes specified by +"pids". - If "err_retry" is true, it retries a failed application of "f" - on a different worker. If "err_stop" is true, it takes precedence - over the value of "err_retry" and "pmap" stops execution on the - first error. -``` +If "err_retry" is true, it retries a failed application of "f" +on a different worker. If "err_stop" is true, it takes precedence +over the value of "err_retry" and "pmap" stops execution on the +first error. """ pmap doc""" -```rst -remotecall(id, func, args...) + remotecall(id, func, args...) - Call a function asynchronously on the given arguments on the - specified process. Returns a "RemoteRef". -``` +Call a function asynchronously on the given arguments on the +specified process. Returns a "RemoteRef". """ remotecall doc""" -```rst -wait([x]) + wait([x]) - Block the current task until some event occurs, depending on the - type of the argument: +Block the current task until some event occurs, depending on the +type of the argument: - * "RemoteRef": Wait for a value to become available for the - specified remote reference. +* "RemoteRef": Wait for a value to become available for the + specified remote reference. - * "Condition": Wait for "notify" on a condition. +* "Condition": Wait for "notify" on a condition. - * "Process": Wait for a process or process chain to exit. The - "exitcode" field of a process can be used to determine success - or failure. +* "Process": Wait for a process or process chain to exit. The + "exitcode" field of a process can be used to determine success + or failure. - * "Task": Wait for a "Task" to finish, returning its result - value. If the task fails with an exception, the exception is - propagated (re-thrown in the task that called "wait"). +* "Task": Wait for a "Task" to finish, returning its result + value. If the task fails with an exception, the exception is + propagated (re-thrown in the task that called "wait"). - * "RawFD": Wait for changes on a file descriptor (see *poll_fd* - for keyword arguments and return code) +* "RawFD": Wait for changes on a file descriptor (see *poll_fd* + for keyword arguments and return code) - If no argument is passed, the task blocks for an undefined period. - If the task's state is set to ":waiting", it can only be - restarted by an explicit call to "schedule" or "yieldto". If - the task's state is ":runnable", it might be restarted - unpredictably. +If no argument is passed, the task blocks for an undefined period. +If the task's state is set to ":waiting", it can only be +restarted by an explicit call to "schedule" or "yieldto". If +the task's state is ":runnable", it might be restarted +unpredictably. - Often "wait" is called within a "while" loop to ensure a - waited-for condition is met before proceeding. -``` +Often "wait" is called within a "while" loop to ensure a +waited-for condition is met before proceeding. """ wait doc""" -```rst -fetch(RemoteRef) + fetch(RemoteRef) - Wait for and get the value of a remote reference. -``` +Wait for and get the value of a remote reference. """ fetch doc""" -```rst -remotecall_wait(id, func, args...) + remotecall_wait(id, func, args...) - Perform "wait(remotecall(...))" in one message. -``` +Perform "wait(remotecall(...))" in one message. """ remotecall_wait doc""" -```rst -remotecall_fetch(id, func, args...) + remotecall_fetch(id, func, args...) - Perform "fetch(remotecall(...))" in one message. -``` +Perform "fetch(remotecall(...))" in one message. """ remotecall_fetch doc""" -```rst -put!(RemoteRef, value) + put!(RemoteRef, value) - Store a value to a remote reference. Implements "shared queue of - length 1" semantics: if a value is already present, blocks until - the value is removed with "take!". Returns its first argument. -``` +Store a value to a remote reference. Implements "shared queue of +length 1" semantics: if a value is already present, blocks until +the value is removed with "take!". Returns its first argument. """ put! doc""" -```rst -take!(RemoteRef) + take!(RemoteRef) - Fetch the value of a remote reference, removing it so that the - reference is empty again. -``` +Fetch the value of a remote reference, removing it so that the +reference is empty again. """ take! doc""" -```rst -isready(r::RemoteRef) + isready(r::RemoteRef) - Determine whether a "RemoteRef" has a value stored to it. Note - that this function can cause race conditions, since by the time you - receive its result it may no longer be true. It is recommended that - this function only be used on a "RemoteRef" that is assigned - once. +Determine whether a "RemoteRef" has a value stored to it. Note +that this function can cause race conditions, since by the time you +receive its result it may no longer be true. It is recommended that +this function only be used on a "RemoteRef" that is assigned +once. - If the argument "RemoteRef" is owned by a different node, this - call will block to wait for the answer. It is recommended to wait - for "r" in a separate task instead, or to use a local - "RemoteRef" as a proxy: +If the argument "RemoteRef" is owned by a different node, this +call will block to wait for the answer. It is recommended to wait +for "r" in a separate task instead, or to use a local +"RemoteRef" as a proxy: - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block -``` + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block """ isready doc""" -```rst -RemoteRef() + RemoteRef() - Make an uninitialized remote reference on the local machine. -``` +Make an uninitialized remote reference on the local machine. """ RemoteRef doc""" -```rst -RemoteRef(n) + RemoteRef(n) - Make an uninitialized remote reference on process "n". -``` +Make an uninitialized remote reference on process "n". """ RemoteRef doc""" -```rst -timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - Waits till "testcb" returns "true" or for "secs`" seconds, - whichever is earlier. "testcb" is polled every "pollint" - seconds. -``` +Waits till "testcb" returns "true" or for "secs`" seconds, +whichever is earlier. "testcb" is polled every "pollint" +seconds. """ timedwait doc""" -```rst -@spawn() + @spawn() - Execute an expression on an automatically-chosen process, returning - a "RemoteRef" to the result. -``` +Execute an expression on an automatically-chosen process, returning +a "RemoteRef" to the result. """ @spawn doc""" -```rst -@spawnat() + @spawnat() - Accepts two arguments, "p" and an expression, and runs the - expression asynchronously on process "p", returning a - "RemoteRef" to the result. -``` +Accepts two arguments, "p" and an expression, and runs the +expression asynchronously on process "p", returning a +"RemoteRef" to the result. """ @spawnat doc""" -```rst -@fetch() + @fetch() - Equivalent to "fetch(@spawn expr)". -``` +Equivalent to "fetch(@spawn expr)". """ @fetch doc""" -```rst -@fetchfrom() + @fetchfrom() - Equivalent to "fetch(@spawnat p expr)". -``` +Equivalent to "fetch(@spawnat p expr)". """ @fetchfrom doc""" -```rst -@async() + @async() - Schedule an expression to run on the local machine, also adding it - to the set of items that the nearest enclosing "@sync" waits for. -``` +Schedule an expression to run on the local machine, also adding it +to the set of items that the nearest enclosing "@sync" waits for. """ @async doc""" -```rst -@sync() + @sync() - Wait until all dynamically-enclosed uses of "@async", "@spawn", - "@spawnat" and "@parallel" are complete. -``` +Wait until all dynamically-enclosed uses of "@async", "@spawn", +"@spawnat" and "@parallel" are complete. """ @sync doc""" -```rst -@parallel() + @parallel() - A parallel for loop of the form +A parallel for loop of the form - @parallel [reducer] for var = range - body - end + @parallel [reducer] for var = range + body + end - The specified range is partitioned and locally executed across all - workers. In case an optional reducer function is specified, - @parallel performs local reductions on each worker with a final - reduction on the calling process. +The specified range is partitioned and locally executed across all +workers. In case an optional reducer function is specified, +@parallel performs local reductions on each worker with a final +reduction on the calling process. - Note that without a reducer function, @parallel executes - asynchronously, i.e. it spawns independent tasks on all available - workers and returns immediately without waiting for completion. To - wait for completion, prefix the call with "@sync", like +Note that without a reducer function, @parallel executes +asynchronously, i.e. it spawns independent tasks on all available +workers and returns immediately without waiting for completion. To +wait for completion, prefix the call with "@sync", like - @sync @parallel for var = range - body - end -``` + @sync @parallel for var = range + body + end """ @parallel doc""" -```rst -SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - Construct a SharedArray of a bitstype "T" and size "dims" - across the processes specified by "pids" - all of which have to - be on the same host. +Construct a SharedArray of a bitstype "T" and size "dims" +across the processes specified by "pids" - all of which have to +be on the same host. - If "pids" is left unspecified, the shared array will be mapped - across all processes on the current host, including the master. - But, "localindexes" and "indexpids" will only refer to worker - processes. This facilitates work distribution code to use workers - for actual computation with the master process acting as a driver. +If "pids" is left unspecified, the shared array will be mapped +across all processes on the current host, including the master. +But, "localindexes" and "indexpids" will only refer to worker +processes. This facilitates work distribution code to use workers +for actual computation with the master process acting as a driver. - If an "init" function of the type "initfn(S::SharedArray)" is - specified, it is called on all the participating workers. -``` +If an "init" function of the type "initfn(S::SharedArray)" is +specified, it is called on all the participating workers. """ SharedArray doc""" -```rst -procs(S::SharedArray) + procs(S::SharedArray) - Get the vector of processes that have mapped the shared array -``` +Get the vector of processes that have mapped the shared array """ procs doc""" -```rst -sdata(S::SharedArray) + sdata(S::SharedArray) - Returns the actual "Array" object backing "S" -``` +Returns the actual "Array" object backing "S" """ sdata doc""" -```rst -indexpids(S::SharedArray) + indexpids(S::SharedArray) - Returns the index of the current worker into the "pids" vector, - i.e., the list of workers mapping the SharedArray -``` +Returns the index of the current worker into the "pids" vector, +i.e., the list of workers mapping the SharedArray """ indexpids doc""" -```rst -launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - Implemented by cluster managers. For every Julia worker launched by - this function, it should append a "WorkerConfig" entry to - "launched" and notify "launch_ntfy". The function MUST exit - once all workers, requested by "manager" have been launched. - "params" is a dictionary of all keyword arguments "addprocs" - was called with. -``` +Implemented by cluster managers. For every Julia worker launched by +this function, it should append a "WorkerConfig" entry to +"launched" and notify "launch_ntfy". The function MUST exit +once all workers, requested by "manager" have been launched. +"params" is a dictionary of all keyword arguments "addprocs" +was called with. """ launch doc""" -```rst -manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - Implemented by cluster managers. It is called on the master - process, during a worker's lifetime, with appropriate "op" - values: +Implemented by cluster managers. It is called on the master +process, during a worker's lifetime, with appropriate "op" +values: - * with ":register"/":deregister" when a worker is added / - removed from the Julia worker pool. + * with ":register"/":deregister" when a worker is added / + removed from the Julia worker pool. - * with ":interrupt" when "interrupt(workers)" is called. - The "ClusterManager" should signal the appropriate worker - with an interrupt signal. + * with ":interrupt" when "interrupt(workers)" is called. + The "ClusterManager" should signal the appropriate worker + with an interrupt signal. - * with ":finalize" for cleanup purposes. -``` + * with ":finalize" for cleanup purposes. """ manage doc""" -```rst -kill(manager::FooManager, pid::Int, config::WorkerConfig) + kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master - process, by "rmprocs". It should cause the remote worker - specified by "pid" to exit. - "Base.kill(manager::ClusterManager.....)" executes a remote - "exit()" on "pid" -``` +Implemented by cluster managers. It is called on the master +process, by "rmprocs". It should cause the remote worker +specified by "pid" to exit. +"Base.kill(manager::ClusterManager.....)" executes a remote +"exit()" on "pid" """ kill doc""" -```rst -init_worker(manager::FooManager) + init_worker(manager::FooManager) - Called by cluster managers implementing custom transports. It - initializes a newly launched process as a worker. Command line - argument "--worker" has the effect of initializing a process as a - worker using TCP/IP sockets for transport. -``` +Called by cluster managers implementing custom transports. It +initializes a newly launched process as a worker. Command line +argument "--worker" has the effect of initializing a process as a +worker using TCP/IP sockets for transport. """ init_worker doc""" -```rst -connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id "pid", specified - by "config" and return a pair of "AsyncStream" objects. - Messages from "pid" to current process will be read off - "instrm", while messages to be sent to "pid" will be written to - "outstrm". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - "Base.connect(manager::ClusterManager.....)" sets up TCP/IP - socket connections in-between workers. -``` +Implemented by cluster managers using custom transports. It should +establish a logical connection to worker with id "pid", specified +by "config" and return a pair of "AsyncStream" objects. +Messages from "pid" to current process will be read off +"instrm", while messages to be sent to "pid" will be written to +"outstrm". The custom transport implementation must ensure that +messages are delivered and received completely and in order. +"Base.connect(manager::ClusterManager.....)" sets up TCP/IP +socket connections in-between workers. """ connect doc""" -```rst -Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) - Called by cluster managers using custom transports. It should be - called when the custom transport implementation receives the first - message from a remote worker. The custom transport must manage a - logical connection to the remote worker and provide two AsyncStream - objects, one for incoming messages and the other for messages - addressed to the remote worker. -``` +Called by cluster managers using custom transports. It should be +called when the custom transport implementation receives the first +message from a remote worker. The custom transport must manage a +logical connection to the remote worker and provide two AsyncStream +objects, one for incoming messages and the other for messages +addressed to the remote worker. """ Base doc""" -```rst -dir() -> AbstractString + dir() -> AbstractString - Returns the absolute path of the package directory. This defaults - to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION - .minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell - syntax). If the "JULIA_PKGDIR" environment variable is set, then - that path is used in the returned value as "joinpath(ENV["JULIA_ - PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If - "JULIA_PKGDIR" is a relative path, it is interpreted relative to - whatever the current working directory is. -``` +Returns the absolute path of the package directory. This defaults +to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION +.minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell +syntax). If the "JULIA_PKGDIR" environment variable is set, then +that path is used in the returned value as "joinpath(ENV["JULIA_ +PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If +"JULIA_PKGDIR" is a relative path, it is interpreted relative to +whatever the current working directory is. """ Base.Pkg.dir doc""" -```rst -dir(names...) -> AbstractString + dir(names...) -> AbstractString - Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, "Pkg.dir(pkg)" returns the path to - the package "pkg". -``` +Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends +path components to the package directory and normalizes the +resulting path. In particular, "Pkg.dir(pkg)" returns the path to +the package "pkg". """ Base.Pkg.dir doc""" -```rst -init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) + init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - Initialize "Pkg.dir()" as a package directory. This will be done - automatically when the "JULIA_PKGDIR" is not set and - "Pkg.dir()" uses its default value. As part of this process, - clones a local METADATA git repository from the site and branch - specified by its arguments, which are typically not provided. - Explicit (non-default) arguments can be used to support a custom - METADATA setup. -``` +Initialize "Pkg.dir()" as a package directory. This will be done +automatically when the "JULIA_PKGDIR" is not set and +"Pkg.dir()" uses its default value. As part of this process, +clones a local METADATA git repository from the site and branch +specified by its arguments, which are typically not provided. +Explicit (non-default) arguments can be used to support a custom +METADATA setup. """ Base.Pkg.init doc""" -```rst -resolve() + resolve() - Determines an optimal, consistent set of package versions to - install or upgrade to. The optimal set of package versions is based - on the contents of "Pkg.dir("REQUIRE")" and the state of - installed packages in "Pkg.dir()", Packages that are no longer - required are moved into "Pkg.dir(".trash")". -``` +Determines an optimal, consistent set of package versions to +install or upgrade to. The optimal set of package versions is based +on the contents of "Pkg.dir("REQUIRE")" and the state of +installed packages in "Pkg.dir()", Packages that are no longer +required are moved into "Pkg.dir(".trash")". """ Base.Pkg.resolve doc""" -```rst -edit() + edit() - Opens "Pkg.dir("REQUIRE")" in the editor specified by the - "VISUAL" or "EDITOR" environment variables; when the editor - command returns, it runs "Pkg.resolve()" to determine and install - a new optimal set of installed package versions. -``` +Opens "Pkg.dir("REQUIRE")" in the editor specified by the +"VISUAL" or "EDITOR" environment variables; when the editor +command returns, it runs "Pkg.resolve()" to determine and install +a new optimal set of installed package versions. """ Base.Pkg.edit doc""" -```rst -add(pkg, vers...) + add(pkg, vers...) - Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and - call "Pkg.resolve()". If "vers" are given, they must be - "VersionNumber" objects and they specify acceptable version - intervals for "pkg". -``` +Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and +call "Pkg.resolve()". If "vers" are given, they must be +"VersionNumber" objects and they specify acceptable version +intervals for "pkg". """ Base.Pkg.add doc""" -```rst -rm(pkg) + rm(pkg) - Remove all requirement entries for "pkg" from - "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". -``` +Remove all requirement entries for "pkg" from +"Pkg.dir("REQUIRE")" and call "Pkg.resolve()". """ Base.Pkg.rm doc""" -```rst -clone(url[, pkg]) + clone(url[, pkg]) - Clone a package directly from the git URL "url". The package does - not need to be a registered in "Pkg.dir("METADATA")". The - package repo is cloned by the name "pkg" if provided; if not - provided, "pkg" is determined automatically from "url". -``` +Clone a package directly from the git URL "url". The package does +not need to be a registered in "Pkg.dir("METADATA")". The +package repo is cloned by the name "pkg" if provided; if not +provided, "pkg" is determined automatically from "url". """ Base.Pkg.clone doc""" -```rst -clone(pkg) + clone(pkg) - If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone - it from that URL on the default branch. The package does not need - to have any registered versions. -``` +If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone +it from that URL on the default branch. The package does not need +to have any registered versions. """ Base.Pkg.clone doc""" -```rst -available() -> Vector{ASCIIString} + available() -> Vector{ASCIIString} - Returns the names of available packages. -``` +Returns the names of available packages. """ Base.Pkg.available doc""" -```rst -available(pkg) -> Vector{VersionNumber} + available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package "pkg". -``` +Returns the version numbers available for package "pkg". """ Base.Pkg.available doc""" -```rst -installed() -> Dict{ASCIIString,VersionNumber} + installed() -> Dict{ASCIIString,VersionNumber} - Returns a dictionary mapping installed package names to the - installed version number of each package. -``` +Returns a dictionary mapping installed package names to the +installed version number of each package. """ Base.Pkg.installed doc""" -```rst -installed(pkg) -> Void | VersionNumber + installed(pkg) -> Void | VersionNumber - If "pkg" is installed, return the installed version number, - otherwise return "nothing". -``` +If "pkg" is installed, return the installed version number, +otherwise return "nothing". """ Base.Pkg.installed doc""" -```rst -status() + status() - Prints out a summary of what packages are installed and what - version and state they're in. -``` +Prints out a summary of what packages are installed and what +version and state they're in. """ Base.Pkg.status doc""" -```rst -update() + update() - Update package the metadata repo – kept in - "Pkg.dir("METADATA")" – then update any fixed packages that can - safely be pulled from their origin; then call "Pkg.resolve()" to - determine a new optimal set of packages versions. -``` +Update package the metadata repo – kept in +"Pkg.dir("METADATA")" – then update any fixed packages that can +safely be pulled from their origin; then call "Pkg.resolve()" to +determine a new optimal set of packages versions. """ Base.Pkg.update doc""" -```rst -checkout(pkg[, branch="master"]) + checkout(pkg[, branch="master"]) - Checkout the "Pkg.dir(pkg)" repo to the branch "branch". - Defaults to checking out the "master" branch. To go back to using - the newest compatible released version, use "Pkg.free(pkg)" -``` +Checkout the "Pkg.dir(pkg)" repo to the branch "branch". +Defaults to checking out the "master" branch. To go back to using +the newest compatible released version, use "Pkg.free(pkg)" """ Base.Pkg.checkout doc""" -```rst -pin(pkg) + pin(pkg) - Pin "pkg" at the current version. To go back to using the newest - compatible released version, use "Pkg.free(pkg)" -``` +Pin "pkg" at the current version. To go back to using the newest +compatible released version, use "Pkg.free(pkg)" """ Base.Pkg.pin doc""" -```rst -pin(pkg, version) + pin(pkg, version) - Pin "pkg" at registered version "version". -``` +Pin "pkg" at registered version "version". """ Base.Pkg.pin doc""" -```rst -free(pkg) + free(pkg) - Free the package "pkg" to be managed by the package manager - again. It calls "Pkg.resolve()" to determine optimal package - versions after. This is an inverse for both "Pkg.checkout" and - "Pkg.pin". +Free the package "pkg" to be managed by the package manager +again. It calls "Pkg.resolve()" to determine optimal package +versions after. This is an inverse for both "Pkg.checkout" and +"Pkg.pin". - You can also supply an iterable collection of package names, e.g., - "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at - once. -``` +You can also supply an iterable collection of package names, e.g., +"Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at +once. """ Base.Pkg.free doc""" -```rst -build() + build() - Run the build scripts for all installed packages in depth-first - recursive order. -``` +Run the build scripts for all installed packages in depth-first +recursive order. """ Base.Pkg.build doc""" -```rst -build(pkgs...) + build(pkgs...) - Run the build script in "deps/build.jl" for each package in - "pkgs" and all of their dependencies in depth-first recursive - order. This is called automatically by "Pkg.resolve()" on all - installed or updated packages. -``` +Run the build script in "deps/build.jl" for each package in +"pkgs" and all of their dependencies in depth-first recursive +order. This is called automatically by "Pkg.resolve()" on all +installed or updated packages. """ Base.Pkg.build doc""" -```rst -generate(pkg, license) + generate(pkg, license) - Generate a new package named "pkg" with one of these license - keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make - a package with a different license, you can edit it afterwards. - Generate creates a git repo at "Pkg.dir(pkg)" for the package and - inside it "LICENSE.md", "README.md", the julia entrypoint - "\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". -``` +Generate a new package named "pkg" with one of these license +keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make +a package with a different license, you can edit it afterwards. +Generate creates a git repo at "Pkg.dir(pkg)" for the package and +inside it "LICENSE.md", "README.md", the julia entrypoint +"\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". """ Base.Pkg.generate doc""" -```rst -register(pkg[, url]) + register(pkg[, url]) - Register "pkg" at the git URL "url", defaulting to the - configured origin URL of the git repo "Pkg.dir(pkg)". -``` +Register "pkg" at the git URL "url", defaulting to the +configured origin URL of the git repo "Pkg.dir(pkg)". """ Base.Pkg.register doc""" -```rst -tag(pkg[, ver[, commit]]) + tag(pkg[, ver[, commit]]) - Tag "commit" as version "ver" of package "pkg" and create a - version entry in "METADATA". If not provided, "commit" defaults - to the current commit of the "pkg" repo. If "ver" is one of the - symbols ":patch", ":minor", ":major" the next patch, minor or - major version is used. If "ver" is not provided, it defaults to - ":patch". -``` +Tag "commit" as version "ver" of package "pkg" and create a +version entry in "METADATA". If not provided, "commit" defaults +to the current commit of the "pkg" repo. If "ver" is one of the +symbols ":patch", ":minor", ":major" the next patch, minor or +major version is used. If "ver" is not provided, it defaults to +":patch". """ Base.Pkg.tag doc""" -```rst -publish() + publish() - For each new package version tagged in "METADATA" not already - published, make sure that the tagged package commits have been - pushed to the repo at the registered URL for the package and if - they all have, open a pull request to "METADATA". -``` +For each new package version tagged in "METADATA" not already +published, make sure that the tagged package commits have been +pushed to the repo at the registered URL for the package and if +they all have, open a pull request to "METADATA". """ Base.Pkg.publish doc""" -```rst -test() + test() - Run the tests for all installed packages ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its "test/runtests.jl" file - and test dependencies are specified in "test/REQUIRE". -``` +Run the tests for all installed packages ensuring that each +package's test dependencies are installed for the duration of the +test. A package is tested by running its "test/runtests.jl" file +and test dependencies are specified in "test/REQUIRE". """ Base.Pkg.test doc""" -```rst -test(pkgs...) + test(pkgs...) - Run the tests for each package in "pkgs" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its "test/runtests.jl" file - and test dependencies are specified in "test/REQUIRE". -``` +Run the tests for each package in "pkgs" ensuring that each +package's test dependencies are installed for the duration of the +test. A package is tested by running its "test/runtests.jl" file +and test dependencies are specified in "test/REQUIRE". """ Base.Pkg.test doc""" -```rst -@profile() + @profile() - "@profile " runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. -``` +"@profile " runs your expression while taking +periodic backtraces. These are appended to an internal buffer of +backtraces. """ @profile doc""" -```rst -clear() + clear() - Clear any existing backtraces from the internal buffer. -``` +Clear any existing backtraces from the internal buffer. """ Base.Profile.clear doc""" -```rst -print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) - Prints profiling results to "io" (by default, "STDOUT"). If you - do not supply a "data" vector, the internal buffer of accumulated - backtraces will be used. "format" can be ":tree" or ":flat". - If "C==true", backtraces from C and Fortran code are shown. - "combine==true" merges instruction pointers that correspond to - the same line of code. "cols" controls the width of the display. -``` +Prints profiling results to "io" (by default, "STDOUT"). If you +do not supply a "data" vector, the internal buffer of accumulated +backtraces will be used. "format" can be ":tree" or ":flat". +If "C==true", backtraces from C and Fortran code are shown. +"combine==true" merges instruction pointers that correspond to +the same line of code. "cols" controls the width of the display. """ Base.Profile.print doc""" -```rst -print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to "io". This variant is used to examine - results exported by a previous call to "retrieve()". Supply the - vector "data" of backtraces and a dictionary "lidict" of line - information. -``` +Prints profiling results to "io". This variant is used to examine +results exported by a previous call to "retrieve()". Supply the +vector "data" of backtraces and a dictionary "lidict" of line +information. """ Base.Profile.print doc""" -```rst -init(; n::Integer, delay::Float64) + init(; n::Integer, delay::Float64) - Configure the "delay" between backtraces (measured in seconds), - and the number "n" of instruction pointers that may be stored. - Each instruction pointer corresponds to a single line of code; - backtraces generally consist of a long list of instruction - pointers. Default settings can be obtained by calling this function - with no arguments, and each can be set independently using keywords - or in the order "(n, delay)". -``` +Configure the "delay" between backtraces (measured in seconds), +and the number "n" of instruction pointers that may be stored. +Each instruction pointer corresponds to a single line of code; +backtraces generally consist of a long list of instruction +pointers. Default settings can be obtained by calling this function +with no arguments, and each can be set independently using keywords +or in the order "(n, delay)". """ Base.Profile.init doc""" -```rst -fetch() -> data + fetch() -> data - Returns a reference to the internal buffer of backtraces. Note that - subsequent operations, like "clear()", can affect "data" unless - you first make a copy. Note that the values in "data" have - meaning only on this machine in the current session, because it - depends on the exact memory addresses used in JIT-compiling. This - function is primarily for internal use; "retrieve()" may be a - better choice for most users. -``` +Returns a reference to the internal buffer of backtraces. Note that +subsequent operations, like "clear()", can affect "data" unless +you first make a copy. Note that the values in "data" have +meaning only on this machine in the current session, because it +depends on the exact memory addresses used in JIT-compiling. This +function is primarily for internal use; "retrieve()" may be a +better choice for most users. """ Base.Profile.fetch doc""" -```rst -retrieve() -> data, lidict + retrieve() -> data, lidict - "Exports" profiling results in a portable format, returning the - set of all backtraces ("data") and a dictionary that maps the - (session-specific) instruction pointers in "data" to "LineInfo" - values that store the file name, function name, and line number. - This function allows you to save profiling results for future - analysis. -``` +"Exports" profiling results in a portable format, returning the +set of all backtraces ("data") and a dictionary that maps the +(session-specific) instruction pointers in "data" to "LineInfo" +values that store the file name, function name, and line number. +This function allows you to save profiling results for future +analysis. """ Base.Profile.retrieve doc""" -```rst -callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} + callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - Given a previous profiling run, determine who called a particular - function. Supplying the filename (and optionally, range of line - numbers over which the function is defined) allows you to - disambiguate an overloaded method. The returned value is a vector - containing a count of the number of calls and line information - about the caller. One can optionally supply backtrace data - obtained from "retrieve()"; otherwise, the current internal - profile buffer is used. -``` +Given a previous profiling run, determine who called a particular +function. Supplying the filename (and optionally, range of line +numbers over which the function is defined) allows you to +disambiguate an overloaded method. The returned value is a vector +containing a count of the number of calls and line information +about the caller. One can optionally supply backtrace data +obtained from "retrieve()"; otherwise, the current internal +profile buffer is used. """ Base.Profile.callers doc""" -```rst -clear_malloc_data() + clear_malloc_data() - Clears any stored memory allocation data when running julia with " - --track-allocation". Execute the command(s) you want to test (to - force JIT-compilation), then call "clear_malloc_data()". Then - execute your command(s) again, quit Julia, and examine the - resulting "*.mem" files. -``` +Clears any stored memory allocation data when running julia with " +--track-allocation". Execute the command(s) you want to test (to +force JIT-compilation), then call "clear_malloc_data()". Then +execute your command(s) again, quit Julia, and examine the +resulting "*.mem" files. """ Base.Profile.clear_malloc_data doc""" -```rst -sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the vector "v" in place. "QuickSort" is used by default - for numeric arrays while "MergeSort" is used for other arrays. - You can specify an algorithm to use via the "alg" keyword (see - Sorting Algorithms for available algorithms). The "by" keyword - lets you provide a function that will be applied to each element - before comparison; the "lt" keyword allows providing a custom - "less than" function; use "rev=true" to reverse the sorting - order. These options are independent and can be used together in - all possible combinations: if both "by" and "lt" are specified, - the "lt" function is applied to the result of the "by" - function; "rev=true" reverses whatever ordering specified via the - "by" and "lt" keywords. -``` +Sort the vector "v" in place. "QuickSort" is used by default +for numeric arrays while "MergeSort" is used for other arrays. +You can specify an algorithm to use via the "alg" keyword (see +Sorting Algorithms for available algorithms). The "by" keyword +lets you provide a function that will be applied to each element +before comparison; the "lt" keyword allows providing a custom +"less than" function; use "rev=true" to reverse the sorting +order. These options are independent and can be used together in +all possible combinations: if both "by" and "lt" are specified, +the "lt" function is applied to the result of the "by" +function; "rev=true" reverses whatever ordering specified via the +"by" and "lt" keywords. """ sort! doc""" -```rst -sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + sort(v, [alg=,] [by=,] [lt=,] [rev=false]) - Variant of "sort!" that returns a sorted copy of "v" leaving - "v" itself unmodified. -``` +Variant of "sort!" that returns a sorted copy of "v" leaving +"v" itself unmodified. """ sort doc""" -```rst -sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array "A" along the given dimension. -``` +Sort a multidimensional array "A" along the given dimension. """ sort doc""" -```rst -sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - Return a permutation vector of indices of "v" that puts it in - sorted order. Specify "alg" to choose a particular sorting - algorithm (see Sorting Algorithms). "MergeSort" is used by - default, and since it is stable, the resulting permutation will be - the lexicographically first one that puts the input array into - sorted order – i.e. indices of equal elements appear in ascending - order. If you choose a non-stable sorting algorithm such as - "QuickSort", a different permutation that puts the array into - order may be returned. The order is specified using the same - keywords as "sort!". +Return a permutation vector of indices of "v" that puts it in +sorted order. Specify "alg" to choose a particular sorting +algorithm (see Sorting Algorithms). "MergeSort" is used by +default, and since it is stable, the resulting permutation will be +the lexicographically first one that puts the input array into +sorted order – i.e. indices of equal elements appear in ascending +order. If you choose a non-stable sorting algorithm such as +"QuickSort", a different permutation that puts the array into +order may be returned. The order is specified using the same +keywords as "sort!". - See also "sortperm!()" -``` +See also "sortperm!()" """ sortperm doc""" -```rst -sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - Like "sortperm", but accepts a preallocated index vector "ix". - If "initialized" is "false" (the default), ix is initialized to - contain the values "1:length(v)". +Like "sortperm", but accepts a preallocated index vector "ix". +If "initialized" is "false" (the default), ix is initialized to +contain the values "1:length(v)". - See also "sortperm()" -``` +See also "sortperm()" """ sortperm! doc""" -```rst -sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the rows of matrix "A" lexicographically. -``` +Sort the rows of matrix "A" lexicographically. """ sortrows doc""" -```rst -sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the columns of matrix "A" lexicographically. -``` +Sort the columns of matrix "A" lexicographically. """ sortcols doc""" -```rst -issorted(v, [by=,] [lt=,] [rev=false]) + issorted(v, [by=,] [lt=,] [rev=false]) - Test whether a vector is in sorted order. The "by", "lt" and - "rev" keywords modify what order is considered to be sorted just - as they do for "sort". -``` +Test whether a vector is in sorted order. The "by", "lt" and +"rev" keywords modify what order is considered to be sorted just +as they do for "sort". """ issorted doc""" -```rst -searchsorted(a, x, [by=,] [lt=,] [rev=false]) + searchsorted(a, x, [by=,] [lt=,] [rev=false]) - Returns the range of indices of "a" which compare as equal to - "x" according to the order specified by the "by", "lt" and - "rev" keywords, assuming that "a" is already sorted in that - order. Returns an empty range located at the insertion point if - "a" does not contain values equal to "x". -``` +Returns the range of indices of "a" which compare as equal to +"x" according to the order specified by the "by", "lt" and +"rev" keywords, assuming that "a" is already sorted in that +order. Returns an empty range located at the insertion point if +"a" does not contain values equal to "x". """ searchsorted doc""" -```rst -searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the first value in "a" greater than or equal - to "x", according to the specified order. Returns "length(a)+1" - if "x" is greater than all values in "a". -``` +Returns the index of the first value in "a" greater than or equal +to "x", according to the specified order. Returns "length(a)+1" +if "x" is greater than all values in "a". """ searchsortedfirst doc""" -```rst -searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the last value in "a" less than or equal to - "x", according to the specified order. Returns "0" if "x" is - less than all values in "a". -``` +Returns the index of the last value in "a" less than or equal to +"x", according to the specified order. Returns "0" if "x" is +less than all values in "a". """ searchsortedlast doc""" -```rst -select!(v, k, [by=,] [lt=,] [rev=false]) + select!(v, k, [by=,] [lt=,] [rev=false]) - Partially sort the vector "v" in place, according to the order - specified by "by", "lt" and "rev" so that the value at index - "k" (or range of adjacent values if "k" is a range) occurs at - the position where it would appear if the array were fully sorted - via a non-stable algorithm. If "k" is a single index, that value - is returned; if "k" is a range, an array of values at those - indices is returned. Note that "select!" does not fully sort the - input array. -``` +Partially sort the vector "v" in place, according to the order +specified by "by", "lt" and "rev" so that the value at index +"k" (or range of adjacent values if "k" is a range) occurs at +the position where it would appear if the array were fully sorted +via a non-stable algorithm. If "k" is a single index, that value +is returned; if "k" is a range, an array of values at those +indices is returned. Note that "select!" does not fully sort the +input array. """ select! doc""" -```rst -select(v, k, [by=,] [lt=,] [rev=false]) + select(v, k, [by=,] [lt=,] [rev=false]) - Variant of "select!" which copies "v" before partially sorting - it, thereby returning the same thing as "select!" but leaving - "v" unmodified. -``` +Variant of "select!" which copies "v" before partially sorting +it, thereby returning the same thing as "select!" but leaving +"v" unmodified. """ select doc""" -```rst -length(s) + length(s) - The number of characters in string "s". -``` +The number of characters in string "s". """ length doc""" -```rst -sizeof(s::AbstractString) + sizeof(s::AbstractString) - The number of bytes in string "s". -``` +The number of bytes in string "s". """ sizeof doc""" -```rst -*(s, t) + *(s, t) - Concatenate strings. The "*" operator is an alias to this - function. +Concatenate strings. The "*" operator is an alias to this +function. - julia> "Hello " * "world" - "Hello world" -``` + julia> "Hello " * "world" + "Hello world" """ Base.(:(*)) doc""" -```rst -^(s, n) + ^(s, n) - Repeat "n" times the string "s". The "^" operator is an alias - to this function. +Repeat "n" times the string "s". The "^" operator is an alias +to this function. - julia> "Test "^3 - "Test Test Test " -``` + julia> "Test "^3 + "Test Test Test " """ Base.(:(^)) doc""" -```rst -string(xs...) + string(xs...) - Create a string from any values using the "print" function. -``` +Create a string from any values using the "print" function. """ string doc""" -```rst -repr(x) + repr(x) - Create a string from any value using the "showall" function. -``` +Create a string from any value using the "showall" function. """ repr doc""" -```rst -bytestring(::Ptr{UInt8}[, length]) + bytestring(::Ptr{UInt8}[, length]) - Create a string from the address of a C (0-terminated) string - encoded in ASCII or UTF-8. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. -``` +Create a string from the address of a C (0-terminated) string +encoded in ASCII or UTF-8. A copy is made; the ptr can be safely +freed. If "length" is specified, the string does not have to be +0-terminated. """ bytestring doc""" -```rst -bytestring(s) + bytestring(s) - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. -``` +Convert a string to a contiguous byte array representation +appropriate for passing it to C functions. The string will be +encoded as either ASCII or UTF-8. """ bytestring doc""" -```rst -ascii(::Array{UInt8, 1}) + ascii(::Array{UInt8, 1}) - Create an ASCII string from a byte array. -``` +Create an ASCII string from a byte array. """ ascii doc""" -```rst -ascii(s) + ascii(s) - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). -``` +Convert a string to a contiguous ASCII string (all characters must +be valid ASCII characters). """ ascii doc""" -```rst -ascii(::Ptr{UInt8}[, length]) + ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. -``` +Create an ASCII string from the address of a C (0-terminated) +string encoded in ASCII. A copy is made; the ptr can be safely +freed. If "length" is specified, the string does not have to be +0-terminated. """ ascii doc""" -```rst -utf8(::Array{UInt8, 1}) + utf8(::Array{UInt8, 1}) - Create a UTF-8 string from a byte array. -``` +Create a UTF-8 string from a byte array. """ utf8 doc""" -```rst -utf8(::Ptr{UInt8}[, length]) + utf8(::Ptr{UInt8}[, length]) - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - "length" is specified, the string does not have to be - 0-terminated. -``` +Create a UTF-8 string from the address of a C (0-terminated) string +encoded in UTF-8. A copy is made; the ptr can be safely freed. If +"length" is specified, the string does not have to be +0-terminated. """ utf8 doc""" -```rst -utf8(s) + utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). -``` +Convert a string to a contiguous UTF-8 string (all characters must +be valid UTF-8 characters). """ utf8 doc""" -```rst -normalize_string(s, normalform::Symbol) + normalize_string(s, normalform::Symbol) - Normalize the string "s" according to one of the four "normal - forms" of the Unicode standard: "normalform" can be ":NFC", - ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical - composition) and D (canonical decomposition) convert different - visually identical representations of the same abstract string into - a single canonical form, with form C being more compact. Normal - forms KC and KD additionally canonicalize "compatibility - equivalents": they convert characters that are abstractly similar - but visually distinct into a single canonical choice (e.g. they - expand ligatures into the individual characters), with form KC - being more compact. +Normalize the string "s" according to one of the four "normal +forms" of the Unicode standard: "normalform" can be ":NFC", +":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical +composition) and D (canonical decomposition) convert different +visually identical representations of the same abstract string into +a single canonical form, with form C being more compact. Normal +forms KC and KD additionally canonicalize "compatibility +equivalents": they convert characters that are abstractly similar +but visually distinct into a single canonical choice (e.g. they +expand ligatures into the individual characters), with form KC +being more compact. - Alternatively, finer control and additional transformations may be - be obtained by calling *normalize_string(s; keywords...)*, where - any number of the following boolean keywords options (which all - default to "false" except for "compose") are specified: +Alternatively, finer control and additional transformations may be +be obtained by calling *normalize_string(s; keywords...)*, where +any number of the following boolean keywords options (which all +default to "false" except for "compose") are specified: - * "compose=false": do not perform canonical composition +* "compose=false": do not perform canonical composition - * "decompose=true": do canonical decomposition instead of - canonical composition ("compose=true" is ignored if present) +* "decompose=true": do canonical decomposition instead of + canonical composition ("compose=true" is ignored if present) - * "compat=true": compatibility equivalents are canonicalized +* "compat=true": compatibility equivalents are canonicalized - * "casefold=true": perform Unicode case folding, e.g. for case- - insensitive string comparison +* "casefold=true": perform Unicode case folding, e.g. for case- + insensitive string comparison - * "newline2lf=true", "newline2ls=true", or - "newline2ps=true": convert various newline sequences (LF, CRLF, - CR, NEL) into a linefeed (LF), line-separation (LS), or - paragraph-separation (PS) character, respectively +* "newline2lf=true", "newline2ls=true", or + "newline2ps=true": convert various newline sequences (LF, CRLF, + CR, NEL) into a linefeed (LF), line-separation (LS), or + paragraph-separation (PS) character, respectively - * "stripmark=true": strip diacritical marks (e.g. accents) +* "stripmark=true": strip diacritical marks (e.g. accents) - * "stripignore=true": strip Unicode's "default ignorable" - characters (e.g. the soft hyphen or the left-to-right marker) +* "stripignore=true": strip Unicode's "default ignorable" + characters (e.g. the soft hyphen or the left-to-right marker) - * "stripcc=true": strip control characters; horizontal tabs and - form feeds are converted to spaces; newlines are also converted - to spaces unless a newline-conversion flag was specified +* "stripcc=true": strip control characters; horizontal tabs and + form feeds are converted to spaces; newlines are also converted + to spaces unless a newline-conversion flag was specified - * "rejectna=true": throw an error if unassigned code points are - found +* "rejectna=true": throw an error if unassigned code points are + found - * "stable=true": enforce Unicode Versioning Stability +* "stable=true": enforce Unicode Versioning Stability - For example, NFKC corresponds to the options "compose=true, - compat=true, stable=true". -``` +For example, NFKC corresponds to the options "compose=true, +compat=true, stable=true". """ normalize_string doc""" -```rst -graphemes(s) -> iterator over substrings of s + graphemes(s) -> iterator over substrings of s - Returns an iterator over substrings of "s" that correspond to the - extended graphemes in the string, as defined by Unicode UAX #29. - (Roughly, these are what users would perceive as single characters, - even though they may contain more than one codepoint; for example a - letter combined with an accent mark is a single grapheme.) -``` +Returns an iterator over substrings of "s" that correspond to the +extended graphemes in the string, as defined by Unicode UAX #29. +(Roughly, these are what users would perceive as single characters, +even though they may contain more than one codepoint; for example a +letter combined with an accent mark is a single grapheme.) """ graphemes doc""" -```rst -isvalid(value) -> Bool + isvalid(value) -> Bool - Returns true if the given value is valid for its type, which - currently can be one of "Char", "ASCIIString", "UTF8String", - "UTF16String", or "UTF32String" -``` +Returns true if the given value is valid for its type, which +currently can be one of "Char", "ASCIIString", "UTF8String", +"UTF16String", or "UTF32String" """ isvalid doc""" -```rst -isvalid(T, value) -> Bool + isvalid(T, value) -> Bool - Returns true if the given value is valid for that type. Types - currently can be "Char", "ASCIIString", "UTF8String", - "UTF16String", or "UTF32String" Values for "Char" can be of - type "Char" or "UInt32" Values for "ASCIIString" and - "UTF8String" can be of that type, or "Vector{UInt8}" Values for - "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values - for "UTF32String" can be "UTF32String", "Vector{Char}" or - "Vector{UInt32}" -``` +Returns true if the given value is valid for that type. Types +currently can be "Char", "ASCIIString", "UTF8String", +"UTF16String", or "UTF32String" Values for "Char" can be of +type "Char" or "UInt32" Values for "ASCIIString" and +"UTF8String" can be of that type, or "Vector{UInt8}" Values for +"UTF16String" can be "UTF16String" or "Vector{UInt16}" Values +for "UTF32String" can be "UTF32String", "Vector{Char}" or +"Vector{UInt32}" """ isvalid doc""" -```rst -is_assigned_char(c) -> Bool + is_assigned_char(c) -> Bool - Returns true if the given char or integer is an assigned Unicode - code point. -``` +Returns true if the given char or integer is an assigned Unicode +code point. """ is_assigned_char doc""" -```rst -ismatch(r::Regex, s::AbstractString) -> Bool + ismatch(r::Regex, s::AbstractString) -> Bool - Test whether a string contains a match of the given regular - expression. -``` +Test whether a string contains a match of the given regular +expression. """ ismatch doc""" -```rst -match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - Search for the first match of the regular expression "r" in "s" - and return a RegexMatch object containing the match, or nothing if - the match failed. The matching substring can be retrieved by - accessing "m.match" and the captured sequences can be retrieved - by accessing "m.captures" The optional "idx" argument specifies - an index at which to start the search. -``` +Search for the first match of the regular expression "r" in "s" +and return a RegexMatch object containing the match, or nothing if +the match failed. The matching substring can be retrieved by +accessing "m.match" and the captured sequences can be retrieved +by accessing "m.captures" The optional "idx" argument specifies +an index at which to start the search. """ match doc""" -```rst -eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - Search for all matches of a the regular expression "r" in "s" - and return a iterator over the matches. If overlap is true, the - matching sequences are allowed to overlap indices in the original - string, otherwise they must be from distinct character ranges. -``` +Search for all matches of a the regular expression "r" in "s" +and return a iterator over the matches. If overlap is true, the +matching sequences are allowed to overlap indices in the original +string, otherwise they must be from distinct character ranges. """ eachmatch doc""" -```rst -matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - Return a vector of the matching substrings from eachmatch. -``` +Return a vector of the matching substrings from eachmatch. """ matchall doc""" -```rst -lpad(string, n, p) + lpad(string, n, p) - Make a string at least "n" columns wide when printed, by padding - on the left with copies of "p". -``` +Make a string at least "n" columns wide when printed, by padding +on the left with copies of "p". """ lpad doc""" -```rst -rpad(string, n, p) + rpad(string, n, p) - Make a string at least "n" columns wide when printed, by padding - on the right with copies of "p". -``` +Make a string at least "n" columns wide when printed, by padding +on the right with copies of "p". """ rpad doc""" -```rst -search(string, chars[, start]) + search(string, chars[, start]) - Search for the first occurrence of the given characters within the - given string. The second argument may be a single character, a - vector or a set of characters, a string, or a regular expression - (though regular expressions are only allowed on contiguous strings, - such as ASCII or UTF-8 strings). The third argument optionally - specifies a starting index. The return value is a range of indexes - where the matching sequence is found, such that "s[search(s,x)] == - x": +Search for the first occurrence of the given characters within the +given string. The second argument may be a single character, a +vector or a set of characters, a string, or a regular expression +(though regular expressions are only allowed on contiguous strings, +such as ASCII or UTF-8 strings). The third argument optionally +specifies a starting index. The return value is a range of indexes +where the matching sequence is found, such that "s[search(s,x)] == +x": - "search(string, "substring")" = "start:end" such that - "string[start:end] == "substring"", or "0:-1" if unmatched. +"search(string, "substring")" = "start:end" such that +"string[start:end] == "substring"", or "0:-1" if unmatched. - "search(string, 'c')" = "index" such that - "string[index] == 'c'", or "0" if unmatched. -``` +"search(string, 'c')" = "index" such that +"string[index] == 'c'", or "0" if unmatched. """ search doc""" -```rst -rsearch(string, chars[, start]) + rsearch(string, chars[, start]) - Similar to "search", but returning the last occurrence of the - given characters within the given string, searching in reverse from - "start". -``` +Similar to "search", but returning the last occurrence of the +given characters within the given string, searching in reverse from +"start". """ rsearch doc""" -```rst -searchindex(string, substring[, start]) + searchindex(string, substring[, start]) - Similar to "search", but return only the start index at which the - substring is found, or 0 if it is not. -``` +Similar to "search", but return only the start index at which the +substring is found, or 0 if it is not. """ searchindex doc""" -```rst -rsearchindex(string, substring[, start]) + rsearchindex(string, substring[, start]) - Similar to "rsearch", but return only the start index at which - the substring is found, or 0 if it is not. -``` +Similar to "rsearch", but return only the start index at which +the substring is found, or 0 if it is not. """ rsearchindex doc""" -```rst -contains(haystack, needle) + contains(haystack, needle) - Determine whether the second argument is a substring of the first. -``` +Determine whether the second argument is a substring of the first. """ contains doc""" -```rst -replace(string, pat, r[, n]) + replace(string, pat, r[, n]) - Search for the given pattern "pat", and replace each occurrence - with "r". If "n" is provided, replace at most "n" - occurrences. As with search, the second argument may be a single - character, a vector or a set of characters, a string, or a regular - expression. If "r" is a function, each occurrence is replaced - with "r(s)" where "s" is the matched substring. -``` +Search for the given pattern "pat", and replace each occurrence +with "r". If "n" is provided, replace at most "n" +occurrences. As with search, the second argument may be a single +character, a vector or a set of characters, a string, or a regular +expression. If "r" is a function, each occurrence is replaced +with "r(s)" where "s" is the matched substring. """ replace doc""" -```rst -split(string, [chars]; limit=0, keep=true) + split(string, [chars]; limit=0, keep=true) - Return an array of substrings by splitting the given string on - occurrences of the given character delimiters, which may be - specified in any of the formats allowed by "search"'s second - argument (i.e. a single character, collection of characters, - string, or regular expression). If "chars" is omitted, it - defaults to the set of all space characters, and "keep" is taken - to be false. The two keyword arguments are optional: they are are a - maximum size for the result and a flag determining whether empty - fields should be kept in the result. -``` +Return an array of substrings by splitting the given string on +occurrences of the given character delimiters, which may be +specified in any of the formats allowed by "search"'s second +argument (i.e. a single character, collection of characters, +string, or regular expression). If "chars" is omitted, it +defaults to the set of all space characters, and "keep" is taken +to be false. The two keyword arguments are optional: they are are a +maximum size for the result and a flag determining whether empty +fields should be kept in the result. """ split doc""" -```rst -rsplit(string, [chars]; limit=0, keep=true) + rsplit(string, [chars]; limit=0, keep=true) - Similar to "split", but starting from the end of the string. -``` +Similar to "split", but starting from the end of the string. """ rsplit doc""" -```rst -strip(string[, chars]) + strip(string[, chars]) - Return "string" with any leading and trailing whitespace removed. - If "chars" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. -``` +Return "string" with any leading and trailing whitespace removed. +If "chars" (a character, or vector or set of characters) is +provided, instead remove characters contained in it. """ strip doc""" -```rst -lstrip(string[, chars]) + lstrip(string[, chars]) - Return "string" with any leading whitespace removed. If "chars" - (a character, or vector or set of characters) is provided, instead - remove characters contained in it. -``` +Return "string" with any leading whitespace removed. If "chars" +(a character, or vector or set of characters) is provided, instead +remove characters contained in it. """ lstrip doc""" -```rst -rstrip(string[, chars]) + rstrip(string[, chars]) - Return "string" with any trailing whitespace removed. If - "chars" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. -``` +Return "string" with any trailing whitespace removed. If +"chars" (a character, or vector or set of characters) is +provided, instead remove characters contained in it. """ rstrip doc""" -```rst -startswith(string, prefix | chars) + startswith(string, prefix | chars) - Returns "true" if "string" starts with "prefix". If the - second argument is a vector or set of characters, tests whether the - first character of "string" belongs to that set. -``` +Returns "true" if "string" starts with "prefix". If the +second argument is a vector or set of characters, tests whether the +first character of "string" belongs to that set. """ startswith doc""" -```rst -endswith(string, suffix | chars) + endswith(string, suffix | chars) - Returns "true" if "string" ends with "suffix". If the second - argument is a vector or set of characters, tests whether the last - character of "string" belongs to that set. -``` +Returns "true" if "string" ends with "suffix". If the second +argument is a vector or set of characters, tests whether the last +character of "string" belongs to that set. """ endswith doc""" -```rst -uppercase(string) + uppercase(string) - Returns "string" with all characters converted to uppercase. -``` +Returns "string" with all characters converted to uppercase. """ uppercase doc""" -```rst -lowercase(string) + lowercase(string) - Returns "string" with all characters converted to lowercase. -``` +Returns "string" with all characters converted to lowercase. """ lowercase doc""" -```rst -ucfirst(string) + ucfirst(string) - Returns "string" with the first character converted to uppercase. -``` +Returns "string" with the first character converted to uppercase. """ ucfirst doc""" -```rst -lcfirst(string) + lcfirst(string) - Returns "string" with the first character converted to lowercase. -``` +Returns "string" with the first character converted to lowercase. """ lcfirst doc""" -```rst -join(strings, delim[, last]) + join(strings, delim[, last]) - Join an array of "strings" into a single string, inserting the - given delimiter between adjacent strings. If "last" is given, it - will be used instead of "delim" between the last two strings. For - example, "join(["apples", "bananas", "pineapples"], ", ", - " and ") == "apples, bananas and pineapples"". +Join an array of "strings" into a single string, inserting the +given delimiter between adjacent strings. If "last" is given, it +will be used instead of "delim" between the last two strings. For +example, "join(["apples", "bananas", "pineapples"], ", ", +" and ") == "apples, bananas and pineapples"". - "strings" can be any iterable over elements "x" which are - convertible to strings via "print(io::IOBuffer, x)". -``` +"strings" can be any iterable over elements "x" which are +convertible to strings via "print(io::IOBuffer, x)". """ join doc""" -```rst -chop(string) + chop(string) - Remove the last character from a string -``` +Remove the last character from a string """ chop doc""" -```rst -chomp(string) + chomp(string) - Remove a trailing newline from a string -``` +Remove a trailing newline from a string """ chomp doc""" -```rst -ind2chr(string, i) + ind2chr(string, i) - Convert a byte index to a character index -``` +Convert a byte index to a character index """ ind2chr doc""" -```rst -chr2ind(string, i) + chr2ind(string, i) - Convert a character index to a byte index -``` +Convert a character index to a byte index """ chr2ind doc""" -```rst -isvalid(str, i) + isvalid(str, i) - Tells whether index "i" is valid for the given string -``` +Tells whether index "i" is valid for the given string """ isvalid doc""" -```rst -nextind(str, i) + nextind(str, i) - Get the next valid string index after "i". Returns a value - greater than "endof(str)" at or after the end of the string. -``` +Get the next valid string index after "i". Returns a value +greater than "endof(str)" at or after the end of the string. """ nextind doc""" -```rst -prevind(str, i) + prevind(str, i) - Get the previous valid string index before "i". Returns a value - less than "1" at the beginning of the string. -``` +Get the previous valid string index before "i". Returns a value +less than "1" at the beginning of the string. """ prevind doc""" -```rst -randstring([rng], len=8) + randstring([rng], len=8) - Create a random ASCII string of length "len", consisting of - upper- and lower-case letters and the digits 0-9. The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. -``` +Create a random ASCII string of length "len", consisting of +upper- and lower-case letters and the digits 0-9. The optional +"rng" argument specifies a random number generator, see *Random +Numbers*. """ randstring doc""" -```rst -charwidth(c) + charwidth(c) - Gives the number of columns needed to print a character. -``` +Gives the number of columns needed to print a character. """ charwidth doc""" -```rst -strwidth(s) + strwidth(s) - Gives the number of columns needed to print a string. -``` +Gives the number of columns needed to print a string. """ strwidth doc""" -```rst -isalnum(c::Union{Char, AbstractString}) -> Bool + isalnum(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphanumeric, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter or - Number, i.e. a character whose category code begins with 'L' or - 'N'. -``` +Tests whether a character is alphanumeric, or whether this is true +for all elements of a string. A character is classified as +alphabetic if it belongs to the Unicode general category Letter or +Number, i.e. a character whose category code begins with 'L' or +'N'. """ isalnum doc""" -```rst -isalpha(c::Union{Char, AbstractString}) -> Bool + isalpha(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphabetic, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter, - i.e. a character whose category code begins with 'L'. -``` +Tests whether a character is alphabetic, or whether this is true +for all elements of a string. A character is classified as +alphabetic if it belongs to the Unicode general category Letter, +i.e. a character whose category code begins with 'L'. """ isalpha doc""" -```rst -isascii(c::Union{Char, AbstractString}) -> Bool + isascii(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the ASCII character set, or - whether this is true for all elements of a string. -``` +Tests whether a character belongs to the ASCII character set, or +whether this is true for all elements of a string. """ isascii doc""" -```rst -iscntrl(c::Union{Char, AbstractString}) -> Bool + iscntrl(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a control character, or whether this - is true for all elements of a string. Control characters are the - non-printing characters of the Latin-1 subset of Unicode. -``` +Tests whether a character is a control character, or whether this +is true for all elements of a string. Control characters are the +non-printing characters of the Latin-1 subset of Unicode. """ iscntrl doc""" -```rst -isdigit(c::Union{Char, AbstractString}) -> Bool + isdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a numeric digit (0-9), or whether this - is true for all elements of a string. -``` +Tests whether a character is a numeric digit (0-9), or whether this +is true for all elements of a string. """ isdigit doc""" -```rst -isgraph(c::Union{Char, AbstractString}) -> Bool + isgraph(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, and not a space, or whether - this is true for all elements of a string. Any character that - would cause a printer to use ink should be classified with - isgraph(c)==true. -``` +Tests whether a character is printable, and not a space, or whether +this is true for all elements of a string. Any character that +would cause a printer to use ink should be classified with +isgraph(c)==true. """ isgraph doc""" -```rst -islower(c::Union{Char, AbstractString}) -> Bool + islower(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a lowercase letter, or whether this is - true for all elements of a string. A character is classified as - lowercase if it belongs to Unicode category Ll, Letter: Lowercase. -``` +Tests whether a character is a lowercase letter, or whether this is +true for all elements of a string. A character is classified as +lowercase if it belongs to Unicode category Ll, Letter: Lowercase. """ islower doc""" -```rst -isnumber(c::Union{Char, AbstractString}) -> Bool + isnumber(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is numeric, or whether this is true for - all elements of a string. A character is classified as numeric if - it belongs to the Unicode general category Number, i.e. a character - whose category code begins with 'N'. -``` +Tests whether a character is numeric, or whether this is true for +all elements of a string. A character is classified as numeric if +it belongs to the Unicode general category Number, i.e. a character +whose category code begins with 'N'. """ isnumber doc""" -```rst -isprint(c::Union{Char, AbstractString}) -> Bool + isprint(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, including spaces, but not a - control character. For strings, tests whether this is true for all - elements of the string. -``` +Tests whether a character is printable, including spaces, but not a +control character. For strings, tests whether this is true for all +elements of the string. """ isprint doc""" -```rst -ispunct(c::Union{Char, AbstractString}) -> Bool + ispunct(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the Unicode general category - Punctuation, i.e. a character whose category code begins with 'P'. - For strings, tests whether this is true for all elements of the - string. -``` +Tests whether a character belongs to the Unicode general category +Punctuation, i.e. a character whose category code begins with 'P'. +For strings, tests whether this is true for all elements of the +string. """ ispunct doc""" -```rst -isspace(c::Union{Char, AbstractString}) -> Bool + isspace(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is any whitespace character. Includes - ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', - Latin-1 character U+0085, and characters in Unicode category Zs. - For strings, tests whether this is true for all elements of the - string. -``` +Tests whether a character is any whitespace character. Includes +ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', +Latin-1 character U+0085, and characters in Unicode category Zs. +For strings, tests whether this is true for all elements of the +string. """ isspace doc""" -```rst -isupper(c::Union{Char, AbstractString}) -> Bool + isupper(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is an uppercase letter, or whether this - is true for all elements of a string. A character is classified - as uppercase if it belongs to Unicode category Lu, Letter: - Uppercase, or Lt, Letter: Titlecase. -``` +Tests whether a character is an uppercase letter, or whether this +is true for all elements of a string. A character is classified +as uppercase if it belongs to Unicode category Lu, Letter: +Uppercase, or Lt, Letter: Titlecase. """ isupper doc""" -```rst -isxdigit(c::Union{Char, AbstractString}) -> Bool + isxdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a valid hexadecimal digit, or whether - this is true for all elements of a string. -``` +Tests whether a character is a valid hexadecimal digit, or whether +this is true for all elements of a string. """ isxdigit doc""" -```rst -symbol(x...) -> Symbol + symbol(x...) -> Symbol - Create a "Symbol" by concatenating the string representations of - the arguments together. -``` +Create a "Symbol" by concatenating the string representations of +the arguments together. """ symbol doc""" -```rst -escape_string(str::AbstractString) -> AbstractString + escape_string(str::AbstractString) -> AbstractString - General escaping of traditional C and Unicode escape sequences. See - "print_escaped()" for more general escaping. -``` +General escaping of traditional C and Unicode escape sequences. See +"print_escaped()" for more general escaping. """ escape_string doc""" -```rst -unescape_string(s::AbstractString) -> AbstractString + unescape_string(s::AbstractString) -> AbstractString - General unescaping of traditional C and Unicode escape sequences. - Reverse of "escape_string()". See also "print_unescaped()". -``` +General unescaping of traditional C and Unicode escape sequences. +Reverse of "escape_string()". See also "print_unescaped()". """ unescape_string doc""" -```rst -utf16(s) + utf16(s) - Create a UTF-16 string from a byte array, array of "UInt16", or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) +Create a UTF-16 string from a byte array, array of "UInt16", or +any other string type. (Data must be valid UTF-16. Conversions of +byte arrays check for a byte-order marker in the first two bytes, +and do not include it in the resulting string.) - Note that the resulting "UTF16String" data is terminated by the - NUL codepoint (16-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf16(s)* conversion function. If you have a "UInt16" array - "A" that is already NUL-terminated valid UTF-16 data, then you - can instead use *UTF16String(A)`* to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. -``` +Note that the resulting "UTF16String" data is terminated by the +NUL codepoint (16-bit zero), which is not treated as a character in +the string (so that it is mostly invisible in Julia); this allows +the string to be passed directly to external functions requiring +NUL-terminated data. This NUL is appended automatically by the +*utf16(s)* conversion function. If you have a "UInt16" array +"A" that is already NUL-terminated valid UTF-16 data, then you +can instead use *UTF16String(A)`* to construct the string without +making a copy of the data and treating the NUL as a terminator +rather than as part of the string. """ utf16 doc""" -```rst -utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If "length" is - specified, the string does not have to be NUL-terminated. -``` +Create a string from the address of a NUL-terminated UTF-16 string. +A copy is made; the pointer can be safely freed. If "length" is +specified, the string does not have to be NUL-terminated. """ utf16 doc""" -```rst -utf32(s) + utf32(s) - Create a UTF-32 string from a byte array, array of "Char" or - "UInt32", or any other string type. (Conversions of byte arrays - check for a byte-order marker in the first four bytes, and do not - include it in the resulting string.) +Create a UTF-32 string from a byte array, array of "Char" or +"UInt32", or any other string type. (Conversions of byte arrays +check for a byte-order marker in the first four bytes, and do not +include it in the resulting string.) - Note that the resulting "UTF32String" data is terminated by the - NUL codepoint (32-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf32(s)* conversion function. If you have a "Char" or - "UInt32" array "A" that is already NUL-terminated UTF-32 data, - then you can instead use *UTF32String(A)`* to construct the string - without making a copy of the data and treating the NUL as a - terminator rather than as part of the string. -``` +Note that the resulting "UTF32String" data is terminated by the +NUL codepoint (32-bit zero), which is not treated as a character in +the string (so that it is mostly invisible in Julia); this allows +the string to be passed directly to external functions requiring +NUL-terminated data. This NUL is appended automatically by the +*utf32(s)* conversion function. If you have a "Char" or +"UInt32" array "A" that is already NUL-terminated UTF-32 data, +then you can instead use *UTF32String(A)`* to construct the string +without making a copy of the data and treating the NUL as a +terminator rather than as part of the string. """ utf32 doc""" -```rst -utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) + utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) - Create a string from the address of a NUL-terminated UTF-32 string. - A copy is made; the pointer can be safely freed. If "length" is - specified, the string does not have to be NUL-terminated. -``` +Create a string from the address of a NUL-terminated UTF-32 string. +A copy is made; the pointer can be safely freed. If "length" is +specified, the string does not have to be NUL-terminated. """ utf32 doc""" -```rst -wstring(s) + wstring(s) - This is a synonym for either "utf32(s)" or "utf16(s)", - depending on whether "Cwchar_t" is 32 or 16 bits, respectively. - The synonym "WString" for "UTF32String" or "UTF16String" is - also provided. -``` +This is a synonym for either "utf32(s)" or "utf16(s)", +depending on whether "Cwchar_t" is 32 or 16 bits, respectively. +The synonym "WString" for "UTF32String" or "UTF16String" is +also provided. """ wstring doc""" -```rst -runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) + runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) - Run the Julia unit tests listed in "tests", which can be either a - string or an array of strings, using "numcores" processors. (not - exported) -``` +Run the Julia unit tests listed in "tests", which can be either a +string or an array of strings, using "numcores" processors. (not +exported) """ runtests doc""" -```rst -@test(ex) + @test(ex) - Test the expression "ex" and calls the current handler to handle - the result. -``` +Test the expression "ex" and calls the current handler to handle +the result. """ Base.Test.@test doc""" -```rst -@test_throws(extype, ex) + @test_throws(extype, ex) - Test that the expression "ex" throws an exception of type - "extype" and calls the current handler to handle the result. -``` +Test that the expression "ex" throws an exception of type +"extype" and calls the current handler to handle the result. """ Base.Test.@test_throws doc""" -```rst -@test_approx_eq(a, b) + @test_approx_eq(a, b) - Test two floating point numbers "a" and "b" for equality taking - in account small numerical errors. -``` +Test two floating point numbers "a" and "b" for equality taking +in account small numerical errors. """ Base.Test.@test_approx_eq doc""" -```rst -@test_approx_eq_eps(a, b, tol) + @test_approx_eq_eps(a, b, tol) - Test two floating point numbers "a" and "b" for equality taking - in account a margin of tolerance given by "tol". -``` +Test two floating point numbers "a" and "b" for equality taking +in account a margin of tolerance given by "tol". """ Base.Test.@test_approx_eq_eps doc""" -```rst -with_handler(f, handler) + with_handler(f, handler) - Run the function "f" using the "handler" as the handler. -``` +Run the function "f" using the "handler" as the handler. """ Base.Test.with_handler + diff --git a/doc/markdown.jl b/doc/markdown.jl new file mode 100644 index 0000000000000..ddf3aa6426e94 --- /dev/null +++ b/doc/markdown.jl @@ -0,0 +1,25 @@ +open("base/docs/helpdb2.jl", "w") do io + rst = false + sig = false + for l in split(readall("base/docs/helpdb.jl"), "\n") + if l == "```rst" + rst = true + sig = true + elseif l == "```" + rst = false + elseif sig == true + println(io, " ", l) + sig = false + elseif rst + if startswith(l, " ") + println(io, l[3:end]) + elseif startswith(l, " ") + println(io, l[4:end]) + else + println(io, l) + end + else + println(io, l) + end + end +end From bf8786b57cc291e30ab198409af85dd954bd1134 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 22:28:08 -0400 Subject: [PATCH 23/27] regen --- doc/stdlib/arrays.rst | 819 +++++++++---------- doc/stdlib/base.rst | 1038 +++++++++++------------- doc/stdlib/c.rst | 180 ++--- doc/stdlib/collections.rst | 1119 +++++++++++++------------- doc/stdlib/dates.rst | 283 +++---- doc/stdlib/file.rst | 269 +++---- doc/stdlib/io-network.rst | 731 +++++++---------- doc/stdlib/libc.rst | 80 +- doc/stdlib/libdl.rst | 42 +- doc/stdlib/linalg.rst | 1230 +++++++++++------------------ doc/stdlib/math.rst | 1531 ++++++++---------------------------- doc/stdlib/numbers.rst | 436 +++++----- doc/stdlib/parallel.rst | 396 ++++------ doc/stdlib/pkg.rst | 149 ++-- doc/stdlib/profile.rst | 63 +- doc/stdlib/sort.rst | 84 +- doc/stdlib/strings.rst | 415 ++++------ doc/stdlib/test.rst | 24 +- 18 files changed, 3496 insertions(+), 5393 deletions(-) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index fee28971e8fbf..dcc0697227fe4 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -9,68 +9,66 @@ Basic functions .. function:: ndims(A) -> Integer - Returns the number of dimensions of A + Returns the number of dimensions of A + .. function:: size(A[, 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.: + 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 = rand(2,3,4); - julia> A = rand(2,3,4); + julia> size(A, 2) + 3 - julia> size(A, 2) - 3 + julia> size(A,3,2) + (4,3) - julia> size(A,3,2) - (4,3) .. function:: iseltype(A, T) - Tests whether A or its elements are of type T + Tests whether A or its elements are of type T + .. function:: length(s) - The number of characters in string "s". + The number of characters in string "s". + .. function:: 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 (like "Array"), this is - simply the range "1: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 non-integer indices). - - Example for a sparse 2-d array: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 + 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 (like "Array"), this is simply the range "1: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 non-integer indices). + + Example for a sparse 2-d array: + + :: + + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 + If you supply more than one ``AbstractArray`` argument, ``eachindex`` will create an iterable object that is fast for all arguments (a @@ -81,161 +79,149 @@ largest range along each dimension. .. function:: Base.linearindexing(A) - ``linearindexing`` defines how an AbstractArray most efficiently accesses its elements. If ``Base.linearindexing(A)`` returns ``Base.LinearFast()``, this means that linear indexing with only one index is an efficient operation. If it instead returns ``Base.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 traits-based mechanism to enable efficient generic code for all array types. + "linearindexing" defines how an AbstractArray most efficiently accesses its elements. If "Base.linearindexing(A)" returns "Base.LinearFast()", this means that linear indexing with only one index is an efficient operation. If it instead returns "Base.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 traits-based 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 define "linearindexing" in the type-domain: - An abstract array subtype ``MyArray`` that wishes to opt into fast linear indexing behaviors should define ``linearindexing`` in the type-domain:: + :: Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() + .. function:: countnz(A) - Counts the number of nonzero values in array A (dense or sparse). - Note that this is not a constant-time operation. For sparse - matrices, one should usually use "nnz", which returns the number - of stored values. + Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use "nnz", which returns the number of stored values. + .. function:: conj!(A) - Convert an array to its complex conjugate in-place + Convert an array to its complex conjugate in-place + .. function:: stride(A, k) - Returns the distance in memory (in number of elements) between - adjacent elements in dimension k + Returns the distance in memory (in number of elements) between adjacent elements in dimension k + .. function:: strides(A) - Returns a tuple of the memory strides in each dimension + Returns a tuple of the memory strides in each dimension + .. function:: ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array "a" corresponding to the - linear index "index" + Returns a tuple of subscripts into array "a" corresponding to the linear index "index" + .. function:: ind2sub(a, index) -> subscripts - Returns a tuple of subscripts into array "a" corresponding to the - linear index "index" + Returns a tuple of subscripts into array "a" corresponding to the linear index "index" + .. function:: sub2ind(dims, i, j, k...) -> index - The inverse of "ind2sub", returns the linear index corresponding - to the provided subscripts + The inverse of "ind2sub", returns the linear index corresponding to the provided subscripts + Constructors ------------ .. function:: Array(dims) - "Array{T}(dims)" constructs an uninitialized dense array with - element type "T". "dims" may be a tuple or a series of integer - arguments. The syntax "Array(T, dims)" is also available, but - deprecated. + "Array{T}(dims)" constructs an uninitialized dense array with element type "T". "dims" may be a tuple or a series of integer arguments. The syntax "Array(T, dims)" is also available, but deprecated. + .. function:: 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, ...)". + 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, ...)". + .. function:: cell(dims) - Construct an uninitialized cell array (heterogeneous array). - "dims" can be either a tuple or a series of integer arguments. + Construct an uninitialized cell array (heterogeneous array). "dims" can be either a tuple or a series of integer arguments. + .. function:: zeros(A) - Create an array of all zeros with the same element type and shape - as A. + Create an array of all zeros with the same element type and shape as A. + .. function:: zeros(A) - Create an array of all zeros with the same element type and shape - as A. + Create an array of all zeros with the same element type and shape as A. + .. function:: ones(A) - Create an array of all ones with the same element type and shape as - A. + Create an array of all ones with the same element type and shape as A. + .. function:: ones(A) - Create an array of all ones with the same element type and shape as - A. + Create an array of all ones with the same element type and shape as A. + .. function:: trues(dims) - Create a "BitArray" with all values set to true + Create a "BitArray" with all values set to true + .. function:: falses(dims) - Create a "BitArray" with all values set to false + Create a "BitArray" with all values set to false + .. function:: fill(x, dims) - Create an array filled with the value "x". For example, - "fill(1.0, (10,10))" returns a 10x10 array of floats, with each - element initialized to 1.0. + Create an array filled with the value "x". For example, "fill(1.0, (10,10))" returns a 10x10 array of floats, with each element initialized to 1.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 evaluating "Foo()" once. - 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 evaluating "Foo()" once. .. function:: fill!(A, x) - Fill array "A" with the value "x". If "x" is an object - reference, all elements will refer to the same object. "fill!(A, - Foo())" will return "A" filled with the result of evaluating - "Foo()" once. + Fill array "A" with the value "x". If "x" is an object reference, all elements will refer to the same object. "fill!(A, Foo())" will return "A" filled with the result of evaluating "Foo()" once. + .. function:: reshape(A, dims) - Create an array with the same data as the given array, but with - different dimensions. An implementation for a particular type of - array may choose whether the data is copied or shared. + Create an array with the same data as the given array, but with different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. + .. function:: similar(array, element_type, dims) - Create an uninitialized array of the same type as the given array, - but with the specified element type and dimensions. The second and - third arguments are both optional. The "dims" argument may be a - tuple or a series of integer arguments. For some special - "AbstractArray" objects which are not real containers (like - ranges), this function returns a standard "Array" to allow - operating on elements. + Create an uninitialized array of the same type as the given array, but with the specified element type and dimensions. The second and third arguments are both optional. The "dims" argument may be a tuple or a series of integer arguments. For some special "AbstractArray" objects which are not real containers (like ranges), this function returns a standard "Array" to allow operating on elements. + .. function:: reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, - "reinterpret(Float32, UInt32(7))" interprets the 4 bytes - corresponding to "UInt32(7)" as a "Float32". For arrays, this - constructs an array with the same binary data as the given array, - but with the specified element type. + Change the type-interpretation of a block of memory. For example, "reinterpret(Float32, UInt32(7))" interprets the 4 bytes corresponding to "UInt32(7)" as a "Float32". For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. + .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as - "A". + Constructs an identity matrix of the same dimensions and type as "A". + .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as - "A". + Constructs an identity matrix of the same dimensions and type as "A". + .. function:: eye(A) - Constructs an identity matrix of the same dimensions and type as - "A". + Constructs an identity matrix of the same dimensions and type as "A". + .. function:: linspace(start, stop, n=100) - Construct a range of "n" linearly spaced elements from "start" - to "stop". + Construct a range of "n" linearly spaced elements from "start" to "stop". + .. function:: logspace(start, stop, n=50) - Construct a vector of "n" logarithmically spaced numbers from - "10^start" to "10^stop". + Construct a vector of "n" logarithmically spaced numbers from "10^start" to "10^stop". + Mathematical operators and functions ------------------------------------ @@ -244,563 +230,499 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) - Broadcasts the arrays "As" to a common size by expanding - singleton dimensions, and returns an array of the results - "f(as...)" for each position. + Broadcasts the arrays "As" to a common size by expanding singleton dimensions, and returns an array of the results "f(as...)" for each position. + .. function:: broadcast!(f, dest, As...) - Like "broadcast", but store the result of "broadcast(f, As...)" - in the "dest" array. Note that "dest" is only used to store the - result, and does not supply arguments to "f" unless it is also - listed in the "As", as in "broadcast!(f, A, A, B)" to perform - "A[:] = broadcast(f, A, B)". + Like "broadcast", but store the result of "broadcast(f, As...)" in the "dest" array. Note that "dest" is only used to store the result, and does not supply arguments to "f" unless it is also listed in the "As", as in "broadcast!(f, A, A, B)" to perform "A[:] = broadcast(f, A, B)". + .. function:: bitbroadcast(f, As...) - Like "broadcast", but allocates a "BitArray" to store the - result, rather then an "Array". + Like "broadcast", but allocates a "BitArray" to store the result, rather then an "Array". + .. function:: broadcast_function(f) - Returns a function "broadcast_f" such that - "broadcast_function(f)(As...) === broadcast(f, As...)". Most - useful in the form "const broadcast_f = broadcast_function(f)". + Returns a function "broadcast_f" such that "broadcast_function(f)(As...) === broadcast(f, As...)". Most useful in the form "const broadcast_f = broadcast_function(f)". + .. function:: broadcast!_function(f) - Like "broadcast_function", but for "broadcast!". + Like "broadcast_function", but for "broadcast!". + Indexing, Assignment, and Concatenation --------------------------------------- .. function:: 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, ...)". + 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, ...)". + .. function:: sub(A, inds...) - Like "getindex()", but returns a view into the parent array "A" - with the given indices instead of making a copy. Calling - "getindex()" or "setindex!()" on the returned "SubArray" - computes the indices to the parent array on the fly without - checking bounds. + Like "getindex()", but returns a view into the parent array "A" with the given indices instead of making a copy. Calling "getindex()" or "setindex!()" on the returned "SubArray" computes the indices to the parent array on the fly without checking bounds. + .. function:: parent(A) - Returns the "parent array" of an array view type (e.g., - SubArray), or the array itself if it is not a view + Returns the "parent array" of an array view type (e.g., SubArray), or the array itself if it is not a view + .. function:: parentindexes(A) - From an array view "A", returns the corresponding indexes in the - parent + From an array view "A", returns the corresponding indexes in the parent + .. function:: slicedim(A, d, i) - Return all the data of "A" where the index for dimension "d" - equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is - in position "d". + Return all the data of "A" where the index for dimension "d" equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is in position "d". + .. function:: slice(A, inds...) - Returns a view of array "A" with the given indices like - "sub()", but drops all dimensions indexed with scalars. + Returns a view of array "A" with the given indices like "sub()", but drops all dimensions indexed with scalars. + .. function:: 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, ...)". + 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, ...)". + .. function:: broadcast_getindex(A, inds...) - Broadcasts the "inds" arrays to a common size like "broadcast", - and returns an array of the results "A[ks...]", where "ks" goes - over the positions in the broadcast. + Broadcasts the "inds" arrays to a common size like "broadcast", and returns an array of the results "A[ks...]", where "ks" goes over the positions in the broadcast. + .. function:: broadcast_setindex!(A, X, inds...) - Broadcasts the "X" and "inds" arrays to a common size and - stores the value from each position in "X" at the indices given - by the same positions in "inds". + Broadcasts the "X" and "inds" arrays to a common size and stores the value from each position in "X" at the indices given by the same positions in "inds". + .. function:: cat(dims, A...) - Concatenate the input arrays along the specified dimensions in the - iterable "dims". For dimensions not in "dims", all input arrays - should have the same size, which will also be the size of the - output array along that dimension. For dimensions in "dims", the - size of the output array is the sum of the sizes of the input - arrays along that dimension. If "dims" is a single number, the - different arrays are tightly stacked along that dimension. If - "dims" is an iterable containing several dimensions, this allows - to construct block diagonal matrices and their higher-dimensional - 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 with *matrices[1]*, *matrices[2]*, ... as diagonal - blocks and matching zero blocks away from the diagonal. + Concatenate the input arrays along the specified dimensions in the iterable "dims". For dimensions not in "dims", all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in "dims", the size of the output array is the sum of the sizes of the input arrays along that dimension. If "dims" is a single number, the different arrays are tightly stacked along that dimension. If "dims" is an iterable containing several dimensions, this allows to construct block diagonal matrices and their higher-dimensional 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 with *matrices[1]*, *matrices[2]*, ... as diagonal blocks and matching zero blocks away from the diagonal. + .. function:: vcat(A...) - Concatenate along dimension 1 + Concatenate along dimension 1 + .. function:: hcat(A...) - Concatenate along dimension 2 + Concatenate along dimension 2 + .. function:: 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. For example, - "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". + 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. For example, "[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". + + If the first argument is a single integer "n", then all block rows are assumed to have "n" block columns. - If the first argument is a single integer "n", then all block - rows are assumed to have "n" block columns. .. function:: flipdim(A, d) - Reverse "A" in dimension "d". + Reverse "A" in dimension "d". + .. function:: circshift(A, shifts) - Circularly shift the data in an array. The second argument is a - vector giving the amount to shift in each dimension. + Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. + .. function:: find(f, A) - Return a vector of the linear indexes of "A" where "f" returns - true. + Return a vector of the linear indexes of "A" where "f" returns true. + .. function:: find(f, A) - Return a vector of the linear indexes of "A" where "f" returns - true. + Return a vector of the linear indexes of "A" where "f" returns true. + .. function:: findn(A) - Return a vector of indexes for each dimension giving the locations - of the non-zeros in "A" (determined by "A[i]!=0"). + Return a vector of indexes for each dimension giving the locations of the non-zeros in "A" (determined by "A[i]!=0"). + .. function:: findnz(A) - Return a tuple "(I, J, V)" where "I" and "J" are the row and - column indexes of the non-zero values in matrix "A", and "V" is - a vector of the non-zero values. + Return a tuple "(I, J, V)" where "I" and "J" are the row and column indexes of the non-zero values in matrix "A", and "V" is a vector of the non-zero values. + .. function:: findfirst(predicate, A) - Return the index of the first element of "A" for which - "predicate" returns true. + Return the index of the first element of "A" for which "predicate" returns true. + .. function:: findfirst(predicate, A) - Return the index of the first element of "A" for which - "predicate" returns true. + Return the index of the first element of "A" for which "predicate" returns true. + .. function:: findfirst(predicate, A) - Return the index of the first element of "A" for which - "predicate" returns true. + Return the index of the first element of "A" for which "predicate" returns true. + .. function:: findlast(predicate, A) - Return the index of the last element of "A" for which - "predicate" returns true. + Return the index of the last element of "A" for which "predicate" returns true. + .. function:: findlast(predicate, A) - Return the index of the last element of "A" for which - "predicate" returns true. + Return the index of the last element of "A" for which "predicate" returns true. + .. function:: findlast(predicate, A) - Return the index of the last element of "A" for which - "predicate" returns true. + Return the index of the last element of "A" for which "predicate" returns true. + .. function:: findnext(A, v, i) - Find the next index >= "i" of an element of "A" equal to "v" - (using "=="), or "0" if not found. + Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. + .. function:: findnext(A, v, i) - Find the next index >= "i" of an element of "A" equal to "v" - (using "=="), or "0" if not found. + Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. + .. function:: findnext(A, v, i) - Find the next index >= "i" of an element of "A" equal to "v" - (using "=="), or "0" if not found. + Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. + .. function:: findprev(A, v, i) - Find the previous index <= "i" of an element of "A" equal to - "v" (using "=="), or "0" if not found. + Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. + .. function:: findprev(A, v, i) - Find the previous index <= "i" of an element of "A" equal to - "v" (using "=="), or "0" if not found. + Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. + .. function:: findprev(A, v, i) - Find the previous index <= "i" of an element of "A" equal to - "v" (using "=="), or "0" if not found. + Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. + .. function:: permutedims(A, perm) - Permute the dimensions of array "A". "perm" is a vector - specifying a permutation of length "ndims(A)". This is a - generalization of transpose for multi-dimensional arrays. Transpose - is equivalent to "permutedims(A, [2,1])". + Permute the dimensions of array "A". "perm" is a vector specifying a permutation of length "ndims(A)". This is a generalization of transpose for multi-dimensional arrays. Transpose is equivalent to "permutedims(A, [2,1])". + .. function:: ipermutedims(A, perm) - Like "permutedims()", except the inverse of the given permutation - is applied. + Like "permutedims()", except the inverse of the given permutation is applied. + .. function:: permutedims!(dest, src, perm) - Permute the dimensions of array "src" and store the result in the - array "dest". "perm" is a vector specifying a permutation of - length "ndims(src)". The preallocated array "dest" should have - "size(dest) == size(src)[perm]" and is completely overwritten. No - in-place permutation is supported and unexpected results will - happen if *src* and *dest* have overlapping memory regions. + Permute the dimensions of array "src" and store the result in the array "dest". "perm" is a vector specifying a permutation of length "ndims(src)". The preallocated array "dest" should have "size(dest) == size(src)[perm]" and is completely overwritten. No in-place permutation is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + .. function:: squeeze(A, dims) - Remove the dimensions specified by "dims" from array "A". - Elements of "dims" must be unique and within the range - "1:ndims(A)". + Remove the dimensions specified by "dims" from array "A". Elements of "dims" must be unique and within the range "1:ndims(A)". + .. function:: vec(Array) -> Vector - Vectorize an array using column-major convention. + Vectorize an array using column-major convention. + .. function:: promote_shape(s1, s2) - Check two array shapes for compatibility, allowing trailing - singleton dimensions, and return whichever shape has more - dimensions. + Check two array shapes for compatibility, allowing trailing singleton dimensions, and return whichever shape has more dimensions. + .. function:: checkbounds(array, indexes...) - Throw an error if the specified indexes are not in bounds for the - given array. + Throw an error if the specified indexes are not in bounds for the given array. + .. function:: randsubseq(A, p) -> Vector - Return a vector consisting of a random subsequence of the given - array "A", where each element of "A" is included (in order) - with independent probability "p". (Complexity is linear in - "p*length(A)", so this function is efficient even if "p" is - small and "A" is large.) Technically, this process is known as - "Bernoulli sampling" of "A". + Return a vector consisting of a random subsequence of the given array "A", where each element of "A" is included (in order) with independent probability "p". (Complexity is linear in "p*length(A)", so this function is efficient even if "p" is small and "A" is large.) Technically, this process is known as "Bernoulli sampling" of "A". + .. function:: randsubseq!(S, A, p) - Like "randsubseq", but the results are stored in "S" (which is - resized as needed). + Like "randsubseq", but the results are stored in "S" (which is resized as needed). + Array functions --------------- .. function:: cumprod(A[, dim]) - Cumulative product along a dimension "dim" (defaults to 1). See - also "cumprod!()" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). + Cumulative product along a dimension "dim" (defaults to 1). See also "cumprod!()" to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). + .. function:: cumprod!(B, A[, dim]) - Cumulative product of "A" along a dimension, storing the result - in "B". The dimension defaults to 1. + Cumulative product of "A" along a dimension, storing the result in "B". The dimension defaults to 1. + .. function:: cumsum(A[, dim]) - Cumulative sum along a dimension "dim" (defaults to 1). See also - "cumsum!()" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). + Cumulative sum along a dimension "dim" (defaults to 1). See also "cumsum!()" to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). + .. function:: cumsum!(B, A[, dim]) - Cumulative sum of "A" along a dimension, storing the result in - "B". The dimension defaults to 1. + Cumulative sum of "A" along a dimension, storing the result in "B". The dimension defaults to 1. + .. function:: cumsum_kbn(A[, dim]) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. The - dimension defaults to 1. + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1. + .. function:: cummin(A[, dim]) - Cumulative minimum along a dimension. The dimension defaults to 1. + Cumulative minimum along a dimension. The dimension defaults to 1. + .. function:: cummax(A[, dim]) - Cumulative maximum along a dimension. The dimension defaults to 1. + Cumulative maximum along a dimension. The dimension defaults to 1. + .. function:: diff(A[, dim]) - Finite difference operator of matrix or vector. + Finite difference operator of matrix or vector. + .. function:: gradient(F[, h]) - Compute differences along vector "F", using "h" as the spacing - between points. The default spacing is one. + Compute differences along vector "F", using "h" as the spacing between points. The default spacing is one. + .. function:: rot180(A, k) - Rotate matrix "A" 180 degrees an integer "k" number of times. - If "k" is even, this is equivalent to a "copy". + Rotate matrix "A" 180 degrees an integer "k" number of times. If "k" is even, this is equivalent to a "copy". + .. function:: rot180(A, k) - Rotate matrix "A" 180 degrees an integer "k" number of times. - If "k" is even, this is equivalent to a "copy". + Rotate matrix "A" 180 degrees an integer "k" number of times. If "k" is even, this is equivalent to a "copy". + .. function:: rotl90(A, k) - Rotate matrix "A" left 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". + Rotate matrix "A" left 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". + .. function:: rotl90(A, k) - Rotate matrix "A" left 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". + Rotate matrix "A" left 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". + .. function:: rotr90(A, k) - Rotate matrix "A" right 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". + Rotate matrix "A" right 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". + .. function:: rotr90(A, k) - Rotate matrix "A" right 90 degrees an integer "k" number of - times. If "k" is zero or a multiple of four, this is equivalent - to a "copy". + Rotate matrix "A" right 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". + .. function:: reducedim(f, A, dims[, initial]) - Reduce 2-argument function "f" along dimensions of "A". - "dims" is a vector specifying the dimensions to reduce, and - "initial" is the initial value to use in the reductions. For *+*, - ***, *max* and *min* the *initial* argument is optional. + Reduce 2-argument function "f" along dimensions of "A". "dims" is a vector specifying the dimensions to reduce, and "initial" is the initial value to use in the reductions. For *+*, ***, *max* and *min* the *initial* argument is optional. + + The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for "reduce". - The associativity of the reduction is implementation-dependent; if - you need a particular associativity, e.g. left-to-right, you should - write your own loop. See documentation for "reduce". .. function:: mapreducedim(f, op, A, dims[, initial]) - Evaluates to the same as *reducedim(op, map(f, A), dims, - f(initial))*, but is generally faster because the intermediate - array is avoided. + Evaluates to the same as *reducedim(op, map(f, A), dims, f(initial))*, but is generally faster because the intermediate array is avoided. + .. function:: mapslices(f, A, dims) - Transform the given dimensions of array "A" using function "f". - "f" is called on each slice of "A" of the form - "A[...,:,...,:,...]". "dims" is an integer vector specifying - where the colons go in this expression. The results are - concatenated along the remaining dimensions. For example, if - "dims" is "[1,2]" and A is 4-dimensional, "f" is called on - "A[:,:,i,j]" for all "i" and "j". + Transform the given dimensions of array "A" using function "f". "f" is called on each slice of "A" of the form "A[...,:,...,:,...]". "dims" is an integer vector specifying where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if "dims" is "[1,2]" and A is 4-dimensional, "f" is called on "A[:,:,i,j]" for all "i" and "j". + .. function:: sum_kbn(A) - Returns the sum of all array elements, using the Kahan-Babuska- - Neumaier compensated summation algorithm for additional accuracy. + Returns the sum of all array elements, using the Kahan-Babuska- Neumaier compensated summation algorithm for additional accuracy. + .. function:: cartesianmap(f, dims) - Given a "dims" tuple of integers "(m, n, ...)", call "f" on - all combinations of integers in the ranges "1:m", "1:n", etc. + Given a "dims" tuple of integers "(m, n, ...)", call "f" on all combinations of integers in the ranges "1:m", "1:n", etc. + + :: + + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 Combinatorics ------------- .. function:: nthperm(p) - Return the "k" that generated permutation "p". Note that - "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". + Return the "k" that generated permutation "p". Note that "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". + .. function:: nthperm(p) - Return the "k" that generated permutation "p". Note that - "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". + Return the "k" that generated permutation "p". Note that "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". + .. function:: nthperm!(v, k) - In-place version of "nthperm()". + In-place version of "nthperm()". + .. function:: randperm([rng], n) - Construct a random permutation of length "n". The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. + Construct a random permutation of length "n". The optional "rng" argument specifies a random number generator, see *Random Numbers*. + .. function:: invperm(v) - Return the inverse permutation of v. + Return the inverse permutation of v. + .. function:: isperm(v) -> Bool - Returns true if v is a valid permutation. + Returns true if v is a valid permutation. + .. function:: permute!(v, p) - Permute vector "v" in-place, according to permutation "p". No - checking is done to verify that "p" is a permutation. + Permute vector "v" in-place, according to permutation "p". No checking is done to verify that "p" is a permutation. + + To return a new permutation, use "v[p]". Note that this is generally faster than "permute!(v,p)" for large vectors. - To return a new permutation, use "v[p]". Note that this is - generally faster than "permute!(v,p)" for large vectors. .. function:: ipermute!(v, p) - Like permute!, but the inverse of the given permutation is applied. + Like permute!, but the inverse of the given permutation is applied. + .. function:: randcycle([rng], n) - Construct a random cyclic permutation of length "n". The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. + Construct a random cyclic permutation of length "n". The optional "rng" argument specifies a random number generator, see *Random Numbers*. + .. function:: shuffle([rng], v) - Return a randomly permuted copy of "v". The optional "rng" - argument specifies a random number generator, see *Random Numbers*. + Return a randomly permuted copy of "v". The optional "rng" argument specifies a random number generator, see *Random Numbers*. + .. function:: shuffle!([rng], v) - In-place version of "shuffle()". + In-place version of "shuffle()". + .. function:: reverse(v[, start=1[, stop=length(v)]]) - Return a copy of "v" reversed from start to stop. + Return a copy of "v" reversed from start to stop. + .. function:: reverseind(v, i) - Given an index "i" in "reverse(v)", return the corresponding - index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". - (This can be nontrivial in the case where "v" is a Unicode - string.) + Given an index "i" in "reverse(v)", return the corresponding index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". (This can be nontrivial in the case where "v" is a Unicode string.) + .. function:: reverse!(v[, start=1[, stop=length(v)]]) -> v - In-place version of "reverse()". + In-place version of "reverse()". + .. function:: combinations(array, n) - Generate all combinations of "n" elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - "collect(combinations(array,n))" to get an array of all - combinations. + Generate all combinations of "n" elements from an indexable object. Because the number of combinations can be very large, this function returns an iterator object. Use "collect(combinations(array,n))" to get an array of all combinations. + .. function:: permutations(array) - Generate all permutations of an indexable object. Because the - number of permutations can be very large, this function returns an - iterator object. Use "collect(permutations(array))" to get an - array of all permutations. + Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use "collect(permutations(array))" to get an array of all permutations. + .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use "collect(partitions(array,m))" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using "length(partitions(array,m))". + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". + .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use "collect(partitions(array,m))" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using "length(partitions(array,m))". + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". + .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use "collect(partitions(array,m))" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using "length(partitions(array,m))". + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". + .. function:: partitions(array, m) - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use "collect(partitions(array,m))" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using "length(partitions(array,m))". + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". + BitArrays --------- .. function:: bitpack(A::AbstractArray{T, N}) -> BitArray - Converts a numeric array to a packed boolean array + Converts a numeric array to a packed boolean array + .. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} - Converts a packed boolean array to an array of booleans + Converts a packed boolean array to an array of booleans + .. function:: flipbits!(B::BitArray{N}) -> BitArray{N} - Performs a bitwise not operation on B. See *~ operator*. + Performs a bitwise not operation on B. See *~ operator*. + .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. + Performs a left rotation operation on B. + .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on B. + Performs a left rotation operation on B. + .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation. + Performs a left rotation operation. + .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. + Performs a right rotation operation on B. + .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on B. + Performs a right rotation operation on B. + .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation. + Performs a right rotation operation. + .. _stdlib-sparse: @@ -811,146 +733,117 @@ Sparse matrices support much of the same set of operations as dense matrices. Th .. function:: sparse(A) - Convert an AbstractMatrix "A" into a sparse matrix. + Convert an AbstractMatrix "A" into a sparse matrix. + .. function:: sparsevec(A) - Convert a dense vector "A" into a sparse matrix of size "m x - 1". In julia, sparse vectors are really just sparse matrices with - one column. + Convert a dense vector "A" into a sparse matrix of size "m x 1". In julia, sparse vectors are really just sparse matrices with one column. + .. function:: sparsevec(A) - Convert a dense vector "A" into a sparse matrix of size "m x - 1". In julia, sparse vectors are really just sparse matrices with - one column. + Convert a dense vector "A" into a sparse matrix of size "m x 1". In julia, sparse vectors are really just sparse matrices with one column. + .. function:: issparse(S) - Returns "true" if "S" is sparse, and "false" otherwise. + Returns "true" if "S" is sparse, and "false" otherwise. + .. function:: sparse(A) - Convert an AbstractMatrix "A" into a sparse matrix. + Convert an AbstractMatrix "A" into a sparse matrix. + .. function:: sparsevec(A) - Convert a dense vector "A" into a sparse matrix of size "m x - 1". In julia, sparse vectors are really just sparse matrices with - one column. + Convert a dense vector "A" into a sparse matrix of size "m x 1". In julia, sparse vectors are really just sparse matrices with one column. + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a - "QRCompactWYQ" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. + Converts an orthogonal or unitary matrix stored as a "QRCompactWYQ" object, i.e. in the compact WY format [Bischof1987], to a dense matrix. + + Optionally takes a "thin" Boolean argument, which if "true" omits the columns that span the rows of "R" in the QR factorization that are zero. The resulting matrix is the "Q" in a thin QR factorization (sometimes called the reduced QR factorization). If "false", returns a "Q" that spans all rows of "R" in its corresponding QR factorization. - Optionally takes a "thin" Boolean argument, which if "true" - omits the columns that span the rows of "R" in the QR - factorization that are zero. The resulting matrix is the "Q" in a - thin QR factorization (sometimes called the reduced QR - factorization). If "false", returns a "Q" that spans all rows - of "R" in its corresponding QR factorization. .. function:: nnz(A) - Returns the number of stored (filled) elements in a sparse matrix. + Returns the number of stored (filled) elements in a sparse matrix. + .. function:: spzeros(m, n) - Create a sparse matrix of size "m x n". This sparse matrix will - not contain any nonzero values. No storage will be allocated for - nonzero values during construction. + Create a sparse matrix of size "m x n". This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. + .. function:: spones(S) - Create a sparse matrix with the same structure as that of "S", - but with every nonzero element having the value "1.0". + Create a sparse matrix with the same structure as that of "S", but with every nonzero element having the value "1.0". + .. function:: speye(type, m[, n]) - Create a sparse identity matrix of specified type of size "m x - m". In case "n" is supplied, create a sparse identity matrix of - size "m x n". + Create a sparse identity matrix of specified type of size "m x m". In case "n" is supplied, create a sparse identity matrix of size "m x n". + .. function:: spdiagm(B, d[, m, n]) - Construct a sparse diagonal matrix. "B" is a tuple of vectors - containing the diagonals and "d" is a tuple containing the - positions of the diagonals. In the case the input contains only one - diagonaly, "B" can be a vector (instead of a tuple) and "d" can - be the diagonal position (instead of a tuple), defaulting to 0 - (diagonal). Optionally, "m" and "n" specify the size of the - resulting sparse matrix. + Construct a sparse diagonal matrix. "B" is a tuple of vectors containing the diagonals and "d" is a tuple containing the positions of the diagonals. In the case the input contains only one diagonaly, "B" can be a vector (instead of a tuple) and "d" can be the diagonal position (instead of a tuple), defaulting to 0 (diagonal). Optionally, "m" and "n" specify the size of the resulting sparse matrix. + .. function:: sprand([rng], m, n, p[, rfn]) - Create a random "m" by "n" sparse matrix, in which the - probability of any element being nonzero is independently given by - "p" (and hence the mean density of nonzeros is also exactly - "p"). Nonzero values are sampled from the distribution specified - by "rfn". The uniform distribution is used in case "rfn" is not - specified. The optional "rng" argument specifies a random number - generator, see *Random Numbers*. + Create a random "m" by "n" sparse matrix, in which the probability of any element being nonzero is independently given by "p" (and hence the mean density of nonzeros is also exactly "p"). Nonzero values are sampled from the distribution specified by "rfn". The uniform distribution is used in case "rfn" is not specified. The optional "rng" argument specifies a random number generator, see *Random Numbers*. + .. function:: sprandn(m, n, p) - Create a random "m" by "n" sparse matrix with the specified - (independent) probability "p" of any entry being nonzero, where - nonzero values are sampled from the normal distribution. + Create a random "m" by "n" sparse matrix with the specified (independent) probability "p" of any entry being nonzero, where nonzero values are sampled from the normal distribution. + .. function:: sprandbool(m, n, p) - Create a random "m" by "n" sparse boolean matrix with the - specified (independent) probability "p" of any entry being - "true". + Create a random "m" by "n" sparse boolean matrix with the specified (independent) probability "p" of any entry being "true". + .. function:: etree(A[, post]) - Compute the elimination tree of a symmetric sparse matrix "A" - from "triu(A)" and, optionally, its post-ordering permutation. + Compute the elimination tree of a symmetric sparse matrix "A" from "triu(A)" and, optionally, its post-ordering permutation. + .. function:: symperm(A, p) - Return the symmetric permutation of A, which is "A[p,p]". A - should be symmetric and sparse, where only the upper triangular - part of the matrix is stored. This algorithm ignores the lower - triangular part of the matrix. Only the upper triangular part of - the result is returned as well. + Return the symmetric permutation of A, which is "A[p,p]". A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. + .. function:: nonzeros(A) - Return a vector of the structural nonzero values in sparse matrix - "A". This includes zeros that are explicitly stored in the sparse - matrix. The returned vector points directly to the internal nonzero - storage of "A", and any modifications to the returned vector will - mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". + Return a vector of the structural nonzero values in sparse matrix "A". This includes zeros that are explicitly stored in the sparse matrix. The returned vector points directly to the internal nonzero storage of "A", and any modifications to the returned vector will mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". + .. function:: rowvals(A) - Return a vector of the row indices of "A", and any modifications - to the returned vector will mutate "A" as well. Given the - internal storage format of sparse matrices, providing access to how - the row indices are stored internally can be useful in conjuction - with iterating over structural nonzero values. See "nonzeros(A)" - and "nzrange(A, col)". + Return a vector of the row indices of "A", and any modifications to the returned vector will mutate "A" as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See "nonzeros(A)" and "nzrange(A, col)". + .. function:: nzrange(A, col) - Return the range of indices to the structural nonzero values of a - sparse matrix column. In conjunction with "nonzeros(A)" and - "rowvals(A)", 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 + Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with "nonzeros(A)" and "rowvals(A)", 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 + diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 335f60b0822fd..aa1091e26f8c2 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -22,96 +22,85 @@ Getting Around .. function:: exit([code]) - Quit (or control-D at the prompt). The default exit code is zero, - indicating that the processes completed successfully. + Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. + .. function:: quit() - Quit the program indicating that the processes completed - successfully. This function calls "exit(0)" (see "exit()"). + Quit the program indicating that the processes completed successfully. This function calls "exit(0)" (see "exit()"). + .. function:: atexit(f) - Register a zero-argument function to be called at exit. + Register a zero-argument function to be called at exit. + .. function:: atreplinit(f) - Register a one-argument function to be called before the REPL - interface is initialized in interactive sessions; this is useful to - customize the interface. The argument of "f" is the REPL object. - This function should be called from within the ".juliarc.jl" - initialization file. + Register a one-argument function to be called before the REPL interface is initialized in interactive sessions; this is useful to customize the interface. The argument of "f" is the REPL object. This function should be called from within the ".juliarc.jl" initialization file. + .. function:: isinteractive() -> Bool - Determine whether Julia is running an interactive session. + Determine whether Julia is running an interactive session. + .. function:: whos([Module,] [pattern::Regex]) - Print information about exported global variables in a module, - optionally restricted to those matching "pattern". + Print information about exported global variables in a module, optionally restricted to those matching "pattern". + .. function:: edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. + Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. + .. function:: edit(function[, types]) - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. + Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. + .. function:: @edit() - Evaluates the arguments to the function call, determines their - types, and calls the "edit" function on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls the "edit" function on the resulting expression + .. function:: less(function[, types]) - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. + Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. + .. function:: less(function[, types]) - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. + Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. + .. function:: @less() - Evaluates the arguments to the function call, determines their - types, and calls the "less" function on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls the "less" function on the resulting expression + .. function:: clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard - ("paste"). + Return a string with the contents of the operating system clipboard ("paste"). + .. function:: clipboard() -> AbstractString - Return a string with the contents of the operating system clipboard - ("paste"). + Return a string with the contents of the operating system clipboard ("paste"). + .. function:: require(file::AbstractString...) - Load source files once, in the context of the "Main" module, on - every active node, searching standard locations for files. - "require" is considered a top-level operation, so it sets the - current "include" path but does not use it to search for files - (see help for "include"). This function is typically used to load - library code, and is implicitly called by "using" to load - packages. + Load source files once, in the context of the "Main" module, on every active node, searching standard locations for files. "require" is considered a top-level operation, so it sets the current "include" path but does not use it to search for files (see help for "include"). This function is typically used to load library code, and is implicitly called by "using" to load packages. + + When searching for files, "require" first looks in the current working directory, then looks for package code under "Pkg.dir()", then tries paths in the global array "LOAD_PATH". - When searching for files, "require" first looks in the current - working directory, then looks for package code under "Pkg.dir()", - then tries paths in the global array "LOAD_PATH". .. function:: reload(file::AbstractString) - Like "require", except forces loading of files regardless of - whether they have been loaded before. Typically used when - interactively developing libraries. + Like "require", except forces loading of files regardless of whether they have been loaded before. Typically used when interactively developing libraries. + .. function:: include("file.jl") @@ -120,9 +109,8 @@ Getting Around .. function:: include_string(code::AbstractString) - Like "include", except reads code from the given string rather - than from a file. Since there is no file path involved, no path - processing or fetching from node 1 is done. + Like "include", except reads code from the given string rather than from a file. Since there is no file path involved, no path processing or fetching from node 1 is done. + .. function:: help(name) @@ -134,56 +122,49 @@ Getting Around .. function:: which(symbol) - Return the module in which the binding for the variable referenced - by "symbol" was created. + Return the module in which the binding for the variable referenced by "symbol" was created. + .. function:: which(symbol) - Return the module in which the binding for the variable referenced - by "symbol" was created. + Return the module in which the binding for the variable referenced by "symbol" was created. + .. function:: @which() - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the "Method" object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the "which" function. + Applied to a function call, it evaluates the arguments to the specified function call, and returns the "Method" object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the "which" function. + .. function:: methods(f[, types]) - Returns the method table for "f". + Returns the method table for "f". + + If "types" is specified, returns an array of methods whose types match. - If "types" is specified, returns an array of methods whose types - match. .. function:: methodswith(typ[, module or function][, showparents]) - Return an array of methods with an argument of type "typ". If - optional "showparents" is "true", also return arguments with a - parent type of "typ", excluding type "Any". + Return an array of methods with an argument of type "typ". If optional "showparents" is "true", also return arguments with a parent type of "typ", excluding type "Any". + + The optional second argument restricts the search to a particular module or function. - The optional second argument restricts the search to a particular - module or function. .. function:: @show() - Show an expression and result, returning the result + Show an expression and result, returning the result + .. function:: versioninfo([verbose::Bool]) - Print information about the version of Julia in use. If the - "verbose" argument is true, detailed system information is shown - as well. + Print information about the version of Julia in use. If the "verbose" argument is true, detailed system information is shown as well. + .. function:: workspace() - Replace the top-level module ("Main") with a new one, providing a - clean workspace. The previous "Main" module is made available as - "LastMain". A previously-loaded package can be accessed using a - statement such as "using LastMain.Package". + Replace the top-level module ("Main") with a new one, providing a clean workspace. The previous "Main" module is made available as "LastMain". A previously-loaded package can be accessed using a statement such as "using LastMain.Package". + + This function should only be used interactively. - This function should only be used interactively. .. data:: ans @@ -195,348 +176,311 @@ All Objects .. function:: ===(x, y) + ≡(x, y) + + See the "is()" operator - See the "is()" operator .. function:: isa(x, type) -> Bool - Determine whether "x" is of the given "type". + Determine whether "x" is of the given "type". + .. function:: isequal(x, y) - Similar to "==", except treats all floating-point "NaN" values - as equal to each other, and treats "-0.0" as unequal to "0.0". - The default implementation of "isequal" calls "==", so if you - have a type that doesn't have these floating-point subtleties then - you probably only need to define "==". + Similar to "==", except treats all floating-point "NaN" values as equal to each other, and treats "-0.0" as unequal to "0.0". The default implementation of "isequal" calls "==", so if you have a type that doesn't have these floating-point subtleties then you probably only need to define "==". - "isequal" is the comparison function used by hash tables - ("Dict"). "isequal(x,y)" must imply that "hash(x) == - hash(y)". + "isequal" is the comparison function used by hash tables ("Dict"). "isequal(x,y)" must imply that "hash(x) == hash(y)". - This typically means that if you define your own "==" function - then you must define a corresponding "hash" (and vice versa). - Collections typically implement "isequal" by calling "isequal" - recursively on all contents. + This typically means that if you define your own "==" function then you must define a corresponding "hash" (and vice versa). Collections typically implement "isequal" by calling "isequal" recursively on all contents. + + Scalar types generally do not need to implement "isequal" separate from "==", unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on "isnan", "signbit", and "=="). - Scalar types generally do not need to implement "isequal" - separate from "==", unless they represent floating-point numbers - amenable to a more efficient implementation than that provided as a - generic fallback (based on "isnan", "signbit", and "=="). .. function:: isless(x, y) - Test whether "x" is less than "y", according to a canonical - total order. Values that are normally unordered, such as "NaN", - are ordered in an arbitrary but consistent fashion. This is the - default comparison used by "sort". Non-numeric types with a - canonical total order should implement this function. Numeric types - only need to implement it if they have special values such as - "NaN". + Test whether "x" is less than "y", according to a canonical total order. Values that are normally unordered, such as "NaN", are ordered in an arbitrary but consistent fashion. This is the default comparison used by "sort". Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as "NaN". + .. function:: ifelse(condition::Bool, x, y) - Return "x" if "condition" is true, otherwise return "y". This - differs from "?" or "if" in that it is an ordinary function, so - all the arguments are evaluated first. In some cases, using - "ifelse" instead of an "if" statement can eliminate the branch - in generated code and provide higher performance in tight loops. + Return "x" if "condition" is true, otherwise return "y". This differs from "?" or "if" in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using "ifelse" instead of an "if" statement can eliminate the branch in generated code and provide higher performance in tight loops. + .. function:: lexcmp(x, y) - Compare "x" and "y" lexicographically and return -1, 0, or 1 - depending on whether "x" is less than, equal to, or greater than - "y", respectively. This function should be defined for - lexicographically comparable types, and "lexless" will call - "lexcmp" by default. + Compare "x" and "y" lexicographically and return -1, 0, or 1 depending on whether "x" is less than, equal to, or greater than "y", respectively. This function should be defined for lexicographically comparable types, and "lexless" will call "lexcmp" by default. + .. function:: lexless(x, y) - Determine whether "x" is lexicographically less than "y". + Determine whether "x" is lexicographically less than "y". + .. function:: typeof(x) - Get the concrete type of "x". + Get the concrete type of "x". + .. function:: tuple(xs...) - Construct a tuple of the given objects. + Construct a tuple of the given objects. + .. function:: ntuple(f::Function, n) - Create a tuple of length "n", computing each element as "f(i)", - where "i" is the index of the element. + Create a tuple of length "n", computing each element as "f(i)", where "i" is the index of the element. + .. function:: object_id(x) - Get a unique integer id for "x". "object_id(x)==object_id(y)" - if and only if "is(x,y)". + Get a unique integer id for "x". "object_id(x)==object_id(y)" if and only if "is(x,y)". + .. function:: hash(x[, h]) - Compute an integer hash code such that "isequal(x,y)" implies - "hash(x)==hash(y)". The optional second argument "h" is a hash - code to be mixed with the result. + Compute an integer hash code such that "isequal(x,y)" implies "hash(x)==hash(y)". The optional second argument "h" is a hash code to be mixed with the result. + + New types should implement the 2-argument form, typically by calling the 2-argument "hash" method recursively in order to mix hashes of the contents with each other (and with "h"). Typically, any type that implements "hash" should also implement its own "==" (hence "isequal") to guarantee the property mentioned above. - New types should implement the 2-argument form, typically by - calling the 2-argument "hash" method recursively in order to mix - hashes of the contents with each other (and with "h"). - Typically, any type that implements "hash" should also implement - its own "==" (hence "isequal") to guarantee the property - mentioned above. .. function:: finalizer(x, function) - Register a function "f(x)" to be called when there are no - program-accessible references to "x". The behavior of this - function is unpredictable if "x" is of a bits type. + Register a function "f(x)" to be called when there are no program-accessible references to "x". The behavior of this function is unpredictable if "x" is of a bits type. + .. function:: finalize(x) - Immediately run finalizers registered for object "x". + Immediately run finalizers registered for object "x". + .. function:: copy(x) - Create a shallow copy of "x": the outer structure is copied, but - not all internal values. For example, copying an array produces a - new array with identically-same elements as the original. + Create a shallow copy of "x": the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. + .. function:: deepcopy(x) - Create a deep copy of "x": everything is copied recursively, - resulting in a fully independent object. For example, deep-copying - an array produces a new array whose elements are deep copies of the - original elements. Calling *deepcopy* on an object should generally - have the same effect as serializing and then deserializing it. - - As a special case, functions can only be actually deep-copied if - they are anonymous, otherwise they are just copied. The difference - is only relevant in the case of closures, i.e. functions which may - contain hidden internal references. - - While it isn't normally necessary, user-defined types can override - the default "deepcopy" behavior by defining a specialized version - of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" - (which shouldn't otherwise be used), where "T" is the type to be - specialized for, and "dict" keeps track of objects copied so far - within the recursion. Within the definition, "deepcopy_internal" - should be used in place of "deepcopy", and the "dict" variable - should be updated as appropriate before returning. + Create a deep copy of "x": everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling *deepcopy* on an object should generally have the same effect as serializing and then deserializing it. + + As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. + + While it isn't normally necessary, user-defined types can override the default "deepcopy" behavior by defining a specialized version of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" (which shouldn't otherwise be used), where "T" is the type to be specialized for, and "dict" keeps track of objects copied so far within the recursion. Within the definition, "deepcopy_internal" should be used in place of "deepcopy", and the "dict" variable should be updated as appropriate before returning. + .. function:: isdefined([object], index | symbol) - Tests whether an assignable location is defined. The arguments can - be an array and index, a composite object and field name (as a - symbol), or a module and a symbol. With a single symbol argument, - tests whether a global variable with that name is defined in - "current_module()". + Tests whether an assignable location is defined. The arguments can be an array and index, a composite object and field name (as a symbol), or a module and a symbol. With a single symbol argument, tests whether a global variable with that name is defined in "current_module()". + .. function:: convert(T, x) - Convert "x" to a value of type "T". + Convert "x" to a value of type "T". - If "T" is an "Integer" type, an "InexactError" will be raised - if "x" is not representable by "T", for example if "x" is not - integer-valued, or is outside the range supported by "T". + If "T" is an "Integer" type, an "InexactError" will be raised if "x" is not representable by "T", for example if "x" is not integer-valued, or is outside the range supported by "T". - julia> convert(Int, 3.0) - 3 + :: - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 + julia> convert(Int, 3.0) + 3 - If "T" is a "FloatingPoint" or "Rational" type, then it will - return the closest value to "x" representable by "T". + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 - julia> x = 1/3 - 0.3333333333333333 + If "T" is a "FloatingPoint" or "Rational" type, then it will return the closest value to "x" representable by "T". - julia> convert(Float32, x) - 0.33333334f0 + :: - julia> convert(Rational{Int32}, x) - 1//3 + julia> x = 1/3 + 0.3333333333333333 + + julia> convert(Float32, x) + 0.33333334f0 + + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 .. function:: promote(xs...) - Convert all arguments to their common promotion type (if any), and - return them all (as a tuple). + Convert all arguments to their common promotion type (if any), and return them all (as a tuple). + .. function:: oftype(x, y) - Convert "y" to the type of "x" ("convert(typeof(x), y)"). + Convert "y" to the type of "x" ("convert(typeof(x), y)"). + .. function:: widen(type | x) - If the argument is a type, return a "larger" type (for numeric - types, this will be a type with at least as much range and - precision as the argument, and usually more). Otherwise the - argument "x" is converted to "widen(typeof(x))". + If the argument is a type, return a "larger" type (for numeric types, this will be a type with at least as much range and precision as the argument, and usually more). Otherwise the argument "x" is converted to "widen(typeof(x))". + + :: - julia> widen(Int32) - Int64 + julia> widen(Int32) + Int64 + + julia> widen(1.5f0) + 1.5 - julia> widen(1.5f0) - 1.5 .. function:: identity(x) - The identity function. Returns its argument. + The identity function. Returns its argument. + Types ----- .. function:: super(T::DataType) - Return the supertype of DataType T + Return the supertype of DataType T + .. function:: <:(T1, T2) - Subtype operator, equivalent to "issubtype(T1,T2)". + Subtype operator, equivalent to "issubtype(T1,T2)". + .. function:: <:(T1, T2) - Subtype operator, equivalent to "issubtype(T1,T2)". + Subtype operator, equivalent to "issubtype(T1,T2)". + .. function:: subtypes(T::DataType) - Return a list of immediate subtypes of DataType T. Note that all - currently loaded subtypes are included, including those not visible - in the current module. + Return a list of immediate subtypes of DataType T. Note that all currently loaded subtypes are included, including those not visible in the current module. + .. function:: typemin(type) - The lowest value representable by the given (real) numeric type. + The lowest value representable by the given (real) numeric type. + .. function:: typemax(type) - The highest value representable by the given (real) numeric type. + The highest value representable by the given (real) numeric type. + .. function:: realmin(type) - The smallest in absolute value non-subnormal value representable by - the given floating-point type + The smallest in absolute value non-subnormal value representable by the given floating-point type + .. function:: realmax(type) - The highest finite value representable by the given floating-point - type + The highest finite value representable by the given floating-point type + .. function:: maxintfloat(type) - The largest integer losslessly representable by the given floating- - point type + The largest integer losslessly representable by the given floating- point type + .. function:: sizeof(s::AbstractString) - The number of bytes in string "s". + The number of bytes in string "s". + .. function:: eps(::DateTime) -> Millisecond + eps(::Date) -> Day + + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" for "Date" values. - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" - for "Date" values. .. function:: eps(::DateTime) -> Millisecond + eps(::Date) -> Day + + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" for "Date" values. - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" - for "Date" values. .. function:: promote_type(type1, type2) - Determine a type big enough to hold values of each argument type - without loss, whenever possible. In some cases, where no type - exists to which both types can be promoted losslessly, some loss is - tolerated; for example, "promote_type(Int64,Float64)" returns - "Float64" even though strictly, not all "Int64" values can be - represented exactly as "Float64" values. + Determine a type big enough to hold values of each argument type without loss, whenever possible. In some cases, where no type exists to which both types can be promoted losslessly, some loss is tolerated; for example, "promote_type(Int64,Float64)" returns "Float64" even though strictly, not all "Int64" values can be represented exactly as "Float64" values. + .. function:: promote_rule(type1, type2) - Specifies what type should be used by "promote" when given values - of types "type1" and "type2". This function should not be - called directly, but should have definitions added to it for new - types as appropriate. + Specifies what type should be used by "promote" when given values of types "type1" and "type2". This function should not be called directly, but should have definitions added to it for new types as appropriate. + .. function:: getfield(value, name::Symbol) - Extract a named field from a value of composite type. The syntax - "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls - "getfield(a, b)". + Extract a named field from a value of composite type. The syntax "a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls "getfield(a, b)". + .. function:: setfield!(value, name::Symbol, x) - Assign "x" to a named field in "value" of composite type. The - syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax - "a.(b) = c" calls "setfield!(a, b, c)". + Assign "x" to a named field in "value" of composite type. The syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax "a.(b) = c" calls "setfield!(a, b, c)". + .. function:: fieldoffsets(type) - The byte offset of each field of a type relative to the data start. - For example, we could use it in the following manner to summarize - information about a struct type: - - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; - - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) + The byte offset of each field of a type relative to the data start. For example, we could use it in the following manner to summarize information about a struct type: + + :: + + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; + + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) + .. function:: fieldtype(type, name::Symbol | index::Int) - Determine the declared type of a field (specified by name or index) - in a composite type. + Determine the declared type of a field (specified by name or index) in a composite type. + .. function:: isimmutable(v) - True if value "v" is immutable. See *Immutable Composite Types* - for a discussion of immutability. Note that this function works on - values, so if you give it a type, it will tell you that a value of - "DataType" is mutable. + True if value "v" is immutable. See *Immutable Composite Types* for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of "DataType" is mutable. + .. function:: isbits(T) - True if "T" is a "plain data" type, meaning it is immutable and - contains no references to other values. Typical examples are - numeric types such as "UInt8", "Float64", and - "Complex{Float64}". + True if "T" is a "plain data" type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as "UInt8", "Float64", and "Complex{Float64}". + + :: - julia> isbits(Complex{Float64}) - true + julia> isbits(Complex{Float64}) + true + + julia> isbits(Complex) + false - julia> isbits(Complex) - false .. function:: isleaftype(T) - Determine whether "T" is a concrete type that can have instances, - meaning its only subtypes are itself and "None" (but "T" itself - is not "None"). + Determine whether "T" is a concrete type that can have instances, meaning its only subtypes are itself and "None" (but "T" itself is not "None"). + .. function:: typejoin(T, S) - Compute a type that contains both "T" and "S". + Compute a type that contains both "T" and "S". + .. function:: typeintersect(T, S) - Compute a type that contains the intersection of "T" and "S". - Usually this will be the smallest such type or one close to it. + Compute a type that contains the intersection of "T" and "S". Usually this will be the smallest such type or one close to it. + .. function:: Val{c} @@ -562,165 +506,155 @@ Types .. function:: instances(T::Type) - Return a collection of all instances of the given type, if - applicable. Mostly used for enumerated types (see "@enum"). + Return a collection of all instances of the given type, if applicable. Mostly used for enumerated types (see "@enum"). + Generic Functions ----------------- .. function:: method_exists(f, Tuple type) -> Bool - Determine whether the given generic function has a method matching - the given "Tuple" of argument types. + Determine whether the given generic function has a method matching the given "Tuple" of argument types. + + :: + + julia> method_exists(length, Tuple{Array}) + true - julia> method_exists(length, Tuple{Array}) - true .. function:: applicable(f, args...) -> Bool - Determine whether the given generic function has a method - applicable to the given arguments. + Determine whether the given generic function has a method applicable to the given arguments. + + :: + + julia> function f(x, y) + x + y + end; - julia> function f(x, y) - x + y - end; + julia> applicable(f, 1) + false - julia> applicable(f, 1) - false + julia> applicable(f, 1, 2) + true - julia> applicable(f, 1, 2) - true .. function:: invoke(f, (types...), args...) - Invoke a method for the given generic function matching the - specified types (as a tuple), on the specified arguments. The - arguments must be compatible with the specified types. This allows - invoking a method other than the most specific matching method, - which is useful when the behavior of a more general definition is - explicitly needed (often as part of the implementation of a more - specific method of the same function). + Invoke a method for the given generic function matching the specified types (as a tuple), on the specified arguments. The arguments must be compatible with the specified types. This allows invoking a method other than the most specific matching method, which is useful when the behavior of a more general definition is explicitly needed (often as part of the implementation of a more specific method of the same function). + .. function:: |>(x, f) - Applies a function to the preceding argument. This allows for easy - function chaining. + Applies a function to the preceding argument. This allows for easy function chaining. + + :: + + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 .. function:: call(x, args...) - If "x" is not a "Function", then "x(args...)" is equivalent - to "call(x, args...)". This means that function-like behavior - can be added to any type by defining new "call" methods. + If "x" is not a "Function", then "x(args...)" is equivalent to "call(x, args...)". This means that function-like behavior can be added to any type by defining new "call" methods. + Syntax ------ .. function:: eval([m::Module], expr::Expr) - Evaluate an expression in the given module and return the result. - Every module (except those defined with "baremodule") has its own - 1-argument definition of "eval", which evaluates expressions in - that module. + Evaluate an expression in the given module and return the result. Every module (except those defined with "baremodule") has its own 1-argument definition of "eval", which evaluates expressions in that module. + .. function:: @eval() - Evaluate an expression and return the value. + Evaluate an expression and return the value. + .. function:: evalfile(path::AbstractString) - Load the file using "include", evaluate all expressions, and - return the value of the last one. + Load the file using "include", evaluate all expressions, and return the value of the last one. + .. function:: esc(e::ANY) - Only valid in the context of an Expr returned from a macro. - Prevents the macro hygiene pass from turning embedded variables - into gensym variables. See the *Macros* section of the - Metaprogramming chapter of the manual for more details and - examples. + Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the *Macros* section of the Metaprogramming chapter of the manual for more details and examples. + .. function:: gensym([tag]) - Generates a symbol which will not conflict with other variable - names. + Generates a symbol which will not conflict with other variable names. + .. function:: @gensym() - Generates a gensym symbol for a variable. For example, "@gensym x - y" is transformed into "x = gensym("x"); y = gensym("y")". + Generates a gensym symbol for a variable. For example, "@gensym x y" is transformed into "x = gensym("x"); y = gensym("y")". + .. function:: parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. + .. function:: parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. + Nullables --------- .. function:: Nullable(x) - Wrap value "x" in an object of type "Nullable", which indicates - whether a value is present. "Nullable(x)" yields a non-empty - wrapper, and "Nullable{T}()" yields an empty instance of a - wrapper that might contain a value of type "T". + Wrap value "x" in an object of type "Nullable", which indicates whether a value is present. "Nullable(x)" yields a non-empty wrapper, and "Nullable{T}()" yields an empty instance of a wrapper that might contain a value of type "T". + .. 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. + 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: + + :: - This is intended to be called using "do" block syntax: + get(dict, key) do + # default value calculated here + time() + end - get(dict, key) do - # default value calculated here - time() - end .. 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. + 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: + This is intended to be called using "do" block syntax: + + :: + + get(dict, key) do + # default value calculated here + time() + end - get(dict, key) do - # default value calculated here - time() - end .. function:: isnull(x) - Is the "Nullable" object "x" null, i.e. missing a value? + Is the "Nullable" object "x" null, i.e. missing a value? + System ------ .. function:: run(command) - Run a command object, constructed with backticks. Throws an error - if anything goes wrong, including the process exiting with a non- - zero status. + Run a command object, constructed with backticks. Throws an error if anything goes wrong, including the process exiting with a non- zero status. + .. function:: spawn(command) - Run a command object asynchronously, returning the resulting - "Process" object. + Run a command object asynchronously, returning the resulting "Process" object. + .. data:: DevNull @@ -729,39 +663,37 @@ System .. function:: success(command) - Run a command object, constructed with backticks, and tell whether - it was successful (exited with a code of 0). An exception is raised - if the process cannot be started. + Run a command object, constructed with backticks, and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started. + .. function:: process_running(p::Process) - Determine whether a process is currently running. + Determine whether a process is currently running. + .. function:: process_exited(p::Process) - Determine whether a process has exited. + Determine whether a process has exited. + .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master - process, by "rmprocs". It should cause the remote worker - specified by "pid" to exit. - "Base.kill(manager::ClusterManager.....)" executes a remote - "exit()" on "pid" + Implemented by cluster managers. It is called on the master process, by "rmprocs". It should cause the remote worker specified by "pid" to exit. "Base.kill(manager::ClusterManager.....)" executes a remote "exit()" on "pid" + .. function:: open(f::function, args...) - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. + + **Example**: "open(readall, "file.txt")" - **Example**: "open(readall, "file.txt")" .. function:: open(f::function, args...) - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. + + **Example**: "open(readall, "file.txt")" - **Example**: "open(readall, "file.txt")" .. function:: Sys.set_process_title(title::AbstractString) @@ -773,153 +705,122 @@ System .. function:: readandwrite(command) - Starts running a command asynchronously, and returns a tuple - (stdout,stdin,process) of the output stream and input stream of the - process, and the process object itself. + Starts running a command asynchronously, and returns a tuple (stdout,stdin,process) of the output stream and input stream of the process, and the process object itself. + .. function:: ignorestatus(command) - Mark a command object so that running it will not throw an error if - the result code is non-zero. + Mark a command object so that running it will not throw an error if the result code is non-zero. + .. function:: detach(command) - Mark a command object so that it will be run in a new process - group, allowing it to outlive the julia process, and not have - Ctrl-C interrupts passed to it. + Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. + .. function:: setenv(command, env; dir=working_dir) - Set environment variables to use when running the given command. - "env" is either a dictionary mapping strings to strings, an array - of strings of the form ""var=val"", or zero or more - ""var"=>val" pair arguments. In order to modify (rather than - replace) the existing environment, create "env" by "copy(ENV)" - and then setting "env["var"]=val" as desired, or use - "withenv". + Set environment variables to use when running the given command. "env" is either a dictionary mapping strings to strings, an array of strings of the form ""var=val"", or zero or more ""var"=>val" pair arguments. In order to modify (rather than replace) the existing environment, create "env" by "copy(ENV)" and then setting "env["var"]=val" as desired, or use "withenv". + + The "dir" keyword argument can be used to specify a working directory for the command. - The "dir" keyword argument can be used to specify a working - directory for the command. .. function:: withenv(f::Function, kv::Pair...) - Execute "f()" in an environment that is temporarily modified (not - replaced as in "setenv") by zero or more ""var"=>val" - arguments "kv". "withenv" is generally used via the - "withenv(kv...) do ... end" syntax. A value of "nothing" can - be used to temporarily unset an environment variable (if it is - set). When "withenv" returns, the original environment has been - restored. + Execute "f()" in an environment that is temporarily modified (not replaced as in "setenv") by zero or more ""var"=>val" arguments "kv". "withenv" is generally used via the "withenv(kv...) do ... end" syntax. A value of "nothing" can be used to temporarily unset an environment variable (if it is set). When "withenv" returns, the original environment has been restored. + .. function:: pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given "command". Keyword arguments - specify which of the command's streams should be redirected. - "append" controls whether file output appends to the file. This - is a more general version of the 2-argument "pipe" function. - "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when - "from" is a command, and to "pipe(to, stdin=from)" when - "from" is another kind of data source. + Redirect I/O to or from the given "command". Keyword arguments specify which of the command's streams should be redirected. "append" controls whether file output appends to the file. This is a more general version of the 2-argument "pipe" function. "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when "from" is a command, and to "pipe(to, stdin=from)" when "from" is another kind of data source. - **Examples**: - * "run(pipe(`dothings`, stdout="out.txt", - stderr="errs.txt"))" + **Examples**: * "run(pipe(``dothings``, stdout="out.txt", stderr="errs.txt"))" + + :: + + * "run(pipe(`update`, stdout="log.txt", append=true))" - * "run(pipe(`update`, stdout="log.txt", append=true))" .. function:: pipe(command; stdin, stdout, stderr, append=false) - Redirect I/O to or from the given "command". Keyword arguments - specify which of the command's streams should be redirected. - "append" controls whether file output appends to the file. This - is a more general version of the 2-argument "pipe" function. - "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when - "from" is a command, and to "pipe(to, stdin=from)" when - "from" is another kind of data source. + Redirect I/O to or from the given "command". Keyword arguments specify which of the command's streams should be redirected. "append" controls whether file output appends to the file. This is a more general version of the 2-argument "pipe" function. "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when "from" is a command, and to "pipe(to, stdin=from)" when "from" is another kind of data source. + + **Examples**: * "run(pipe(``dothings``, stdout="out.txt", stderr="errs.txt"))" - **Examples**: - * "run(pipe(`dothings`, stdout="out.txt", - stderr="errs.txt"))" + :: + + * "run(pipe(`update`, stdout="log.txt", append=true))" - * "run(pipe(`update`, stdout="log.txt", append=true))" .. function:: gethostname() -> AbstractString - Get the local machine's host name. + Get the local machine's host name. + .. function:: getipaddr() -> AbstractString - Get the IP address of the local machine, as a string of the form - "x.x.x.x". + Get the IP address of the local machine, as a string of the form "x.x.x.x". + .. function:: getpid() -> Int32 - Get julia's process ID. + Get julia's process ID. + .. function:: time(t::TmStruct) - Converts a "TmStruct" struct to a number of seconds since the - epoch. + Converts a "TmStruct" struct to a number of seconds since the epoch. + .. function:: time_ns() - Get the time in nanoseconds. The time corresponding to 0 is - undefined, and wraps every 5.8 years. + Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. + .. function:: tic() - Set a timer to be read by the next call to "toc()" or "toq()". - The macro call "@time expr" can also be used to time evaluation. + Set a timer to be read by the next call to "toc()" or "toq()". The macro call "@time expr" can also be used to time evaluation. + .. function:: toc() - Print and return the time elapsed since the last "tic()". + Print and return the time elapsed since the last "tic()". + .. function:: toq() - Return, but do not print, the time elapsed since the last - "tic()". + Return, but do not print, the time elapsed since the last "tic()". + .. function:: @time() - A macro to execute an expression, printing the time it took to - execute, the number of allocations, and the total number of bytes - its execution caused to be allocated, before returning the value of - the expression. + A macro to execute an expression, printing the time it took to execute, the number of allocations, and the total number of bytes its execution caused to be allocated, before returning the value of the expression. + .. function:: @timev() - This is a verbose version of the "@time" macro, it first prints - the same information as "@time", then any non-zero memory - allocation counters, and then returns the value of the expression. + This is a verbose version of the "@time" macro, it first prints the same information as "@time", then any non-zero memory allocation counters, and then returns the value of the expression. + .. function:: @timed() - A macro to execute an expression, and return the value of the - expression, elapsed time, total bytes allocated, garbage collection - time, and an object with various memory allocation counters. + A macro to execute an expression, and return the value of the expression, elapsed time, total bytes allocated, garbage collection time, and an object with various memory allocation counters. + .. function:: @elapsed() - A macro to evaluate an expression, discarding the resulting value, - instead returning the number of seconds it took to execute as a - floating-point number. + A macro to evaluate an expression, discarding the resulting value, instead returning the number of seconds it took to execute as a floating-point number. + .. function:: @allocated() - A macro to evaluate an expression, discarding the resulting value, - instead returning the total number of bytes allocated during - evaluation of the expression. Note: the expression is evaluated - inside a local function, instead of the current context, in order - to eliminate the effects of compilation, however, there still may - be some allocations due to JIT compilation. This also makes the - results inconsistent with the "@time" macros, which do not try to - adjust for the effects of compilation. + A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the "@time" macros, which do not try to adjust for the effects of compilation. + .. function:: EnvHash() -> EnvHash - A singleton of this type provides a hash table interface to - environment variables. + A singleton of this type provides a hash table interface to environment variables. + .. data:: ENV @@ -927,59 +828,56 @@ System .. function:: @unix() - Given "@unix? a : b", do "a" on Unix systems (including Linux - and OS X) and "b" elsewhere. See documentation for Handling - Platform Variations in the Calling C and Fortran Code section of - the manual. + Given "@unix? a : b", do "a" on Unix systems (including Linux and OS X) and "b" elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. function:: @osx() - Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. + Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. function:: @linux() - Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. + Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. function:: @windows() - Given "@windows? a : b", do "a" on Windows and "b" elsewhere. - See documentation for Handling Platform Variations in the Calling C - and Fortran Code section of the manual. + Given "@windows? a : b", do "a" on Windows and "b" elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + Errors ------ .. function:: error(message::AbstractString) - Raise an "ErrorException" with the given message + Raise an "ErrorException" with the given message + .. function:: throw(e) - Throw an object as an exception + Throw an object as an exception + .. function:: rethrow([e]) - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - "catch" block). + Throw an object without changing the current exception backtrace. The default argument is the current exception (if called within a "catch" block). + .. function:: backtrace() - Get a backtrace object for the current program point. + Get a backtrace object for the current program point. + .. function:: catch_backtrace() - Get the backtrace of the current exception, for use within - "catch" blocks. + Get the backtrace of the current exception, for use within "catch" blocks. + .. function:: assert(cond) - Throw an "AssertionError" if "cond" is false. Also available as - the macro "@assert expr". + Throw an "AssertionError" if "cond" is false. Also available as the macro "@assert expr". + .. function:: @assert cond [text] @@ -987,278 +885,282 @@ Errors .. function:: ArgumentError(msg) - The parameters to a function call do not match a valid signature. + The parameters to a function call do not match a valid signature. + .. function:: AssertionError([msg]) - The asserted condition did not evalutate to "true". + The asserted condition did not evalutate to "true". + .. function:: BoundsError([a][, i]) - An indexing operation into an array, "a", tried to access an out- - of-bounds element, "i". + An indexing operation into an array, "a", tried to access an out- of-bounds element, "i". + .. function:: DimensionMismatch([msg]) - The objects called do not have matching dimensionality. + The objects called do not have matching dimensionality. + .. function:: DivideError() - Integer division was attempted with a denominator value of 0. + Integer division was attempted with a denominator value of 0. + .. function:: DomainError() - The arguments to a function or constructor are outside the valid - domain. + The arguments to a function or constructor are outside the valid domain. + .. function:: EOFError() - No more data was available to read from a file or stream. + No more data was available to read from a file or stream. + .. function:: ErrorException(msg) - Generic error type. The error message, in the *.msg* field, may - provide more specific details. + Generic error type. The error message, in the *.msg* field, may provide more specific details. + .. function:: InexactError() - Type conversion cannot be done exactly. + Type conversion cannot be done exactly. + .. function:: InterruptException() - The process was stopped by a terminal interrupt (CTRL+C). + The process was stopped by a terminal interrupt (CTRL+C). + .. function:: KeyError(key) - An indexing operation into an "Associative" ("Dict") or "Set" - like object tried to access or delete a non-existent element. + An indexing operation into an "Associative" ("Dict") or "Set" like object tried to access or delete a non-existent element. + .. function:: LoadError(file::AbstractString, line::Int, error) - An error occurred while *including*, *requiring*, or *using* a - file. The error specifics should be available in the *.error* - field. + An error occurred while *including*, *requiring*, or *using* a file. The error specifics should be available in the *.error* field. + .. function:: MethodError(f, args) - A method with the required type signature does not exist in the - given generic function. + A method with the required type signature does not exist in the given generic function. + .. function:: NullException() - An attempted access to a "Nullable" with no defined value. + An attempted access to a "Nullable" with no defined value. + .. function:: OutOfMemoryError() - An operation allocated too much memory for either the system or the - garbage collector to handle properly. + An operation allocated too much memory for either the system or the garbage collector to handle properly. + .. function:: ReadOnlyMemoryError() - An operation tried to write to memory that is read-only. + An operation tried to write to memory that is read-only. + .. function:: OverflowError() - The result of an expression is too large for the specified type and - will cause a wraparound. + The result of an expression is too large for the specified type and will cause a wraparound. + .. function:: ParseError(msg) - The expression passed to the *parse* function could not be - interpreted as a valid Julia expression. + The expression passed to the *parse* function could not be interpreted as a valid Julia expression. + .. function:: ProcessExitedException() - After a client Julia process has exited, further attempts to - reference the dead child will throw this exception. + After a client Julia process has exited, further attempts to reference the dead child will throw this exception. + .. function:: StackOverflowError() - The function call grew beyond the size of the call stack. This - usually happens when a call recurses infinitely. + The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. + .. function:: SystemError(prefix::AbstractString[, errnum::Int32]) - A system call failed with an error code (in the "errno" global - variable). + A system call failed with an error code (in the "errno" global variable). + .. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) - A type assertion failure, or calling an intrinsic function with an - incorrect argument type. + A type assertion failure, or calling an intrinsic function with an incorrect argument type. + .. function:: UndefRefError() - The item or field is not defined for the given object. + The item or field is not defined for the given object. + .. function:: UndefVarError(var::Symbol) - A symbol in the current scope is not defined. + A symbol in the current scope is not defined. + Events ------ .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling - "wait" on the timer object) at a specified interval. + Create a timer that wakes up tasks waiting for it (by calling "wait" on the timer object) at a specified interval. + .. function:: Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling - "wait" on the timer object) at a specified interval. + Create a timer that wakes up tasks waiting for it (by calling "wait" on the timer object) at a specified interval. + Reflection ---------- .. function:: module_name(m::Module) -> Symbol - Get the name of a module as a symbol. + Get the name of a module as a symbol. + .. function:: module_parent(m::Module) -> Module - Get a module's enclosing module. "Main" is its own parent. + Get a module's enclosing module. "Main" is its own parent. + .. function:: current_module() -> Module - Get the *dynamically* current module, which is the module code is - currently being read from. In general, this is not the same as the - module containing the call to this function. + Get the *dynamically* current module, which is the module code is currently being read from. In general, this is not the same as the module containing the call to this function. + .. function:: fullname(m::Module) - Get the fully-qualified name of a module as a tuple of symbols. For - example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and - "fullname(Main)" gives "()". + Get the fully-qualified name of a module as a tuple of symbols. For example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and "fullname(Main)" gives "()". + .. function:: names(x::Module[, all=false[, imported=false]]) - Get an array of the names exported by a module, with optionally - more module globals according to the additional parameters. + Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. + .. function:: nfields(x::DataType) -> Int - Get the number of fields of a data type. + Get the number of fields of a data type. + .. function:: fieldnames(x::DataType) - Get an array of the fields of a data type. + Get an array of the fields of a data type. + .. function:: isconst([m::Module], s::Symbol) -> Bool - Determine whether a global is declared "const" in a given module. - The default module argument is "current_module()". + Determine whether a global is declared "const" in a given module. The default module argument is "current_module()". + .. function:: isgeneric(f::Function) -> Bool - Determine whether a function is generic. + Determine whether a function is generic. + .. function:: function_name(f::Function) -> Symbol - Get the name of a generic function as a symbol, or ":anonymous". + Get the name of a generic function as a symbol, or ":anonymous". + .. function:: function_module(f::Function, types) -> Module - Determine the module containing a given definition of a generic - function. + Determine the module containing a given definition of a generic function. + .. function:: functionloc(m::Method) - Returns a tuple "(filename,line)" giving the location of a method - definition. + Returns a tuple "(filename,line)" giving the location of a method definition. + .. function:: functionloc(m::Method) - Returns a tuple "(filename,line)" giving the location of a method - definition. + Returns a tuple "(filename,line)" giving the location of a method definition. + Internals --------- .. function:: gc() - Perform garbage collection. This should not generally be used. + Perform garbage collection. This should not generally be used. + .. function:: gc_enable(on::Bool) - Control whether garbage collection is enabled using a boolean - argument (true for enabled, false for disabled). Returns previous - GC state. Disabling garbage collection should be used only with - extreme caution, as it can cause memory use to grow without bound. + Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Returns previous GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. + .. function:: macroexpand(x) - Takes the expression x and returns an equivalent expression with - all macros removed (expanded). + Takes the expression x and returns an equivalent expression with all macros removed (expanded). + .. function:: expand(x) - Takes the expression x and returns an equivalent expression in - lowered form + Takes the expression x and returns an equivalent expression in lowered form + .. function:: code_lowered(f, types) - Returns an array of lowered ASTs for the methods matching the given - generic function and type signature. + Returns an array of lowered ASTs for the methods matching the given generic function and type signature. + .. function:: @code_lowered() - Evaluates the arguments to the function call, determines their - types, and calls "code_lowered()" on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls "code_lowered()" on the resulting expression + .. function:: code_typed(f, types; optimize=true) - Returns an array of lowered and type-inferred ASTs for the methods - matching the given generic function and type signature. The keyword - argument "optimize" controls whether additional optimizations, - such as inlining, are also applied. + Returns an array of lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The keyword argument "optimize" controls whether additional optimizations, such as inlining, are also applied. + .. function:: @code_typed() - Evaluates the arguments to the function call, determines their - types, and calls "code_typed()" on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls "code_typed()" on the resulting expression + .. function:: code_warntype(f, types) - Displays lowered and type-inferred ASTs for the methods matching - the given generic function and type signature. The ASTs are - annotated in such a way as to cause "non-leaf" types to be - emphasized (if color is available, displayed in red). This serves - as a warning of potential type instability. Not all non-leaf types - are particularly problematic for performance, so the results need - to be used judiciously. See *@code_warntype* for more information. + Displays lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The ASTs are annotated in such a way as to cause "non-leaf" types to be emphasized (if color is available, displayed in red). This serves as a warning of potential type instability. Not all non-leaf types are particularly problematic for performance, so the results need to be used judiciously. See *@code_warntype* for more information. + .. function:: @code_warntype() - Evaluates the arguments to the function call, determines their - types, and calls "code_warntype()" on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls "code_warntype()" on the resulting expression + .. function:: code_llvm(f, types) - Prints the LLVM bitcodes generated for running the method matching - the given generic function and type signature to "STDOUT". + Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to "STDOUT". + + All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. - All metadata and dbg.* calls are removed from the printed bitcode. - Use code_llvm_raw for the full IR. .. function:: @code_llvm() - Evaluates the arguments to the function call, determines their - types, and calls "code_llvm()" on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls "code_llvm()" on the resulting expression + .. function:: code_native(f, types) - Prints the native assembly instructions generated for running the - method matching the given generic function and type signature to - STDOUT. + Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. + .. function:: @code_native() - Evaluates the arguments to the function call, determines their - types, and calls "code_native()" on the resulting expression + Evaluates the arguments to the function call, determines their types, and calls "code_native()" on the resulting expression + .. function:: precompile(f, args::Tuple{Vararg{Any}}) - Compile the given function "f" for the argument tuple (of types) - "args", but do not execute it. + Compile the given function "f" for the argument tuple (of types) "args", but do not execute it. + diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index 4807b89147822..e3363ea4b7db3 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -6,188 +6,136 @@ .. function:: ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - Call function in C-exported shared library, specified by - "(function name, library)" tuple, where each component is an - AbstractString or :Symbol. - - Note that the argument type tuple must be a literal tuple, and not - a tuple-valued variable or expression. Alternatively, ccall may - also be used to call a function pointer, such as one returned by - dlsym. - - Each "ArgumentValue" to the "ccall" will be converted to the - corresponding "ArgumentType", by automatic insertion of calls to - "unsafe_convert(ArgumentType, cconvert(ArgumentType, - ArgumentValue))". (see also the documentation for each of these - functions for further details). In most cases, this simply results - in a call to "convert(ArgumentType, ArgumentValue)" + Call function in C-exported shared library, specified by "(function name, library)" tuple, where each component is an AbstractString or :Symbol. + + Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. + + Each "ArgumentValue" to the "ccall" will be converted to the corresponding "ArgumentType", by automatic insertion of calls to "unsafe_convert(ArgumentType, cconvert(ArgumentType, ArgumentValue))". (see also the documentation for each of these functions for further details). In most cases, this simply results in a call to "convert(ArgumentType, ArgumentValue)" + .. function:: cglobal((symbol, library)[, type=Void]) - Obtain a pointer to a global variable in a C-exported shared - library, specified exactly as in "ccall". Returns a - "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is - supplied. The values can be read or written by "unsafe_load" or - "unsafe_store!", respectively. + Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in "ccall". Returns a "Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is supplied. The values can be read or written by "unsafe_load" or "unsafe_store!", respectively. + .. function:: cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - Generate C-callable function pointer from Julia function. Type - annotation of the return value in the callback function is a must - for situations where Julia cannot infer the return type - automatically. + Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically. + + For example: + + :: - For example: + function foo() + # body - function foo() - # body + retval::Float64 + end - retval::Float64 - end + bar = cfunction(foo, Float64, ()) - bar = cfunction(foo, Float64, ()) .. function:: unsafe_convert(T, x) - Convert "x" to a value of type "T" + Convert "x" to a value of type "T" - In cases where "convert" would need to take a Julia object and - turn it into a "Ptr", this function should be used to define and - perform that conversion. + In cases where "convert" would need to take a Julia object and turn it into a "Ptr", this function should be used to define and perform that conversion. - Be careful to ensure that a julia reference to "x" exists as long - as the result of this function will be used. Accordingly, the - argument "x" to this function should never be an expression, only - a variable name or field reference. For example, "x=a.b.c" is - acceptable, but "x=[a,b,c]" is not. + Be careful to ensure that a julia reference to "x" exists as long as the result of this function will be used. Accordingly, the argument "x" to this function should never be an expression, only a variable name or field reference. For example, "x=a.b.c" is acceptable, but "x=[a,b,c]" is not. + + The "unsafe" prefix on this function indicates that using the result of this function after the "x" argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time. - The "unsafe" prefix on this function indicates that using the - result of this function after the "x" argument to this function - is no longer accessible to the program may cause undefined - behavior, including program corruption or segfaults, at any later - time. .. function:: cconvert(T, x) - Convert "x" to a value of type "T", typically by calling - "convert(T,x)" + Convert "x" to a value of type "T", typically by calling "convert(T,x)" + + In cases where "x" cannot be safely converted to "T", unlike "convert", "cconvert" may return an object of a type different from "T", which however is suitable for "unsafe_convert" to handle. - In cases where "x" cannot be safely converted to "T", unlike - "convert", "cconvert" may return an object of a type different - from "T", which however is suitable for "unsafe_convert" to - handle. + Neither "convert" nor "cconvert" should take a Julia object and turn it into a "Ptr". - Neither "convert" nor "cconvert" should take a Julia object and - turn it into a "Ptr". .. function:: unsafe_load(p::Ptr{T}, i::Integer) - Load a value of type "T" from the address of the ith element - (1-indexed) starting at "p". This is equivalent to the C - expression "p[i-1]". + Load a value of type "T" from the address of the ith element (1-indexed) starting at "p". This is equivalent to the C expression "p[i-1]". + + The "unsafe" prefix on this function indicates that no validation is performed on the pointer "p" to ensure that it is valid. Incorrect usage may segfault your program or return garbage answers, in the same manner as C. - The "unsafe" prefix on this function indicates that no validation - is performed on the pointer "p" to ensure that it is valid. - Incorrect usage may segfault your program or return garbage - answers, in the same manner as C. .. function:: unsafe_store!(p::Ptr{T}, x, i::Integer) - Store a value of type "T" to the address of the ith element - (1-indexed) starting at "p". This is equivalent to the C - expression "p[i-1] = x". + Store a value of type "T" to the address of the ith element (1-indexed) starting at "p". This is equivalent to the C expression "p[i-1] = x". + + The "unsafe" prefix on this function indicates that no validation is performed on the pointer "p" to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. - The "unsafe" prefix on this function indicates that no validation - is performed on the pointer "p" to ensure that it is valid. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy "N" elements from a source array to a destination, starting - at offset "so" in the source and "do" in the destination - (1-indexed). + Copy "N" elements from a source array to a destination, starting at offset "so" in the source and "do" in the destination (1-indexed). + + The "unsafe" prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. - The "unsafe" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy "N" elements from a source array to a destination, starting - at offset "so" in the source and "do" in the destination - (1-indexed). + Copy "N" elements from a source array to a destination, starting at offset "so" in the source and "do" in the destination (1-indexed). + + The "unsafe" prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. - The "unsafe" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. .. function:: copy!(dest, do, src, so, N) - Copy "N" elements from collection "src" starting at offset - "so", to array "dest" starting at offset "do". Returns - "dest". + Copy "N" elements from collection "src" starting at offset "so", to array "dest" starting at offset "do". Returns "dest". + .. function:: copy!(dest, do, src, so, N) - Copy "N" elements from collection "src" starting at offset - "so", to array "dest" starting at offset "do". Returns - "dest". + Copy "N" elements from collection "src" starting at offset "so", to array "dest" starting at offset "do". Returns "dest". + .. function:: pointer(array[, index]) - Get the native address of an array or string element. Be careful to - ensure that a julia reference to "a" exists as long as this - pointer will be used. This function is "unsafe" like - "unsafe_convert". + Get the native address of an array or string element. Be careful to ensure that a julia reference to "a" exists as long as this pointer will be used. This function is "unsafe" like "unsafe_convert". + + Calling "Ref(array[, index])" is generally preferable to this function. - Calling "Ref(array[, index])" is generally preferable to this - function. .. function:: pointer_to_array(pointer, dims[, take_ownership::Bool]) - Wrap a native pointer as a Julia Array object. The pointer element - type determines the array element type. "own" optionally - specifies whether Julia should take ownership of the memory, - calling "free" on the pointer when the array is no longer - referenced. + Wrap a native pointer as a Julia Array object. The pointer element type determines the array element type. "own" optionally specifies whether Julia should take ownership of the memory, calling "free" on the pointer when the array is no longer referenced. + .. function:: pointer_from_objref(object_instance) - Get the memory address of a Julia object as a "Ptr". The - existence of the resulting "Ptr" will not protect the object from - garbage collection, so you must ensure that the object remains - referenced for the whole time that the "Ptr" will be used. + Get the memory address of a Julia object as a "Ptr". The existence of the resulting "Ptr" will not protect the object from garbage collection, so you must ensure that the object remains referenced for the whole time that the "Ptr" will be used. + .. function:: unsafe_pointer_to_objref(p::Ptr) - Convert a "Ptr" to an object reference. Assumes the pointer - refers to a valid heap-allocated Julia object. If this is not the - case, undefined behavior results, hence this function is considered - "unsafe" and should be used with care. + Convert a "Ptr" to an object reference. Assumes the pointer refers to a valid heap-allocated Julia object. If this is not the case, undefined behavior results, hence this function is considered "unsafe" and should be used with care. + .. function:: disable_sigint(f::Function) - Disable Ctrl-C handler during execution of a function, for calling - external code that is not interrupt safe. Intended to be called - using "do" block syntax as follows: + Disable Ctrl-C handler during execution of a function, for calling external code that is not interrupt safe. Intended to be called using "do" block syntax as follows: + + :: + + disable_sigint() do + # interrupt-unsafe code + ... + end - disable_sigint() do - # interrupt-unsafe code - ... - end .. function:: reenable_sigint(f::Function) - Re-enable Ctrl-C handler during execution of a function. - Temporarily reverses the effect of "disable_sigint". + Re-enable Ctrl-C handler during execution of a function. Temporarily reverses the effect of "disable_sigint". + .. function:: systemerror(sysfunc, iftrue) - Raises a "SystemError" for "errno" with the descriptive string - "sysfunc" if "bool" is true + Raises a "SystemError" for "errno" with the descriptive string "sysfunc" if "bool" is true + .. data:: Ptr{T} diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index d6aa0acc55990..f04824b71b698 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -26,71 +26,71 @@ The ``state`` object may be anything, and should be chosen appropriately for eac .. function:: start(iter) -> state - Get initial iteration state for an iterable object + Get initial iteration state for an iterable object + .. function:: done(iter, state) -> Bool - Test whether we are done iterating + Test whether we are done iterating + .. function:: next(iter, state) -> item, state - For a given iterable object and iteration state, return the current - item and the next iteration state + For a given iterable object and iteration state, return the current item and the next iteration state + .. function:: zip(iters...) - For a set of iterable objects, returns an iterable of tuples, where - the "i"th tuple contains the "i"th component of each input - iterable. + For a set of iterable objects, returns an iterable of tuples, where the "i"th tuple contains the "i"th component of each input iterable. + + Note that "zip()" is its own inverse: "collect(zip(zip(a...)...)) == collect(a)". - Note that "zip()" is its own inverse: - "collect(zip(zip(a...)...)) == collect(a)". .. function:: enumerate(iter) - An iterator that yields "(i, x)" where "i" is an index starting - at 1, and "x" is the "i"th value from the given iterator. It's - useful when you need not only the values "x" over which you are - iterating, but also the index "i" of the iterations. + An iterator that yields "(i, x)" where "i" is an index starting at 1, and "x" is the "i"th value from the given iterator. It's useful when you need not only the values "x" over which you are iterating, but also the index "i" of the iterations. + + :: + + julia> a = ["a", "b", "c"]; - julia> a = ["a", "b", "c"]; + julia> for (index, value) in enumerate(a) + println("\$index \$value") + end + 1 a + 2 b + 3 c - julia> for (index, value) in enumerate(a) - println("\$index \$value") - end - 1 a - 2 b - 3 c .. function:: rest(iter, state) - An iterator that yields the same elements as "iter", but starting - at the given "state". + An iterator that yields the same elements as "iter", but starting at the given "state". + .. function:: countfrom(start=1, step=1) - An iterator that counts forever, starting at "start" and - incrementing by "step". + An iterator that counts forever, starting at "start" and incrementing by "step". + .. function:: take(iter, n) - An iterator that generates at most the first "n" elements of - "iter". + An iterator that generates at most the first "n" elements of "iter". + .. function:: drop(iter, n) - An iterator that generates all but the first "n" elements of - "iter". + An iterator that generates all but the first "n" elements of "iter". + .. function:: cycle(iter) - An iterator that cycles through "iter" forever. + An iterator that cycles through "iter" forever. + .. function:: repeated(x[, n::Int]) - An iterator that generates the value "x" forever. If "n" is - specified, generates "x" that many times (equivalent to - "take(repeated(x), n)"). + An iterator that generates the value "x" forever. If "n" is specified, generates "x" that many times (equivalent to "take(repeated(x), n)"). + Fully implemented by: @@ -114,28 +114,36 @@ General Collections .. function:: isempty(collection) -> Bool - Determine whether a collection is empty (has no elements). + Determine whether a collection is empty (has no elements). + + :: + + julia> isempty([]) + true - julia> isempty([]) - true + julia> isempty([1 2 3]) + false - julia> isempty([1 2 3]) - false .. function:: empty!(collection) -> collection - Remove all elements from a "collection". + Remove all elements from a "collection". + .. function:: length(s) - The number of characters in string "s". + The number of characters in string "s". + .. function:: endof(collection) -> Integer - Returns the last index of the collection. + Returns the last index of the collection. + + :: + + julia> endof([1,2,4]) + 3 - julia> endof([1,2,4]) - 3 Fully implemented by: @@ -155,406 +163,400 @@ Iterable Collections .. function:: in(item, collection) -> Bool - ∋(collection, item) -> Bool - ∉(item, collection) -> Bool - ∌(collection, item) -> Bool + :: + + 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)". - 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)". .. 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 "(key,value)" tuple type. 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. + Determine the type of the elements generated by iterating a collection of the given "type". For associative collection types, this will be a "(key,value)" tuple type. 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. + .. 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". + 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". + .. function:: findin(a, b) - Returns the indices of elements in collection "a" that appear in - collection "b" + Returns the indices of elements in collection "a" that appear in collection "b" + .. function:: 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". + 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". + .. function:: 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". + 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". + .. function:: 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". + 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". + .. function:: 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)"). + 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)"). + .. function:: 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)"). + 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)"). + .. function:: 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)"). + 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)"). + .. function:: 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)"). + 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)"). + .. function:: maximum(A, dims) - Compute the maximum value of an array over the given dimensions. + Compute the maximum value of an array over the given dimensions. + .. function:: maximum(A, dims) - Compute the maximum value of an array over the given dimensions. + Compute the maximum value of an array over the given dimensions. + .. function:: maximum!(r, A) - Compute the maximum value of "A" over the singleton dimensions of - "r", and write results to "r". + Compute the maximum value of "A" over the singleton dimensions of "r", and write results to "r". + .. function:: minimum(A, dims) - Compute the minimum value of an array over the given dimensions. + Compute the minimum value of an array over the given dimensions. + .. function:: minimum(A, dims) - Compute the minimum value of an array over the given dimensions. + Compute the minimum value of an array over the given dimensions. + .. function:: minimum!(r, A) - Compute the minimum value of "A" over the singleton dimensions of - "r", and write results to "r". + Compute the minimum value of "A" over the singleton dimensions of "r", and write results to "r". + .. function:: extrema(itr) - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. + Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. + .. function:: indmax(itr) -> Integer - Returns the index of the maximum element in a collection. + Returns the index of the maximum element in a collection. + .. function:: indmin(itr) -> Integer - Returns the index of the minimum element in a collection. + Returns the index of the minimum element in a collection. + .. function:: findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over - the given dimensions. + For an array input, returns the value and index of the maximum over the given dimensions. + .. function:: findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over - the given dimensions. + For an array input, returns the value and index of the maximum over the given dimensions. + .. function:: findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over - the given dimensions. + For an array input, returns the value and index of the minimum over the given dimensions. + .. function:: findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over - the given dimensions. + For an array input, returns the value and index of the minimum over the given dimensions. + .. function:: maxabs(A, dims) - Compute the maximum absolute values over given dimensions. + Compute the maximum absolute values over given dimensions. + .. function:: maxabs(A, dims) - Compute the maximum absolute values over given dimensions. + Compute the maximum absolute values over given dimensions. + .. function:: maxabs!(r, A) - Compute the maximum absolute values over the singleton dimensions - of "r", and write values to "r". + Compute the maximum absolute values over the singleton dimensions of "r", and write values to "r". + .. function:: minabs(A, dims) - Compute the minimum absolute values over given dimensions. + Compute the minimum absolute values over given dimensions. + .. function:: minabs(A, dims) - Compute the minimum absolute values over given dimensions. + Compute the minimum absolute values over given dimensions. + .. function:: minabs!(r, A) - Compute the minimum absolute values over the singleton dimensions - of "r", and write values to "r". + Compute the minimum absolute values over the singleton dimensions of "r", and write values to "r". + .. function:: sum(f, itr) - Sum the results of calling function "f" on each element of - "itr". + Sum the results of calling function "f" on each element of "itr". + .. function:: sum(f, itr) - Sum the results of calling function "f" on each element of - "itr". + Sum the results of calling function "f" on each element of "itr". + .. function:: sum!(r, A) - Sum elements of "A" over the singleton dimensions of "r", and - write results to "r". + Sum elements of "A" over the singleton dimensions of "r", and write results to "r". + .. function:: sum(f, itr) - Sum the results of calling function "f" on each element of - "itr". + Sum the results of calling function "f" on each element of "itr". + .. function:: sumabs(A, dims) - Sum absolute values of elements of an array over the given - dimensions. + Sum absolute values of elements of an array over the given dimensions. + .. function:: sumabs(A, dims) - Sum absolute values of elements of an array over the given - dimensions. + Sum absolute values of elements of an array over the given dimensions. + .. function:: sumabs!(r, A) - Sum absolute values of elements of "A" over the singleton - dimensions of "r", and write results to "r". + Sum absolute values of elements of "A" over the singleton dimensions of "r", and write results to "r". + .. function:: sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. + Sum squared absolute values of elements of an array over the given dimensions. + .. function:: sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. + Sum squared absolute values of elements of an array over the given dimensions. + .. function:: sumabs2!(r, A) - Sum squared absolute values of elements of "A" over the singleton - dimensions of "r", and write results to "r". + Sum squared absolute values of elements of "A" over the singleton dimensions of "r", and write results to "r". + .. function:: prod(A, dims) - Multiply elements of an array over the given dimensions. + Multiply elements of an array over the given dimensions. + .. function:: prod(A, dims) - Multiply elements of an array over the given dimensions. + Multiply elements of an array over the given dimensions. + .. function:: prod!(r, A) - Multiply elements of "A" over the singleton dimensions of "r", - and write results to "r". + Multiply elements of "A" over the singleton dimensions of "r", and write results to "r". + .. function:: any(p, itr) -> Bool - Determine whether predicate "p" returns true for any elements of - "itr". + Determine whether predicate "p" returns true for any elements of "itr". + .. function:: any(p, itr) -> Bool - Determine whether predicate "p" returns true for any elements of - "itr". + Determine whether predicate "p" returns true for any elements of "itr". + .. function:: any!(r, A) - Test whether any values in "A" along the singleton dimensions of - "r" are true, and write results to "r". + Test whether any values in "A" along the singleton dimensions of "r" are true, and write results to "r". + .. function:: all(p, itr) -> Bool - Determine whether predicate "p" returns true for all elements of - "itr". + Determine whether predicate "p" returns true for all elements of "itr". + + :: + + julia> all(i->(4<=i<=6), [4,5,6]) + true - julia> all(i->(4<=i<=6), [4,5,6]) - true .. function:: all(p, itr) -> Bool - Determine whether predicate "p" returns true for all elements of - "itr". + Determine whether predicate "p" returns true for all elements of "itr". + + :: + + julia> all(i->(4<=i<=6), [4,5,6]) + true - julia> all(i->(4<=i<=6), [4,5,6]) - true .. function:: all!(r, A) - Test whether all values in "A" along the singleton dimensions of - "r" are true, and write results to "r". + Test whether all values in "A" along the singleton dimensions of "r" are true, and write results to "r". + .. function:: count(p, itr) -> Integer - Count the number of elements in "itr" for which predicate "p" - returns true. + Count the number of elements in "itr" for which predicate "p" returns true. + .. function:: any(p, itr) -> Bool - Determine whether predicate "p" returns true for any elements of - "itr". + Determine whether predicate "p" returns true for any elements of "itr". + .. function:: all(p, itr) -> Bool - Determine whether predicate "p" returns true for all elements of - "itr". + Determine whether predicate "p" returns true for all elements of "itr". + + :: + + julia> all(i->(4<=i<=6), [4,5,6]) + true - julia> all(i->(4<=i<=6), [4,5,6]) - true .. function:: map(f, c...) -> collection - Transform collection "c" by applying "f" to each element. For - multiple collection arguments, apply "f" elementwise. + 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((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 - julia> map(+, [1, 2, 3], [10, 20, 30]) - 3-element Array{Int64,1}: - 11 - 22 - 33 .. 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. + Like "map()", but stores the result in "destination" rather than a new collection. "destination" must be at least as large as the first collection. + .. 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. + Like "map()", but stores the result in "destination" rather than a new collection. "destination" must be at least as large as the first collection. + .. function:: mapreduce(f, op, itr) - Like "mapreduce(f, op, v0, itr)". In general, this cannot be used - with empty collections (see "reduce(op, itr)"). + Like "mapreduce(f, op, v0, itr)". In general, this cannot be used with empty collections (see "reduce(op, itr)"). + .. function:: mapreduce(f, op, itr) - Like "mapreduce(f, op, v0, itr)". In general, this cannot be used - with empty collections (see "reduce(op, itr)"). + Like "mapreduce(f, op, v0, itr)". In general, this cannot be used with empty collections (see "reduce(op, itr)"). + .. function:: 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)"). + 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)"). + .. function:: 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)"). + 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)"). + .. function:: 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)"). + 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)"). + .. function:: 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)"). + 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)"). + .. function:: first(coll) - Get the first element of an iterable collection. Returns the start - point of a "Range" even if it is empty. + Get the first element of an iterable collection. Returns the start point of a "Range" even if it is empty. + .. 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. + 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. + .. function:: step(r) - Get the step size of a "Range" object. + Get the step size of a "Range" object. + .. function:: collect(element_type, collection) - Return an array of type "Array{element_type,1}" of all items in a - collection. + Return an array of type "Array{element_type,1}" of all items in a collection. + .. function:: collect(element_type, collection) - Return an array of type "Array{element_type,1}" of all items in a - collection. + Return an array of type "Array{element_type,1}" of all items in a collection. + .. function:: issubset(A, S) -> Bool + ⊆(A, S) -> Bool + + True if A is a subset of or equal to S. - True if A is a subset of or equal to S. .. 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). + Return a copy of "collection", removing elements for which "function" is false. For associative collections, the function is passed two arguments (key and value). + .. 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). + Update "collection", removing elements for which "function" is false. For associative collections, the function is passed two arguments (key and value). + Indexable Collections --------------------- .. function:: 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, ...)". + 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, ...)". + .. function:: 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, ...)". + 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, ...)". + Fully implemented by: @@ -593,167 +595,179 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: Dict([itr]) - "Dict{K,V}()" constructs a hash table with keys of type "K" and - values of type "V". + "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{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 - Given a single iterable argument, constructs a "Dict" whose key- - value pairs are taken from 2-tuples "(key,value)" generated by - the argument. + Alternatively, a sequence of pair arguments may be passed. - julia> Dict([("A", 1), ("B", 2)]) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 + :: - Alternatively, a sequence of pair arguments may be passed. + julia> Dict("A"=>1, "B"=>2) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 - julia> Dict("A"=>1, "B"=>2) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 .. function:: haskey(collection, key) -> Bool - Determine whether a collection has a mapping for a given key. + Determine whether a collection has a mapping for a given key. + .. 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. + 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: + + :: - This is intended to be called using "do" block syntax: + get(dict, key) do + # default value calculated here + time() + end - get(dict, key) do - # default value calculated here - time() - end .. 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. + 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: + This is intended to be called using "do" block syntax: + + :: + + get(dict, key) do + # default value calculated here + time() + end - get(dict, key) do - # default value calculated here - time() - end time() end .. function:: 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()". + 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: - This is intended to be called using "do" block syntax: + :: + + get!(dict, key) do + # default value calculated here + time() + end - get!(dict, key) do - # default value calculated here - time() - end .. function:: 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()". + 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: + + :: - This is intended to be called using "do" block syntax: + get!(dict, key) do + # default value calculated here + time() + end - get!(dict, key) do - # default value calculated here - time() - end time() end .. function:: getkey(collection, key, default) - Return the key matching argument "key" if one exists in - "collection", otherwise return "default". + Return the key matching argument "key" if one exists in "collection", otherwise return "default". + .. function:: delete!(collection, key) - Delete the mapping for the given key in a collection, and return - the collection. + Delete the mapping for the given key in a collection, and return the collection. + .. function:: pop!(collection) -> item - Remove the last item in "collection" and return it. + 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=[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 - julia> A - 5-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 .. function:: keys(collection) - Return an iterator over all keys in a collection. - "collect(keys(d))" returns an array of keys. + Return an iterator over all keys in a collection. "collect(keys(d))" returns an array of keys. + .. function:: values(collection) - Return an iterator over all values in a collection. - "collect(values(d))" returns an array of values. + Return an iterator over all values in a collection. "collect(values(d))" returns an array of values. + .. function:: merge(collection, others...) - 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{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 - - julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "bar" => 4711 - "baz" => 17 - - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 - - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 + 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{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 + + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 + + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 + + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 + .. function:: merge!(collection, others...) - Update collection with pairs from the other collections + Update collection with pairs from the other collections + .. function:: sizehint!(s, n) - Suggest that collection "s" reserve capacity for at least "n" - elements. This can improve performance. + Suggest that collection "s" reserve capacity for at least "n" elements. This can improve performance. + Fully implemented by: @@ -774,84 +788,84 @@ Set-Like Collections .. function:: 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. + 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. + .. function:: IntSet([itr]) - Construct a sorted set of the integers generated by the given - iterable object, or an empty set. Implemented as a bit string, and - therefore designed for dense integer sets. Only non-negative - integers can be stored. If the set will be sparse (for example - holding a single very large integer), use "Set" instead. + Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use "Set" instead. + .. function:: union(s1, s2...) + ∪(s1, s2) + + Construct the union of two or more sets. Maintains order with arrays. - Construct the union of two or more sets. Maintains order with - arrays. .. function:: union!(s, iterable) - Union each element of "iterable" into set "s" in-place. + Union each element of "iterable" into set "s" in-place. + .. 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. - Construct the intersection of two or more sets. Maintains order and - multiplicity of the first argument for arrays and ranges. .. function:: setdiff(s1, s2) - Construct the set of elements in "s1" but not "s2". 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. + Construct the set of elements in "s1" but not "s2". 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. + .. function:: setdiff!(s, iterable) - Remove each element of "iterable" from set "s" in-place. + Remove each element of "iterable" from set "s" in-place. + .. function:: symdiff(s1, s2...) - Construct the symmetric difference of elements in the passed in - sets or arrays. Maintains order with arrays. + Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. + .. function:: symdiff!(s1, s2) - Construct the symmetric difference of sets "s1" and "s2", - storing the result in "s1". + Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". + .. function:: symdiff!(s1, s2) - Construct the symmetric difference of sets "s1" and "s2", - storing the result in "s1". + Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". + .. function:: symdiff!(s1, s2) - Construct the symmetric difference of sets "s1" and "s2", - storing the result in "s1". + Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". + .. function:: complement(s) - Returns the set-complement of "IntSet" "s". + Returns the set-complement of "IntSet" "s". + .. function:: complement!(s) - Mutates "IntSet" "s" into its set-complement. + Mutates "IntSet" "s" into its set-complement. + .. function:: intersect!(s1, s2) - Intersects sets "s1" and "s2" and overwrites the set "s1" - with the result. If needed, "s1" will be expanded to the size of - "s2". + Intersects sets "s1" and "s2" and overwrites the set "s1" with the result. If needed, "s1" will be expanded to the size of "s2". + .. function:: issubset(A, S) -> Bool + ⊆(A, S) -> Bool + + True if A is a subset of or equal to S. - True if A is a subset of or equal to S. Fully implemented by: @@ -867,233 +881,248 @@ Dequeues .. function:: push!(collection, items...) -> collection - Insert one or more "items" at the end of "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 + :: + + 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])". - 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])". .. function:: pop!(collection) -> item - Remove the last item in "collection" and return it. + 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> A=[1, 2, 3, 4, 5, 6] + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 - julia> pop!(A) - 6 + julia> pop!(A) + 6 + + julia> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 - julia> A - 5-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 .. function:: unshift!(collection, items...) -> collection - Insert one or more "items" at the beginning of "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 - julia> unshift!([1, 2, 3, 4], 5, 6) - 6-element Array{Int64,1}: - 5 - 6 - 1 - 2 - 3 - 4 .. function:: shift!(collection) -> item - Remove the first "item" from "collection". + 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> A = [1, 2, 3, 4, 5, 6] - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 + julia> shift!(A) + 1 - julia> shift!(A) - 1 + julia> A + 5-element Array{Int64,1}: + 2 + 3 + 4 + 5 + 6 - julia> A - 5-element Array{Int64,1}: - 2 - 3 - 4 - 5 - 6 .. function:: insert!(collection, index, item) - Insert an "item" into "collection" at the given "index". - "index" is the index of "item" in the resulting "collection". + Insert an "item" into "collection" at the given "index". "index" is the index of "item" in the resulting "collection". + + :: + + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 .. function:: deleteat!(collection, itr) - Remove the items at the indices given by "itr", and return the - modified "collection". Subsequent items are shifted to fill the - resulting gap. "itr" must be sorted and unique. + Remove the items at the indices given by "itr", and return the modified "collection". Subsequent items are shifted to fill the resulting gap. "itr" must be sorted and unique. + + :: - 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], 1:2:5) + 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 + in deleteat! at array.jl:631 - julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 .. function:: deleteat!(collection, itr) - Remove the items at the indices given by "itr", and return the - modified "collection". Subsequent items are shifted to fill the - resulting gap. "itr" must be sorted and unique. + Remove the items at the indices given by "itr", and return the modified "collection". Subsequent items are shifted to fill the resulting gap. "itr" must be sorted and unique. + + :: + + 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], 1:2:5) - 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 + in deleteat! at array.jl:631 - julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 .. function:: splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down to - fill the resulting gap. If specified, replacement values from an - ordered collection will be spliced in place of the removed items. + Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)". + 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> 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 - julia> A - 8-element Array{Int64,1}: - -1 - -2 - -3 - 2 - 5 - 4 - 3 - -1 .. function:: splice!(collection, range[, replacement]) -> items - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down to - fill the resulting gap. If specified, replacement values from an - ordered collection will be spliced in place of the removed items. + Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down 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)". + + :: - 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> 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 - julia> A - 8-element Array{Int64,1}: - -1 - -2 - -3 - 2 - 5 - 4 - 3 - -1 .. function:: resize!(collection, n) -> collection - Resize "collection" 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 + Resize "collection" 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 + .. function:: append!(collection, collection2) -> collection. - Add the elements of "collection2" to the end of "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]) + 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 + 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)". - 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)". .. function:: prepend!(collection, items) -> collection - Insert the elements of "items" to the beginning of - "collection". + Insert the elements of "items" to the beginning of "collection". + + :: + + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 Fully implemented by: @@ -1112,24 +1141,23 @@ changed efficiently. .. function:: PriorityQueue(K, V[, ord]) - Construct a new "PriorityQueue", with keys of type "K" and - values/priorites of type "V". If an order is not given, the - priority queue is min-ordered using the default comparison for - "V". + Construct a new "PriorityQueue", with keys of type "K" and values/priorites of type "V". If an order is not given, the priority queue is min-ordered using the default comparison for "V". + .. function:: enqueue!(pq, k, v) - Insert the a key "k" into a priority queue "pq" with priority - "v". + Insert the a key "k" into a priority queue "pq" with priority "v". + .. function:: dequeue!(pq) - Remove and return the lowest priority key from a priority queue. + Remove and return the lowest priority key from a priority queue. + .. function:: peek(pq) - Return the lowest priority key from a priority queue without - removing that key from the queue. + Return the lowest priority key from a priority queue without removing that key from the queue. + :obj:`PriorityQueue` also behaves similarly to a :obj:`Dict` in that keys can be inserted and priorities accessed or changed using indexing notation. @@ -1163,27 +1191,26 @@ is used, so that elements popped from the heap are given in ascending order. .. function:: heapify(v[, ord]) - Return a new vector in binary heap order, optionally using the - given ordering. + Return a new vector in binary heap order, optionally using the given ordering. + .. function:: heapify!(v[, ord]) - In-place "heapify()". + In-place "heapify()". + .. function:: isheap(v[, ord]) - Return true iff an array is heap-ordered according to the given - order. + Return true iff an array is heap-ordered according to the given order. + .. function:: heappush!(v, x[, ord]) - Given a binary heap-ordered array, push a new element "x", - preserving the heap property. For efficiency, this function does - not check that the array is indeed heap-ordered. + Given a binary heap-ordered array, push a new element "x", preserving the heap property. For efficiency, this function does not check that the array is indeed heap-ordered. + .. function:: heappop!(v[, ord]) - Given a binary heap-ordered array, remove and return the lowest - ordered element. For efficiency, this function does not check that - the array is indeed heap-ordered. + Given a binary heap-ordered array, remove and return the lowest ordered element. For efficiency, this function does not check that the array is indeed heap-ordered. + diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index eb07661ac47f1..49be03c0b8f98 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -49,43 +49,28 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. + Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. + Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. + Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. + Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. + .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. + Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. + .. function:: Dates.DateFormat(format::AbstractString) -> DateFormat @@ -93,260 +78,237 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Similar form as above for parsing a "DateTime", but passes a - "DateFormat" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a "DateFormat" object then use this - method for parsing. + Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". + Parse a date from a date string "dt" using a "DateFormat" object "df". + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". + Parse a date from a date string "dt" using a "DateFormat" object "df". + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". + Parse a date from a date string "dt" using a "DateFormat" object "df". + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". + Parse a date from a date string "dt" using a "DateFormat" object "df". + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". + Parse a date from a date string "dt" using a "DateFormat" object "df". + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string "dt" using a "DateFormat" - object "df". + Parse a date from a date string "dt" using a "DateFormat" object "df". + .. function:: now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as - UTC/GMT. + Returns a DateTime corresponding to the user's system time as UTC/GMT. + .. function:: now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time as - UTC/GMT. + Returns a DateTime corresponding to the user's system time as UTC/GMT. + .. function:: eps(::DateTime) -> Millisecond + eps(::Date) -> Day + + Returns "Millisecond(1)" for "DateTime" values and "Day(1)" for "Date" values. - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" - for "Date" values. Accessor Functions ~~~~~~~~~~~~~~~~~~ .. function:: year(dt::TimeType) -> Int64 - week(dt::TimeType) -> Int64 - day(dt::TimeType) -> Int64 - hour(dt::TimeType) -> Int64 - minute(dt::TimeType) -> Int64 - second(dt::TimeType) -> Int64 - millisecond(dt::TimeType) -> Int64 + month(dt::TimeType) -> Int64 week(dt::TimeType) -> Int64 day(dt::TimeType) -> Int64 hour(dt::TimeType) -> Int64 minute(dt::TimeType) -> Int64 second(dt::TimeType) -> Int64 millisecond(dt::TimeType) -> Int64 + + Return the field part of a Date or DateTime as an "Int64". - Return the field part of a Date or DateTime as an "Int64". .. function:: Year(v) - Week(v) - Day(v) - Hour(v) - Minute(v) - Second(v) - Millisecond(v) + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) + + Construct a "Period" type with the given "v" value. Input must be losslessly convertible to an "Int64". - Construct a "Period" type with the given "v" value. Input must - be losslessly convertible to an "Int64". .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) - Simultaneously return the year and month parts of a Date or - DateTime. + Simultaneously return the year and month parts of a Date or DateTime. + .. function:: monthday(dt::TimeType) -> (Int64, Int64) - Simultaneously return the month and day parts of a Date or - DateTime. + Simultaneously return the month and day parts of a Date or DateTime. + .. function:: yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - Simultaneously return the year, month, and day parts of a Date or - DateTime. + Simultaneously return the year, month, and day parts of a Date or DateTime. + Query Functions ~~~~~~~~~~~~~~~ .. function:: dayname(dt::TimeType; locale="english") -> AbstractString - Return the full day name corresponding to the day of the week of - the Date or DateTime in the given "locale". + Return the full day name corresponding to the day of the week of the Date or DateTime in the given "locale". + .. function:: dayabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated name corresponding to the day of the week of - the Date or DateTime in the given "locale". + Return the abbreviated name corresponding to the day of the week of the Date or DateTime in the given "locale". + .. function:: dayofweek(dt::TimeType) -> Int64 - Returns the day of the week as an "Int64" with "1 = Monday, 2 = - Tuesday, etc.". + Returns the day of the week as an "Int64" with "1 = Monday, 2 = Tuesday, etc.". + .. function:: dayofweekofmonth(dt::TimeType) -> Int - For the day of week of "dt", returns which number it is in - "dt"'s month. So if the day of the week of "dt" is Monday, then - "1 = First Monday of the month, 2 = Second Monday of the month, - etc." In the range 1:5. + For the day of week of "dt", returns which number it is in "dt"'s month. So if the day of the week of "dt" is Monday, then "1 = First Monday of the month, 2 = Second Monday of the month, etc." In the range 1:5. + .. function:: daysofweekinmonth(dt::TimeType) -> Int - For the day of week of "dt", returns the total number of that day - of the week in "dt"'s month. Returns 4 or 5. Useful in temporal - expressions for specifying the last day of a week in a month by - including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the - adjuster function. + For the day of week of "dt", returns the total number of that day of the week in "dt"'s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the adjuster function. + .. function:: monthname(dt::TimeType; locale="english") -> AbstractString - Return the full name of the month of the Date or DateTime in the - given "locale". + Return the full name of the month of the Date or DateTime in the given "locale". + .. function:: monthabbr(dt::TimeType; locale="english") -> AbstractString - Return the abbreviated month name of the Date or DateTime in the - given "locale". + Return the abbreviated month name of the Date or DateTime in the given "locale". + .. function:: daysinmonth(dt::TimeType) -> Int - Returns the number of days in the month of "dt". Value will be - 28, 29, 30, or 31. + Returns the number of days in the month of "dt". Value will be 28, 29, 30, or 31. + .. function:: isleapyear(dt::TimeType) -> Bool - Returns true if the year of "dt" is a leap year. + Returns true if the year of "dt" is a leap year. + .. function:: dayofyear(dt::TimeType) -> Int - Returns the day of the year for "dt" with January 1st being day - 1. + Returns the day of the year for "dt" with January 1st being day 1. + .. function:: daysinyear(dt::TimeType) -> Int - Returns 366 if the year of "dt" is a leap year, otherwise returns - 365. + Returns 366 if the year of "dt" is a leap year, otherwise returns 365. + .. function:: quarterofyear(dt::TimeType) -> Int - Returns the quarter that "dt" resides in. Range of value is 1:4. + Returns the quarter that "dt" resides in. Range of value is 1:4. + .. function:: dayofquarter(dt::TimeType) -> Int - Returns the day of the current quarter of "dt". Range of value is - 1:92. + Returns the day of the current quarter of "dt". Range of value is 1:92. + Adjuster Functions ~~~~~~~~~~~~~~~~~~ .. function:: trunc([T], x[, digits[, base]]) - "trunc(x)" returns the nearest integral value of the same type as - "x" whose absolute value is less than or equal to "x". + "trunc(x)" returns the nearest integral value of the same type as "x" whose absolute value is less than or equal to "x". - "trunc(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. + "trunc(T, x)" converts the result to type "T", throwing an "InexactError" if the value is not representable. + + "digits" and "base" work as for "round()". - "digits" and "base" work as for "round()". .. function:: firstdayofweek(dt::TimeType) -> TimeType - Adjusts "dt" to the Monday of its week. + Adjusts "dt" to the Monday of its week. + .. function:: lastdayofweek(dt::TimeType) -> TimeType - Adjusts "dt" to the Sunday of its week. + Adjusts "dt" to the Sunday of its week. + .. function:: firstdayofmonth(dt::TimeType) -> TimeType - Adjusts "dt" to the first day of its month. + Adjusts "dt" to the first day of its month. + .. function:: lastdayofmonth(dt::TimeType) -> TimeType - Adjusts "dt" to the last day of its month. + Adjusts "dt" to the last day of its month. + .. function:: firstdayofyear(dt::TimeType) -> TimeType - Adjusts "dt" to the first day of its year. + Adjusts "dt" to the first day of its year. + .. function:: lastdayofyear(dt::TimeType) -> TimeType - Adjusts "dt" to the last day of its year. + Adjusts "dt" to the last day of its year. + .. function:: firstdayofquarter(dt::TimeType) -> TimeType - Adjusts "dt" to the first day of its quarter. + Adjusts "dt" to the first day of its quarter. + .. function:: lastdayofquarter(dt::TimeType) -> TimeType - Adjusts "dt" to the last day of its quarter. + Adjusts "dt" to the last day of its quarter. + .. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. + Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. + .. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. + Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. + .. function:: tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts "dt" to the first "dow" of its month. Alternatively, - "of=Year" will adjust to the first "dow" of the year. + Adjusts "dt" to the first "dow" of its month. Alternatively, "of=Year" will adjust to the first "dow" of the year. + .. function:: tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - Adjusts "dt" to the last "dow" of its month. Alternatively, - "of=Year" will adjust to the last "dow" of the year. + Adjusts "dt" to the last "dow" of its month. Alternatively, "of=Year" will adjust to the last "dow" of the year. + .. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. + Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. + .. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts "dt" by iterating at most "limit" iterations by - "step" increments until "func" returns true. "func" must take - a single "TimeType" argument and return a "Bool". "same" - allows "dt" to be considered in satisfying "func". "negate" - will make the adjustment process terminate when "func" returns - false instead of true. + Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. + .. function:: recur{T<:TimeType}(func::Function,dr::StepRange{T};negate=false,limit=10000) -> Vector{T} @@ -361,58 +323,53 @@ Periods .. function:: Year(v) - Week(v) - Day(v) - Hour(v) - Minute(v) - Second(v) - Millisecond(v) + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) + + Construct a "Period" type with the given "v" value. Input must be losslessly convertible to an "Int64". - Construct a "Period" type with the given "v" value. Input must - be losslessly convertible to an "Int64". .. function:: default(p::Period) -> Period - Returns a sensible "default" value for the input Period by - returning "one(p)" for Year, Month, and Day, and "zero(p)" for - Hour, Minute, Second, and Millisecond. + Returns a sensible "default" value for the input Period by returning "one(p)" for Year, Month, and Day, and "zero(p)" for Hour, Minute, Second, and Millisecond. + Conversion Functions ~~~~~~~~~~~~~~~~~~~~ .. function:: today() -> Date - Returns the date portion of "now()". + Returns the date portion of "now()". + .. function:: unix2datetime(x) -> DateTime - Takes the number of seconds since unix epoch - "1970-01-01T00:00:00" and converts to the corresponding DateTime. + Takes the number of seconds since unix epoch "1970-01-01T00:00:00" and converts to the corresponding DateTime. + .. function:: datetime2unix(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of seconds since - the unix epoch as a "Float64". + Takes the given DateTime and returns the number of seconds since the unix epoch as a "Float64". + .. function:: julian2datetime(julian_days) -> DateTime - Takes the number of Julian calendar days since epoch - "-4713-11-24T12:00:00" and returns the corresponding DateTime. + Takes the number of Julian calendar days since epoch "-4713-11-24T12:00:00" and returns the corresponding DateTime. + .. function:: datetime2julian(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of Julian calendar - days since the julian epoch as a "Float64". + Takes the given DateTime and returns the number of Julian calendar days since the julian epoch as a "Float64". + .. function:: rata2datetime(days) -> DateTime - Takes the number of Rata Die days since epoch - "0000-12-31T00:00:00" and returns the corresponding DateTime. + Takes the number of Rata Die days since epoch "0000-12-31T00:00:00" and returns the corresponding DateTime. + .. function:: datetime2rata(dt::TimeType) -> Int64 - Returns the number of Rata Die days since epoch from the given Date - or DateTime. + Returns the number of Rata Die days since epoch from the given Date or DateTime. + Constants ~~~~~~~~~ diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index d40a4bc983dd2..e27ce87709d55 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -7,325 +7,296 @@ .. function:: pwd() -> AbstractString - Get the current working directory. + Get the current working directory. + .. function:: cd(f[, dir]) - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. + Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. + .. function:: cd(f[, dir]) - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. + Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. + .. function:: readdir([dir]) -> Vector{ByteString} - Returns the files and directories in the directory *dir* (or the - current working directory if not given). + Returns the files and directories in the directory *dir* (or the current working directory if not given). + .. function:: mkdir(path[, mode]) - Make a new directory with name "path" and permissions "mode". - "mode" defaults to 0o777, modified by the current file creation - mask. + Make a new directory with name "path" and permissions "mode". "mode" defaults to 0o777, modified by the current file creation mask. + .. function:: mkpath(path[, mode]) - Create all directories in the given "path", with permissions - "mode". "mode" defaults to 0o777, modified by the current file - creation mask. + Create all directories in the given "path", with permissions "mode". "mode" defaults to 0o777, modified by the current file creation mask. + .. function:: symlink(target, link) - Creates a symbolic link to "target" with the name "link". + Creates a symbolic link to "target" with the name "link". + + Note: This function raises an error under operating systems that do not support soft symbolic links, such as Windows XP. - Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. .. function:: readlink(path) -> AbstractString - Returns the value of a symbolic link "path". + Returns the value of a symbolic link "path". + .. function:: chmod(path, mode) - Change the permissions mode of "path" to "mode". Only integer - "mode"s (e.g. 0o777) are currently supported. + Change the permissions mode of "path" to "mode". Only integer "mode"s (e.g. 0o777) are currently supported. + .. function:: stat(file) - Returns a structure whose fields contain information about the - file. The fields of the structure are: - - +-----------+------------------------------------------------------------------------+ - | size | The size (in bytes) of the file | - +-----------+------------------------------------------------------------------------+ - | device | ID of the device that contains the file | - +-----------+------------------------------------------------------------------------+ - | inode | The inode number of the file | - +-----------+------------------------------------------------------------------------+ - | mode | The protection mode of the file | - +-----------+------------------------------------------------------------------------+ - | nlink | The number of hard links to the file | - +-----------+------------------------------------------------------------------------+ - | uid | The user id of the owner of the file | - +-----------+------------------------------------------------------------------------+ - | gid | The group id of the file owner | - +-----------+------------------------------------------------------------------------+ - | rdev | If this file refers to a device, the ID of the device it refers to | - +-----------+------------------------------------------------------------------------+ - | blksize | The file-system preferred block size for the file | - +-----------+------------------------------------------------------------------------+ - | blocks | The number of such blocks allocated | - +-----------+------------------------------------------------------------------------+ - | mtime | Unix timestamp of when the file was last modified | - +-----------+------------------------------------------------------------------------+ - | ctime | Unix timestamp of when the file was created | - +-----------+------------------------------------------------------------------------+ + Returns a structure whose fields contain information about the file. The fields of the structure are: + + +–––––-+––––––––––––––––––––––––––––––––––––+ | size | The size (in bytes) of the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | device | ID of the device that contains the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | inode | The inode number of the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | mode | The protection mode of the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | nlink | The number of hard links to the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | uid | The user id of the owner of the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | gid | The group id of the file owner | +–––––-+––––––––––––––––––––––––––––––––––––+ | rdev | If this file refers to a device, the ID of the device it refers to | +–––––-+––––––––––––––––––––––––––––––––––––+ | blksize | The file-system preferred block size for the file | +–––––-+––––––––––––––––––––––––––––––––––––+ | blocks | The number of such blocks allocated | +–––––-+––––––––––––––––––––––––––––––––––––+ | mtime | Unix timestamp of when the file was last modified | +–––––-+––––––––––––––––––––––––––––––––––––+ | ctime | Unix timestamp of when the file was created | +–––––-+––––––––––––––––––––––––––––––––––––+ + .. function:: lstat(file) - Like stat, but for symbolic links gets the info for the link itself - rather than the file it refers to. This function must be called on - a file path rather than a file object or a file descriptor. + Like stat, but for symbolic links gets the info for the link itself rather than the file it refers to. This function must be called on a file path rather than a file object or a file descriptor. + .. function:: ctime(file) - Equivalent to stat(file).ctime + Equivalent to stat(file).ctime + .. function:: mtime(file) - Equivalent to stat(file).mtime + Equivalent to stat(file).mtime + .. function:: filemode(file) - Equivalent to stat(file).mode + Equivalent to stat(file).mode + .. function:: filesize(path...) - Equivalent to stat(file).size + Equivalent to stat(file).size + .. function:: uperm(file) - Gets the permissions of the owner of the file as a bitfield of + Gets the permissions of the owner of the file as a bitfield of + + +–––+–––––––––––-+ | 01 | Execute Permission | +–––+–––––––––––-+ | 02 | Write Permission | +–––+–––––––––––-+ | 04 | Read Permission | +–––+–––––––––––-+ - +------+-----------------------+ - | 01 | Execute Permission | - +------+-----------------------+ - | 02 | Write Permission | - +------+-----------------------+ - | 04 | Read Permission | - +------+-----------------------+ + For allowed arguments, see "stat". - For allowed arguments, see "stat". .. function:: gperm(file) - Like uperm but gets the permissions of the group owning the file + Like uperm but gets the permissions of the group owning the file + .. function:: operm(file) - Like uperm but gets the permissions for people who neither own the - file nor are a member of the group owning the file + Like uperm but gets the permissions for people who neither own the file nor are a member of the group owning the file + .. function:: cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - Copy the file, link, or directory from *src* to *dest*. - "remove_destination=true" will first remove an existing *dst*. + Copy the file, link, or directory from *src* to *dest*. "remove_destination=true" will first remove an existing *dst*. + + If *follow_symlinks=false*, and src is a symbolic link, dst will be created as a symbolic link. If *follow_symlinks=true* and src is a symbolic link, dst will be a copy of the file or directory *src* refers to. - If *follow_symlinks=false*, and src is a symbolic link, dst will be - created as a symbolic link. If *follow_symlinks=true* and src is a - symbolic link, dst will be a copy of the file or directory *src* - refers to. .. function:: download(url[, localfile]) - Download a file from the given url, optionally renaming it to the - given local file name. Note that this function relies on the - availability of external tools such as "curl", "wget" or - "fetch" to download the file and is provided for convenience. For - production use or situations in which more options are need, please - use a package that provides the desired functionality instead. + Download a file from the given url, optionally renaming it to the given local file name. Note that this function relies on the availability of external tools such as "curl", "wget" or "fetch" to download the file and is provided for convenience. For production use or situations in which more options are need, please use a package that provides the desired functionality instead. + .. function:: mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - Move the file, link, or directory from *src* to *dest*. - "remove_destination=true" will first remove an existing *dst*. + Move the file, link, or directory from *src* to *dest*. "remove_destination=true" will first remove an existing *dst*. + .. function:: rm(path::AbstractString; recursive=false) - Delete the file, link, or empty directory at the given path. If - "recursive=true" is passed and the path is a directory, then all - contents are removed recursively. + Delete the file, link, or empty directory at the given path. If "recursive=true" is passed and the path is a directory, then all contents are removed recursively. + .. function:: touch(path::AbstractString) - Update the last-modified timestamp on a file to the current time. + Update the last-modified timestamp on a file to the current time. + .. function:: tempname() - Generate a unique temporary file path. + Generate a unique temporary file path. + .. function:: tempdir() - Obtain the path of a temporary directory (possibly shared with - other processes). + Obtain the path of a temporary directory (possibly shared with other processes). + .. function:: mktemp([parent=tempdir()]) - Returns "(path, io)", where "path" is the path of a new - temporary file in "parent" and "io" is an open file object for - this path. + Returns "(path, io)", where "path" is the path of a new temporary file in "parent" and "io" is an open file object for this path. + .. function:: mktempdir([parent=tempdir()]) - Create a temporary directory in the "parent" directory and return - its path. + Create a temporary directory in the "parent" directory and return its path. + .. function:: isblockdev(path) -> Bool - Returns "true" if "path" is a block device, "false" - otherwise. + Returns "true" if "path" is a block device, "false" otherwise. + .. function:: ischardev(path) -> Bool - Returns "true" if "path" is a character device, "false" - otherwise. + Returns "true" if "path" is a character device, "false" otherwise. + .. function:: isdir(path) -> Bool - Returns "true" if "path" is a directory, "false" otherwise. + Returns "true" if "path" is a directory, "false" otherwise. + .. function:: isexecutable(path) -> Bool - Returns "true" if the current user has permission to execute - "path", "false" otherwise. + Returns "true" if the current user has permission to execute "path", "false" otherwise. + .. function:: isfifo(path) -> Bool - Returns "true" if "path" is a FIFO, "false" otherwise. + Returns "true" if "path" is a FIFO, "false" otherwise. + .. function:: isfile(path) -> Bool - Returns "true" if "path" is a regular file, "false" - otherwise. + Returns "true" if "path" is a regular file, "false" otherwise. + .. function:: islink(path) -> Bool - Returns "true" if "path" is a symbolic link, "false" - otherwise. + Returns "true" if "path" is a symbolic link, "false" otherwise. + .. function:: ismount(path) -> Bool - Returns "true" if "path" is a mount point, "false" otherwise. + Returns "true" if "path" is a mount point, "false" otherwise. + .. function:: ispath(path) -> Bool - Returns "true" if "path" is a valid filesystem path, "false" - otherwise. + Returns "true" if "path" is a valid filesystem path, "false" otherwise. + .. function:: isreadable(path) -> Bool - Returns "true" if the current user has permission to read - "path", "false" otherwise. + Returns "true" if the current user has permission to read "path", "false" otherwise. + .. function:: issetgid(path) -> Bool - Returns "true" if "path" has the setgid flag set, "false" - otherwise. + Returns "true" if "path" has the setgid flag set, "false" otherwise. + .. function:: issetuid(path) -> Bool - Returns "true" if "path" has the setuid flag set, "false" - otherwise. + Returns "true" if "path" has the setuid flag set, "false" otherwise. + .. function:: issocket(path) -> Bool - Returns "true" if "path" is a socket, "false" otherwise. + Returns "true" if "path" is a socket, "false" otherwise. + .. function:: issticky(path) -> Bool - Returns "true" if "path" has the sticky bit set, "false" - otherwise. + Returns "true" if "path" has the sticky bit set, "false" otherwise. + .. function:: iswritable(path) -> Bool - Returns "true" if the current user has permission to write to - "path", "false" otherwise. + Returns "true" if the current user has permission to write to "path", "false" otherwise. + .. function:: homedir() -> AbstractString - Return the current user's home directory. + Return the current user's home directory. + .. function:: dirname(path::AbstractString) -> AbstractString - Get the directory part of a path. + Get the directory part of a path. + .. function:: basename(path::AbstractString) -> AbstractString - Get the file name part of a path. + Get the file name part of a path. + .. function:: @__FILE__() -> AbstractString - "@__FILE__" expands to a string with the absolute path and file - name of the script being run. Returns "nothing" if run from a - REPL or an empty string if evaluated by "julia -e ". + "@__FILE__" expands to a string with the absolute path and file name of the script being run. Returns "nothing" if run from a REPL or an empty string if evaluated by "julia -e ". + .. function:: isabspath(path::AbstractString) -> Bool - Determines whether a path is absolute (begins at the root - directory). + Determines whether a path is absolute (begins at the root directory). + .. function:: isdirpath(path::AbstractString) -> Bool - Determines whether a path refers to a directory (for example, ends - with a path separator). + Determines whether a path refers to a directory (for example, ends with a path separator). + .. function:: joinpath(parts...) -> AbstractString - Join path components into a full path. If some argument is an - absolute path, then prior components are dropped. + Join path components into a full path. If some argument is an absolute path, then prior components are dropped. + .. function:: abspath(path::AbstractString) -> AbstractString - Convert a path to an absolute path by adding the current directory - if necessary. + Convert a path to an absolute path by adding the current directory if necessary. + .. function:: normpath(path::AbstractString) -> AbstractString - Normalize a path, removing "." and ".." entries. + Normalize a path, removing "." and ".." entries. + .. function:: realpath(path::AbstractString) -> AbstractString - Canonicalize a path by expanding symbolic links and removing "." - and ".." entries. + Canonicalize a path by expanding symbolic links and removing "." and ".." entries. + .. function:: relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString - Return a relative filepath to path either from the current - directory or from an optional start directory. This is a path - computation: the filesystem is not accessed to confirm the - existence or nature of path or startpath. + Return a relative filepath to path either from the current directory or from an optional start directory. This is a path computation: the filesystem is not accessed to confirm the existence or nature of path or startpath. + .. function:: expanduser(path::AbstractString) -> AbstractString - On Unix systems, replace a tilde character at the start of a path - with the current user's home directory. + On Unix systems, replace a tilde character at the start of a path with the current user's home directory. + .. function:: splitdir(path::AbstractString) -> (AbstractString, AbstractString) - Split a path into a tuple of the directory name and file name. + Split a path into a tuple of the directory name and file name. + .. function:: splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - On Windows, split a path into the drive letter part and the path - part. On Unix systems, the first component is always the empty - string. + On Windows, split a path into the drive letter part and the path part. On Unix systems, the first component is always the empty string. + .. function:: splitext(path::AbstractString) -> (AbstractString, AbstractString) - If the last component of a path contains a dot, split the path into - everything before the dot and everything including and after the - dot. Otherwise, return a tuple of the argument unmodified and the - empty string. + If the last component of a path contains a dot, split the path into everything before the dot and everything including and after the dot. Otherwise, return a tuple of the argument unmodified and the empty string. + diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 45b96f1392472..6b365d4d096a7 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -21,495 +21,434 @@ General I/O .. function:: open(f::function, args...) - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. + + **Example**: "open(readall, "file.txt")" - **Example**: "open(readall, "file.txt")" .. function:: open(f::function, args...) - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. + + **Example**: "open(readall, "file.txt")" - **Example**: "open(readall, "file.txt")" .. function:: open(f::function, args...) - Apply the function "f" to the result of "open(args...)" and - close the resulting file descriptor upon completion. + Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. + + **Example**: "open(readall, "file.txt")" - **Example**: "open(readall, "file.txt")" .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer([data][, readable, writable[, maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: takebuf_array(b::IOBuffer) - Obtain the contents of an "IOBuffer" as an array, without - copying. Afterwards, the IOBuffer is reset to its initial state. + Obtain the contents of an "IOBuffer" as an array, without copying. Afterwards, the IOBuffer is reset to its initial state. + .. function:: takebuf_string(b::IOBuffer) - Obtain the contents of an "IOBuffer" as a string, without - copying. Afterwards, the IOBuffer is reset to its initial state. + Obtain the contents of an "IOBuffer" as a string, without copying. Afterwards, the IOBuffer is reset to its initial state. + .. function:: fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - Create an "IOStream" object from an integer file descriptor. If - "own" is true, closing this object will close the underlying - descriptor. By default, an "IOStream" is closed when it is - garbage collected. "name" allows you to associate the descriptor - with a named file. + Create an "IOStream" object from an integer file descriptor. If "own" is true, closing this object will close the underlying descriptor. By default, an "IOStream" is closed when it is garbage collected. "name" allows you to associate the descriptor with a named file. + .. function:: flush(stream) - Commit all currently buffered writes to the given stream. + Commit all currently buffered writes to the given stream. + .. function:: close(stream) - Close an I/O stream. Performs a "flush" first. + Close an I/O stream. Performs a "flush" first. + .. function:: write(stream, x) - Write the canonical binary representation of a value to the given - stream. + Write the canonical binary representation of a value to the given stream. + .. function:: read(stream, type, dims) - Read a series of values of the given type from a stream, in - canonical binary representation. "dims" is either a tuple or a - series of integer arguments specifying the size of "Array" to - return. + Read a series of values of the given type from a stream, in canonical binary representation. "dims" is either a tuple or a series of integer arguments specifying the size of "Array" to return. + .. function:: read(stream, type, dims) - Read a series of values of the given type from a stream, in - canonical binary representation. "dims" is either a tuple or a - series of integer arguments specifying the size of "Array" to - return. + Read a series of values of the given type from a stream, in canonical binary representation. "dims" is either a tuple or a series of integer arguments specifying the size of "Array" to return. + .. function:: read!(stream, array::Array) - Read binary data from a stream, filling in the argument "array". + Read binary data from a stream, filling in the argument "array". + .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - Read at most "nb" bytes from the stream into "b", returning the - number of bytes read (increasing the size of "b" as needed). + Read at most "nb" bytes from the stream into "b", returning the number of bytes read (increasing the size of "b" as needed). + .. function:: readbytes(stream, nb=typemax(Int)) - Read at most "nb" bytes from the stream, returning a - "Vector{UInt8}" of the bytes read. + Read at most "nb" bytes from the stream, returning a "Vector{UInt8}" of the bytes read. + .. function:: position(s) - Get the current position of a stream. + Get the current position of a stream. + .. function:: seek(s, pos) - Seek a stream to the given position. + Seek a stream to the given position. + .. function:: seekstart(s) - Seek a stream to its beginning. + Seek a stream to its beginning. + .. function:: seekend(s) - Seek a stream to its end. + Seek a stream to its end. + .. function:: skip(s, offset) - Seek a stream relative to the current position. + Seek a stream relative to the current position. + .. function:: mark(s) - Add a mark at the current position of stream "s". Returns the - marked position. + Add a mark at the current position of stream "s". Returns the marked position. + + See also "unmark()", "reset()", "ismarked()" - See also "unmark()", "reset()", "ismarked()" .. function:: unmark(s) - Remove a mark from stream "s". Returns "true" if the stream was - marked, "false" otherwise. + Remove a mark from stream "s". Returns "true" if the stream was marked, "false" otherwise. + + See also "mark()", "reset()", "ismarked()" - See also "mark()", "reset()", "ismarked()" .. function:: reset(s) - Reset a stream "s" to a previously marked position, and remove - the mark. Returns the previously marked position. Throws an error - if the stream is not marked. + Reset a stream "s" to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked. + + See also "mark()", "unmark()", "ismarked()" - See also "mark()", "unmark()", "ismarked()" .. function:: ismarked(s) - Returns true if stream "s" is marked. + Returns true if stream "s" is marked. + + See also "mark()", "unmark()", "reset()" - See also "mark()", "unmark()", "reset()" .. function:: eof(stream) -> Bool - Tests whether an I/O stream is at end-of-file. If the stream is not - yet exhausted, this function will block to wait for more data if - necessary, and then return "false". Therefore it is always safe - to read one byte after seeing "eof" return "false". "eof" - will return "false" as long as buffered data is still available, - even if the remote end of a connection is closed. + Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return "false". Therefore it is always safe to read one byte after seeing "eof" return "false". "eof" will return "false" as long as buffered data is still available, even if the remote end of a connection is closed. + .. function:: isreadonly(stream) -> Bool - Determine whether a stream is read-only. + Determine whether a stream is read-only. + .. function:: isopen(stream) -> Bool - Determine whether a stream is open (i.e. has not been closed yet). - If the connection has been closed remotely (in case of e.g. a - socket), "isopen" will return "false" even though buffered data - may still be available. Use "eof" to check if necessary. + Determine whether a stream is open (i.e. has not been closed yet). If the connection has been closed remotely (in case of e.g. a socket), "isopen" will return "false" even though buffered data may still be available. Use "eof" to check if necessary. + .. function:: serialize(stream, value) - Write an arbitrary value to a stream in an opaque format, such that - it can be read back by "deserialize". The read-back value will be - as identical as possible to the original. In general, this process - will not work if the reading and writing are done by different - versions of Julia, or an instance of Julia with a different system - image. + Write an arbitrary value to a stream in an opaque format, such that it can be read back by "deserialize". The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. + .. function:: deserialize(stream) - Read a value written by "serialize". + Read a value written by "serialize". + .. function:: print_escaped(io, str::AbstractString, esc::AbstractString) - General escaping of traditional C and Unicode escape sequences, - plus any characters in esc are also escaped (with a backslash). + General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). + .. function:: print_unescaped(io, s::AbstractString) - General unescaping of traditional C and Unicode escape sequences. - Reverse of "print_escaped()". + General unescaping of traditional C and Unicode escape sequences. Reverse of "print_escaped()". + .. function:: print_joined(io, items, delim[, last]) - Print elements of "items" to "io" with "delim" between them. - If "last" is specified, it is used as the final delimiter instead - of "delim". + Print elements of "items" to "io" with "delim" between them. If "last" is specified, it is used as the final delimiter instead of "delim". + .. function:: print_shortest(io, x) - Print the shortest possible representation, with the minimum number - of consecutive non-zero digits, of number "x", ensuring that it - would parse to the exact same number. + Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number "x", ensuring that it would parse to the exact same number. + .. function:: fd(stream) - Returns the file descriptor backing the stream or file. Note that - this function only applies to synchronous *File*'s and *IOStream*'s - not to any of the asynchronous streams. + Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. + .. function:: redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + .. function:: redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. + .. function:: redirect_stderr([stream]) - Like redirect_stdout, but for STDERR + Like redirect_stdout, but for STDERR + .. function:: redirect_stdin([stream]) - Like redirect_stdout, but for STDIN. Note that the order of the - return tuple is still (rd,wr), i.e. data to be read from STDIN, may - be written to wr. + Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read from STDIN, may be written to wr. + .. function:: readchomp(x) - Read the entirety of x as a string but remove trailing newlines. - Equivalent to chomp(readall(x)). + Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). + .. function:: truncate(file, n) - Resize the file or buffer given by the first argument to exactly - *n* bytes, filling previously unallocated space with '\0' if the - file or buffer is grown + Resize the file or buffer given by the first argument to exactly *n* bytes, filling previously unallocated space with '\0' if the file or buffer is grown + .. function:: skipchars(stream, predicate; linecomment::Char) - Advance the stream until before the first character for which - "predicate" returns false. For example "skipchars(stream, - isspace)" will skip all whitespace. If keyword argument - "linecomment" is specified, characters from that character - through the end of a line will also be skipped. + Advance the stream until before the first character for which "predicate" returns false. For example "skipchars(stream, isspace)" will skip all whitespace. If keyword argument "linecomment" is specified, characters from that character through the end of a line will also be skipped. + .. function:: countlines(io[, eol::Char]) - Read io until the end of the stream/file and count the number of - non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than '\n' are supported by passing - them as the second argument. + Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first argument. EOL markers other than '\n' are supported by passing them as the second argument. + .. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. + Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. + .. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. + Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. + .. function:: readavailable(stream) - Read all available data on the stream, blocking the task only if no - data is available. The result is a "Vector{UInt8,1}". + Read all available data on the stream, blocking the task only if no data is available. The result is a "Vector{UInt8,1}". + Text I/O -------- .. function:: show(x) - Write an informative text representation of a value to the current - output stream. New types should overload "show(io, x)" where the - first argument is a stream. The representation used by "show" - generally includes Julia-specific formatting and type information. + Write an informative text representation of a value to the current output stream. New types should overload "show(io, x)" where the first argument is a stream. The representation used by "show" generally includes Julia-specific formatting and type information. + .. function:: showcompact(x) - Show a more compact representation of a value. This is used for - printing array elements. If a new type has a different compact - representation, it should overload "showcompact(io, x)" where the - first argument is a stream. + Show a more compact representation of a value. This is used for printing array elements. If a new type has a different compact representation, it should overload "showcompact(io, x)" where the first argument is a stream. + .. function:: showall(x) - Similar to "show", except shows all elements of arrays. + Similar to "show", except shows all elements of arrays. + .. function:: summary(x) - Return a string giving a brief description of a value. By default - returns "string(typeof(x))". For arrays, returns strings like - "2x2 Float64 Array". + Return a string giving a brief description of a value. By default returns "string(typeof(x))". For arrays, returns strings like "2x2 Float64 Array". + .. function:: print(x) - Write (to the default output stream) a canonical (un-decorated) - text representation of a value if there is one, otherwise call - "show". The representation used by "print" includes minimal - formatting and tries to avoid Julia-specific details. + Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call "show". The representation used by "print" includes minimal formatting and tries to avoid Julia-specific details. + .. function:: println(x) - Print (using "print()") "x" followed by a newline. + Print (using "print()") "x" followed by a newline. + .. function:: print_with_color(color::Symbol[, io], strings...) - Print strings in a color specified as a symbol, for example - ":red" or ":blue". + Print strings in a color specified as a symbol, for example ":red" or ":blue". + .. function:: info(msg) - Display an informational message. + Display an informational message. + .. function:: warn(msg) - Display a warning. + Display a warning. + .. function:: @printf([io::IOStream], "%Fmt", args...) - Print arg(s) using C "printf()" style format specification - string. Optionally, an IOStream may be passed as the first argument - to redirect output. + Print arg(s) using C "printf()" style format specification string. Optionally, an IOStream may be passed as the first argument to redirect output. + .. function:: @sprintf("%Fmt", args...) - Return "@printf" formatted output as string. + Return "@printf" formatted output as string. + .. function:: sprint(f::Function, args...) - Call the given function with an I/O stream and the supplied extra - arguments. Everything written to this I/O stream is returned as a - string. + Call the given function with an I/O stream and the supplied extra arguments. Everything written to this I/O stream is returned as a string. + .. function:: showerror(io, e) - Show a descriptive representation of an exception object. + Show a descriptive representation of an exception object. + .. function:: dump(x) - Show all user-visible structure of a value. + Show all user-visible structure of a value. + .. function:: xdump(x) - Show all structure of a value, including all fields of objects. + Show all structure of a value, including all fields of objects. + .. function:: readall(filename::AbstractString) - Open "filename", read the entire contents as a string, then close - the file. Equivalent to "open(readall, filename)". + Open "filename", read the entire contents as a string, then close the file. Equivalent to "open(readall, filename)". + .. function:: readall(filename::AbstractString) - Open "filename", read the entire contents as a string, then close - the file. Equivalent to "open(readall, filename)". + Open "filename", read the entire contents as a string, then close the file. Equivalent to "open(readall, filename)". + .. function:: readline(stream=STDIN) - Read a single line of text, including a trailing newline character - (if one is reached before the end of the input), from the given - "stream" (defaults to "STDIN"), + Read a single line of text, including a trailing newline character (if one is reached before the end of the input), from the given "stream" (defaults to "STDIN"), + .. function:: readuntil(stream, delim) - Read a string, up to and including the given delimiter byte. + Read a string, up to and including the given delimiter byte. + .. function:: readlines(stream) - Read all lines as an array. + Read all lines as an array. + .. function:: eachline(stream) - Create an iterable object that will yield each line from a stream. + Create an iterable object that will yield each line from a stream. + .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as "\n". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: writedlm(f, A, delim='\t') - Write "A" (a vector, matrix or an iterable collection of iterable - rows) as text to "f" (either a filename string or an "IO" - stream) using the given delimeter "delim" (which defaults to tab, - but can be any printable Julia object, typically a "Char" or - "AbstractString"). + Write "A" (a vector, matrix or an iterable collection of iterable rows) as text to "f" (either a filename string or an "IO" stream) using the given delimeter "delim" (which defaults to tab, but can be any printable Julia object, typically a "Char" or "AbstractString"). + + For example, two vectors "x" and "y" of the same length can be written as two columns of tab-delimited text to "f" by either "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". - For example, two vectors "x" and "y" of the same length can be - written as two columns of tab-delimited text to "f" by either - "writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". .. function:: readcsv(source, [T::Type]; options...) - Equivalent to "readdlm" with "delim" set to comma. + Equivalent to "readdlm" with "delim" set to comma. + .. function:: writecsv(filename, A) - Equivalent to "writedlm" with "delim" set to comma. + Equivalent to "writedlm" with "delim" set to comma. + .. function:: Base64EncodePipe(ostream) - Returns a new write-only I/O stream, which converts any bytes - written to it into base64-encoded ASCII bytes written to - "ostream". Calling "close" on the "Base64Pipe" stream is - necessary to complete the encoding (but does not close - "ostream"). + Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to "ostream". Calling "close" on the "Base64Pipe" stream is necessary to complete the encoding (but does not close "ostream"). + .. function:: Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded - data read from "istream". + Returns a new read-only I/O stream, which decodes base64-encoded data read from "istream". + .. function:: base64encode(writefunc, args...) + base64encode(args...) + + Given a "write"-like function "writefunc", which takes an I/O stream as its first argument, "base64(writefunc, args...)" calls "writefunc" to write "args..." to a base64-encoded string, and returns the string. "base64(args...)" is equivalent to "base64(write, args...)": it converts its arguments into bytes using the standard "write" functions and returns the base64-encoded string. - Given a "write"-like function "writefunc", which takes an I/O - stream as its first argument, "base64(writefunc, args...)" calls - "writefunc" to write "args..." to a base64-encoded string, and - returns the string. "base64(args...)" is equivalent to - "base64(write, args...)": it converts its arguments into bytes - using the standard "write" functions and returns the - base64-encoded string. .. function:: base64decode(string) - Decodes the base64-encoded "string" and returns a - "Vector{UInt8}" of the decoded bytes. + Decodes the base64-encoded "string" and returns a "Vector{UInt8}" of the decoded bytes. + Multimedia I/O -------------- @@ -534,101 +473,52 @@ Julia environments (such as the IPython-based IJulia notebook). .. function:: display(x) - display(mime, x) - display(d::Display, mime, x) - - Display "x" using the topmost applicable display in the display - stack, typically using the richest supported multimedia output for - "x", with plain-text "STDOUT" output as a fallback. The - "display(d, x)" variant attempts to display "x" on the given - display "d" only, throwing a "MethodError" if "d" cannot - display objects of this type. - - There are also two variants with a "mime" argument (a MIME type - string, such as ""image/png""), which attempt to display "x" - using the requested MIME type *only*, throwing a "MethodError" if - this type is not supported by either the display(s) or by "x". - With these variants, one can also supply the "raw" data in the - requested MIME type by passing "x::AbstractString" (for MIME - types with text-based storage, such as text/html or - application/postscript) or "x::Vector{UInt8}" (for binary MIME - types). + display(d::Display, x) display(mime, x) display(d::Display, mime, x) + + Display "x" using the topmost applicable display in the display stack, typically using the richest supported multimedia output for "x", with plain-text "STDOUT" output as a fallback. The "display(d, x)" variant attempts to display "x" on the given display "d" only, throwing a "MethodError" if "d" cannot display objects of this type. + + There are also two variants with a "mime" argument (a MIME type string, such as ""image/png""), which attempt to display "x" using the requested MIME type *only*, throwing a "MethodError" if this type is not supported by either the display(s) or by "x". With these variants, one can also supply the "raw" data in the requested MIME type by passing "x::AbstractString" (for MIME types with text-based storage, such as text/html or application/postscript) or "x::Vector{UInt8}" (for binary MIME types). + .. function:: redisplay(x) - redisplay(mime, x) - redisplay(d::Display, mime, x) + redisplay(d::Display, x) redisplay(mime, x) redisplay(d::Display, mime, x) + + By default, the "redisplay" functions simply call "display". However, some display backends may override "redisplay" to modify an existing display of "x" (if any). Using "redisplay" is also a hint to the backend that "x" may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt. - By default, the "redisplay" functions simply call "display". - However, some display backends may override "redisplay" to modify - an existing display of "x" (if any). Using "redisplay" is - also a hint to the backend that "x" may be redisplayed several - times, and the backend may choose to defer the display until (for - example) the next interactive prompt. .. function:: displayable(mime) -> Bool + displayable(d::Display, mime) -> Bool + + Returns a boolean value indicating whether the given "mime" type (string) is displayable by any of the displays in the current display stack, or specifically by the display "d" in the second variant. - Returns a boolean value indicating whether the given "mime" type - (string) is displayable by any of the displays in the current - display stack, or specifically by the display "d" in the second - variant. .. function:: writemime(stream, mime, x) - The "display" functions ultimately call "writemime" in order to - write an object "x" as a given "mime" type to a given I/O - "stream" (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - "T", it is only necessary to define a new "writemime" method - for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", - where "mime" is a MIME-type string and the function body calls - "write" (or similar) to write that representation of "x" to - "stream". (Note that the "MIME""" notation only supports - literal strings; to construct "MIME" types in a more flexible - manner use "MIME{symbol("")}".) - - For example, if you define a "MyImage" type and know how to write - it to a PNG file, you could define a function "writemime(stream, - ::MIME"image/png", x::MyImage) = ...`" to allow your images to - be displayed on any PNG-capable "Display" (such as IJulia). As - usual, be sure to "import Base.writemime" in order to add new - methods to the built-in Julia function "writemime". - - Technically, the "MIME"mime"" macro defines a singleton type - for the given "mime" string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. + The "display" functions ultimately call "writemime" in order to write an object "x" as a given "mime" type to a given I/O "stream" (usually a memory buffer), if possible. In order to provide a rich multimedia representation of a user-defined type "T", it is only necessary to define a new "writemime" method for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", where "mime" is a MIME-type string and the function body calls "write" (or similar) to write that representation of "x" to "stream". (Note that the "MIME""" notation only supports literal strings; to construct "MIME" types in a more flexible manner use "MIME{symbol("")}".) + + For example, if you define a "MyImage" type and know how to write it to a PNG file, you could define a function "writemime(stream, ::MIME"image/png", x::MyImage) = ...`" to allow your images to be displayed on any PNG-capable "Display" (such as IJulia). As usual, be sure to "import Base.writemime" in order to add new methods to the built-in Julia function "writemime". + + Technically, the "MIME"mime"" macro defines a singleton type for the given "mime" string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type. + .. function:: mimewritable(mime, x) - Returns a boolean value indicating whether or not the object "x" - can be written as the given "mime" type. (By default, this is - determined automatically by the existence of the corresponding - "writemime" function for "typeof(x)".) + Returns a boolean value indicating whether or not the object "x" can be written as the given "mime" type. (By default, this is determined automatically by the existence of the corresponding "writemime" function for "typeof(x)".) + .. function:: reprmime(mime, x) - Returns an "AbstractString" or "Vector{UInt8}" containing the - representation of "x" in the requested "mime" type, as written - by "writemime" (throwing a "MethodError" if no appropriate - "writemime" is available). An "AbstractString" is returned for - MIME types with textual representations (such as ""text/html"" - or ""application/postscript""), whereas binary data is returned - as "Vector{UInt8}". (The function "istext(mime)" returns - whether or not Julia treats a given "mime" type as text.) + Returns an "AbstractString" or "Vector{UInt8}" containing the representation of "x" in the requested "mime" type, as written by "writemime" (throwing a "MethodError" if no appropriate "writemime" is available). An "AbstractString" is returned for MIME types with textual representations (such as ""text/html"" or ""application/postscript""), whereas binary data is returned as "Vector{UInt8}". (The function "istext(mime)" returns whether or not Julia treats a given "mime" type as text.) + + As a special case, if "x" is an "AbstractString" (for textual MIME types) or a "Vector{UInt8}" (for binary MIME types), the "reprmime" function assumes that "x" is already in the requested "mime" format and simply returns "x". - As a special case, if "x" is an "AbstractString" (for textual - MIME types) or a "Vector{UInt8}" (for binary MIME types), the - "reprmime" function assumes that "x" is already in the - requested "mime" format and simply returns "x". .. function:: stringmime(mime, x) - Returns an "AbstractString" containing the representation of - "x" in the requested "mime" type. This is similar to - "reprmime" except that binary data is base64-encoded as an ASCII - string. + Returns an "AbstractString" containing the representation of "x" in the requested "mime" type. This is similar to "reprmime" except that binary data is base64-encoded as an ASCII string. + As mentioned above, one can also define new display backends. For example, a module that can display PNG images in a window can register @@ -658,249 +548,200 @@ stack with: .. function:: pushdisplay(d::Display) - Pushes a new display "d" on top of the global display-backend - stack. Calling "display(x)" or "display(mime, x)" will display - "x" on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a "MethodError"). + Pushes a new display "d" on top of the global display-backend stack. Calling "display(x)" or "display(mime, x)" will display "x" on the topmost compatible backend in the stack (i.e., the topmost backend that does not throw a "MethodError"). + .. function:: popdisplay() + popdisplay(d::Display) + + Pop the topmost backend off of the display-backend stack, or the topmost copy of "d" in the second variant. - Pop the topmost backend off of the display-backend stack, or the - topmost copy of "d" in the second variant. .. function:: TextDisplay(stream) - Returns a "TextDisplay <: Display", which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same as - the way an object is printed in the Julia REPL.) + Returns a "TextDisplay <: Display", which can display any object as the text/plain MIME type (only), writing the text representation to the given I/O stream. (The text representation is the same as the way an object is printed in the Julia REPL.) + .. function:: istext(m::MIME) - Determine whether a MIME type is text data. + Determine whether a MIME type is text data. + Memory-mapped I/O ----------------- .. function:: mmap_array(type, dims, stream[, offset]) - Create an "Array" whose values are linked to a file, using - memory-mapping. This provides a convenient way of working with data - too large to fit in the computer's memory. + Create an "Array" whose values are linked to a file, using memory-mapping. This provides a convenient way of working with data too large to fit in the computer's memory. - The type determines how the bytes of the array are interpreted. - Note that the file must be stored in binary format, and no format - conversions are possible (this is a limitation of operating - systems, not Julia). + The type determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). - "dims" is a tuple specifying the size of the array. + "dims" is a tuple specifying the size of the array. - The file is passed via the stream argument. When you initialize - the stream, use ""r"" for a "read-only" array, and ""w+"" - to create a new array used to write values to disk. + The file is passed via the stream argument. When you initialize the stream, use ""r"" for a "read-only" array, and ""w+"" to create a new array used to write values to disk. - Optionally, you can specify an offset (in bytes) if, for example, - you want to skip over a header in the file. The default value for - the offset is the current stream position. + Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position. - For example, the following code: + For example, the following code: - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open("/tmp/mmap.bin", "w+") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) + :: - # Test by reading it back in - s = open("/tmp/mmap.bin") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) - creates a "m"-by-"n" "Matrix{Int}", linked to the file - associated with stream "s". + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) + + creates a "m"-by-"n" "Matrix{Int}", linked to the file associated with stream "s". + + A more portable file would need to encode the word size–-32 bit or 64 bit–-and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). - A more portable file would need to encode the word size---32 bit or - 64 bit---and endianness information in the header. In practice, - consider encoding binary data using standard formats like HDF5 - (which can be used with memory-mapping). .. function:: mmap_bitarray([type], dims, stream[, offset]) - Create a "BitArray" whose values are linked to a file, using - memory-mapping; it has the same purpose, works in the same way, and - has the same arguments, as "mmap_array()", but the byte - representation is different. The "type" parameter is optional, - and must be "Bool" if given. + Create a "BitArray" whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as "mmap_array()", but the byte representation is different. The "type" parameter is optional, and must be "Bool" if given. - **Example**: "B = mmap_bitarray((25,30000), s)" + **Example**: "B = mmap_bitarray((25,30000), s)" + + This would create a 25-by-30000 "BitArray", linked to the file associated with stream "s". - This would create a 25-by-30000 "BitArray", linked to the file - associated with stream "s". .. function:: msync(ptr, len[, flags]) - Forces synchronization of the "mmap()"ped memory region from - "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a - combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See - your platform man page for specifics. The flags argument is not - valid on Windows. + Forces synchronization of the "mmap()"ped memory region from "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See your platform man page for specifics. The flags argument is not valid on Windows. + + You may not need to call "msync", because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. - You may not need to call "msync", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. Network I/O ----------- .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id "pid", specified - by "config" and return a pair of "AsyncStream" objects. - Messages from "pid" to current process will be read off - "instrm", while messages to be sent to "pid" will be written to - "outstrm". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - "Base.connect(manager::ClusterManager.....)" sets up TCP/IP - socket connections in-between workers. + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id "pid", specified by "config" and return a pair of "AsyncStream" objects. Messages from "pid" to current process will be read off "instrm", while messages to be sent to "pid" will be written to "outstrm". The custom transport implementation must ensure that messages are delivered and received completely and in order. "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. + .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id "pid", specified - by "config" and return a pair of "AsyncStream" objects. - Messages from "pid" to current process will be read off - "instrm", while messages to be sent to "pid" will be written to - "outstrm". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - "Base.connect(manager::ClusterManager.....)" sets up TCP/IP - socket connections in-between workers. + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id "pid", specified by "config" and return a pair of "AsyncStream" objects. Messages from "pid" to current process will be read off "instrm", while messages to be sent to "pid" will be written to "outstrm". The custom transport implementation must ensure that messages are delivered and received completely and in order. "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. + .. function:: listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket + Listens on/Creates a Named Pipe/Domain Socket + .. function:: listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket + Listens on/Creates a Named Pipe/Domain Socket + .. function:: getaddrinfo(host) - Gets the IP address of the "host" (may have to do a DNS lookup) + Gets the IP address of the "host" (may have to do a DNS lookup) + .. function:: parseip(addr) - Parse a string specifying an IPv4 or IPv6 ip address. + Parse a string specifying an IPv4 or IPv6 ip address. + .. function:: IPv4(host::Integer) -> IPv4 - Returns IPv4 object from ip address formatted as Integer + Returns IPv4 object from ip address formatted as Integer + .. function:: IPv6(host::Integer) -> IPv6 - Returns IPv6 object from ip address formatted as Integer + Returns IPv6 object from ip address formatted as Integer + .. function:: nb_available(stream) - Returns the number of bytes available for reading before a read - from this stream or buffer will block. + Returns the number of bytes available for reading before a read from this stream or buffer will block. + .. function:: accept(server[, client]) - Accepts a connection on the given server and returns a connection - to the client. An uninitialized client stream may be provided, in - which case it will be used instead of creating a new stream. + Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. + .. function:: listenany(port_hint) -> (UInt16, TcpServer) - Create a TcpServer on any port, using hint as a starting point. - Returns a tuple of the actual port that the server was created on - and the server itself. + Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server was created on and the server itself. + .. function:: watch_file(cb=false, s; poll=false) - Watch file or directory "s" and run callback "cb" when "s" is - modified. The "poll" parameter specifies whether to use file - system event monitoring or polling. The callback function "cb" - should accept 3 arguments: "(filename, events, status)" where - "filename" is the name of file that was modified, "events" is - an object with boolean fields "changed" and "renamed" when - using file system event monitoring, or "readable" and - "writable" when using polling, and "status" is always 0. Pass - "false" for "cb" to not use a callback function. + Watch file or directory "s" and run callback "cb" when "s" is modified. The "poll" parameter specifies whether to use file system event monitoring or polling. The callback function "cb" should accept 3 arguments: "(filename, events, status)" where "filename" is the name of file that was modified, "events" is an object with boolean fields "changed" and "renamed" when using file system event monitoring, or "readable" and "writable" when using polling, and "status" is always 0. Pass "false" for "cb" to not use a callback function. + .. function:: poll_fd(fd, seconds::Real; readable=false, writable=false) - Poll a file descriptor fd for changes in the read or write - availability and with a timeout given by the second argument. If - the timeout is not needed, use "wait(fd)" instead. The keyword - arguments determine which of read and/or write status should be - monitored and at least one of them needs to be set to true. The - returned value is an object with boolean fields "readable", - "writable", and "timedout", giving the result of the polling. + Poll a file descriptor fd for changes in the read or write availability and with a timeout given by the second argument. If the timeout is not needed, use "wait(fd)" instead. The keyword arguments determine which of read and/or write status should be monitored and at least one of them needs to be set to true. The returned value is an object with boolean fields "readable", "writable", and "timedout", giving the result of the polling. + .. function:: poll_file(s, interval_seconds::Real, seconds::Real) - Monitor a file for changes by polling every *interval_seconds* - seconds for *seconds* seconds. A return value of true indicates the - file changed, a return value of false indicates a timeout. + Monitor a file for changes by polling every *interval_seconds* seconds for *seconds* seconds. A return value of true indicates the file changed, a return value of false indicates a timeout. + .. function:: bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - Bind "socket" to the given "host:port". Note that *0.0.0.0* - will listen on all devices. + Bind "socket" to the given "host:port". Note that *0.0.0.0* will listen on all devices. + .. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) - Send "msg" over "socket to ``host:port". + Send "msg" over "socket to ``host:port". + .. function:: recv(socket::UDPSocket) - Read a UDP packet from the specified socket, and return the bytes - received. This call blocks. + Read a UDP packet from the specified socket, and return the bytes received. This call blocks. + .. function:: recvfrom(socket::UDPSocket) -> (address, data) - Read a UDP packet from the specified socket, returning a tuple of - (address, data), where address will be either IPv4 or IPv6 as - appropriate. + Read a UDP packet from the specified socket, returning a tuple of (address, data), where address will be either IPv4 or IPv6 as appropriate. + .. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - Set UDP socket options. "multicast_loop": loopback for multicast - packets (default: true). "multicast_ttl": TTL for multicast - packets. "enable_broadcast": flag must be set to true if socket - will be used for broadcast messages, or else the UDP system will - return an access error (default: false). "ttl": Time-to-live of - packets sent on the socket. + Set UDP socket options. "multicast_loop": loopback for multicast packets (default: true). "multicast_ttl": TTL for multicast packets. "enable_broadcast": flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). "ttl": Time-to-live of packets sent on the socket. + .. function:: ntoh(x) - Converts the endianness of a value from Network byte order (big- - endian) to that used by the Host. + Converts the endianness of a value from Network byte order (big- endian) to that used by the Host. + .. function:: hton(x) - Converts the endianness of a value from that used by the Host to - Network byte order (big-endian). + Converts the endianness of a value from that used by the Host to Network byte order (big-endian). + .. function:: ltoh(x) - Converts the endianness of a value from Little-endian to that used - by the Host. + Converts the endianness of a value from Little-endian to that used by the Host. + .. function:: htol(x) - Converts the endianness of a value from that used by the Host to - Little-endian. + Converts the endianness of a value from that used by the Host to Little-endian. + .. data:: ENDIAN_BOM diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index 6b9663f2dc446..a566f072eeb66 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -6,87 +6,69 @@ .. function:: malloc(size::Integer) -> Ptr{Void} - Call "malloc" from the C standard library. + Call "malloc" from the C standard library. + .. function:: calloc(num::Integer, size::Integer) -> Ptr{Void} - Call "calloc" from the C standard library. + Call "calloc" from the C standard library. + .. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void} - Call "realloc" from the C standard library. + Call "realloc" from the C standard library. + + See warning in the documentation for "free" regarding only using this on memory originally obtained from "malloc". - See warning in the documentation for "free" regarding only using - this on memory originally obtained from "malloc". .. function:: free(addr::Ptr) - Call "free" from the C standard library. Only use this on memory - obtained from "malloc", not on pointers retrieved from other C - libraries. "Ptr" objects obtained from C libraries should be - freed by the free functions defined in that library, to avoid - assertion failures if multiple "libc" libraries exist on the - system. + Call "free" from the C standard library. Only use this on memory obtained from "malloc", not on pointers retrieved from other C libraries. "Ptr" objects obtained from C libraries should be freed by the free functions defined in that library, to avoid assertion failures if multiple "libc" libraries exist on the system. + .. function:: errno([code]) - Get the value of the C library's "errno". If an argument is - specified, it is used to set the value of "errno". + Get the value of the C library's "errno". If an argument is specified, it is used to set the value of "errno". + + The value of "errno" is only valid immediately after a "ccall" to a C library routine that sets it. Specifically, you cannot call "errno" at the next prompt in a REPL, because lots of code is executed between prompts. - The value of "errno" is only valid immediately after a "ccall" - to a C library routine that sets it. Specifically, you cannot call - "errno" at the next prompt in a REPL, because lots of code is - executed between prompts. .. function:: strerror(n) - Convert a system call error code to a descriptive string + Convert a system call error code to a descriptive string + .. function:: time(t::TmStruct) - Converts a "TmStruct" struct to a number of seconds since the - epoch. + Converts a "TmStruct" struct to a number of seconds since the epoch. + .. function:: strftime([format], time) - Convert time, given as a number of seconds since the epoch or a - "TmStruct", to a formatted string using the given format. - Supported formats are the same as those in the standard C library. + Convert time, given as a number of seconds since the epoch or a "TmStruct", to a formatted string using the given format. Supported formats are the same as those in the standard C library. + .. function:: strptime([format], timestr) - Parse a formatted time string into a "TmStruct" giving the - seconds, minute, hour, date, etc. Supported formats are the same as - those in the standard C library. On some platforms, timezones will - not be parsed correctly. If the result of this function will be - passed to "time" to convert it to seconds since the epoch, the - "isdst" field should be filled in manually. Setting it to "-1" - will tell the C library to use the current system settings to - determine the timezone. + Parse a formatted time string into a "TmStruct" giving the seconds, minute, hour, date, etc. Supported formats are the same as those in the standard C library. On some platforms, timezones will not be parsed correctly. If the result of this function will be passed to "time" to convert it to seconds since the epoch, the "isdst" field should be filled in manually. Setting it to "-1" will tell the C library to use the current system settings to determine the timezone. + .. function:: TmStruct([seconds]) - Convert a number of seconds since the epoch to broken-down format, - with fields "sec", "min", "hour", "mday", "month", - "year", "wday", "yday", and "isdst". + Convert a number of seconds since the epoch to broken-down format, with fields "sec", "min", "hour", "mday", "month", "year", "wday", "yday", and "isdst". + .. function:: flush_cstdio() - Flushes the C "stdout" and "stderr" streams (which may have - been written to by external C code). + Flushes the C "stdout" and "stderr" streams (which may have been written to by external C code). + .. function:: msync(ptr, len[, flags]) - Forces synchronization of the "mmap()"ped memory region from - "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a - combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See - your platform man page for specifics. The flags argument is not - valid on Windows. + Forces synchronization of the "mmap()"ped memory region from "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See your platform man page for specifics. The flags argument is not valid on Windows. + + You may not need to call "msync", because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. - You may not need to call "msync", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. .. data:: MS_ASYNC @@ -102,11 +84,11 @@ .. function:: mmap(len, prot, flags, fd, offset) - Low-level interface to the "mmap" system call. See the man page. + Low-level interface to the "mmap" system call. See the man page. + .. function:: munmap(pointer, len) - Low-level interface for unmapping memory (see the man page). With - "mmap_array()" you do not need to call this directly; the memory - is unmapped for you when the array goes out of scope. + Low-level interface for unmapping memory (see the man page). With "mmap_array()" you do not need to call this directly; the memory is unmapped for you when the array goes out of scope. + diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index 9788d78ba13d5..5d246bb018819 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -6,25 +6,15 @@ .. function:: dlopen(libfile::AbstractString[, flags::Integer]) - Load a shared library, returning an opaque handle. - - The optional flags argument is a bitwise-or of zero or more of - "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", - "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and - "RTLD_FIRST". These are converted to the corresponding flags of - the POSIX (and/or GNU libc and/or MacOS) dlopen command, if - possible, or are ignored if the specified functionality is not - available on the current platform. The default is - "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of - these flags, on POSIX platforms, is to specify - "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's - symbols to be available for usage in other shared libraries, in - situations where there are dependencies between shared libraries. + Load a shared library, returning an opaque handle. + + The optional flags argument is a bitwise-or of zero or more of "RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", "RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and "RTLD_FIRST". These are converted to the corresponding flags of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default is "RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of these flags, on POSIX platforms, is to specify "RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's symbols to be available for usage in other shared libraries, in situations where there are dependencies between shared libraries. + .. function:: dlopen_e(libfile::AbstractString[, flags::Integer]) - Similar to "dlopen()", except returns a "NULL" pointer instead - of raising errors. + Similar to "dlopen()", except returns a "NULL" pointer instead of raising errors. + .. data:: RTLD_DEEPBIND @@ -60,27 +50,23 @@ .. function:: dlsym(handle, sym) - Look up a symbol from a shared library handle, return callable - function pointer on success. + Look up a symbol from a shared library handle, return callable function pointer on success. + .. function:: dlsym_e(handle, sym) - Look up a symbol from a shared library handle, silently return NULL - pointer on lookup failure. + Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. + .. function:: dlclose(handle) - Close shared library referenced by handle. + Close shared library referenced by handle. + .. function:: find_library(names, locations) - Searches for the first library in "names" in the paths in the - "locations" list, "DL_LOAD_PATH", or system library paths (in - that order) which can successfully be dlopen'd. On success, the - return value will be one of the names (potentially prefixed by one - of the paths in locations). This string can be assigned to a - "global const" and used as the library name in future - "ccall"'s. On failure, it returns the empty string. + Searches for the first library in "names" in the paths in the "locations" list, "DL_LOAD_PATH", or system library paths (in that order) which can successfully be dlopen'd. On success, the return value will be one of the names (potentially prefixed by one of the paths in locations). This string can be assigned to a "global const" and used as the library name in future "ccall"'s. On failure, it returns the empty string. + .. data:: DL_LOAD_PATH diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index f7f1500895fcd..43cb0c55f06f0 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -15,11 +15,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: *(s, t) - Concatenate strings. The "*" operator is an alias to this - function. + Concatenate strings. The "*" operator is an alias to this function. + + :: + + julia> "Hello " * "world" + "Hello world" - julia> "Hello " * "world" - "Hello world" .. function:: \\(A, B) :noindex: @@ -30,983 +32,750 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: dot(x, y) + ⋅(x, y) + + Compute the dot product. For complex vectors, the first vector is conjugated. - Compute the dot product. For complex vectors, the first vector is - conjugated. .. function:: vecdot(x, y) - For any iterable containers "x" and "y" (including arrays of - any dimension) of numbers (or any element type for which "dot" is - defined), compute the Euclidean dot product (the sum of - "dot(x[i],y[i])") as if they were vectors. + For any iterable containers "x" and "y" (including arrays of any dimension) of numbers (or any element type for which "dot" is defined), compute the Euclidean dot product (the sum of "dot(x[i],y[i])") as if they were vectors. + .. function:: cross(x, y) + ×(x, y) + + Compute the cross product of two 3-vectors. - Compute the cross product of two 3-vectors. .. function:: factorize(A) - Compute a convenient factorization (including LU, Cholesky, Bunch- - Kaufman, LowerTriangular, UpperTriangular) of A, based upon the - type of the input matrix. The return value can then be reused for - efficient solving of multiple systems. For example: - "A=factorize(A); x=A\\b; y=A\\C". + Compute a convenient factorization (including LU, Cholesky, Bunch- Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: "A=factorize(A); x=A\b; y=A\C". + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a - "QRCompactWYQ" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. + Converts an orthogonal or unitary matrix stored as a "QRCompactWYQ" object, i.e. in the compact WY format [Bischof1987], to a dense matrix. + + Optionally takes a "thin" Boolean argument, which if "true" omits the columns that span the rows of "R" in the QR factorization that are zero. The resulting matrix is the "Q" in a thin QR factorization (sometimes called the reduced QR factorization). If "false", returns a "Q" that spans all rows of "R" in its corresponding QR factorization. - Optionally takes a "thin" Boolean argument, which if "true" - omits the columns that span the rows of "R" in the QR - factorization that are zero. The resulting matrix is the "Q" in a - thin QR factorization (sometimes called the reduced QR - factorization). If "false", returns a "Q" that spans all rows - of "R" in its corresponding QR factorization. Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. .. function:: lu(A) -> L, U, p - Compute the LU factorization of "A", such that "A[p,:] = L*U". + Compute the LU factorization of "A", such that "A[p,:] = L*U". + .. function:: lufact(A[, pivot=Val{true}]) -> F - Compute the LU factorization of "A". The return type of "F" - depends on the type of "A". In most cases, if "A" is a subtype - "S" of AbstractMatrix with an element type "T`" supporting - "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If - pivoting is chosen (default) the element type should also support - "abs" and "<". When "A" is sparse and have element of type - "Float32", "Float64", "Complex{Float32}", or - "Complex{Float64}" the return type is "UmfpackLU". Some - examples are shown in the table below. - - +-------------------------+---------------------------+----------------------------------------------+ - | Type of input "A" | Type of output "F" | Relationship between "F" and "A" | - +-------------------------+---------------------------+----------------------------------------------+ - | "Matrix()" | "LU" | "F[:L]*F[:U] == A[F[:p], :]" | - +-------------------------+---------------------------+----------------------------------------------+ - | "Tridiagonal()" | "LU{T,Tridiagonal{T}}" | N/A | - +-------------------------+---------------------------+----------------------------------------------+ - | "SparseMatrixCSC()" | "UmfpackLU" | "F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]" | - +-------------------------+---------------------------+----------------------------------------------+ - - The individual components of the factorization "F" can be - accessed by indexing: - - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | "LU" | "LU{T,Tridiagonal{T}}" | "UmfpackLU" | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:L]" | "L" (lower triangular) part of "LU" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:U]" | "U" (upper triangular) part of "LU" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:p]" | (right) permutation "Vector" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:P]" | (right) permutation "Matrix" | ✓ | | | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:q]" | left permutation "Vector" | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:Rs]" | "Vector" of scaling factors | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | "F[:(:)]" | "(L,U,p,q,Rs)" components | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - - +--------------------+--------+--------------------------+---------------+ - | Supported function | "LU" | "LU{T,Tridiagonal{T}}" | "UmfpackLU" | - +--------------------+--------+--------------------------+---------------+ - | "/" | ✓ | | | - +--------------------+--------+--------------------------+---------------+ - | "\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | "cond" | ✓ | | ✓ | - +--------------------+--------+--------------------------+---------------+ - | "det" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | "logdet" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | "logabsdet" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | "size" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ + Compute the LU factorization of "A". The return type of "F" depends on the type of "A". In most cases, if "A" is a subtype "S" of AbstractMatrix with an element type "T`" supporting "+", "-", "*" and "/" the return type is "LU{T,S{T}}". If pivoting is chosen (default) the element type should also support "abs" and "<". When "A" is sparse and have element of type "Float32", "Float64", "Complex{Float32}", or "Complex{Float64}" the return type is "UmfpackLU". Some examples are shown in the table below. + + :: + + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input "A" | Type of output "F" | Relationship between "F" and "A" | + +-------------------------+---------------------------+----------------------------------------------+ + | "Matrix()" | "LU" | "F[:L]*F[:U] == A[F[:p], :]" | + +-------------------------+---------------------------+----------------------------------------------+ + | "Tridiagonal()" | "LU{T,Tridiagonal{T}}" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | "SparseMatrixCSC()" | "UmfpackLU" | "F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]" | + +-------------------------+---------------------------+----------------------------------------------+ + + The individual components of the factorization "F" can be accessed by indexing: + + :: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | "LU" | "LU{T,Tridiagonal{T}}" | "UmfpackLU" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:L]" | "L" (lower triangular) part of "LU" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:U]" | "U" (upper triangular) part of "LU" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:p]" | (right) permutation "Vector" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:P]" | (right) permutation "Matrix" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:q]" | left permutation "Vector" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:Rs]" | "Vector" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | "F[:(:)]" | "(L,U,p,q,Rs)" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | "LU" | "LU{T,Tridiagonal{T}}" | "UmfpackLU" | + +--------------------+--------+--------------------------+---------------+ + | "/" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | "\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | "cond" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | "det" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | "logdet" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | "logabsdet" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | "size" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + .. function:: lufact!(A) -> LU - "lufact!" is the same as "lufact()", but saves space by - overwriting the input A, instead of creating a copy. For sparse - "A" the "nzval" field is not overwritten but the index fields, - "colptr" and "rowval" are decremented in place, converting from - 1-based indices to 0-based indices. + "lufact!" is the same as "lufact()", but saves space by overwriting the input A, instead of creating a copy. For sparse "A" the "nzval" field is not overwritten but the index fields, "colptr" and "rowval" are decremented in place, converting from 1-based indices to 0-based indices. + .. function:: chol(A[, LU]) -> F - Compute the Cholesky factorization of a symmetric positive definite - matrix "A" and return the matrix "F". If "LU" is "Val{:U}" - (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If - "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" - and "A = F*F'". "LU" defaults to "Val{:U}". + Compute the Cholesky factorization of a symmetric positive definite matrix "A" and return the matrix "F". If "LU" is "Val{:U}" (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" and "A = F*F'". "LU" defaults to "Val{:U}". + .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite - matrix "A". A fill-reducing permutation is used. "F = - cholfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors - from "F", using "F[:L]". However, since pivoting is on by - default, the factorization is internally represented as "A == - P'*L*L'*P" with a permutation matrix "P"; using just "L" - without accounting for "P" will give incorrect answers. To - include the effects of permutation, it's typically preferable to - extact "combined" factors like "PtL = F[:PtL]" (the equivalent - of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + Compute the Cholesky factorization of a sparse positive definite matrix "A". A fill-reducing permutation is used. "F = cholfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + + Setting optional "shift" keyword argument computes the factorization of "A+shift*I" instead of "A". If the "perm" argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the Cholesky factorization of a sparse positive definite - matrix "A". A fill-reducing permutation is used. "F = - cholfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors - from "F", using "F[:L]". However, since pivoting is on by - default, the factorization is internally represented as "A == - P'*L*L'*P" with a permutation matrix "P"; using just "L" - without accounting for "P" will give incorrect answers. To - include the effects of permutation, it's typically preferable to - extact "combined" factors like "PtL = F[:PtL]" (the equivalent - of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + Compute the Cholesky factorization of a sparse positive definite matrix "A". A fill-reducing permutation is used. "F = cholfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + + Setting optional "shift" keyword argument computes the factorization of "A+shift*I" instead of "A". If the "perm" argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - "cholfact!" is the same as "cholfact()", but saves space by - overwriting the input "A", instead of creating a copy. - "cholfact!" can also reuse the symbolic factorization from a - different matrix "F" with the same structure when used as: - "cholfact!(F::CholmodFactor, A)". + "cholfact!" is the same as "cholfact()", but saves space by overwriting the input "A", instead of creating a copy. "cholfact!" can also reuse the symbolic factorization from a different matrix "F" with the same structure when used as: "cholfact!(F::CholmodFactor, A)". + .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix "A". A fill-reducing permutation is used. "F = - ldltfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors from - "F", using "F[:L]". However, since pivoting is on by default, - the factorization is internally represented as "A == P'*L*D*L'*P" - with a permutation matrix "P"; using just "L" without - accounting for "P" will give incorrect answers. To include the - effects of permutation, it's typically preferable to extact - "combined" factors like "PtL = F[:PtL]" (the equivalent of - "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The - complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, - :DU, :PtLD, :DUP". - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + Compute the LDLt factorization of a sparse symmetric or Hermitian matrix "A". A fill-reducing permutation is used. "F = ldltfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*D*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, :DU, :PtLD, :DUP". + + Setting optional "shift" keyword argument computes the factorization of "A+shift*I" instead of "A". If the "perm" argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix "A". A fill-reducing permutation is used. "F = - ldltfact(A)" is most frequently used to solve systems of equations - with "F\b", but also the methods "diag", "det", "logdet" - are defined for "F". You can also extract individual factors from - "F", using "F[:L]". However, since pivoting is on by default, - the factorization is internally represented as "A == P'*L*D*L'*P" - with a permutation matrix "P"; using just "L" without - accounting for "P" will give incorrect answers. To include the - effects of permutation, it's typically preferable to extact - "combined" factors like "PtL = F[:PtL]" (the equivalent of - "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The - complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, - :DU, :PtLD, :DUP". - - Setting optional "shift" keyword argument computes the - factorization of "A+shift*I" instead of "A". If the "perm" - argument is nonempty, it should be a permutation of *1:size(A,1)* - giving the ordering to use (instead of CHOLMOD's default AMD - ordering). - - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + Compute the LDLt factorization of a sparse symmetric or Hermitian matrix "A". A fill-reducing permutation is used. "F = ldltfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*D*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, :DU, :PtLD, :DUP". + + Setting optional "shift" keyword argument computes the factorization of "A+shift*I" instead of "A". If the "perm" argument is nonempty, it should be a permutation of *1:size(A,1)* giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. + .. function:: qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - Compute the (pivoted) QR factorization of "A" such that either - "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default - is to compute a thin factorization. Note that "R" is not extended - with zeros when the full "Q" is requested. + Compute the (pivoted) QR factorization of "A" such that either "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default is to compute a thin factorization. Note that "R" is not extended with zeros when the full "Q" is requested. + .. function:: qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix "A". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with "". The function calls the - C library SPQR and a few additional functions from the library are - wrapped but not exported. + Compute the QR factorization of a sparse matrix "A". A fill- reducing permutation is used. The main application of this type is to solve least squares problems with "". The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. + .. function:: qrfact(A) -> SPQR.Factorization - Compute the QR factorization of a sparse matrix "A". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with "". The function calls the - C library SPQR and a few additional functions from the library are - wrapped but not exported. + Compute the QR factorization of a sparse matrix "A". A fill- reducing permutation is used. The main application of this type is to solve least squares problems with "". The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. + .. function:: qrfact!(A[, pivot=Val{false}]) - "qrfact!" is the same as "qrfact()" when A is a subtype of - "StridedMatrix", but saves space by overwriting the input "A", - instead of creating a copy. + "qrfact!" is the same as "qrfact()" when A is a subtype of "StridedMatrix", but saves space by overwriting the input "A", instead of creating a copy. + .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix - Converts an orthogonal or unitary matrix stored as a - "QRCompactWYQ" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. + Converts an orthogonal or unitary matrix stored as a "QRCompactWYQ" object, i.e. in the compact WY format [Bischof1987], to a dense matrix. + + Optionally takes a "thin" Boolean argument, which if "true" omits the columns that span the rows of "R" in the QR factorization that are zero. The resulting matrix is the "Q" in a thin QR factorization (sometimes called the reduced QR factorization). If "false", returns a "Q" that spans all rows of "R" in its corresponding QR factorization. - Optionally takes a "thin" Boolean argument, which if "true" - omits the columns that span the rows of "R" in the QR - factorization that are zero. The resulting matrix is the "Q" in a - thin QR factorization (sometimes called the reduced QR - factorization). If "false", returns a "Q" that spans all rows - of "R" in its corresponding QR factorization. .. function:: bkfact(A) -> BunchKaufman - Compute the Bunch-Kaufman [Bunch1977] factorization of a real - symmetric or complex Hermitian matrix "A" and return a - "BunchKaufman" object. The following functions are available for - "BunchKaufman" objects: "size", "", "inv", "issym", - "ishermitian". + Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix "A" and return a "BunchKaufman" object. The following functions are available for "BunchKaufman" objects: "size", "", "inv", "issym", "ishermitian". + .. [Bunch1977] J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. `url `_. .. function:: bkfact!(A) -> BunchKaufman - "bkfact!" is the same as "bkfact()", but saves space by - overwriting the input "A", instead of creating a copy. + "bkfact!" is the same as "bkfact()", but saves space by overwriting the input "A", instead of creating a copy. + .. function:: sqrtm(A) - Compute the matrix square root of "A". If "B = sqrtm(A)", then - "B*B == A" within roundoff error. + Compute the matrix square root of "A". If "B = sqrtm(A)", then "B*B == A" within roundoff error. + + "sqrtm" uses a polyalgorithm, computing the matrix square root using Schur factorizations ("schurfact()") unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition ("eigfact()"). In the latter situation for positive definite matrices, the matrix square root has "Real" elements, otherwise it has "Complex" elements. - "sqrtm" uses a polyalgorithm, computing the matrix square root - using Schur factorizations ("schurfact()") unless it detects the - matrix to be Hermitian or real symmetric, in which case it computes - the matrix square root from an eigendecomposition ("eigfact()"). - In the latter situation for positive definite matrices, the matrix - square root has "Real" elements, otherwise it has "Complex" - elements. .. function:: eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of "A" with respect - to "B". + Computes generalized eigenvalues and vectors of "A" with respect to "B". + + "eig" is a wrapper around "eigfact()", extracting all parts of the factorization to a tuple; where possible, using "eigfact()" is recommended. - "eig" is a wrapper around "eigfact()", extracting all parts of - the factorization to a tuple; where possible, using "eigfact()" - is recommended. .. function:: eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of "A" with respect - to "B". + Computes generalized eigenvalues and vectors of "A" with respect to "B". + + "eig" is a wrapper around "eigfact()", extracting all parts of the factorization to a tuple; where possible, using "eigfact()" is recommended. - "eig" is a wrapper around "eigfact()", extracting all parts of - the factorization to a tuple; where possible, using "eigfact()" - is recommended. .. function:: eigvals(A,[irange,][vl,][vu]) - Returns the eigenvalues of "A". If "A" is "Symmetric", - "Hermitian" or "SymTridiagonal", it is possible to calculate - only a subset of the eigenvalues by specifying either a - "UnitRange" "irange" covering indices of the sorted - eigenvalues, or a pair "vl" and "vu" for the lower and upper - boundaries of the eigenvalues. + Returns the eigenvalues of "A". If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it is possible to calculate only a subset of the eigenvalues by specifying either a "UnitRange" "irange" covering indices of the sorted eigenvalues, or a pair "vl" and "vu" for the lower and upper boundaries of the eigenvalues. + + For general non-symmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option "permute=true" permutes the matrix to become closer to upper triangular, and "scale=true" scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is "true" for both options. - For general non-symmetric matrices it is possible to specify how - the matrix is balanced before the eigenvector calculation. The - option "permute=true" permutes the matrix to become closer to - upper triangular, and "scale=true" scales the matrix by its - diagonal elements to make rows and columns more equal in norm. The - default is "true" for both options. .. function:: eigmax(A) - Returns the largest eigenvalue of "A". + Returns the largest eigenvalue of "A". + .. function:: eigmin(A) - Returns the smallest eigenvalue of "A". + Returns the smallest eigenvalue of "A". + .. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - Returns a matrix "M" whose columns are the eigenvectors of "A". - (The "k"th eigenvector can be obtained from the slice "M[:, - k]".) The "permute" and "scale" keywords are the same as for - "eigfact()". + Returns a matrix "M" whose columns are the eigenvectors of "A". (The "k"th eigenvector can be obtained from the slice "M[:, k]".) The "permute" and "scale" keywords are the same as for "eigfact()". + + For "SymTridiagonal" matrices, if the optional vector of eigenvalues "eigvals" is specified, returns the specific corresponding eigenvectors. - For "SymTridiagonal" matrices, if the optional vector of - eigenvalues "eigvals" is specified, returns the specific - corresponding eigenvectors. .. function:: eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of "A" and - "B", returning a "GeneralizedEigen" factorization object "F" - which contains the generalized eigenvalues in "F[:values]" and - the generalized eigenvectors in the columns of the matrix - "F[:vectors]". (The "k"th generalized eigenvector can be - obtained from the slice "F[:vectors][:, k]".) + Computes the generalized eigenvalue decomposition of "A" and "B", returning a "GeneralizedEigen" factorization object "F" which contains the generalized eigenvalues in "F[:values]" and the generalized eigenvectors in the columns of the matrix "F[:vectors]". (The "k"th generalized eigenvector can be obtained from the slice "F[:vectors][:, k]".) + .. function:: eigfact(A, B) -> GeneralizedEigen - Computes the generalized eigenvalue decomposition of "A" and - "B", returning a "GeneralizedEigen" factorization object "F" - which contains the generalized eigenvalues in "F[:values]" and - the generalized eigenvectors in the columns of the matrix - "F[:vectors]". (The "k"th generalized eigenvector can be - obtained from the slice "F[:vectors][:, k]".) + Computes the generalized eigenvalue decomposition of "A" and "B", returning a "GeneralizedEigen" factorization object "F" which contains the generalized eigenvalues in "F[:values]" and the generalized eigenvectors in the columns of the matrix "F[:vectors]". (The "k"th generalized eigenvector can be obtained from the slice "F[:vectors][:, k]".) + .. function:: eigfact!(A[, B]) - Same as "eigfact()", but saves space by overwriting the input - "A" (and "B"), instead of creating a copy. + Same as "eigfact()", but saves space by overwriting the input "A" (and "B"), instead of creating a copy. + .. function:: hessfact(A) - Compute the Hessenberg decomposition of "A" and return a - "Hessenberg" object. If "F" is the factorization object, the - unitary matrix can be accessed with "F[:Q]" and the Hessenberg - matrix with "F[:H]". When "Q" is extracted, the resulting type - is the "HessenbergQ" object, and may be converted to a regular - matrix with "full()". + Compute the Hessenberg decomposition of "A" and return a "Hessenberg" object. If "F" is the factorization object, the unitary matrix can be accessed with "F[:Q]" and the Hessenberg matrix with "F[:H]". When "Q" is extracted, the resulting type is the "HessenbergQ" object, and may be converted to a regular matrix with "full()". + .. function:: hessfact!(A) - "hessfact!" is the same as "hessfact()", but saves space by - overwriting the input A, instead of creating a copy. + "hessfact!" is the same as "hessfact()", but saves space by overwriting the input A, instead of creating a copy. + .. function:: schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the - matrices "A" and "B". The (quasi) triangular Schur factors can - be obtained from the "Schur" object "F" with "F[:S]" and - "F[:T]", the left unitary/orthogonal Schur vectors can be - obtained with "F[:left]" or "F[:Q]" and the right - unitary/orthogonal Schur vectors can be obtained with "F[:right]" - or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and - "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of - "A" and "B" can be obtained with "F[:alpha]./F[:beta]". + Computes the Generalized Schur (or QZ) factorization of the matrices "A" and "B". The (quasi) triangular Schur factors can be obtained from the "Schur" object "F" with "F[:S]" and "F[:T]", the left unitary/orthogonal Schur vectors can be obtained with "F[:left]" or "F[:Q]" and the right unitary/orthogonal Schur vectors can be obtained with "F[:right]" or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of "A" and "B" can be obtained with "F[:alpha]./F[:beta]". + .. function:: schurfact!(A) - Computes the Schur factorization of "A", overwriting "A" in the - process. See "schurfact()" + Computes the Schur factorization of "A", overwriting "A" in the process. See "schurfact()" + .. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See "schurfact()" + See "schurfact()" + .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object. See "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". + .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". + .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object. See "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". + .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". + .. function:: schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the - matrices "A" and "B". The (quasi) triangular Schur factors can - be obtained from the "Schur" object "F" with "F[:S]" and - "F[:T]", the left unitary/orthogonal Schur vectors can be - obtained with "F[:left]" or "F[:Q]" and the right - unitary/orthogonal Schur vectors can be obtained with "F[:right]" - or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and - "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of - "A" and "B" can be obtained with "F[:alpha]./F[:beta]". + Computes the Generalized Schur (or QZ) factorization of the matrices "A" and "B". The (quasi) triangular Schur factors can be obtained from the "Schur" object "F" with "F[:S]" and "F[:T]", the left unitary/orthogonal Schur vectors can be obtained with "F[:left]" or "F[:Q]" and the right unitary/orthogonal Schur vectors can be obtained with "F[:right]" or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of "A" and "B" can be obtained with "F[:alpha]./F[:beta]". + .. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - See "schurfact()" + See "schurfact()" + .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object. See "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". + .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". + .. function:: ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object. See "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". + .. function:: ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - "ordschur()". + Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". + .. function:: svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of "A" and "B", returning a - "GeneralizedSVD" Factorization object "F", such that "A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'". + Compute the generalized SVD of "A" and "B", returning a "GeneralizedSVD" Factorization object "F", such that "A = F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = F[:V]*F[:D2]*F[:R0]*F[:Q]'". + .. function:: svdfact!(A[, thin=true]) -> SVD - "svdfact!" is the same as "svdfact()", but saves space by - overwriting the input A, instead of creating a copy. If "thin" is - "true", an economy mode decomposition is returned. The default is - to produce a thin decomposition. + "svdfact!" is the same as "svdfact()", but saves space by overwriting the input A, instead of creating a copy. If "thin" is "true", an economy mode decomposition is returned. The default is to produce a thin decomposition. + .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around "svdfact" extracting all parts the factorization - to a tuple. Direct use of "svdfact" is therefore generally more - efficient. The function returns the generalized SVD of "A" and - "B", returning "U", "V", "Q", "D1", "D2", and "R0" - such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". + Wrapper around "svdfact" extracting all parts the factorization to a tuple. Direct use of "svdfact" is therefore generally more efficient. The function returns the generalized SVD of "A" and "B", returning "U", "V", "Q", "D1", "D2", and "R0" such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". + .. function:: svdvals(A, B) - Return only the singular values from the generalized singular value - decomposition of "A" and "B". + Return only the singular values from the generalized singular value decomposition of "A" and "B". + .. function:: svdvals!(A) - Returns the singular values of "A", while saving space by - overwriting the input. + Returns the singular values of "A", while saving space by overwriting the input. + .. function:: svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of "A" and "B", returning a - "GeneralizedSVD" Factorization object "F", such that "A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'". + Compute the generalized SVD of "A" and "B", returning a "GeneralizedSVD" Factorization object "F", such that "A = F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = F[:V]*F[:D2]*F[:R0]*F[:Q]'". + .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around "svdfact" extracting all parts the factorization - to a tuple. Direct use of "svdfact" is therefore generally more - efficient. The function returns the generalized SVD of "A" and - "B", returning "U", "V", "Q", "D1", "D2", and "R0" - such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". + Wrapper around "svdfact" extracting all parts the factorization to a tuple. Direct use of "svdfact" is therefore generally more efficient. The function returns the generalized SVD of "A" and "B", returning "U", "V", "Q", "D1", "D2", and "R0" such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". + .. function:: svdvals(A, B) - Return only the singular values from the generalized singular value - decomposition of "A" and "B". + Return only the singular values from the generalized singular value decomposition of "A" and "B". + .. function:: triu(M, k) - Returns the upper triangle of "M" starting from the "k"th - superdiagonal. + Returns the upper triangle of "M" starting from the "k"th superdiagonal. + .. function:: triu(M, k) - Returns the upper triangle of "M" starting from the "k"th - superdiagonal. + Returns the upper triangle of "M" starting from the "k"th superdiagonal. + .. function:: triu!(M, k) - Returns the upper triangle of "M" starting from the "k"th - superdiagonal, overwriting "M" in the process. + Returns the upper triangle of "M" starting from the "k"th superdiagonal, overwriting "M" in the process. + .. function:: triu!(M, k) - Returns the upper triangle of "M" starting from the "k"th - superdiagonal, overwriting "M" in the process. + Returns the upper triangle of "M" starting from the "k"th superdiagonal, overwriting "M" in the process. + .. function:: tril(M, k) - Returns the lower triangle of "M" starting from the "k"th - subdiagonal. + Returns the lower triangle of "M" starting from the "k"th subdiagonal. + .. function:: tril(M, k) - Returns the lower triangle of "M" starting from the "k"th - subdiagonal. + Returns the lower triangle of "M" starting from the "k"th subdiagonal. + .. function:: tril!(M, k) - Returns the lower triangle of "M" starting from the "k"th - subdiagonal, overwriting "M" in the process. + Returns the lower triangle of "M" starting from the "k"th subdiagonal, overwriting "M" in the process. + .. function:: tril!(M, k) - Returns the lower triangle of "M" starting from the "k"th - subdiagonal, overwriting "M" in the process. + Returns the lower triangle of "M" starting from the "k"th subdiagonal, overwriting "M" in the process. + .. function:: diagind(M[, k]) - A "Range" giving the indices of the "k"th diagonal of the - matrix "M". + A "Range" giving the indices of the "k"th diagonal of the matrix "M". + .. function:: diag(M[, k]) - The "k"th diagonal of a matrix, as a vector. Use "diagm" to - construct a diagonal matrix. + The "k"th diagonal of a matrix, as a vector. Use "diagm" to construct a diagonal matrix. + .. function:: diagm(v[, k]) - Construct a diagonal matrix and place "v" on the "k"th - diagonal. + Construct a diagonal matrix and place "v" on the "k"th diagonal. + .. function:: scale(b, A) - Scale an array "A" by a scalar "b", returning a new array. + Scale an array "A" by a scalar "b", returning a new array. + + If "A" is a matrix and "b" is a vector, then "scale(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), returning a new array. - If "A" is a matrix and "b" is a vector, then "scale(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), returning a new - array. + Note: for large "A", "scale" can be much faster than "A .* b" or "b .* A", due to the use of BLAS. - Note: for large "A", "scale" can be much faster than "A .* b" - or "b .* A", due to the use of BLAS. .. function:: scale(b, A) - Scale an array "A" by a scalar "b", returning a new array. + Scale an array "A" by a scalar "b", returning a new array. - If "A" is a matrix and "b" is a vector, then "scale(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), returning a new - array. + If "A" is a matrix and "b" is a vector, then "scale(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), returning a new array. + + Note: for large "A", "scale" can be much faster than "A .* b" or "b .* A", due to the use of BLAS. - Note: for large "A", "scale" can be much faster than "A .* b" - or "b .* A", due to the use of BLAS. .. function:: scale!(b, A) - Scale an array "A" by a scalar "b", similar to "scale()" but - overwriting "A" in-place. + Scale an array "A" by a scalar "b", similar to "scale()" but overwriting "A" in-place. + + If "A" is a matrix and "b" is a vector, then "scale!(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- place on "A". - If "A" is a matrix and "b" is a vector, then "scale!(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- - place on "A". .. function:: scale!(b, A) - Scale an array "A" by a scalar "b", similar to "scale()" but - overwriting "A" in-place. + Scale an array "A" by a scalar "b", similar to "scale()" but overwriting "A" in-place. + + If "A" is a matrix and "b" is a vector, then "scale!(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- place on "A". - If "A" is a matrix and "b" is a vector, then "scale!(A,b)" - scales each column "i" of "A" by "b[i]" (similar to - "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of - "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- - place on "A". .. function:: Tridiagonal(dl, d, du) - Construct a tridiagonal matrix from the lower diagonal, diagonal, - and upper diagonal, respectively. The result is of type - "Tridiagonal" and provides efficient specialized linear solvers, - but may be converted into a regular matrix with "full()". + Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type "Tridiagonal" and provides efficient specialized linear solvers, but may be converted into a regular matrix with "full()". + .. function:: Bidiagonal(dv, ev, isupper) - Constructs an upper ("isupper=true") or lower ("isupper=false") - bidiagonal matrix using the given diagonal ("dv") and off- - diagonal ("ev") vectors. The result is of type "Bidiagonal" - and provides efficient specialized linear solvers, but may be - converted into a regular matrix with "full()". + Constructs an upper ("isupper=true") or lower ("isupper=false") bidiagonal matrix using the given diagonal ("dv") and off- diagonal ("ev") vectors. The result is of type "Bidiagonal" and provides efficient specialized linear solvers, but may be converted into a regular matrix with "full()". + .. function:: SymTridiagonal(d, du) - Construct a real symmetric tridiagonal matrix from the diagonal and - upper diagonal, respectively. The result is of type - "SymTridiagonal" and provides efficient specialized eigensolvers, - but may be converted into a regular matrix with "full()". + Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type "SymTridiagonal" and provides efficient specialized eigensolvers, but may be converted into a regular matrix with "full()". + .. function:: rank(M) - Compute the rank of a matrix. + Compute the rank of a matrix. + .. function:: norm(A[, p]) - Compute the "p"-norm of a vector or the operator norm of a matrix - "A", defaulting to the "p=2"-norm. + Compute the "p"-norm of a vector or the operator norm of a matrix "A", defaulting to the "p=2"-norm. + + For vectors, "p" can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, "norm(A, Inf)" returns the largest value in "abs(A)", whereas "norm(A, -Inf)" returns the smallest. - For vectors, "p" can assume any numeric value (even though not - all values produce a mathematically valid vector norm). In - particular, "norm(A, Inf)" returns the largest value in - "abs(A)", whereas "norm(A, -Inf)" returns the smallest. + For matrices, valid values of "p" are "1", "2", or "Inf". (Note that for sparse matrices, "p=2" is currently not implemented.) Use "vecnorm()" to compute the Frobenius norm. - For matrices, valid values of "p" are "1", "2", or "Inf". - (Note that for sparse matrices, "p=2" is currently not - implemented.) Use "vecnorm()" to compute the Frobenius norm. .. function:: vecnorm(A[, p]) - For any iterable container "A" (including arrays of any - dimension) of numbers (or any element type for which "norm" is - defined), compute the "p"-norm (defaulting to "p=2") as if - "A" were a vector of the corresponding length. + For any iterable container "A" (including arrays of any dimension) of numbers (or any element type for which "norm" is defined), compute the "p"-norm (defaulting to "p=2") as if "A" were a vector of the corresponding length. + + For example, if "A" is a matrix and "p=2", then this is equivalent to the Frobenius norm. - For example, if "A" is a matrix and "p=2", then this is - equivalent to the Frobenius norm. .. function:: cond(M[, p]) - Condition number of the matrix "M", computed using the operator - "p"-norm. Valid values for "p" are "1", "2" (default), or - "Inf". + Condition number of the matrix "M", computed using the operator "p"-norm. Valid values for "p" are "1", "2" (default), or "Inf". + .. function:: condskeel(M[, x, p]) - \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \right\Vert_p \\ - \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \left\vert x \right\vert - \right\Vert_p + :: + + condskeel(M[, x, p]) + + \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \right\Vert_p \\ + \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \left\vert x \right\vert + \right\Vert_p + + Skeel condition number \kappa_S of the matrix "M", optionally with respect to the vector "x", as computed using the operator "p"-norm. "p" is "Inf" by default, if not provided. Valid values for "p" are "1", "2", or "Inf". - Skeel condition number \kappa_S of the matrix "M", optionally - with respect to the vector "x", as computed using the operator - "p"-norm. "p" is "Inf" by default, if not provided. Valid - values for "p" are "1", "2", or "Inf". + This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. - This quantity is also known in the literature as the Bauer - condition number, relative condition number, or componentwise - relative condition number. .. function:: trace(M) - Matrix trace + Matrix trace + .. function:: det(M) - Matrix determinant + Matrix determinant + .. function:: logabsdet(M) - Log of absolute value of determinant of real matrix. Equivalent to - "(log(abs(det(M))), sign(det(M)))", but may provide increased - accuracy and/or speed. + Log of absolute value of determinant of real matrix. Equivalent to "(log(abs(det(M))), sign(det(M)))", but may provide increased accuracy and/or speed. + .. function:: logabsdet(M) - Log of absolute value of determinant of real matrix. Equivalent to - "(log(abs(det(M))), sign(det(M)))", but may provide increased - accuracy and/or speed. + Log of absolute value of determinant of real matrix. Equivalent to "(log(abs(det(M))), sign(det(M)))", but may provide increased accuracy and/or speed. + .. function:: inv(M) - Matrix inverse + Matrix inverse + .. function:: pinv(M[, tol]) - Computes the Moore-Penrose pseudoinverse. + Computes the Moore-Penrose pseudoinverse. + + For matrices "M" with floating point elements, it is convenient to compute the pseudoinverse by inverting only singular values above a given threshold, "tol". - For matrices "M" with floating point elements, it is convenient - to compute the pseudoinverse by inverting only singular values - above a given threshold, "tol". + The optimal choice of "tol" varies both with the value of "M" and the intended application of the pseudoinverse. The default value of "tol" is "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is essentially machine epsilon for the real part of a matrix element multiplied by the larger matrix dimension. For inverting dense ill- conditioned matrices in a least-squares sense, "tol = sqrt(eps(real(float(one(eltype(M))))))" is recommended. - The optimal choice of "tol" varies both with the value of "M" - and the intended application of the pseudoinverse. The default - value of "tol" is - "eps(real(float(one(eltype(M)))))*maximum(size(A))", which is - essentially machine epsilon for the real part of a matrix element - multiplied by the larger matrix dimension. For inverting dense ill- - conditioned matrices in a least-squares sense, "tol = - sqrt(eps(real(float(one(eltype(M))))))" is recommended. + For more information, see [8859], [B96], [S84], [KY88]. - For more information, see [8859], [B96], [S84], [KY88]. + [8859] Issue 8859, "Fix least squares", https://github.com/JuliaLang/julia/pull/8859 - [8859] Issue 8859, "Fix least squares", - https://github.com/JuliaLang/julia/pull/8859 + [B96] Åke Björck, "Numerical Methods for Least Squares Problems", SIAM Press, Philadelphia, 1996, "Other Titles in Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 - [B96] Åke Björck, "Numerical Methods for Least Squares - Problems", SIAM Press, Philadelphia, 1996, "Other Titles in - Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 + [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on Scientific and Statistical Computing, 5(2), 1984, 403-413. doi:10.1137/0905030 - [S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 + [KY88] Konstantinos Konstantinides and Kung Yao, "Statistical analysis of effective singular values in matrix rank determination", IEEE Transactions on Acoustics, Speech and Signal Processing, 36(5), 1988, 757-763. doi:10.1109/29.1585 - [KY88] Konstantinos Konstantinides and Kung Yao, - "Statistical analysis of effective singular values in - matrix rank determination", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 .. function:: nullspace(M) - Basis for nullspace of "M". + Basis for nullspace of "M". + .. function:: repmat(A, n, m) - Construct a matrix by repeating the given matrix "n" times in - dimension 1 and "m" times in dimension 2. + Construct a matrix by repeating the given matrix "n" times in dimension 1 and "m" times in dimension 2. + .. function:: repeat(A, inner = Int[], outer = Int[]) - Construct an array by repeating the entries of "A". The i-th - element of "inner" specifies the number of times that the - individual entries of the i-th dimension of "A" should be - repeated. The i-th element of "outer" specifies the number of - times that a slice along the i-th dimension of "A" should be - repeated. + Construct an array by repeating the entries of "A". The i-th element of "inner" specifies the number of times that the individual entries of the i-th dimension of "A" should be repeated. The i-th element of "outer" specifies the number of times that a slice along the i-th dimension of "A" should be repeated. + .. function:: kron(A, B) - Kronecker tensor product of two vectors or two matrices. + Kronecker tensor product of two vectors or two matrices. + .. function:: blkdiag(A...) - Concatenate matrices block-diagonally. Currently only implemented - for sparse matrices. + Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. + .. function:: linreg(x, y, w) - Weighted least-squares linear regression. + Weighted least-squares linear regression. + .. function:: linreg(x, y, w) - Weighted least-squares linear regression. + Weighted least-squares linear regression. + .. function:: expm(A) - Matrix exponential. + Matrix exponential. + .. function:: lyap(A, C) - Computes the solution "X" to the continuous Lyapunov equation - "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real - part and no two eigenvalues are negative complex conjugates of each - other. + Computes the solution "X" to the continuous Lyapunov equation "AX + XA' + C = 0", where no eigenvalue of "A" has a zero real part and no two eigenvalues are negative complex conjugates of each other. + .. function:: sylvester(A, B, C) - Computes the solution "X" to the Sylvester equation "AX + XB + C - = 0", where "A", "B" and "C" have compatible dimensions and - "A" and "-B" have no eigenvalues with equal real part. + Computes the solution "X" to the Sylvester equation "AX + XB + C = 0", where "A", "B" and "C" have compatible dimensions and "A" and "-B" have no eigenvalues with equal real part. + .. function:: issym(A) -> Bool - Test whether a matrix is symmetric. + Test whether a matrix is symmetric. + .. function:: isposdef(A) -> Bool - Test whether a matrix is positive definite. + Test whether a matrix is positive definite. + .. function:: isposdef!(A) -> Bool - Test whether a matrix is positive definite, overwriting "A" in - the processes. + Test whether a matrix is positive definite, overwriting "A" in the processes. + .. function:: istril(A) -> Bool - Test whether a matrix is lower triangular. + Test whether a matrix is lower triangular. + .. function:: istriu(A) -> Bool - Test whether a matrix is upper triangular. + Test whether a matrix is upper triangular. + .. function:: isdiag(A) -> Bool - Test whether a matrix is diagonal. + Test whether a matrix is diagonal. + .. function:: ishermitian(A) -> Bool - Test whether a matrix is Hermitian. + Test whether a matrix is Hermitian. + .. function:: transpose(A) - The transposition operator (".'"). + The transposition operator (".'"). + .. function:: transpose!(dest, src) - Transpose array "src" and store the result in the preallocated - array "dest", which should have a size corresponding to - "(size(src,2),size(src,1))". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. + Transpose array "src" and store the result in the preallocated array "dest", which should have a size corresponding to "(size(src,2),size(src,1))". No in-place transposition is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + .. function:: ctranspose(A) - The conjugate transposition operator ("'"). + The conjugate transposition operator ("'"). + .. function:: ctranspose!(dest, src) - Conjugate transpose array "src" and store the result in the - preallocated array "dest", which should have a size corresponding - to "(size(src,2),size(src,1))". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. + Conjugate transpose array "src" and store the result in the preallocated array "dest", which should have a size corresponding to "(size(src,2),size(src,1))". No in-place transposition is supported and unexpected results will happen if *src* and *dest* have overlapping memory regions. + .. function:: eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - Computes eigenvalues "d" of "A" using Lanczos or Arnoldi - iterations for real symmetric or general nonsymmetric matrices - respectively. If "B" is provided, the generalized eigenproblem is - solved. - - The following keyword arguments are supported: - * "nev": Number of eigenvalues - - * "ncv": Number of Krylov vectors used in the computation; - should satisfy - - "nev+1 <= ncv <= n" for real symmetric problems and - "nev+2 <= ncv <= n" for other problems, where "n" is - the size of the input matrix "A". The default is "ncv = - max(20,2*nev+1)". Note that these restrictions limit the - input matrix "A" to be of dimension at least 2. - - * "which": type of eigenvalues to compute. See the note - below. - - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | "which" | type of eigenvalues | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":LM" | eigenvalues of largest magnitude (default) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":SM" | eigenvalues of smallest magnitude | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":LR" | eigenvalues of largest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":SR" | eigenvalues of smallest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":LI" | eigenvalues of largest imaginary part (nonsymmetric or complex "A" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":SI" | eigenvalues of smallest imaginary part (nonsymmetric or complex "A" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | ":BE" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric "A" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - - * "tol": tolerance (tol \le 0.0 defaults to - "DLAMCH('EPS')") - - * "maxiter": Maximum number of iterations (default = 300) - - * "sigma": Specifies the level shift used in inverse - iteration. If "nothing" (default), defaults to ordinary - (forward) iterations. Otherwise, find eigenvalues close to - "sigma" using shift and invert iterations. - - * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) - if "true" - - * "v0": starting vector from which to start the iterations - - "eigs" returns the "nev" requested eigenvalues in "d", the - corresponding Ritz vectors "v" (only if "ritzvec=true"), the - number of converged eigenvalues "nconv", the number of iterations - "niter" and the number of matrix vector multiplications - "nmult", as well as the final residual vector "resid". - - Note: The "sigma" and "which" keywords interact: the - description of eigenvalues searched for by "which" do _not_ - necessarily refer to the eigenvalues of "A", but rather the - linear operator constructed by the specification of the iteration - mode implied by "sigma". - - +-----------------+------------------------------------+------------------------------------+ - | "sigma" | iteration mode | "which" refers to eigenvalues of | - +-----------------+------------------------------------+------------------------------------+ - | "nothing" | ordinary (forward) | A | - +-----------------+------------------------------------+------------------------------------+ - | real or complex | inverse with level shift "sigma" | (A - \\sigma I )^{-1} | - +-----------------+------------------------------------+------------------------------------+ + Computes eigenvalues "d" of "A" using Lanczos or Arnoldi iterations for real symmetric or general nonsymmetric matrices respectively. If "B" is provided, the generalized eigenproblem is solved. + + The following keyword arguments are supported: * "nev": Number of eigenvalues + + :: + + * "ncv": Number of Krylov vectors used in the computation; + should satisfy + + "nev+1 <= ncv <= n" for real symmetric problems and + "nev+2 <= ncv <= n" for other problems, where "n" is + the size of the input matrix "A". The default is "ncv = + max(20,2*nev+1)". Note that these restrictions limit the + input matrix "A" to be of dimension at least 2. + + * "which": type of eigenvalues to compute. See the note + below. + + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | "which" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":LM" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":SM" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":LR" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":SR" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":LI" | eigenvalues of largest imaginary part (nonsymmetric or complex "A" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":SI" | eigenvalues of smallest imaginary part (nonsymmetric or complex "A" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | ":BE" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric "A" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + + * "tol": tolerance (tol \le 0.0 defaults to + "DLAMCH('EPS')") + + * "maxiter": Maximum number of iterations (default = 300) + + * "sigma": Specifies the level shift used in inverse + iteration. If "nothing" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + "sigma" using shift and invert iterations. + + * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) + if "true" + + * "v0": starting vector from which to start the iterations + + "eigs" returns the "nev" requested eigenvalues in "d", the corresponding Ritz vectors "v" (only if "ritzvec=true"), the number of converged eigenvalues "nconv", the number of iterations "niter" and the number of matrix vector multiplications "nmult", as well as the final residual vector "resid". + + Note: The "sigma" and "which" keywords interact: the description of eigenvalues searched for by "which" do _not_ necessarily refer to the eigenvalues of "A", but rather the linear operator constructed by the specification of the iteration mode implied by "sigma". + + +––––––––-+––––––––––––––––––+––––––––––––––––––+ | "sigma" | iteration mode | "which" refers to eigenvalues of | +––––––––-+––––––––––––––––––+––––––––––––––––––+ | "nothing" | ordinary (forward) | A | +––––––––-+––––––––––––––––––+––––––––––––––––––+ | real or complex | inverse with level shift "sigma" | (A - \sigma I )^{-1} | +––––––––-+––––––––––––––––––+––––––––––––––––––+ + .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - "svds" computes largest singular values "s" of "A" using - Lanczos or Arnoldi iterations. Uses "eigs()" underneath. + "svds" computes largest singular values "s" of "A" using Lanczos or Arnoldi iterations. Uses "eigs()" underneath. + + Inputs are: * "A": Linear operator. It can either subtype of "AbstractArray" (e.g., sparse matrix) or duck typed. For duck typing "A" has to support "size(A)", "eltype(A)", "A * vector" and "A' * vector". + + :: + + * "nsv": Number of singular values. - Inputs are: - * "A": Linear operator. It can either subtype of - "AbstractArray" (e.g., sparse matrix) or duck typed. For - duck typing "A" has to support "size(A)", "eltype(A)", - "A * vector" and "A' * vector". + * "ritzvec": Whether to return the left and right singular + vectors "left_sv" and "right_sv", default is "true". If + "false" the singular vectors are omitted from the output. - * "nsv": Number of singular values. + * "tol": tolerance, see "eigs()". - * "ritzvec": Whether to return the left and right singular - vectors "left_sv" and "right_sv", default is "true". If - "false" the singular vectors are omitted from the output. + * "maxiter": Maximum number of iterations, see "eigs()". - * "tol": tolerance, see "eigs()". + **Example**: - * "maxiter": Maximum number of iterations, see "eigs()". + :: - **Example**: + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) .. function:: peakflops(n; parallel=false) - "peakflops" computes the peak flop rate of the computer by using - double precision "Base.LinAlg.BLAS.gemm!()". By default, if no - arguments are specified, it multiplies a matrix of size "n x n", - where "n = 2000". If the underlying BLAS is using multiple - threads, higher flop rates are realized. The number of BLAS threads - can be set with "blas_set_num_threads(n)". + "peakflops" computes the peak flop rate of the computer by using double precision "Base.LinAlg.BLAS.gemm!()". By default, if no arguments are specified, it multiplies a matrix of size "n x n", where "n = 2000". If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with "blas_set_num_threads(n)". + + If the keyword argument "parallel" is set to "true", "peakflops" is run in parallel on all the worker processors. The flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument "n" still refers to the size of the problem that is solved on each processor. - If the keyword argument "parallel" is set to "true", - "peakflops" is run in parallel on all the worker processors. The - flop rate of the entire parallel computer is returned. When running - in parallel, only 1 BLAS thread is used. The argument "n" still - refers to the size of the problem that is solved on each processor. BLAS Functions -------------- @@ -1024,259 +793,220 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: dot(n, X, incx, Y, incy) - Dot product of two vectors consisting of "n" elements of array - "X" with stride "incx" and "n" elements of array "Y" with - stride "incy". + Dot product of two vectors consisting of "n" elements of array "X" with stride "incx" and "n" elements of array "Y" with stride "incy". + .. function:: dotu(n, X, incx, Y, incy) - Dot function for two complex vectors. + Dot function for two complex vectors. + .. function:: dotc(n, X, incx, U, incy) - Dot function for two complex vectors conjugating the first vector. + Dot function for two complex vectors conjugating the first vector. + .. function:: blascopy!(n, X, incx, Y, incy) - Copy "n" elements of array "X" with stride "incx" to array - "Y" with stride "incy". Returns "Y". + Copy "n" elements of array "X" with stride "incx" to array "Y" with stride "incy". Returns "Y". + .. function:: nrm2(n, X, incx) - 2-norm of a vector consisting of "n" elements of array "X" with - stride "incx". + 2-norm of a vector consisting of "n" elements of array "X" with stride "incx". + .. function:: asum(n, X, incx) - sum of the absolute values of the first "n" elements of array - "X" with stride "incx". + sum of the absolute values of the first "n" elements of array "X" with stride "incx". + .. function:: axpy!(a, X, Y) - Overwrite "Y" with "a*X + Y". Returns "Y". + Overwrite "Y" with "a*X + Y". Returns "Y". + .. function:: scal!(n, a, X, incx) - Overwrite "X" with "a*X". Returns "X". + Overwrite "X" with "a*X". Returns "X". + .. function:: scal(n, a, X, incx) - Returns "a*X". + Returns "a*X". + .. function:: ger!(alpha, x, y, A) - Rank-1 update of the matrix "A" with vectors "x" and "y" as - "alpha*x*y' + A". + Rank-1 update of the matrix "A" with vectors "x" and "y" as "alpha*x*y' + A". + .. function:: syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix "A" with vector "x" as - "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of - "A" is updated ('L' for lower triangle). Returns "A". + Rank-1 update of the symmetric matrix "A" with vector "x" as "alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of "A" is updated ('L' for lower triangle). Returns "A". + .. function:: syrk!(uplo, trans, alpha, A, beta, C) - Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + - beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" - is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is - updated ('L' for lower triangle). Returns "C". + Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is updated ('L' for lower triangle). Returns "C". + .. function:: syrk(uplo, trans, alpha, A) - Returns either the upper triangle or the lower triangle, according - to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", - according to "trans" ('N' or 'T'). + Returns either the upper triangle or the lower triangle, according to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", according to "trans" ('N' or 'T'). + .. function:: her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian - matrix "A" with vector "x" as "alpha*x*x' + A". When - "uplo" is 'U' the upper triangle of "A" is updated ('L' for - lower triangle). Returns "A". + Methods for complex arrays only. Rank-1 update of the Hermitian matrix "A" with vector "x" as "alpha*x*x' + A". When "uplo" is 'U' the upper triangle of "A" is updated ('L' for lower triangle). Returns "A". + .. function:: herk!(uplo, trans, alpha, A, beta, C) - Methods for complex arrays only. Rank-k update of the Hermitian - matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" - according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' - the upper triangle of "C" is updated ('L' for lower triangle). - Returns "C". + Methods for complex arrays only. Rank-k update of the Hermitian matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is updated ('L' for lower triangle). Returns "C". + .. function:: herk(uplo, trans, alpha, A) - Methods for complex arrays only. Returns either the upper triangle - or the lower triangle, according to "uplo" ('U' or 'L'), of - "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or - 'T'). + Methods for complex arrays only. Returns either the upper triangle or the lower triangle, according to "uplo" ('U' or 'L'), of "alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or 'T'). + .. function:: gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) - Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + - beta*y" according to "trans" ('N' or 'T'). The matrix "A" is - a general band matrix of dimension "m" by "size(A,2)" with - "kl" sub-diagonals and "ku" super-diagonals. Returns the - updated "y". + Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + beta*y" according to "trans" ('N' or 'T'). The matrix "A" is a general band matrix of dimension "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super-diagonals. Returns the updated "y". + .. function:: gbmv(trans, m, kl, ku, alpha, A, x, beta, y) - Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' - or 'T'). The matrix "A" is a general band matrix of dimension - "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- - diagonals. + Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' or 'T'). The matrix "A" is a general band matrix of dimension "m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- diagonals. + .. function:: sbmv!(uplo, k, alpha, A, x, beta, y) - Update vector "y" as "alpha*A*x + beta*y" where "A" is a a - symmetric band matrix of order "size(A,2)" with "k" super- - diagonals stored in the argument "A". The storage layout for - "A" is described the reference BLAS module, level-2 BLAS at - http://www.netlib.org/lapack/explore-html/. + Update vector "y" as "alpha*A*x + beta*y" where "A" is a a symmetric band matrix of order "size(A,2)" with "k" super- diagonals stored in the argument "A". The storage layout for "A" is described the reference BLAS module, level-2 BLAS at http://www.netlib.org/lapack/explore-html/. + + Returns the updated "y". - Returns the updated "y". .. function:: sbmv(uplo, k, A, x) - Returns "A*x" where "A" is a symmetric band matrix of order - "size(A,2)" with "k" super-diagonals stored in the argument - "A". + Returns "A*x" where "A" is a symmetric band matrix of order "size(A,2)" with "k" super-diagonals stored in the argument "A". + .. function:: sbmv(uplo, k, A, x) - Returns "A*x" where "A" is a symmetric band matrix of order - "size(A,2)" with "k" super-diagonals stored in the argument - "A". + Returns "A*x" where "A" is a symmetric band matrix of order "size(A,2)" with "k" super-diagonals stored in the argument "A". + .. function:: gemm!(tA, tB, alpha, A, B, beta, C) - Update "C" as "alpha*A*B + beta*C" or the other three variants - according to "tA" (transpose "A") and "tB". Returns the - updated "C". + Update "C" as "alpha*A*B + beta*C" or the other three variants according to "tA" (transpose "A") and "tB". Returns the updated "C". + .. function:: gemm(tA, tB, A, B) - Returns "A*B" or the other three variants according to "tA" - (transpose "A") and "tB". + Returns "A*B" or the other three variants according to "tA" (transpose "A") and "tB". + .. function:: gemm(tA, tB, A, B) - Returns "A*B" or the other three variants according to "tA" - (transpose "A") and "tB". + Returns "A*B" or the other three variants according to "tA" (transpose "A") and "tB". + .. function:: gemv!(tA, alpha, A, x, beta, y) - Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + - beta*y" according to "tA" (transpose "A"). Returns the updated - "y". + Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + beta*y" according to "tA" (transpose "A"). Returns the updated "y". + .. function:: gemv(tA, A, x) - Returns "A*x" or "A'x" according to "tA" (transpose "A"). + Returns "A*x" or "A'x" according to "tA" (transpose "A"). + .. function:: gemv(tA, A, x) - Returns "A*x" or "A'x" according to "tA" (transpose "A"). + Returns "A*x" or "A'x" according to "tA" (transpose "A"). + .. function:: symm!(side, ul, alpha, A, B, beta, C) - Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" - according to "side". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. Returns the updated "C". + Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. Returns the updated "C". + .. function:: symm(tA, tB, alpha, A, B) - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". + Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". + .. function:: symm(tA, tB, alpha, A, B) - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". + Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". + .. function:: symm(tA, tB, alpha, A, B) - Returns "alpha*A*B" or the other three variants according to - "tA" (transpose "A") and "tB". + Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". + .. function:: symv!(ul, alpha, A, x, beta, y) - Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed - to be symmetric. Only the "ul" triangle of "A" is used. - Returns the updated "y". + Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. Returns the updated "y". + .. function:: symv(ul, A, x) - Returns "A*x". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. + Returns "A*x". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + .. function:: symv(ul, A, x) - Returns "A*x". "A" is assumed to be symmetric. Only the - "ul" triangle of "A" is used. + Returns "A*x". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + .. function:: trmm!(side, ul, tA, dA, alpha, A, B) - Update "B" as "alpha*A*B" or one of the other three variants - determined by "side" (A on left or right) and "tA" (transpose - A). Only the "ul" triangle of "A" is used. "dA" indicates if - "A" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated "B". + Update "B" as "alpha*A*B" or one of the other three variants determined by "side" (A on left or right) and "tA" (transpose A). Only the "ul" triangle of "A" is used. "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). Returns the updated "B". + .. function:: trmm(side, ul, tA, dA, alpha, A, B) - Returns "alpha*A*B" or one of the other three variants determined - by "side" (A on left or right) and "tA" (transpose A). Only the - "ul" triangle of "A" is used. "dA" indicates if "A" is - unit-triangular (the diagonal is assumed to be all ones). + Returns "alpha*A*B" or one of the other three variants determined by "side" (A on left or right) and "tA" (transpose A). Only the "ul" triangle of "A" is used. "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). + .. function:: trsm!(side, ul, tA, dA, alpha, A, B) - Overwrite "B" with the solution to "A*X = alpha*B" or one of - the other three variants determined by "side" (A on left or right - of "X") and "tA" (transpose A). Only the "ul" triangle of - "A" is used. "dA" indicates if "A" is unit-triangular (the - diagonal is assumed to be all ones). Returns the updated "B". + Overwrite "B" with the solution to "A*X = alpha*B" or one of the other three variants determined by "side" (A on left or right of "X") and "tA" (transpose A). Only the "ul" triangle of "A" is used. "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). Returns the updated "B". + .. function:: trsm(side, ul, tA, dA, alpha, A, B) - Returns the solution to "A*X = alpha*B" or one of the other three - variants determined by "side" (A on left or right of "X") and - "tA" (transpose A). Only the "ul" triangle of "A" is used. - "dA" indicates if "A" is unit-triangular (the diagonal is - assumed to be all ones). + Returns the solution to "A*X = alpha*B" or one of the other three variants determined by "side" (A on left or right of "X") and "tA" (transpose A). Only the "ul" triangle of "A" is used. "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). + .. function:: trmv!(side, ul, tA, dA, alpha, A, b) - Update "b" as "alpha*A*b" or one of the other three variants - determined by "side" (A on left or right) and "tA" (transpose - A). Only the "ul" triangle of "A" is used. "dA" indicates if - "A" is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated "b". + Update "b" as "alpha*A*b" or one of the other three variants determined by "side" (A on left or right) and "tA" (transpose A). Only the "ul" triangle of "A" is used. "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). Returns the updated "b". + .. function:: trmv(side, ul, tA, dA, alpha, A, b) - Returns "alpha*A*b" or one of the other three variants determined - by "side" (A on left or right) and "tA" (transpose A). Only the - "ul" triangle of "A" is used. "dA" indicates if "A" is - unit-triangular (the diagonal is assumed to be all ones). + Returns "alpha*A*b" or one of the other three variants determined by "side" (A on left or right) and "tA" (transpose A). Only the "ul" triangle of "A" is used. "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). + .. function:: trsv!(ul, tA, dA, A, b) - Overwrite "b" with the solution to "A*x = b" or one of the - other two variants determined by "tA" (transpose A) and "ul" - (triangle of "A" used). "dA" indicates if "A" is unit- - triangular (the diagonal is assumed to be all ones). Returns the - updated "b". + Overwrite "b" with the solution to "A*x = b" or one of the other two variants determined by "tA" (transpose A) and "ul" (triangle of "A" used). "dA" indicates if "A" is unit- triangular (the diagonal is assumed to be all ones). Returns the updated "b". + .. function:: trsv(ul, tA, dA, A, b) - Returns the solution to "A*x = b" or one of the other two - variants determined by "tA" (transpose A) and "ul" (triangle of - "A" is used.) "dA" indicates if "A" is unit-triangular (the - diagonal is assumed to be all ones). + Returns the solution to "A*x = b" or one of the other two variants determined by "tA" (transpose A) and "ul" (triangle of "A" is used.) "dA" indicates if "A" is unit-triangular (the diagonal is assumed to be all ones). + .. function:: blas_set_num_threads(n) - Set the number of threads the BLAS library should use. + Set the number of threads the BLAS library should use. + .. data:: I diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index d6ac9da293a68..5d6612092a850 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -11,34 +11,37 @@ Mathematical Operators .. function:: -(x, y) - Subtraction operator. + Subtraction operator. + .. _+: .. function:: +(x, y...) - Addition operator. "x+y+z+..." calls this function with all - arguments, i.e. "+(x, y, z, ...)". + Addition operator. "x+y+z+..." calls this function with all arguments, i.e. "+(x, y, z, ...)". + .. _-: .. function:: -(x, y) - Subtraction operator. + Subtraction operator. + .. _*: .. function:: *(s, t) - Concatenate strings. The "*" operator is an alias to this - function. + Concatenate strings. The "*" operator is an alias to this function. + + :: + + julia> "Hello " * "world" + "Hello world" - julia> "Hello " * "world" - "Hello world" .. _/: .. function:: /(x, y) - Right division operator: multiplication of "x" by the inverse of - "y" on the right. Gives floating-point results for integer - arguments. + Right division operator: multiplication of "x" by the inverse of "y" on the right. Gives floating-point results for integer arguments. + .. _\\: .. function:: \\(x, y) @@ -49,31 +52,37 @@ Mathematical Operators .. _^: .. function:: ^(s, n) - Repeat "n" times the string "s". The "^" operator is an alias - to this function. + Repeat "n" times the string "s". The "^" operator is an alias to this function. + + :: + + julia> "Test "^3 + "Test Test Test " - julia> "Test "^3 - "Test Test Test " .. _.+: .. function:: .+(x, y) - Element-wise addition operator. + Element-wise addition operator. + .. _.-: .. function:: .-(x, y) - Element-wise subtraction operator. + Element-wise subtraction operator. + .. _.*: .. function:: .*(x, y) - Element-wise multiplication operator. + Element-wise multiplication operator. + .. _./: .. function:: ./(x, y) - Element-wise right division operator. + Element-wise right division operator. + .. _.\\: .. function:: .\\(x, y) @@ -83,109 +92,113 @@ Mathematical Operators .. _.^: .. function:: .^(x, y) - Element-wise exponentiation operator. + Element-wise exponentiation operator. + .. function:: fma(x, y, z) - Computes "x*y+z" without rounding the intermediate result - "x*y". On some systems this is significantly more expensive than - "x*y+z". "fma" is used to improve accuracy in certain - algorithms. See "muladd". + Computes "x*y+z" without rounding the intermediate result "x*y". On some systems this is significantly more expensive than "x*y+z". "fma" is used to improve accuracy in certain algorithms. See "muladd". + .. function:: muladd(x, y, z) - Combined multiply-add, computes "x*y+z" in an efficient manner. - This may on some systems be equivalent to "x*y+z", or to - "fma(x,y,z)". "muladd" is used to improve performance. See - "fma". + Combined multiply-add, computes "x*y+z" in an efficient manner. This may on some systems be equivalent to "x*y+z", or to "fma(x,y,z)". "muladd" is used to improve performance. See "fma". + .. function:: div(x, y) + ÷(x, y) + + The quotient from Euclidean division. Computes "x/y", truncated to an integer. - The quotient from Euclidean division. Computes "x/y", truncated - to an integer. .. function:: fld(x, y) - Largest integer less than or equal to "x/y". + Largest integer less than or equal to "x/y". + .. function:: cld(x, y) - Smallest integer larger than or equal to "x/y". + Smallest integer larger than or equal to "x/y". + .. function:: mod(x, y) - Modulus after division, returning in the range [0,``y``), if "y" - is positive, or ("y",0] if "y" is negative. + Modulus after division, returning in the range [0,``y``), if "y" is positive, or ("y",0] if "y" is negative. + .. function:: mod2pi(x) - Modulus after division by 2pi, returning in the range [0,2pi). + Modulus after division by 2pi, returning in the range [0,2pi). + + This function computes a floating point representation of the modulus after division by numerically exact 2pi, and is therefore not exactly the same as mod(x,2pi), which would compute the modulus of x relative to division by the floating-point number 2pi. - This function computes a floating point representation of the - modulus after division by numerically exact 2pi, and is therefore - not exactly the same as mod(x,2pi), which would compute the modulus - of x relative to division by the floating-point number 2pi. .. function:: rem(x, y) + %(x, y) + + Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than "y". This value is always exact. - Remainder from Euclidean division, returning a value of the same - sign as``x``, and smaller in magnitude than "y". This value is - always exact. .. function:: divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to - "(x÷y, x%y)". + The quotient and remainder from Euclidean division. Equivalent to "(x÷y, x%y)". + .. function:: fldmod(x, y) - The floored quotient and modulus after division. Equivalent to - "(fld(x,y), mod(x,y))". + The floored quotient and modulus after division. Equivalent to "(fld(x,y), mod(x,y))". + .. function:: mod1(x, m) - Modulus after division, returning in the range (0,m] + Modulus after division, returning in the range (0,m] + .. function:: rem1(x, m) - Remainder after division, returning in the range (0,m] + Remainder after division, returning in the range (0,m] + .. _//: .. function:: //(num, den) - Divide two integers or rational numbers, giving a "Rational" - result. + Divide two integers or rational numbers, giving a "Rational" result. + .. function:: rationalize([Type=Int], x; tol=eps(x)) - Approximate floating point number "x" as a Rational number with - components of the given integer type. The result will differ from - "x" by no more than "tol". + Approximate floating point number "x" as a Rational number with components of the given integer type. The result will differ from "x" by no more than "tol". + .. function:: num(x) - Numerator of the rational representation of "x" + Numerator of the rational representation of "x" + .. function:: den(x) - Denominator of the rational representation of "x" + Denominator of the rational representation of "x" + .. _<<: .. function:: <<(x, n) - Left bit shift operator. + Left bit shift operator. + .. _>>: .. function:: >>(x, n) - Right bit shift operator, preserving the sign of "x". + Right bit shift operator, preserving the sign of "x". + .. _>>>: .. function:: >>>(x, n) - Unsigned right bit shift operator. + Unsigned right bit shift operator. + .. _\:: .. function:: \:(start, [step], stop) @@ -197,134 +210,142 @@ Mathematical Operators .. function:: colon(start[, step], stop) - Called by ":" syntax for constructing ranges. + Called by ":" syntax for constructing ranges. + .. function:: range(start[, step], length) - Construct a range by length, given a starting value and optional - step (defaults to 1). + Construct a range by length, given a starting value and optional step (defaults to 1). + .. _==: .. function:: ==(x, y) - Generic equality operator, giving a single "Bool" result. Falls - back to "===". Should be implemented for all types with a notion - of equality, based on the abstract value that an instance - represents. For example, all numeric types are compared by numeric - value, ignoring type. Strings are compared as sequences of - characters, ignoring encoding. + Generic equality operator, giving a single "Bool" result. Falls back to "===". Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. + + Follows IEEE semantics for floating-point numbers. - Follows IEEE semantics for floating-point numbers. + Collections should generally implement "==" by calling "==" recursively on all contents. - Collections should generally implement "==" by calling "==" - recursively on all contents. + New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible. - New numeric types should implement this function for two arguments - of the new type, and handle comparison to other types via promotion - rules where possible. .. _!=: .. function:: !=(x, y) + ≠(x, y) + + Not-equals comparison operator. Always gives the opposite answer as "==". New types should generally not implement this, and rely on the fallback definition "!=(x,y) = !(x==y)" instead. - Not-equals comparison operator. Always gives the opposite answer as - "==". New types should generally not implement this, and rely on - the fallback definition "!=(x,y) = !(x==y)" instead. .. _===: .. function:: ===(x, y) + ≡(x, y) + + See the "is()" operator - See the "is()" operator .. _!==: .. function:: !==(x, y) + ≢(x, y) + + Equivalent to "!is(x, y)" - Equivalent to "!is(x, y)" .. _<: .. function:: <(x, y) - Less-than comparison operator. New numeric types should implement - this function for two arguments of the new type. Because of the - behavior of floating-point NaN values, "<" implements a partial - order. Types with a canonical partial order should implement "<", - and types with a canonical total order should implement "isless". + Less-than comparison operator. New numeric types should implement this function for two arguments of the new type. Because of the behavior of floating-point NaN values, "<" implements a partial order. Types with a canonical partial order should implement "<", and types with a canonical total order should implement "isless". + .. _<=: .. function:: <=(x, y) + ≤(x, y) + + Less-than-or-equals comparison operator. - Less-than-or-equals comparison operator. .. _>: .. function:: >(x, y) - Greater-than comparison operator. Generally, new types should - implement "<" instead of this function, and rely on the fallback - definition ">(x,y) = y(x,y) = y=: .. function:: >=(x, y) + ≥(x, y) + + Greater-than-or-equals comparison operator. - Greater-than-or-equals comparison operator. .. _.==: .. function:: .==(x, y) - Element-wise equality comparison operator. + Element-wise equality comparison operator. + .. _.!=: .. function:: .!=(x, y) + .≠(x, y) + + Element-wise not-equals comparison operator. - Element-wise not-equals comparison operator. .. _.<: .. function:: .<(x, y) - Element-wise less-than comparison operator. + Element-wise less-than comparison operator. + .. _.<=: .. function:: .<=(x, y) + .≤(x, y) + + Element-wise less-than-or-equals comparison operator. - Element-wise less-than-or-equals comparison operator. .. _.>: .. function:: .>(x, y) - Element-wise greater-than comparison operator. + Element-wise greater-than comparison operator. + .. _.>=: .. function:: .>=(x, y) + .≥(x, y) + + Element-wise greater-than-or-equals comparison operator. - Element-wise greater-than-or-equals comparison operator. .. function:: cmp(x, y) - Return -1, 0, or 1 depending on whether "x" is less than, equal - to, or greater than "y", respectively. Uses the total order - implemented by "isless". For floating-point numbers, uses "<" - but throws an error for unordered arguments. + Return -1, 0, or 1 depending on whether "x" is less than, equal to, or greater than "y", respectively. Uses the total order implemented by "isless". For floating-point numbers, uses "<" but throws an error for unordered arguments. + .. _~: .. function:: ~(x) - Bitwise not + Bitwise not + .. _&: .. function:: &(x, y) - Bitwise and + Bitwise and + .. _|: .. function:: |(x, y) - Bitwise or + Bitwise or + .. _$: .. function:: \$(x, y) @@ -335,7 +356,8 @@ Mathematical Operators .. _!: .. function:: !(x) - Boolean not + Boolean not + .. _&&: .. function:: x && y @@ -349,361 +371,410 @@ Mathematical Operators .. function:: A_ldiv_Bc(a, b) - Matrix operator A \ B^H + Matrix operator A \ B^H + .. function:: A_ldiv_Bt(a, b) - Matrix operator A \ B^T + Matrix operator A \ B^T + .. function:: A_mul_B!(Y, A, B) -> Y - Calculates the matrix-matrix or matrix-vector product *A B* and - stores the result in *Y*, overwriting the existing value of *Y*. + Calculates the matrix-matrix or matrix-vector product *A B* and stores the result in *Y*, overwriting the existing value of *Y*. + + :: + + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 .. function:: A_mul_Bc(...) - Matrix operator A B^H + Matrix operator A B^H + .. function:: A_mul_Bt(...) - Matrix operator A B^T + Matrix operator A B^T + .. function:: A_rdiv_Bc(...) - Matrix operator A / B^H + Matrix operator A / B^H + .. function:: A_rdiv_Bt(a, b) - Matrix operator A / B^T + Matrix operator A / B^T + .. function:: Ac_ldiv_B(...) - Matrix operator A^H \ B + Matrix operator A^H \ B + .. function:: Ac_ldiv_Bc(...) - Matrix operator A^H \ B^H + Matrix operator A^H \ B^H + .. function:: Ac_mul_B(...) - Matrix operator A^H B + Matrix operator A^H B + .. function:: Ac_mul_Bc(...) - Matrix operator A^H B^H + Matrix operator A^H B^H + .. function:: Ac_rdiv_B(a, b) - Matrix operator A^H / B + Matrix operator A^H / B + .. function:: Ac_rdiv_Bc(a, b) - Matrix operator A^H / B^H + Matrix operator A^H / B^H + .. function:: At_ldiv_B(...) - Matrix operator A^T \ B + Matrix operator A^T \ B + .. function:: At_ldiv_Bt(...) - Matrix operator A^T \ B^T + Matrix operator A^T \ B^T + .. function:: At_mul_B(...) - Matrix operator A^T B + Matrix operator A^T B + .. function:: At_mul_Bt(...) - Matrix operator A^T B^T + Matrix operator A^T B^T + .. function:: At_rdiv_B(a, b) - Matrix operator A^T / B + Matrix operator A^T / B + .. function:: At_rdiv_Bt(a, b) - Matrix operator A^T / B^T + Matrix operator A^T / B^T + Mathematical Functions ---------------------- .. function:: isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - Inexact equality comparison - behaves slightly different depending - on types of input args: + Inexact equality comparison - behaves slightly different depending on types of input args: + + * For "FloatingPoint" numbers, "isapprox" returns "true" if "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". - * For "FloatingPoint" numbers, "isapprox" returns "true" if - "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". + * For "Integer" and "Rational" numbers, "isapprox" returns "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. If one of "x" and "y" is "FloatingPoint", the other is promoted, and the method above is called instead. - * For "Integer" and "Rational" numbers, "isapprox" returns - "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. - If one of "x" and "y" is "FloatingPoint", the other is - promoted, and the method above is called instead. + * For "Complex" numbers, the distance in the complex plane is compared, using the same criterion as above. - * For "Complex" numbers, the distance in the complex plane is - compared, using the same criterion as above. + For default tolerance arguments, "maxeps = max(eps(abs(x)), eps(abs(y)))". - For default tolerance arguments, "maxeps = max(eps(abs(x)), - eps(abs(y)))". .. function:: sin(x) - Compute sine of "x", where "x" is in radians + Compute sine of "x", where "x" is in radians + .. function:: cos(x) - Compute cosine of "x", where "x" is in radians + Compute cosine of "x", where "x" is in radians + .. function:: tan(x) - Compute tangent of "x", where "x" is in radians + Compute tangent of "x", where "x" is in radians + .. function:: sind(x) - Compute sine of "x", where "x" is in degrees + Compute sine of "x", where "x" is in degrees + .. function:: cosd(x) - Compute cosine of "x", where "x" is in degrees + Compute cosine of "x", where "x" is in degrees + .. function:: tand(x) - Compute tangent of "x", where "x" is in degrees + Compute tangent of "x", where "x" is in degrees + .. function:: sinpi(x) - Compute \sin(\pi x) more accurately than "sin(pi*x)", - especially for large "x". + Compute \sin(\pi x) more accurately than "sin(pi*x)", especially for large "x". + .. function:: cospi(x) - Compute \cos(\pi x) more accurately than "cos(pi*x)", - especially for large "x". + Compute \cos(\pi x) more accurately than "cos(pi*x)", especially for large "x". + .. function:: sinh(x) - Compute hyperbolic sine of "x" + Compute hyperbolic sine of "x" + .. function:: cosh(x) - Compute hyperbolic cosine of "x" + Compute hyperbolic cosine of "x" + .. function:: tanh(x) - Compute hyperbolic tangent of "x" + Compute hyperbolic tangent of "x" + .. function:: asin(x) - Compute the inverse sine of "x", where the output is in radians + Compute the inverse sine of "x", where the output is in radians + .. function:: acos(x) - Compute the inverse cosine of "x", where the output is in radians + Compute the inverse cosine of "x", where the output is in radians + .. function:: atan(x) - Compute the inverse tangent of "x", where the output is in - radians + Compute the inverse tangent of "x", where the output is in radians + .. function:: atan2(y, x) - Compute the inverse tangent of "y/x", using the signs of both - "x" and "y" to determine the quadrant of the return value. + Compute the inverse tangent of "y/x", using the signs of both "x" and "y" to determine the quadrant of the return value. + .. function:: asind(x) - Compute the inverse sine of "x", where the output is in degrees + Compute the inverse sine of "x", where the output is in degrees + .. function:: acosd(x) - Compute the inverse cosine of "x", where the output is in degrees + Compute the inverse cosine of "x", where the output is in degrees + .. function:: atand(x) - Compute the inverse tangent of "x", where the output is in - degrees + Compute the inverse tangent of "x", where the output is in degrees + .. function:: sec(x) - Compute the secant of "x", where "x" is in radians + Compute the secant of "x", where "x" is in radians + .. function:: csc(x) - Compute the cosecant of "x", where "x" is in radians + Compute the cosecant of "x", where "x" is in radians + .. function:: cot(x) - Compute the cotangent of "x", where "x" is in radians + Compute the cotangent of "x", where "x" is in radians + .. function:: secd(x) - Compute the secant of "x", where "x" is in degrees + Compute the secant of "x", where "x" is in degrees + .. function:: cscd(x) - Compute the cosecant of "x", where "x" is in degrees + Compute the cosecant of "x", where "x" is in degrees + .. function:: cotd(x) - Compute the cotangent of "x", where "x" is in degrees + Compute the cotangent of "x", where "x" is in degrees + .. function:: asec(x) - Compute the inverse secant of "x", where the output is in radians + Compute the inverse secant of "x", where the output is in radians + .. function:: acsc(x) - Compute the inverse cosecant of "x", where the output is in - radians + Compute the inverse cosecant of "x", where the output is in radians + .. function:: acot(x) - Compute the inverse cotangent of "x", where the output is in - radians + Compute the inverse cotangent of "x", where the output is in radians + .. function:: asecd(x) - Compute the inverse secant of "x", where the output is in degrees + Compute the inverse secant of "x", where the output is in degrees + .. function:: acscd(x) - Compute the inverse cosecant of "x", where the output is in - degrees + Compute the inverse cosecant of "x", where the output is in degrees + .. function:: acotd(x) - Compute the inverse cotangent of "x", where the output is in - degrees + Compute the inverse cotangent of "x", where the output is in degrees + .. function:: sech(x) - Compute the hyperbolic secant of "x" + Compute the hyperbolic secant of "x" + .. function:: csch(x) - Compute the hyperbolic cosecant of "x" + Compute the hyperbolic cosecant of "x" + .. function:: coth(x) - Compute the hyperbolic cotangent of "x" + Compute the hyperbolic cotangent of "x" + .. function:: asinh(x) - Compute the inverse hyperbolic sine of "x" + Compute the inverse hyperbolic sine of "x" + .. function:: acosh(x) - Compute the inverse hyperbolic cosine of "x" + Compute the inverse hyperbolic cosine of "x" + .. function:: atanh(x) - Compute the inverse hyperbolic tangent of "x" + Compute the inverse hyperbolic tangent of "x" + .. function:: asech(x) - Compute the inverse hyperbolic secant of "x" + Compute the inverse hyperbolic secant of "x" + .. function:: acsch(x) - Compute the inverse hyperbolic cosecant of "x" + Compute the inverse hyperbolic cosecant of "x" + .. function:: acoth(x) - Compute the inverse hyperbolic cotangent of "x" + Compute the inverse hyperbolic cotangent of "x" + .. function:: sinc(x) - Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. + Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. + .. function:: cosc(x) - Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq - 0, and 0 if x = 0. This is the derivative of "sinc(x)". + Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq 0, and 0 if x = 0. This is the derivative of "sinc(x)". + .. function:: deg2rad(x) - Convert "x" from degrees to radians + Convert "x" from degrees to radians + .. function:: rad2deg(x) - Convert "x" from radians to degrees + Convert "x" from radians to degrees + .. function:: hypot(x, y) - Compute the \sqrt{x^2+y^2} avoiding overflow and underflow + Compute the \sqrt{x^2+y^2} avoiding overflow and underflow + .. function:: log(b, x) - Compute the base "b" logarithm of "x". Throws "DomainError" - for negative "Real" arguments. + Compute the base "b" logarithm of "x". Throws "DomainError" for negative "Real" arguments. + .. function:: log(b, x) - Compute the base "b" logarithm of "x". Throws "DomainError" - for negative "Real" arguments. + Compute the base "b" logarithm of "x". Throws "DomainError" for negative "Real" arguments. + .. function:: log2(x) - Compute the logarithm of "x" to base 2. Throws "DomainError" - for negative "Real" arguments. + Compute the logarithm of "x" to base 2. Throws "DomainError" for negative "Real" arguments. + .. function:: log10(x) - Compute the logarithm of "x" to base 10. Throws "DomainError" - for negative "Real" arguments. + Compute the logarithm of "x" to base 10. Throws "DomainError" for negative "Real" arguments. + .. function:: log1p(x) - Accurate natural logarithm of "1+x". Throws "DomainError" for - "Real" arguments less than -1. + Accurate natural logarithm of "1+x". Throws "DomainError" for "Real" arguments less than -1. + + There is an experimental variant in the "Base.Math.JuliaLibm" module, which is typically faster and more accurate. - There is an experimental variant in the "Base.Math.JuliaLibm" - module, which is typically faster and more accurate. .. function:: frexp(val) - Return "(x,exp)" such that "x" has a magnitude in the interval - "[1/2, 1)" or 0, and val = x \times 2^{exp}. + Return "(x,exp)" such that "x" has a magnitude in the interval "[1/2, 1)" or 0, and val = x \times 2^{exp}. + .. function:: exp(x) - Compute e^x + Compute e^x + .. function:: exp2(x) - Compute 2^x + Compute 2^x + .. function:: exp10(x) - Compute 10^x + Compute 10^x + .. function:: ldexp(x, n) - Compute x \times 2^n + Compute x \times 2^n + .. function:: modf(x) - Return a tuple (fpart,ipart) of the fractional and integral parts - of a number. Both parts have the same sign as the argument. + Return a tuple (fpart,ipart) of the fractional and integral parts of a number. Both parts have the same sign as the argument. + .. function:: expm1(x) - Accurately compute e^x-1 + Accurately compute e^x-1 + .. function:: round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- - valued "z" to "z", breaking ties using the specified - "RoundingMode"s. The first "RoundingMode" is used for rounding - the real components while the second is used for rounding the - imaginary components. + Returns the nearest integral value of the same type as the complex- valued "z" to "z", breaking ties using the specified "RoundingMode"s. The first "RoundingMode" is used for rounding the real components while the second is used for rounding the imaginary components. + julia> round(pi, 2) 3.14 @@ -772,1035 +843,63 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) - Returns the nearest integral value of the same type as the complex- - valued "z" to "z", breaking ties using the specified - "RoundingMode"s. The first "RoundingMode" is used for rounding - the real components while the second is used for rounding the - imaginary components. - -.. function:: ceil([T], x[, digits[, base]]) - - "ceil(x)" returns the nearest integral value of the same type as - "x" that is greater than or equal to "x". - - "ceil(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. - - "digits" and "base" work as for "round()". - -.. function:: floor([T], x[, digits[, base]]) - - "floor(x)" returns the nearest integral value of the same type as - "x" that is less than or equal to "x". - - "floor(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. - - "digits" and "base" work as for "round()". - -.. function:: trunc([T], x[, digits[, base]]) - - "trunc(x)" returns the nearest integral value of the same type as - "x" whose absolute value is less than or equal to "x". - - "trunc(T, x)" converts the result to type "T", throwing an - "InexactError" if the value is not representable. - - "digits" and "base" work as for "round()". - -.. function:: unsafe_trunc(T, x) - - "unsafe_trunc(T, x)" returns the nearest integral value of type - "T" whose absolute value is less than or equal to "x". If the - value is not representable by "T", an arbitrary value will be - returned. - -.. function:: signif(x, digits[, base]) - - Rounds (in the sense of "round") "x" so that there are - "digits" significant digits, under a base "base" - representation, default 10. E.g., "signif(123.456, 2)" is - "120.0", and "signif(357.913, 4, 2)" is "352.0". - -.. function:: min(x, y, ...) - - Return the minimum of the arguments. Operates elementwise over - arrays. - -.. function:: max(x, y, ...) - - Return the maximum of the arguments. Operates elementwise over - arrays. - -.. function:: minmax(x, y) - - Return "(min(x,y), max(x,y))". See also: "extrema()" that - returns "(minimum(x), maximum(x))" - -.. function:: clamp(x, lo, hi) - - Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x - > hi", return "hi". Arguments are promoted to a common type. - Operates elementwise over "x" if it is an array. - -.. function:: abs(x) - - Absolute value of "x" - -.. function:: abs2(x) - - Squared absolute value of "x" - -.. function:: copysign(x, y) - - Return "x" such that it has the same sign as "y" - -.. function:: sign(x) - - Return "+1" if "x" is positive, "0" if "x == 0", and "-1" - if "x" is negative. - -.. function:: signbit(x) - - Returns "true" if the value of the sign of "x" is negative, - otherwise "false". - -.. function:: flipsign(x, y) - - Return "x" with its sign flipped if "y" is negative. For - example "abs(x) = flipsign(x,x)". - -.. function:: sqrt(x) - - Return \sqrt{x}. Throws "DomainError" for negative "Real" - arguments. Use complex negative arguments instead. The prefix - operator "√" is equivalent to "sqrt". - -.. function:: isqrt(n) - - Integer square root: the largest integer "m" such that "m*m <= - n". - -.. function:: cbrt(x) - - Return x^{1/3}. The prefix operator "∛" is equivalent to - "cbrt". - -.. function:: erf(x) - - Compute the error function of "x", defined by - \frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex - "x". - -.. function:: erfc(x) - - Compute the complementary error function of "x", defined by 1 - - \operatorname{erf}(x). - -.. function:: erfcx(x) - - Compute the scaled complementary error function of "x", defined - by e^{x^2} \operatorname{erfc}(x). Note also that - \operatorname{erfcx}(-ix) computes the Faddeeva function w(x). - -.. function:: erfi(x) - - Compute the imaginary error function of "x", defined by -i - \operatorname{erf}(ix). - -.. function:: dawson(x) - - Compute the Dawson function (scaled imaginary error function) of - "x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} - \operatorname{erfi}(x). - -.. function:: erfinv(x) - - Compute the inverse error function of a real "x", defined by - \operatorname{erf}(\operatorname{erfinv}(x)) = x. - -.. function:: erfcinv(x) - - Compute the inverse error complementary function of a real "x", - defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. - -.. function:: real(z) - - Return the real part of the complex number "z" - -.. function:: imag(z) - - Return the imaginary part of the complex number "z" - -.. function:: reim(z) - - Return both the real and imaginary parts of the complex number - "z" - -.. function:: conj(z) - - Compute the complex conjugate of a complex number "z" - -.. function:: angle(z) - - Compute the phase angle in radians of a complex number "z" - -.. function:: cis(z) - - Return \exp(iz). - -.. function:: binomial(n, k) - - Number of ways to choose "k" out of "n" items - -.. function:: factorial(n, k) - - Compute "factorial(n)/factorial(k)" - -.. function:: factorial(n, k) - - Compute "factorial(n)/factorial(k)" - -.. function:: factor(n) -> Dict - - Compute the prime factorization of an integer "n". Returns a - dictionary. The keys of the dictionary correspond to the factors, - and hence are of the same type as "n". The value associated with - each key indicates the number of times the factor appears in the - factorization. - - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 - -.. function:: gcd(x, y) - - Greatest common (positive) divisor (or zero if x and y are both - zero). - -.. function:: lcm(x, y) - - Least common (non-negative) multiple. - -.. function:: gcdx(x, y) - - Computes the greatest common (positive) divisor of "x" and "y" - and their Bézout coefficients, i.e. the integer coefficients "u" - and "v" that satisfy ux+vy = d = gcd(x,y). - - julia> gcdx(12, 42) - (6,-3,1) - - julia> gcdx(240, 46) - (2,-9,47) - - Note: Bézout coefficients are *not* uniquely defined. "gcdx" - returns the minimal Bézout coefficients that are computed by the - extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, - Algorithm X.) These coefficients "u" and "v" are minimal in - the sense that |u| < |\frac y d and |v| < |\frac x d. - Furthermore, the signs of "u" and "v" are chosen so that - "d" is positive. - -.. function:: ispow2(n) -> Bool + Returns the nearest integral value of the same type as the complex- valued "z" to "z", breaking ties using the specified "RoundingMode"s. The first "RoundingMode" is used for rounding the real components while the second is used for rounding the imaginary components. - Test whether "n" is a power of two -.. function:: nextpow2(n) - - The smallest power of two not less than "n". Returns 0 for - "n==0", and returns "-nextpow2(-n)" for negative arguments. - -.. function:: prevpow2(n) - - The largest power of two not greater than "n". Returns 0 for - "n==0", and returns "-prevpow2(-n)" for negative arguments. - -.. function:: nextpow(a, x) - - The smallest "a^n" not less than "x", where "n" is a non- - negative integer. "a" must be greater than 1, and "x" must be - greater than 0. - -.. function:: prevpow(a, x) - - The largest "a^n" not greater than "x", where "n" is a non- - negative integer. "a" must be greater than 1, and "x" must not - be less than 1. - -.. function:: nextprod([k_1, k_2, ...], n) - - Next integer not less than "n" that can be written as \prod - k_i^{p_i} for integers p_1, p_2, etc. - -.. function:: prevprod([k_1, k_2, ...], n) - - Previous integer not greater than "n" that can be written as - \prod k_i^{p_i} for integers p_1, p_2, etc. - -.. function:: invmod(x, m) - - Take the inverse of "x" modulo "m": "y" such that xy = 1 - \pmod m - -.. function:: powermod(x, p, m) - - Compute x^p \pmod m - -.. function:: gamma(x) - - Compute the gamma function of "x" - -.. function:: lgamma(x) - - Compute the logarithm of the absolute value of "gamma()" for - "Real" "x", while for "Complex" "x" it computes the - logarithm of "gamma(x)". - -.. function:: lfact(x) - - Compute the logarithmic factorial of "x" - -.. function:: digamma(x) - - Compute the digamma function of "x" (the logarithmic derivative - of "gamma(x)") - -.. function:: invdigamma(x) - - Compute the inverse digamma function of "x". - -.. function:: trigamma(x) - - Compute the trigamma function of "x" (the logarithmic second - derivative of "gamma(x)") - -.. function:: polygamma(m, x) - - Compute the polygamma function of order "m" of argument "x" - (the "(m+1)th" derivative of the logarithm of "gamma(x)") - -.. function:: airy(k, x) - - kth derivative of the Airy function \operatorname{Ai}(x). - -.. function:: airyai(x) - - Airy function \operatorname{Ai}(x). - -.. function:: airyprime(x) - - Airy function derivative \operatorname{Ai}'(x). - -.. function:: airyaiprime(x) - - Airy function derivative \operatorname{Ai}'(x). - -.. function:: airybi(x) - - Airy function \operatorname{Bi}(x). - -.. function:: airybiprime(x) - - Airy function derivative \operatorname{Bi}'(x). - -.. function:: airyx(k, x) - - scaled kth derivative of the Airy function, return - \operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || - k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} - \left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || - k == 3". - -.. function:: besselj0(x) - - Bessel function of the first kind of order 0, J_0(x). - -.. function:: besselj1(x) - - Bessel function of the first kind of order 1, J_1(x). - -.. function:: besselj(nu, x) - - Bessel function of the first kind of order "nu", J_\nu(x). - -.. function:: besseljx(nu, x) - - Scaled Bessel function of the first kind of order "nu", J_\nu(x) - e^{- | \operatorname{Im}(x) |}. - -.. function:: bessely0(x) - - Bessel function of the second kind of order 0, Y_0(x). - -.. function:: bessely1(x) - - Bessel function of the second kind of order 1, Y_1(x). - -.. function:: bessely(nu, x) - - Bessel function of the second kind of order "nu", Y_\nu(x). - -.. function:: besselyx(nu, x) - - Scaled Bessel function of the second kind of order "nu", - Y_\nu(x) e^{- | \operatorname{Im}(x) |}. - -.. function:: hankelh1(nu, x) - - Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). - -.. function:: hankelh1x(nu, x) - - Scaled Bessel function of the third kind of order "nu", - H^{(1)}_\nu(x) e^{-x i}. - -.. function:: hankelh2(nu, x) - - Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). - -.. function:: hankelh2x(nu, x) - - Scaled Bessel function of the third kind of order "nu", - H^{(2)}_\nu(x) e^{x i}. - -.. function:: besselh(nu, k, x) - - Bessel function of the third kind of order "nu" (Hankel - function). "k" is either 1 or 2, selecting "hankelh1" or - "hankelh2", respectively. - -.. function:: besseli(nu, x) - - Modified Bessel function of the first kind of order "nu", - I_\nu(x). - -.. function:: besselix(nu, x) - - Scaled modified Bessel function of the first kind of order "nu", - I_\nu(x) e^{- | \operatorname{Re}(x) |}. - -.. function:: besselk(nu, x) - - Modified Bessel function of the second kind of order "nu", - K_\nu(x). - -.. function:: besselkx(nu, x) - - Scaled modified Bessel function of the second kind of order "nu", - K_\nu(x) e^x. - -.. function:: beta(x, y) - - Euler integral of the first kind \operatorname{B}(x,y) = - \Gamma(x)\Gamma(y)/\Gamma(x+y). - -.. function:: lbeta(x, y) - - Natural logarithm of the absolute value of the beta function - \log(|\operatorname{B}(x,y)|). - -.. function:: eta(x) - - Dirichlet eta function \eta(s) = - \sum^\infty_{n=1}(-)^{n-1}/n^{s}. - -.. function:: zeta(s, z) - - Hurwitz zeta function \zeta(s, z). (This is equivalent to the - Riemann zeta function \zeta(s) for the case of "z=1".) - -.. function:: zeta(s, z) - - Hurwitz zeta function \zeta(s, z). (This is equivalent to the - Riemann zeta function \zeta(s) for the case of "z=1".) - -.. function:: ndigits(n, b) - - Compute the number of digits in number "n" written in base "b". - -.. function:: widemul(x, y) - - Multiply "x" and "y", giving the result as a larger type. - -.. function:: @evalpoly(z, c...) - - Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients - "c[1]", "c[2]", ...; that is, the coefficients are given in - ascending order by power of "z". This macro expands to efficient - inline code that uses either Horner's method or, for complex "z", - a more efficient Goertzel-like algorithm. - -Statistics ----------- - -.. function:: mean(v[, region]) - - Compute the mean of whole array "v", or optionally along the - dimensions in "region". Note: Julia does not ignore "NaN" - values in the computation. For applications requiring the handling - of missing data, the "DataArray" package is recommended. - -.. function:: mean!(r, v) - - Compute the mean of "v" over the singleton dimensions of "r", - and write results to "r". - -.. function:: std(v[, region]) - - Compute the sample standard deviation of a vector or array "v", - optionally along dimensions in "region". The algorithm returns an - estimator of the generative distribution's standard deviation under - the assumption that each entry of "v" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". - Note: Julia does not ignore "NaN" values in the computation. For - applications requiring the handling of missing data, the - "DataArray" package is recommended. - -.. function:: stdm(v, m) - - Compute the sample standard deviation of a vector "v" with known - mean "m". Note: Julia does not ignore "NaN" values in the - computation. - -.. function:: var(v[, region]) - - Compute the sample variance of a vector or array "v", optionally - along dimensions in "region". The algorithm will return an - estimator of the generative distribution's variance under the - assumption that each entry of "v" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: - Julia does not ignore "NaN" values in the computation. For - applications requiring the handling of missing data, the - "DataArray" package is recommended. - -.. function:: varm(v, m) - - Compute the sample variance of a vector "v" with known mean - "m". Note: Julia does not ignore "NaN" values in the - computation. - -.. function:: middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - -.. function:: middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - -.. function:: middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - -.. function:: middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - -.. function:: median(v) - - Compute the median of a vector "v". "NaN" is returned if the - data contains any "NaN" values. For applications requiring the - handling of missing data, the "DataArrays" package is - recommended. - -.. function:: median!(v) - - Like "median", but may overwrite the input vector. - -.. function:: hist(v, e) -> e, counts - - Compute the histogram of "v" using a vector/range "e" as the - edges for the bins. The result will be a vector of length - "length(e) - 1", such that the element at location "i" - satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not - ignore "NaN" values in the computation. - -.. function:: hist(v, e) -> e, counts - - Compute the histogram of "v" using a vector/range "e" as the - edges for the bins. The result will be a vector of length - "length(e) - 1", such that the element at location "i" - satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not - ignore "NaN" values in the computation. - -.. function:: hist!(counts, v, e) -> e, counts - - Compute the histogram of "v", using a vector/range "e" as the - edges for the bins. This function writes the resultant counts to a - pre-allocated array "counts". - -.. function:: hist2d(M, e1, e2) -> (edge1, edge2, counts) - - Compute a "2d histogram" of a set of N points specified by N-by-2 - matrix "M". Arguments "e1" and "e2" are bins for each - dimension, specified either as integer bin counts or vectors of bin - edges. The result is a tuple of "edge1" (the bin edges used in - the first dimension), "edge2" (the bin edges used in the second - dimension), and "counts", a histogram matrix of size - "(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore - "NaN" values in the computation. - -.. function:: hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - - Compute a "2d histogram" with respect to the bins delimited by - the edges given in "e1" and "e2". This function writes the - results to a pre-allocated array "counts". - -.. function:: histrange(v, n) - - Compute *nice* bin ranges for the edges of a histogram of "v", - using approximately "n" bins. The resulting step sizes will be 1, - 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - "NaN" values in the computation. - -.. function:: midpoints(e) - - Compute the midpoints of the bins with edges "e". The result is a - vector/range of length "length(e) - 1". Note: Julia does not - ignore "NaN" values in the computation. - -.. function:: quantile(v, p) - - Compute the quantile of a vector "v" at the probability "p". - Note: Julia does not ignore "NaN" values in the computation. - -.. function:: quantile(v, p) - - Compute the quantile of a vector "v" at the probability "p". - Note: Julia does not ignore "NaN" values in the computation. - -.. function:: quantile!(v, p) - - Like "quantile", but overwrites the input vector. - -.. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - - Compute the Pearson covariance between the vector(s) in "v1" and - "v2". Here, "v1" and "v2" can be either vectors or matrices. - - This function accepts three keyword arguments: - - * "vardim": the dimension of variables. When "vardim = 1", - variables are considered in columns while observations in rows; - when "vardim = 2", variables are in rows while observations in - columns. By default, it is set to "1". - - * "corrected": whether to apply Bessel's correction (divide by - "n-1" instead of "n"). By default, it is set to "true". - - * "mean": allow users to supply mean values that are known. By - default, it is set to "nothing", which indicates that the - mean(s) are unknown, and the function will compute the mean. - Users can use "mean=0" to indicate that the input data are - centered, and hence there's no need to subtract the mean. - - The size of the result depends on the size of "v1" and "v2". - When both "v1" and "v2" are vectors, it returns the covariance - between them as a scalar. When either one is a matrix, it returns a - covariance matrix of size "(n1, n2)", where "n1" and "n2" are - the numbers of slices in "v1" and "v2", which depend on the - setting of "vardim". - - Note: "v2" can be omitted, which indicates "v2 = v1". - -.. function:: cor(v1[, v2][, vardim=1, mean=nothing]) - - Compute the Pearson correlation between the vector(s) in "v1" and - "v2". - - Users can use the keyword argument "vardim" to specify the - variable dimension, and "mean" to supply pre-computed mean - values. - -Signal Processing ------------------ - -Fast Fourier transform (FFT) functions in Julia are largely -implemented by calling functions from `FFTW -`_. By default, Julia does not use multi-threaded -FFTW. Higher performance may be obtained by experimenting with -multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. - -.. function:: fft(A[, dims]) - - Performs a multidimensional FFT of the array "A". The optional - "dims" argument specifies an iterable subset of dimensions (e.g. - an integer, range, tuple, or array) to transform along. Most - efficient if the size of "A" along the transformed dimensions is - a product of small primes; see "nextprod()". See also - "plan_fft()" for even greater efficiency. - - A one-dimensional FFT computes the one-dimensional discrete Fourier - transform (DFT) as defined by - - \operatorname{DFT}(A)[k] = - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(-i\frac{2\pi - (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. - - A multidimensional FFT simply performs this operation along each - transformed dimension of "A". - - Higher performance is usually possible with multi-threading. Use - *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* - processors. - -.. function:: fft!(A[, dims]) - - Same as "fft()", but operates in-place on "A", which must be an - array of complex floating-point numbers. - -.. function:: ifft(A[, dims]) - - Multidimensional inverse FFT. - - A one-dimensional inverse FFT computes - - \operatorname{IDFT}(A)[k] = - \frac{1}{\operatorname{length}(A)} - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(+i\frac{2\pi (n-1)(k-1)} - {\operatorname{length}(A)} \right) A[n]. - - A multidimensional inverse FFT simply performs this operation along - each transformed dimension of "A". - -.. function:: ifft!(A[, dims]) - - Same as "ifft()", but operates in-place on "A". - -.. function:: bfft(A[, dims]) - - Similar to "ifft()", but computes an unnormalized inverse - (backward) transform, which must be divided by the product of the - sizes of the transformed dimensions in order to obtain the inverse. - (This is slightly more efficient than "ifft()" because it omits a - scaling step, which in some applications can be combined with other - computational steps elsewhere.) - - \operatorname{BDFT}(A)[k] = \operatorname{length}(A) - \operatorname{IDFT}(A)[k] - -.. function:: bfft!(A[, dims]) - - Same as "bfft()", but operates in-place on "A". - -.. function:: plan_fft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized FFT along given dimensions ("dims") of - arrays matching the shape and type of "A". (The first two - arguments have the same meaning as for "fft()".) Returns a - function "plan(A)" that computes "fft(A, dims)" quickly. - - The "flags" argument is a bitwise-or of FFTW planner flags, - defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or - "FFTW.PATIENT" will instead spend several seconds (or more) - benchmarking different possible FFT algorithms and picking the - fastest one; see the FFTW manual for more information on planner - flags. The optional "timelimit" argument specifies a rough upper - bound on the allowed planning time, in seconds. Passing - "FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array - "A" to be overwritten with zeros during plan creation. - - "plan_fft!()" is the same as "plan_fft()" but creates a plan - that operates in-place on its argument (which must be an array of - complex floating-point numbers). "plan_ifft()" and so on are - similar but produce plans that perform the equivalent of the - inverse transforms "ifft()" and so on. - -.. function:: plan_ifft(A[, dims[, flags[, timelimit]]]) - - Same as "plan_fft()", but produces a plan that performs inverse - transforms "ifft()". - -.. function:: plan_bfft(A[, dims[, flags[, timelimit]]]) - - Same as "plan_fft()", but produces a plan that performs an - unnormalized backwards transform "bfft()". - -.. function:: plan_fft!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_fft()", but operates in-place on "A". - -.. function:: plan_ifft!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_ifft()", but operates in-place on "A". - -.. function:: plan_bfft!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_bfft()", but operates in-place on "A". - -.. function:: rfft(A[, dims]) - - Multidimensional FFT of a real array A, exploiting the fact that - the transform has conjugate symmetry in order to save roughly half - the computational time and storage costs compared with "fft()". - If "A" has size "(n_1, ..., n_d)", the result has size - "(floor(n_1/2)+1, ..., n_d)". - - The optional "dims" argument specifies an iterable subset of one - or more dimensions of "A" to transform, similar to "fft()". - Instead of (roughly) halving the first dimension of "A" in the - result, the "dims[1]" dimension is (roughly) halved in the same - way. - -.. function:: irfft(A, d[, dims]) - - Inverse of "rfft()": for a complex array "A", gives the - corresponding real array whose FFT yields "A" in the first half. - As for "rfft()", "dims" is an optional subset of dimensions to - transform, defaulting to "1:ndims(A)". - - "d" is the length of the transformed real array along the - "dims[1]" dimension, which must satisfy "d == - floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred - from "size(A)" due to the possibility of rounding by the - "floor" function here.) - -.. function:: brfft(A, d[, dims]) - - Similar to "irfft()" but computes an unnormalized inverse - transform (similar to "bfft()"), which must be divided by the - product of the sizes of the transformed dimensions (of the real - output array) in order to obtain the inverse transform. - -.. function:: plan_rfft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized real-input FFT, similar to "plan_fft()" - except for "rfft()" instead of "fft()". The first two - arguments, and the size of the transformed result, are the same as - for "rfft()". - -.. function:: plan_brfft(A, d[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized real-input unnormalized transform, similar to - "plan_rfft()" except for "brfft()" instead of "rfft()". The - first two arguments and the size of the transformed result, are the - same as for "brfft()". - -.. function:: plan_irfft(A, d[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized inverse real-input FFT, similar to - "plan_rfft()" except for "irfft()" and "brfft()", - respectively. The first three arguments have the same meaning as - for "irfft()". - -.. function:: dct(A[, dims]) - - Performs a multidimensional type-II discrete cosine transform (DCT) - of the array "A", using the unitary normalization of the DCT. The - optional "dims" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of "A" along the transformed - dimensions is a product of small primes; see "nextprod()". See - also "plan_dct()" for even greater efficiency. - -.. function:: dct!(A[, dims]) - - Same as "dct!()", except that it operates in-place on "A", - which must be an array of real or complex floating-point values. - -.. function:: idct(A[, dims]) - - Computes the multidimensional inverse discrete cosine transform - (DCT) of the array "A" (technically, a type-III DCT with the - unitary normalization). The optional "dims" argument specifies an - iterable subset of dimensions (e.g. an integer, range, tuple, or - array) to transform along. Most efficient if the size of "A" - along the transformed dimensions is a product of small primes; see - "nextprod()". See also "plan_idct()" for even greater - efficiency. - -.. function:: idct!(A[, dims]) - - Same as "idct!()", but operates in-place on "A". - -.. function:: plan_dct(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized discrete cosine transform (DCT), similar to - "plan_fft()" except producing a function that computes "dct()". - The first two arguments have the same meaning as for "dct()". - -.. function:: plan_dct!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_dct()", but operates in-place on "A". - -.. function:: plan_idct(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized inverse discrete cosine transform (DCT), - similar to "plan_fft()" except producing a function that computes - "idct()". The first two arguments have the same meaning as for - "idct()". - -.. function:: plan_idct!(A[, dims[, flags[, timelimit]]]) - - Same as "plan_idct()", but operates in-place on "A". - -.. function:: fftshift(x, dim) +.. function:: ceil([T], x[, digits[, base]]) - Swap the first and second halves of the given dimension of array - "x". + "ceil(x)" returns the nearest integral value of the same type as "x" that is greater than or equal to "x". -.. function:: fftshift(x, dim) + "ceil(T, x)" converts the result to type "T", throwing an "InexactError" if the value is not representable. - Swap the first and second halves of the given dimension of array - "x". + "digits" and "base" work as for "round()". -.. function:: ifftshift(x[, dim]) - Undoes the effect of "fftshift". +.. function:: floor([T], x[, digits[, base]]) -.. function:: filt(b, a, x[, si]) + "floor(x)" returns the nearest integral value of the same type as "x" that is less than or equal to "x". - Apply filter described by vectors "a" and "b" to vector "x", - with an optional initial filter state vector "si" (defaults to - zeros). + "floor(T, x)" converts the result to type "T", throwing an "InexactError" if the value is not representable. -.. function:: filt!(out, b, a, x[, si]) + "digits" and "base" work as for "round()". - Same as "filt()" but writes the result into the "out" argument, - which may alias the input "x" to modify it in-place. -.. function:: deconv(b, a) +.. function:: trunc([T], x[, digits[, base]]) - Construct vector "c" such that "b = conv(a,c) + r". Equivalent - to polynomial division. + "trunc(x)" returns the nearest integral value of the same type as "x" whose absolute value is less than or equal to "x". -.. function:: conv(u, v) + "trunc(T, x)" converts the result to type "T", throwing an "InexactError" if the value is not representable. - Convolution of two vectors. Uses FFT algorithm. + "digits" and "base" work as for "round()". -.. function:: conv2(B, A) - 2-D convolution of the matrix "B" with the matrix "A". Uses - 2-D FFT algorithm +.. function:: unsafe_trunc(T, x) -.. function:: conv2(B, A) + "unsafe_trunc(T, x)" returns the nearest integral value of type "T" whose absolute value is less than or equal to "x". If the value is not representable by "T", an arbitrary value will be returned. - 2-D convolution of the matrix "B" with the matrix "A". Uses - 2-D FFT algorithm -.. function:: xcorr(u, v) +.. function:: signif(x, digits[, base]) - Compute the cross-correlation of two vectors. + Rounds (in the sense of "round") "x" so that there are "digits" significant digits, under a base "base" representation, default 10. E.g., "signif(123.456, 2)" is "120.0", and "signif(357.913, 4, 2)" is "352.0". -The following functions are defined within the ``Base.FFTW`` module. -.. currentmodule:: Base.FFTW +.. function:: min(x, y, ...) -.. function:: r2r(A, kind[, dims]) + Return the minimum of the arguments. Operates elementwise over arrays. - Performs a multidimensional real-input/real-output (r2r) transform - of type "kind" of the array "A", as defined in the FFTW manual. - "kind" specifies either a discrete cosine transform of various - types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or - "FFTW.REDFT11"), a discrete sine transform of various types - ("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or - "FFTW.RODFT11"), a real-input DFT with halfcomplex-format output - ("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete - Hartley transform ("FFTW.DHT"). The "kind" argument may be an - array or tuple in order to specify different transform types along - the different dimensions of "A"; "kind[end]" is used for any - unspecified dimensions. See the FFTW manual for precise - definitions of these transform types, at http://www.fftw.org/doc. - The optional "dims" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. "kind[i]" is then the transform type for "dims[i]", with - "kind[end]" being used for "i > length(kind)". +.. function:: max(x, y, ...) - See also "plan_r2r()" to pre-plan optimized r2r transforms. + Return the maximum of the arguments. Operates elementwise over arrays. -.. function:: r2r!(A, kind[, dims]) - Same as "r2r()", but operates in-place on "A", which must be an - array of real or complex floating-point numbers. +.. function:: minmax(x, y) -.. function:: plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + Return "(min(x,y), max(x,y))". See also: "extrema()" that returns "(minimum(x), maximum(x))" - Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" - except that the transforms (and the first three arguments) - correspond to "r2r()" and "r2r!()", respectively. -.. function:: plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) +.. function:: clamp(x, lo, hi) - Similar to "Base.plan_fft()", but corresponds to "r2r!()". + Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x > hi", return "hi". Arguments are promoted to a common type. Operates elementwise over "x" if it is an array. -.. currentmodule:: Base -Numerical Integration ---------------------- - -Although several external packages are available for numeric integration -and solution of ordinary differential equations, we also provide -some built-in integration support in Julia. - -.. function:: quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - - Numerically integrate the function "f(x)" from "a" to "b", - and optionally over additional intervals "b" to "c" and so on. - Keyword options include a relative error tolerance "reltol" - (defaults to "sqrt(eps)" in the precision of the endpoints), an - absolute error tolerance "abstol" (defaults to 0), a maximum - number of function evaluations "maxevals" (defaults to "10^7"), - and the "order" of the integration rule (defaults to 7). - - Returns a pair "(I,E)" of the estimated integral "I" and an - estimated upper bound on the absolute error "E". If "maxevals" - is not exceeded then "E <= max(abstol, reltol*norm(I))" will - hold. (Note that it is useful to specify a positive "abstol" in - cases where "norm(I)" may be zero.) - - The endpoints "a" etcetera can also be complex (in which case the - integral is performed over straight-line segments in the complex - plane). If the endpoints are "BigFloat", then the integration - will be performed in "BigFloat" precision as well (note: it is - advisable to increase the integration "order" in rough proportion - to the precision, for smooth integrands). More generally, the - precision is set by the precision of the integration endpoints - (promoted to floating-point types). - - The integrand "f(x)" can return any numeric scalar, vector, or - matrix type, or in fact any type supporting "+", "-", - multiplication by real values, and a "norm" (i.e., any normed - vector space). Alternatively, a different norm can be specified by - passing a *norm*-like function as the *norm* keyword argument - (which defaults to *vecnorm*). - - [Only one-dimensional integrals are provided by this function. For - multi-dimensional integration (cubature), there are many different - algorithms (often much better than simple nested 1d integrals) and - the optimal choice tends to be very problem-dependent. See the - Julia external-package listing for available algorithms for - multidimensional integration or other specialized tasks (such as - integrals of highly oscillatory or singular functions).] - - The algorithm is an adaptive Gauss-Kronrod integration technique: - the integral in each interval is estimated using a Kronrod rule - ("2*order+1" points) and the error is estimated using an embedded - Gauss rule ("order" points). The interval with the largest - error is then subdivided into two intervals and the process is - repeated until the desired error tolerance is achieved. - - These quadrature rules work best for smooth functions within each - interval, so if your function has a known discontinuity or other - singularity, it is best to subdivide your interval to put the - singularity at an endpoint. For example, if "f" has a - discontinuity at "x=0.7" and you want to integrate from 0 to 1, - you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at - the point of discontinuity. The integrand is never evaluated - exactly at the endpoints of the intervals, so it is possible to - integrate functions that diverge at the endpoints as long as the - singularity is integrable (for example, a "log(x)" or - "1/sqrt(x)" singularity). - - For real-valued endpoints, the starting and/or ending points may be - infinite. (A coordinate transformation is performed internally to - map the infinite interval to a finite one.) diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 9e4499c4136e3..58b78022b070d 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -14,145 +14,134 @@ Data Formats .. function:: bin(n[, pad]) - Convert an integer to a binary string, optionally specifying a - number of digits to pad to. + Convert an integer to a binary string, optionally specifying a number of digits to pad to. + .. function:: hex(n[, pad]) - Convert an integer to a hexadecimal string, optionally specifying a - number of digits to pad to. + Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. + .. function:: dec(n[, pad]) - Convert an integer to a decimal string, optionally specifying a - number of digits to pad to. + Convert an integer to a decimal string, optionally specifying a number of digits to pad to. + .. function:: oct(n[, pad]) - Convert an integer to an octal string, optionally specifying a - number of digits to pad to. + Convert an integer to an octal string, optionally specifying a number of digits to pad to. + .. function:: base(base, n[, pad]) - Convert an integer to a string in the given base, optionally - specifying a number of digits to pad to. The base can be specified - as either an integer, or as a "UInt8" array of character values - to use as digit symbols. + Convert an integer to a string in the given base, optionally specifying a number of digits to pad to. The base can be specified as either an integer, or as a "UInt8" array of character values to use as digit symbols. + .. function:: digits(n[, base][, pad]) - Returns an array of the digits of "n" in the given base, - optionally padded with zeros to a specified size. More significant - digits are at higher indexes, such that "n == - sum([digits[k]*base^(k-1) for k=1:length(digits)])". + Returns an array of the digits of "n" in the given base, optionally padded with zeros to a specified size. More significant digits are at higher indexes, such that "n == sum([digits[k]*base^(k-1) for k=1:length(digits)])". + .. function:: digits!(array, n[, base]) - Fills an array of the digits of "n" in the given base. More - significant digits are at higher indexes. If the array length is - insufficient, the least significant digits are filled up to the - array length. If the array length is excessive, the excess portion - is filled with zeros. + Fills an array of the digits of "n" in the given base. More significant digits are at higher indexes. If the array length is insufficient, the least significant digits are filled up to the array length. If the array length is excessive, the excess portion is filled with zeros. + .. function:: bits(n) - A string giving the literal bit representation of a number. + A string giving the literal bit representation of a number. + .. function:: parse(type, str[, base]) - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. + .. function:: tryparse(type, str[, base]) - Like "parse", but returns a "Nullable" of the requested type. - The result will be null if the string does not contain a valid - number. + Like "parse", but returns a "Nullable" of the requested type. The result will be null if the string does not contain a valid number. + .. function:: big(x) - Convert a number to a maximum precision representation (typically - "BigInt" or "BigFloat"). See "BigFloat" for information about - some pitfalls with floating-point numbers. + Convert a number to a maximum precision representation (typically "BigInt" or "BigFloat"). See "BigFloat" for information about some pitfalls with floating-point numbers. + .. function:: signed(x) - Convert a number to a signed integer. If the argument is unsigned, - it is reinterpreted as signed without checking for overflow. + Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. + .. function:: unsigned(x) -> Unsigned - Convert a number to an unsigned integer. If the argument is signed, - it is reinterpreted as unsigned without checking for negative - values. + Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as unsigned without checking for negative values. + .. function:: float(x) - Convert a number, array, or string to a "FloatingPoint" data - type. For numeric data, the smallest suitable "FloatingPoint" - type is used. Converts strings to "Float64". + Convert a number, array, or string to a "FloatingPoint" data type. For numeric data, the smallest suitable "FloatingPoint" type is used. Converts strings to "Float64". + .. function:: significand(x) - Extract the significand(s) (a.k.a. mantissa), in binary - representation, of a floating-point number or array. If "x" is a - non-zero finite number, than the result will be a number of the - same type on the interval [1,2). Otherwise "x" is returned. + Extract the significand(s) (a.k.a. mantissa), in binary representation, of a floating-point number or array. If "x" is a non-zero finite number, than the result will be a number of the same type on the interval [1,2). Otherwise "x" is returned. + + :: + + julia> significand(15.2)/15.2 + 0.125 - julia> significand(15.2)/15.2 - 0.125 + julia> significand(15.2)*8 + 15.2 - julia> significand(15.2)*8 - 15.2 .. function:: exponent(x) -> Int - Get the exponent of a normalized floating-point number. + Get the exponent of a normalized floating-point number. + .. function:: complex(r[, i]) - Convert real numbers or arrays to complex. "i" defaults to zero. + Convert real numbers or arrays to complex. "i" defaults to zero. + .. function:: bswap(n) - Byte-swap an integer + Byte-swap an integer + .. function:: num2hex(f) - Get a hexadecimal string of the binary representation of a floating - point number + Get a hexadecimal string of the binary representation of a floating point number + .. function:: hex2num(str) - Convert a hexadecimal string to the floating point number it - represents + Convert a hexadecimal string to the floating point number it represents + .. function:: hex2bytes(s::ASCIIString) - Convert an arbitrarily long hexadecimal string to its binary - representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. + Convert an arbitrarily long hexadecimal string to its binary representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. + .. function:: bytes2hex(bin_arr::Array{UInt8, 1}) - Convert an array of bytes to its hexadecimal representation. All - characters are in lower-case. Returns an ASCIIString. + Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. + General Number Functions and Constants -------------------------------------- .. function:: one(x) - Get the multiplicative identity element for the type of x (x can - also specify the type itself). For matrices, returns an identity - matrix of the appropriate size and type. + Get the multiplicative identity element for the type of x (x can also specify the type itself). For matrices, returns an identity matrix of the appropriate size and type. + .. function:: zero(x) - Get the additive identity element for the type of x (x can also - specify the type itself). + Get the additive identity element for the type of x (x can also specify the type itself). + .. data:: pi π @@ -208,222 +197,244 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool - Test whether a floating point number is subnormal + Test whether a floating point number is subnormal + .. function:: isfinite(f) -> Bool - Test whether a number is finite + Test whether a number is finite + .. function:: isinf(f) -> Bool - Test whether a number is infinite + Test whether a number is infinite + .. function:: isnan(f) -> Bool - Test whether a floating point number is not a number (NaN) + Test whether a floating point number is not a number (NaN) + .. function:: inf(f) - Returns positive infinity of the floating point type "f" or of - the same floating point type as "f" + Returns positive infinity of the floating point type "f" or of the same floating point type as "f" + .. function:: nan(f) - Returns NaN (not-a-number) of the floating point type "f" or of - the same floating point type as "f" + Returns NaN (not-a-number) of the floating point type "f" or of the same floating point type as "f" + .. function:: nextfloat(f) - Get the next floating point number in lexicographic order + Get the next floating point number in lexicographic order + .. function:: prevfloat(f) -> FloatingPoint - Get the previous floating point number in lexicographic order + Get the previous floating point number in lexicographic order + .. function:: isinteger(x) -> Bool - Test whether "x" or all its elements are numerically equal to - some integer + Test whether "x" or all its elements are numerically equal to some integer + .. function:: isreal(x) -> Bool - Test whether "x" or all its elements are numerically equal to - some real number + Test whether "x" or all its elements are numerically equal to some real number + .. function:: Float32(x[, mode::RoundingMode]) - Create a Float32 from "x". If "x" is not exactly representable - then "mode" determines how "x" is rounded. + Create a Float32 from "x". If "x" is not exactly representable then "mode" determines how "x" is rounded. + + :: - julia> Float32(1/3, RoundDown) - 0.3333333f0 + julia> Float32(1/3, RoundDown) + 0.3333333f0 - julia> Float32(1/3, RoundUp) - 0.33333334f0 + julia> Float32(1/3, RoundUp) + 0.33333334f0 + + See "get_rounding" for available rounding modes. - See "get_rounding" for available rounding modes. .. function:: Float64(x[, mode::RoundingMode]) - Create a Float64 from "x". If "x" is not exactly representable - then "mode" determines how "x" is rounded. + Create a Float64 from "x". If "x" is not exactly representable then "mode" determines how "x" is rounded. + + :: + + julia> Float64(pi, RoundDown) + 3.141592653589793 - julia> Float64(pi, RoundDown) - 3.141592653589793 + julia> Float64(pi, RoundUp) + 3.1415926535897936 - julia> Float64(pi, RoundUp) - 3.1415926535897936 + See "get_rounding" for available rounding modes. - See "get_rounding" for available rounding modes. .. function:: BigInt(x) - Create an arbitrary precision integer. "x" may be an "Int" (or - anything that can be converted to an "Int"). The usual - mathematical operators are defined for this type, and results are - promoted to a "BigInt". + Create an arbitrary precision integer. "x" may be an "Int" (or anything that can be converted to an "Int"). The usual mathematical operators are defined for this type, and results are promoted to a "BigInt". + + Instances can be constructed from strings via "parse()", or using the "big" string literal. - Instances can be constructed from strings via "parse()", or using - the "big" string literal. .. function:: BigFloat(x) - Create an arbitrary precision floating point number. "x" may be - an "Integer", a "Float64" or a "BigInt". The usual - mathematical operators are defined for this type, and results are - promoted to a "BigFloat". + Create an arbitrary precision floating point number. "x" may be an "Integer", a "Float64" or a "BigInt". The usual mathematical operators are defined for this type, and results are promoted to a "BigFloat". + + Note that because decimal literals are converted to floating point numbers when parsed, "BigFloat(2.1)" may not yield what you expect. You may instead prefer to initialize constants from strings via "parse()", or using the "big" string literal. - Note that because decimal literals are converted to floating point - numbers when parsed, "BigFloat(2.1)" may not yield what you - expect. You may instead prefer to initialize constants from strings - via "parse()", or using the "big" string literal. + :: + + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision .. function:: get_rounding(T) - Get the current floating point rounding mode for type "T", - controlling the rounding of basic arithmetic functions ("+()", - "-()", "*()", "/()" and "sqrt()") and type conversion. + Get the current floating point rounding mode for type "T", controlling the rounding of basic arithmetic functions ("+()", "-()", "*()", "/()" and "sqrt()") and type conversion. + + Valid modes are "RoundNearest", "RoundToZero", "RoundUp", "RoundDown", and "RoundFromZero" ("BigFloat" only). - Valid modes are "RoundNearest", "RoundToZero", "RoundUp", - "RoundDown", and "RoundFromZero" ("BigFloat" only). .. function:: set_rounding(T, mode) - Set the rounding mode of floating point type "T", controlling the - rounding of basic arithmetic functions ("+()", "-()", "*()", - "/()" and "sqrt()") and type conversion. + Set the rounding mode of floating point type "T", controlling the rounding of basic arithmetic functions ("+()", "-()", "*()", "/()" and "sqrt()") and type conversion. + + Note that this may affect other types, for instance changing the rounding mode of "Float64" will change the rounding mode of "Float32". See "get_rounding" for available modes - Note that this may affect other types, for instance changing the - rounding mode of "Float64" will change the rounding mode of - "Float32". See "get_rounding" for available modes .. function:: with_rounding(f::Function, T, mode) - Change the rounding mode of floating point type "T" for the - duration of "f". It is logically equivalent to: + Change the rounding mode of floating point type "T" for the duration of "f". It is logically equivalent to: - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) + :: + + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) + + See "get_rounding" for available rounding modes. - See "get_rounding" for available rounding modes. Integers ~~~~~~~~ .. function:: count_ones(x::Integer) -> Integer - Number of ones in the binary representation of "x". + Number of ones in the binary representation of "x". + + :: + + julia> count_ones(7) + 3 - julia> count_ones(7) - 3 .. function:: count_zeros(x::Integer) -> Integer - Number of zeros in the binary representation of "x". + Number of zeros in the binary representation of "x". + + :: + + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 .. function:: leading_zeros(x::Integer) -> Integer - Number of zeros leading the binary representation of "x". + Number of zeros leading the binary representation of "x". + + :: + + julia> leading_zeros(Int32(1)) + 31 - julia> leading_zeros(Int32(1)) - 31 .. function:: leading_ones(x::Integer) -> Integer - Number of ones leading the binary representation of "x". + Number of ones leading the binary representation of "x". + + :: + + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 .. function:: trailing_zeros(x::Integer) -> Integer - Number of zeros trailing the binary representation of "x". + Number of zeros trailing the binary representation of "x". + + :: + + julia> trailing_zeros(2) + 1 - julia> trailing_zeros(2) - 1 .. function:: trailing_ones(x::Integer) -> Integer - Number of ones trailing the binary representation of "x". + Number of ones trailing the binary representation of "x". + + :: + + julia> trailing_ones(3) + 2 - julia> trailing_ones(3) - 2 .. function:: isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns "true" if "x" is prime; - and "false" if "x" is not prime with high probability. The - false positive rate is about "0.25^reps". "reps = 25" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). + Probabilistic primality test. Returns "true" if "x" is prime; and "false" if "x" is not prime with high probability. The false positive rate is about "0.25^reps". "reps = 25" is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + + :: + + julia> isprime(big(3)) + true - julia> isprime(big(3)) - true .. function:: isprime(x::BigInt[, reps = 25]) -> Bool - Probabilistic primality test. Returns "true" if "x" is prime; - and "false" if "x" is not prime with high probability. The - false positive rate is about "0.25^reps". "reps = 25" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). + Probabilistic primality test. Returns "true" if "x" is prime; and "false" if "x" is not prime with high probability. The false positive rate is about "0.25^reps". "reps = 25" is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). + + :: + + julia> isprime(big(3)) + true - julia> isprime(big(3)) - true .. function:: primes(n) - Returns a collection of the prime numbers <= "n". + Returns a collection of the prime numbers <= "n". + .. function:: isodd(x::Integer) -> Bool - Returns "true" if "x" is odd (that is, not divisible by 2), and - "false" otherwise. + Returns "true" if "x" is odd (that is, not divisible by 2), and "false" otherwise. + + :: + + julia> isodd(9) + true - julia> isodd(9) - true + julia> isodd(10) + false - julia> isodd(10) - false .. function:: iseven(x::Integer) -> Bool - Returns "true" is "x" is even (that is, divisible by 2), and - "false" otherwise. + Returns "true" is "x" is even (that is, divisible by 2), and "false" otherwise. + + :: + + julia> iseven(9) + false - julia> iseven(9) - false + julia> iseven(10) + true - julia> iseven(10) - true BigFloats --------- @@ -431,26 +442,30 @@ The `BigFloat` type implements arbitrary-precision floating-point arithmetic usi .. function:: precision(num::FloatingPoint) - Get the precision of a floating point number, as defined by the - effective number of bits in the mantissa. + Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. + .. function:: get_bigfloat_precision() - Get the precision (in bits) currently used for BigFloat arithmetic. + Get the precision (in bits) currently used for BigFloat arithmetic. + .. function:: set_bigfloat_precision(x::Int64) - Set the precision (in bits) to be used to BigFloat arithmetic. + Set the precision (in bits) to be used to BigFloat arithmetic. + .. function:: with_bigfloat_precision(f::Function, precision::Integer) - Change the BigFloat arithmetic precision (in bits) for the duration - of "f". It is logically equivalent to: + Change the BigFloat arithmetic precision (in bits) for the duration of "f". It is logically equivalent to: + + :: + + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) .. _random-numbers: @@ -473,68 +488,57 @@ As ``BigInt`` represents unbounded integers, the interval must be specified (e.g .. function:: srand([rng][, seed]) - Reseed the random number generator. If a "seed" is provided, the - RNG will give a reproducible sequence of numbers, otherwise Julia - will get entropy from the system. For "MersenneTwister", the - "seed" may be a non-negative integer, a vector of "UInt32" - integers or a filename, in which case the seed is read from a file. - "RandomDevice" does not support seeding. + Reseed the random number generator. If a "seed" is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. For "MersenneTwister", the "seed" may be a non-negative integer, a vector of "UInt32" integers or a filename, in which case the seed is read from a file. "RandomDevice" does not support seeding. + .. function:: MersenneTwister([seed]) - Create a "MersenneTwister" RNG object. Different RNG objects can - have their own seeds, which may be useful for generating different - streams of random numbers. + Create a "MersenneTwister" RNG object. Different RNG objects can have their own seeds, which may be useful for generating different streams of random numbers. + .. function:: RandomDevice() - Create a "RandomDevice" RNG object. Two such objects will always - generate different streams of random numbers. + Create a "RandomDevice" RNG object. Two such objects will always generate different streams of random numbers. + .. function:: rand([rng][, S][, dims...]) - Pick a random element or array of random elements from the set of - values specified by "S"; "S" can be + Pick a random element or array of random elements from the set of values specified by "S"; "S" can be - * an indexable collection (for example "1:n" or - "['x','y','z']"), or + * an indexable collection (for example "1:n" or "['x','y','z']"), or - * a type: the set of values to pick from is then equivalent to - "typemin(S):typemax(S)" for integers (this is not applicable to - "BigInt"), and to [0,1) for floating point numbers; + * a type: the set of values to pick from is then equivalent to "typemin(S):typemax(S)" for integers (this is not applicable to "BigInt"), and to [0,1) for floating point numbers; + + "S" defaults to "Float64". - "S" defaults to "Float64". .. function:: rand!([rng], A[, coll]) - Populate the array A with random values. If the indexable - collection "coll" is specified, the values are picked randomly - from "coll". This is equivalent to "copy!(A, rand(rng, coll, - size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but - without allocating a new array. + Populate the array A with random values. If the indexable collection "coll" is specified, the values are picked randomly from "coll". This is equivalent to "copy!(A, rand(rng, coll, size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but without allocating a new array. + .. function:: bitrand([rng][, dims...]) - Generate a "BitArray" of random boolean values. + Generate a "BitArray" of random boolean values. + .. function:: randn([rng][, dims...]) - Generate a normally-distributed random number with mean 0 and - standard deviation 1. Optionally generate an array of normally- - distributed random numbers. + Generate a normally-distributed random number with mean 0 and standard deviation 1. Optionally generate an array of normally- distributed random numbers. + .. function:: randn!([rng], A::Array{Float64, N}) - Fill the array A with normally-distributed (mean 0, standard - deviation 1) random numbers. Also see the rand function. + Fill the array A with normally-distributed (mean 0, standard deviation 1) random numbers. Also see the rand function. + .. function:: randexp([rng][, dims...]) - Generate a random number according to the exponential distribution - with scale 1. Optionally generate an array of such random numbers. + Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. + .. function:: randexp!([rng], A::Array{Float64, N}) - Fill the array A with random numbers following the exponential - distribution (with scale 1). + Fill the array A with random numbers following the exponential distribution (with scale 1). + diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 03a5844413af6..41d8f6a0f61c0 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -9,396 +9,341 @@ Tasks .. function:: Task(func) - Create a "Task" (i.e. thread, or coroutine) to execute the given - function (which must be callable with no arguments). The task exits - when this function returns. + Create a "Task" (i.e. thread, or coroutine) to execute the given function (which must be callable with no arguments). The task exits when this function returns. + .. function:: yieldto(task, arg = nothing) - Switch to the given task. The first time a task is switched to, the - task's function is called with no arguments. On subsequent - switches, "arg" is returned from the task's last call to - "yieldto". This is a low-level call that only switches tasks, not - considering states or scheduling in any way. Its use is - discouraged. + Switch to the given task. The first time a task is switched to, the task's function is called with no arguments. On subsequent switches, "arg" is returned from the task's last call to "yieldto". This is a low-level call that only switches tasks, not considering states or scheduling in any way. Its use is discouraged. + .. function:: current_task() - Get the currently running Task. + Get the currently running Task. + .. function:: istaskdone(task) -> Bool - Tell whether a task has exited. + Tell whether a task has exited. + .. function:: istaskstarted(task) -> Bool - Tell whether a task has started executing. + Tell whether a task has started executing. + .. function:: consume(task, values...) - Receive the next value passed to "produce" by the specified task. - Additional arguments may be passed, to be returned from the last - "produce" call in the producer. + Receive the next value passed to "produce" by the specified task. Additional arguments may be passed, to be returned from the last "produce" call in the producer. + .. function:: produce(value) - Send the given value to the last "consume" call, switching to the - consumer task. If the next "consume" call passes any values, they - are returned by "produce". + Send the given value to the last "consume" call, switching to the consumer task. If the next "consume" call passes any values, they are returned by "produce". + .. function:: yield() - Switch to the scheduler to allow another scheduled task to run. A - task that calls this function is still runnable, and will be - restarted immediately if there are no other runnable tasks. + Switch to the scheduler to allow another scheduled task to run. A task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. + .. function:: task_local_storage(body, symbol, value) - Call the function "body" with a modified task-local storage, in - which "value" is assigned to "symbol"; the previous value of - "symbol", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. + Call the function "body" with a modified task-local storage, in which "value" is assigned to "symbol"; the previous value of "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + .. function:: task_local_storage(body, symbol, value) - Call the function "body" with a modified task-local storage, in - which "value" is assigned to "symbol"; the previous value of - "symbol", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. + Call the function "body" with a modified task-local storage, in which "value" is assigned to "symbol"; the previous value of "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + .. function:: task_local_storage(body, symbol, value) - Call the function "body" with a modified task-local storage, in - which "value" is assigned to "symbol"; the previous value of - "symbol", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. + Call the function "body" with a modified task-local storage, in which "value" is assigned to "symbol"; the previous value of "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + .. function:: Condition() - Create an edge-triggered event source that tasks can wait for. - Tasks that call "wait" on a "Condition" are suspended and - queued. Tasks are woken up when "notify" is later called on the - "Condition". Edge triggering means that only tasks waiting at the - time "notify" is called can be woken up. For level-triggered - notifications, you must keep extra state to keep track of whether a - notification has happened. The "RemoteRef" type does this, and so - can be used for level-triggered events. + Create an edge-triggered event source that tasks can wait for. Tasks that call "wait" on a "Condition" are suspended and queued. Tasks are woken up when "notify" is later called on the "Condition". Edge triggering means that only tasks waiting at the time "notify" is called can be woken up. For level-triggered notifications, you must keep extra state to keep track of whether a notification has happened. The "RemoteRef" type does this, and so can be used for level-triggered events. + .. function:: notify(condition, val=nothing; all=true, error=false) - Wake up tasks waiting for a condition, passing them "val". If - "all" is true (the default), all waiting tasks are woken, - otherwise only one is. If "error" is true, the passed value is - raised as an exception in the woken tasks. + Wake up tasks waiting for a condition, passing them "val". If "all" is true (the default), all waiting tasks are woken, otherwise only one is. If "error" is true, the passed value is raised as an exception in the woken tasks. + .. function:: schedule(t::Task, [val]; error=false) - Add a task to the scheduler's queue. This causes the task to run - constantly when the system is otherwise idle, unless the task - performs a blocking operation such as "wait". + Add a task to the scheduler's queue. This causes the task to run constantly when the system is otherwise idle, unless the task performs a blocking operation such as "wait". + + If a second argument is provided, it will be passed to the task (via the return value of "yieldto") when it runs again. If "error" is true, the value is raised as an exception in the woken task. - If a second argument is provided, it will be passed to the task - (via the return value of "yieldto") when it runs again. If - "error" is true, the value is raised as an exception in the woken - task. .. function:: @schedule() - Wrap an expression in a Task and add it to the scheduler's queue. + Wrap an expression in a Task and add it to the scheduler's queue. + .. function:: @task() - Wrap an expression in a Task without executing it, and return the - Task. This only creates a task, and does not run it. + Wrap an expression in a Task without executing it, and return the Task. This only creates a task, and does not run it. + .. function:: sleep(seconds) - Block the current task for a specified number of seconds. The - minimum sleep time is 1 millisecond or input of "0.001". + Block the current task for a specified number of seconds. The minimum sleep time is 1 millisecond or input of "0.001". + .. function:: ReentrantLock() - Creates a reentrant lock. The same task can acquire the lock as - many times as required. Each lock must be matched with an unlock. + Creates a reentrant lock. The same task can acquire the lock as many times as required. Each lock must be matched with an unlock. + .. function:: lock(l::ReentrantLock) - Associates "l" with the current task. If "l" is already locked - by a different task, waits for it to become available. The same - task can acquire the lock multiple times. Each "lock" must be - matched by an "unlock" + Associates "l" with the current task. If "l" is already locked by a different task, waits for it to become available. The same task can acquire the lock multiple times. Each "lock" must be matched by an "unlock" + .. function:: unlock(l::ReentrantLock) - Releases ownership of the lock by the current task. If the lock had - been acquired before, it just decrements an internal counter and - returns immediately. + Releases ownership of the lock by the current task. If the lock had been acquired before, it just decrements an internal counter and returns immediately. + General Parallel Computing Support ---------------------------------- .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. + Launches worker processes via the specified cluster manager. - For example Beowulf clusters are supported via a custom cluster - manager implemented in package "ClusterManagers". + For example Beowulf clusters are supported via a custom cluster manager implemented in package "ClusterManagers". + + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - "JULIA_WORKER_TIMEOUT" in the worker process's environment. - Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster manager implemented in package "ClusterManagers". - For example Beowulf clusters are supported via a custom cluster - manager implemented in package "ClusterManagers". + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - "JULIA_WORKER_TIMEOUT" in the worker process's environment. - Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. + Launches worker processes via the specified cluster manager. - For example Beowulf clusters are supported via a custom cluster - manager implemented in package "ClusterManagers". + For example Beowulf clusters are supported via a custom cluster manager implemented in package "ClusterManagers". + + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - "JULIA_WORKER_TIMEOUT" in the worker process's environment. - Relevant only when using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Launches worker processes via the specified cluster manager. + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster manager implemented in package "ClusterManagers". - For example Beowulf clusters are supported via a custom cluster - manager implemented in package "ClusterManagers". + The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - "JULIA_WORKER_TIMEOUT" in the worker process's environment. - Relevant only when using TCP/IP as transport. .. function:: nprocs() - Get the number of available processes. + Get the number of available processes. + .. function:: nworkers() - Get the number of available worker processes. This is one less than - nprocs(). Equal to nprocs() if nprocs() == 1. + Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. + .. function:: procs(S::SharedArray) - Get the vector of processes that have mapped the shared array + Get the vector of processes that have mapped the shared array + .. function:: workers() - Returns a list of all worker process identifiers. + Returns a list of all worker process identifiers. + .. function:: rmprocs(pids...) - Removes the specified workers. + Removes the specified workers. + .. function:: interrupt([pids...]) - Interrupt the current executing task on the specified workers. This - is equivalent to pressing Ctrl-C on the local machine. If no - arguments are given, all workers are interrupted. + Interrupt the current executing task on the specified workers. This is equivalent to pressing Ctrl-C on the local machine. If no arguments are given, all workers are interrupted. + .. function:: myid() - Get the id of the current process. + Get the id of the current process. + .. function:: pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - Transform collections "lsts" by applying "f" to each element in - parallel. If "nprocs() > 1", the calling process will be - dedicated to assigning tasks. All other available processes will be - used as parallel workers, or on the processes specified by - "pids". + Transform collections "lsts" by applying "f" to each element in parallel. If "nprocs() > 1", the calling process will be dedicated to assigning tasks. All other available processes will be used as parallel workers, or on the processes specified by "pids". + + If "err_retry" is true, it retries a failed application of "f" on a different worker. If "err_stop" is true, it takes precedence over the value of "err_retry" and "pmap" stops execution on the first error. - If "err_retry" is true, it retries a failed application of "f" - on a different worker. If "err_stop" is true, it takes precedence - over the value of "err_retry" and "pmap" stops execution on the - first error. .. function:: remotecall(id, func, args...) - Call a function asynchronously on the given arguments on the - specified process. Returns a "RemoteRef". + Call a function asynchronously on the given arguments on the specified process. Returns a "RemoteRef". + .. function:: wait([x]) - Block the current task until some event occurs, depending on the - type of the argument: + Block the current task until some event occurs, depending on the type of the argument: + + * "RemoteRef": Wait for a value to become available for the specified remote reference. - * "RemoteRef": Wait for a value to become available for the - specified remote reference. + * "Condition": Wait for "notify" on a condition. - * "Condition": Wait for "notify" on a condition. + * "Process": Wait for a process or process chain to exit. The "exitcode" field of a process can be used to determine success or failure. - * "Process": Wait for a process or process chain to exit. The - "exitcode" field of a process can be used to determine success - or failure. + * "Task": Wait for a "Task" to finish, returning its result value. If the task fails with an exception, the exception is propagated (re-thrown in the task that called "wait"). - * "Task": Wait for a "Task" to finish, returning its result - value. If the task fails with an exception, the exception is - propagated (re-thrown in the task that called "wait"). + * "RawFD": Wait for changes on a file descriptor (see *poll_fd* for keyword arguments and return code) - * "RawFD": Wait for changes on a file descriptor (see *poll_fd* - for keyword arguments and return code) + If no argument is passed, the task blocks for an undefined period. If the task's state is set to ":waiting", it can only be restarted by an explicit call to "schedule" or "yieldto". If the task's state is ":runnable", it might be restarted unpredictably. - If no argument is passed, the task blocks for an undefined period. - If the task's state is set to ":waiting", it can only be - restarted by an explicit call to "schedule" or "yieldto". If - the task's state is ":runnable", it might be restarted - unpredictably. + Often "wait" is called within a "while" loop to ensure a waited-for condition is met before proceeding. - Often "wait" is called within a "while" loop to ensure a - waited-for condition is met before proceeding. .. function:: fetch(RemoteRef) - Wait for and get the value of a remote reference. + Wait for and get the value of a remote reference. + .. function:: remotecall_wait(id, func, args...) - Perform "wait(remotecall(...))" in one message. + Perform "wait(remotecall(...))" in one message. + .. function:: remotecall_fetch(id, func, args...) - Perform "fetch(remotecall(...))" in one message. + Perform "fetch(remotecall(...))" in one message. + .. function:: put!(RemoteRef, value) - Store a value to a remote reference. Implements "shared queue of - length 1" semantics: if a value is already present, blocks until - the value is removed with "take!". Returns its first argument. + Store a value to a remote reference. Implements "shared queue of length 1" semantics: if a value is already present, blocks until the value is removed with "take!". Returns its first argument. + .. function:: take!(RemoteRef) - Fetch the value of a remote reference, removing it so that the - reference is empty again. + Fetch the value of a remote reference, removing it so that the reference is empty again. + .. function:: isready(r::RemoteRef) - Determine whether a "RemoteRef" has a value stored to it. Note - that this function can cause race conditions, since by the time you - receive its result it may no longer be true. It is recommended that - this function only be used on a "RemoteRef" that is assigned - once. + Determine whether a "RemoteRef" has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. It is recommended that this function only be used on a "RemoteRef" that is assigned once. + + If the argument "RemoteRef" is owned by a different node, this call will block to wait for the answer. It is recommended to wait for "r" in a separate task instead, or to use a local "RemoteRef" as a proxy: - If the argument "RemoteRef" is owned by a different node, this - call will block to wait for the answer. It is recommended to wait - for "r" in a separate task instead, or to use a local - "RemoteRef" as a proxy: + :: + + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block .. function:: RemoteRef(n) - Make an uninitialized remote reference on process "n". + Make an uninitialized remote reference on process "n". + .. function:: RemoteRef(n) - Make an uninitialized remote reference on process "n". + Make an uninitialized remote reference on process "n". + .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - Waits till "testcb" returns "true" or for "secs`" seconds, - whichever is earlier. "testcb" is polled every "pollint" - seconds. + Waits till "testcb" returns "true" or for "secs`" seconds, whichever is earlier. "testcb" is polled every "pollint" seconds. + .. function:: @spawn() - Execute an expression on an automatically-chosen process, returning - a "RemoteRef" to the result. + Execute an expression on an automatically-chosen process, returning a "RemoteRef" to the result. + .. function:: @spawnat() - Accepts two arguments, "p" and an expression, and runs the - expression asynchronously on process "p", returning a - "RemoteRef" to the result. + Accepts two arguments, "p" and an expression, and runs the expression asynchronously on process "p", returning a "RemoteRef" to the result. + .. function:: @fetch() - Equivalent to "fetch(@spawn expr)". + Equivalent to "fetch(@spawn expr)". + .. function:: @fetchfrom() - Equivalent to "fetch(@spawnat p expr)". + Equivalent to "fetch(@spawnat p expr)". + .. function:: @async() - Schedule an expression to run on the local machine, also adding it - to the set of items that the nearest enclosing "@sync" waits for. + Schedule an expression to run on the local machine, also adding it to the set of items that the nearest enclosing "@sync" waits for. + .. function:: @sync() - Wait until all dynamically-enclosed uses of "@async", "@spawn", - "@spawnat" and "@parallel" are complete. + Wait until all dynamically-enclosed uses of "@async", "@spawn", "@spawnat" and "@parallel" are complete. + .. function:: @parallel() - A parallel for loop of the form + A parallel for loop of the form + + :: + + @parallel [reducer] for var = range + body + end - @parallel [reducer] for var = range - body - end + The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, @parallel performs local reductions on each worker with a final reduction on the calling process. - The specified range is partitioned and locally executed across all - workers. In case an optional reducer function is specified, - @parallel performs local reductions on each worker with a final - reduction on the calling process. + Note that without a reducer function, @parallel executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with "@sync", like - Note that without a reducer function, @parallel executes - asynchronously, i.e. it spawns independent tasks on all available - workers and returns immediately without waiting for completion. To - wait for completion, prefix the call with "@sync", like + :: + + @sync @parallel for var = range + body + end - @sync @parallel for var = range - body - end Shared Arrays (Experimental, UNIX-only feature) ----------------------------------------------- .. function:: SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - Construct a SharedArray of a bitstype "T" and size "dims" - across the processes specified by "pids" - all of which have to - be on the same host. + Construct a SharedArray of a bitstype "T" and size "dims" across the processes specified by "pids" - all of which have to be on the same host. + + If "pids" is left unspecified, the shared array will be mapped across all processes on the current host, including the master. But, "localindexes" and "indexpids" will only refer to worker processes. This facilitates work distribution code to use workers for actual computation with the master process acting as a driver. - If "pids" is left unspecified, the shared array will be mapped - across all processes on the current host, including the master. - But, "localindexes" and "indexpids" will only refer to worker - processes. This facilitates work distribution code to use workers - for actual computation with the master process acting as a driver. + If an "init" function of the type "initfn(S::SharedArray)" is specified, it is called on all the participating workers. - If an "init" function of the type "initfn(S::SharedArray)" is - specified, it is called on all the participating workers. .. function:: procs(S::SharedArray) - Get the vector of processes that have mapped the shared array + Get the vector of processes that have mapped the shared array + .. function:: sdata(S::SharedArray) - Returns the actual "Array" object backing "S" + Returns the actual "Array" object backing "S" + .. function:: indexpids(S::SharedArray) - Returns the index of the current worker into the "pids" vector, - i.e., the list of workers mapping the SharedArray + Returns the index of the current worker into the "pids" vector, i.e., the list of workers mapping the SharedArray + Cluster Manager Interface ------------------------- @@ -409,54 +354,39 @@ Cluster Manager Interface .. function:: launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - Implemented by cluster managers. For every Julia worker launched by - this function, it should append a "WorkerConfig" entry to - "launched" and notify "launch_ntfy". The function MUST exit - once all workers, requested by "manager" have been launched. - "params" is a dictionary of all keyword arguments "addprocs" - was called with. + Implemented by cluster managers. For every Julia worker launched by this function, it should append a "WorkerConfig" entry to "launched" and notify "launch_ntfy". The function MUST exit once all workers, requested by "manager" have been launched. "params" is a dictionary of all keyword arguments "addprocs" was called with. + .. function:: manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - Implemented by cluster managers. It is called on the master - process, during a worker's lifetime, with appropriate "op" - values: + Implemented by cluster managers. It is called on the master process, during a worker's lifetime, with appropriate "op" values: + + :: + + * with ":register"/":deregister" when a worker is added / + removed from the Julia worker pool. - * with ":register"/":deregister" when a worker is added / - removed from the Julia worker pool. + * with ":interrupt" when "interrupt(workers)" is called. + The "ClusterManager" should signal the appropriate worker + with an interrupt signal. - * with ":interrupt" when "interrupt(workers)" is called. - The "ClusterManager" should signal the appropriate worker - with an interrupt signal. + * with ":finalize" for cleanup purposes. - * with ":finalize" for cleanup purposes. .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master - process, by "rmprocs". It should cause the remote worker - specified by "pid" to exit. - "Base.kill(manager::ClusterManager.....)" executes a remote - "exit()" on "pid" + Implemented by cluster managers. It is called on the master process, by "rmprocs". It should cause the remote worker specified by "pid" to exit. "Base.kill(manager::ClusterManager.....)" executes a remote "exit()" on "pid" + .. function:: init_worker(manager::FooManager) - Called by cluster managers implementing custom transports. It - initializes a newly launched process as a worker. Command line - argument "--worker" has the effect of initializing a process as a - worker using TCP/IP sockets for transport. + Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument "–worker" has the effect of initializing a process as a worker using TCP/IP sockets for transport. + .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id "pid", specified - by "config" and return a pair of "AsyncStream" objects. - Messages from "pid" to current process will be read off - "instrm", while messages to be sent to "pid" will be written to - "outstrm". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - "Base.connect(manager::ClusterManager.....)" sets up TCP/IP - socket connections in-between workers. + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id "pid", specified by "config" and return a pair of "AsyncStream" objects. Messages from "pid" to current process will be read off "instrm", while messages to be sent to "pid" will be written to "outstrm". The custom transport implementation must ensure that messages are delivered and received completely and in order. "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. + .. function:: Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index 63bb29c76e59f..0f956463e9cfc 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -9,177 +9,138 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, .. function:: dir(names...) -> AbstractString - Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, "Pkg.dir(pkg)" returns the path to - the package "pkg". + Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, "Pkg.dir(pkg)" returns the path to the package "pkg". + .. function:: dir(names...) -> AbstractString - Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, "Pkg.dir(pkg)" returns the path to - the package "pkg". + Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, "Pkg.dir(pkg)" returns the path to the package "pkg". + .. function:: init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - Initialize "Pkg.dir()" as a package directory. This will be done - automatically when the "JULIA_PKGDIR" is not set and - "Pkg.dir()" uses its default value. As part of this process, - clones a local METADATA git repository from the site and branch - specified by its arguments, which are typically not provided. - Explicit (non-default) arguments can be used to support a custom - METADATA setup. + Initialize "Pkg.dir()" as a package directory. This will be done automatically when the "JULIA_PKGDIR" is not set and "Pkg.dir()" uses its default value. As part of this process, clones a local METADATA git repository from the site and branch specified by its arguments, which are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. + .. function:: resolve() - Determines an optimal, consistent set of package versions to - install or upgrade to. The optimal set of package versions is based - on the contents of "Pkg.dir("REQUIRE")" and the state of - installed packages in "Pkg.dir()", Packages that are no longer - required are moved into "Pkg.dir(".trash")". + Determines an optimal, consistent set of package versions to install or upgrade to. The optimal set of package versions is based on the contents of "Pkg.dir("REQUIRE")" and the state of installed packages in "Pkg.dir()", Packages that are no longer required are moved into "Pkg.dir(".trash")". + .. function:: edit() - Opens "Pkg.dir("REQUIRE")" in the editor specified by the - "VISUAL" or "EDITOR" environment variables; when the editor - command returns, it runs "Pkg.resolve()" to determine and install - a new optimal set of installed package versions. + Opens "Pkg.dir("REQUIRE")" in the editor specified by the "VISUAL" or "EDITOR" environment variables; when the editor command returns, it runs "Pkg.resolve()" to determine and install a new optimal set of installed package versions. + .. function:: add(pkg, vers...) - Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and - call "Pkg.resolve()". If "vers" are given, they must be - "VersionNumber" objects and they specify acceptable version - intervals for "pkg". + Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". If "vers" are given, they must be "VersionNumber" objects and they specify acceptable version intervals for "pkg". + .. function:: rm(pkg) - Remove all requirement entries for "pkg" from - "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". + Remove all requirement entries for "pkg" from "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". + .. function:: clone(pkg) - If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone - it from that URL on the default branch. The package does not need - to have any registered versions. + If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone it from that URL on the default branch. The package does not need to have any registered versions. + .. function:: clone(pkg) - If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone - it from that URL on the default branch. The package does not need - to have any registered versions. + If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone it from that URL on the default branch. The package does not need to have any registered versions. + .. function:: available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package "pkg". + Returns the version numbers available for package "pkg". + .. function:: available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package "pkg". + Returns the version numbers available for package "pkg". + .. function:: installed(pkg) -> Void | VersionNumber - If "pkg" is installed, return the installed version number, - otherwise return "nothing". + If "pkg" is installed, return the installed version number, otherwise return "nothing". + .. function:: installed(pkg) -> Void | VersionNumber - If "pkg" is installed, return the installed version number, - otherwise return "nothing". + If "pkg" is installed, return the installed version number, otherwise return "nothing". + .. function:: status() - Prints out a summary of what packages are installed and what - version and state they're in. + Prints out a summary of what packages are installed and what version and state they're in. + .. function:: update() - Update package the metadata repo – kept in - "Pkg.dir("METADATA")" – then update any fixed packages that can - safely be pulled from their origin; then call "Pkg.resolve()" to - determine a new optimal set of packages versions. + Update package the metadata repo – kept in "Pkg.dir("METADATA")" – then update any fixed packages that can safely be pulled from their origin; then call "Pkg.resolve()" to determine a new optimal set of packages versions. + .. function:: checkout(pkg[, branch="master"]) - Checkout the "Pkg.dir(pkg)" repo to the branch "branch". - Defaults to checking out the "master" branch. To go back to using - the newest compatible released version, use "Pkg.free(pkg)" + Checkout the "Pkg.dir(pkg)" repo to the branch "branch". Defaults to checking out the "master" branch. To go back to using the newest compatible released version, use "Pkg.free(pkg)" + .. function:: pin(pkg, version) - Pin "pkg" at registered version "version". + Pin "pkg" at registered version "version". + .. function:: pin(pkg, version) - Pin "pkg" at registered version "version". + Pin "pkg" at registered version "version". + .. function:: free(pkg) - Free the package "pkg" to be managed by the package manager - again. It calls "Pkg.resolve()" to determine optimal package - versions after. This is an inverse for both "Pkg.checkout" and - "Pkg.pin". + Free the package "pkg" to be managed by the package manager again. It calls "Pkg.resolve()" to determine optimal package versions after. This is an inverse for both "Pkg.checkout" and "Pkg.pin". + + You can also supply an iterable collection of package names, e.g., "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at once. - You can also supply an iterable collection of package names, e.g., - "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at - once. .. function:: build(pkgs...) - Run the build script in "deps/build.jl" for each package in - "pkgs" and all of their dependencies in depth-first recursive - order. This is called automatically by "Pkg.resolve()" on all - installed or updated packages. + Run the build script in "deps/build.jl" for each package in "pkgs" and all of their dependencies in depth-first recursive order. This is called automatically by "Pkg.resolve()" on all installed or updated packages. + .. function:: build(pkgs...) - Run the build script in "deps/build.jl" for each package in - "pkgs" and all of their dependencies in depth-first recursive - order. This is called automatically by "Pkg.resolve()" on all - installed or updated packages. + Run the build script in "deps/build.jl" for each package in "pkgs" and all of their dependencies in depth-first recursive order. This is called automatically by "Pkg.resolve()" on all installed or updated packages. + .. function:: generate(pkg, license) - Generate a new package named "pkg" with one of these license - keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make - a package with a different license, you can edit it afterwards. - Generate creates a git repo at "Pkg.dir(pkg)" for the package and - inside it "LICENSE.md", "README.md", the julia entrypoint - "\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". + Generate a new package named "pkg" with one of these license keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make a package with a different license, you can edit it afterwards. Generate creates a git repo at "Pkg.dir(pkg)" for the package and inside it "LICENSE.md", "README.md", the julia entrypoint "$pkg/src/$pkg.jl", and a travis test file, ".travis.yml". + .. function:: register(pkg[, url]) - Register "pkg" at the git URL "url", defaulting to the - configured origin URL of the git repo "Pkg.dir(pkg)". + Register "pkg" at the git URL "url", defaulting to the configured origin URL of the git repo "Pkg.dir(pkg)". + .. function:: tag(pkg[, ver[, commit]]) - Tag "commit" as version "ver" of package "pkg" and create a - version entry in "METADATA". If not provided, "commit" defaults - to the current commit of the "pkg" repo. If "ver" is one of the - symbols ":patch", ":minor", ":major" the next patch, minor or - major version is used. If "ver" is not provided, it defaults to - ":patch". + Tag "commit" as version "ver" of package "pkg" and create a version entry in "METADATA". If not provided, "commit" defaults to the current commit of the "pkg" repo. If "ver" is one of the symbols ":patch", ":minor", ":major" the next patch, minor or major version is used. If "ver" is not provided, it defaults to ":patch". + .. function:: publish() - For each new package version tagged in "METADATA" not already - published, make sure that the tagged package commits have been - pushed to the repo at the registered URL for the package and if - they all have, open a pull request to "METADATA". + For each new package version tagged in "METADATA" not already published, make sure that the tagged package commits have been pushed to the repo at the registered URL for the package and if they all have, open a pull request to "METADATA". + .. function:: test(pkgs...) - Run the tests for each package in "pkgs" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its "test/runtests.jl" file - and test dependencies are specified in "test/REQUIRE". + Run the tests for each package in "pkgs" ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its "test/runtests.jl" file and test dependencies are specified in "test/REQUIRE". + .. function:: test(pkgs...) - Run the tests for each package in "pkgs" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its "test/runtests.jl" file - and test dependencies are specified in "test/REQUIRE". + Run the tests for each package in "pkgs" ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its "test/runtests.jl" file and test dependencies are specified in "test/REQUIRE". + diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 517c1cddaae03..0e6e6612f998f 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -10,76 +10,49 @@ .. function:: @profile() - "@profile " runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. + "@profile " runs your expression while taking periodic backtraces. These are appended to an internal buffer of backtraces. + .. currentmodule:: Base.Profile The methods in :mod:`Base.Profile` are not exported and need to be called e.g. as ``Profile.print()``. .. function:: clear() - Clear any existing backtraces from the internal buffer. + Clear any existing backtraces from the internal buffer. + .. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to "io". This variant is used to examine - results exported by a previous call to "retrieve()". Supply the - vector "data" of backtraces and a dictionary "lidict" of line - information. + Prints profiling results to "io". This variant is used to examine results exported by a previous call to "retrieve()". Supply the vector "data" of backtraces and a dictionary "lidict" of line information. + .. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to "io". This variant is used to examine - results exported by a previous call to "retrieve()". Supply the - vector "data" of backtraces and a dictionary "lidict" of line - information. + Prints profiling results to "io". This variant is used to examine results exported by a previous call to "retrieve()". Supply the vector "data" of backtraces and a dictionary "lidict" of line information. + .. function:: init(; n::Integer, delay::Float64) - Configure the "delay" between backtraces (measured in seconds), - and the number "n" of instruction pointers that may be stored. - Each instruction pointer corresponds to a single line of code; - backtraces generally consist of a long list of instruction - pointers. Default settings can be obtained by calling this function - with no arguments, and each can be set independently using keywords - or in the order "(n, delay)". + Configure the "delay" between backtraces (measured in seconds), and the number "n" of instruction pointers that may be stored. Each instruction pointer corresponds to a single line of code; backtraces generally consist of a long list of instruction pointers. Default settings can be obtained by calling this function with no arguments, and each can be set independently using keywords or in the order "(n, delay)". + .. function:: fetch() -> data - Returns a reference to the internal buffer of backtraces. Note that - subsequent operations, like "clear()", can affect "data" unless - you first make a copy. Note that the values in "data" have - meaning only on this machine in the current session, because it - depends on the exact memory addresses used in JIT-compiling. This - function is primarily for internal use; "retrieve()" may be a - better choice for most users. + Returns a reference to the internal buffer of backtraces. Note that subsequent operations, like "clear()", can affect "data" unless you first make a copy. Note that the values in "data" have meaning only on this machine in the current session, because it depends on the exact memory addresses used in JIT-compiling. This function is primarily for internal use; "retrieve()" may be a better choice for most users. + .. function:: retrieve() -> data, lidict - "Exports" profiling results in a portable format, returning the - set of all backtraces ("data") and a dictionary that maps the - (session-specific) instruction pointers in "data" to "LineInfo" - values that store the file name, function name, and line number. - This function allows you to save profiling results for future - analysis. + "Exports" profiling results in a portable format, returning the set of all backtraces ("data") and a dictionary that maps the (session-specific) instruction pointers in "data" to "LineInfo" values that store the file name, function name, and line number. This function allows you to save profiling results for future analysis. + .. function:: callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - Given a previous profiling run, determine who called a particular - function. Supplying the filename (and optionally, range of line - numbers over which the function is defined) allows you to - disambiguate an overloaded method. The returned value is a vector - containing a count of the number of calls and line information - about the caller. One can optionally supply backtrace data - obtained from "retrieve()"; otherwise, the current internal - profile buffer is used. + Given a previous profiling run, determine who called a particular function. Supplying the filename (and optionally, range of line numbers over which the function is defined) allows you to disambiguate an overloaded method. The returned value is a vector containing a count of the number of calls and line information about the caller. One can optionally supply backtrace data obtained from "retrieve()"; otherwise, the current internal profile buffer is used. + .. function:: clear_malloc_data() - Clears any stored memory allocation data when running julia with " - --track-allocation". Execute the command(s) you want to test (to - force JIT-compilation), then call "clear_malloc_data()". Then - execute your command(s) again, quit Julia, and examine the - resulting "*.mem" files. + Clears any stored memory allocation data when running julia with " –track-allocation". Execute the command(s) you want to test (to force JIT-compilation), then call "clear_malloc_data()". Then execute your command(s) again, quit Julia, and examine the resulting "*.mem" files. + diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 5f6c96b57edeb..05a22e2479be7 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -119,103 +119,75 @@ Sorting Functions .. function:: sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the vector "v" in place. "QuickSort" is used by default - for numeric arrays while "MergeSort" is used for other arrays. - You can specify an algorithm to use via the "alg" keyword (see - Sorting Algorithms for available algorithms). The "by" keyword - lets you provide a function that will be applied to each element - before comparison; the "lt" keyword allows providing a custom - "less than" function; use "rev=true" to reverse the sorting - order. These options are independent and can be used together in - all possible combinations: if both "by" and "lt" are specified, - the "lt" function is applied to the result of the "by" - function; "rev=true" reverses whatever ordering specified via the - "by" and "lt" keywords. + Sort the vector "v" in place. "QuickSort" is used by default for numeric arrays while "MergeSort" is used for other arrays. You can specify an algorithm to use via the "alg" keyword (see Sorting Algorithms for available algorithms). The "by" keyword lets you provide a function that will be applied to each element before comparison; the "lt" keyword allows providing a custom "less than" function; use "rev=true" to reverse the sorting order. These options are independent and can be used together in all possible combinations: if both "by" and "lt" are specified, the "lt" function is applied to the result of the "by" function; "rev=true" reverses whatever ordering specified via the "by" and "lt" keywords. + .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array "A" along the given dimension. + Sort a multidimensional array "A" along the given dimension. + .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Sort a multidimensional array "A" along the given dimension. + Sort a multidimensional array "A" along the given dimension. + .. function:: sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - Return a permutation vector of indices of "v" that puts it in - sorted order. Specify "alg" to choose a particular sorting - algorithm (see Sorting Algorithms). "MergeSort" is used by - default, and since it is stable, the resulting permutation will be - the lexicographically first one that puts the input array into - sorted order – i.e. indices of equal elements appear in ascending - order. If you choose a non-stable sorting algorithm such as - "QuickSort", a different permutation that puts the array into - order may be returned. The order is specified using the same - keywords as "sort!". + Return a permutation vector of indices of "v" that puts it in sorted order. Specify "alg" to choose a particular sorting algorithm (see Sorting Algorithms). "MergeSort" is used by default, and since it is stable, the resulting permutation will be the lexicographically first one that puts the input array into sorted order – i.e. indices of equal elements appear in ascending order. If you choose a non-stable sorting algorithm such as "QuickSort", a different permutation that puts the array into order may be returned. The order is specified using the same keywords as "sort!". + + See also "sortperm!()" - See also "sortperm!()" .. function:: sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - Like "sortperm", but accepts a preallocated index vector "ix". - If "initialized" is "false" (the default), ix is initialized to - contain the values "1:length(v)". + Like "sortperm", but accepts a preallocated index vector "ix". If "initialized" is "false" (the default), ix is initialized to contain the values "1:length(v)". + + See also "sortperm()" - See also "sortperm()" .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the rows of matrix "A" lexicographically. + Sort the rows of matrix "A" lexicographically. + .. function:: sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the columns of matrix "A" lexicographically. + Sort the columns of matrix "A" lexicographically. + Order-Related Functions ----------------------- .. function:: issorted(v, [by=,] [lt=,] [rev=false]) - Test whether a vector is in sorted order. The "by", "lt" and - "rev" keywords modify what order is considered to be sorted just - as they do for "sort". + Test whether a vector is in sorted order. The "by", "lt" and "rev" keywords modify what order is considered to be sorted just as they do for "sort". + .. function:: searchsorted(a, x, [by=,] [lt=,] [rev=false]) - Returns the range of indices of "a" which compare as equal to - "x" according to the order specified by the "by", "lt" and - "rev" keywords, assuming that "a" is already sorted in that - order. Returns an empty range located at the insertion point if - "a" does not contain values equal to "x". + Returns the range of indices of "a" which compare as equal to "x" according to the order specified by the "by", "lt" and "rev" keywords, assuming that "a" is already sorted in that order. Returns an empty range located at the insertion point if "a" does not contain values equal to "x". + .. function:: searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the first value in "a" greater than or equal - to "x", according to the specified order. Returns "length(a)+1" - if "x" is greater than all values in "a". + Returns the index of the first value in "a" greater than or equal to "x", according to the specified order. Returns "length(a)+1" if "x" is greater than all values in "a". + .. function:: searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - Returns the index of the last value in "a" less than or equal to - "x", according to the specified order. Returns "0" if "x" is - less than all values in "a". + Returns the index of the last value in "a" less than or equal to "x", according to the specified order. Returns "0" if "x" is less than all values in "a". + .. function:: select!(v, k, [by=,] [lt=,] [rev=false]) - Partially sort the vector "v" in place, according to the order - specified by "by", "lt" and "rev" so that the value at index - "k" (or range of adjacent values if "k" is a range) occurs at - the position where it would appear if the array were fully sorted - via a non-stable algorithm. If "k" is a single index, that value - is returned; if "k" is a range, an array of values at those - indices is returned. Note that "select!" does not fully sort the - input array. + Partially sort the vector "v" in place, according to the order specified by "by", "lt" and "rev" so that the value at index "k" (or range of adjacent values if "k" is a range) occurs at the position where it would appear if the array were fully sorted via a non-stable algorithm. If "k" is a single index, that value is returned; if "k" is a range, an array of values at those indices is returned. Note that "select!" does not fully sort the input array. + .. function:: select(v, k, [by=,] [lt=,] [rev=false]) - Variant of "select!" which copies "v" before partially sorting - it, thereby returning the same thing as "select!" but leaving - "v" unmodified. + Variant of "select!" which copies "v" before partially sorting it, thereby returning the same thing as "select!" but leaving "v" unmodified. + Sorting Algorithms ------------------ diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index 06a5104e0c3fc..a9f1bdecf47f1 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,487 +6,414 @@ .. function:: length(s) - The number of characters in string "s". + The number of characters in string "s". + .. function:: sizeof(s::AbstractString) - The number of bytes in string "s". + The number of bytes in string "s". + .. function:: *(s, t) - Concatenate strings. The "*" operator is an alias to this - function. + Concatenate strings. The "*" operator is an alias to this function. + + :: + + julia> "Hello " * "world" + "Hello world" - julia> "Hello " * "world" - "Hello world" julia> "Hello " * "world" "Hello world" .. function:: ^(s, n) - Repeat "n" times the string "s". The "^" operator is an alias - to this function. + Repeat "n" times the string "s". The "^" operator is an alias to this function. + + :: + + julia> "Test "^3 + "Test Test Test " - julia> "Test "^3 - "Test Test Test " .. function:: string(xs...) - Create a string from any values using the "print" function. + Create a string from any values using the "print" function. + .. function:: repr(x) - Create a string from any value using the "showall" function. + Create a string from any value using the "showall" function. + .. function:: bytestring(s) - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. + Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. + .. function:: bytestring(s) - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. + Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. + .. function:: ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + .. function:: ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + .. function:: ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If "length" is specified, the string does not have to be - 0-terminated. + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + .. function:: utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: utf8(s) - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: normalize_string(s, normalform::Symbol) - Normalize the string "s" according to one of the four "normal - forms" of the Unicode standard: "normalform" can be ":NFC", - ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical - composition) and D (canonical decomposition) convert different - visually identical representations of the same abstract string into - a single canonical form, with form C being more compact. Normal - forms KC and KD additionally canonicalize "compatibility - equivalents": they convert characters that are abstractly similar - but visually distinct into a single canonical choice (e.g. they - expand ligatures into the individual characters), with form KC - being more compact. + Normalize the string "s" according to one of the four "normal forms" of the Unicode standard: "normalform" can be ":NFC", ":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical composition) and D (canonical decomposition) convert different visually identical representations of the same abstract string into a single canonical form, with form C being more compact. Normal forms KC and KD additionally canonicalize "compatibility equivalents": they convert characters that are abstractly similar but visually distinct into a single canonical choice (e.g. they expand ligatures into the individual characters), with form KC being more compact. + + Alternatively, finer control and additional transformations may be be obtained by calling *normalize_string(s; keywords...)*, where any number of the following boolean keywords options (which all default to "false" except for "compose") are specified: - Alternatively, finer control and additional transformations may be - be obtained by calling *normalize_string(s; keywords...)*, where - any number of the following boolean keywords options (which all - default to "false" except for "compose") are specified: + * "compose=false": do not perform canonical composition - * "compose=false": do not perform canonical composition + * "decompose=true": do canonical decomposition instead of canonical composition ("compose=true" is ignored if present) - * "decompose=true": do canonical decomposition instead of - canonical composition ("compose=true" is ignored if present) + * "compat=true": compatibility equivalents are canonicalized - * "compat=true": compatibility equivalents are canonicalized + * "casefold=true": perform Unicode case folding, e.g. for case- insensitive string comparison - * "casefold=true": perform Unicode case folding, e.g. for case- - insensitive string comparison + * "newline2lf=true", "newline2ls=true", or "newline2ps=true": convert various newline sequences (LF, CRLF, CR, NEL) into a linefeed (LF), line-separation (LS), or paragraph-separation (PS) character, respectively - * "newline2lf=true", "newline2ls=true", or - "newline2ps=true": convert various newline sequences (LF, CRLF, - CR, NEL) into a linefeed (LF), line-separation (LS), or - paragraph-separation (PS) character, respectively + * "stripmark=true": strip diacritical marks (e.g. accents) - * "stripmark=true": strip diacritical marks (e.g. accents) + * "stripignore=true": strip Unicode's "default ignorable" characters (e.g. the soft hyphen or the left-to-right marker) - * "stripignore=true": strip Unicode's "default ignorable" - characters (e.g. the soft hyphen or the left-to-right marker) + * "stripcc=true": strip control characters; horizontal tabs and form feeds are converted to spaces; newlines are also converted to spaces unless a newline-conversion flag was specified - * "stripcc=true": strip control characters; horizontal tabs and - form feeds are converted to spaces; newlines are also converted - to spaces unless a newline-conversion flag was specified + * "rejectna=true": throw an error if unassigned code points are found - * "rejectna=true": throw an error if unassigned code points are - found + * "stable=true": enforce Unicode Versioning Stability - * "stable=true": enforce Unicode Versioning Stability + For example, NFKC corresponds to the options "compose=true, compat=true, stable=true". - For example, NFKC corresponds to the options "compose=true, - compat=true, stable=true". .. function:: graphemes(s) -> iterator over substrings of s - Returns an iterator over substrings of "s" that correspond to the - extended graphemes in the string, as defined by Unicode UAX #29. - (Roughly, these are what users would perceive as single characters, - even though they may contain more than one codepoint; for example a - letter combined with an accent mark is a single grapheme.) + Returns an iterator over substrings of "s" that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. (Roughly, these are what users would perceive as single characters, even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) + .. function:: isvalid(str, i) - Tells whether index "i" is valid for the given string + Tells whether index "i" is valid for the given string + .. function:: isvalid(str, i) - Tells whether index "i" is valid for the given string + Tells whether index "i" is valid for the given string + .. function:: is_assigned_char(c) -> Bool - Returns true if the given char or integer is an assigned Unicode - code point. + Returns true if the given char or integer is an assigned Unicode code point. + .. function:: ismatch(r::Regex, s::AbstractString) -> Bool - Test whether a string contains a match of the given regular - expression. + Test whether a string contains a match of the given regular expression. + .. function:: match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - Search for the first match of the regular expression "r" in "s" - and return a RegexMatch object containing the match, or nothing if - the match failed. The matching substring can be retrieved by - accessing "m.match" and the captured sequences can be retrieved - by accessing "m.captures" The optional "idx" argument specifies - an index at which to start the search. + Search for the first match of the regular expression "r" in "s" and return a RegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessing "m.match" and the captured sequences can be retrieved by accessing "m.captures" The optional "idx" argument specifies an index at which to start the search. + .. function:: eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - Search for all matches of a the regular expression "r" in "s" - and return a iterator over the matches. If overlap is true, the - matching sequences are allowed to overlap indices in the original - string, otherwise they must be from distinct character ranges. + Search for all matches of a the regular expression "r" in "s" and return a iterator over the matches. If overlap is true, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges. + .. function:: matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - Return a vector of the matching substrings from eachmatch. + Return a vector of the matching substrings from eachmatch. + .. function:: lpad(string, n, p) - Make a string at least "n" columns wide when printed, by padding - on the left with copies of "p". + Make a string at least "n" columns wide when printed, by padding on the left with copies of "p". + .. function:: rpad(string, n, p) - Make a string at least "n" columns wide when printed, by padding - on the right with copies of "p". + Make a string at least "n" columns wide when printed, by padding on the right with copies of "p". + .. function:: search(string, chars[, start]) - Search for the first occurrence of the given characters within the - given string. The second argument may be a single character, a - vector or a set of characters, a string, or a regular expression - (though regular expressions are only allowed on contiguous strings, - such as ASCII or UTF-8 strings). The third argument optionally - specifies a starting index. The return value is a range of indexes - where the matching sequence is found, such that "s[search(s,x)] == - x": + Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression (though regular expressions are only allowed on contiguous strings, such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that "s[search(s,x)] == x": - "search(string, "substring")" = "start:end" such that - "string[start:end] == "substring"", or "0:-1" if unmatched. + "search(string, "substring")" = "start:end" such that "string[start:end] == "substring"", or "0:-1" if unmatched. + + "search(string, 'c')" = "index" such that "string[index] == 'c'", or "0" if unmatched. - "search(string, 'c')" = "index" such that - "string[index] == 'c'", or "0" if unmatched. .. function:: rsearch(string, chars[, start]) - Similar to "search", but returning the last occurrence of the - given characters within the given string, searching in reverse from - "start". + Similar to "search", but returning the last occurrence of the given characters within the given string, searching in reverse from "start". + .. function:: searchindex(string, substring[, start]) - Similar to "search", but return only the start index at which the - substring is found, or 0 if it is not. + Similar to "search", but return only the start index at which the substring is found, or 0 if it is not. + .. function:: rsearchindex(string, substring[, start]) - Similar to "rsearch", but return only the start index at which - the substring is found, or 0 if it is not. + Similar to "rsearch", but return only the start index at which the substring is found, or 0 if it is not. + .. function:: contains(haystack, needle) - Determine whether the second argument is a substring of the first. + Determine whether the second argument is a substring of the first. + .. function:: replace(string, pat, r[, n]) - Search for the given pattern "pat", and replace each occurrence - with "r". If "n" is provided, replace at most "n" - occurrences. As with search, the second argument may be a single - character, a vector or a set of characters, a string, or a regular - expression. If "r" is a function, each occurrence is replaced - with "r(s)" where "s" is the matched substring. + Search for the given pattern "pat", and replace each occurrence with "r". If "n" is provided, replace at most "n" occurrences. As with search, the second argument may be a single character, a vector or a set of characters, a string, or a regular expression. If "r" is a function, each occurrence is replaced with "r(s)" where "s" is the matched substring. + .. function:: split(string, [chars]; limit=0, keep=true) - Return an array of substrings by splitting the given string on - occurrences of the given character delimiters, which may be - specified in any of the formats allowed by "search"'s second - argument (i.e. a single character, collection of characters, - string, or regular expression). If "chars" is omitted, it - defaults to the set of all space characters, and "keep" is taken - to be false. The two keyword arguments are optional: they are are a - maximum size for the result and a flag determining whether empty - fields should be kept in the result. + Return an array of substrings by splitting the given string on occurrences of the given character delimiters, which may be specified in any of the formats allowed by "search"'s second argument (i.e. a single character, collection of characters, string, or regular expression). If "chars" is omitted, it defaults to the set of all space characters, and "keep" is taken to be false. The two keyword arguments are optional: they are are a maximum size for the result and a flag determining whether empty fields should be kept in the result. + .. function:: rsplit(string, [chars]; limit=0, keep=true) - Similar to "split", but starting from the end of the string. + Similar to "split", but starting from the end of the string. + .. function:: strip(string[, chars]) - Return "string" with any leading and trailing whitespace removed. - If "chars" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. + Return "string" with any leading and trailing whitespace removed. If "chars" (a character, or vector or set of characters) is provided, instead remove characters contained in it. + .. function:: lstrip(string[, chars]) - Return "string" with any leading whitespace removed. If "chars" - (a character, or vector or set of characters) is provided, instead - remove characters contained in it. + Return "string" with any leading whitespace removed. If "chars" (a character, or vector or set of characters) is provided, instead remove characters contained in it. + .. function:: rstrip(string[, chars]) - Return "string" with any trailing whitespace removed. If - "chars" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. + Return "string" with any trailing whitespace removed. If "chars" (a character, or vector or set of characters) is provided, instead remove characters contained in it. + .. function:: startswith(string, prefix | chars) - Returns "true" if "string" starts with "prefix". If the - second argument is a vector or set of characters, tests whether the - first character of "string" belongs to that set. + Returns "true" if "string" starts with "prefix". If the second argument is a vector or set of characters, tests whether the first character of "string" belongs to that set. + .. function:: endswith(string, suffix | chars) - Returns "true" if "string" ends with "suffix". If the second - argument is a vector or set of characters, tests whether the last - character of "string" belongs to that set. + Returns "true" if "string" ends with "suffix". If the second argument is a vector or set of characters, tests whether the last character of "string" belongs to that set. + .. function:: uppercase(string) - Returns "string" with all characters converted to uppercase. + Returns "string" with all characters converted to uppercase. + .. function:: lowercase(string) - Returns "string" with all characters converted to lowercase. + Returns "string" with all characters converted to lowercase. + .. function:: ucfirst(string) - Returns "string" with the first character converted to uppercase. + Returns "string" with the first character converted to uppercase. + .. function:: lcfirst(string) - Returns "string" with the first character converted to lowercase. + Returns "string" with the first character converted to lowercase. + .. function:: join(strings, delim[, last]) - Join an array of "strings" into a single string, inserting the - given delimiter between adjacent strings. If "last" is given, it - will be used instead of "delim" between the last two strings. For - example, "join(["apples", "bananas", "pineapples"], ", ", - " and ") == "apples, bananas and pineapples"". + Join an array of "strings" into a single string, inserting the given delimiter between adjacent strings. If "last" is given, it will be used instead of "delim" between the last two strings. For example, "join(["apples", "bananas", "pineapples"], ", ", " and ") == "apples, bananas and pineapples"". + + "strings" can be any iterable over elements "x" which are convertible to strings via "print(io::IOBuffer, x)". - "strings" can be any iterable over elements "x" which are - convertible to strings via "print(io::IOBuffer, x)". .. function:: chop(string) - Remove the last character from a string + Remove the last character from a string + .. function:: chomp(string) - Remove a trailing newline from a string + Remove a trailing newline from a string + .. function:: ind2chr(string, i) - Convert a byte index to a character index + Convert a byte index to a character index + .. function:: chr2ind(string, i) - Convert a character index to a byte index + Convert a character index to a byte index + .. function:: isvalid(str, i) - Tells whether index "i" is valid for the given string + Tells whether index "i" is valid for the given string + .. function:: nextind(str, i) - Get the next valid string index after "i". Returns a value - greater than "endof(str)" at or after the end of the string. + Get the next valid string index after "i". Returns a value greater than "endof(str)" at or after the end of the string. + .. function:: prevind(str, i) - Get the previous valid string index before "i". Returns a value - less than "1" at the beginning of the string. + Get the previous valid string index before "i". Returns a value less than "1" at the beginning of the string. + .. function:: randstring([rng], len=8) - Create a random ASCII string of length "len", consisting of - upper- and lower-case letters and the digits 0-9. The optional - "rng" argument specifies a random number generator, see *Random - Numbers*. + Create a random ASCII string of length "len", consisting of upper- and lower-case letters and the digits 0-9. The optional "rng" argument specifies a random number generator, see *Random Numbers*. + .. function:: charwidth(c) - Gives the number of columns needed to print a character. + Gives the number of columns needed to print a character. + .. function:: strwidth(s) - Gives the number of columns needed to print a string. + Gives the number of columns needed to print a string. + .. function:: isalnum(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphanumeric, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter or - Number, i.e. a character whose category code begins with 'L' or - 'N'. + Tests whether a character is alphanumeric, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter or Number, i.e. a character whose category code begins with 'L' or 'N'. + .. function:: isalpha(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is alphabetic, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter, - i.e. a character whose category code begins with 'L'. + Tests whether a character is alphabetic, or whether this is true for all elements of a string. A character is classified as alphabetic if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'. + .. function:: isascii(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the ASCII character set, or - whether this is true for all elements of a string. + Tests whether a character belongs to the ASCII character set, or whether this is true for all elements of a string. + .. function:: iscntrl(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a control character, or whether this - is true for all elements of a string. Control characters are the - non-printing characters of the Latin-1 subset of Unicode. + Tests whether a character is a control character, or whether this is true for all elements of a string. Control characters are the non-printing characters of the Latin-1 subset of Unicode. + .. function:: isdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a numeric digit (0-9), or whether this - is true for all elements of a string. + Tests whether a character is a numeric digit (0-9), or whether this is true for all elements of a string. + .. function:: isgraph(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, and not a space, or whether - this is true for all elements of a string. Any character that - would cause a printer to use ink should be classified with - isgraph(c)==true. + Tests whether a character is printable, and not a space, or whether this is true for all elements of a string. Any character that would cause a printer to use ink should be classified with isgraph(c)==true. + .. function:: islower(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a lowercase letter, or whether this is - true for all elements of a string. A character is classified as - lowercase if it belongs to Unicode category Ll, Letter: Lowercase. + Tests whether a character is a lowercase letter, or whether this is true for all elements of a string. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase. + .. function:: isnumber(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is numeric, or whether this is true for - all elements of a string. A character is classified as numeric if - it belongs to the Unicode general category Number, i.e. a character - whose category code begins with 'N'. + Tests whether a character is numeric, or whether this is true for all elements of a string. A character is classified as numeric if it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'. + .. function:: isprint(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is printable, including spaces, but not a - control character. For strings, tests whether this is true for all - elements of the string. + Tests whether a character is printable, including spaces, but not a control character. For strings, tests whether this is true for all elements of the string. + .. function:: ispunct(c::Union{Char, AbstractString}) -> Bool - Tests whether a character belongs to the Unicode general category - Punctuation, i.e. a character whose category code begins with 'P'. - For strings, tests whether this is true for all elements of the - string. + Tests whether a character belongs to the Unicode general category Punctuation, i.e. a character whose category code begins with 'P'. For strings, tests whether this is true for all elements of the string. + .. function:: isspace(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is any whitespace character. Includes - ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', - Latin-1 character U+0085, and characters in Unicode category Zs. - For strings, tests whether this is true for all elements of the - string. + Tests whether a character is any whitespace character. Includes ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs. For strings, tests whether this is true for all elements of the string. + .. function:: isupper(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is an uppercase letter, or whether this - is true for all elements of a string. A character is classified - as uppercase if it belongs to Unicode category Lu, Letter: - Uppercase, or Lt, Letter: Titlecase. + Tests whether a character is an uppercase letter, or whether this is true for all elements of a string. A character is classified as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase. + .. function:: isxdigit(c::Union{Char, AbstractString}) -> Bool - Tests whether a character is a valid hexadecimal digit, or whether - this is true for all elements of a string. + Tests whether a character is a valid hexadecimal digit, or whether this is true for all elements of a string. + .. function:: symbol(x...) -> Symbol - Create a "Symbol" by concatenating the string representations of - the arguments together. + Create a "Symbol" by concatenating the string representations of the arguments together. + .. function:: escape_string(str::AbstractString) -> AbstractString - General escaping of traditional C and Unicode escape sequences. See - "print_escaped()" for more general escaping. + General escaping of traditional C and Unicode escape sequences. See "print_escaped()" for more general escaping. + .. function:: unescape_string(s::AbstractString) -> AbstractString - General unescaping of traditional C and Unicode escape sequences. - Reverse of "escape_string()". See also "print_unescaped()". + General unescaping of traditional C and Unicode escape sequences. Reverse of "escape_string()". See also "print_unescaped()". + .. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If "length" is - specified, the string does not have to be NUL-terminated. + Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If "length" is specified, the string does not have to be NUL-terminated. + .. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If "length" is - specified, the string does not have to be NUL-terminated. + Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If "length" is specified, the string does not have to be NUL-terminated. + .. function:: wstring(s) - This is a synonym for either "utf32(s)" or "utf16(s)", - depending on whether "Cwchar_t" is 32 or 16 bits, respectively. - The synonym "WString" for "UTF32String" or "UTF16String" is - also provided. + This is a synonym for either "utf32(s)" or "utf16(s)", depending on whether "Cwchar_t" is 32 or 16 bits, respectively. The synonym "WString" for "UTF32String" or "UTF16String" is also provided. + .. function:: wstring(s) - This is a synonym for either "utf32(s)" or "utf16(s)", - depending on whether "Cwchar_t" is 32 or 16 bits, respectively. - The synonym "WString" for "UTF32String" or "UTF16String" is - also provided. + This is a synonym for either "utf32(s)" or "utf16(s)", depending on whether "Cwchar_t" is 32 or 16 bits, respectively. The synonym "WString" for "UTF32String" or "UTF16String" is also provided. + .. function:: wstring(s) - This is a synonym for either "utf32(s)" or "utf16(s)", - depending on whether "Cwchar_t" is 32 or 16 bits, respectively. - The synonym "WString" for "UTF32String" or "UTF16String" is - also provided. + This is a synonym for either "utf32(s)" or "utf16(s)", depending on whether "Cwchar_t" is 32 or 16 bits, respectively. The synonym "WString" for "UTF32String" or "UTF16String" is also provided. + diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst index f923ec028a058..c301aacbd8030 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -14,9 +14,8 @@ binary install, you can run the test suite using ``Base.runtests()``. .. function:: runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) - Run the Julia unit tests listed in "tests", which can be either a - string or an array of strings, using "numcores" processors. (not - exported) + Run the Julia unit tests listed in "tests", which can be either a string or an array of strings, using "numcores" processors. (not exported) + .. module:: Base.Test Test Framework @@ -132,28 +131,29 @@ Macros .. function:: @test(ex) - Test the expression "ex" and calls the current handler to handle - the result. + Test the expression "ex" and calls the current handler to handle the result. + .. function:: @test_throws(extype, ex) - Test that the expression "ex" throws an exception of type - "extype" and calls the current handler to handle the result. + Test that the expression "ex" throws an exception of type "extype" and calls the current handler to handle the result. + .. function:: @test_approx_eq(a, b) - Test two floating point numbers "a" and "b" for equality taking - in account small numerical errors. + Test two floating point numbers "a" and "b" for equality taking in account small numerical errors. + .. function:: @test_approx_eq_eps(a, b, tol) - Test two floating point numbers "a" and "b" for equality taking - in account a margin of tolerance given by "tol". + Test two floating point numbers "a" and "b" for equality taking in account a margin of tolerance given by "tol". + Functions --------- .. function:: with_handler(f, handler) - Run the function "f" using the "handler" as the handler. + Run the function "f" using the "handler" as the handler. + From ab4f5f149be4a13e4547a6560c10e42054d30526 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 22:36:55 -0400 Subject: [PATCH 24/27] avoid blockquote --- base/docs/helpdb.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index c0a9aac92482d..fe33fb81bbb41 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -10585,8 +10585,8 @@ minmax doc""" clamp(x, lo, hi) -Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x -> hi", return "hi". Arguments are promoted to a common type. +Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x > +hi", return "hi". Arguments are promoted to a common type. Operates elementwise over "x" if it is an array. """ clamp From 08b4f653c612675e1050fd4929b31b70a4dd5544 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sat, 27 Jun 2015 23:25:29 -0400 Subject: [PATCH 25/27] wip --- doc/Makefile | 7 +- doc/helpdb.jl | 3936 ++++++++++++------------------------ doc/stdlib/collections.rst | 8 +- 3 files changed, 1299 insertions(+), 2652 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index de445e7d6a910..dc803abc94b90 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,6 @@ # Makefile for Sphinx documentation -default: html +default: helpdb.jl html # You can set these variables from the command line. SPHINXOPTS = @@ -34,6 +34,7 @@ SPHINXBUILD = . $(ACTIVATE) && sphinx-build help: @echo "Please use 'make ' where is one of" + @echo " helpdb.jl to make the REPL help db" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @@ -170,6 +171,10 @@ doctest: $(SPHINX_BUILD) @echo "Testing of doctests in the sources finished, look at the " \ "results in _build/doctest/output.txt." +helpdb.jl: stdlib/*.rst $(SPHINX_BUILD) + $(SPHINXBUILD) -b jlhelp $(ALLSPHINXOPTS) _build/jlhelp + mv _build/jlhelp/jlhelp.jl helpdb.jl + manual/unicode-input-table.rst: $(JULIAHOME)/base/latex_symbols.jl $(JULIAHOME)/julia tabcomplete.jl > manual/unicode-input-table.rst diff --git a/doc/helpdb.jl b/doc/helpdb.jl index da10fee2d15de..369eaac64cb26 100644 --- a/doc/helpdb.jl +++ b/doc/helpdb.jl @@ -31,9 +31,9 @@ Any[ "), -("Base","length","length(A) -> Integer +("Base","length","length(s) - Returns the number of elements in A + The number of characters in string \"s\". "), @@ -126,13 +126,10 @@ Any[ "), -("Base","ind2sub","ind2sub(dims, index) -> subscripts - - Returns a tuple of subscripts into an array with dimensions - \"dims\", corresponding to the linear index \"index\" +("Base","ind2sub","ind2sub(a, index) -> subscripts - **Example** \"i, j, ... = ind2sub(size(A), indmax(A))\" provides - the indices of the maximum element + Returns a tuple of subscripts into array \"a\" corresponding to the + linear index \"index\" "), @@ -159,11 +156,11 @@ Any[ "), -("Base","getindex","getindex(type[, elements...]) +("Base","getindex","getindex(collection, key...) - Construct a 1-d array of the specified type. This is usually called - with the syntax \"Type[]\". Element values can be specified using - \"Type[a,b,c,...]\". + 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, ...)\". "), @@ -174,10 +171,10 @@ Any[ "), -("Base","zeros","zeros(type, dims) +("Base","zeros","zeros(A) - Create an array of all zeros of specified type. The type defaults - to Float64 if not specified. + Create an array of all zeros with the same element type and shape + as A. "), @@ -188,10 +185,10 @@ Any[ "), -("Base","ones","ones(type, dims) +("Base","ones","ones(A) - Create an array of all ones of specified type. The type defaults to - Float64 if not specified. + Create an array of all ones with the same element type and shape as + A. "), @@ -265,15 +262,17 @@ Any[ "), -("Base","eye","eye(n) +("Base","eye","eye(A) - n-by-n identity matrix + Constructs an identity matrix of the same dimensions and type as + \"A\". "), -("Base","eye","eye(m, n) +("Base","eye","eye(A) - m-by-n identity matrix + Constructs an identity matrix of the same dimensions and type as + \"A\". "), @@ -337,11 +336,11 @@ Any[ "), -("Base","getindex","getindex(A, inds...) +("Base","getindex","getindex(collection, key...) - Returns a subset of array \"A\" as specified by \"inds\", where - each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See - the manual section on *array indexing* for details. + 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, ...)\". "), @@ -384,10 +383,11 @@ Any[ "), -("Base","setindex!","setindex!(A, X, inds...) +("Base","setindex!","setindex!(collection, value, key...) - Store values from array \"X\" within some subset of \"A\" as - specified by \"inds\". + 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, ...)\". "), @@ -463,11 +463,10 @@ Any[ "), -("Base","find","find(A) +("Base","find","find(f, A) - Return a vector of the linear indexes of the non-zeros in \"A\" - (determined by \"A[i]!=0\"). A common use of this is to convert a - boolean array to an array of indexes of the \"true\" elements. + Return a vector of the linear indexes of \"A\" where \"f\" returns + true. "), @@ -493,16 +492,17 @@ Any[ "), -("Base","findfirst","findfirst(A) +("Base","findfirst","findfirst(predicate, A) - Return the index of the first non-zero value in \"A\" (determined - by \"A[i]!=0\"). + Return the index of the first element of \"A\" for which + \"predicate\" returns true. "), -("Base","findfirst","findfirst(A, v) +("Base","findfirst","findfirst(predicate, A) - Return the index of the first element equal to \"v\" in \"A\". + Return the index of the first element of \"A\" for which + \"predicate\" returns true. "), @@ -513,16 +513,17 @@ Any[ "), -("Base","findlast","findlast(A) +("Base","findlast","findlast(predicate, A) - Return the index of the last non-zero value in \"A\" (determined by - \"A[i]!=0\"). + Return the index of the last element of \"A\" for which + \"predicate\" returns true. "), -("Base","findlast","findlast(A, v) +("Base","findlast","findlast(predicate, A) - Return the index of the last element equal to \"v\" in \"A\". + Return the index of the last element of \"A\" for which + \"predicate\" returns true. "), @@ -533,17 +534,17 @@ Any[ "), -("Base","findnext","findnext(A, i) +("Base","findnext","findnext(A, v, i) - Find the next index >= \"i\" of a non-zero element of \"A\", or - \"0\" if not found. + Find the next index >= \"i\" of an element of \"A\" equal to \"v\" + (using \"==\"), or \"0\" if not found. "), -("Base","findnext","findnext(predicate, A, i) +("Base","findnext","findnext(A, v, i) - Find the next index >= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. + Find the next index >= \"i\" of an element of \"A\" equal to \"v\" + (using \"==\"), or \"0\" if not found. "), @@ -554,17 +555,17 @@ Any[ "), -("Base","findprev","findprev(A, i) +("Base","findprev","findprev(A, v, i) - Find the previous index <= \"i\" of a non-zero element of \"A\", or - 0 if not found. + Find the previous index <= \"i\" of an element of \"A\" equal to + \"v\" (using \"==\"), or \"0\" if not found. "), -("Base","findprev","findprev(predicate, A, i) +("Base","findprev","findprev(A, v, i) - Find the previous index <= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. + Find the previous index <= \"i\" of an element of \"A\" equal to + \"v\" (using \"==\"), or \"0\" if not found. "), @@ -714,9 +715,10 @@ Any[ "), -("Base","rot180","rot180(A) +("Base","rot180","rot180(A, k) - Rotate matrix \"A\" 180 degrees. + Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. + If \"k\" is even, this is equivalent to a \"copy\". "), @@ -727,9 +729,11 @@ Any[ "), -("Base","rotl90","rotl90(A) +("Base","rotl90","rotl90(A, k) - Rotate matrix \"A\" left 90 degrees. + Rotate matrix \"A\" left 90 degrees an integer \"k\" number of + times. If \"k\" is zero or a multiple of four, this is equivalent + to a \"copy\". "), @@ -741,9 +745,11 @@ Any[ "), -("Base","rotr90","rotr90(A) +("Base","rotr90","rotr90(A, k) - Rotate matrix \"A\" right 90 degrees. + Rotate matrix \"A\" right 90 degrees an integer \"k\" number of + times. If \"k\" is zero or a multiple of four, this is equivalent + to a \"copy\". "), @@ -760,7 +766,7 @@ Any[ Reduce 2-argument function \"f\" along dimensions of \"A\". \"dims\" is a vector specifying the dimensions to reduce, and \"initial\" is the initial value to use in the reductions. For *+*, - ***, *max* and *min* the *initial* argument is optional. + >>**<<*, *max* and *min* the *initial* argument is optional. The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should @@ -808,9 +814,10 @@ Any[ "), -("Base","nthperm","nthperm(v, k) +("Base","nthperm","nthperm(p) - Compute the kth lexicographic permutation of a vector. + Return the \"k\" that generated permutation \"p\". Note that + \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". "), @@ -924,34 +931,39 @@ Any[ "), -("Base","partitions","partitions(n) +("Base","partitions","partitions(array, m) - Generate all integer arrays that sum to \"n\". Because the number - of partitions can be very large, this function returns an iterator - object. Use \"collect(partitions(n))\" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using \"length(partitions(n))\". + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use \"collect(partitions(array,m))\" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using \"length(partitions(array,m))\". "), -("Base","partitions","partitions(n, m) +("Base","partitions","partitions(array, m) - Generate all arrays of \"m\" integers that sum to \"n\". Because - the number of partitions can be very large, this function returns - an iterator object. Use \"collect(partitions(n,m))\" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using \"length(partitions(n,m))\". + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use \"collect(partitions(array,m))\" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using \"length(partitions(array,m))\". "), -("Base","partitions","partitions(array) +("Base","partitions","partitions(array, m) - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - \"collect(partitions(array))\" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using \"length(partitions(array))\". + Generate all set partitions of the elements of an array into + exactly m subsets, represented as arrays of arrays. Because the + number of partitions can be very large, this function returns an + iterator object. Use \"collect(partitions(array,m))\" to get an + array of all partitions. The number of partitions into m subsets is + equal to the Stirling number of the second kind and can be + efficiently computed using \"length(partitions(array,m))\". "), @@ -985,10 +997,9 @@ Any[ "), -("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +("Base","rol!","rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on \"src\" and put the result - into \"dest\". + Performs a left rotation operation on B. "), @@ -1004,10 +1015,9 @@ Any[ "), -("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +("Base","ror!","ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on \"src\" and put the result - into \"dest\". + Performs a right rotation operation on B. "), @@ -1023,33 +1033,25 @@ Any[ "), -("Base","sparse","sparse(I, J, V[, m, n, combine]) +("Base","sparse","sparse(A) - Create a sparse matrix \"S\" of dimensions \"m x n\" such that - \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to - combine duplicates. If \"m\" and \"n\" are not specified, they are - set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" - function is not supplied, duplicates are added by default. + Convert an AbstractMatrix \"A\" into a sparse matrix. "), -("Base","sparsevec","sparsevec(I, V[, m, combine]) +("Base","sparsevec","sparsevec(A) - Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] - = V[k]\". Duplicates are combined using the \"combine\" function, - which defaults to \"+\" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. + Convert a dense vector \"A\" into a sparse matrix of size \"m x + 1\". In julia, sparse vectors are really just sparse matrices with + one column. "), -("Base","sparsevec","sparsevec(D::Dict[, m]) +("Base","sparsevec","sparsevec(A) - Create a sparse matrix of size \"m x 1\" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. + Convert a dense vector \"A\" into a sparse matrix of size \"m x + 1\". In julia, sparse vectors are really just sparse matrices with + one column. "), @@ -1073,9 +1075,18 @@ Any[ "), -("Base","full","full(S) +("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a + \"QRCompactWYQ\" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. - Convert a sparse matrix \"S\" into a dense matrix. + Optionally takes a \"thin\" Boolean argument, which if \"true\" + omits the columns that span the rows of \"R\" in the QR + factorization that are zero. The resulting matrix is the \"Q\" in a + thin QR factorization (sometimes called the reduced QR + factorization). If \"false\", returns a \"Q\" that spans all rows + of \"R\" in its corresponding QR factorization. "), @@ -1250,10 +1261,10 @@ Any[ "), -("Base","edit","edit(file::AbstractString[, line]) +("Base","edit","edit(function[, types]) - Edit a file optionally providing a line number to edit at. Returns - to the julia prompt when you quit the editor. + Edit the definition of a function, optionally specifying a tuple of + types to indicate which method to edit. "), @@ -1271,11 +1282,11 @@ Any[ "), -("Base","less","less(file::AbstractString[, line]) +("Base","less","less(function[, types]) - Show a file using the default pager, optionally providing a - starting line number. Returns to the julia prompt when you quit the - pager. + Show the definition of a function using the default pager, + optionally specifying a tuple of types to indicate which method to + see. "), @@ -1294,10 +1305,10 @@ Any[ "), -("Base","clipboard","clipboard(x) +("Base","clipboard","clipboard() -> AbstractString - Send a printed form of \"x\" to the operating system clipboard - (\"copy\"). + Return a string with the contents of the operating system clipboard + (\"paste\"). "), @@ -1332,7 +1343,7 @@ Any[ "), -("Base","include","include(path::AbstractString) +("Base","include","include(\"file.jl\") Evaluate the contents of a source file in the current context. During including, a task-local include path is set to the directory @@ -1365,13 +1376,10 @@ Any[ "), -("Base","which","which(f, types) - - Returns the method of \"f\" (a \"Method\" object) that would be - called for arguments of the given types. +("Base","which","which(symbol) - If \"types\" is an abstract type, then the method that would be - called by \"invoke\" is returned. + Return the module in which the binding for the variable referenced + by \"symbol\" was created. "), @@ -1444,15 +1452,11 @@ Any[ "), -("Base","is","is(x, y) -> Bool -===(x, y) -> Bool -≡(x, y) -> Bool +("Base","===","===(x, y) + + ≡(x, y) - Determine whether \"x\" and \"y\" are identical, in the sense that - no program could distinguish them. Compares mutable objects by - address in memory, and compares immutable objects (such as numbers) - by contents at the bit level. This function is sometimes called - \"egal\". + See the \"is()\" operator "), @@ -1558,10 +1562,10 @@ Any[ New types should implement the 2-argument form, typically by calling the 2-argument \"hash\" method recursively in order to mix - hashes of the contents with each other (and with \"h\"). - Typically, any type that implements \"hash\" should also implement - its own \"==\" (hence \"isequal\") to guarantee the property - mentioned above. + hashes of the contents with each other (and with \"h\"). Typically, + any type that implements \"hash\" should also implement its own + \"==\" (hence \"isequal\") to guarantee the property mentioned + above. "), @@ -1693,11 +1697,9 @@ Any[ "), -("Base","issubtype","issubtype(type1, type2) +("Base","<:","<:(T1, T2) - True if and only if all values of \"type1\" are also of \"type2\". - Can also be written using the \"<:\" infix operator as \"type1 <: - type2\". + Subtype operator, equivalent to \"issubtype(T1,T2)\". "), @@ -1748,26 +1750,27 @@ Any[ "), -("Base","sizeof","sizeof(type) +("Base","sizeof","sizeof(s::AbstractString) - Size, in bytes, of the canonical binary representation of the given - type, if any. + The number of bytes in string \"s\". "), -("Base","eps","eps([type]) +("Base","eps","eps(::DateTime) -> Millisecond + + eps(::Date) -> Day - The distance between 1.0 and the next larger representable - floating-point value of \"type\". Only floating-point types are - sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" - is returned. + Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" + for \"Date\" values. "), -("Base","eps","eps(x) +("Base","eps","eps(::DateTime) -> Millisecond - The distance between \"x\" and the next larger representable - floating-point value of the same type as \"x\". + eps(::Date) -> Day + + Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" + for \"Date\" values. "), @@ -2022,28 +2025,23 @@ Any[ "), -("Base","parse","parse(str, start; greedy=true, raise=true) +("Base","parse","parse(type, str[, base]) - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If \"greedy\" is true (default), - \"parse\" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is - true (default), syntax errors other than incomplete expressions - will raise an error. If \"raise\" is false, \"parse\" will return - an expression that will raise an error upon evaluation. + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. "), -("Base","parse","parse(str; raise=true) +("Base","parse","parse(type, str[, base]) - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If \"raise\" is true (default), syntax errors will - raise an error; otherwise, \"parse\" will return an expression that - will raise an error upon evaluation. + Parse a string as a number. If the type is an integer type, then a + base can be specified (the default is 10). If the type is a + floating point type, the string is parsed as a decimal floating + point number. If the string does not contain a valid number, an + error is raised. "), @@ -2056,19 +2054,33 @@ Any[ "), -("Base","get","get(x) +("Base","get","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: - Attempt to access the value of the \"Nullable\" object, \"x\". - Returns the value if it is present; otherwise, throws a - \"NullException\". + get(dict, key) do + # default value calculated here + time() + end "), -("Base","get","get(x, y) +("Base","get","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: - Attempt to access the value of the \"Nullable{T}\" object, \"x\". - Returns the value if it is present; otherwise, returns \"convert(T, - y)\". + get(dict, key) do + # default value calculated here + time() + end "), @@ -2121,31 +2133,31 @@ Any[ "), -("Base","kill","kill(p::Process, signum=SIGTERM) +("Base","kill","kill(manager::FooManager, pid::Int, config::WorkerConfig) - Send a signal to a process. The default is to terminate the - process. + Implemented by cluster managers. It is called on the master + process, by \"rmprocs\". It should cause the remote worker + specified by \"pid\" to exit. + \"Base.kill(manager::ClusterManager.....)\" executes a remote + \"exit()\" on \"pid\" "), -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) +("Base","open","open(f::function, args...) + + Apply the function \"f\" to the result of \"open(args...)\" and + close the resulting file descriptor upon completion. - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. + **Example**: \"open(readall, \"file.txt\")\" "), -("Base","open","open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) +("Base","open","open(f::function, args...) + + Apply the function \"f\" to the result of \"open(args...)\" and + close the resulting file descriptor upon completion. - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". + **Example**: \"open(readall, \"file.txt\")\" "), @@ -2213,22 +2225,20 @@ Any[ "), -("Base","pipe","pipe(from, to, ...) - - Create a pipeline from a data source to a destination. The source - and destination can be commands, I/O streams, strings, or results - of other \"pipe\" calls. At least one argument must be a command. - Strings refer to filenames. When called with more than two - arguments, they are chained together from left to right. For - example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". - This provides a more concise way to specify multi-stage pipelines. +("Base","pipe","pipe(command; stdin, stdout, stderr, append=false) - **Examples**: - * \"run(pipe(`ls`, `grep xyz`))\" + Redirect I/O to or from the given \"command\". Keyword arguments + specify which of the command's streams should be redirected. + \"append\" controls whether file output appends to the file. This + is a more general version of the 2-argument \"pipe\" function. + \"pipe(from, to)\" is equivalent to \"pipe(from, stdout=to)\" when + \"from\" is a command, and to \"pipe(to, stdin=from)\" when + \"from\" is another kind of data source. - * \"run(pipe(`ls`, \"out.txt\"))\" + **Examples**: * \"run(pipe(\"dothings\", stdout=\"out.txt\", + stderr=\"errs.txt\"))\" - * \"run(pipe(\"out.txt\", `grep xyz`))\" + * \"run(pipe(`update`, stdout=\"log.txt\", append=true))\" "), @@ -2242,9 +2252,8 @@ Any[ \"from\" is a command, and to \"pipe(to, stdin=from)\" when \"from\" is another kind of data source. - **Examples**: - * \"run(pipe(`dothings`, stdout=\"out.txt\", - stderr=\"errs.txt\"))\" + **Examples**: * \"run(pipe(\"dothings\", stdout=\"out.txt\", + stderr=\"errs.txt\"))\" * \"run(pipe(`update`, stdout=\"log.txt\", append=true))\" @@ -2269,10 +2278,10 @@ Any[ "), -("Base","time","time() +("Base","time","time(t::TmStruct) - Get the system time in seconds since the epoch, with fairly high - (typically, microsecond) resolution. + Converts a \"TmStruct\" struct to a number of seconds since the + epoch. "), @@ -2601,14 +2610,10 @@ Any[ "), -("Base","Timer","Timer(callback::Function, delay, repeat=0) +("Base","Timer","Timer(delay, repeat=0) - Create a timer to call the given callback function. The callback is - passed one argument, the timer object itself. The callback will be - invoked after the specified initial delay, and then repeating with - the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is - only triggered once. Times are in seconds. A timer is stopped and - has its resources freed by calling \"close\" on it. + Create a timer that wakes up tasks waiting for it (by calling + \"wait\" on the timer object) at a specified interval. "), @@ -2692,7 +2697,7 @@ Any[ "), -("Base","functionloc","functionloc(f::Function, types) +("Base","functionloc","functionloc(m::Method) Returns a tuple \"(filename,line)\" giving the location of a method definition. @@ -2935,16 +2940,16 @@ Any[ "), -("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) +("Base","unsafe_copy!","unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy \"N\" elements from a source pointer to a destination, with no - checking. The size of an element is determined by the type of the - pointers. + Copy \"N\" elements from a source array to a destination, starting + at offset \"so\" in the source and \"do\" in the destination + (1-indexed). The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointers \"dest\" and \"src\" to ensure that - they are valid. Incorrect usage may corrupt or segfault your - program, in the same manner as C. + is performed to ensure that N is inbounds on either array. + Incorrect usage may corrupt or segfault your program, in the same + manner as C. "), @@ -2961,10 +2966,11 @@ Any[ "), -("Base","copy!","copy!(dest, src) +("Base","copy!","copy!(dest, do, src, so, N) - Copy all elements from collection \"src\" to array \"dest\". - Returns \"dest\". + Copy \"N\" elements from collection \"src\" starting at offset + \"so\", to array \"dest\" starting at offset \"do\". Returns + \"dest\". "), @@ -3220,7 +3226,7 @@ Any[ julia> a = [\"a\", \"b\", \"c\"]; julia> for (index, value) in enumerate(a) - println(\"\$index \$value\") + println(\"\\\$index \\\$value\") end 1 a 2 b @@ -3288,11 +3294,9 @@ Any[ "), -("Base","length","length(collection) -> Integer +("Base","length","length(s) - For ordered, indexable collections, the maximum index \"i\" for - which \"getindex(collection, i)\" is valid. For unordered - collections, the number of elements. + The number of characters in string \"s\". "), @@ -3306,10 +3310,9 @@ Any[ "), ("Base","in","in(item, collection) -> Bool -∈(item, collection) -> Bool -∋(collection, item) -> Bool -∉(item, collection) -> Bool -∌(collection, item) -> 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 @@ -3357,28 +3360,12 @@ Any[ "), -("Base","reduce","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. +("Base","reduce","reduce(op, itr) - 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. + 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\". "), @@ -3391,10 +3378,11 @@ Any[ "), -("Base","foldl","foldl(op, v0, itr) +("Base","foldl","foldl(op, itr) - Like \"reduce()\", but with guaranteed left associativity. \"v0\" - will be used exactly once. + 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)\"). "), @@ -3406,10 +3394,11 @@ Any[ "), -("Base","foldr","foldr(op, v0, itr) +("Base","foldr","foldr(op, itr) - Like \"reduce()\", but with guaranteed right associativity. \"v0\" - will be used exactly once. + 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)\"). "), @@ -3421,9 +3410,9 @@ Any[ "), -("Base","maximum","maximum(itr) +("Base","maximum","maximum(A, dims) - Returns the largest element in a collection. + Compute the maximum value of an array over the given dimensions. "), @@ -3440,9 +3429,9 @@ Any[ "), -("Base","minimum","minimum(itr) +("Base","minimum","minimum(A, dims) - Returns the smallest element in a collection. + Compute the minimum value of an array over the given dimensions. "), @@ -3478,9 +3467,10 @@ Any[ "), -("Base","findmax","findmax(itr) -> (x, index) +("Base","findmax","findmax(A, dims) -> (maxval, index) - Returns the maximum element and its index. + For an array input, returns the value and index of the maximum over + the given dimensions. "), @@ -3491,9 +3481,10 @@ Any[ "), -("Base","findmin","findmin(itr) -> (x, index) +("Base","findmin","findmin(A, dims) -> (minval, index) - Returns the minimum element and its index. + For an array input, returns the value and index of the minimum over + the given dimensions. "), @@ -3504,9 +3495,9 @@ Any[ "), -("Base","maxabs","maxabs(itr) +("Base","maxabs","maxabs(A, dims) - Compute the maximum absolute value of a collection of values. + Compute the maximum absolute values over given dimensions. "), @@ -3523,9 +3514,9 @@ Any[ "), -("Base","minabs","minabs(itr) +("Base","minabs","minabs(A, dims) - Compute the minimum absolute value of a collection of values. + Compute the minimum absolute values over given dimensions. "), @@ -3542,15 +3533,17 @@ Any[ "), -("Base","sum","sum(itr) +("Base","sum","sum(f, itr) - Returns the sum of all elements in a collection. + Sum the results of calling function \"f\" on each element of + \"itr\". "), -("Base","sum","sum(A, dims) +("Base","sum","sum(f, itr) - Sum elements of an array over the given dimensions. + Sum the results of calling function \"f\" on each element of + \"itr\". "), @@ -3568,10 +3561,10 @@ Any[ "), -("Base","sumabs","sumabs(itr) +("Base","sumabs","sumabs(A, dims) - Sum absolute values of all elements in a collection. This is - equivalent to *sum(abs(itr))* but faster. + Sum absolute values of elements of an array over the given + dimensions. "), @@ -3589,10 +3582,10 @@ Any[ "), -("Base","sumabs2","sumabs2(itr) +("Base","sumabs2","sumabs2(A, dims) - Sum squared absolute values of all elements in a collection. This - is equivalent to *sum(abs2(itr))* but faster. + Sum squared absolute values of elements of an array over the given + dimensions. "), @@ -3610,9 +3603,9 @@ Any[ "), -("Base","prod","prod(itr) +("Base","prod","prod(A, dims) - Returns the product of all elements of a collection. + Multiply elements of an array over the given dimensions. "), @@ -3629,16 +3622,17 @@ Any[ "), -("Base","any","any(itr) -> Bool +("Base","any","any(p, itr) -> Bool - Test whether any elements of a boolean collection are true. + Determine whether predicate \"p\" returns true for any elements of + \"itr\". "), -("Base","any","any(A, dims) +("Base","any","any(p, itr) -> Bool - Test whether any values along the given dimensions of an array are - true. + Determine whether predicate \"p\" returns true for any elements of + \"itr\". "), @@ -3649,16 +3643,23 @@ Any[ "), -("Base","all","all(itr) -> Bool +("Base","all","all(p, itr) -> Bool + + Determine whether predicate \"p\" returns true for all elements of + \"itr\". - Test whether all elements of a boolean collection are true. + julia> all(i->(4<=i<=6), [4,5,6]) + true "), -("Base","all","all(A, dims) +("Base","all","all(p, itr) -> Bool - Test whether all values along the given dimensions of an array are - true. + Determine whether predicate \"p\" returns true for all elements of + \"itr\". + + julia> all(i->(4<=i<=6), [4,5,6]) + true "), @@ -3712,9 +3713,11 @@ Any[ "), -("Base","map!","map!(function, collection) +("Base","map!","map!(function, destination, collection...) - In-place version of \"map()\". + Like \"map()\", but stores the result in \"destination\" rather + than a new collection. \"destination\" must be at least as large as + the first collection. "), @@ -3726,27 +3729,10 @@ Any[ "), -("Base","mapreduce","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 +("Base","mapreduce","mapreduce(f, op, itr) - 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. + Like \"mapreduce(f, op, v0, itr)\". In general, this cannot be used + with empty collections (see \"reduce(op, itr)\"). "), @@ -3757,10 +3743,11 @@ Any[ "), -("Base","mapfoldl","mapfoldl(f, op, v0, itr) +("Base","mapfoldl","mapfoldl(f, op, itr) - Like \"mapreduce()\", but with guaranteed left associativity. - \"v0\" will be used exactly once. + 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)\"). "), @@ -3772,10 +3759,11 @@ Any[ "), -("Base","mapfoldr","mapfoldr(f, op, v0, itr) +("Base","mapfoldr","mapfoldr(f, op, itr) - Like \"mapreduce()\", but with guaranteed right associativity. - \"v0\" will be used exactly once. + 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)\"). "), @@ -3809,10 +3797,10 @@ Any[ "), -("Base","collect","collect(collection) +("Base","collect","collect(element_type, collection) - Return an array of all items in a collection. For associative - collections, returns (key, value) tuples. + Return an array of type \"Array{element_type,1}\" of all items in a + collection. "), @@ -3823,13 +3811,11 @@ Any[ "), -("Base","issubset","issubset(a, b) -⊆(A, S) -> Bool -⊈(A, S) -> Bool -⊊(A, S) -> Bool +("Base","issubset","issubset(A, S) -> Bool + + ⊆(A, S) -> Bool - Determine whether every element of \"a\" is also in \"b\", using - \"in()\". + True if A is a subset of or equal to S. "), @@ -3894,13 +3880,6 @@ Any[ "), -("Base","get","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. - -"), - ("Base","get","get(f::Function, collection, key) Return the value stored for the given key, or if no mapping for the @@ -3916,10 +3895,22 @@ Any[ "), -("Base","get!","get!(collection, key, default) +("Base","get","get(f::Function, collection, key) Return the value stored for the given key, or if no mapping for the - key is present, store \"key => default\", and return \"default\". + 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 + + + time() + end "), @@ -3937,6 +3928,24 @@ Any[ "), +("Base","get!","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 + + + time() + end + +"), + ("Base","getkey","getkey(collection, key, default) Return the key matching argument \"key\" if one exists in @@ -3951,11 +3960,29 @@ Any[ "), -("Base","pop!","pop!(collection, key[, default]) +("Base","pop!","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 - 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> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 "), @@ -4037,7 +4064,8 @@ Any[ "), ("Base","union","union(s1, s2...) -∪(s1, s2) + + ∪(s1, s2) Construct the union of two or more sets. Maintains order with arrays. @@ -4051,7 +4079,8 @@ Any[ "), ("Base","intersect","intersect(s1, s2...) -∩(s1, s2) + + ∩(s1, s2) Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. @@ -4081,17 +4110,17 @@ Any[ "), -("Base","symdiff!","symdiff!(s, n) +("Base","symdiff!","symdiff!(s1, s2) - The set \"s\" is destructively modified to toggle the inclusion of - integer \"n\". + Construct the symmetric difference of sets \"s1\" and \"s2\", + storing the result in \"s1\". "), -("Base","symdiff!","symdiff!(s, itr) +("Base","symdiff!","symdiff!(s1, s2) - For each element in \"itr\", destructively toggle its inclusion in - set \"s\". + Construct the symmetric difference of sets \"s1\" and \"s2\", + storing the result in \"s1\". "), @@ -4123,7 +4152,8 @@ Any[ "), ("Base","issubset","issubset(A, S) -> Bool -⊆(A, S) -> Bool + + ⊆(A, S) -> Bool True if A is a subset of or equal to S. @@ -4231,20 +4261,22 @@ Any[ "), -("Base","deleteat!","deleteat!(collection, index) +("Base","deleteat!","deleteat!(collection, itr) - Remove the item at the given \"index\" and return the modified - \"collection\". Subsequent items are shifted to fill the resulting - gap. + Remove the items at the indices given by \"itr\", and return the + modified \"collection\". Subsequent items are shifted to fill the + resulting gap. \"itr\" must be sorted and unique. - julia> deleteat!([6, 5, 4, 3, 2, 1], 2) - 5-element Array{Int64,1}: - 6 - 4 + julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5) + 3-element Array{Int64,1}: + 5 3 - 2 1 + julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 + "), ("Base","deleteat!","deleteat!(collection, itr) @@ -4265,51 +4297,30 @@ Any[ "), -("Base","splice!","splice!(collection, index[, replacement]) -> item - - Remove the item at the given index, and return the removed item. - Subsequent items are shifted down 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 +("Base","splice!","splice!(collection, range[, replacement]) -> items - julia> splice!(A, 5, -1) - 1 + Remove items in the specified index range, and return a collection + containing the removed items. Subsequent items are shifted down to + fill the resulting gap. If specified, replacement values from an + ordered collection will be spliced in place of the removed items. - julia> A - 5-element Array{Int64,1}: - 6 - 5 - 4 - 3 - -1 + To insert \"replacement\" before an index \"n\" without removing + any items, use \"splice!(collection, n:n-1, replacement)\". - julia> splice!(A, 1, [-1, -2, -3]) - 6 + julia> splice!(A, 4:3, 2) + 0-element Array{Int64,1} julia> A - 7-element Array{Int64,1}: + 8-element Array{Int64,1}: -1 -2 -3 + 2 5 4 3 -1 - To insert \"replacement\" before an index \"n\" without removing - any items, use \"splice!(collection, n:n-1, replacement)\". - "), ("Base","splice!","splice!(collection, range[, replacement]) -> items @@ -4609,81 +4620,53 @@ Any[ "), -("Dates","DateTime","DateTime(y[, m, d, h, mi, s, ms]) -> DateTime +("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". + Similar form as above for parsing a \"DateTime\", but passes a + \"DateFormat\" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a \"DateFormat\" object then use this + method for parsing. "), -("Dates","DateTime","DateTime(periods::Period...) -> DateTime +("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". + Similar form as above for parsing a \"DateTime\", but passes a + \"DateFormat\" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a \"DateFormat\" object then use this + method for parsing. "), -("Dates","DateTime","DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime +("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). + Similar form as above for parsing a \"DateTime\", but passes a + \"DateFormat\" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a \"DateFormat\" object then use this + method for parsing. "), -("Dates","DateTime","DateTime(dt::Date) -> DateTime +("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. + Similar form as above for parsing a \"DateTime\", but passes a + \"DateFormat\" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a \"DateFormat\" object then use this + method for parsing. "), -("Dates","DateTime","DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +-----------------+-----------+-----------------------------------------------------------------+ - | Code | Matches | Comment | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"y\\\" | 1996, 96 | Returns year of 1996, 0096 | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"m\\\" | 1, 01 | Matches 1 or 2-digit months | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"u\\\" | Jan | Matches abbreviated months according to the \\\"locale\\\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"U\\\" | January | Matches full month names according to the \\\"locale\\\" keyword | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"d\\\" | 1, 01 | Matches 1 or 2-digit days | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"H\\\" | 00 | Matches hours | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"M\\\" | 00 | Matches minutes | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"S\\\" | 00 | Matches seconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"s\\\" | .500 | Matches milliseconds | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"e\\\" | Mon, Tues | Matches abbreviated days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"E\\\" | Monday | Matches full name days of the week | - +-----------------+-----------+-----------------------------------------------------------------+ - | \\\"yyyymmdd\\\" | 19960101 | Matches fixed-width year, month, and day | - +-----------------+-----------+-----------------------------------------------------------------+ +("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". + Similar form as above for parsing a \"DateTime\", but passes a + \"DateFormat\" object instead of a raw formatting string. It is + more efficient if similarly formatted date strings will be parsed + repeatedly to first create a \"DateFormat\" object then use this + method for parsing. "), @@ -4706,47 +4689,38 @@ Any[ "), -("Dates","Date","Date(y[, m, d]) -> Date +("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". "), -("Dates","Date","Date(period::Period...) -> Date +("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". "), -("Dates","Date","Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date +("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". "), -("Dates","Date","Date(dt::DateTime) -> Date +("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". "), -("Dates","Date","Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date +("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". "), @@ -4757,10 +4731,10 @@ Any[ "), -("Dates","now","now() -> DateTime +("Dates","now","now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system time - including the system timezone locale. + Returns a DateTime corresponding to the user's system time as + UTC/GMT. "), @@ -4772,7 +4746,8 @@ Any[ "), ("Dates","eps","eps(::DateTime) -> Millisecond -eps(::Date) -> Day + + eps(::Date) -> Day Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" for \"Date\" values. @@ -4780,28 +4755,22 @@ eps(::Date) -> Day "), ("Dates","year","year(dt::TimeType) -> Int64 -month(dt::TimeType) -> Int64 -week(dt::TimeType) -> Int64 -day(dt::TimeType) -> Int64 -hour(dt::TimeType) -> Int64 -minute(dt::TimeType) -> Int64 -second(dt::TimeType) -> Int64 -millisecond(dt::TimeType) -> Int64 + + month(dt::TimeType) -> Int64 week(dt::TimeType) -> Int64 + day(dt::TimeType) -> Int64 hour(dt::TimeType) -> Int64 + minute(dt::TimeType) -> Int64 second(dt::TimeType) -> Int64 + millisecond(dt::TimeType) -> Int64 Return the field part of a Date or DateTime as an \"Int64\". "), -("Dates","Year","Year(dt::TimeType) -> Year -Month(dt::TimeType) -> Month -Week(dt::TimeType) -> Week -Day(dt::TimeType) -> Day -Hour(dt::TimeType) -> Hour -Minute(dt::TimeType) -> Minute -Second(dt::TimeType) -> Second -Millisecond(dt::TimeType) -> Millisecond +("Dates","Year","Year(v) + + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) - Return the field part of a Date or DateTime as a \"Period\" type. + Construct a \"Period\" type with the given \"v\" value. Input must + be losslessly convertible to an \"Int64\". "), @@ -4920,11 +4889,15 @@ Millisecond(dt::TimeType) -> Millisecond "), -("Dates","trunc","trunc(dt::TimeType, ::Type{Period}) -> TimeType +("Dates","trunc","trunc([T], x[, digits[, base]]) + + \"trunc(x)\" returns the nearest integral value of the same type as + \"x\" whose absolute value is less than or equal to \"x\". + + \"trunc(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. - Truncates the value of \"dt\" according to the provided \"Period\" - type. E.g. if \"dt\" is \"1996-01-01T12:30:00\", then - \"trunc(dt,Day) == 1996-01-01T00:00:00\". + \"digits\" and \"base\" work as for \"round()\". "), @@ -4976,21 +4949,25 @@ Millisecond(dt::TimeType) -> Millisecond "), -("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType +("Dates","tonext","tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - Adjusts \"dt\" to the next day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the next \"dow\", allowing - for no adjustment to occur. + Adjusts \"dt\" by iterating at most \"limit\" iterations by + \"step\" increments until \"func\" returns true. \"func\" must take + a single \"TimeType\" argument and return a \"Bool\". \"same\" + allows \"dt\" to be considered in satisfying \"func\". \"negate\" + will make the adjustment process terminate when \"func\" returns + false instead of true. "), -("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType +("Dates","toprev","toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - Adjusts \"dt\" to the previous day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the previous \"dow\", - allowing for no adjustment to occur. + Adjusts \"dt\" by iterating at most \"limit\" iterations by + \"step\" increments until \"func\" returns true. \"func\" must take + a single \"TimeType\" argument and return a \"Bool\". \"same\" + allows \"dt\" to be considered in satisfying \"func\". \"negate\" + will make the adjustment process terminate when \"func\" returns + false instead of true. "), @@ -5042,13 +5019,8 @@ Millisecond(dt::TimeType) -> Millisecond "), ("Dates","Year","Year(v) -Month(v) -Week(v) -Day(v) -Hour(v) -Minute(v) -Second(v) -Millisecond(v) + + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) Construct a \"Period\" type with the given \"v\" value. Input must be losslessly convertible to an \"Int64\". @@ -5117,9 +5089,10 @@ Millisecond(v) "), -("Base","cd","cd(dir::AbstractString) +("Base","cd","cd(f[, dir]) - Set the current working directory. + Temporarily changes the current working directory (HOME if not + specified) and applies function f before returning. "), @@ -5158,7 +5131,7 @@ Millisecond(v) Creates a symbolic link to \"target\" with the name \"link\". Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. + do not support soft symbolic links, such as Windows XP. "), @@ -5180,31 +5153,31 @@ Millisecond(v) Returns a structure whose fields contain information about the file. The fields of the structure are: - +-----------+------------------------------------------------------------------------+ - | size | The size (in bytes) of the file | - +-----------+------------------------------------------------------------------------+ - | device | ID of the device that contains the file | - +-----------+------------------------------------------------------------------------+ - | inode | The inode number of the file | - +-----------+------------------------------------------------------------------------+ - | mode | The protection mode of the file | - +-----------+------------------------------------------------------------------------+ - | nlink | The number of hard links to the file | - +-----------+------------------------------------------------------------------------+ - | uid | The user id of the owner of the file | - +-----------+------------------------------------------------------------------------+ - | gid | The group id of the file owner | - +-----------+------------------------------------------------------------------------+ - | rdev | If this file refers to a device, the ID of the device it refers to | - +-----------+------------------------------------------------------------------------+ - | blksize | The file-system preferred block size for the file | - +-----------+------------------------------------------------------------------------+ - | blocks | The number of such blocks allocated | - +-----------+------------------------------------------------------------------------+ - | mtime | Unix timestamp of when the file was last modified | - +-----------+------------------------------------------------------------------------+ - | ctime | Unix timestamp of when the file was created | - +-----------+------------------------------------------------------------------------+ + +–––––-+––––––––––––––––––––––––––––––––––––+ | size | The + size (in bytes) of the file + | +–––––-+––––––––––––––––––––––––––––––––––––+ | device | ID of + the device that contains the file | + +–––––-+––––––––––––––––––––––––––––––––––––+ | inode | The + inode number of the file + | +–––––-+––––––––––––––––––––––––––––––––––––+ | mode | The + protection mode of the file + | +–––––-+––––––––––––––––––––––––––––––––––––+ | nlink | The + number of hard links to the file + | +–––––-+––––––––––––––––––––––––––––––––––––+ | uid | The + user id of the owner of the file + | +–––––-+––––––––––––––––––––––––––––––––––––+ | gid | The + group id of the file owner + | +–––––-+––––––––––––––––––––––––––––––––––––+ | rdev | If + this file refers to a device, the ID of the device it refers to + | +–––––-+––––––––––––––––––––––––––––––––––––+ | blksize | The + file-system preferred block size for the file + | +–––––-+––––––––––––––––––––––––––––––––––––+ | blocks | The + number of such blocks allocated + | +–––––-+––––––––––––––––––––––––––––––––––––+ | mtime | Unix + timestamp of when the file was last modified | + +–––––-+––––––––––––––––––––––––––––––––––––+ | ctime | Unix + timestamp of when the file was created | + +–––––-+––––––––––––––––––––––––––––––––––––+ "), @@ -5244,13 +5217,10 @@ Millisecond(v) Gets the permissions of the owner of the file as a bitfield of - +------+-----------------------+ - | 01 | Execute Permission | - +------+-----------------------+ - | 02 | Write Permission | - +------+-----------------------+ - | 04 | Read Permission | - +------+-----------------------+ + +–––+–––––––––––-+ | 01 | Execute Permission | + +–––+–––––––––––-+ | 02 | Write Permission | + +–––+–––––––––––-+ | 04 | Read Permission | + +–––+–––––––––––-+ For allowed arguments, see \"stat\". @@ -5567,34 +5537,12 @@ Millisecond(v) "), -("Base","open","open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - -"), - -("Base","open","open(file_name[, mode]) -> IOStream +("Base","open","open(f::function, args...) - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: + Apply the function \"f\" to the result of \"open(args...)\" and + close the resulting file descriptor upon completion. - +------+-----------------------------------+ - | r | read | - +------+-----------------------------------+ - | r+ | read, write | - +------+-----------------------------------+ - | w | write, create, truncate | - +------+-----------------------------------+ - | w+ | read, write, create, truncate | - +------+-----------------------------------+ - | a | write, create, append | - +------+-----------------------------------+ - | a+ | read, write, create, append | - +------+-----------------------------------+ + **Example**: \"open(readall, \"file.txt\")\" "), @@ -5607,21 +5555,45 @@ Millisecond(v) "), -("Base","IOBuffer","IOBuffer() -> IOBuffer +("Base","open","open(f::function, args...) + + Apply the function \"f\" to the result of \"open(args...)\" and + close the resulting file descriptor upon completion. + + **Example**: \"open(readall, \"file.txt\")\" + +"), - Create an in-memory I/O stream. +("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. "), -("Base","IOBuffer","IOBuffer(size::Int) +("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) - Create a fixed size IOBuffer. The buffer will not grow dynamically. + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. "), -("Base","IOBuffer","IOBuffer(string) +("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) - Create a read-only IOBuffer on the data underlying the given string + Create an IOBuffer, which may optionally operate on a pre-existing + array. If the readable/writable arguments are given, they restrict + whether or not the buffer may be read from or written to + respectively. By default the buffer is readable but not writable. + The last argument optionally specifies a size beyond which the + buffer may not be grown. "), @@ -5679,10 +5651,12 @@ Millisecond(v) "), -("Base","read","read(stream, type) +("Base","read","read(stream, type, dims) - Read a value of the given type from a stream, in canonical binary - representation. + Read a series of values of the given type from a stream, in + canonical binary representation. \"dims\" is either a tuple or a + series of integer arguments specifying the size of \"Array\" to + return. "), @@ -5862,13 +5836,10 @@ Millisecond(v) "), -("Base","redirect_stdout","redirect_stdout() +("Base","redirect_stdout","redirect_stdout(stream) - Create a pipe to which all C and Julia level STDOUT output will be - redirected. Returns a tuple (rd,wr) representing the pipe ends. - Data written to STDOUT may now be read from the rd end of the pipe. - The wr end is given for convenience in case the old STDOUT object - was cached by the user and needs to be replaced elsewhere. + Replace STDOUT by stream for all C and julia level output to + STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. "), @@ -5903,7 +5874,7 @@ Millisecond(v) ("Base","truncate","truncate(file, n) Resize the file or buffer given by the first argument to exactly - *n* bytes, filling previously unallocated space with '\\0' if the + *n* bytes, filling previously unallocated space with '0' if the file or buffer is grown "), @@ -5922,16 +5893,16 @@ Millisecond(v) Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than '\\n' are supported by passing - them as the second argument. + argument. EOL markers other than 'n' are supported by passing them + as the second argument. "), -("Base","PipeBuffer","PipeBuffer() +("Base","PipeBuffer","PipeBuffer(data::Vector{UInt8}[, maxsize]) - An IOBuffer that allows reading and performs writes by appending. - Seeking and truncating are not supported. See IOBuffer for the - available constructors. + Create a PipeBuffer to operate on a data vector, optionally + specifying a size beyond which the underlying Array may not be + grown. "), @@ -6056,9 +6027,10 @@ Millisecond(v) "), -("Base","readall","readall(stream::IO) +("Base","readall","readall(filename::AbstractString) - Read the entire contents of an I/O stream as a string. + Open \"filename\", read the entire contents as a string, then close + the file. Equivalent to \"open(readall, filename)\". "), @@ -6095,92 +6067,67 @@ Millisecond(v) "), -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. +("Base","readdlm","readdlm(source; options...) - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. "), -("Base","readdlm","readdlm(source, delim::Char, eol::Char; options...) +("Base","readdlm","readdlm(source; options...) - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. "), -("Base","readdlm","readdlm(source, delim::Char, T::Type; options...) +("Base","readdlm","readdlm(source; options...) - The end of line delimiter is taken as \"\\n\". + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. "), -("Base","readdlm","readdlm(source, delim::Char; options...) +("Base","readdlm","readdlm(source; options...) - The end of line delimiter is taken as \"\\n\". If all data is + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. "), -("Base","readdlm","readdlm(source, T::Type; options...) +("Base","readdlm","readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"\\n\". + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. "), ("Base","readdlm","readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"\\n\". If all data is + The end of line delimiter is taken as \"n\". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. "), -("Base","writedlm","writedlm(f, A, delim='\\t') +("Base","writedlm","writedlm(f, A, delim='t') Write \"A\" (a vector, matrix or an iterable collection of iterable rows) as text to \"f\" (either a filename string or an \"IO\" @@ -6224,7 +6171,8 @@ Millisecond(v) "), ("Base","base64encode","base64encode(writefunc, args...) -base64encode(args...) + + base64encode(args...) Given a \"write\"-like function \"writefunc\", which takes an I/O stream as its first argument, \"base64(writefunc, args...)\" calls @@ -6244,9 +6192,9 @@ base64encode(args...) "), ("Base","display","display(x) -display(d::Display, x) -display(mime, x) -display(d::Display, mime, x) + + display(d::Display, x) display(mime, x) display(d::Display, mime, + x) Display \"x\" using the topmost applicable display in the display stack, typically using the richest supported multimedia output for @@ -6268,9 +6216,9 @@ display(d::Display, mime, x) "), ("Base","redisplay","redisplay(x) -redisplay(d::Display, x) -redisplay(mime, x) -redisplay(d::Display, mime, x) + + redisplay(d::Display, x) redisplay(mime, x) redisplay(d::Display, + mime, x) By default, the \"redisplay\" functions simply call \"display\". However, some display backends may override \"redisplay\" to modify @@ -6282,7 +6230,8 @@ redisplay(d::Display, mime, x) "), ("Base","displayable","displayable(mime) -> Bool -displayable(d::Display, mime) -> Bool + + displayable(d::Display, mime) -> Bool Returns a boolean value indicating whether the given \"mime\" type (string) is displayable by any of the displays in the current @@ -6365,7 +6314,8 @@ displayable(d::Display, mime) -> Bool "), ("Base","popdisplay","popdisplay() -popdisplay(d::Display) + + popdisplay(d::Display) Pop the topmost backend off of the display-backend stack, or the topmost copy of \"d\" in the second variant. @@ -6430,8 +6380,8 @@ popdisplay(d::Display) creates a \"m\"-by-\"n\" \"Matrix{Int}\", linked to the file associated with stream \"s\". - A more portable file would need to encode the word size---32 bit or - 64 bit---and endianness information in the header. In practice, + A more portable file would need to encode the word size–-32 bit or + 64 bit–-and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). @@ -6452,30 +6402,52 @@ popdisplay(d::Display) "), -("Base","msync","msync(array) +("Base","msync","msync(ptr, len[, flags]) - Forces synchronization between the in-memory version of a memory- - mapped \"Array\" or \"BitArray\" and the on-disk version. + Forces synchronization of the \"mmap()\"ped memory region from + \"ptr\" to \"ptr+len\". Flags defaults to \"MS_SYNC\", but can be a + combination of \"MS_ASYNC\", \"MS_SYNC\", or \"MS_INVALIDATE\". See + your platform man page for specifics. The flags argument is not + valid on Windows. + + You may not need to call \"msync\", because synchronization is + performed at intervals automatically by the operating system. + However, you can call this directly if, for example, you are + concerned about losing the result of a long-running calculation. "), -("Base","connect","connect([host], port) -> TcpSocket +("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Connect to the host \"host\" on port \"port\" + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id \"pid\", specified + by \"config\" and return a pair of \"AsyncStream\" objects. + Messages from \"pid\" to current process will be read off + \"instrm\", while messages to be sent to \"pid\" will be written to + \"outstrm\". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP + socket connections in-between workers. "), -("Base","connect","connect(path) -> Pipe +("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Connect to the Named Pipe/Domain Socket at \"path\" + Implemented by cluster managers using custom transports. It should + establish a logical connection to worker with id \"pid\", specified + by \"config\" and return a pair of \"AsyncStream\" objects. + Messages from \"pid\" to current process will be read off + \"instrm\", while messages to be sent to \"pid\" will be written to + \"outstrm\". The custom transport implementation must ensure that + messages are delivered and received completely and in order. + \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP + socket connections in-between workers. "), -("Base","listen","listen([addr], port) -> TcpServer +("Base","listen","listen(path) -> PipeServer - Listen on port on the address specified by \"addr\". By default - this listens on localhost only. To listen on all interfaces pass, - \"IPv4(0)\" or \"IPv6(0)\" as appropriate. + Listens on/Creates a Named Pipe/Domain Socket "), @@ -6575,7 +6547,7 @@ popdisplay(d::Display) ("Base","send","send(socket::UDPSocket, host::IPv4, port::Integer, msg) - Send \"msg\" over \"socket to ``host:port\". + Send \"msg\" over \"socket to >>``< \"Hello \" * \"world\" + \"Hello world\" "), @@ -6933,7 +6909,8 @@ popdisplay(d::Display) "), ("Base","dot","dot(x, y) -⋅(x, y) + + ⋅(x, y) Compute the dot product. For complex vectors, the first vector is conjugated. @@ -6950,7 +6927,8 @@ popdisplay(d::Display) "), ("Base","cross","cross(x, y) -×(x, y) + + ×(x, y) Compute the cross product of two 3-vectors. @@ -6962,11 +6940,22 @@ popdisplay(d::Display) Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: - \"A=factorize(A); x=A\\\\b; y=A\\\\C\". + \"A=factorize(A); x=Ab; y=AC\". "), -("Base","full","full(F) +("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a + \"QRCompactWYQ\" object, i.e. in the compact WY format + [Bischof1987], to a dense matrix. + + Optionally takes a \"thin\" Boolean argument, which if \"true\" + omits the columns that span the rows of \"R\" in the QR + factorization that are zero. The resulting matrix is the \"Q\" + in a thin QR factorization (sometimes called the reduced QR + factorization). If \"false\", returns a \"Q\" that spans all + rows of \"R\" in its corresponding QR factorization. Reconstruct the matrix \"A\" from the factorization \"F=factorize(A)\". @@ -6992,52 +6981,52 @@ popdisplay(d::Display) examples are shown in the table below. +-------------------------+---------------------------+----------------------------------------------+ - | Type of input \\\"A\\\" | Type of output \\\"F\\\" | Relationship between \\\"F\\\" and \\\"A\\\" | + | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | +-------------------------+---------------------------+----------------------------------------------+ - | \\\"Matrix()\\\" | \\\"LU\\\" | \\\"F[:L]*F[:U] == A[F[:p], :]\\\" | + | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | +-------------------------+---------------------------+----------------------------------------------+ - | \\\"Tridiagonal()\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | N/A | + | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | +-------------------------+---------------------------+----------------------------------------------+ - | \\\"SparseMatrixCSC()\\\" | \\\"UmfpackLU\\\" | \\\"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\\\" | + | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | +-------------------------+---------------------------+----------------------------------------------+ The individual components of the factorization \"F\" can be accessed by indexing: +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | \\\"LU\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | \\\"UmfpackLU\\\" | + | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:L]\\\" | \\\"L\\\" (lower triangular) part of \\\"LU\\\" | ✓ | | ✓ | + | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:U]\\\" | \\\"U\\\" (upper triangular) part of \\\"LU\\\" | ✓ | | ✓ | + | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:p]\\\" | (right) permutation \\\"Vector\\\" | ✓ | | ✓ | + | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:P]\\\" | (right) permutation \\\"Matrix\\\" | ✓ | | | + | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:q]\\\" | left permutation \\\"Vector\\\" | | | ✓ | + | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:Rs]\\\" | \\\"Vector\\\" of scaling factors | | | ✓ | + | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \\\"F[:(:)]\\\" | \\\"(L,U,p,q,Rs)\\\" components | | | ✓ | + | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | +-------------+-----------------------------------------+--------+--------------------------+---------------+ +--------------------+--------+--------------------------+---------------+ - | Supported function | \\\"LU\\\" | \\\"LU{T,Tridiagonal{T}}\\\" | \\\"UmfpackLU\\\" | + | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | +--------------------+--------+--------------------------+---------------+ - | \\\"/\\\" | ✓ | | | + | \"/\" | ✓ | | | +--------------------+--------+--------------------------+---------------+ - | \\\"\\\\\\\" | ✓ | ✓ | ✓ | + | \"\\\\\" | ✓ | ✓ | ✓ | +--------------------+--------+--------------------------+---------------+ - | \\\"cond\\\" | ✓ | | ✓ | + | \"cond\" | ✓ | | ✓ | +--------------------+--------+--------------------------+---------------+ - | \\\"det\\\" | ✓ | ✓ | ✓ | + | \"det\" | ✓ | ✓ | ✓ | +--------------------+--------+--------------------------+---------------+ - | \\\"logdet\\\" | ✓ | ✓ | | + | \"logdet\" | ✓ | ✓ | | +--------------------+--------+--------------------------+---------------+ - | \\\"logabsdet\\\" | ✓ | ✓ | | + | \"logabsdet\" | ✓ | ✓ | | +--------------------+--------+--------------------------+---------------+ - | \\\"size\\\" | ✓ | ✓ | | + | \"size\" | ✓ | ✓ | | +--------------------+--------+--------------------------+---------------+ "), @@ -7056,27 +7045,37 @@ popdisplay(d::Display) Compute the Cholesky factorization of a symmetric positive definite matrix \"A\" and return the matrix \"F\". If \"LU\" is \"Val{:U}\" - (Upper), \"F\" is of type \"UpperTriangular\" and \"A = F'*F\". If - \"LU\" is \"Val{:L}\" (Lower), \"F\" is of type \"LowerTriangular\" - and \"A = F*F'\". \"LU\" defaults to \"Val{:U}\". + (Upper), \"F\" is of type \"UpperTriangular\" and \"A = F'>>*< Cholesky +("Base","cholfact","cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite + matrix \"A\". A fill-reducing permutation is used. \"F = + cholfact(A)\" is most frequently used to solve systems of equations + with \"Fb\", but also the methods \"diag\", \"det\", \"logdet\" are + defined for \"F\". You can also extract individual factors from + \"F\", using \"F[:L]\". However, since pivoting is on by default, + the factorization is internally represented as \"A == + P'>>*<>*<>*<>*<>*<>*<>*<>*< LDLtFactorization +("Base","ldltfact","ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix \"A\". A fill-reducing permutation is used. \"F = + ldltfact(A)\" is most frequently used to solve systems of equations + with \"Fb\", but also the methods \"diag\", \"det\", \"logdet\" are + defined for \"F\". You can also extract individual factors from + \"F\", using \"F[:L]\". However, since pivoting is on by default, + the factorization is internally represented as \"A == + P'>>*<>*<>*<>*<>*<>*<>*<>*< F - - Computes the QR factorization of \"A\". The return type of \"F\" - depends on the element type of \"A\" and whether pivoting is - specified (with \"pivot==Val{true}\"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \\\"eltype(A)\\\" | \\\"pivot\\\" | Relationship between \\\"F\\\" and \\\"A\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \\\"QR\\\" | not \\\"BlasFloat\\\" | either | \\\"A==F[:Q]*F[:R]\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \\\"QRCompactWY\\\" | \\\"BlasFloat\\\" | \\\"Val{false}\\\" | \\\"A==F[:Q]*F[:R]\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \\\"QRPivoted\\\" | \\\"BlasFloat\\\" | \\\"Val{true}\\\" | \\\"A[:,F[:p]]==F[:Q]*F[:R]\\\" | - +------------------+-------------------+----------------+---------------------------------------+ - - \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", - \"Complex64\" or \"Complex128\". - - The individual components of the factorization \"F\" can be - accessed by indexing: +("Base","qrfact","qrfact(A) -> SPQR.Factorization - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \\\"QR\\\" | \\\"QRCompactWY\\\" | \\\"QRPivoted\\\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:Q]\\\" | \\\"Q\\\" (orthogonal/unitary) part of \\\"QR\\\" | ✓ (\\\"QRPackedQ\\\") | ✓ (\\\"QRCompactWYQ\\\") | ✓ (\\\"QRPackedQ\\\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:R]\\\" | \\\"R\\\" (upper right triangular) part of \\\"QR\\\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:p]\\\" | pivot \\\"Vector\\\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \\\"F[:P]\\\" | (pivot) permutation \\\"Matrix\\\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - - The following functions are available for the \"QR\" objects: - \"size\", \"\\\". When \"A\" is rectangular, \"\\\" will return a - least squares solution and if the solution is not unique, the one - with smallest norm is returned. - - Multiplication with respect to either thin or full \"Q\" is - allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A - \"Q\" matrix can be converted into a regular matrix with \"full()\" - which has a named argument \"thin\". - - Note: \"qrfact\" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the \"Q\" and \"R\" matrices can be stored compactly rather - as two separate dense matrices.The data contained in \"QR\" or - \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, - which is a compact representation of the rotation matrix: - - Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) - - where \\tau_i is the scale factor and v_i is the projection - vector associated with the i^{th} Householder elementary - reflector.The data contained in \"QRCompactWY\" can be used to - construct the \"QRCompactWYQ\" type, which is a compact - representation of the rotation matrix - - Q = I + Y T Y^T - - where \"Y\" is m \\times r lower trapezoidal and \"T\" is r - \\times r upper triangular. The *compact WY* representation - [Schreiber1989] is not to be confused with the older, *WY* - representation [Bischof1987]. (The LAPACK documentation uses - \"V\" in lieu of \"Y\".) - - [Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 - - [Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 + Compute the QR factorization of a sparse matrix \"A\". A fill- + reducing permutation is used. The main application of this type is + to solve least squares problems with \"\". The function calls the C + library SPQR and a few additional functions from the library are + wrapped but not exported. "), @@ -7245,8 +7195,8 @@ popdisplay(d::Display) Compute the QR factorization of a sparse matrix \"A\". A fill- reducing permutation is used. The main application of this type is - to solve least squares problems with \"\\\". The function calls the - C library SPQR and a few additional functions from the library are + to solve least squares problems with \"\". The function calls the C + library SPQR and a few additional functions from the library are wrapped but not exported. "), @@ -7279,7 +7229,7 @@ popdisplay(d::Display) Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix \"A\" and return a \"BunchKaufman\" object. The following functions are available for - \"BunchKaufman\" objects: \"size\", \"\\\", \"inv\", \"issym\", + \"BunchKaufman\" objects: \"size\", \"\", \"inv\", \"issym\", \"ishermitian\". "), @@ -7306,17 +7256,10 @@ popdisplay(d::Display) "), -("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - - Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" - for details on the \"balance\" keyword argument. +("Base","eig","eig(A, B) -> D, V - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) + Computes generalized eigenvalues and vectors of \"A\" with respect + to \"B\". \"eig\" is a wrapper around \"eigfact()\", extracting all parts of the factorization to a tuple; where possible, using \"eigfact()\" @@ -7378,29 +7321,14 @@ popdisplay(d::Display) "), -("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - - Computes the eigenvalue decomposition of \"A\", returning an - \"Eigen\" factorization object \"F\" which contains the eigenvalues - in \"F[:values]\" and the eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the - slice \"F[:vectors][:, k]\".) - - The following functions are available for \"Eigen\" objects: - \"inv\", \"det\". - - If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it - is possible to calculate only a subset of the eigenvalues by - specifying either a \"UnitRange\" \"irange\" covering indices of - the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower - and upper boundaries of the eigenvalues. +("Base","eigfact","eigfact(A, B) -> GeneralizedEigen - For general nonsymmetric matrices it is possible to specify how the - matrix is balanced before the eigenvector calculation. The option - \"permute=true\" permutes the matrix to become closer to upper - triangular, and \"scale=true\" scales the matrix by its diagonal - elements to make rows and columns more equal in norm. The default - is \"true\" for both options. + Computes the generalized eigenvalue decomposition of \"A\" and + \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" + which contains the generalized eigenvalues in \"F[:values]\" and + the generalized eigenvectors in the columns of the matrix + \"F[:vectors]\". (The \"k\"th generalized eigenvector can be + obtained from the slice \"F[:vectors][:, k]\".) "), @@ -7440,15 +7368,17 @@ popdisplay(d::Display) "), -("Base","schurfact","schurfact(A) -> Schur +("Base","schurfact","schurfact(A, B) -> GeneralizedSchur - Computes the Schur factorization of the matrix \"A\". The (quasi) - triangular Schur factor can be obtained from the \"Schur\" object - \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the - unitary/orthogonal Schur vectors can be obtained with - \"F[:vectors]\" or \"F[:Z]\" such that - \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" - can be obtained with \"F[:values]\". + Computes the Generalized Schur (or QZ) factorization of the + matrices \"A\" and \"B\". The (quasi) triangular Schur factors can + be obtained from the \"Schur\" object \"F\" with \"F[:S]\" and + \"F[:T]\", the left unitary/orthogonal Schur vectors can be + obtained with \"F[:left]\" or \"F[:Q]\" and the right + unitary/orthogonal Schur vectors can be obtained with \"F[:right]\" + or \"F[:Z]\" such that \"A=F[:left]*F[:S]*F[:right]'\" and + \"B=F[:left]*F[:T]*F[:right]'\". The generalized eigenvalues of + \"A\" and \"B\" can be obtained with \"F[:alpha]./F[:beta]\". "), @@ -7459,41 +7389,39 @@ popdisplay(d::Display) "), -("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] +("Base","schur","schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See \"schurfact()\" "), -("Base","ordschur","ordschur(Q, T, select) -> Schur +("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" - according to the logical array \"select\" returning a Schur object - \"F\". The selected eigenvalues appear in the leading diagonal of - \"F[:Schur]\" and the the corresponding leading columns of - \"F[:vectors]\" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via \"select\". + Reorders the Generalized Schur factorization of a Generalized Schur + object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(Q, T, select) -> Schur +("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", - overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + \"ordschur()\". "), -("Base","ordschur","ordschur(S, select) -> Schur +("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur - Reorders the Schur factorization \"S\" of type \"Schur\". + Reorders the Generalized Schur factorization of a Generalized Schur + object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(S, select) -> Schur +("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur - Reorders the Schur factorization \"S\" of type \"Schur\", - overwriting \"S\" in the process. See \"ordschur()\" + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See + \"ordschur()\". "), @@ -7517,24 +7445,17 @@ popdisplay(d::Display) "), -("Base","ordschur","ordschur(S, T, Q, Z, select) -> GeneralizedSchur +("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a matrix \"(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" - and returns a GeneralizedSchur object \"GS\". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of - \"A\" and \"B\" can still be obtained with - \"GS[:alpha]./GS[:beta]\". + Reorders the Generalized Schur factorization of a Generalized Schur + object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(S, T, Q, Z, select) -> GeneralizedSchur +("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices \"(S, T, Q, Z)\" in the process. See + Reorders the Generalized Schur factorization of a Generalized Schur + object by overwriting the object with the new factorization. See \"ordschur()\". "), @@ -7554,15 +7475,12 @@ popdisplay(d::Display) "), -("Base","svdfact","svdfact(A[, thin=true]) -> SVD +("Base","svdfact","svdfact(A, B) -> GeneralizedSVD - Compute the Singular Value Decomposition (SVD) of \"A\" and return - an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained - from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" - and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The algorithm - produces \"Vt\" and hence \"Vt\" is more efficient to extract than - \"V\". The default is to produce a thin decomposition. + Compute the generalized SVD of \"A\" and \"B\", returning a + \"GeneralizedSVD\" Factorization object \"F\", such that \"A = + F[:U]*F[:D1]*F[:R0]*F[:Q]'\" and \"B = + F[:V]*F[:D2]*F[:R0]*F[:Q]'\". "), @@ -7575,20 +7493,20 @@ popdisplay(d::Display) "), -("Base","svd","svd(A[, thin=true]) -> U, S, V +("Base","svd","svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around \"svdfact\" extracting all parts the factorization to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. Computes the SVD of A, returning \"U\", vector \"S\", - and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The default is - to produce a thin decomposition. + efficient. The function returns the generalized SVD of \"A\" and + \"B\", returning \"U\", \"V\", \"Q\", \"D1\", \"D2\", and \"R0\" + such that \"A = U*D1*R0*Q'\" and \"B = V*D2*R0*Q'\". "), -("Base","svdvals","svdvals(A) +("Base","svdvals","svdvals(A, B) - Returns the singular values of \"A\". + Return only the singular values from the generalized singular value + decomposition of \"A\" and \"B\". "), @@ -7625,9 +7543,10 @@ popdisplay(d::Display) "), -("Base","triu","triu(M) +("Base","triu","triu(M, k) - Upper triangle of a matrix. + Returns the upper triangle of \"M\" starting from the \"k\"th + superdiagonal. "), @@ -7638,9 +7557,10 @@ popdisplay(d::Display) "), -("Base","triu!","triu!(M) +("Base","triu!","triu!(M, k) - Upper triangle of a matrix, overwriting \"M\" in the process. + Returns the upper triangle of \"M\" starting from the \"k\"th + superdiagonal, overwriting \"M\" in the process. "), @@ -7651,9 +7571,10 @@ popdisplay(d::Display) "), -("Base","tril","tril(M) +("Base","tril","tril(M, k) - Lower triangle of a matrix. + Returns the lower triangle of \"M\" starting from the \"k\"th + subdiagonal. "), @@ -7664,9 +7585,10 @@ popdisplay(d::Display) "), -("Base","tril!","tril!(M) +("Base","tril!","tril!(M, k) - Lower triangle of a matrix, overwriting \"M\" in the process. + Returns the lower triangle of \"M\" starting from the \"k\"th + subdiagonal, overwriting \"M\" in the process. "), @@ -7698,10 +7620,6 @@ popdisplay(d::Display) "), -("Base","scale","scale(A, b) - -"), - ("Base","scale","scale(b, A) Scale an array \"A\" by a scalar \"b\", returning a new array. @@ -7717,7 +7635,18 @@ popdisplay(d::Display) "), -("Base","scale!","scale!(A, b) +("Base","scale","scale(b, A) + + Scale an array \"A\" by a scalar \"b\", returning a new array. + + If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" + scales each column \"i\" of \"A\" by \"b[i]\" (similar to + \"A*diagm(b)\"), while \"scale(b,A)\" scales each row \"i\" of + \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), returning a new + array. + + Note: for large \"A\", \"scale\" can be much faster than \"A .* b\" + or \"b .* A\", due to the use of BLAS. "), @@ -7734,7 +7663,20 @@ popdisplay(d::Display) "), -("Base","Tridiagonal","Tridiagonal(dl, d, du) +("Base","scale!","scale!(b, A) + + Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but + overwriting \"A\" in-place. + + If \"A\" is a matrix and \"b\" is a vector, then \"scale!(A,b)\" + scales each column \"i\" of \"A\" by \"b[i]\" (similar to + \"A*diagm(b)\"), while \"scale!(b,A)\" scales each row \"i\" of + \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), again operating in- + place on \"A\". + +"), + +("Base","Tridiagonal","Tridiagonal(dl, d, du) Construct a tridiagonal matrix from the lower diagonal, diagonal, and upper diagonal, respectively. The result is of type @@ -7806,14 +7748,16 @@ popdisplay(d::Display) ("Base","condskeel","condskeel(M[, x, p]) + condskeel(M[, x, p]) + \\kappa_S(M, p) & = \\left\\Vert \\left\\vert M \\right\\vert \\left\\vert M^{-1} \\right\\vert \\right\\Vert_p \\\\ \\kappa_S(M, x, p) & = \\left\\Vert \\left\\vert M \\right\\vert \\left\\vert M^{-1} \\right\\vert \\left\\vert x \\right\\vert \\right\\Vert_p - Skeel condition number \\kappa_S of the matrix \"M\", optionally - with respect to the vector \"x\", as computed using the operator + Skeel condition number kappa_S of the matrix \"M\", optionally with + respect to the vector \"x\", as computed using the operator \"p\"-norm. \"p\" is \"Inf\" by default, if not provided. Valid values for \"p\" are \"1\", \"2\", or \"Inf\". @@ -7835,10 +7779,11 @@ popdisplay(d::Display) "), -("Base","logdet","logdet(M) +("Base","logabsdet","logabsdet(M) - Log of matrix determinant. Equivalent to \"log(det(M))\", but may - provide increased accuracy and/or speed. + Log of absolute value of determinant of real matrix. Equivalent to + \"(log(abs(det(M))), sign(det(M)))\", but may provide increased + accuracy and/or speed. "), @@ -7876,21 +7821,21 @@ popdisplay(d::Display) For more information, see [8859], [B96], [S84], [KY88]. [8859] Issue 8859, \"Fix least squares\", - https://github.com/JuliaLang/julia/pull/8859 + https://github.com/JuliaLang/julia/pull/8859 [B96] Åke Björck, \"Numerical Methods for Least Squares - Problems\", SIAM Press, Philadelphia, 1996, \"Other Titles in - Applied Mathematics\", Vol. 51. doi:10.1137/1.9781611971484 + Problems\", SIAM Press, Philadelphia, 1996, \"Other Titles in + Applied Mathematics\", Vol. 51. doi:10.1137/1.9781611971484 [S84] G. W. Stewart, \"Rank Degeneracy\", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 [KY88] Konstantinos Konstantinides and Kung Yao, - \"Statistical analysis of effective singular values in - matrix rank determination\", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 + \"Statistical analysis of effective singular values in + matrix rank determination\", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 "), @@ -7931,21 +7876,9 @@ popdisplay(d::Display) "), -("Base","linreg","linreg(x, y) -> [a; b] - - Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is - the closest line to the given points \"(x,y)\". In other words, - this function determines parameters \"[a, b]\" that minimize the - squared error between \"y\" and \"a+b*x\". - - **Example**: +("Base","linreg","linreg(x, y, w) - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, \"o\") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + Weighted least-squares linear regression. "), @@ -8060,8 +7993,8 @@ popdisplay(d::Display) respectively. If \"B\" is provided, the generalized eigenproblem is solved. - The following keyword arguments are supported: - * \"nev\": Number of eigenvalues + The following keyword arguments are supported: * \"nev\": + Number of eigenvalues * \"ncv\": Number of Krylov vectors used in the computation; should satisfy @@ -8076,21 +8009,21 @@ popdisplay(d::Display) below. +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\"which\\\" | type of eigenvalues | + | \"which\" | type of eigenvalues | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":LM\\\" | eigenvalues of largest magnitude (default) | + | \":LM\" | eigenvalues of largest magnitude (default) | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":SM\\\" | eigenvalues of smallest magnitude | + | \":SM\" | eigenvalues of smallest magnitude | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":LR\\\" | eigenvalues of largest real part | + | \":LR\" | eigenvalues of largest real part | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":SR\\\" | eigenvalues of smallest real part | + | \":SR\" | eigenvalues of smallest real part | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":LI\\\" | eigenvalues of largest imaginary part (nonsymmetric or complex \\\"A\\\" only) | + | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":SI\\\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \\\"A\\\" only) | + | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \\\":BE\\\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \\\"A\\\" only) | + | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | +-----------+-----------------------------------------------------------------------------------------------------------------------------+ * \"tol\": tolerance (tol \\le 0.0 defaults to @@ -8115,18 +8048,19 @@ popdisplay(d::Display) \"nmult\", as well as the final residual vector \"resid\". Note: The \"sigma\" and \"which\" keywords interact: the - description of eigenvalues searched for by \"which\" do _not_ - necessarily refer to the eigenvalues of \"A\", but rather the - linear operator constructed by the specification of the iteration - mode implied by \"sigma\". + description of eigenvalues searched for by \"which\" do _not_ + necessarily refer to the eigenvalues of \"A\", but rather the + linear operator constructed by the specification of the iteration + mode implied by \"sigma\". - +-----------------+------------------------------------+------------------------------------+ - | \\\"sigma\\\" | iteration mode | \\\"which\\\" refers to eigenvalues of | - +-----------------+------------------------------------+------------------------------------+ - | \\\"nothing\\\" | ordinary (forward) | A | - +-----------------+------------------------------------+------------------------------------+ - | real or complex | inverse with level shift \\\"sigma\\\" | (A - \\\\sigma I )^{-1} | - +-----------------+------------------------------------+------------------------------------+ + +––––––––-+––––––––––––––––––+––––––––––––––––––+ | \"sigma\" + | iteration mode | \"which\" refers to + eigenvalues of | + +––––––––-+––––––––––––––––––+––––––––––––––––––+ | \"nothing\" + | ordinary (forward) | A + | +––––––––-+––––––––––––––––––+––––––––––––––––––+ | real or + complex | inverse with level shift \"sigma\" | (A - sigma I )^{-1} + | +––––––––-+––––––––––––––––––+––––––––––––––––––+ "), @@ -8135,11 +8069,10 @@ popdisplay(d::Display) \"svds\" computes largest singular values \"s\" of \"A\" using Lanczos or Arnoldi iterations. Uses \"eigs()\" underneath. - Inputs are: - * \"A\": Linear operator. It can either subtype of - \"AbstractArray\" (e.g., sparse matrix) or duck typed. For - duck typing \"A\" has to support \"size(A)\", \"eltype(A)\", - \"A * vector\" and \"A' * vector\". + Inputs are: * \"A\": Linear operator. It can either subtype of + \"AbstractArray\" (e.g., sparse matrix) or duck typed. For + duck typing \"A\" has to support \"size(A)\", \"eltype(A)\", + \"A * vector\" and \"A' * vector\". * \"nsv\": Number of singular values. @@ -8252,17 +8185,17 @@ popdisplay(d::Display) ("Base.LinAlg.BLAS","syrk!","syrk!(uplo, trans, alpha, A, beta, C) Rank-k update of the symmetric matrix \"C\" as \"alpha*A*A.' + - beta*C\" or \"alpha*A.'*A + beta*C\" according to whether \"trans\" - is 'N' or 'T'. When \"uplo\" is 'U' the upper triangle of \"C\" is - updated ('L' for lower triangle). Returns \"C\". + beta*C\" or \"alpha*A.'>>*<>*<>*<>*<>*<>*< \"Hello \" * \"world\" + \"Hello world\" "), @@ -8568,9 +8502,13 @@ popdisplay(d::Display) "), -("Base","^","^(x, y) +("Base","^","^(s, n) + + Repeat \"n\" times the string \"s\". The \"^\" operator is an alias + to this function. - Exponentiation operator. + julia> \"Test \"^3 + \"Test Test Test \" "), @@ -8629,7 +8567,8 @@ popdisplay(d::Display) "), ("Base","div","div(x, y) -÷(x, y) + + ÷(x, y) The quotient from Euclidean division. Computes \"x/y\", truncated to an integer. @@ -8667,7 +8606,8 @@ popdisplay(d::Display) "), ("Base","rem","rem(x, y) -%(x, y) + + %(x, y) Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than \"y\". This value is @@ -8789,7 +8729,8 @@ popdisplay(d::Display) "), ("Base","!=","!=(x, y) -≠(x, y) + + ≠(x, y) Not-equals comparison operator. Always gives the opposite answer as \"==\". New types should generally not implement this, and rely on @@ -8798,14 +8739,16 @@ popdisplay(d::Display) "), ("Base","===","===(x, y) -≡(x, y) + + ≡(x, y) See the \"is()\" operator "), ("Base","!==","!==(x, y) -≢(x, y) + + ≢(x, y) Equivalent to \"!is(x, y)\" @@ -8822,7 +8765,8 @@ popdisplay(d::Display) "), ("Base","<=","<=(x, y) -≤(x, y) + + ≤(x, y) Less-than-or-equals comparison operator. @@ -8837,7 +8781,8 @@ popdisplay(d::Display) "), ("Base",">=",">=(x, y) -≥(x, y) + + ≥(x, y) Greater-than-or-equals comparison operator. @@ -8850,7 +8795,8 @@ popdisplay(d::Display) "), ("Base",".!=",".!=(x, y) -.≠(x, y) + + .≠(x, y) Element-wise not-equals comparison operator. @@ -8863,7 +8809,8 @@ popdisplay(d::Display) "), ("Base",".<=",".<=(x, y) -.≤(x, y) + + .≤(x, y) Element-wise less-than-or-equals comparison operator. @@ -8876,7 +8823,8 @@ popdisplay(d::Display) "), ("Base",".>=",".>=(x, y) -.≥(x, y) + + .≥(x, y) Element-wise greater-than-or-equals comparison operator. @@ -8935,13 +8883,13 @@ popdisplay(d::Display) ("Base","A_ldiv_Bc","A_ldiv_Bc(a, b) - Matrix operator A \\ B^H + Matrix operator A B^H "), ("Base","A_ldiv_Bt","A_ldiv_Bt(a, b) - Matrix operator A \\ B^T + Matrix operator A B^T "), @@ -8985,13 +8933,13 @@ popdisplay(d::Display) ("Base","Ac_ldiv_B","Ac_ldiv_B(...) - Matrix operator A^H \\ B + Matrix operator A^H B "), ("Base","Ac_ldiv_Bc","Ac_ldiv_Bc(...) - Matrix operator A^H \\ B^H + Matrix operator A^H B^H "), @@ -9021,13 +8969,13 @@ popdisplay(d::Display) ("Base","At_ldiv_B","At_ldiv_B(...) - Matrix operator A^T \\ B + Matrix operator A^T B "), ("Base","At_ldiv_Bt","At_ldiv_Bt(...) - Matrix operator A^T \\ B^T + Matrix operator A^T B^T "), @@ -9060,16 +9008,17 @@ popdisplay(d::Display) Inexact equality comparison - behaves slightly different depending on types of input args: - * For \"FloatingPoint\" numbers, \"isapprox\" returns \"true\" if - \"abs(x-y) <= atol + rtol*max(abs(x), abs(y))\". + * For \"FloatingPoint\" numbers, \"isapprox\" returns \"true\" + if \"abs(x-y) <= atol + rtol*max(abs(x), abs(y))\". - * For \"Integer\" and \"Rational\" numbers, \"isapprox\" returns - \"true\" if \"abs(x-y) <= atol\". The *rtol* argument is ignored. - If one of \"x\" and \"y\" is \"FloatingPoint\", the other is - promoted, and the method above is called instead. + * For \"Integer\" and \"Rational\" numbers, \"isapprox\" + returns \"true\" if \"abs(x-y) <= atol\". The *rtol* argument + is ignored. If one of \"x\" and \"y\" is \"FloatingPoint\", + the other is promoted, and the method above is called + instead. - * For \"Complex\" numbers, the distance in the complex plane is - compared, using the same criterion as above. + * For \"Complex\" numbers, the distance in the complex plane + is compared, using the same criterion as above. For default tolerance arguments, \"maxeps = max(eps(abs(x)), eps(abs(y)))\". @@ -9114,15 +9063,15 @@ popdisplay(d::Display) ("Base","sinpi","sinpi(x) - Compute \\sin(\\pi x) more accurately than \"sin(pi*x)\", - especially for large \"x\". + Compute sin(pi x) more accurately than \"sin(pi*x)\", especially + for large \"x\". "), ("Base","cospi","cospi(x) - Compute \\cos(\\pi x) more accurately than \"cos(pi*x)\", - especially for large \"x\". + Compute cos(pi x) more accurately than \"cos(pi*x)\", especially + for large \"x\". "), @@ -9321,14 +9270,14 @@ popdisplay(d::Display) ("Base","sinc","sinc(x) - Compute \\sin(\\pi x) / (\\pi x) if x \\neq 0, and 1 if x = 0. + Compute sin(pi x) / (pi x) if x neq 0, and 1 if x = 0. "), ("Base","cosc","cosc(x) - Compute \\cos(\\pi x) / x - \\sin(\\pi x) / (\\pi x^2) if x \\neq - 0, and 0 if x = 0. This is the derivative of \"sinc(x)\". + Compute cos(pi x) / x - sin(pi x) / (pi x^2) if x neq 0, and 0 if x + = 0. This is the derivative of \"sinc(x)\". "), @@ -9346,18 +9295,14 @@ popdisplay(d::Display) ("Base","hypot","hypot(x, y) - Compute the \\sqrt{x^2+y^2} avoiding overflow and underflow + Compute the sqrt{x^2+y^2} avoiding overflow and underflow "), -("Base","log","log(x) - - Compute the natural logarithm of \"x\". Throws \"DomainError\" for - negative \"Real\" arguments. Use complex negative arguments to - obtain complex results. +("Base","log","log(b, x) - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. + Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" + for negative \"Real\" arguments. "), @@ -9375,1496 +9320,247 @@ popdisplay(d::Display) "), -("Base","log10","log10(x) - - Compute the logarithm of \"x\" to base 10. Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log1p","log1p(x) - - Accurate natural logarithm of \"1+x\". Throws \"DomainError\" for - \"Real\" arguments less than -1. - - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. - -"), - -("Base","frexp","frexp(val) - - Return \"(x,exp)\" such that \"x\" has a magnitude in the interval - \"[1/2, 1)\" or 0, and val = x \\times 2^{exp}. - -"), - -("Base","exp","exp(x) - - Compute e^x - -"), - -("Base","exp2","exp2(x) - - Compute 2^x - -"), - -("Base","exp10","exp10(x) - - Compute 10^x - -"), - -("Base","ldexp","ldexp(x, n) - - Compute x \\times 2^n - -"), - -("Base","modf","modf(x) - - Return a tuple (fpart,ipart) of the fractional and integral parts - of a number. Both parts have the same sign as the argument. - -"), - -("Base","expm1","expm1(x) - - Accurately compute e^x-1 - -"), - -("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) - - \"round(x)\" rounds \"x\" to an integer value according to the - default rounding mode (see \"get_rounding()\"), returning a value - of the same type as \"x\". By default (\"RoundNearest\"), this will - round to the nearest integer, with ties (fractional values of 0.5) - being rounded to the even integer. - - julia> round(1.7) - 2.0 - - julia> round(1.5) - 2.0 - - julia> round(2.5) - 2.0 - - The optional \"RoundingMode\" argument will change how the number - gets rounded. - - \"round(T, x, [r::RoundingMode])\" converts the result to type - \"T\", throwing an \"InexactError\" if the value is not - representable. - - \"round(x, digits)\" rounds to the specified number of digits after - the decimal place (or before if negative). \"round(x, digits, - base)\" rounds using a base other than 10. - - julia> round(pi, 2) - 3.14 - - julia> round(pi, 3, 2) - 3.125 - - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the \"Float64\" value represented by \"1.15\" is - actually *less* than 1.15, yet will be rounded to 1.2. - - julia> x = 1.15 - 1.15 - - julia> @sprintf \"%.20f\" x - \"1.14999999999999991118\" - - julia> x < 115//100 - true - - julia> round(x, 1) - 1.2 - -"), - -("Base","RoundingMode","RoundingMode - - A type which controls rounding behavior. Currently supported - rounding modes are: - - * \"RoundNearest\" (default) - - * \"RoundNearestTiesAway\" - - * \"RoundNearestTiesUp\" - - * \"RoundToZero\" - - * \"RoundUp\" - - * \"RoundDown\" - -"), - -("Base","RoundNearest","RoundNearest - - The default rounding mode. Rounds to the nearest integer, with ties - (fractional values of 0.5) being rounded to the nearest even - integer. - -"), - -("Base","RoundNearestTiesAway","RoundNearestTiesAway - - Rounds to nearest integer, with ties rounded away from zero (C/C++ - \"round()\" behaviour). - -"), - -("Base","RoundNearestTiesUp","RoundNearestTiesUp - - Rounds to nearest integer, with ties rounded toward positive - infinity (Java/JavaScript \"round()\" behaviour). - -"), - -("Base","RoundToZero","RoundToZero - - \"round()\" using this rounding mode is an alias for \"trunc()\". - -"), - -("Base","RoundUp","RoundUp - - \"round()\" using this rounding mode is an alias for \"ceil()\". - -"), - -("Base","RoundDown","RoundDown - - \"round()\" using this rounding mode is an alias for \"floor()\". - -"), - -("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) - - Returns the nearest integral value of the same type as the complex- - valued \"z\" to \"z\", breaking ties using the specified - \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding - the real components while the second is used for rounding the - imaginary components. - -"), - -("Base","ceil","ceil([T], x[, digits[, base]]) - - \"ceil(x)\" returns the nearest integral value of the same type as - \"x\" that is greater than or equal to \"x\". - - \"ceil(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","floor","floor([T], x[, digits[, base]]) - - \"floor(x)\" returns the nearest integral value of the same type as - \"x\" that is less than or equal to \"x\". - - \"floor(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","trunc","trunc([T], x[, digits[, base]]) - - \"trunc(x)\" returns the nearest integral value of the same type as - \"x\" whose absolute value is less than or equal to \"x\". - - \"trunc(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","unsafe_trunc","unsafe_trunc(T, x) - - \"unsafe_trunc(T, x)\" returns the nearest integral value of type - \"T\" whose absolute value is less than or equal to \"x\". If the - value is not representable by \"T\", an arbitrary value will be - returned. - -"), - -("Base","signif","signif(x, digits[, base]) - - Rounds (in the sense of \"round\") \"x\" so that there are - \"digits\" significant digits, under a base \"base\" - representation, default 10. E.g., \"signif(123.456, 2)\" is - \"120.0\", and \"signif(357.913, 4, 2)\" is \"352.0\". - -"), - -("Base","min","min(x, y, ...) - - Return the minimum of the arguments. Operates elementwise over - arrays. - -"), - -("Base","max","max(x, y, ...) - - Return the maximum of the arguments. Operates elementwise over - arrays. - -"), - -("Base","minmax","minmax(x, y) - - Return \"(min(x,y), max(x,y))\". See also: \"extrema()\" that - returns \"(minimum(x), maximum(x))\" - -"), - -("Base","clamp","clamp(x, lo, hi) - - Return x if \"lo <= x <= hi\". If \"x < lo\", return \"lo\". If \"x - > hi\", return \"hi\". Arguments are promoted to a common type. - Operates elementwise over \"x\" if it is an array. - -"), - -("Base","abs","abs(x) - - Absolute value of \"x\" - -"), - -("Base","abs2","abs2(x) - - Squared absolute value of \"x\" - -"), - -("Base","copysign","copysign(x, y) - - Return \"x\" such that it has the same sign as \"y\" - -"), - -("Base","sign","sign(x) - - Return \"+1\" if \"x\" is positive, \"0\" if \"x == 0\", and \"-1\" - if \"x\" is negative. - -"), - -("Base","signbit","signbit(x) - - Returns \"true\" if the value of the sign of \"x\" is negative, - otherwise \"false\". - -"), - -("Base","flipsign","flipsign(x, y) - - Return \"x\" with its sign flipped if \"y\" is negative. For - example \"abs(x) = flipsign(x,x)\". - -"), - -("Base","sqrt","sqrt(x) - - Return \\sqrt{x}. Throws \"DomainError\" for negative \"Real\" - arguments. Use complex negative arguments instead. The prefix - operator \"√\" is equivalent to \"sqrt\". - -"), - -("Base","isqrt","isqrt(n) - - Integer square root: the largest integer \"m\" such that \"m*m <= - n\". - -"), - -("Base","cbrt","cbrt(x) - - Return x^{1/3}. The prefix operator \"∛\" is equivalent to - \"cbrt\". - -"), - -("Base","erf","erf(x) - - Compute the error function of \"x\", defined by - \\frac{2}{\\sqrt{\\pi}} \\int_0^x e^{-t^2} dt for arbitrary complex - \"x\". - -"), - -("Base","erfc","erfc(x) - - Compute the complementary error function of \"x\", defined by 1 - - \\operatorname{erf}(x). - -"), - -("Base","erfcx","erfcx(x) - - Compute the scaled complementary error function of \"x\", defined - by e^{x^2} \\operatorname{erfc}(x). Note also that - \\operatorname{erfcx}(-ix) computes the Faddeeva function w(x). - -"), - -("Base","erfi","erfi(x) - - Compute the imaginary error function of \"x\", defined by -i - \\operatorname{erf}(ix). - -"), - -("Base","dawson","dawson(x) - - Compute the Dawson function (scaled imaginary error function) of - \"x\", defined by \\frac{\\sqrt{\\pi}}{2} e^{-x^2} - \\operatorname{erfi}(x). - -"), - -("Base","erfinv","erfinv(x) - - Compute the inverse error function of a real \"x\", defined by - \\operatorname{erf}(\\operatorname{erfinv}(x)) = x. - -"), - -("Base","erfcinv","erfcinv(x) - - Compute the inverse error complementary function of a real \"x\", - defined by \\operatorname{erfc}(\\operatorname{erfcinv}(x)) = x. - -"), - -("Base","real","real(z) - - Return the real part of the complex number \"z\" - -"), - -("Base","imag","imag(z) - - Return the imaginary part of the complex number \"z\" - -"), - -("Base","reim","reim(z) - - Return both the real and imaginary parts of the complex number - \"z\" - -"), - -("Base","conj","conj(z) - - Compute the complex conjugate of a complex number \"z\" - -"), - -("Base","angle","angle(z) - - Compute the phase angle in radians of a complex number \"z\" - -"), - -("Base","cis","cis(z) - - Return \\exp(iz). - -"), - -("Base","binomial","binomial(n, k) - - Number of ways to choose \"k\" out of \"n\" items - -"), - -("Base","factorial","factorial(n) - - Factorial of \"n\". If \"n\" is an \"Integer\", the factorial is - computed as an integer (promoted to at least 64 bits). Note that - this may overflow if \"n\" is not small, but you can use - \"factorial(big(n))\" to compute the result exactly in arbitrary - precision. If \"n\" is not an \"Integer\", \"factorial(n)\" is - equivalent to \"gamma(n+1)\". - -"), - -("Base","factorial","factorial(n, k) - - Compute \"factorial(n)/factorial(k)\" - -"), - -("Base","factor","factor(n) -> Dict - - Compute the prime factorization of an integer \"n\". Returns a - dictionary. The keys of the dictionary correspond to the factors, - and hence are of the same type as \"n\". The value associated with - each key indicates the number of times the factor appears in the - factorization. - - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 - -"), - -("Base","gcd","gcd(x, y) - - Greatest common (positive) divisor (or zero if x and y are both - zero). - -"), - -("Base","lcm","lcm(x, y) - - Least common (non-negative) multiple. - -"), - -("Base","gcdx","gcdx(x, y) - - Computes the greatest common (positive) divisor of \"x\" and \"y\" - and their Bézout coefficients, i.e. the integer coefficients \"u\" - and \"v\" that satisfy ux+vy = d = gcd(x,y). - - julia> gcdx(12, 42) - (6,-3,1) - - julia> gcdx(240, 46) - (2,-9,47) - - Note: Bézout coefficients are *not* uniquely defined. \"gcdx\" - returns the minimal Bézout coefficients that are computed by the - extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, - Algorithm X.) These coefficients \"u\" and \"v\" are minimal in - the sense that |u| < |\\frac y d and |v| < |\\frac x d. - Furthermore, the signs of \"u\" and \"v\" are chosen so that - \"d\" is positive. - -"), - -("Base","ispow2","ispow2(n) -> Bool - - Test whether \"n\" is a power of two - -"), - -("Base","nextpow2","nextpow2(n) - - The smallest power of two not less than \"n\". Returns 0 for - \"n==0\", and returns \"-nextpow2(-n)\" for negative arguments. - -"), - -("Base","prevpow2","prevpow2(n) - - The largest power of two not greater than \"n\". Returns 0 for - \"n==0\", and returns \"-prevpow2(-n)\" for negative arguments. - -"), - -("Base","nextpow","nextpow(a, x) - - The smallest \"a^n\" not less than \"x\", where \"n\" is a non- - negative integer. \"a\" must be greater than 1, and \"x\" must be - greater than 0. - -"), - -("Base","prevpow","prevpow(a, x) - - The largest \"a^n\" not greater than \"x\", where \"n\" is a non- - negative integer. \"a\" must be greater than 1, and \"x\" must not - be less than 1. - -"), - -("Base","nextprod","nextprod([k_1, k_2, ...], n) - - Next integer not less than \"n\" that can be written as \\prod - k_i^{p_i} for integers p_1, p_2, etc. - -"), - -("Base","prevprod","prevprod([k_1, k_2, ...], n) - - Previous integer not greater than \"n\" that can be written as - \\prod k_i^{p_i} for integers p_1, p_2, etc. - -"), - -("Base","invmod","invmod(x, m) - - Take the inverse of \"x\" modulo \"m\": \"y\" such that xy = 1 - \\pmod m - -"), - -("Base","powermod","powermod(x, p, m) - - Compute x^p \\pmod m - -"), - -("Base","gamma","gamma(x) - - Compute the gamma function of \"x\" - -"), - -("Base","lgamma","lgamma(x) - - Compute the logarithm of the absolute value of \"gamma()\" for - \"Real\" \"x\", while for \"Complex\" \"x\" it computes the - logarithm of \"gamma(x)\". - -"), - -("Base","lfact","lfact(x) - - Compute the logarithmic factorial of \"x\" - -"), - -("Base","digamma","digamma(x) - - Compute the digamma function of \"x\" (the logarithmic derivative - of \"gamma(x)\") - -"), - -("Base","invdigamma","invdigamma(x) - - Compute the inverse digamma function of \"x\". - -"), - -("Base","trigamma","trigamma(x) - - Compute the trigamma function of \"x\" (the logarithmic second - derivative of \"gamma(x)\") - -"), - -("Base","polygamma","polygamma(m, x) - - Compute the polygamma function of order \"m\" of argument \"x\" - (the \"(m+1)th\" derivative of the logarithm of \"gamma(x)\") - -"), - -("Base","airy","airy(k, x) - - kth derivative of the Airy function \\operatorname{Ai}(x). - -"), - -("Base","airyai","airyai(x) - - Airy function \\operatorname{Ai}(x). - -"), - -("Base","airyprime","airyprime(x) - - Airy function derivative \\operatorname{Ai}'(x). - -"), - -("Base","airyaiprime","airyaiprime(x) - - Airy function derivative \\operatorname{Ai}'(x). - -"), - -("Base","airybi","airybi(x) - - Airy function \\operatorname{Bi}(x). - -"), - -("Base","airybiprime","airybiprime(x) - - Airy function derivative \\operatorname{Bi}'(x). - -"), - -("Base","airyx","airyx(k, x) - - scaled kth derivative of the Airy function, return - \\operatorname{Ai}(x) e^{\\frac{2}{3} x \\sqrt{x}} for \"k == 0 || - k == 1\", and \\operatorname{Ai}(x) e^{- \\left| \\operatorname{Re} - \\left( \\frac{2}{3} x \\sqrt{x} \\right) \\right|} for \"k == 2 || - k == 3\". - -"), - -("Base","besselj0","besselj0(x) - - Bessel function of the first kind of order 0, J_0(x). - -"), - -("Base","besselj1","besselj1(x) - - Bessel function of the first kind of order 1, J_1(x). - -"), - -("Base","besselj","besselj(nu, x) - - Bessel function of the first kind of order \"nu\", J_\\nu(x). - -"), - -("Base","besseljx","besseljx(nu, x) - - Scaled Bessel function of the first kind of order \"nu\", J_\\nu(x) - e^{- | \\operatorname{Im}(x) |}. - -"), - -("Base","bessely0","bessely0(x) - - Bessel function of the second kind of order 0, Y_0(x). - -"), - -("Base","bessely1","bessely1(x) - - Bessel function of the second kind of order 1, Y_1(x). - -"), - -("Base","bessely","bessely(nu, x) - - Bessel function of the second kind of order \"nu\", Y_\\nu(x). - -"), - -("Base","besselyx","besselyx(nu, x) - - Scaled Bessel function of the second kind of order \"nu\", - Y_\\nu(x) e^{- | \\operatorname{Im}(x) |}. - -"), - -("Base","hankelh1","hankelh1(nu, x) - - Bessel function of the third kind of order \"nu\", H^{(1)}_\\nu(x). - -"), - -("Base","hankelh1x","hankelh1x(nu, x) - - Scaled Bessel function of the third kind of order \"nu\", - H^{(1)}_\\nu(x) e^{-x i}. - -"), - -("Base","hankelh2","hankelh2(nu, x) - - Bessel function of the third kind of order \"nu\", H^{(2)}_\\nu(x). - -"), - -("Base","hankelh2x","hankelh2x(nu, x) - - Scaled Bessel function of the third kind of order \"nu\", - H^{(2)}_\\nu(x) e^{x i}. - -"), - -("Base","besselh","besselh(nu, k, x) - - Bessel function of the third kind of order \"nu\" (Hankel - function). \"k\" is either 1 or 2, selecting \"hankelh1\" or - \"hankelh2\", respectively. - -"), - -("Base","besseli","besseli(nu, x) - - Modified Bessel function of the first kind of order \"nu\", - I_\\nu(x). - -"), - -("Base","besselix","besselix(nu, x) - - Scaled modified Bessel function of the first kind of order \"nu\", - I_\\nu(x) e^{- | \\operatorname{Re}(x) |}. - -"), - -("Base","besselk","besselk(nu, x) - - Modified Bessel function of the second kind of order \"nu\", - K_\\nu(x). - -"), - -("Base","besselkx","besselkx(nu, x) - - Scaled modified Bessel function of the second kind of order \"nu\", - K_\\nu(x) e^x. - -"), - -("Base","beta","beta(x, y) - - Euler integral of the first kind \\operatorname{B}(x,y) = - \\Gamma(x)\\Gamma(y)/\\Gamma(x+y). - -"), - -("Base","lbeta","lbeta(x, y) - - Natural logarithm of the absolute value of the beta function - \\log(|\\operatorname{B}(x,y)|). - -"), - -("Base","eta","eta(x) - - Dirichlet eta function \\eta(s) = - \\sum^\\infty_{n=1}(-)^{n-1}/n^{s}. - -"), - -("Base","zeta","zeta(s) - - Riemann zeta function \\zeta(s). - -"), - -("Base","zeta","zeta(s, z) - - Hurwitz zeta function \\zeta(s, z). (This is equivalent to the - Riemann zeta function \\zeta(s) for the case of \"z=1\".) - -"), - -("Base","ndigits","ndigits(n, b) - - Compute the number of digits in number \"n\" written in base \"b\". - -"), - -("Base","widemul","widemul(x, y) - - Multiply \"x\" and \"y\", giving the result as a larger type. - -"), - -("Base","@evalpoly","@evalpoly(z, c...) - - Evaluate the polynomial \\sum_k c[k] z^{k-1} for the coefficients - \"c[1]\", \"c[2]\", ...; that is, the coefficients are given in - ascending order by power of \"z\". This macro expands to efficient - inline code that uses either Horner's method or, for complex \"z\", - a more efficient Goertzel-like algorithm. - -"), - -("Base","mean","mean(v[, region]) - - Compute the mean of whole array \"v\", or optionally along the - dimensions in \"region\". Note: Julia does not ignore \"NaN\" - values in the computation. For applications requiring the handling - of missing data, the \"DataArray\" package is recommended. - -"), - -("Base","mean!","mean!(r, v) - - Compute the mean of \"v\" over the singleton dimensions of \"r\", - and write results to \"r\". - -"), - -("Base","std","std(v[, region]) - - Compute the sample standard deviation of a vector or array \"v\", - optionally along dimensions in \"region\". The algorithm returns an - estimator of the generative distribution's standard deviation under - the assumption that each entry of \"v\" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating \"sqrt(sum((v - mean(v)).^2) / (length(v) - 1))\". - Note: Julia does not ignore \"NaN\" values in the computation. For - applications requiring the handling of missing data, the - \"DataArray\" package is recommended. - -"), - -("Base","stdm","stdm(v, m) - - Compute the sample standard deviation of a vector \"v\" with known - mean \"m\". Note: Julia does not ignore \"NaN\" values in the - computation. - -"), - -("Base","var","var(v[, region]) - - Compute the sample variance of a vector or array \"v\", optionally - along dimensions in \"region\". The algorithm will return an - estimator of the generative distribution's variance under the - assumption that each entry of \"v\" is an IID drawn from that - generative distribution. This computation is equivalent to - calculating \"sum((v - mean(v)).^2) / (length(v) - 1)\". Note: - Julia does not ignore \"NaN\" values in the computation. For - applications requiring the handling of missing data, the - \"DataArray\" package is recommended. - -"), - -("Base","varm","varm(v, m) - - Compute the sample variance of a vector \"v\" with known mean - \"m\". Note: Julia does not ignore \"NaN\" values in the - computation. - -"), - -("Base","middle","middle(x) - - Compute the middle of a scalar value, which is equivalent to \"x\" - itself, but of the type of \"middle(x, x)\" for consistency. - -"), - -("Base","middle","middle(x, y) - - Compute the middle of two reals \"x\" and \"y\", which is - equivalent in both value and type to computing their mean (\"(x + - y) / 2\"). - -"), - -("Base","middle","middle(range) - - Compute the middle of a range, which consists in computing the mean - of its extrema. Since a range is sorted, the mean is performed with - the first and last element. - -"), - -("Base","middle","middle(array) - - Compute the middle of an array, which consists in finding its - extrema and then computing their mean. - -"), - -("Base","median","median(v) - - Compute the median of a vector \"v\". \"NaN\" is returned if the - data contains any \"NaN\" values. For applications requiring the - handling of missing data, the \"DataArrays\" package is - recommended. - -"), - -("Base","median!","median!(v) - - Like \"median\", but may overwrite the input vector. - -"), - -("Base","hist","hist(v[, n]) -> e, counts - - Compute the histogram of \"v\", optionally using approximately - \"n\" bins. The return values are a range \"e\", which correspond - to the edges of the bins, and \"counts\" containing the number of - elements of \"v\" in each bin. Note: Julia does not ignore \"NaN\" - values in the computation. - -"), - -("Base","hist","hist(v, e) -> e, counts - - Compute the histogram of \"v\" using a vector/range \"e\" as the - edges for the bins. The result will be a vector of length - \"length(e) - 1\", such that the element at location \"i\" - satisfies \"sum(e[i] .< v .<= e[i+1])\". Note: Julia does not - ignore \"NaN\" values in the computation. - -"), - -("Base","hist!","hist!(counts, v, e) -> e, counts - - Compute the histogram of \"v\", using a vector/range \"e\" as the - edges for the bins. This function writes the resultant counts to a - pre-allocated array \"counts\". - -"), - -("Base","hist2d","hist2d(M, e1, e2) -> (edge1, edge2, counts) - - Compute a \"2d histogram\" of a set of N points specified by N-by-2 - matrix \"M\". Arguments \"e1\" and \"e2\" are bins for each - dimension, specified either as integer bin counts or vectors of bin - edges. The result is a tuple of \"edge1\" (the bin edges used in - the first dimension), \"edge2\" (the bin edges used in the second - dimension), and \"counts\", a histogram matrix of size - \"(length(edge1)-1, length(edge2)-1)\". Note: Julia does not ignore - \"NaN\" values in the computation. - -"), - -("Base","hist2d!","hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - - Compute a \"2d histogram\" with respect to the bins delimited by - the edges given in \"e1\" and \"e2\". This function writes the - results to a pre-allocated array \"counts\". - -"), - -("Base","histrange","histrange(v, n) - - Compute *nice* bin ranges for the edges of a histogram of \"v\", - using approximately \"n\" bins. The resulting step sizes will be 1, - 2 or 5 multiplied by a power of 10. Note: Julia does not ignore - \"NaN\" values in the computation. - -"), - -("Base","midpoints","midpoints(e) - - Compute the midpoints of the bins with edges \"e\". The result is a - vector/range of length \"length(e) - 1\". Note: Julia does not - ignore \"NaN\" values in the computation. - -"), - -("Base","quantile","quantile(v, p) - - Compute the quantiles of a vector \"v\" at a specified set of - probability values \"p\". Note: Julia does not ignore \"NaN\" - values in the computation. - -"), - -("Base","quantile","quantile(v, p) - - Compute the quantile of a vector \"v\" at the probability \"p\". - Note: Julia does not ignore \"NaN\" values in the computation. - -"), - -("Base","quantile!","quantile!(v, p) - - Like \"quantile\", but overwrites the input vector. - -"), - -("Base","cov","cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - - Compute the Pearson covariance between the vector(s) in \"v1\" and - \"v2\". Here, \"v1\" and \"v2\" can be either vectors or matrices. - - This function accepts three keyword arguments: - - * \"vardim\": the dimension of variables. When \"vardim = 1\", - variables are considered in columns while observations in rows; - when \"vardim = 2\", variables are in rows while observations in - columns. By default, it is set to \"1\". - - * \"corrected\": whether to apply Bessel's correction (divide by - \"n-1\" instead of \"n\"). By default, it is set to \"true\". - - * \"mean\": allow users to supply mean values that are known. By - default, it is set to \"nothing\", which indicates that the - mean(s) are unknown, and the function will compute the mean. - Users can use \"mean=0\" to indicate that the input data are - centered, and hence there's no need to subtract the mean. - - The size of the result depends on the size of \"v1\" and \"v2\". - When both \"v1\" and \"v2\" are vectors, it returns the covariance - between them as a scalar. When either one is a matrix, it returns a - covariance matrix of size \"(n1, n2)\", where \"n1\" and \"n2\" are - the numbers of slices in \"v1\" and \"v2\", which depend on the - setting of \"vardim\". - - Note: \"v2\" can be omitted, which indicates \"v2 = v1\". - -"), - -("Base","cor","cor(v1[, v2][, vardim=1, mean=nothing]) - - Compute the Pearson correlation between the vector(s) in \"v1\" and - \"v2\". - - Users can use the keyword argument \"vardim\" to specify the - variable dimension, and \"mean\" to supply pre-computed mean - values. - -"), - -("Base","fft","fft(A[, dims]) - - Performs a multidimensional FFT of the array \"A\". The optional - \"dims\" argument specifies an iterable subset of dimensions (e.g. - an integer, range, tuple, or array) to transform along. Most - efficient if the size of \"A\" along the transformed dimensions is - a product of small primes; see \"nextprod()\". See also - \"plan_fft()\" for even greater efficiency. - - A one-dimensional FFT computes the one-dimensional discrete Fourier - transform (DFT) as defined by - - \\operatorname{DFT}(A)[k] = - \\sum_{n=1}^{\\operatorname{length}(A)} - \\exp\\left(-i\\frac{2\\pi - (n-1)(k-1)}{\\operatorname{length}(A)} \\right) A[n]. - - A multidimensional FFT simply performs this operation along each - transformed dimension of \"A\". - - Higher performance is usually possible with multi-threading. Use - *FFTW.set_num_threads(np)* to use *np* threads, if you have *np* - processors. - -"), - -("Base","fft!","fft!(A[, dims]) - - Same as \"fft()\", but operates in-place on \"A\", which must be an - array of complex floating-point numbers. - -"), - -("Base","ifft","ifft(A[, dims]) - - Multidimensional inverse FFT. - - A one-dimensional inverse FFT computes - - \\operatorname{IDFT}(A)[k] = - \\frac{1}{\\operatorname{length}(A)} - \\sum_{n=1}^{\\operatorname{length}(A)} - \\exp\\left(+i\\frac{2\\pi (n-1)(k-1)} - {\\operatorname{length}(A)} \\right) A[n]. - - A multidimensional inverse FFT simply performs this operation along - each transformed dimension of \"A\". - -"), - -("Base","ifft!","ifft!(A[, dims]) - - Same as \"ifft()\", but operates in-place on \"A\". - -"), - -("Base","bfft","bfft(A[, dims]) - - Similar to \"ifft()\", but computes an unnormalized inverse - (backward) transform, which must be divided by the product of the - sizes of the transformed dimensions in order to obtain the inverse. - (This is slightly more efficient than \"ifft()\" because it omits a - scaling step, which in some applications can be combined with other - computational steps elsewhere.) - - \\operatorname{BDFT}(A)[k] = \\operatorname{length}(A) - \\operatorname{IDFT}(A)[k] - -"), - -("Base","bfft!","bfft!(A[, dims]) - - Same as \"bfft()\", but operates in-place on \"A\". - -"), - -("Base","plan_fft","plan_fft(A[, dims[, flags[, timelimit]]]) - - Pre-plan an optimized FFT along given dimensions (\"dims\") of - arrays matching the shape and type of \"A\". (The first two - arguments have the same meaning as for \"fft()\".) Returns a - function \"plan(A)\" that computes \"fft(A, dims)\" quickly. - - The \"flags\" argument is a bitwise-or of FFTW planner flags, - defaulting to \"FFTW.ESTIMATE\". e.g. passing \"FFTW.MEASURE\" or - \"FFTW.PATIENT\" will instead spend several seconds (or more) - benchmarking different possible FFT algorithms and picking the - fastest one; see the FFTW manual for more information on planner - flags. The optional \"timelimit\" argument specifies a rough upper - bound on the allowed planning time, in seconds. Passing - \"FFTW.MEASURE\" or \"FFTW.PATIENT\" may cause the input array - \"A\" to be overwritten with zeros during plan creation. - - \"plan_fft!()\" is the same as \"plan_fft()\" but creates a plan - that operates in-place on its argument (which must be an array of - complex floating-point numbers). \"plan_ifft()\" and so on are - similar but produce plans that perform the equivalent of the - inverse transforms \"ifft()\" and so on. - -"), - -("Base","plan_ifft","plan_ifft(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_fft()\", but produces a plan that performs inverse - transforms \"ifft()\". - -"), - -("Base","plan_bfft","plan_bfft(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_fft()\", but produces a plan that performs an - unnormalized backwards transform \"bfft()\". - -"), - -("Base","plan_fft!","plan_fft!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_fft()\", but operates in-place on \"A\". - -"), - -("Base","plan_ifft!","plan_ifft!(A[, dims[, flags[, timelimit]]]) - - Same as \"plan_ifft()\", but operates in-place on \"A\". - -"), - -("Base","plan_bfft!","plan_bfft!(A[, dims[, flags[, timelimit]]]) +("Base","log10","log10(x) - Same as \"plan_bfft()\", but operates in-place on \"A\". + Compute the logarithm of \"x\" to base 10. Throws \"DomainError\" + for negative \"Real\" arguments. "), -("Base","rfft","rfft(A[, dims]) +("Base","log1p","log1p(x) - Multidimensional FFT of a real array A, exploiting the fact that - the transform has conjugate symmetry in order to save roughly half - the computational time and storage costs compared with \"fft()\". - If \"A\" has size \"(n_1, ..., n_d)\", the result has size - \"(floor(n_1/2)+1, ..., n_d)\". + Accurate natural logarithm of \"1+x\". Throws \"DomainError\" for + \"Real\" arguments less than -1. - The optional \"dims\" argument specifies an iterable subset of one - or more dimensions of \"A\" to transform, similar to \"fft()\". - Instead of (roughly) halving the first dimension of \"A\" in the - result, the \"dims[1]\" dimension is (roughly) halved in the same - way. + There is an experimental variant in the \"Base.Math.JuliaLibm\" + module, which is typically faster and more accurate. "), -("Base","irfft","irfft(A, d[, dims]) - - Inverse of \"rfft()\": for a complex array \"A\", gives the - corresponding real array whose FFT yields \"A\" in the first half. - As for \"rfft()\", \"dims\" is an optional subset of dimensions to - transform, defaulting to \"1:ndims(A)\". +("Base","frexp","frexp(val) - \"d\" is the length of the transformed real array along the - \"dims[1]\" dimension, which must satisfy \"d == - floor(size(A,dims[1])/2)+1\". (This parameter cannot be inferred - from \"size(A)\" due to the possibility of rounding by the - \"floor\" function here.) + Return \"(x,exp)\" such that \"x\" has a magnitude in the interval + \"[1/2, 1)\" or 0, and val = x times 2^{exp}. "), -("Base","brfft","brfft(A, d[, dims]) +("Base","exp","exp(x) - Similar to \"irfft()\" but computes an unnormalized inverse - transform (similar to \"bfft()\"), which must be divided by the - product of the sizes of the transformed dimensions (of the real - output array) in order to obtain the inverse transform. + Compute e^x "), -("Base","plan_rfft","plan_rfft(A[, dims[, flags[, timelimit]]]) +("Base","exp2","exp2(x) - Pre-plan an optimized real-input FFT, similar to \"plan_fft()\" - except for \"rfft()\" instead of \"fft()\". The first two - arguments, and the size of the transformed result, are the same as - for \"rfft()\". + Compute 2^x "), -("Base","plan_brfft","plan_brfft(A, d[, dims[, flags[, timelimit]]]) +("Base","exp10","exp10(x) - Pre-plan an optimized real-input unnormalized transform, similar to - \"plan_rfft()\" except for \"brfft()\" instead of \"rfft()\". The - first two arguments and the size of the transformed result, are the - same as for \"brfft()\". + Compute 10^x "), -("Base","plan_irfft","plan_irfft(A, d[, dims[, flags[, timelimit]]]) +("Base","ldexp","ldexp(x, n) - Pre-plan an optimized inverse real-input FFT, similar to - \"plan_rfft()\" except for \"irfft()\" and \"brfft()\", - respectively. The first three arguments have the same meaning as - for \"irfft()\". + Compute x times 2^n "), -("Base","dct","dct(A[, dims]) +("Base","modf","modf(x) - Performs a multidimensional type-II discrete cosine transform (DCT) - of the array \"A\", using the unitary normalization of the DCT. The - optional \"dims\" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. Most efficient if the size of \"A\" along the transformed - dimensions is a product of small primes; see \"nextprod()\". See - also \"plan_dct()\" for even greater efficiency. + Return a tuple (fpart,ipart) of the fractional and integral parts + of a number. Both parts have the same sign as the argument. "), -("Base","dct!","dct!(A[, dims]) +("Base","expm1","expm1(x) - Same as \"dct!()\", except that it operates in-place on \"A\", - which must be an array of real or complex floating-point values. + Accurately compute e^x-1 "), -("Base","idct","idct(A[, dims]) +("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) + + Returns the nearest integral value of the same type as the complex- + valued \"z\" to \"z\", breaking ties using the specified + \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding + the real components while the second is used for rounding the + imaginary components. - Computes the multidimensional inverse discrete cosine transform - (DCT) of the array \"A\" (technically, a type-III DCT with the - unitary normalization). The optional \"dims\" argument specifies an - iterable subset of dimensions (e.g. an integer, range, tuple, or - array) to transform along. Most efficient if the size of \"A\" - along the transformed dimensions is a product of small primes; see - \"nextprod()\". See also \"plan_idct()\" for even greater - efficiency. + julia> round(pi, 2) 3.14 -"), + julia> round(pi, 3, 2) 3.125 -("Base","idct!","idct!(A[, dims]) + Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the \"Float64\" value represented by \"1.15\" is + actually *less* than 1.15, yet will be rounded to 1.2. - Same as \"idct!()\", but operates in-place on \"A\". + julia> x = 1.15 + 1.15 -"), + julia> @sprintf \"%.20f\" x + \"1.14999999999999991118\" -("Base","plan_dct","plan_dct(A[, dims[, flags[, timelimit]]]) + julia> x < 115//100 + true - Pre-plan an optimized discrete cosine transform (DCT), similar to - \"plan_fft()\" except producing a function that computes \"dct()\". - The first two arguments have the same meaning as for \"dct()\". + julia> round(x, 1) + 1.2 "), -("Base","plan_dct!","plan_dct!(A[, dims[, flags[, timelimit]]]) +("Base","RoundingMode","RoundingMode - Same as \"plan_dct()\", but operates in-place on \"A\". + A type which controls rounding behavior. Currently supported + rounding modes are: -"), + * \"RoundNearest\" (default) -("Base","plan_idct","plan_idct(A[, dims[, flags[, timelimit]]]) + * \"RoundNearestTiesAway\" - Pre-plan an optimized inverse discrete cosine transform (DCT), - similar to \"plan_fft()\" except producing a function that computes - \"idct()\". The first two arguments have the same meaning as for - \"idct()\". + * \"RoundNearestTiesUp\" -"), + * \"RoundToZero\" -("Base","plan_idct!","plan_idct!(A[, dims[, flags[, timelimit]]]) + * \"RoundUp\" - Same as \"plan_idct()\", but operates in-place on \"A\". + * \"RoundDown\" "), -("Base","fftshift","fftshift(x) +("Base","RoundNearest","RoundNearest - Swap the first and second halves of each dimension of \"x\". + The default rounding mode. Rounds to the nearest integer, with ties + (fractional values of 0.5) being rounded to the nearest even + integer. "), -("Base","fftshift","fftshift(x, dim) +("Base","RoundNearestTiesAway","RoundNearestTiesAway - Swap the first and second halves of the given dimension of array - \"x\". + Rounds to nearest integer, with ties rounded away from zero (C/C++ + \"round()\" behaviour). "), -("Base","ifftshift","ifftshift(x[, dim]) +("Base","RoundNearestTiesUp","RoundNearestTiesUp - Undoes the effect of \"fftshift\". + Rounds to nearest integer, with ties rounded toward positive + infinity (Java/JavaScript \"round()\" behaviour). "), -("Base","filt","filt(b, a, x[, si]) +("Base","RoundToZero","RoundToZero - Apply filter described by vectors \"a\" and \"b\" to vector \"x\", - with an optional initial filter state vector \"si\" (defaults to - zeros). + \"round()\" using this rounding mode is an alias for \"trunc()\". "), -("Base","filt!","filt!(out, b, a, x[, si]) +("Base","RoundUp","RoundUp - Same as \"filt()\" but writes the result into the \"out\" argument, - which may alias the input \"x\" to modify it in-place. + \"round()\" using this rounding mode is an alias for \"ceil()\". "), -("Base","deconv","deconv(b, a) +("Base","RoundDown","RoundDown - Construct vector \"c\" such that \"b = conv(a,c) + r\". Equivalent - to polynomial division. + \"round()\" using this rounding mode is an alias for \"floor()\". "), -("Base","conv","conv(u, v) +("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) - Convolution of two vectors. Uses FFT algorithm. + Returns the nearest integral value of the same type as the complex- + valued \"z\" to \"z\", breaking ties using the specified + \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding + the real components while the second is used for rounding the + imaginary components. "), -("Base","conv2","conv2(u, v, A) - - 2-D convolution of the matrix \"A\" with the 2-D separable kernel - generated by the vectors \"u\" and \"v\". Uses 2-D FFT algorithm +("Base","ceil","ceil([T], x[, digits[, base]]) -"), + \"ceil(x)\" returns the nearest integral value of the same type as + \"x\" that is greater than or equal to \"x\". -("Base","conv2","conv2(B, A) + \"ceil(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. - 2-D convolution of the matrix \"B\" with the matrix \"A\". Uses - 2-D FFT algorithm + \"digits\" and \"base\" work as for \"round()\". "), -("Base","xcorr","xcorr(u, v) +("Base","floor","floor([T], x[, digits[, base]]) + + \"floor(x)\" returns the nearest integral value of the same type as + \"x\" that is less than or equal to \"x\". + + \"floor(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. - Compute the cross-correlation of two vectors. + \"digits\" and \"base\" work as for \"round()\". "), -("Base.FFTW","r2r","r2r(A, kind[, dims]) +("Base","trunc","trunc([T], x[, digits[, base]]) - Performs a multidimensional real-input/real-output (r2r) transform - of type \"kind\" of the array \"A\", as defined in the FFTW manual. - \"kind\" specifies either a discrete cosine transform of various - types (\"FFTW.REDFT00\", \"FFTW.REDFT01\", \"FFTW.REDFT10\", or - \"FFTW.REDFT11\"), a discrete sine transform of various types - (\"FFTW.RODFT00\", \"FFTW.RODFT01\", \"FFTW.RODFT10\", or - \"FFTW.RODFT11\"), a real-input DFT with halfcomplex-format output - (\"FFTW.R2HC\" and its inverse \"FFTW.HC2R\"), or a discrete - Hartley transform (\"FFTW.DHT\"). The \"kind\" argument may be an - array or tuple in order to specify different transform types along - the different dimensions of \"A\"; \"kind[end]\" is used for any - unspecified dimensions. See the FFTW manual for precise - definitions of these transform types, at http://www.fftw.org/doc. + \"trunc(x)\" returns the nearest integral value of the same type as + \"x\" whose absolute value is less than or equal to \"x\". - The optional \"dims\" argument specifies an iterable subset of - dimensions (e.g. an integer, range, tuple, or array) to transform - along. \"kind[i]\" is then the transform type for \"dims[i]\", with - \"kind[end]\" being used for \"i > length(kind)\". + \"trunc(T, x)\" converts the result to type \"T\", throwing an + \"InexactError\" if the value is not representable. - See also \"plan_r2r()\" to pre-plan optimized r2r transforms. + \"digits\" and \"base\" work as for \"round()\". "), -("Base.FFTW","r2r!","r2r!(A, kind[, dims]) +("Base","unsafe_trunc","unsafe_trunc(T, x) - Same as \"r2r()\", but operates in-place on \"A\", which must be an - array of real or complex floating-point numbers. + \"unsafe_trunc(T, x)\" returns the nearest integral value of type + \"T\" whose absolute value is less than or equal to \"x\". If the + value is not representable by \"T\", an arbitrary value will be + returned. "), -("Base.FFTW","plan_r2r","plan_r2r(A, kind[, dims[, flags[, timelimit]]]) +("Base","signif","signif(x, digits[, base]) - Pre-plan an optimized r2r transform, similar to \"Base.plan_fft()\" - except that the transforms (and the first three arguments) - correspond to \"r2r()\" and \"r2r!()\", respectively. + Rounds (in the sense of \"round\") \"x\" so that there are + \"digits\" significant digits, under a base \"base\" + representation, default 10. E.g., \"signif(123.456, 2)\" is + \"120.0\", and \"signif(357.913, 4, 2)\" is \"352.0\". "), -("Base.FFTW","plan_r2r!","plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) +("Base","min","min(x, y, ...) - Similar to \"Base.plan_fft()\", but corresponds to \"r2r!()\". + Return the minimum of the arguments. Operates elementwise over + arrays. "), -("Base","quadgk","quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) - - Numerically integrate the function \"f(x)\" from \"a\" to \"b\", - and optionally over additional intervals \"b\" to \"c\" and so on. - Keyword options include a relative error tolerance \"reltol\" - (defaults to \"sqrt(eps)\" in the precision of the endpoints), an - absolute error tolerance \"abstol\" (defaults to 0), a maximum - number of function evaluations \"maxevals\" (defaults to \"10^7\"), - and the \"order\" of the integration rule (defaults to 7). +("Base","max","max(x, y, ...) - Returns a pair \"(I,E)\" of the estimated integral \"I\" and an - estimated upper bound on the absolute error \"E\". If \"maxevals\" - is not exceeded then \"E <= max(abstol, reltol*norm(I))\" will - hold. (Note that it is useful to specify a positive \"abstol\" in - cases where \"norm(I)\" may be zero.) + Return the maximum of the arguments. Operates elementwise over + arrays. - The endpoints \"a\" etcetera can also be complex (in which case the - integral is performed over straight-line segments in the complex - plane). If the endpoints are \"BigFloat\", then the integration - will be performed in \"BigFloat\" precision as well (note: it is - advisable to increase the integration \"order\" in rough proportion - to the precision, for smooth integrands). More generally, the - precision is set by the precision of the integration endpoints - (promoted to floating-point types). +"), - The integrand \"f(x)\" can return any numeric scalar, vector, or - matrix type, or in fact any type supporting \"+\", \"-\", - multiplication by real values, and a \"norm\" (i.e., any normed - vector space). Alternatively, a different norm can be specified by - passing a *norm*-like function as the *norm* keyword argument - (which defaults to *vecnorm*). +("Base","minmax","minmax(x, y) - [Only one-dimensional integrals are provided by this function. For - multi-dimensional integration (cubature), there are many different - algorithms (often much better than simple nested 1d integrals) and - the optimal choice tends to be very problem-dependent. See the - Julia external-package listing for available algorithms for - multidimensional integration or other specialized tasks (such as - integrals of highly oscillatory or singular functions).] + Return \"(min(x,y), max(x,y))\". See also: \"extrema()\" that + returns \"(minimum(x), maximum(x))\" - The algorithm is an adaptive Gauss-Kronrod integration technique: - the integral in each interval is estimated using a Kronrod rule - (\"2*order+1\" points) and the error is estimated using an embedded - Gauss rule (\"order\" points). The interval with the largest - error is then subdivided into two intervals and the process is - repeated until the desired error tolerance is achieved. +"), - These quadrature rules work best for smooth functions within each - interval, so if your function has a known discontinuity or other - singularity, it is best to subdivide your interval to put the - singularity at an endpoint. For example, if \"f\" has a - discontinuity at \"x=0.7\" and you want to integrate from 0 to 1, - you should use \"quadgk(f, 0,0.7,1)\" to subdivide the interval at - the point of discontinuity. The integrand is never evaluated - exactly at the endpoints of the intervals, so it is possible to - integrate functions that diverge at the endpoints as long as the - singularity is integrable (for example, a \"log(x)\" or - \"1/sqrt(x)\" singularity). +("Base","clamp","clamp(x, lo, hi) - For real-valued endpoints, the starting and/or ending points may be - infinite. (A coordinate transformation is performed internally to - map the infinite interval to a finite one.) + Return x if \"lo <= x <= hi\". If \"x < lo\", return \"lo\". If \"x + > hi\", return \"hi\". Arguments are promoted to a common type. + Operates elementwise over \"x\" if it is an array. "), @@ -11258,7 +9954,7 @@ golden Get the current floating point rounding mode for type \"T\", controlling the rounding of basic arithmetic functions (\"+()\", - \"-()\", \"*()\", \"/()\" and \"sqrt()\") and type conversion. + \"-()\", \">>*<<()\", \"/()\" and \"sqrt()\") and type conversion. Valid modes are \"RoundNearest\", \"RoundToZero\", \"RoundUp\", \"RoundDown\", and \"RoundFromZero\" (\"BigFloat\" only). @@ -11268,8 +9964,8 @@ golden ("Base","set_rounding","set_rounding(T, mode) Set the rounding mode of floating point type \"T\", controlling the - rounding of basic arithmetic functions (\"+()\", \"-()\", \"*()\", - \"/()\" and \"sqrt()\") and type conversion. + rounding of basic arithmetic functions (\"+()\", \"-()\", + \">>*<<()\", \"/()\" and \"sqrt()\") and type conversion. Note that this may affect other types, for instance changing the rounding mode of \"Float64\" will change the rounding mode of @@ -11345,11 +10041,15 @@ golden "), -("Base","isprime","isprime(x::Integer) -> Bool +("Base","isprime","isprime(x::BigInt[, reps = 25]) -> Bool - Returns \"true\" if \"x\" is prime, and \"false\" otherwise. + Probabilistic primality test. Returns \"true\" if \"x\" is prime; + and \"false\" if \"x\" is not prime with high probability. The + false positive rate is about \"0.25^reps\". \"reps = 25\" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). - julia> isprime(3) + julia> isprime(big(3)) true "), @@ -11461,12 +10161,12 @@ golden Pick a random element or array of random elements from the set of values specified by \"S\"; \"S\" can be - * an indexable collection (for example \"1:n\" or - \"['x','y','z']\"), or + * an indexable collection (for example \"1:n\" or + \"['x','y','z']\"), or - * a type: the set of values to pick from is then equivalent to - \"typemin(S):typemax(S)\" for integers (this is not applicable to - \"BigInt\"), and to [0,1) for floating point numbers; + * a type: the set of values to pick from is then equivalent to + \"typemin(S):typemax(S)\" for integers (this is not applicable + to \"BigInt\"), and to [0,1) for floating point numbers; \"S\" defaults to \"Float64\". @@ -11578,17 +10278,21 @@ golden "), -("Base","task_local_storage","task_local_storage(symbol) +("Base","task_local_storage","task_local_storage(body, symbol, value) - Look up the value of a symbol in the current task's task-local - storage. + Call the function \"body\" with a modified task-local storage, in + which \"value\" is assigned to \"symbol\"; the previous value of + \"symbol\", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. "), -("Base","task_local_storage","task_local_storage(symbol, value) +("Base","task_local_storage","task_local_storage(body, symbol, value) - Assign a value to a symbol in the current task's task-local - storage. + Call the function \"body\" with a modified task-local storage, in + which \"value\" is assigned to \"symbol\"; the previous value of + \"symbol\", or lack thereof, is restored afterwards. Useful for + emulating dynamic scoping. "), @@ -11680,72 +10384,45 @@ golden "), -("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built \"LocalManager\" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. \"addprocs(4)\" will add 4 processes - on the local machine. +("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers -"), + Launches worker processes via the specified cluster manager. -("Base","addprocs","addprocs() -> List of process identifiers + For example Beowulf clusters are supported via a custom cluster + manager implemented in package \"ClusterManagers\". - Equivalent to \"addprocs(CPU_CORES)\" + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. + Relevant only when using TCP/IP as transport. "), -("Base","addprocs","addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - \"machines\" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string \"machine_spec\" or a - tuple - \"(machine_spec, count)\" - - \"machine_spec\" is a string of the form \"[user@]host[:port] - [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" - to the standard ssh port. If \"[bind_addr[:port]]\" is specified, - other workers will connect to this worker at the specified - \"bind_addr\" and \"port\". - - \"count\" is the number of workers to be launched on the specified - host. If specified as \":auto\" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: +("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - \"tunnel\" : if \"true\" then SSH tunneling will be used to connect - to the worker from the master process. + Launches worker processes via the specified cluster manager. - \"sshflags\" : specifies additional ssh options, e.g. - \"sshflags=`-i /home/foo/bar.pem`\" . + For example Beowulf clusters are supported via a custom cluster + manager implemented in package \"ClusterManagers\". - \"max_parallel\" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. + Relevant only when using TCP/IP as transport. - \"dir\" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) +"), - \"exename\" : name of the julia executable. Defaults to - \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case - may be. +("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - \"exeflags\" : additional flags passed to the worker processes. + Launches worker processes via the specified cluster manager. - Environment variables : + For example Beowulf clusters are supported via a custom cluster + manager implemented in package \"ClusterManagers\". - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable \"JULIA_WORKER_TIMEOUT\". The value of - \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. + The number of seconds a newly launched worker waits for connection + establishment from the master can be specified via variable + \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. + Relevant only when using TCP/IP as transport. "), @@ -11776,9 +10453,9 @@ golden "), -("Base","procs","procs() +("Base","procs","procs(S::SharedArray) - Returns a list of all process identifiers. + Get the vector of processes that have mapped the shared array "), @@ -11835,21 +10512,22 @@ golden Block the current task until some event occurs, depending on the type of the argument: - * \"RemoteRef\": Wait for a value to become available for the - specified remote reference. + * \"RemoteRef\": Wait for a value to become available for the + specified remote reference. - * \"Condition\": Wait for \"notify\" on a condition. + * \"Condition\": Wait for \"notify\" on a condition. - * \"Process\": Wait for a process or process chain to exit. The - \"exitcode\" field of a process can be used to determine success - or failure. + * \"Process\": Wait for a process or process chain to exit. + The \"exitcode\" field of a process can be used to determine + success or failure. - * \"Task\": Wait for a \"Task\" to finish, returning its result - value. If the task fails with an exception, the exception is - propagated (re-thrown in the task that called \"wait\"). + * \"Task\": Wait for a \"Task\" to finish, returning its + result value. If the task fails with an exception, the + exception is propagated (re-thrown in the task that called + \"wait\"). - * \"RawFD\": Wait for changes on a file descriptor (see *poll_fd* - for keyword arguments and return code) + * \"RawFD\": Wait for changes on a file descriptor (see + *poll_fd* for keyword arguments and return code) If no argument is passed, the task blocks for an undefined period. If the task's state is set to \":waiting\", it can only be @@ -11914,9 +10592,9 @@ golden "), -("Base","RemoteRef","RemoteRef() +("Base","RemoteRef","RemoteRef(n) - Make an uninitialized remote reference on the local machine. + Make an uninitialized remote reference on process \"n\". "), @@ -12077,7 +10755,7 @@ golden Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line - argument \"--worker\" has the effect of initializing a process as a + argument \"–worker\" has the effect of initializing a process as a worker using TCP/IP sockets for transport. "), @@ -12107,16 +10785,12 @@ golden "), -("Base.Pkg","dir","dir() -> AbstractString +("Base.Pkg","dir","dir(names...) -> AbstractString - Returns the absolute path of the package directory. This defaults - to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION - .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell - syntax). If the \"JULIA_PKGDIR\" environment variable is set, then - that path is used in the returned value as \"joinpath(ENV[\"JULIA_ - PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If - \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to - whatever the current working directory is. + Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends + path components to the package directory and normalizes the + resulting path. In particular, \"Pkg.dir(pkg)\" returns the path to + the package \"pkg\". "), @@ -12176,12 +10850,11 @@ golden "), -("Base.Pkg","clone","clone(url[, pkg]) +("Base.Pkg","clone","clone(pkg) - Clone a package directly from the git URL \"url\". The package does - not need to be a registered in \"Pkg.dir(\"METADATA\")\". The - package repo is cloned by the name \"pkg\" if provided; if not - provided, \"pkg\" is determined automatically from \"url\". + If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone + it from that URL on the default branch. The package does not need + to have any registered versions. "), @@ -12193,9 +10866,9 @@ golden "), -("Base.Pkg","available","available() -> Vector{ASCIIString} +("Base.Pkg","available","available(pkg) -> Vector{VersionNumber} - Returns the names of available packages. + Returns the version numbers available for package \"pkg\". "), @@ -12205,10 +10878,10 @@ golden "), -("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} +("Base.Pkg","installed","installed(pkg) -> Void | VersionNumber - Returns a dictionary mapping installed package names to the - installed version number of each package. + If \"pkg\" is installed, return the installed version number, + otherwise return \"nothing\". "), @@ -12243,10 +10916,9 @@ golden "), -("Base.Pkg","pin","pin(pkg) +("Base.Pkg","pin","pin(pkg, version) - Pin \"pkg\" at the current version. To go back to using the newest - compatible released version, use \"Pkg.free(pkg)\" + Pin \"pkg\" at registered version \"version\". "), @@ -12269,10 +10941,12 @@ golden "), -("Base.Pkg","build","build() +("Base.Pkg","build","build(pkgs...) - Run the build scripts for all installed packages in depth-first - recursive order. + Run the build script in \"deps/build.jl\" for each package in + \"pkgs\" and all of their dependencies in depth-first recursive + order. This is called automatically by \"Pkg.resolve()\" on all + installed or updated packages. "), @@ -12323,9 +10997,9 @@ golden "), -("Base.Pkg","test","test() +("Base.Pkg","test","test(pkgs...) - Run the tests for all installed packages ensuring that each + Run the tests for each package in \"pkgs\" ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its \"test/runtests.jl\" file and test dependencies are specified in \"test/REQUIRE\". @@ -12355,14 +11029,12 @@ golden "), -("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) +("Base.Profile","print","print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - Prints profiling results to \"io\" (by default, \"STDOUT\"). If you - do not supply a \"data\" vector, the internal buffer of accumulated - backtraces will be used. \"format\" can be \":tree\" or \":flat\". - If \"C==true\", backtraces from C and Fortran code are shown. - \"combine==true\" merges instruction pointers that correspond to - the same line of code. \"cols\" controls the width of the display. + Prints profiling results to \"io\". This variant is used to examine + results exported by a previous call to \"retrieve()\". Supply the + vector \"data\" of backtraces and a dictionary \"lidict\" of line + information. "), @@ -12426,10 +11098,10 @@ golden ("Base.Profile","clear_malloc_data","clear_malloc_data() Clears any stored memory allocation data when running julia with \" - --track-allocation\". Execute the command(s) you want to test (to + –track-allocation\". Execute the command(s) you want to test (to force JIT-compilation), then call \"clear_malloc_data()\". Then execute your command(s) again, quit Julia, and examine the - resulting \"*.mem\" files. + resulting \">>*<<.mem\" files. "), @@ -12451,10 +11123,9 @@ golden "), -("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) +("Base","sort","sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - Variant of \"sort!\" that returns a sorted copy of \"v\" leaving - \"v\" itself unmodified. + Sort a multidimensional array \"A\" along the given dimension. "), @@ -12578,6 +11249,10 @@ golden julia> \"Hello \" * \"world\" \"Hello world\" + + julia> \"Hello \" * \"world\" + \"Hello world\" + "), ("Base","^","^(s, n) @@ -12602,12 +11277,11 @@ golden "), -("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) +("Base","bytestring","bytestring(s) - Create a string from the address of a C (0-terminated) string - encoded in ASCII or UTF-8. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. + Convert a string to a contiguous byte array representation + appropriate for passing it to C functions. The string will be + encoded as either ASCII or UTF-8. "), @@ -12619,16 +11293,21 @@ golden "), -("Base","ascii","ascii(::Array{UInt8, 1}) +("Base","ascii","ascii(::Ptr{UInt8}[, length]) - Create an ASCII string from a byte array. + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If \"length\" is specified, the string does not have to be + 0-terminated. "), -("Base","ascii","ascii(s) +("Base","ascii","ascii(::Ptr{UInt8}[, length]) - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). + Create an ASCII string from the address of a C (0-terminated) + string encoded in ASCII. A copy is made; the ptr can be safely + freed. If \"length\" is specified, the string does not have to be + 0-terminated. "), @@ -12641,18 +11320,17 @@ golden "), -("Base","utf8","utf8(::Array{UInt8, 1}) +("Base","utf8","utf8(s) - Create a UTF-8 string from a byte array. + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). "), -("Base","utf8","utf8(::Ptr{UInt8}[, length]) +("Base","utf8","utf8(s) - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - \"length\" is specified, the string does not have to be - 0-terminated. + Convert a string to a contiguous UTF-8 string (all characters must + be valid UTF-8 characters). "), @@ -12682,34 +11360,35 @@ golden any number of the following boolean keywords options (which all default to \"false\" except for \"compose\") are specified: - * \"compose=false\": do not perform canonical composition + * \"compose=false\": do not perform canonical composition - * \"decompose=true\": do canonical decomposition instead of - canonical composition (\"compose=true\" is ignored if present) + * \"decompose=true\": do canonical decomposition instead of + canonical composition (\"compose=true\" is ignored if present) - * \"compat=true\": compatibility equivalents are canonicalized + * \"compat=true\": compatibility equivalents are canonicalized - * \"casefold=true\": perform Unicode case folding, e.g. for case- - insensitive string comparison + * \"casefold=true\": perform Unicode case folding, e.g. for + case- insensitive string comparison - * \"newline2lf=true\", \"newline2ls=true\", or - \"newline2ps=true\": convert various newline sequences (LF, CRLF, - CR, NEL) into a linefeed (LF), line-separation (LS), or - paragraph-separation (PS) character, respectively + * \"newline2lf=true\", \"newline2ls=true\", or + \"newline2ps=true\": convert various newline sequences (LF, + CRLF, CR, NEL) into a linefeed (LF), line-separation (LS), + or paragraph-separation (PS) character, respectively - * \"stripmark=true\": strip diacritical marks (e.g. accents) + * \"stripmark=true\": strip diacritical marks (e.g. accents) - * \"stripignore=true\": strip Unicode's \"default ignorable\" - characters (e.g. the soft hyphen or the left-to-right marker) + * \"stripignore=true\": strip Unicode's \"default ignorable\" + characters (e.g. the soft hyphen or the left-to-right marker) - * \"stripcc=true\": strip control characters; horizontal tabs and - form feeds are converted to spaces; newlines are also converted - to spaces unless a newline-conversion flag was specified + * \"stripcc=true\": strip control characters; horizontal tabs + and form feeds are converted to spaces; newlines are also + converted to spaces unless a newline-conversion flag was + specified - * \"rejectna=true\": throw an error if unassigned code points are - found + * \"rejectna=true\": throw an error if unassigned code points + are found - * \"stable=true\": enforce Unicode Versioning Stability + * \"stable=true\": enforce Unicode Versioning Stability For example, NFKC corresponds to the options \"compose=true, compat=true, stable=true\". @@ -12726,24 +11405,15 @@ golden "), -("Base","isvalid","isvalid(value) -> Bool +("Base","isvalid","isvalid(str, i) - Returns true if the given value is valid for its type, which - currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" + Tells whether index \"i\" is valid for the given string "), -("Base","isvalid","isvalid(T, value) -> Bool +("Base","isvalid","isvalid(str, i) - Returns true if the given value is valid for that type. Types - currently can be \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of - type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and - \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for - \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values - for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or - \"Vector{UInt32}\" + Tells whether index \"i\" is valid for the given string "), @@ -13108,9 +11778,9 @@ golden ("Base","isspace","isspace(c::Union{Char, AbstractString}) -> Bool Tests whether a character is any whitespace character. Includes - ASCII characters '\\t', '\\n', '\\v', '\\f', '\\r', and ' ', - Latin-1 character U+0085, and characters in Unicode category Zs. - For strings, tests whether this is true for all elements of the + ASCII characters 't', 'n', 'v', 'f', 'r', and ' ', Latin-1 + character U+0085, and characters in Unicode category Zs. For + strings, tests whether this is true for all elements of the string. "), @@ -13152,23 +11822,11 @@ golden "), -("Base","utf16","utf16(s) - - Create a UTF-16 string from a byte array, array of \"UInt16\", or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) +("Base","utf16","utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - Note that the resulting \"UTF16String\" data is terminated by the - NUL codepoint (16-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf16(s)* conversion function. If you have a \"UInt16\" array - \"A\" that is already NUL-terminated valid UTF-16 data, then you - can instead use *UTF16String(A)`* to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. + Create a string from the address of a NUL-terminated UTF-16 string. + A copy is made; the pointer can be safely freed. If \"length\" is + specified, the string does not have to be NUL-terminated. "), @@ -13180,31 +11838,21 @@ golden "), -("Base","utf32","utf32(s) - - Create a UTF-32 string from a byte array, array of \"Char\" or - \"UInt32\", or any other string type. (Conversions of byte arrays - check for a byte-order marker in the first four bytes, and do not - include it in the resulting string.) +("Base","wstring","wstring(s) - Note that the resulting \"UTF32String\" data is terminated by the - NUL codepoint (32-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf32(s)* conversion function. If you have a \"Char\" or - \"UInt32\" array \"A\" that is already NUL-terminated UTF-32 data, - then you can instead use *UTF32String(A)`* to construct the string - without making a copy of the data and treating the NUL as a - terminator rather than as part of the string. + This is a synonym for either \"utf32(s)\" or \"utf16(s)\", + depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. + The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is + also provided. "), -("Base","utf32","utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) +("Base","wstring","wstring(s) - Create a string from the address of a NUL-terminated UTF-32 string. - A copy is made; the pointer can be safely freed. If \"length\" is - specified, the string does not have to be NUL-terminated. + This is a synonym for either \"utf32(s)\" or \"utf16(s)\", + depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. + The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is + also provided. "), diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index f04824b71b698..f7ee5380aed81 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -163,13 +163,7 @@ Iterable Collections .. function:: in(item, collection) -> Bool - :: - - in(item, collection) -> Bool - ∈(item, collection) -> Bool - ∋(collection, item) -> Bool - ∉(item, collection) -> Bool - ∌(collection, item) -> 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)". From ec3541aee19e7ec74ab70587d90b088265965434 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sun, 28 Jun 2015 00:09:38 -0400 Subject: [PATCH 26/27] now we repeat ourselves a *lot* but we aren't missing anything --- base/docs/helpdb.jl | 18261 ++++++++++++++++++----------------- doc/helpdb.jl | 4888 +++++++++- doc/stdlib/arrays.rst | 576 +- doc/stdlib/base.rst | 306 +- doc/stdlib/c.rst | 36 +- doc/stdlib/collections.rst | 724 +- doc/stdlib/dates.rst | 566 +- doc/stdlib/file.rst | 16 +- doc/stdlib/io-network.rst | 578 +- doc/stdlib/libc.rst | 10 +- doc/stdlib/linalg.rst | 728 +- doc/stdlib/math.rst | 158 +- doc/stdlib/numbers.rst | 36 +- doc/stdlib/parallel.rst | 280 +- doc/stdlib/pkg.rst | 112 +- doc/stdlib/profile.rst | 16 +- doc/stdlib/sort.rst | 16 +- doc/stdlib/strings.rst | 206 +- 18 files changed, 18084 insertions(+), 9429 deletions(-) diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index fe33fb81bbb41..7167abbe2e40f 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -1,2694 +1,2860 @@ doc""" - ndims(A) -> Integer + !(x) + +Boolean not -Returns the number of dimensions of A """ -ndims +! doc""" - size(A[, 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 = rand(2,3,4); + \$(x, y) - julia> size(A, 2) - 3 +Bitwise exclusive or - julia> size(A,3,2) - (4,3) """ -size +$ doc""" - iseltype(A, T) + &(x, y) + +Bitwise and -Tests whether A or its elements are of type T """ -iseltype +& doc""" - length(A) -> Integer + +(x, y...) + +Addition operator. "x+y+z+..." calls this function with all +arguments, i.e. "+(x, y, z, ...)". -Returns the number of elements in A """ -length ++ doc""" - eachindex(A...) + -(x) -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 (like "Array"), this is -simply the range "1: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 non-integer indices). +Unary minus operator. -Example for a sparse 2-d array: + -(x, y) - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 +Subtraction operator. - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 """ -eachindex +- doc""" - Base.linearindexing(A) - -"linearindexing" defines how an AbstractArray most efficiently -accesses its elements. If "Base.linearindexing(A)" returns -"Base.LinearFast()", this means that linear indexing with only -one index is an efficient operation. If it instead returns -"Base.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 -traits-based mechanism to enable efficient generic code for all -array types. + @__FILE__() -> AbstractString -An abstract array subtype "MyArray" that wishes to opt into fast -linear indexing behaviors should define "linearindexing" in the -type-domain: +"@__FILE__" expands to a string with the absolute path and file +name of the script being run. Returns "nothing" if run from a +REPL or an empty string if evaluated by "julia -e ". - Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() """ -linearindexing +@__FILE__ doc""" - countnz(A) + @allocated() + +A macro to evaluate an expression, discarding the resulting value, +instead returning the total number of bytes allocated during +evaluation of the expression. Note: the expression is evaluated +inside a local function, instead of the current context, in order +to eliminate the effects of compilation, however, there still may +be some allocations due to JIT compilation. This also makes the +results inconsistent with the "@time" macros, which do not try to +adjust for the effects of compilation. -Counts the number of nonzero values in array A (dense or sparse). -Note that this is not a constant-time operation. For sparse -matrices, one should usually use "nnz", which returns the number -of stored values. """ -countnz +@allocated doc""" - conj!(A) + @async() + +Schedule an expression to run on the local machine, also adding it +to the set of items that the nearest enclosing "@sync" waits for. -Convert an array to its complex conjugate in-place """ -conj! +@async doc""" - stride(A, k) + @code_llvm() + +Evaluates the arguments to the function call, determines their +types, and calls "code_llvm()" on the resulting expression -Returns the distance in memory (in number of elements) between -adjacent elements in dimension k """ -stride +@code_llvm doc""" - strides(A) + @code_lowered() + +Evaluates the arguments to the function call, determines their +types, and calls "code_lowered()" on the resulting expression -Returns a tuple of the memory strides in each dimension """ -strides +@code_lowered doc""" - ind2sub(dims, index) -> subscripts + @code_native() -Returns a tuple of subscripts into an array with dimensions -"dims", corresponding to the linear index "index" +Evaluates the arguments to the function call, determines their +types, and calls "code_native()" on the resulting expression -**Example** "i, j, ... = ind2sub(size(A), indmax(A))" provides -the indices of the maximum element """ -ind2sub +@code_native doc""" - ind2sub(a, index) -> subscripts + @code_typed() + +Evaluates the arguments to the function call, determines their +types, and calls "code_typed()" on the resulting expression -Returns a tuple of subscripts into array "a" corresponding to the -linear index "index" """ -ind2sub +@code_typed doc""" - sub2ind(dims, i, j, k...) -> index + @code_warntype() + +Evaluates the arguments to the function call, determines their +types, and calls "code_warntype()" on the resulting expression -The inverse of "ind2sub", returns the linear index corresponding -to the provided subscripts """ -sub2ind +@code_warntype doc""" - Array(dims) + @edit() + +Evaluates the arguments to the function call, determines their +types, and calls the "edit" function on the resulting expression -"Array{T}(dims)" constructs an uninitialized dense array with -element type "T". "dims" may be a tuple or a series of integer -arguments. The syntax "Array(T, dims)" is also available, but -deprecated. """ -Array +@edit doc""" - getindex(type[, elements...]) + @elapsed() + +A macro to evaluate an expression, discarding the resulting value, +instead returning the number of seconds it took to execute as a +floating-point number. -Construct a 1-d array of the specified type. This is usually called -with the syntax "Type[]". Element values can be specified using -"Type[a,b,c,...]". """ -getindex +@elapsed doc""" - cell(dims) + @eval() + +Evaluate an expression and return the value. -Construct an uninitialized cell array (heterogeneous array). -"dims" can be either a tuple or a series of integer arguments. """ -cell +@eval doc""" - zeros(type, dims) + @evalpoly(z, c...) + +Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients +"c[1]", "c[2]", ...; that is, the coefficients are given in +ascending order by power of "z". This macro expands to efficient +inline code that uses either Horner's method or, for complex "z", +a more efficient Goertzel-like algorithm. -Create an array of all zeros of specified type. The type defaults -to Float64 if not specified. """ -zeros +@evalpoly doc""" - zeros(A) + @fetch() + +Equivalent to "fetch(@spawn expr)". -Create an array of all zeros with the same element type and shape -as A. """ -zeros +@fetch doc""" - ones(type, dims) + @fetchfrom() + +Equivalent to "fetch(@spawnat p expr)". -Create an array of all ones of specified type. The type defaults to -Float64 if not specified. """ -ones +@fetchfrom doc""" - ones(A) + @gensym() + +Generates a gensym symbol for a variable. For example, "@gensym x +y" is transformed into "x = gensym("x"); y = gensym("y")". -Create an array of all ones with the same element type and shape as -A. """ -ones +@gensym doc""" - trues(dims) + @less() + +Evaluates the arguments to the function call, determines their +types, and calls the "less" function on the resulting expression -Create a "BitArray" with all values set to true """ -trues +@less doc""" - falses(dims) + @linux() + +Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See +documentation for Handling Platform Variations in the Calling C and +Fortran Code section of the manual. -Create a "BitArray" with all values set to false """ -falses +@linux doc""" - fill(x, dims) + @osx() -Create an array filled with the value "x". For example, -"fill(1.0, (10,10))" returns a 10x10 array of floats, with each -element initialized to 1.0. +Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See +documentation for Handling Platform Variations in the Calling C and +Fortran Code section of the manual. -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 evaluating "Foo()" once. """ -fill +@osx doc""" - fill!(A, x) + @parallel() -Fill array "A" with the value "x". If "x" is an object -reference, all elements will refer to the same object. "fill!(A, -Foo())" will return "A" filled with the result of evaluating -"Foo()" once. -""" -fill! +A parallel for loop of the form -doc""" - reshape(A, dims) + @parallel [reducer] for var = range + body + end -Create an array with the same data as the given array, but with -different dimensions. An implementation for a particular type of -array may choose whether the data is copied or shared. -""" -reshape +The specified range is partitioned and locally executed across all +workers. In case an optional reducer function is specified, +@parallel performs local reductions on each worker with a final +reduction on the calling process. -doc""" - similar(array, element_type, dims) +Note that without a reducer function, @parallel executes +asynchronously, i.e. it spawns independent tasks on all available +workers and returns immediately without waiting for completion. To +wait for completion, prefix the call with "@sync", like + + @sync @parallel for var = range + body + end -Create an uninitialized array of the same type as the given array, -but with the specified element type and dimensions. The second and -third arguments are both optional. The "dims" argument may be a -tuple or a series of integer arguments. For some special -"AbstractArray" objects which are not real containers (like -ranges), this function returns a standard "Array" to allow -operating on elements. """ -similar +@parallel doc""" - reinterpret(type, A) + @printf([io::IOStream], "%Fmt", args...) + +Print arg(s) using C "printf()" style format specification +string. Optionally, an IOStream may be passed as the first argument +to redirect output. -Change the type-interpretation of a block of memory. For example, -"reinterpret(Float32, UInt32(7))" interprets the 4 bytes -corresponding to "UInt32(7)" as a "Float32". For arrays, this -constructs an array with the same binary data as the given array, -but with the specified element type. """ -reinterpret +@printf doc""" - eye(n) + @profile() + +"@profile " runs your expression while taking +periodic backtraces. These are appended to an internal buffer of +backtraces. -n-by-n identity matrix """ -eye +@profile doc""" - eye(m, n) + @schedule() + +Wrap an expression in a Task and add it to the scheduler's queue. -m-by-n identity matrix """ -eye +@schedule doc""" - eye(A) + @show() + +Show an expression and result, returning the result -Constructs an identity matrix of the same dimensions and type as -"A". """ -eye +@show doc""" - linspace(start, stop, n=100) + @spawn() + +Execute an expression on an automatically-chosen process, returning +a "RemoteRef" to the result. -Construct a range of "n" linearly spaced elements from "start" -to "stop". """ -linspace +@spawn doc""" - logspace(start, stop, n=50) + @spawnat() + +Accepts two arguments, "p" and an expression, and runs the +expression asynchronously on process "p", returning a +"RemoteRef" to the result. -Construct a vector of "n" logarithmically spaced numbers from -"10^start" to "10^stop". """ -logspace +@spawnat doc""" - broadcast(f, As...) + @sprintf("%Fmt", args...) + +Return "@printf" formatted output as string. -Broadcasts the arrays "As" to a common size by expanding -singleton dimensions, and returns an array of the results -"f(as...)" for each position. """ -broadcast +@sprintf doc""" - broadcast!(f, dest, As...) + @sync() + +Wait until all dynamically-enclosed uses of "@async", "@spawn", +"@spawnat" and "@parallel" are complete. -Like "broadcast", but store the result of "broadcast(f, As...)" -in the "dest" array. Note that "dest" is only used to store the -result, and does not supply arguments to "f" unless it is also -listed in the "As", as in "broadcast!(f, A, A, B)" to perform -"A[:] = broadcast(f, A, B)". """ -broadcast! +@sync doc""" - bitbroadcast(f, As...) + @task() + +Wrap an expression in a Task without executing it, and return the +Task. This only creates a task, and does not run it. -Like "broadcast", but allocates a "BitArray" to store the -result, rather then an "Array". """ -bitbroadcast +@task doc""" - broadcast_function(f) + @time() + +A macro to execute an expression, printing the time it took to +execute, the number of allocations, and the total number of bytes +its execution caused to be allocated, before returning the value of +the expression. -Returns a function "broadcast_f" such that -"broadcast_function(f)(As...) === broadcast(f, As...)". Most -useful in the form "const broadcast_f = broadcast_function(f)". """ -broadcast_function +@time doc""" - broadcast!_function(f) + @timed() + +A macro to execute an expression, and return the value of the +expression, elapsed time, total bytes allocated, garbage collection +time, and an object with various memory allocation counters. -Like "broadcast_function", but for "broadcast!". """ -broadcast!_function +@timed doc""" - getindex(A, inds...) + @timev() + +This is a verbose version of the "@time" macro, it first prints +the same information as "@time", then any non-zero memory +allocation counters, and then returns the value of the expression. -Returns a subset of array "A" as specified by "inds", where -each "ind" may be an "Int", a "Range", or a "Vector". See -the manual section on *array indexing* for details. """ -getindex +@timev doc""" - sub(A, inds...) + @unix() + +Given "@unix? a : b", do "a" on Unix systems (including Linux +and OS X) and "b" elsewhere. See documentation for Handling +Platform Variations in the Calling C and Fortran Code section of +the manual. -Like "getindex()", but returns a view into the parent array "A" -with the given indices instead of making a copy. Calling -"getindex()" or "setindex!()" on the returned "SubArray" -computes the indices to the parent array on the fly without -checking bounds. """ -sub +@unix doc""" - parent(A) + @which() + +Applied to a function call, it evaluates the arguments to the +specified function call, and returns the "Method" object for the +method that would be called for those arguments. Applied to a +variable, it returns the module in which the variable was bound. It +calls out to the "which" function. -Returns the "parent array" of an array view type (e.g., -SubArray), or the array itself if it is not a view """ -parent +@which doc""" - parentindexes(A) + @windows() + +Given "@windows? a : b", do "a" on Windows and "b" elsewhere. +See documentation for Handling Platform Variations in the Calling C +and Fortran Code section of the manual. -From an array view "A", returns the corresponding indexes in the -parent """ -parentindexes +@windows doc""" - slicedim(A, d, i) + ANY + +Equivalent to "Any" for dispatch purposes, but signals the +compiler to skip code generation specialization for that field -Return all the data of "A" where the index for dimension "d" -equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is -in position "d". """ -slicedim +ANY doc""" - slice(A, inds...) + ARGS + +An array of the command line arguments passed to Julia, as strings. -Returns a view of array "A" with the given indices like -"sub()", but drops all dimensions indexed with scalars. """ -slice +ARGS doc""" - setindex!(A, X, inds...) + A_ldiv_Bc(a, b) + +Matrix operator A \ B^H -Store values from array "X" within some subset of "A" as -specified by "inds". """ -setindex! +A_ldiv_Bc doc""" - broadcast_getindex(A, inds...) + A_ldiv_Bt(a, b) + +Matrix operator A \ B^T -Broadcasts the "inds" arrays to a common size like "broadcast", -and returns an array of the results "A[ks...]", where "ks" goes -over the positions in the broadcast. """ -broadcast_getindex +A_ldiv_Bt doc""" - broadcast_setindex!(A, X, inds...) + A_mul_B!(Y, A, B) -> Y -Broadcasts the "X" and "inds" arrays to a common size and -stores the value from each position in "X" at the indices given -by the same positions in "inds". -""" -broadcast_setindex! +Calculates the matrix-matrix or matrix-vector product *A B* and +stores the result in *Y*, overwriting the existing value of *Y*. -doc""" - cat(dims, A...) + julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); + + julia> B + 2x2 Array{Float64,2}: + 3.0 3.0 + 7.0 7.0 -Concatenate the input arrays along the specified dimensions in the -iterable "dims". For dimensions not in "dims", all input arrays -should have the same size, which will also be the size of the -output array along that dimension. For dimensions in "dims", the -size of the output array is the sum of the sizes of the input -arrays along that dimension. If "dims" is a single number, the -different arrays are tightly stacked along that dimension. If -"dims" is an iterable containing several dimensions, this allows -to construct block diagonal matrices and their higher-dimensional -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 with *matrices[1]*, *matrices[2]*, ... as diagonal -blocks and matching zero blocks away from the diagonal. """ -cat +A_mul_B! doc""" - vcat(A...) + A_mul_Bc(...) + +Matrix operator A B^H -Concatenate along dimension 1 """ -vcat +A_mul_Bc doc""" - hcat(A...) + A_mul_Bt(...) + +Matrix operator A B^T -Concatenate along dimension 2 """ -hcat +A_mul_Bt doc""" - hvcat(rows::Tuple{Vararg{Int}}, values...) + A_rdiv_Bc(...) -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. For example, -"[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". +Matrix operator A / B^H -If the first argument is a single integer "n", then all block -rows are assumed to have "n" block columns. """ -hvcat +A_rdiv_Bc doc""" - flipdim(A, d) + A_rdiv_Bt(a, b) + +Matrix operator A / B^T -Reverse "A" in dimension "d". """ -flipdim +A_rdiv_Bt doc""" - circshift(A, shifts) + Ac_ldiv_B(...) + +Matrix operator A^H \ B -Circularly shift the data in an array. The second argument is a -vector giving the amount to shift in each dimension. """ -circshift +Ac_ldiv_B doc""" - find(A) + Ac_ldiv_Bc(...) + +Matrix operator A^H \ B^H -Return a vector of the linear indexes of the non-zeros in "A" -(determined by "A[i]!=0"). A common use of this is to convert a -boolean array to an array of indexes of the "true" elements. """ -find +Ac_ldiv_Bc doc""" - find(f, A) + Ac_mul_B(...) + +Matrix operator A^H B -Return a vector of the linear indexes of "A" where "f" returns -true. """ -find +Ac_mul_B doc""" - findn(A) + Ac_mul_Bc(...) + +Matrix operator A^H B^H -Return a vector of indexes for each dimension giving the locations -of the non-zeros in "A" (determined by "A[i]!=0"). """ -findn +Ac_mul_Bc doc""" - findnz(A) + Ac_rdiv_B(a, b) + +Matrix operator A^H / B -Return a tuple "(I, J, V)" where "I" and "J" are the row and -column indexes of the non-zero values in matrix "A", and "V" is -a vector of the non-zero values. """ -findnz +Ac_rdiv_B doc""" - findfirst(A) + Ac_rdiv_Bc(a, b) + +Matrix operator A^H / B^H -Return the index of the first non-zero value in "A" (determined -by "A[i]!=0"). """ -findfirst +Ac_rdiv_Bc doc""" - findfirst(A, v) + ArgumentError(msg) + +The parameters to a function call do not match a valid signature. -Return the index of the first element equal to "v" in "A". """ -findfirst +ArgumentError doc""" - findfirst(predicate, A) + Array(dims) + +"Array{T}(dims)" constructs an uninitialized dense array with +element type "T". "dims" may be a tuple or a series of integer +arguments. The syntax "Array(T, dims)" is also available, but +deprecated. -Return the index of the first element of "A" for which -"predicate" returns true. """ -findfirst +Array doc""" - findlast(A) + AssertionError([msg]) + +The asserted condition did not evalutate to "true". -Return the index of the last non-zero value in "A" (determined by -"A[i]!=0"). """ -findlast +AssertionError doc""" - findlast(A, v) + At_ldiv_B(...) + +Matrix operator A^T \ B -Return the index of the last element equal to "v" in "A". """ -findlast +At_ldiv_B doc""" - findlast(predicate, A) + At_ldiv_Bt(...) + +Matrix operator A^T \ B^T -Return the index of the last element of "A" for which -"predicate" returns true. """ -findlast +At_ldiv_Bt doc""" - findnext(A, i) + At_mul_B(...) + +Matrix operator A^T B -Find the next index >= "i" of a non-zero element of "A", or -"0" if not found. """ -findnext +At_mul_B doc""" - findnext(predicate, A, i) + At_mul_Bt(...) + +Matrix operator A^T B^T -Find the next index >= "i" of an element of "A" for which -"predicate" returns true, or "0" if not found. """ -findnext +At_mul_Bt doc""" - findnext(A, v, i) + At_rdiv_B(a, b) + +Matrix operator A^T / B -Find the next index >= "i" of an element of "A" equal to "v" -(using "=="), or "0" if not found. """ -findnext +At_rdiv_B doc""" - findprev(A, i) + At_rdiv_Bt(a, b) + +Matrix operator A^T / B^T -Find the previous index <= "i" of a non-zero element of "A", or -0 if not found. """ -findprev +At_rdiv_Bt doc""" - findprev(predicate, A, i) + Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + +Called by cluster managers using custom transports. It should be +called when the custom transport implementation receives the first +message from a remote worker. The custom transport must manage a +logical connection to the remote worker and provide two AsyncStream +objects, one for incoming messages and the other for messages +addressed to the remote worker. -Find the previous index <= "i" of an element of "A" for which -"predicate" returns true, or "0" if not found. """ -findprev +Base doc""" - findprev(A, v, i) + !=(x, y) +≠(x, y) + +Not-equals comparison operator. Always gives the opposite answer as +"==". New types should generally not implement this, and rely on +the fallback definition "!=(x,y) = !(x==y)" instead. -Find the previous index <= "i" of an element of "A" equal to -"v" (using "=="), or "0" if not found. """ -findprev +Base.(:(!=)) doc""" - permutedims(A, perm) + !==(x, y) +≢(x, y) + +Equivalent to "!is(x, y)" -Permute the dimensions of array "A". "perm" is a vector -specifying a permutation of length "ndims(A)". This is a -generalization of transpose for multi-dimensional arrays. Transpose -is equivalent to "permutedims(A, [2,1])". """ -permutedims +Base.(:(!==)) doc""" - ipermutedims(A, perm) + *(A, B) -Like "permutedims()", except the inverse of the given permutation -is applied. -""" -ipermutedims +Matrix multiplication -doc""" - permutedims!(dest, src, perm) + *(x, y...) + +Multiplication operator. "x*y*z*..." calls this function with all +arguments, i.e. "*(x, y, z, ...)". + + *(s, t) + +Concatenate strings. The "*" operator is an alias to this +function. + + julia> "Hello " * "world" + "Hello world" -Permute the dimensions of array "src" and store the result in the -array "dest". "perm" is a vector specifying a permutation of -length "ndims(src)". The preallocated array "dest" should have -"size(dest) == size(src)[perm]" and is completely overwritten. No -in-place permutation is supported and unexpected results will -happen if *src* and *dest* have overlapping memory regions. """ -permutedims! +Base.(:(*)) doc""" - squeeze(A, dims) + .!=(x, y) +.≠(x, y) + +Element-wise not-equals comparison operator. -Remove the dimensions specified by "dims" from array "A". -Elements of "dims" must be unique and within the range -"1:ndims(A)". """ -squeeze +Base.(:(.!=)) doc""" - vec(Array) -> Vector + .*(x, y) + +Element-wise multiplication operator. -Vectorize an array using column-major convention. """ -vec +Base.(:(.*)) doc""" - promote_shape(s1, s2) + .+(x, y) -Check two array shapes for compatibility, allowing trailing -singleton dimensions, and return whichever shape has more -dimensions. -""" -promote_shape - -doc""" - checkbounds(array, indexes...) +Element-wise addition operator. -Throw an error if the specified indexes are not in bounds for the -given array. """ -checkbounds +Base.(:(.+)) doc""" - randsubseq(A, p) -> Vector - -Return a vector consisting of a random subsequence of the given -array "A", where each element of "A" is included (in order) -with independent probability "p". (Complexity is linear in -"p*length(A)", so this function is efficient even if "p" is -small and "A" is large.) Technically, this process is known as -"Bernoulli sampling" of "A". -""" -randsubseq + .-(x, y) -doc""" - randsubseq!(S, A, p) +Element-wise subtraction operator. -Like "randsubseq", but the results are stored in "S" (which is -resized as needed). """ -randsubseq! +Base.(:(.-)) doc""" - cumprod(A[, dim]) - -Cumulative product along a dimension "dim" (defaults to 1). See -also "cumprod!()" to use a preallocated output array, both for -performance and to control the precision of the output (e.g. to -avoid overflow). -""" -cumprod + ./(x, y) -doc""" - cumprod!(B, A[, dim]) +Element-wise right division operator. -Cumulative product of "A" along a dimension, storing the result -in "B". The dimension defaults to 1. """ -cumprod! +Base.(:(./)) doc""" - cumsum(A[, dim]) + .<(x, y) + +Element-wise less-than comparison operator. -Cumulative sum along a dimension "dim" (defaults to 1). See also -"cumsum!()" to use a preallocated output array, both for -performance and to control the precision of the output (e.g. to -avoid overflow). """ -cumsum +Base.(:(.<)) doc""" - cumsum!(B, A[, dim]) + .<=(x, y) +.≤(x, y) + +Element-wise less-than-or-equals comparison operator. -Cumulative sum of "A" along a dimension, storing the result in -"B". The dimension defaults to 1. """ -cumsum! +Base.(:(.<=)) doc""" - cumsum_kbn(A[, dim]) + .==(x, y) + +Element-wise equality comparison operator. -Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier -compensated summation algorithm for additional accuracy. The -dimension defaults to 1. """ -cumsum_kbn +Base.(:(.==)) doc""" - cummin(A[, dim]) + .>(x, y) + +Element-wise greater-than comparison operator. -Cumulative minimum along a dimension. The dimension defaults to 1. """ -cummin +Base.(:(.>)) doc""" - cummax(A[, dim]) + .>=(x, y) +.≥(x, y) + +Element-wise greater-than-or-equals comparison operator. -Cumulative maximum along a dimension. The dimension defaults to 1. """ -cummax +Base.(:(.>=)) doc""" - diff(A[, dim]) + .\(x, y) + +Element-wise left division operator. -Finite difference operator of matrix or vector. """ -diff +Base.(:(.\)) doc""" - gradient(F[, h]) + .^(x, y) + +Element-wise exponentiation operator. -Compute differences along vector "F", using "h" as the spacing -between points. The default spacing is one. """ -gradient +Base.(:(.^)) doc""" - rot180(A) + /(x, y) + +Right division operator: multiplication of "x" by the inverse of +"y" on the right. Gives floating-point results for integer +arguments. -Rotate matrix "A" 180 degrees. """ -rot180 +Base.(:(/)) doc""" - rot180(A, k) + //(num, den) + +Divide two integers or rational numbers, giving a "Rational" +result. -Rotate matrix "A" 180 degrees an integer "k" number of times. -If "k" is even, this is equivalent to a "copy". """ -rot180 +Base.(:(//)) doc""" - rotl90(A) + :(start[, step], stop) + +Range operator. "a:b" constructs a range from "a" to "b" with +a step size of 1, and "a:s:b" is similar but uses a step size of +"s". These syntaxes call the function "colon". The colon is +also used in indexing to select whole dimensions. -Rotate matrix "A" left 90 degrees. """ -rotl90 +Base.(:(:)) doc""" - rotl90(A, k) + <(x, y) + +Less-than comparison operator. New numeric types should implement +this function for two arguments of the new type. Because of the +behavior of floating-point NaN values, "<" implements a partial +order. Types with a canonical partial order should implement "<", +and types with a canonical total order should implement "isless". -Rotate matrix "A" left 90 degrees an integer "k" number of -times. If "k" is zero or a multiple of four, this is equivalent -to a "copy". """ -rotl90 +Base.(:(<)) doc""" - rotr90(A) + <:(T1, T2) + +Subtype operator, equivalent to "issubtype(T1,T2)". -Rotate matrix "A" right 90 degrees. """ -rotr90 +Base.(:(<:)) doc""" - rotr90(A, k) + <<(x, n) + +Left bit shift operator. -Rotate matrix "A" right 90 degrees an integer "k" number of -times. If "k" is zero or a multiple of four, this is equivalent -to a "copy". """ -rotr90 +Base.(:(<<)) doc""" - reducedim(f, A, dims[, initial]) + <=(x, y) +≤(x, y) -Reduce 2-argument function "f" along dimensions of "A". -"dims" is a vector specifying the dimensions to reduce, and -"initial" is the initial value to use in the reductions. For *+*, -***, *max* and *min* the *initial* argument is optional. +Less-than-or-equals comparison operator. -The associativity of the reduction is implementation-dependent; if -you need a particular associativity, e.g. left-to-right, you should -write your own loop. See documentation for "reduce". """ -reducedim +Base.(:(<=)) doc""" - mapreducedim(f, op, A, dims[, initial]) + ==(x, y) -Evaluates to the same as *reducedim(op, map(f, A), dims, -f(initial))*, but is generally faster because the intermediate -array is avoided. -""" -mapreducedim +Generic equality operator, giving a single "Bool" result. Falls +back to "===". Should be implemented for all types with a notion +of equality, based on the abstract value that an instance +represents. For example, all numeric types are compared by numeric +value, ignoring type. Strings are compared as sequences of +characters, ignoring encoding. -doc""" - mapslices(f, A, dims) +Follows IEEE semantics for floating-point numbers. + +Collections should generally implement "==" by calling "==" +recursively on all contents. + +New numeric types should implement this function for two arguments +of the new type, and handle comparison to other types via promotion +rules where possible. -Transform the given dimensions of array "A" using function "f". -"f" is called on each slice of "A" of the form -"A[...,:,...,:,...]". "dims" is an integer vector specifying -where the colons go in this expression. The results are -concatenated along the remaining dimensions. For example, if -"dims" is "[1,2]" and A is 4-dimensional, "f" is called on -"A[:,:,i,j]" for all "i" and "j". """ -mapslices +Base.(:(==)) doc""" - sum_kbn(A) + ===(x, y) +≡(x, y) + +See the "is()" operator -Returns the sum of all array elements, using the Kahan-Babuska- -Neumaier compensated summation algorithm for additional accuracy. """ -sum_kbn +Base.(:(===)) doc""" - cartesianmap(f, dims) + >(x, y) -Given a "dims" tuple of integers "(m, n, ...)", call "f" on -all combinations of integers in the ranges "1:m", "1:n", etc. +Greater-than comparison operator. Generally, new types should +implement "<" instead of this function, and rely on the fallback +definition ">(x,y) = y cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 """ -cartesianmap +Base.(:(>)) doc""" - nthperm(v, k) + >=(x, y) +≥(x, y) + +Greater-than-or-equals comparison operator. -Compute the kth lexicographic permutation of a vector. """ -nthperm +Base.(:(>=)) doc""" - nthperm(p) + >>(x, n) + +Right bit shift operator, preserving the sign of "x". -Return the "k" that generated permutation "p". Note that -"nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". """ -nthperm +Base.(:(>>)) doc""" - nthperm!(v, k) + >>>(x, n) + +Unsigned right bit shift operator. -In-place version of "nthperm()". """ -nthperm! +Base.(:(>>>)) doc""" - randperm([rng], n) + \(A, B) -Construct a random permutation of length "n". The optional -"rng" argument specifies a random number generator, see *Random -Numbers*. -""" -randperm +Matrix division using a polyalgorithm. For input matrices "A" and +"B", the result "X" is such that "A*X == B" when "A" is +square. The solver that is used depends upon the structure of +"A". A direct solver is used for upper- or lower triangular +"A". For Hermitian "A" (equivalent to symmetric "A" for non- +complex "A") the "BunchKaufman" factorization is used. +Otherwise an LU factorization is used. For rectangular "A" the +result is the minimum-norm least squares solution computed by a +pivoted QR factorization of "A" and a rank estimate of A based on +the R factor. -doc""" - invperm(v) +When "A" is sparse, a similar polyalgorithm is used. For +indefinite matrices, the LDLt factorization does not use pivoting +during the numerical factorization and therefore the procedure can +fail even for invertible matrices. -Return the inverse permutation of v. -""" -invperm + \(x, y) -doc""" - isperm(v) -> Bool +Left division operator: multiplication of "y" by the inverse of +"x" on the left. Gives floating-point results for integer +arguments. -Returns true if v is a valid permutation. """ -isperm +Base.(:(\)) doc""" - permute!(v, p) + ^(x, y) -Permute vector "v" in-place, according to permutation "p". No -checking is done to verify that "p" is a permutation. +Exponentiation operator. -To return a new permutation, use "v[p]". Note that this is -generally faster than "permute!(v,p)" for large vectors. -""" -permute! + ^(s, n) -doc""" - ipermute!(v, p) +Repeat "n" times the string "s". The "^" operator is an alias +to this function. + + julia> "Test "^3 + "Test Test Test " -Like permute!, but the inverse of the given permutation is applied. """ -ipermute! +Base.(:(^)) doc""" - randcycle([rng], n) + |(x, y) + +Bitwise or -Construct a random cyclic permutation of length "n". The optional -"rng" argument specifies a random number generator, see *Random -Numbers*. """ -randcycle +Base.(:(|)) doc""" - shuffle([rng], v) + |>(x, f) -Return a randomly permuted copy of "v". The optional "rng" -argument specifies a random number generator, see *Random Numbers*. -""" -shuffle +Applies a function to the preceding argument. This allows for easy +function chaining. -doc""" - shuffle!([rng], v) + julia> [1:5;] |> x->x.^2 |> sum |> inv + 0.01818181818181818 -In-place version of "shuffle()". """ -shuffle! +Base.(:(|>)) doc""" - reverse(v[, start=1[, stop=length(v)]]) + PriorityQueue(K, V[, ord]) + +Construct a new "PriorityQueue", with keys of type "K" and +values/priorites of type "V". If an order is not given, the +priority queue is min-ordered using the default comparison for +"V". -Return a copy of "v" reversed from start to stop. """ -reverse +Base.Collections.PriorityQueue doc""" - reverseind(v, i) + dequeue!(pq) + +Remove and return the lowest priority key from a priority queue. -Given an index "i" in "reverse(v)", return the corresponding -index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". -(This can be nontrivial in the case where "v" is a Unicode -string.) """ -reverseind +Base.Collections.dequeue! doc""" - reverse!(v[, start=1[, stop=length(v)]]) -> v + enqueue!(pq, k, v) + +Insert the a key "k" into a priority queue "pq" with priority +"v". -In-place version of "reverse()". """ -reverse! +Base.Collections.enqueue! doc""" - combinations(array, n) + heapify(v[, ord]) + +Return a new vector in binary heap order, optionally using the +given ordering. -Generate all combinations of "n" elements from an indexable -object. Because the number of combinations can be very large, this -function returns an iterator object. Use -"collect(combinations(array,n))" to get an array of all -combinations. """ -combinations +Base.Collections.heapify doc""" - permutations(array) + heapify!(v[, ord]) + +In-place "heapify()". -Generate all permutations of an indexable object. Because the -number of permutations can be very large, this function returns an -iterator object. Use "collect(permutations(array))" to get an -array of all permutations. """ -permutations +Base.Collections.heapify! doc""" - partitions(n) + heappop!(v[, ord]) + +Given a binary heap-ordered array, remove and return the lowest +ordered element. For efficiency, this function does not check that +the array is indeed heap-ordered. -Generate all integer arrays that sum to "n". Because the number -of partitions can be very large, this function returns an iterator -object. Use "collect(partitions(n))" to get an array of all -partitions. The number of partitions to generate can be efficiently -computed using "length(partitions(n))". """ -partitions +Base.Collections.heappop! doc""" - partitions(n, m) + heappush!(v, x[, ord]) + +Given a binary heap-ordered array, push a new element "x", +preserving the heap property. For efficiency, this function does +not check that the array is indeed heap-ordered. -Generate all arrays of "m" integers that sum to "n". Because -the number of partitions can be very large, this function returns -an iterator object. Use "collect(partitions(n,m))" to get an -array of all partitions. The number of partitions to generate can -be efficiently computed using "length(partitions(n,m))". """ -partitions +Base.Collections.heappush! doc""" - partitions(array) + isheap(v[, ord]) + +Return true iff an array is heap-ordered according to the given +order. -Generate all set partitions of the elements of an array, -represented as arrays of arrays. Because the number of partitions -can be very large, this function returns an iterator object. Use -"collect(partitions(array))" to get an array of all partitions. -The number of partitions to generate can be efficiently computed -using "length(partitions(array))". """ -partitions +Base.Collections.isheap doc""" - partitions(array, m) + peek(pq) + +Return the lowest priority key from a priority queue without +removing that key from the queue. -Generate all set partitions of the elements of an array into -exactly m subsets, represented as arrays of arrays. Because the -number of partitions can be very large, this function returns an -iterator object. Use "collect(partitions(array,m))" to get an -array of all partitions. The number of partitions into m subsets is -equal to the Stirling number of the second kind and can be -efficiently computed using "length(partitions(array,m))". """ -partitions +Base.Collections.peek doc""" - bitpack(A::AbstractArray{T, N}) -> BitArray + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" +except that the transforms (and the first three arguments) +correspond to "r2r()" and "r2r!()", respectively. -Converts a numeric array to a packed boolean array """ -bitpack +Base.FFTW.plan_r2r doc""" - bitunpack(B::BitArray{N}) -> Array{Bool,N} + plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + +Similar to "Base.plan_fft()", but corresponds to "r2r!()". -Converts a packed boolean array to an array of booleans """ -bitunpack +Base.FFTW.plan_r2r! doc""" - flipbits!(B::BitArray{N}) -> BitArray{N} + r2r(A, kind[, dims]) + +Performs a multidimensional real-input/real-output (r2r) transform +of type "kind" of the array "A", as defined in the FFTW manual. +"kind" specifies either a discrete cosine transform of various +types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or +"FFTW.REDFT11"), a discrete sine transform of various types +("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or +"FFTW.RODFT11"), a real-input DFT with halfcomplex-format output +("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete +Hartley transform ("FFTW.DHT"). The "kind" argument may be an +array or tuple in order to specify different transform types along +the different dimensions of "A"; "kind[end]" is used for any +unspecified dimensions. See the FFTW manual for precise +definitions of these transform types, at http://www.fftw.org/doc. + +The optional "dims" argument specifies an iterable subset of +dimensions (e.g. an integer, range, tuple, or array) to transform +along. "kind[i]" is then the transform type for "dims[i]", with +"kind[end]" being used for "i > length(kind)". + +See also "plan_r2r()" to pre-plan optimized r2r transforms. -Performs a bitwise not operation on B. See *~ operator*. """ -flipbits! +Base.FFTW.r2r doc""" - rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + r2r!(A, kind[, dims]) + +Same as "r2r()", but operates in-place on "A", which must be an +array of real or complex floating-point numbers. -Performs a left rotation operation on "src" and put the result -into "dest". """ -rol! +Base.FFTW.r2r! doc""" - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + I + +An object of type "UniformScaling", representing an identity +matrix of any size. -Performs a left rotation operation on B. """ -rol! +Base.LinAlg.BLAS.I doc""" - rol(B::BitArray{1}, i::Integer) -> BitArray{1} + asum(n, X, incx) + +sum of the absolute values of the first "n" elements of array +"X" with stride "incx". -Performs a left rotation operation. """ -rol +Base.LinAlg.BLAS.asum doc""" - ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + axpy!(a, X, Y) + +Overwrite "Y" with "a*X + Y". Returns "Y". -Performs a right rotation operation on "src" and put the result -into "dest". """ -ror! +Base.LinAlg.BLAS.axpy! doc""" - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + blas_set_num_threads(n) + +Set the number of threads the BLAS library should use. -Performs a right rotation operation on B. """ -ror! +Base.LinAlg.BLAS.blas_set_num_threads doc""" - ror(B::BitArray{1}, i::Integer) -> BitArray{1} + blascopy!(n, X, incx, Y, incy) + +Copy "n" elements of array "X" with stride "incx" to array +"Y" with stride "incy". Returns "Y". -Performs a right rotation operation. """ -ror +Base.LinAlg.BLAS.blascopy! doc""" - sparse(I, J, V[, m, n, combine]) + dot(n, X, incx, Y, incy) + +Dot product of two vectors consisting of "n" elements of array +"X" with stride "incx" and "n" elements of array "Y" with +stride "incy". -Create a sparse matrix "S" of dimensions "m x n" such that -"S[I[k], J[k]] = V[k]". The "combine" function is used to -combine duplicates. If "m" and "n" are not specified, they are -set to "max(I)" and "max(J)" respectively. If the "combine" -function is not supplied, duplicates are added by default. """ -sparse +Base.LinAlg.BLAS.dot doc""" - sparsevec(I, V[, m, combine]) + dotc(n, X, incx, U, incy) + +Dot function for two complex vectors conjugating the first vector. -Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] -= V[k]". Duplicates are combined using the "combine" function, -which defaults to "+" if it is not provided. In julia, sparse -vectors are really just sparse matrices with one column. Given -Julia's Compressed Sparse Columns (CSC) storage format, a sparse -column matrix with one column is sparse, whereas a sparse row -matrix with one row ends up being dense. """ -sparsevec +Base.LinAlg.BLAS.dotc doc""" - sparsevec(D::Dict[, m]) + dotu(n, X, incx, Y, incy) + +Dot function for two complex vectors. -Create a sparse matrix of size "m x 1" where the row values are -keys from the dictionary, and the nonzero values are the values -from the dictionary. """ -sparsevec +Base.LinAlg.BLAS.dotu doc""" - issparse(S) + gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + +Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' +or 'T'). The matrix "A" is a general band matrix of dimension +"m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- +diagonals. -Returns "true" if "S" is sparse, and "false" otherwise. """ -issparse +Base.LinAlg.BLAS.gbmv doc""" - sparse(A) + gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) + +Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + +beta*y" according to "trans" ('N' or 'T'). The matrix "A" is +a general band matrix of dimension "m" by "size(A,2)" with +"kl" sub-diagonals and "ku" super-diagonals. Returns the +updated "y". -Convert an AbstractMatrix "A" into a sparse matrix. """ -sparse +Base.LinAlg.BLAS.gbmv! doc""" - sparsevec(A) + gemm(tA, tB, alpha, A, B) -Convert a dense vector "A" into a sparse matrix of size "m x -1". In julia, sparse vectors are really just sparse matrices with -one column. -""" -sparsevec +Returns "alpha*A*B" or the other three variants according to +"tA" (transpose "A") and "tB". -doc""" - full(S) + gemm(tA, tB, A, B) + +Returns "A*B" or the other three variants according to "tA" +(transpose "A") and "tB". -Convert a sparse matrix "S" into a dense matrix. """ -full +Base.LinAlg.BLAS.gemm doc""" - nnz(A) + gemm!(tA, tB, alpha, A, B, beta, C) + +Update "C" as "alpha*A*B + beta*C" or the other three variants +according to "tA" (transpose "A") and "tB". Returns the +updated "C". -Returns the number of stored (filled) elements in a sparse matrix. """ -nnz +Base.LinAlg.BLAS.gemm! doc""" - spzeros(m, n) + gemv(tA, alpha, A, x) -Create a sparse matrix of size "m x n". This sparse matrix will -not contain any nonzero values. No storage will be allocated for -nonzero values during construction. -""" -spzeros +Returns "alpha*A*x" or "alpha*A'x" according to "tA" +(transpose "A"). -doc""" - spones(S) + gemv(tA, A, x) + +Returns "A*x" or "A'x" according to "tA" (transpose "A"). -Create a sparse matrix with the same structure as that of "S", -but with every nonzero element having the value "1.0". """ -spones +Base.LinAlg.BLAS.gemv doc""" - speye(type, m[, n]) + gemv!(tA, alpha, A, x, beta, y) + +Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + +beta*y" according to "tA" (transpose "A"). Returns the updated +"y". -Create a sparse identity matrix of specified type of size "m x -m". In case "n" is supplied, create a sparse identity matrix of -size "m x n". """ -speye +Base.LinAlg.BLAS.gemv! doc""" - spdiagm(B, d[, m, n]) + ger!(alpha, x, y, A) + +Rank-1 update of the matrix "A" with vectors "x" and "y" as +"alpha*x*y' + A". -Construct a sparse diagonal matrix. "B" is a tuple of vectors -containing the diagonals and "d" is a tuple containing the -positions of the diagonals. In the case the input contains only one -diagonaly, "B" can be a vector (instead of a tuple) and "d" can -be the diagonal position (instead of a tuple), defaulting to 0 -(diagonal). Optionally, "m" and "n" specify the size of the -resulting sparse matrix. """ -spdiagm +Base.LinAlg.BLAS.ger! doc""" - sprand([rng], m, n, p[, rfn]) + her!(uplo, alpha, x, A) + +Methods for complex arrays only. Rank-1 update of the Hermitian +matrix "A" with vector "x" as "alpha*x*x' + A". When +"uplo" is 'U' the upper triangle of "A" is updated ('L' for +lower triangle). Returns "A". -Create a random "m" by "n" sparse matrix, in which the -probability of any element being nonzero is independently given by -"p" (and hence the mean density of nonzeros is also exactly -"p"). Nonzero values are sampled from the distribution specified -by "rfn". The uniform distribution is used in case "rfn" is not -specified. The optional "rng" argument specifies a random number -generator, see *Random Numbers*. """ -sprand +Base.LinAlg.BLAS.her! doc""" - sprandn(m, n, p) + herk(uplo, trans, alpha, A) + +Methods for complex arrays only. Returns either the upper triangle +or the lower triangle, according to "uplo" ('U' or 'L'), of +"alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or +'T'). -Create a random "m" by "n" sparse matrix with the specified -(independent) probability "p" of any entry being nonzero, where -nonzero values are sampled from the normal distribution. """ -sprandn +Base.LinAlg.BLAS.herk doc""" - sprandbool(m, n, p) + herk!(uplo, trans, alpha, A, beta, C) + +Methods for complex arrays only. Rank-k update of the Hermitian +matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" +according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' +the upper triangle of "C" is updated ('L' for lower triangle). +Returns "C". -Create a random "m" by "n" sparse boolean matrix with the -specified (independent) probability "p" of any entry being -"true". """ -sprandbool +Base.LinAlg.BLAS.herk! doc""" - etree(A[, post]) + nrm2(n, X, incx) + +2-norm of a vector consisting of "n" elements of array "X" with +stride "incx". -Compute the elimination tree of a symmetric sparse matrix "A" -from "triu(A)" and, optionally, its post-ordering permutation. """ -etree +Base.LinAlg.BLAS.nrm2 doc""" - symperm(A, p) + sbmv(uplo, k, alpha, A, x) -Return the symmetric permutation of A, which is "A[p,p]". A -should be symmetric and sparse, where only the upper triangular -part of the matrix is stored. This algorithm ignores the lower -triangular part of the matrix. Only the upper triangular part of -the result is returned as well. -""" -symperm +Returns "alpha*A*x" where "A" is a symmetric band matrix of +order "size(A,2)" with "k" super-diagonals stored in the +argument "A". -doc""" - nonzeros(A) + sbmv(uplo, k, A, x) + +Returns "A*x" where "A" is a symmetric band matrix of order +"size(A,2)" with "k" super-diagonals stored in the argument +"A". -Return a vector of the structural nonzero values in sparse matrix -"A". This includes zeros that are explicitly stored in the sparse -matrix. The returned vector points directly to the internal nonzero -storage of "A", and any modifications to the returned vector will -mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". """ -nonzeros +Base.LinAlg.BLAS.sbmv doc""" - rowvals(A) + sbmv!(uplo, k, alpha, A, x, beta, y) + +Update vector "y" as "alpha*A*x + beta*y" where "A" is a a +symmetric band matrix of order "size(A,2)" with "k" super- +diagonals stored in the argument "A". The storage layout for +"A" is described the reference BLAS module, level-2 BLAS at +http://www.netlib.org/lapack/explore-html/. + +Returns the updated "y". -Return a vector of the row indices of "A", and any modifications -to the returned vector will mutate "A" as well. Given the -internal storage format of sparse matrices, providing access to how -the row indices are stored internally can be useful in conjuction -with iterating over structural nonzero values. See "nonzeros(A)" -and "nzrange(A, col)". """ -rowvals +Base.LinAlg.BLAS.sbmv! doc""" - nzrange(A, col) + scal(n, a, X, incx) -Return the range of indices to the structural nonzero values of a -sparse matrix column. In conjunction with "nonzeros(A)" and -"rowvals(A)", this allows for convenient iterating over a sparse -matrix +Returns "a*X". - 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 """ -nzrange +Base.LinAlg.BLAS.scal doc""" - exit([code]) + scal!(n, a, X, incx) + +Overwrite "X" with "a*X". Returns "X". -Quit (or control-D at the prompt). The default exit code is zero, -indicating that the processes completed successfully. """ -exit +Base.LinAlg.BLAS.scal! doc""" - quit() + symm(side, ul, alpha, A, B) -Quit the program indicating that the processes completed -successfully. This function calls "exit(0)" (see "exit()"). -""" -quit +Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" +is assumed to be symmetric. Only the "ul" triangle of "A" is +used. -doc""" - atexit(f) + symm(side, ul, A, B) -Register a zero-argument function to be called at exit. -""" -atexit +Returns "A*B" or "B*A" according to "side". "A" is assumed +to be symmetric. Only the "ul" triangle of "A" is used. -doc""" - atreplinit(f) + symm(tA, tB, alpha, A, B) + +Returns "alpha*A*B" or the other three variants according to +"tA" (transpose "A") and "tB". -Register a one-argument function to be called before the REPL -interface is initialized in interactive sessions; this is useful to -customize the interface. The argument of "f" is the REPL object. -This function should be called from within the ".juliarc.jl" -initialization file. """ -atreplinit +Base.LinAlg.BLAS.symm doc""" - isinteractive() -> Bool + symm!(side, ul, alpha, A, B, beta, C) + +Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" +according to "side". "A" is assumed to be symmetric. Only the +"ul" triangle of "A" is used. Returns the updated "C". -Determine whether Julia is running an interactive session. """ -isinteractive +Base.LinAlg.BLAS.symm! doc""" - whos([Module,] [pattern::Regex]) + symv(ul, alpha, A, x) -Print information about exported global variables in a module, -optionally restricted to those matching "pattern". -""" -whos +Returns "alpha*A*x". "A" is assumed to be symmetric. Only the +"ul" triangle of "A" is used. -doc""" - edit(file::AbstractString[, line]) + symv(ul, A, x) + +Returns "A*x". "A" is assumed to be symmetric. Only the +"ul" triangle of "A" is used. -Edit a file optionally providing a line number to edit at. Returns -to the julia prompt when you quit the editor. """ -edit +Base.LinAlg.BLAS.symv doc""" - edit(function[, types]) + symv!(ul, alpha, A, x, beta, y) + +Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed +to be symmetric. Only the "ul" triangle of "A" is used. +Returns the updated "y". -Edit the definition of a function, optionally specifying a tuple of -types to indicate which method to edit. """ -edit +Base.LinAlg.BLAS.symv! doc""" - @edit() + syr!(uplo, alpha, x, A) + +Rank-1 update of the symmetric matrix "A" with vector "x" as +"alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of +"A" is updated ('L' for lower triangle). Returns "A". -Evaluates the arguments to the function call, determines their -types, and calls the "edit" function on the resulting expression """ -@edit +Base.LinAlg.BLAS.syr! doc""" - less(file::AbstractString[, line]) + syrk(uplo, trans, alpha, A) + +Returns either the upper triangle or the lower triangle, according +to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", +according to "trans" ('N' or 'T'). -Show a file using the default pager, optionally providing a -starting line number. Returns to the julia prompt when you quit the -pager. """ -less +Base.LinAlg.BLAS.syrk doc""" - less(function[, types]) + syrk!(uplo, trans, alpha, A, beta, C) + +Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + +beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" +is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is +updated ('L' for lower triangle). Returns "C". -Show the definition of a function using the default pager, -optionally specifying a tuple of types to indicate which method to -see. """ -less +Base.LinAlg.BLAS.syrk! doc""" - @less() + trmm(side, ul, tA, dA, alpha, A, B) + +Returns "alpha*A*B" or one of the other three variants determined +by "side" (A on left or right) and "tA" (transpose A). Only the +"ul" triangle of "A" is used. "dA" indicates if "A" is +unit-triangular (the diagonal is assumed to be all ones). -Evaluates the arguments to the function call, determines their -types, and calls the "less" function on the resulting expression """ -@less +Base.LinAlg.BLAS.trmm doc""" - clipboard(x) + trmm!(side, ul, tA, dA, alpha, A, B) + +Update "B" as "alpha*A*B" or one of the other three variants +determined by "side" (A on left or right) and "tA" (transpose +A). Only the "ul" triangle of "A" is used. "dA" indicates if +"A" is unit-triangular (the diagonal is assumed to be all ones). +Returns the updated "B". -Send a printed form of "x" to the operating system clipboard -("copy"). """ -clipboard +Base.LinAlg.BLAS.trmm! doc""" - clipboard() -> AbstractString + trmv(side, ul, tA, dA, alpha, A, b) + +Returns "alpha*A*b" or one of the other three variants determined +by "side" (A on left or right) and "tA" (transpose A). Only the +"ul" triangle of "A" is used. "dA" indicates if "A" is +unit-triangular (the diagonal is assumed to be all ones). -Return a string with the contents of the operating system clipboard -("paste"). """ -clipboard +Base.LinAlg.BLAS.trmv doc""" - require(file::AbstractString...) + trmv!(side, ul, tA, dA, alpha, A, b) -Load source files once, in the context of the "Main" module, on -every active node, searching standard locations for files. -"require" is considered a top-level operation, so it sets the -current "include" path but does not use it to search for files -(see help for "include"). This function is typically used to load -library code, and is implicitly called by "using" to load -packages. +Update "b" as "alpha*A*b" or one of the other three variants +determined by "side" (A on left or right) and "tA" (transpose +A). Only the "ul" triangle of "A" is used. "dA" indicates if +"A" is unit-triangular (the diagonal is assumed to be all ones). +Returns the updated "b". -When searching for files, "require" first looks in the current -working directory, then looks for package code under "Pkg.dir()", -then tries paths in the global array "LOAD_PATH". """ -require +Base.LinAlg.BLAS.trmv! doc""" - reload(file::AbstractString) + trsm(side, ul, tA, dA, alpha, A, B) + +Returns the solution to "A*X = alpha*B" or one of the other three +variants determined by "side" (A on left or right of "X") and +"tA" (transpose A). Only the "ul" triangle of "A" is used. +"dA" indicates if "A" is unit-triangular (the diagonal is +assumed to be all ones). -Like "require", except forces loading of files regardless of -whether they have been loaded before. Typically used when -interactively developing libraries. """ -reload +Base.LinAlg.BLAS.trsm doc""" - include(path::AbstractString) + trsm!(side, ul, tA, dA, alpha, A, B) + +Overwrite "B" with the solution to "A*X = alpha*B" or one of +the other three variants determined by "side" (A on left or right +of "X") and "tA" (transpose A). Only the "ul" triangle of +"A" is used. "dA" indicates if "A" is unit-triangular (the +diagonal is assumed to be all ones). Returns the updated "B". -Evaluate the contents of a source file in the current context. -During including, a task-local include path is set to the directory -containing the file. Nested calls to "include" will search -relative to that path. All paths refer to files on node 1 when -running in parallel, and files will be fetched from node 1. This -function is typically used to load source interactively, or to -combine files in packages that are broken into multiple source -files. """ -include +Base.LinAlg.BLAS.trsm! doc""" - include_string(code::AbstractString) + trsv(ul, tA, dA, A, b) + +Returns the solution to "A*x = b" or one of the other two +variants determined by "tA" (transpose A) and "ul" (triangle of +"A" is used.) "dA" indicates if "A" is unit-triangular (the +diagonal is assumed to be all ones). -Like "include", except reads code from the given string rather -than from a file. Since there is no file path involved, no path -processing or fetching from node 1 is done. """ -include_string +Base.LinAlg.BLAS.trsv doc""" - which(f, types) + trsv!(ul, tA, dA, A, b) -Returns the method of "f" (a "Method" object) that would be -called for arguments of the given types. +Overwrite "b" with the solution to "A*x = b" or one of the +other two variants determined by "tA" (transpose A) and "ul" +(triangle of "A" used). "dA" indicates if "A" is unit- +triangular (the diagonal is assumed to be all ones). Returns the +updated "b". -If "types" is an abstract type, then the method that would be -called by "invoke" is returned. """ -which +Base.LinAlg.BLAS.trsv! doc""" - which(symbol) + add(pkg, vers...) + +Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and +call "Pkg.resolve()". If "vers" are given, they must be +"VersionNumber" objects and they specify acceptable version +intervals for "pkg". -Return the module in which the binding for the variable referenced -by "symbol" was created. """ -which +Base.Pkg.add doc""" - @which() + available() -> Vector{ASCIIString} -Applied to a function call, it evaluates the arguments to the -specified function call, and returns the "Method" object for the -method that would be called for those arguments. Applied to a -variable, it returns the module in which the variable was bound. It -calls out to the "which" function. -""" -@which +Returns the names of available packages. -doc""" - methods(f[, types]) + available(pkg) -> Vector{VersionNumber} -Returns the method table for "f". +Returns the version numbers available for package "pkg". -If "types" is specified, returns an array of methods whose types -match. """ -methods +Base.Pkg.available doc""" - methodswith(typ[, module or function][, showparents]) + build() -Return an array of methods with an argument of type "typ". If -optional "showparents" is "true", also return arguments with a -parent type of "typ", excluding type "Any". +Run the build scripts for all installed packages in depth-first +recursive order. -The optional second argument restricts the search to a particular -module or function. -""" -methodswith + build(pkgs...) -doc""" - @show() +Run the build script in "deps/build.jl" for each package in +"pkgs" and all of their dependencies in depth-first recursive +order. This is called automatically by "Pkg.resolve()" on all +installed or updated packages. -Show an expression and result, returning the result """ -@show +Base.Pkg.build doc""" - versioninfo([verbose::Bool]) + checkout(pkg[, branch="master"]) + +Checkout the "Pkg.dir(pkg)" repo to the branch "branch". +Defaults to checking out the "master" branch. To go back to using +the newest compatible released version, use "Pkg.free(pkg)" -Print information about the version of Julia in use. If the -"verbose" argument is true, detailed system information is shown -as well. """ -versioninfo +Base.Pkg.checkout doc""" - workspace() + clone(url[, pkg]) -Replace the top-level module ("Main") with a new one, providing a -clean workspace. The previous "Main" module is made available as -"LastMain". A previously-loaded package can be accessed using a -statement such as "using LastMain.Package". +Clone a package directly from the git URL "url". The package does +not need to be a registered in "Pkg.dir("METADATA")". The +package repo is cloned by the name "pkg" if provided; if not +provided, "pkg" is determined automatically from "url". + + clone(pkg) + +If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone +it from that URL on the default branch. The package does not need +to have any registered versions. -This function should only be used interactively. """ -workspace +Base.Pkg.clone doc""" - is(x, y) -> Bool -===(x, y) -> Bool -≡(x, y) -> Bool + dir() -> AbstractString + +Returns the absolute path of the package directory. This defaults +to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION +.minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell +syntax). If the "JULIA_PKGDIR" environment variable is set, then +that path is used in the returned value as "joinpath(ENV["JULIA_ +PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If +"JULIA_PKGDIR" is a relative path, it is interpreted relative to +whatever the current working directory is. + + dir(names...) -> AbstractString + +Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends +path components to the package directory and normalizes the +resulting path. In particular, "Pkg.dir(pkg)" returns the path to +the package "pkg". -Determine whether "x" and "y" are identical, in the sense that -no program could distinguish them. Compares mutable objects by -address in memory, and compares immutable objects (such as numbers) -by contents at the bit level. This function is sometimes called -"egal". """ -is +Base.Pkg.dir doc""" - isa(x, type) -> Bool + edit() + +Opens "Pkg.dir("REQUIRE")" in the editor specified by the +"VISUAL" or "EDITOR" environment variables; when the editor +command returns, it runs "Pkg.resolve()" to determine and install +a new optimal set of installed package versions. -Determine whether "x" is of the given "type". """ -isa +Base.Pkg.edit doc""" - isequal(x, y) - -Similar to "==", except treats all floating-point "NaN" values -as equal to each other, and treats "-0.0" as unequal to "0.0". -The default implementation of "isequal" calls "==", so if you -have a type that doesn't have these floating-point subtleties then -you probably only need to define "==". + free(pkg) -"isequal" is the comparison function used by hash tables -("Dict"). "isequal(x,y)" must imply that "hash(x) == -hash(y)". +Free the package "pkg" to be managed by the package manager +again. It calls "Pkg.resolve()" to determine optimal package +versions after. This is an inverse for both "Pkg.checkout" and +"Pkg.pin". -This typically means that if you define your own "==" function -then you must define a corresponding "hash" (and vice versa). -Collections typically implement "isequal" by calling "isequal" -recursively on all contents. +You can also supply an iterable collection of package names, e.g., +"Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at +once. -Scalar types generally do not need to implement "isequal" -separate from "==", unless they represent floating-point numbers -amenable to a more efficient implementation than that provided as a -generic fallback (based on "isnan", "signbit", and "=="). """ -isequal +Base.Pkg.free doc""" - isless(x, y) + generate(pkg, license) + +Generate a new package named "pkg" with one of these license +keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make +a package with a different license, you can edit it afterwards. +Generate creates a git repo at "Pkg.dir(pkg)" for the package and +inside it "LICENSE.md", "README.md", the julia entrypoint +"\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". -Test whether "x" is less than "y", according to a canonical -total order. Values that are normally unordered, such as "NaN", -are ordered in an arbitrary but consistent fashion. This is the -default comparison used by "sort". Non-numeric types with a -canonical total order should implement this function. Numeric types -only need to implement it if they have special values such as -"NaN". """ -isless +Base.Pkg.generate doc""" - ifelse(condition::Bool, x, y) + init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) + +Initialize "Pkg.dir()" as a package directory. This will be done +automatically when the "JULIA_PKGDIR" is not set and +"Pkg.dir()" uses its default value. As part of this process, +clones a local METADATA git repository from the site and branch +specified by its arguments, which are typically not provided. +Explicit (non-default) arguments can be used to support a custom +METADATA setup. -Return "x" if "condition" is true, otherwise return "y". This -differs from "?" or "if" in that it is an ordinary function, so -all the arguments are evaluated first. In some cases, using -"ifelse" instead of an "if" statement can eliminate the branch -in generated code and provide higher performance in tight loops. """ -ifelse +Base.Pkg.init doc""" - lexcmp(x, y) + installed() -> Dict{ASCIIString,VersionNumber} -Compare "x" and "y" lexicographically and return -1, 0, or 1 -depending on whether "x" is less than, equal to, or greater than -"y", respectively. This function should be defined for -lexicographically comparable types, and "lexless" will call -"lexcmp" by default. -""" -lexcmp +Returns a dictionary mapping installed package names to the +installed version number of each package. -doc""" - lexless(x, y) + installed(pkg) -> Void | VersionNumber + +If "pkg" is installed, return the installed version number, +otherwise return "nothing". -Determine whether "x" is lexicographically less than "y". """ -lexless +Base.Pkg.installed doc""" - typeof(x) + pin(pkg) -Get the concrete type of "x". -""" -typeof +Pin "pkg" at the current version. To go back to using the newest +compatible released version, use "Pkg.free(pkg)" -doc""" - tuple(xs...) + pin(pkg, version) + +Pin "pkg" at registered version "version". -Construct a tuple of the given objects. """ -tuple +Base.Pkg.pin doc""" - ntuple(f::Function, n) + publish() + +For each new package version tagged in "METADATA" not already +published, make sure that the tagged package commits have been +pushed to the repo at the registered URL for the package and if +they all have, open a pull request to "METADATA". -Create a tuple of length "n", computing each element as "f(i)", -where "i" is the index of the element. """ -ntuple +Base.Pkg.publish doc""" - object_id(x) + register(pkg[, url]) + +Register "pkg" at the git URL "url", defaulting to the +configured origin URL of the git repo "Pkg.dir(pkg)". -Get a unique integer id for "x". "object_id(x)==object_id(y)" -if and only if "is(x,y)". """ -object_id +Base.Pkg.register doc""" - hash(x[, h]) + resolve() -Compute an integer hash code such that "isequal(x,y)" implies -"hash(x)==hash(y)". The optional second argument "h" is a hash -code to be mixed with the result. +Determines an optimal, consistent set of package versions to +install or upgrade to. The optimal set of package versions is based +on the contents of "Pkg.dir("REQUIRE")" and the state of +installed packages in "Pkg.dir()", Packages that are no longer +required are moved into "Pkg.dir(".trash")". -New types should implement the 2-argument form, typically by -calling the 2-argument "hash" method recursively in order to mix -hashes of the contents with each other (and with "h"). -Typically, any type that implements "hash" should also implement -its own "==" (hence "isequal") to guarantee the property -mentioned above. """ -hash +Base.Pkg.resolve doc""" - finalizer(x, function) + rm(pkg) + +Remove all requirement entries for "pkg" from +"Pkg.dir("REQUIRE")" and call "Pkg.resolve()". -Register a function "f(x)" to be called when there are no -program-accessible references to "x". The behavior of this -function is unpredictable if "x" is of a bits type. """ -finalizer +Base.Pkg.rm doc""" - finalize(x) + status() + +Prints out a summary of what packages are installed and what +version and state they're in. -Immediately run finalizers registered for object "x". """ -finalize +Base.Pkg.status doc""" - copy(x) + tag(pkg[, ver[, commit]]) + +Tag "commit" as version "ver" of package "pkg" and create a +version entry in "METADATA". If not provided, "commit" defaults +to the current commit of the "pkg" repo. If "ver" is one of the +symbols ":patch", ":minor", ":major" the next patch, minor or +major version is used. If "ver" is not provided, it defaults to +":patch". -Create a shallow copy of "x": the outer structure is copied, but -not all internal values. For example, copying an array produces a -new array with identically-same elements as the original. """ -copy +Base.Pkg.tag doc""" - deepcopy(x) + test() -Create a deep copy of "x": everything is copied recursively, -resulting in a fully independent object. For example, deep-copying -an array produces a new array whose elements are deep copies of the -original elements. Calling *deepcopy* on an object should generally -have the same effect as serializing and then deserializing it. +Run the tests for all installed packages ensuring that each +package's test dependencies are installed for the duration of the +test. A package is tested by running its "test/runtests.jl" file +and test dependencies are specified in "test/REQUIRE". -As a special case, functions can only be actually deep-copied if -they are anonymous, otherwise they are just copied. The difference -is only relevant in the case of closures, i.e. functions which may -contain hidden internal references. + test(pkgs...) + +Run the tests for each package in "pkgs" ensuring that each +package's test dependencies are installed for the duration of the +test. A package is tested by running its "test/runtests.jl" file +and test dependencies are specified in "test/REQUIRE". -While it isn't normally necessary, user-defined types can override -the default "deepcopy" behavior by defining a specialized version -of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" -(which shouldn't otherwise be used), where "T" is the type to be -specialized for, and "dict" keeps track of objects copied so far -within the recursion. Within the definition, "deepcopy_internal" -should be used in place of "deepcopy", and the "dict" variable -should be updated as appropriate before returning. """ -deepcopy +Base.Pkg.test doc""" - isdefined([object], index | symbol) + update() + +Update package the metadata repo – kept in +"Pkg.dir("METADATA")" – then update any fixed packages that can +safely be pulled from their origin; then call "Pkg.resolve()" to +determine a new optimal set of packages versions. -Tests whether an assignable location is defined. The arguments can -be an array and index, a composite object and field name (as a -symbol), or a module and a symbol. With a single symbol argument, -tests whether a global variable with that name is defined in -"current_module()". """ -isdefined +Base.Pkg.update doc""" - convert(T, x) - -Convert "x" to a value of type "T". + callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} -If "T" is an "Integer" type, an "InexactError" will be raised -if "x" is not representable by "T", for example if "x" is not -integer-valued, or is outside the range supported by "T". +Given a previous profiling run, determine who called a particular +function. Supplying the filename (and optionally, range of line +numbers over which the function is defined) allows you to +disambiguate an overloaded method. The returned value is a vector +containing a count of the number of calls and line information +about the caller. One can optionally supply backtrace data +obtained from "retrieve()"; otherwise, the current internal +profile buffer is used. - julia> convert(Int, 3.0) - 3 +""" +Base.Profile.callers - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 +doc""" + clear() -If "T" is a "FloatingPoint" or "Rational" type, then it will -return the closest value to "x" representable by "T". +Clear any existing backtraces from the internal buffer. - julia> x = 1/3 - 0.3333333333333333 +""" +Base.Profile.clear - julia> convert(Float32, x) - 0.33333334f0 +doc""" + clear_malloc_data() - julia> convert(Rational{Int32}, x) - 1//3 +Clears any stored memory allocation data when running julia with " +--track-allocation". Execute the command(s) you want to test (to +force JIT-compilation), then call "clear_malloc_data()". Then +execute your command(s) again, quit Julia, and examine the +resulting "*.mem" files. - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 """ -convert +Base.Profile.clear_malloc_data doc""" - promote(xs...) + fetch() -> data + +Returns a reference to the internal buffer of backtraces. Note that +subsequent operations, like "clear()", can affect "data" unless +you first make a copy. Note that the values in "data" have +meaning only on this machine in the current session, because it +depends on the exact memory addresses used in JIT-compiling. This +function is primarily for internal use; "retrieve()" may be a +better choice for most users. -Convert all arguments to their common promotion type (if any), and -return them all (as a tuple). """ -promote +Base.Profile.fetch doc""" - oftype(x, y) + init(; n::Integer, delay::Float64) + +Configure the "delay" between backtraces (measured in seconds), +and the number "n" of instruction pointers that may be stored. +Each instruction pointer corresponds to a single line of code; +backtraces generally consist of a long list of instruction +pointers. Default settings can be obtained by calling this function +with no arguments, and each can be set independently using keywords +or in the order "(n, delay)". -Convert "y" to the type of "x" ("convert(typeof(x), y)"). """ -oftype +Base.Profile.init doc""" - widen(type | x) + print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) -If the argument is a type, return a "larger" type (for numeric -types, this will be a type with at least as much range and -precision as the argument, and usually more). Otherwise the -argument "x" is converted to "widen(typeof(x))". +Prints profiling results to "io" (by default, "STDOUT"). If you +do not supply a "data" vector, the internal buffer of accumulated +backtraces will be used. "format" can be ":tree" or ":flat". +If "C==true", backtraces from C and Fortran code are shown. +"combine==true" merges instruction pointers that correspond to +the same line of code. "cols" controls the width of the display. - julia> widen(Int32) - Int64 + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + +Prints profiling results to "io". This variant is used to examine +results exported by a previous call to "retrieve()". Supply the +vector "data" of backtraces and a dictionary "lidict" of line +information. - julia> widen(1.5f0) - 1.5 """ -widen +Base.Profile.print doc""" - identity(x) + retrieve() -> data, lidict + +"Exports" profiling results in a portable format, returning the +set of all backtraces ("data") and a dictionary that maps the +(session-specific) instruction pointers in "data" to "LineInfo" +values that store the file name, function name, and line number. +This function allows you to save profiling results for future +analysis. -The identity function. Returns its argument. """ -identity +Base.Profile.retrieve doc""" - super(T::DataType) + @test(ex) + +Test the expression "ex" and calls the current handler to handle +the result. -Return the supertype of DataType T """ -super +Base.Test.@test doc""" - issubtype(type1, type2) + @test_approx_eq(a, b) + +Test two floating point numbers "a" and "b" for equality taking +in account small numerical errors. -True if and only if all values of "type1" are also of "type2". -Can also be written using the "<:" infix operator as "type1 <: -type2". """ -issubtype +Base.Test.@test_approx_eq doc""" - <:(T1, T2) + @test_approx_eq_eps(a, b, tol) + +Test two floating point numbers "a" and "b" for equality taking +in account a margin of tolerance given by "tol". -Subtype operator, equivalent to "issubtype(T1,T2)". """ -Base.(:(<:)) +Base.Test.@test_approx_eq_eps doc""" - subtypes(T::DataType) + @test_throws(extype, ex) + +Test that the expression "ex" throws an exception of type +"extype" and calls the current handler to handle the result. -Return a list of immediate subtypes of DataType T. Note that all -currently loaded subtypes are included, including those not visible -in the current module. """ -subtypes +Base.Test.@test_throws doc""" - typemin(type) + with_handler(f, handler) + +Run the function "f" using the "handler" as the handler. -The lowest value representable by the given (real) numeric type. """ -typemin +Base.Test.with_handler doc""" - typemax(type) + ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) -The highest value representable by the given (real) numeric type. -""" -typemax +Call function in C-exported shared library, specified by +"(function name, library)" tuple, where each component is an +AbstractString or :Symbol. -doc""" - realmin(type) +Note that the argument type tuple must be a literal tuple, and not +a tuple-valued variable or expression. Alternatively, ccall may +also be used to call a function pointer, such as one returned by +dlsym. + +Each "ArgumentValue" to the "ccall" will be converted to the +corresponding "ArgumentType", by automatic insertion of calls to +"unsafe_convert(ArgumentType, cconvert(ArgumentType, +ArgumentValue))". (see also the documentation for each of these +functions for further details). In most cases, this simply results +in a call to "convert(ArgumentType, ArgumentValue)" -The smallest in absolute value non-subnormal value representable by -the given floating-point type """ -realmin +Base.ccall doc""" - realmax(type) + 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)". -The highest finite value representable by the given floating-point -type """ -realmax +Base.in doc""" - maxintfloat(type) + Base64DecodePipe(istream) + +Returns a new read-only I/O stream, which decodes base64-encoded +data read from "istream". -The largest integer losslessly representable by the given floating- -point type """ -maxintfloat +Base64DecodePipe doc""" - sizeof(type) + Base64EncodePipe(ostream) + +Returns a new write-only I/O stream, which converts any bytes +written to it into base64-encoded ASCII bytes written to +"ostream". Calling "close" on the "Base64Pipe" stream is +necessary to complete the encoding (but does not close +"ostream"). -Size, in bytes, of the canonical binary representation of the given -type, if any. """ -sizeof +Base64EncodePipe doc""" - eps([type]) + Bidiagonal(dv, ev, isupper) + +Constructs an upper ("isupper=true") or lower ("isupper=false") +bidiagonal matrix using the given diagonal ("dv") and off- +diagonal ("ev") vectors. The result is of type "Bidiagonal" +and provides efficient specialized linear solvers, but may be +converted into a regular matrix with "full()". -The distance between 1.0 and the next larger representable -floating-point value of "type". Only floating-point types are -sensible arguments. If "type" is omitted, then "eps(Float64)" -is returned. """ -eps +Bidiagonal doc""" - eps(x) + BigFloat(x) + +Create an arbitrary precision floating point number. "x" may be +an "Integer", a "Float64" or a "BigInt". The usual +mathematical operators are defined for this type, and results are +promoted to a "BigFloat". + +Note that because decimal literals are converted to floating point +numbers when parsed, "BigFloat(2.1)" may not yield what you +expect. You may instead prefer to initialize constants from strings +via "parse()", or using the "big" string literal. + + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision -The distance between "x" and the next larger representable -floating-point value of the same type as "x". """ -eps +BigFloat doc""" - promote_type(type1, type2) + BigInt(x) + +Create an arbitrary precision integer. "x" may be an "Int" (or +anything that can be converted to an "Int"). The usual +mathematical operators are defined for this type, and results are +promoted to a "BigInt". + +Instances can be constructed from strings via "parse()", or using +the "big" string literal. -Determine a type big enough to hold values of each argument type -without loss, whenever possible. In some cases, where no type -exists to which both types can be promoted losslessly, some loss is -tolerated; for example, "promote_type(Int64,Float64)" returns -"Float64" even though strictly, not all "Int64" values can be -represented exactly as "Float64" values. """ -promote_type +BigInt doc""" - promote_rule(type1, type2) + BoundsError([a][, i]) + +An indexing operation into an array, "a", tried to access an out- +of-bounds element, "i". -Specifies what type should be used by "promote" when given values -of types "type1" and "type2". This function should not be -called directly, but should have definitions added to it for new -types as appropriate. """ -promote_rule +BoundsError doc""" - getfield(value, name::Symbol) + C_NULL + +The C null pointer constant, sometimes used when calling external +code. -Extract a named field from a value of composite type. The syntax -"a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls -"getfield(a, b)". """ -getfield +C_NULL doc""" - setfield!(value, name::Symbol, x) + Cchar + +Equivalent to the native "char" c-type -Assign "x" to a named field in "value" of composite type. The -syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax -"a.(b) = c" calls "setfield!(a, b, c)". """ -setfield! +Cchar doc""" - fieldoffsets(type) - -The byte offset of each field of a type relative to the data start. -For example, we could use it in the following manner to summarize -information about a struct type: + Cdouble - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; +Equivalent to the native "double" c-type (Float64) - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) """ -fieldoffsets +Cdouble doc""" - fieldtype(type, name::Symbol | index::Int) + Cfloat + +Equivalent to the native "float" c-type (Float32) -Determine the declared type of a field (specified by name or index) -in a composite type. """ -fieldtype +Cfloat doc""" - isimmutable(v) + Cint + +Equivalent to the native "signed int" c-type (Int32) -True if value "v" is immutable. See *Immutable Composite Types* -for a discussion of immutability. Note that this function works on -values, so if you give it a type, it will tell you that a value of -"DataType" is mutable. """ -isimmutable +Cint doc""" - isbits(T) - -True if "T" is a "plain data" type, meaning it is immutable and -contains no references to other values. Typical examples are -numeric types such as "UInt8", "Float64", and -"Complex{Float64}". + Cintmax_t - julia> isbits(Complex{Float64}) - true +Equivalent to the native "intmax_t" c-type (Int64) - julia> isbits(Complex) - false """ -isbits +Cintmax_t doc""" - isleaftype(T) + Clong + +Equivalent to the native "signed long" c-type -Determine whether "T" is a concrete type that can have instances, -meaning its only subtypes are itself and "None" (but "T" itself -is not "None"). """ -isleaftype +Clong doc""" - typejoin(T, S) + Clonglong + +Equivalent to the native "signed long long" c-type (Int64) -Compute a type that contains both "T" and "S". """ -typejoin +Clonglong doc""" - typeintersect(T, S) + Coff_t + +Equivalent to the native "off_t" c-type -Compute a type that contains the intersection of "T" and "S". -Usually this will be the smallest such type or one close to it. """ -typeintersect +Coff_t doc""" - instances(T::Type) + Condition() + +Create an edge-triggered event source that tasks can wait for. +Tasks that call "wait" on a "Condition" are suspended and +queued. Tasks are woken up when "notify" is later called on the +"Condition". Edge triggering means that only tasks waiting at the +time "notify" is called can be woken up. For level-triggered +notifications, you must keep extra state to keep track of whether a +notification has happened. The "RemoteRef" type does this, and so +can be used for level-triggered events. -Return a collection of all instances of the given type, if -applicable. Mostly used for enumerated types (see "@enum"). """ -instances +Condition doc""" - method_exists(f, Tuple type) -> Bool + Cptrdiff_t -Determine whether the given generic function has a method matching -the given "Tuple" of argument types. +Equivalent to the native "ptrdiff_t" c-type (Int) - julia> method_exists(length, Tuple{Array}) - true """ -method_exists +Cptrdiff_t doc""" - applicable(f, args...) -> Bool + Cshort -Determine whether the given generic function has a method -applicable to the given arguments. +Equivalent to the native "signed short" c-type (Int16) - julia> function f(x, y) - x + y - end; +""" +Cshort - julia> applicable(f, 1) - false +doc""" + Csize_t + +Equivalent to the native "size_t" c-type (UInt) - julia> applicable(f, 1, 2) - true """ -applicable +Csize_t doc""" - invoke(f, (types...), args...) + Cssize_t + +Equivalent to the native "ssize_t" c-type -Invoke a method for the given generic function matching the -specified types (as a tuple), on the specified arguments. The -arguments must be compatible with the specified types. This allows -invoking a method other than the most specific matching method, -which is useful when the behavior of a more general definition is -explicitly needed (often as part of the implementation of a more -specific method of the same function). """ -invoke +Cssize_t doc""" - |>(x, f) + Cuchar -Applies a function to the preceding argument. This allows for easy -function chaining. +Equivalent to the native "unsigned char" c-type (UInt8) - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 """ -Base.(:(|>)) +Cuchar doc""" - call(x, args...) + Cuint + +Equivalent to the native "unsigned int" c-type (UInt32) -If "x" is not a "Function", then "x(args...)" is equivalent -to "call(x, args...)". This means that function-like behavior -can be added to any type by defining new "call" methods. """ -call +Cuint doc""" - eval([m::Module], expr::Expr) + Cuintmax_t + +Equivalent to the native "uintmax_t" c-type (UInt64) -Evaluate an expression in the given module and return the result. -Every module (except those defined with "baremodule") has its own -1-argument definition of "eval", which evaluates expressions in -that module. """ -eval +Cuintmax_t doc""" - @eval() + Culong + +Equivalent to the native "unsigned long" c-type -Evaluate an expression and return the value. """ -@eval +Culong doc""" - evalfile(path::AbstractString) + Culonglong + +Equivalent to the native "unsigned long long" c-type (UInt64) -Load the file using "include", evaluate all expressions, and -return the value of the last one. """ -evalfile +Culonglong doc""" - esc(e::ANY) + Cushort + +Equivalent to the native "unsigned short" c-type (UInt16) -Only valid in the context of an Expr returned from a macro. -Prevents the macro hygiene pass from turning embedded variables -into gensym variables. See the *Macros* section of the -Metaprogramming chapter of the manual for more details and -examples. """ -esc +Cushort doc""" - gensym([tag]) + Cwchar_t + +Equivalent to the native "wchar_t" c-type (Int32) -Generates a symbol which will not conflict with other variable -names. """ -gensym +Cwchar_t doc""" - @gensym() + Date -Generates a gensym symbol for a variable. For example, "@gensym x -y" is transformed into "x = gensym("x"); y = gensym("y")". -""" -@gensym +"Date" wraps a "UTInstant{Day}" and interprets it according to +the proleptic Gregorian calendar. -doc""" - parse(str, start; greedy=true, raise=true) + Date(y[, m, d]) -> Date + +Construct a "Date" type by parts. Arguments must be convertible +to "Int64". + + Date(period::Period...) -> Date + +Constuct a Date type by "Period" type parts. Arguments may be in +any order. Date parts not provided will default to the value of +"Dates.default(period)". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + +Create a Date through the adjuster API. The starting point will be +constructed from the provided "y, m" arguments, and will be +adjusted until "f::Function" returns true. The step size in +adjusting can be provided manually through the "step" keyword. If +"negate=true", then the adjusting will stop when "f::Function" +returns false instead of true. "limit" provides a limit to the +max number of iterations the adjustment API will pursue before +throwing an error (given that "f::Function" is never satisfied). + + Date(dt::DateTime) -> Date + +Converts a "DateTime" type to a "Date". The hour, minute, +second, and millisecond parts of the "DateTime" are truncated, so +only the year, month and day parts are used in construction. + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + +Construct a Date type by parsing a "dt" date string following the +pattern given in the "format" string. Follows the same +conventions as "DateTime" above. + + Date(dt::AbstractString, df::DateFormat) -> Date + +Parse a date from a date string "dt" using a "DateFormat" +object "df". -Parse the expression string and return an expression (which could -later be passed to eval for execution). Start is the index of the -first character to start parsing. If "greedy" is true (default), -"parse" will try to consume as much input as it can; otherwise, -it will stop as soon as it has parsed a valid expression. -Incomplete but otherwise syntactically valid expressions will -return "Expr(:incomplete, "(error message)")". If "raise" is -true (default), syntax errors other than incomplete expressions -will raise an error. If "raise" is false, "parse" will return -an expression that will raise an error upon evaluation. """ -parse +Dates.Date doc""" - parse(str; raise=true) + DateTime + +"DateTime" wraps a "UTInstant{Millisecond}" and interprets it +according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + +Construct a DateTime type by parts. Arguments must be convertible +to "Int64". + + DateTime(periods::Period...) -> DateTime + +Constuct a DateTime type by "Period" type parts. Arguments may be +in any order. DateTime parts not provided will default to the value +of "Dates.default(period)". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + +Create a DateTime through the adjuster API. The starting point will +be constructed from the provided "y, m, d..." arguments, and will +be adjusted until "f::Function" returns true. The step size in +adjusting can be provided manually through the "step" keyword. If +"negate=true", then the adjusting will stop when "f::Function" +returns false instead of true. "limit" provides a limit to the +max number of iterations the adjustment API will pursue before +throwing an error (in the case that "f::Function" is never +satisfied). + + DateTime(dt::Date) -> DateTime + +Converts a "Date" type to a "DateTime". The hour, minute, +second, and millisecond parts of the new "DateTime" are assumed +to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + +Construct a DateTime type by parsing the "dt" date string +following the pattern given in the "format" string. The following +codes can be used for constructing format strings: + ++-----------------+-----------+-----------------------------------------------------------------+ +| Code | Matches | Comment | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"y\" | 1996, 96 | Returns year of 1996, 0096 | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"m\" | 1, 01 | Matches 1 or 2-digit months | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"U\" | January | Matches full month names according to the \"locale\" keyword | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"d\" | 1, 01 | Matches 1 or 2-digit days | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"H\" | 00 | Matches hours | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"M\" | 00 | Matches minutes | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"S\" | 00 | Matches seconds | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"s\" | .500 | Matches milliseconds | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"e\" | Mon, Tues | Matches abbreviated days of the week | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"E\" | Monday | Matches full name days of the week | ++-----------------+-----------+-----------------------------------------------------------------+ +| \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | ++-----------------+-----------+-----------------------------------------------------------------+ + +All characters not listed above are treated as delimiters between +date and time slots. So a "dt" string of +"1996-01-15T00:00:00.0" would have a "format" string like +"y-m-dTH:M:S.s". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + +Similar form as above for parsing a "DateTime", but passes a +"DateFormat" object instead of a raw formatting string. It is +more efficient if similarly formatted date strings will be parsed +repeatedly to first create a "DateFormat" object then use this +method for parsing. -Parse the whole string greedily, returning a single expression. An -error is thrown if there are additional characters after the first -expression. If "raise" is true (default), syntax errors will -raise an error; otherwise, "parse" will return an expression that -will raise an error upon evaluation. """ -parse +Dates.DateTime doc""" - Nullable(x) + Dates.DateFormat(format::AbstractString) -> DateFormat + +Construct a date formatting object that can be passed repeatedly +for parsing similarly formatted date strings. "format" is a +format string in the form described above (e.g. ""yyyy-mm- +dd""). -Wrap value "x" in an object of type "Nullable", which indicates -whether a value is present. "Nullable(x)" yields a non-empty -wrapper, and "Nullable{T}()" yields an empty instance of a -wrapper that might contain a value of type "T". """ -Nullable +Dates.Dates doc""" - get(x) + Day -Attempt to access the value of the "Nullable" object, "x". -Returns the value if it is present; otherwise, throws a -"NullException". """ -get +Dates.Day doc""" - get(x, y) + Hour -Attempt to access the value of the "Nullable{T}" object, "x". -Returns the value if it is present; otherwise, returns "convert(T, -y)". """ -get +Dates.Hour doc""" - isnull(x) + Instant + +"Instant" types represent integer-based, machine representations +of time as continuous timelines starting from an epoch. -Is the "Nullable" object "x" null, i.e. missing a value? """ -isnull +Dates.Instant doc""" - run(command) + Millisecond + +"Period" types represent discrete, human representations of time. -Run a command object, constructed with backticks. Throws an error -if anything goes wrong, including the process exiting with a non- -zero status. """ -run +Dates.Millisecond doc""" - spawn(command) + Minute -Run a command object asynchronously, returning the resulting -"Process" object. """ -spawn +Dates.Minute doc""" - DevNull + Month -Used in a stream redirect to discard all data written to it. -Essentially equivalent to /dev/null on Unix or NUL on Windows. -Usage: "run(`cat test.txt` |> DevNull)" """ -DevNull +Dates.Month doc""" - success(command) + Period -Run a command object, constructed with backticks, and tell whether -it was successful (exited with a code of 0). An exception is raised -if the process cannot be started. """ -success +Dates.Period doc""" - process_running(p::Process) + Second -Determine whether a process is currently running. """ -process_running +Dates.Second doc""" - process_exited(p::Process) + TimeType + +"TimeType" types wrap "Instant" machine instances to provide +human representations of the machine instant. -Determine whether a process has exited. """ -process_exited +Dates.TimeType doc""" - kill(p::Process, signum=SIGTERM) + Week -Send a signal to a process. The default is to terminate the -process. """ -kill +Dates.Week doc""" - open(command, mode::AbstractString="r", stdio=DevNull) + Year + + Year(dt::TimeType) -> Year +Month(dt::TimeType) -> Month +Week(dt::TimeType) -> Week +Day(dt::TimeType) -> Day +Hour(dt::TimeType) -> Hour +Minute(dt::TimeType) -> Minute +Second(dt::TimeType) -> Second +Millisecond(dt::TimeType) -> Millisecond + +Return the field part of a Date or DateTime as a "Period" type. + + Year(v) +Month(v) +Week(v) +Day(v) +Hour(v) +Minute(v) +Second(v) +Millisecond(v) + +Construct a "Period" type with the given "v" value. Input must +be losslessly convertible to an "Int64". -Start running "command" asynchronously, and return a tuple -"(stream,process)". If "mode" is ""r"", then "stream" -reads from the process's standard output and "stdio" optionally -specifies the process's standard input stream. If "mode" is -""w"", then "stream" writes to the process's standard input -and "stdio" optionally specifies the process's standard output -stream. """ -open +Dates.Year doc""" - open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + datetime2julian(dt::DateTime) -> Float64 + +Takes the given DateTime and returns the number of Julian calendar +days since the julian epoch as a "Float64". -Similar to "open(command, mode, stdio)", but calls "f(stream)" -on the resulting read or write stream, then closes the stream and -waits for the process to complete. Returns the value returned by -"f". """ -open +Dates.datetime2julian doc""" - Sys.set_process_title(title::AbstractString) + datetime2rata(dt::TimeType) -> Int64 + +Returns the number of Rata Die days since epoch from the given Date +or DateTime. -Set the process title. No-op on some operating systems. (not -exported) """ -Sys +Dates.datetime2rata doc""" - Sys.get_process_title() + datetime2unix(dt::DateTime) -> Float64 + +Takes the given DateTime and returns the number of seconds since +the unix epoch as a "Float64". -Get the process title. On some systems, will always return empty -string. (not exported) """ -Sys +Dates.datetime2unix doc""" - readandwrite(command) + dayabbr(dt::TimeType; locale="english") -> AbstractString + +Return the abbreviated name corresponding to the day of the week of +the Date or DateTime in the given "locale". -Starts running a command asynchronously, and returns a tuple -(stdout,stdin,process) of the output stream and input stream of the -process, and the process object itself. """ -readandwrite +Dates.dayabbr doc""" - ignorestatus(command) + dayname(dt::TimeType; locale="english") -> AbstractString + +Return the full day name corresponding to the day of the week of +the Date or DateTime in the given "locale". -Mark a command object so that running it will not throw an error if -the result code is non-zero. """ -ignorestatus +Dates.dayname doc""" - detach(command) + dayofquarter(dt::TimeType) -> Int + +Returns the day of the current quarter of "dt". Range of value is +1:92. -Mark a command object so that it will be run in a new process -group, allowing it to outlive the julia process, and not have -Ctrl-C interrupts passed to it. """ -detach +Dates.dayofquarter doc""" - setenv(command, env; dir=working_dir) + dayofweek(dt::TimeType) -> Int64 -Set environment variables to use when running the given command. -"env" is either a dictionary mapping strings to strings, an array -of strings of the form ""var=val"", or zero or more -""var"=>val" pair arguments. In order to modify (rather than -replace) the existing environment, create "env" by "copy(ENV)" -and then setting "env["var"]=val" as desired, or use -"withenv". +Returns the day of the week as an "Int64" with "1 = Monday, 2 = +Tuesday, etc.". -The "dir" keyword argument can be used to specify a working -directory for the command. """ -setenv +Dates.dayofweek doc""" - withenv(f::Function, kv::Pair...) + dayofweekofmonth(dt::TimeType) -> Int + +For the day of week of "dt", returns which number it is in +"dt"'s month. So if the day of the week of "dt" is Monday, then +"1 = First Monday of the month, 2 = Second Monday of the month, +etc." In the range 1:5. -Execute "f()" in an environment that is temporarily modified (not -replaced as in "setenv") by zero or more ""var"=>val" -arguments "kv". "withenv" is generally used via the -"withenv(kv...) do ... end" syntax. A value of "nothing" can -be used to temporarily unset an environment variable (if it is -set). When "withenv" returns, the original environment has been -restored. """ -withenv +Dates.dayofweekofmonth doc""" - pipe(from, to, ...) + dayofyear(dt::TimeType) -> Int -Create a pipeline from a data source to a destination. The source -and destination can be commands, I/O streams, strings, or results -of other "pipe" calls. At least one argument must be a command. -Strings refer to filenames. When called with more than two -arguments, they are chained together from left to right. For -example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". -This provides a more concise way to specify multi-stage pipelines. +Returns the day of the year for "dt" with January 1st being day +1. -**Examples**: - * "run(pipe(`ls`, `grep xyz`))" +""" +Dates.dayofyear - * "run(pipe(`ls`, "out.txt"))" +doc""" + daysinmonth(dt::TimeType) -> Int + +Returns the number of days in the month of "dt". Value will be +28, 29, 30, or 31. - * "run(pipe("out.txt", `grep xyz`))" """ -pipe +Dates.daysinmonth doc""" - pipe(command; stdin, stdout, stderr, append=false) - -Redirect I/O to or from the given "command". Keyword arguments -specify which of the command's streams should be redirected. -"append" controls whether file output appends to the file. This -is a more general version of the 2-argument "pipe" function. -"pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when -"from" is a command, and to "pipe(to, stdin=from)" when -"from" is another kind of data source. + daysinyear(dt::TimeType) -> Int -**Examples**: - * "run(pipe(`dothings`, stdout="out.txt", - stderr="errs.txt"))" +Returns 366 if the year of "dt" is a leap year, otherwise returns +365. - * "run(pipe(`update`, stdout="log.txt", append=true))" """ -pipe +Dates.daysinyear doc""" - gethostname() -> AbstractString + daysofweekinmonth(dt::TimeType) -> Int + +For the day of week of "dt", returns the total number of that day +of the week in "dt"'s month. Returns 4 or 5. Useful in temporal +expressions for specifying the last day of a week in a month by +including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the +adjuster function. -Get the local machine's host name. """ -gethostname +Dates.daysofweekinmonth doc""" - getipaddr() -> AbstractString + default(p::Period) -> Period + +Returns a sensible "default" value for the input Period by +returning "one(p)" for Year, Month, and Day, and "zero(p)" for +Hour, Minute, Second, and Millisecond. -Get the IP address of the local machine, as a string of the form -"x.x.x.x". """ -getipaddr +Dates.default doc""" - getpid() -> Int32 + eps(::DateTime) -> Millisecond +eps(::Date) -> Day + +Returns "Millisecond(1)" for "DateTime" values and "Day(1)" +for "Date" values. -Get julia's process ID. """ -getpid +Dates.eps doc""" - time() + firstdayofmonth(dt::TimeType) -> TimeType + +Adjusts "dt" to the first day of its month. -Get the system time in seconds since the epoch, with fairly high -(typically, microsecond) resolution. """ -time +Dates.firstdayofmonth doc""" - time_ns() + firstdayofquarter(dt::TimeType) -> TimeType + +Adjusts "dt" to the first day of its quarter. -Get the time in nanoseconds. The time corresponding to 0 is -undefined, and wraps every 5.8 years. """ -time_ns +Dates.firstdayofquarter doc""" - tic() + firstdayofweek(dt::TimeType) -> TimeType + +Adjusts "dt" to the Monday of its week. -Set a timer to be read by the next call to "toc()" or "toq()". -The macro call "@time expr" can also be used to time evaluation. """ -tic +Dates.firstdayofweek doc""" - toc() + firstdayofyear(dt::TimeType) -> TimeType + +Adjusts "dt" to the first day of its year. -Print and return the time elapsed since the last "tic()". """ -toc +Dates.firstdayofyear doc""" - toq() + isleapyear(dt::TimeType) -> Bool + +Returns true if the year of "dt" is a leap year. -Return, but do not print, the time elapsed since the last -"tic()". """ -toq +Dates.isleapyear doc""" - @time() + julian2datetime(julian_days) -> DateTime + +Takes the number of Julian calendar days since epoch +"-4713-11-24T12:00:00" and returns the corresponding DateTime. -A macro to execute an expression, printing the time it took to -execute, the number of allocations, and the total number of bytes -its execution caused to be allocated, before returning the value of -the expression. """ -@time +Dates.julian2datetime doc""" - @timev() + lastdayofmonth(dt::TimeType) -> TimeType + +Adjusts "dt" to the last day of its month. -This is a verbose version of the "@time" macro, it first prints -the same information as "@time", then any non-zero memory -allocation counters, and then returns the value of the expression. """ -@timev +Dates.lastdayofmonth doc""" - @timed() + lastdayofquarter(dt::TimeType) -> TimeType + +Adjusts "dt" to the last day of its quarter. -A macro to execute an expression, and return the value of the -expression, elapsed time, total bytes allocated, garbage collection -time, and an object with various memory allocation counters. """ -@timed +Dates.lastdayofquarter doc""" - @elapsed() + lastdayofweek(dt::TimeType) -> TimeType + +Adjusts "dt" to the Sunday of its week. -A macro to evaluate an expression, discarding the resulting value, -instead returning the number of seconds it took to execute as a -floating-point number. """ -@elapsed +Dates.lastdayofweek doc""" - @allocated() + lastdayofyear(dt::TimeType) -> TimeType + +Adjusts "dt" to the last day of its year. -A macro to evaluate an expression, discarding the resulting value, -instead returning the total number of bytes allocated during -evaluation of the expression. Note: the expression is evaluated -inside a local function, instead of the current context, in order -to eliminate the effects of compilation, however, there still may -be some allocations due to JIT compilation. This also makes the -results inconsistent with the "@time" macros, which do not try to -adjust for the effects of compilation. """ -@allocated +Dates.lastdayofyear doc""" - EnvHash() -> EnvHash + monthabbr(dt::TimeType; locale="english") -> AbstractString + +Return the abbreviated month name of the Date or DateTime in the +given "locale". -A singleton of this type provides a hash table interface to -environment variables. """ -EnvHash +Dates.monthabbr doc""" - ENV + monthday(dt::TimeType) -> (Int64, Int64) + +Simultaneously return the month and day parts of a Date or +DateTime. -Reference to the singleton "EnvHash", providing a dictionary -interface to system environment variables. """ -ENV +Dates.monthday doc""" - @unix() + monthname(dt::TimeType; locale="english") -> AbstractString + +Return the full name of the month of the Date or DateTime in the +given "locale". -Given "@unix? a : b", do "a" on Unix systems (including Linux -and OS X) and "b" elsewhere. See documentation for Handling -Platform Variations in the Calling C and Fortran Code section of -the manual. """ -@unix +Dates.monthname doc""" - @osx() + now() -> DateTime + +Returns a DateTime corresponding to the user's system time +including the system timezone locale. + + now(::Type{UTC}) -> DateTime + +Returns a DateTime corresponding to the user's system time as +UTC/GMT. -Given "@osx? a : b", do "a" on OS X and "b" elsewhere. See -documentation for Handling Platform Variations in the Calling C and -Fortran Code section of the manual. """ -@osx +Dates.now doc""" - @linux() + quarterofyear(dt::TimeType) -> Int + +Returns the quarter that "dt" resides in. Range of value is 1:4. -Given "@linux? a : b", do "a" on Linux and "b" elsewhere. See -documentation for Handling Platform Variations in the Calling C and -Fortran Code section of the manual. """ -@linux +Dates.quarterofyear doc""" - @windows() + rata2datetime(days) -> DateTime + +Takes the number of Rata Die days since epoch +"0000-12-31T00:00:00" and returns the corresponding DateTime. -Given "@windows? a : b", do "a" on Windows and "b" elsewhere. -See documentation for Handling Platform Variations in the Calling C -and Fortran Code section of the manual. """ -@windows +Dates.rata2datetime doc""" - error(message::AbstractString) + today() -> Date + +Returns the date portion of "now()". -Raise an "ErrorException" with the given message """ -error +Dates.today doc""" - throw(e) + tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + +Adjusts "dt" to the first "dow" of its month. Alternatively, +"of=Year" will adjust to the first "dow" of the year. -Throw an object as an exception """ -throw +Dates.tofirst doc""" - rethrow([e]) + tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + +Adjusts "dt" to the last "dow" of its month. Alternatively, +"of=Year" will adjust to the last "dow" of the year. -Throw an object without changing the current exception backtrace. -The default argument is the current exception (if called within a -"catch" block). """ -rethrow +Dates.tolast doc""" - backtrace() + tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + +Adjusts "dt" to the next day of week corresponding to "dow" +with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows +the current "dt" to be considered as the next "dow", allowing +for no adjustment to occur. + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + +Adjusts "dt" by iterating at most "limit" iterations by +"step" increments until "func" returns true. "func" must take +a single "TimeType" argument and return a "Bool". "same" +allows "dt" to be considered in satisfying "func". "negate" +will make the adjustment process terminate when "func" returns +false instead of true. -Get a backtrace object for the current program point. """ -backtrace +Dates.tonext doc""" - catch_backtrace() + toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + +Adjusts "dt" to the previous day of week corresponding to "dow" +with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows +the current "dt" to be considered as the previous "dow", +allowing for no adjustment to occur. + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + +Adjusts "dt" by iterating at most "limit" iterations by +"step" increments until "func" returns true. "func" must take +a single "TimeType" argument and return a "Bool". "same" +allows "dt" to be considered in satisfying "func". "negate" +will make the adjustment process terminate when "func" returns +false instead of true. -Get the backtrace of the current exception, for use within -"catch" blocks. """ -catch_backtrace +Dates.toprev doc""" - assert(cond) + trunc(dt::TimeType, ::Type{Period}) -> TimeType + +Truncates the value of "dt" according to the provided "Period" +type. E.g. if "dt" is "1996-01-01T12:30:00", then +"trunc(dt,Day) == 1996-01-01T00:00:00". -Throw an "AssertionError" if "cond" is false. Also available as -the macro "@assert expr". """ -assert +Dates.trunc doc""" - ArgumentError(msg) + unix2datetime(x) -> DateTime + +Takes the number of seconds since unix epoch +"1970-01-01T00:00:00" and converts to the corresponding DateTime. -The parameters to a function call do not match a valid signature. """ -ArgumentError +Dates.unix2datetime doc""" - AssertionError([msg]) + year(dt::TimeType) -> Int64 +month(dt::TimeType) -> Int64 +week(dt::TimeType) -> Int64 +day(dt::TimeType) -> Int64 +hour(dt::TimeType) -> Int64 +minute(dt::TimeType) -> Int64 +second(dt::TimeType) -> Int64 +millisecond(dt::TimeType) -> Int64 + +Return the field part of a Date or DateTime as an "Int64". -The asserted condition did not evalutate to "true". """ -AssertionError +Dates.year doc""" - BoundsError([a][, i]) + yearmonth(dt::TimeType) -> (Int64, Int64) + +Simultaneously return the year and month parts of a Date or +DateTime. -An indexing operation into an array, "a", tried to access an out- -of-bounds element, "i". """ -BoundsError +Dates.yearmonth + +doc""" + yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + +Simultaneously return the year, month, and day parts of a Date or +DateTime. + +""" +Dates.yearmonthday + +doc""" + DevNull + +Used in a stream redirect to discard all data written to it. +Essentially equivalent to /dev/null on Unix or NUL on Windows. +Usage: "run(`cat test.txt` |> DevNull)" + +""" +DevNull + +doc""" + 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{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 + +Alternatively, a sequence of pair arguments may be passed. + + julia> Dict("A"=>1, "B"=>2) + Dict{ASCIIString,Int64} with 2 entries: + "B" => 2 + "A" => 1 + +""" +Dict doc""" DimensionMismatch([msg]) The objects called do not have matching dimensionality. + """ DimensionMismatch @@ -2696,6 +2862,7 @@ doc""" DivideError() Integer division was attempted with a denominator value of 0. + """ DivideError @@ -2704,1289 +2871,1239 @@ doc""" The arguments to a function or constructor are outside the valid domain. + """ DomainError doc""" - EOFError() + ENDIAN_BOM + +The 32-bit byte-order-mark indicates the native byte order of the +host machine. Little-endian machines will contain the value +0x04030201. Big-endian machines will contain the value 0x01020304. -No more data was available to read from a file or stream. """ -EOFError +ENDIAN_BOM doc""" - ErrorException(msg) + ENV + +Reference to the singleton "EnvHash", providing a dictionary +interface to system environment variables. -Generic error type. The error message, in the *.msg* field, may -provide more specific details. """ -ErrorException +ENV doc""" - InexactError() + EOFError() + +No more data was available to read from a file or stream. -Type conversion cannot be done exactly. """ -InexactError +EOFError doc""" - InterruptException() + EnvHash() -> EnvHash + +A singleton of this type provides a hash table interface to +environment variables. -The process was stopped by a terminal interrupt (CTRL+C). """ -InterruptException +EnvHash doc""" - KeyError(key) + ErrorException(msg) + +Generic error type. The error message, in the *.msg* field, may +provide more specific details. -An indexing operation into an "Associative" ("Dict") or "Set" -like object tried to access or delete a non-existent element. """ -KeyError +ErrorException doc""" - LoadError(file::AbstractString, line::Int, error) + Float32(x[, mode::RoundingMode]) -An error occurred while *including*, *requiring*, or *using* a -file. The error specifics should be available in the *.error* -field. -""" -LoadError +Create a Float32 from "x". If "x" is not exactly representable +then "mode" determines how "x" is rounded. -doc""" - MethodError(f, args) + julia> Float32(1/3, RoundDown) + 0.3333333f0 -A method with the required type signature does not exist in the -given generic function. -""" -MethodError + julia> Float32(1/3, RoundUp) + 0.33333334f0 -doc""" - NullException() +See "get_rounding" for available rounding modes. -An attempted access to a "Nullable" with no defined value. """ -NullException +Float32 doc""" - OutOfMemoryError() + Float64(x[, mode::RoundingMode]) -An operation allocated too much memory for either the system or the -garbage collector to handle properly. -""" -OutOfMemoryError +Create a Float64 from "x". If "x" is not exactly representable +then "mode" determines how "x" is rounded. -doc""" - ReadOnlyMemoryError() + julia> Float64(pi, RoundDown) + 3.141592653589793 -An operation tried to write to memory that is read-only. -""" -ReadOnlyMemoryError + julia> Float64(pi, RoundUp) + 3.1415926535897936 -doc""" - OverflowError() +See "get_rounding" for available rounding modes. -The result of an expression is too large for the specified type and -will cause a wraparound. """ -OverflowError +Float64 doc""" - ParseError(msg) + IOBuffer() -> IOBuffer -The expression passed to the *parse* function could not be -interpreted as a valid Julia expression. -""" -ParseError +Create an in-memory I/O stream. -doc""" - ProcessExitedException() + IOBuffer(size::Int) -After a client Julia process has exited, further attempts to -reference the dead child will throw this exception. -""" -ProcessExitedException +Create a fixed size IOBuffer. The buffer will not grow dynamically. -doc""" - StackOverflowError() + IOBuffer(string) -The function call grew beyond the size of the call stack. This -usually happens when a call recurses infinitely. -""" -StackOverflowError +Create a read-only IOBuffer on the data underlying the given string -doc""" - SystemError(prefix::AbstractString[, errnum::Int32]) + IOBuffer([data][, readable, writable[, maxsize]]) + +Create an IOBuffer, which may optionally operate on a pre-existing +array. If the readable/writable arguments are given, they restrict +whether or not the buffer may be read from or written to +respectively. By default the buffer is readable but not writable. +The last argument optionally specifies a size beyond which the +buffer may not be grown. -A system call failed with an error code (in the "errno" global -variable). """ -SystemError +IOBuffer doc""" - TypeError(func::Symbol, context::AbstractString, expected::Type, got) + IPv4(host::Integer) -> IPv4 + +Returns IPv4 object from ip address formatted as Integer -A type assertion failure, or calling an intrinsic function with an -incorrect argument type. """ -TypeError +IPv4 doc""" - UndefRefError() + IPv6(host::Integer) -> IPv6 + +Returns IPv6 object from ip address formatted as Integer -The item or field is not defined for the given object. """ -UndefRefError +IPv6 doc""" - UndefVarError(var::Symbol) + InexactError() + +Type conversion cannot be done exactly. -A symbol in the current scope is not defined. """ -UndefVarError +InexactError doc""" - Timer(callback::Function, delay, repeat=0) + Inf + +Positive infinity of type Float64 -Create a timer to call the given callback function. The callback is -passed one argument, the timer object itself. The callback will be -invoked after the specified initial delay, and then repeating with -the given "repeat" interval. If "repeat" is "0", the timer is -only triggered once. Times are in seconds. A timer is stopped and -has its resources freed by calling "close" on it. """ -Timer +Inf doc""" - Timer(delay, repeat=0) + Inf16 + +Positive infinity of type Float16 -Create a timer that wakes up tasks waiting for it (by calling -"wait" on the timer object) at a specified interval. """ -Timer +Inf16 doc""" - module_name(m::Module) -> Symbol + Inf32 + +Positive infinity of type Float32 -Get the name of a module as a symbol. """ -module_name +Inf32 doc""" - module_parent(m::Module) -> Module + IntSet([itr]) + +Construct a sorted set of the integers generated by the given +iterable object, or an empty set. Implemented as a bit string, and +therefore designed for dense integer sets. Only non-negative +integers can be stored. If the set will be sparse (for example +holding a single very large integer), use "Set" instead. -Get a module's enclosing module. "Main" is its own parent. """ -module_parent +IntSet doc""" - current_module() -> Module + InterruptException() + +The process was stopped by a terminal interrupt (CTRL+C). -Get the *dynamically* current module, which is the module code is -currently being read from. In general, this is not the same as the -module containing the call to this function. """ -current_module +InterruptException doc""" - fullname(m::Module) + KeyError(key) + +An indexing operation into an "Associative" ("Dict") or "Set" +like object tried to access or delete a non-existent element. -Get the fully-qualified name of a module as a tuple of symbols. For -example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and -"fullname(Main)" gives "()". """ -fullname +KeyError doc""" - names(x::Module[, all=false[, imported=false]]) + LOAD_PATH + +An array of paths (as strings) where the "require" function looks +for code. -Get an array of the names exported by a module, with optionally -more module globals according to the additional parameters. """ -names +LOAD_PATH doc""" - nfields(x::DataType) -> Int + MS_ASYNC + +Enum constant for "msync()". See your platform man page for +details. (not available on Windows). -Get the number of fields of a data type. """ -nfields +Libc.MS_ASYNC doc""" - fieldnames(x::DataType) + MS_INVALIDATE + +Enum constant for "msync()". See your platform man page for +details. (not available on Windows). -Get an array of the fields of a data type. """ -fieldnames +Libc.MS_INVALIDATE doc""" - isconst([m::Module], s::Symbol) -> Bool + MS_SYNC + +Enum constant for "msync()". See your platform man page for +details. (not available on Windows). -Determine whether a global is declared "const" in a given module. -The default module argument is "current_module()". """ -isconst +Libc.MS_SYNC doc""" - isgeneric(f::Function) -> Bool + TmStruct([seconds]) + +Convert a number of seconds since the epoch to broken-down format, +with fields "sec", "min", "hour", "mday", "month", +"year", "wday", "yday", and "isdst". -Determine whether a function is generic. """ -isgeneric +Libc.TmStruct doc""" - function_name(f::Function) -> Symbol + calloc(num::Integer, size::Integer) -> Ptr{Void} + +Call "calloc" from the C standard library. -Get the name of a generic function as a symbol, or ":anonymous". """ -function_name +Libc.calloc doc""" - function_module(f::Function, types) -> Module + errno([code]) + +Get the value of the C library's "errno". If an argument is +specified, it is used to set the value of "errno". + +The value of "errno" is only valid immediately after a "ccall" +to a C library routine that sets it. Specifically, you cannot call +"errno" at the next prompt in a REPL, because lots of code is +executed between prompts. -Determine the module containing a given definition of a generic -function. """ -function_module +Libc.errno doc""" - functionloc(f::Function, types) + flush_cstdio() + +Flushes the C "stdout" and "stderr" streams (which may have +been written to by external C code). -Returns a tuple "(filename,line)" giving the location of a method -definition. """ -functionloc +Libc.flush_cstdio doc""" - functionloc(m::Method) + free(addr::Ptr) + +Call "free" from the C standard library. Only use this on memory +obtained from "malloc", not on pointers retrieved from other C +libraries. "Ptr" objects obtained from C libraries should be +freed by the free functions defined in that library, to avoid +assertion failures if multiple "libc" libraries exist on the +system. -Returns a tuple "(filename,line)" giving the location of a method -definition. """ -functionloc +Libc.free doc""" - gc() + malloc(size::Integer) -> Ptr{Void} + +Call "malloc" from the C standard library. -Perform garbage collection. This should not generally be used. """ -gc +Libc.malloc doc""" - gc_enable(on::Bool) + mmap(len, prot, flags, fd, offset) + +Low-level interface to the "mmap" system call. See the man page. -Control whether garbage collection is enabled using a boolean -argument (true for enabled, false for disabled). Returns previous -GC state. Disabling garbage collection should be used only with -extreme caution, as it can cause memory use to grow without bound. """ -gc_enable +Libc.mmap doc""" - macroexpand(x) + msync(ptr, len[, flags]) -Takes the expression x and returns an equivalent expression with -all macros removed (expanded). -""" -macroexpand +Forces synchronization of the "mmap()"ped memory region from +"ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a +combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See +your platform man page for specifics. The flags argument is not +valid on Windows. -doc""" - expand(x) +You may not need to call "msync", because synchronization is +performed at intervals automatically by the operating system. +However, you can call this directly if, for example, you are +concerned about losing the result of a long-running calculation. -Takes the expression x and returns an equivalent expression in -lowered form """ -expand +Libc.msync doc""" - code_lowered(f, types) + munmap(pointer, len) + +Low-level interface for unmapping memory (see the man page). With +"mmap_array()" you do not need to call this directly; the memory +is unmapped for you when the array goes out of scope. -Returns an array of lowered ASTs for the methods matching the given -generic function and type signature. """ -code_lowered +Libc.munmap doc""" - @code_lowered() + realloc(addr::Ptr, size::Integer) -> Ptr{Void} -Evaluates the arguments to the function call, determines their -types, and calls "code_lowered()" on the resulting expression -""" -@code_lowered +Call "realloc" from the C standard library. -doc""" - code_typed(f, types; optimize=true) +See warning in the documentation for "free" regarding only using +this on memory originally obtained from "malloc". -Returns an array of lowered and type-inferred ASTs for the methods -matching the given generic function and type signature. The keyword -argument "optimize" controls whether additional optimizations, -such as inlining, are also applied. """ -code_typed +Libc.realloc doc""" - @code_typed() + strerror(n) + +Convert a system call error code to a descriptive string -Evaluates the arguments to the function call, determines their -types, and calls "code_typed()" on the resulting expression """ -@code_typed +Libc.strerror doc""" - code_warntype(f, types) + strftime([format], time) + +Convert time, given as a number of seconds since the epoch or a +"TmStruct", to a formatted string using the given format. +Supported formats are the same as those in the standard C library. -Displays lowered and type-inferred ASTs for the methods matching -the given generic function and type signature. The ASTs are -annotated in such a way as to cause "non-leaf" types to be -emphasized (if color is available, displayed in red). This serves -as a warning of potential type instability. Not all non-leaf types -are particularly problematic for performance, so the results need -to be used judiciously. See *@code_warntype* for more information. """ -code_warntype +Libc.strftime doc""" - @code_warntype() + strptime([format], timestr) + +Parse a formatted time string into a "TmStruct" giving the +seconds, minute, hour, date, etc. Supported formats are the same as +those in the standard C library. On some platforms, timezones will +not be parsed correctly. If the result of this function will be +passed to "time" to convert it to seconds since the epoch, the +"isdst" field should be filled in manually. Setting it to "-1" +will tell the C library to use the current system settings to +determine the timezone. -Evaluates the arguments to the function call, determines their -types, and calls "code_warntype()" on the resulting expression """ -@code_warntype +Libc.strptime doc""" - code_llvm(f, types) + time(t::TmStruct) -Prints the LLVM bitcodes generated for running the method matching -the given generic function and type signature to "STDOUT". +Converts a "TmStruct" struct to a number of seconds since the +epoch. -All metadata and dbg.* calls are removed from the printed bitcode. -Use code_llvm_raw for the full IR. """ -code_llvm +Libc.time doc""" - @code_llvm() + DL_LOAD_PATH + +When calling "dlopen", the paths in this list will be searched +first, in order, before searching the system locations for a valid +library handle. -Evaluates the arguments to the function call, determines their -types, and calls "code_llvm()" on the resulting expression """ -@code_llvm +Libdl.DL_LOAD_PATH doc""" - code_native(f, types) + RTLD_DEEPBIND + +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -Prints the native assembly instructions generated for running the -method matching the given generic function and type signature to -STDOUT. """ -code_native +Libdl.RTLD_DEEPBIND doc""" - @code_native() + RTLD_FIRST + +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -Evaluates the arguments to the function call, determines their -types, and calls "code_native()" on the resulting expression """ -@code_native +Libdl.RTLD_FIRST doc""" - precompile(f, args::Tuple{Vararg{Any}}) + RTLD_GLOBAL + +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -Compile the given function "f" for the argument tuple (of types) -"args", but do not execute it. """ -precompile +Libdl.RTLD_GLOBAL doc""" - ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - -Call function in C-exported shared library, specified by -"(function name, library)" tuple, where each component is an -AbstractString or :Symbol. + RTLD_LAZY -Note that the argument type tuple must be a literal tuple, and not -a tuple-valued variable or expression. Alternatively, ccall may -also be used to call a function pointer, such as one returned by -dlsym. +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -Each "ArgumentValue" to the "ccall" will be converted to the -corresponding "ArgumentType", by automatic insertion of calls to -"unsafe_convert(ArgumentType, cconvert(ArgumentType, -ArgumentValue))". (see also the documentation for each of these -functions for further details). In most cases, this simply results -in a call to "convert(ArgumentType, ArgumentValue)" """ -Base.ccall +Libdl.RTLD_LAZY doc""" - cglobal((symbol, library)[, type=Void]) + RTLD_LOCAL + +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -Obtain a pointer to a global variable in a C-exported shared -library, specified exactly as in "ccall". Returns a -"Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is -supplied. The values can be read or written by "unsafe_load" or -"unsafe_store!", respectively. """ -cglobal +Libdl.RTLD_LOCAL doc""" - cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + RTLD_NODELETE -Generate C-callable function pointer from Julia function. Type -annotation of the return value in the callback function is a must -for situations where Julia cannot infer the return type -automatically. +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -For example: +""" +Libdl.RTLD_NODELETE - function foo() - # body +doc""" + RTLD_NOLOAD - retval::Float64 - end +Enum constant for "dlopen()". See your platform man page for +details, if applicable. - bar = cfunction(foo, Float64, ()) """ -cfunction +Libdl.RTLD_NOLOAD doc""" - unsafe_convert(T, x) + RTLD_NOW -Convert "x" to a value of type "T" +Enum constant for "dlopen()". See your platform man page for +details, if applicable. -In cases where "convert" would need to take a Julia object and -turn it into a "Ptr", this function should be used to define and -perform that conversion. +""" +Libdl.RTLD_NOW -Be careful to ensure that a julia reference to "x" exists as long -as the result of this function will be used. Accordingly, the -argument "x" to this function should never be an expression, only -a variable name or field reference. For example, "x=a.b.c" is -acceptable, but "x=[a,b,c]" is not. +doc""" + dlclose(handle) + +Close shared library referenced by handle. -The "unsafe" prefix on this function indicates that using the -result of this function after the "x" argument to this function -is no longer accessible to the program may cause undefined -behavior, including program corruption or segfaults, at any later -time. """ -unsafe_convert +Libdl.dlclose doc""" - cconvert(T, x) + dlopen(libfile::AbstractString[, flags::Integer]) -Convert "x" to a value of type "T", typically by calling -"convert(T,x)" +Load a shared library, returning an opaque handle. -In cases where "x" cannot be safely converted to "T", unlike -"convert", "cconvert" may return an object of a type different -from "T", which however is suitable for "unsafe_convert" to -handle. +The optional flags argument is a bitwise-or of zero or more of +"RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", +"RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and +"RTLD_FIRST". These are converted to the corresponding flags of +the POSIX (and/or GNU libc and/or MacOS) dlopen command, if +possible, or are ignored if the specified functionality is not +available on the current platform. The default is +"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of +these flags, on POSIX platforms, is to specify +"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's +symbols to be available for usage in other shared libraries, in +situations where there are dependencies between shared libraries. -Neither "convert" nor "cconvert" should take a Julia object and -turn it into a "Ptr". """ -cconvert +Libdl.dlopen doc""" - unsafe_load(p::Ptr{T}, i::Integer) + dlopen_e(libfile::AbstractString[, flags::Integer]) -Load a value of type "T" from the address of the ith element -(1-indexed) starting at "p". This is equivalent to the C -expression "p[i-1]". +Similar to "dlopen()", except returns a "NULL" pointer instead +of raising errors. -The "unsafe" prefix on this function indicates that no validation -is performed on the pointer "p" to ensure that it is valid. -Incorrect usage may segfault your program or return garbage -answers, in the same manner as C. """ -unsafe_load +Libdl.dlopen_e doc""" - unsafe_store!(p::Ptr{T}, x, i::Integer) + dlsym(handle, sym) -Store a value of type "T" to the address of the ith element -(1-indexed) starting at "p". This is equivalent to the C -expression "p[i-1] = x". +Look up a symbol from a shared library handle, return callable +function pointer on success. -The "unsafe" prefix on this function indicates that no validation -is performed on the pointer "p" to ensure that it is valid. -Incorrect usage may corrupt or segfault your program, in the same -manner as C. """ -unsafe_store! +Libdl.dlsym doc""" - unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + dlsym_e(handle, sym) -Copy "N" elements from a source pointer to a destination, with no -checking. The size of an element is determined by the type of the -pointers. +Look up a symbol from a shared library handle, silently return NULL +pointer on lookup failure. -The "unsafe" prefix on this function indicates that no validation -is performed on the pointers "dest" and "src" to ensure that -they are valid. Incorrect usage may corrupt or segfault your -program, in the same manner as C. """ -unsafe_copy! +Libdl.dlsym_e doc""" - unsafe_copy!(dest::Array, do, src::Array, so, N) + find_library(names, locations) -Copy "N" elements from a source array to a destination, starting -at offset "so" in the source and "do" in the destination -(1-indexed). +Searches for the first library in "names" in the paths in the +"locations" list, "DL_LOAD_PATH", or system library paths (in +that order) which can successfully be dlopen'd. On success, the +return value will be one of the names (potentially prefixed by one +of the paths in locations). This string can be assigned to a +"global const" and used as the library name in future +"ccall"'s. On failure, it returns the empty string. -The "unsafe" prefix on this function indicates that no validation -is performed to ensure that N is inbounds on either array. -Incorrect usage may corrupt or segfault your program, in the same -manner as C. """ -unsafe_copy! +Libdl.find_library doc""" - copy!(dest, src) + LoadError(file::AbstractString, line::Int, error) + +An error occurred while *including*, *requiring*, or *using* a +file. The error specifics should be available in the *.error* +field. -Copy all elements from collection "src" to array "dest". -Returns "dest". """ -copy! +LoadError doc""" - copy!(dest, do, src, so, N) + MersenneTwister([seed]) + +Create a "MersenneTwister" RNG object. Different RNG objects can +have their own seeds, which may be useful for generating different +streams of random numbers. -Copy "N" elements from collection "src" starting at offset -"so", to array "dest" starting at offset "do". Returns -"dest". """ -copy! +MersenneTwister doc""" - pointer(array[, index]) + MethodError(f, args) -Get the native address of an array or string element. Be careful to -ensure that a julia reference to "a" exists as long as this -pointer will be used. This function is "unsafe" like -"unsafe_convert". +A method with the required type signature does not exist in the +given generic function. -Calling "Ref(array[, index])" is generally preferable to this -function. """ -pointer +MethodError doc""" - pointer_to_array(pointer, dims[, take_ownership::Bool]) + NaN + +A not-a-number value of type Float64 -Wrap a native pointer as a Julia Array object. The pointer element -type determines the array element type. "own" optionally -specifies whether Julia should take ownership of the memory, -calling "free" on the pointer when the array is no longer -referenced. """ -pointer_to_array +NaN doc""" - pointer_from_objref(object_instance) + NaN16 + +A not-a-number value of type Float16 -Get the memory address of a Julia object as a "Ptr". The -existence of the resulting "Ptr" will not protect the object from -garbage collection, so you must ensure that the object remains -referenced for the whole time that the "Ptr" will be used. """ -pointer_from_objref +NaN16 doc""" - unsafe_pointer_to_objref(p::Ptr) + NaN32 + +A not-a-number value of type Float32 -Convert a "Ptr" to an object reference. Assumes the pointer -refers to a valid heap-allocated Julia object. If this is not the -case, undefined behavior results, hence this function is considered -"unsafe" and should be used with care. """ -unsafe_pointer_to_objref +NaN32 doc""" - disable_sigint(f::Function) + NullException() -Disable Ctrl-C handler during execution of a function, for calling -external code that is not interrupt safe. Intended to be called -using "do" block syntax as follows: +An attempted access to a "Nullable" with no defined value. - disable_sigint() do - # interrupt-unsafe code - ... - end """ -disable_sigint +NullException doc""" - reenable_sigint(f::Function) + Nullable(x) + +Wrap value "x" in an object of type "Nullable", which indicates +whether a value is present. "Nullable(x)" yields a non-empty +wrapper, and "Nullable{T}()" yields an empty instance of a +wrapper that might contain a value of type "T". -Re-enable Ctrl-C handler during execution of a function. -Temporarily reverses the effect of "disable_sigint". """ -reenable_sigint +Nullable doc""" - systemerror(sysfunc, iftrue) + OS_NAME + +A symbol representing the name of the operating system. Possible +values are ":Linux", ":Darwin" (OS X), or ":Windows". -Raises a "SystemError" for "errno" with the descriptive string -"sysfunc" if "bool" is true """ -systemerror +OS_NAME doc""" - Cchar + OutOfMemoryError() + +An operation allocated too much memory for either the system or the +garbage collector to handle properly. -Equivalent to the native "char" c-type """ -Cchar +OutOfMemoryError doc""" - Cuchar + OverflowError() + +The result of an expression is too large for the specified type and +will cause a wraparound. -Equivalent to the native "unsigned char" c-type (UInt8) """ -Cuchar +OverflowError doc""" - Cshort + ParseError(msg) + +The expression passed to the *parse* function could not be +interpreted as a valid Julia expression. -Equivalent to the native "signed short" c-type (Int16) """ -Cshort +ParseError doc""" - Cushort + PipeBuffer() -Equivalent to the native "unsigned short" c-type (UInt16) -""" -Cushort +An IOBuffer that allows reading and performs writes by appending. +Seeking and truncating are not supported. See IOBuffer for the +available constructors. -doc""" - Cint + PipeBuffer(data::Vector{UInt8}[, maxsize]) + +Create a PipeBuffer to operate on a data vector, optionally +specifying a size beyond which the underlying Array may not be +grown. -Equivalent to the native "signed int" c-type (Int32) """ -Cint +PipeBuffer doc""" - Cuint + ProcessExitedException() + +After a client Julia process has exited, further attempts to +reference the dead child will throw this exception. -Equivalent to the native "unsigned int" c-type (UInt32) """ -Cuint +ProcessExitedException doc""" - Clong + RandomDevice() + +Create a "RandomDevice" RNG object. Two such objects will always +generate different streams of random numbers. -Equivalent to the native "signed long" c-type """ -Clong +RandomDevice doc""" - Culong + ReadOnlyMemoryError() + +An operation tried to write to memory that is read-only. -Equivalent to the native "unsigned long" c-type """ -Culong +ReadOnlyMemoryError doc""" - Clonglong + ReentrantLock() + +Creates a reentrant lock. The same task can acquire the lock as +many times as required. Each lock must be matched with an unlock. -Equivalent to the native "signed long long" c-type (Int64) """ -Clonglong +ReentrantLock doc""" - Culonglong + RemoteRef() + +Make an uninitialized remote reference on the local machine. + + RemoteRef(n) + +Make an uninitialized remote reference on process "n". -Equivalent to the native "unsigned long long" c-type (UInt64) """ -Culonglong +RemoteRef doc""" - Cintmax_t + RoundDown + +"round()" using this rounding mode is an alias for "floor()". -Equivalent to the native "intmax_t" c-type (Int64) """ -Cintmax_t +RoundDown doc""" - Cuintmax_t + RoundNearest + +The default rounding mode. Rounds to the nearest integer, with ties +(fractional values of 0.5) being rounded to the nearest even +integer. -Equivalent to the native "uintmax_t" c-type (UInt64) """ -Cuintmax_t +RoundNearest doc""" - Csize_t + RoundNearestTiesAway + +Rounds to nearest integer, with ties rounded away from zero (C/C++ +"round()" behaviour). -Equivalent to the native "size_t" c-type (UInt) """ -Csize_t +RoundNearestTiesAway doc""" - Cssize_t + RoundNearestTiesUp + +Rounds to nearest integer, with ties rounded toward positive +infinity (Java/JavaScript "round()" behaviour). -Equivalent to the native "ssize_t" c-type """ -Cssize_t +RoundNearestTiesUp doc""" - Cptrdiff_t + RoundToZero + +"round()" using this rounding mode is an alias for "trunc()". -Equivalent to the native "ptrdiff_t" c-type (Int) """ -Cptrdiff_t +RoundToZero doc""" - Coff_t + RoundUp + +"round()" using this rounding mode is an alias for "ceil()". -Equivalent to the native "off_t" c-type """ -Coff_t +RoundUp doc""" - Cwchar_t + RoundingMode + +A type which controls rounding behavior. Currently supported +rounding modes are: + +* "RoundNearest" (default) + +* "RoundNearestTiesAway" + +* "RoundNearestTiesUp" + +* "RoundToZero" + +* "RoundUp" + +* "RoundDown" -Equivalent to the native "wchar_t" c-type (Int32) """ -Cwchar_t +RoundingMode doc""" - Cfloat + 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. -Equivalent to the native "float" c-type (Float32) """ -Cfloat +Set doc""" - Cdouble + SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) + +Construct a SharedArray of a bitstype "T" and size "dims" +across the processes specified by "pids" - all of which have to +be on the same host. + +If "pids" is left unspecified, the shared array will be mapped +across all processes on the current host, including the master. +But, "localindexes" and "indexpids" will only refer to worker +processes. This facilitates work distribution code to use workers +for actual computation with the master process acting as a driver. + +If an "init" function of the type "initfn(S::SharedArray)" is +specified, it is called on all the participating workers. -Equivalent to the native "double" c-type (Float64) """ -Cdouble +SharedArray doc""" - start(iter) -> state + StackOverflowError() + +The function call grew beyond the size of the call stack. This +usually happens when a call recurses infinitely. -Get initial iteration state for an iterable object """ -start +StackOverflowError doc""" - done(iter, state) -> Bool + SymTridiagonal(d, du) + +Construct a real symmetric tridiagonal matrix from the diagonal and +upper diagonal, respectively. The result is of type +"SymTridiagonal" and provides efficient specialized eigensolvers, +but may be converted into a regular matrix with "full()". -Test whether we are done iterating """ -done +SymTridiagonal doc""" - next(iter, state) -> item, state + Sys.set_process_title(title::AbstractString) + +Set the process title. No-op on some operating systems. (not +exported) + + Sys.get_process_title() + +Get the process title. On some systems, will always return empty +string. (not exported) -For a given iterable object and iteration state, return the current -item and the next iteration state """ -next +Sys doc""" - zip(iters...) + SystemError(prefix::AbstractString[, errnum::Int32]) -For a set of iterable objects, returns an iterable of tuples, where -the "i"th tuple contains the "i"th component of each input -iterable. +A system call failed with an error code (in the "errno" global +variable). -Note that "zip()" is its own inverse: -"collect(zip(zip(a...)...)) == collect(a)". """ -zip +SystemError doc""" - enumerate(iter) - -An iterator that yields "(i, x)" where "i" is an index starting -at 1, and "x" is the "i"th value from the given iterator. It's -useful when you need not only the values "x" over which you are -iterating, but also the index "i" of the iterations. + Task(func) - julia> a = ["a", "b", "c"]; +Create a "Task" (i.e. thread, or coroutine) to execute the given +function (which must be callable with no arguments). The task exits +when this function returns. - julia> for (index, value) in enumerate(a) - println("\$index \$value") - end - 1 a - 2 b - 3 c """ -enumerate +Task doc""" - rest(iter, state) + TextDisplay(stream) + +Returns a "TextDisplay <: Display", which can display any object +as the text/plain MIME type (only), writing the text representation +to the given I/O stream. (The text representation is the same as +the way an object is printed in the Julia REPL.) -An iterator that yields the same elements as "iter", but starting -at the given "state". """ -rest +TextDisplay doc""" - countfrom(start=1, step=1) + Timer(callback::Function, delay, repeat=0) + +Create a timer to call the given callback function. The callback is +passed one argument, the timer object itself. The callback will be +invoked after the specified initial delay, and then repeating with +the given "repeat" interval. If "repeat" is "0", the timer is +only triggered once. Times are in seconds. A timer is stopped and +has its resources freed by calling "close" on it. + + Timer(delay, repeat=0) + +Create a timer that wakes up tasks waiting for it (by calling +"wait" on the timer object) at a specified interval. -An iterator that counts forever, starting at "start" and -incrementing by "step". """ -countfrom +Timer doc""" - take(iter, n) + Tridiagonal(dl, d, du) + +Construct a tridiagonal matrix from the lower diagonal, diagonal, +and upper diagonal, respectively. The result is of type +"Tridiagonal" and provides efficient specialized linear solvers, +but may be converted into a regular matrix with "full()". -An iterator that generates at most the first "n" elements of -"iter". """ -take +Tridiagonal doc""" - drop(iter, n) + TypeError(func::Symbol, context::AbstractString, expected::Type, got) + +A type assertion failure, or calling an intrinsic function with an +incorrect argument type. -An iterator that generates all but the first "n" elements of -"iter". """ -drop +TypeError doc""" - cycle(iter) + UndefRefError() + +The item or field is not defined for the given object. -An iterator that cycles through "iter" forever. """ -cycle +UndefRefError doc""" - repeated(x[, n::Int]) + UndefVarError(var::Symbol) + +A symbol in the current scope is not defined. -An iterator that generates the value "x" forever. If "n" is -specified, generates "x" that many times (equivalent to -"take(repeated(x), n)"). """ -repeated +UndefVarError doc""" - isempty(collection) -> Bool - -Determine whether a collection is empty (has no elements). + VERSION - julia> isempty([]) - true +An object describing which version of Julia is in use. - julia> isempty([1 2 3]) - false """ -isempty +VERSION doc""" - empty!(collection) -> collection + WORD_SIZE + +Standard word size on the current machine, in bits. -Remove all elements from a "collection". """ -empty! +WORD_SIZE doc""" - length(collection) -> Integer + abs(x) + +Absolute value of "x" -For ordered, indexable collections, the maximum index "i" for -which "getindex(collection, i)" is valid. For unordered -collections, the number of elements. """ -length +abs doc""" - endof(collection) -> Integer + abs2(x) -Returns the last index of the collection. +Squared absolute value of "x" - julia> endof([1,2,4]) - 3 """ -endof +abs2 doc""" - in(item, collection) -> Bool -∈(item, collection) -> Bool -∋(collection, item) -> Bool -∉(item, collection) -> Bool -∌(collection, item) -> Bool + abspath(path::AbstractString) -> AbstractString + +Convert a path to an absolute path by adding the current directory +if necessary. -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)". """ -Base.in +abspath doc""" - eltype(type) + accept(server[, client]) + +Accepts a connection on the given server and returns a connection +to the client. An uninitialized client stream may be provided, in +which case it will be used instead of creating a new stream. -Determine the type of the elements generated by iterating a -collection of the given "type". For associative collection types, -this will be a "(key,value)" tuple type. 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. """ -eltype +accept doc""" - indexin(a, b) + acos(x) + +Compute the inverse cosine of "x", where the output is in radians -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". """ -indexin +acos doc""" - findin(a, b) + acosd(x) + +Compute the inverse cosine of "x", where the output is in degrees -Returns the indices of elements in collection "a" that appear in -collection "b" """ -findin +acosd doc""" - unique(itr[, dim]) + acosh(x) + +Compute the inverse hyperbolic cosine of "x" -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". """ -unique +acosh doc""" - 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)". + acot(x) -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. +Compute the inverse cotangent of "x", where the output is in +radians -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. """ -reduce +acot doc""" - reduce(op, itr) + acotd(x) + +Compute the inverse cotangent of "x", where the output is in +degrees -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". """ -reduce +acotd doc""" - foldl(op, v0, itr) + acoth(x) + +Compute the inverse hyperbolic cotangent of "x" -Like "reduce()", but with guaranteed left associativity. "v0" -will be used exactly once. """ -foldl +acoth doc""" - foldl(op, itr) + acsc(x) + +Compute the inverse cosecant of "x", where the output is in +radians -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)"). """ -foldl +acsc doc""" - foldr(op, v0, itr) + acscd(x) + +Compute the inverse cosecant of "x", where the output is in +degrees -Like "reduce()", but with guaranteed right associativity. "v0" -will be used exactly once. """ -foldr +acscd doc""" - foldr(op, itr) + acsch(x) + +Compute the inverse hyperbolic cosecant of "x" -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)"). """ -foldr +acsch doc""" - maximum(itr) + addprocs(n::Integer; exeflags=``) -> List of process identifiers -Returns the largest element in a collection. -""" -maximum +Launches workers using the in-built "LocalManager" which only +launches workers on the local host. This can be used to take +advantage of multiple cores. "addprocs(4)" will add 4 processes +on the local machine. -doc""" - maximum(A, dims) + addprocs() -> List of process identifiers -Compute the maximum value of an array over the given dimensions. -""" -maximum +Equivalent to "addprocs(CPU_CORES)" -doc""" - maximum!(r, A) + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers -Compute the maximum value of "A" over the singleton dimensions of -"r", and write results to "r". -""" -maximum! +Add processes on remote machines via SSH. Requires julia to be +installed in the same location on each node, or to be available via +a shared file system. -doc""" - minimum(itr) +"machines" is a vector of machine specifications. Worker are +started for each specification. -Returns the smallest element in a collection. -""" -minimum +A machine specification is either a string "machine_spec" or a +tuple - "(machine_spec, count)" -doc""" - minimum(A, dims) +"machine_spec" is a string of the form "[user@]host[:port] +[bind_addr[:port]]". "user" defaults to current user, "port" +to the standard ssh port. If "[bind_addr[:port]]" is specified, +other workers will connect to this worker at the specified +"bind_addr" and "port". -Compute the minimum value of an array over the given dimensions. -""" -minimum +"count" is the number of workers to be launched on the specified +host. If specified as ":auto" it will launch as many workers as +the number of cores on the specific host. -doc""" - minimum!(r, A) +Keyword arguments: -Compute the minimum value of "A" over the singleton dimensions of -"r", and write results to "r". -""" -minimum! +"tunnel" : if "true" then SSH tunneling will be used to connect +to the worker from the master process. -doc""" - extrema(itr) +"sshflags" : specifies additional ssh options, e.g. +"sshflags=`-i /home/foo/bar.pem`" . -Compute both the minimum and maximum element in a single pass, and -return them as a 2-tuple. -""" -extrema +"max_parallel" : specifies the maximum number of workers +connected to in parallel at a host. Defaults to 10. -doc""" - indmax(itr) -> Integer +"dir" : specifies the working directory on the workers. Defaults +to the host's current directory (as found by *pwd()*) -Returns the index of the maximum element in a collection. -""" -indmax +"exename" : name of the julia executable. Defaults to +"\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case +may be. -doc""" - indmin(itr) -> Integer +"exeflags" : additional flags passed to the worker processes. -Returns the index of the minimum element in a collection. -""" -indmin +Environment variables : -doc""" - findmax(itr) -> (x, index) +If the master process fails to establish a connection with a newly +launched worker within 60.0 seconds, the worker treats it a fatal +situation and terminates. This timeout can be controlled via +environment variable "JULIA_WORKER_TIMEOUT". The value of +"JULIA_WORKER_TIMEOUT" on the master process, specifies the +number of seconds a newly launched worker waits for connection +establishment. -Returns the maximum element and its index. -""" -findmax + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers -doc""" - findmax(A, dims) -> (maxval, index) +Launches worker processes via the specified cluster manager. -For an array input, returns the value and index of the maximum over -the given dimensions. -""" -findmax +For example Beowulf clusters are supported via a custom cluster +manager implemented in package "ClusterManagers". -doc""" - findmin(itr) -> (x, index) +The number of seconds a newly launched worker waits for connection +establishment from the master can be specified via variable +"JULIA_WORKER_TIMEOUT" in the worker process's environment. +Relevant only when using TCP/IP as transport. -Returns the minimum element and its index. """ -findmin +addprocs doc""" - findmin(A, dims) -> (minval, index) + airy(k, x) + +kth derivative of the Airy function \operatorname{Ai}(x). -For an array input, returns the value and index of the minimum over -the given dimensions. """ -findmin +airy doc""" - maxabs(itr) + airyai(x) -Compute the maximum absolute value of a collection of values. -""" -maxabs - -doc""" - maxabs(A, dims) +Airy function \operatorname{Ai}(x). -Compute the maximum absolute values over given dimensions. """ -maxabs +airyai doc""" - maxabs!(r, A) - -Compute the maximum absolute values over the singleton dimensions -of "r", and write values to "r". -""" -maxabs! + airyaiprime(x) -doc""" - minabs(itr) +Airy function derivative \operatorname{Ai}'(x). -Compute the minimum absolute value of a collection of values. """ -minabs +airyaiprime doc""" - minabs(A, dims) - -Compute the minimum absolute values over given dimensions. -""" -minabs + airybi(x) -doc""" - minabs!(r, A) +Airy function \operatorname{Bi}(x). -Compute the minimum absolute values over the singleton dimensions -of "r", and write values to "r". """ -minabs! +airybi doc""" - sum(itr) - -Returns the sum of all elements in a collection. -""" -sum + airybiprime(x) -doc""" - sum(A, dims) +Airy function derivative \operatorname{Bi}'(x). -Sum elements of an array over the given dimensions. """ -sum +airybiprime doc""" - sum!(r, A) - -Sum elements of "A" over the singleton dimensions of "r", and -write results to "r". -""" -sum! + airyprime(x) -doc""" - sum(f, itr) +Airy function derivative \operatorname{Ai}'(x). -Sum the results of calling function "f" on each element of -"itr". """ -sum +airyprime doc""" - sumabs(itr) - -Sum absolute values of all elements in a collection. This is -equivalent to *sum(abs(itr))* but faster. -""" -sumabs + airyx(k, x) -doc""" - sumabs(A, dims) +scaled kth derivative of the Airy function, return +\operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || +k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} +\left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || +k == 3". -Sum absolute values of elements of an array over the given -dimensions. """ -sumabs +airyx doc""" - sumabs!(r, A) + all(itr) -> Bool -Sum absolute values of elements of "A" over the singleton -dimensions of "r", and write results to "r". -""" -sumabs! +Test whether all elements of a boolean collection are true. -doc""" - sumabs2(itr) + all(A, dims) -Sum squared absolute values of all elements in a collection. This -is equivalent to *sum(abs2(itr))* but faster. -""" -sumabs2 +Test whether all values along the given dimensions of an array are +true. -doc""" - sumabs2(A, dims) + all(p, itr) -> Bool -Sum squared absolute values of elements of an array over the given -dimensions. -""" -sumabs2 +Determine whether predicate "p" returns true for all elements of +"itr". -doc""" - sumabs2!(r, A) + julia> all(i->(4<=i<=6), [4,5,6]) + true -Sum squared absolute values of elements of "A" over the singleton -dimensions of "r", and write results to "r". """ -sumabs2! +all doc""" - prod(itr) - -Returns the product of all elements of a collection. -""" -prod + all!(r, A) -doc""" - prod(A, dims) +Test whether all values in "A" along the singleton dimensions of +"r" are true, and write results to "r". -Multiply elements of an array over the given dimensions. """ -prod +all! doc""" - prod!(r, A) + angle(z) + +Compute the phase angle in radians of a complex number "z" -Multiply elements of "A" over the singleton dimensions of "r", -and write results to "r". """ -prod! +angle doc""" any(itr) -> Bool Test whether any elements of a boolean collection are true. -""" -any -doc""" any(A, dims) Test whether any values along the given dimensions of an array are true. + + any(p, itr) -> Bool + +Determine whether predicate "p" returns true for any elements of +"itr". + """ any @@ -3995,1780 +4112,1900 @@ doc""" Test whether any values in "A" along the singleton dimensions of "r" are true, and write results to "r". + """ any! doc""" - all(itr) -> Bool + append!(collection, collection2) -> collection. -Test whether all elements of a boolean collection are true. -""" -all +Add the elements of "collection2" to the end of "collection". -doc""" - all(A, dims) + julia> append!([1],[2,3]) + 3-element Array{Int64,1}: + 1 + 2 + 3 -Test whether all values along the given dimensions of an array are -true. -""" -all + julia> append!([1, 2, 3], [4, 5, 6]) + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 -doc""" - all!(r, A) +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)". -Test whether all values in "A" along the singleton dimensions of -"r" are true, and write results to "r". """ -all! +append! doc""" - count(p, itr) -> Integer + applicable(f, args...) -> Bool -Count the number of elements in "itr" for which predicate "p" -returns true. -""" -count +Determine whether the given generic function has a method +applicable to the given arguments. -doc""" - any(p, itr) -> Bool + julia> function f(x, y) + x + y + end; + + julia> applicable(f, 1) + false + + julia> applicable(f, 1, 2) + true -Determine whether predicate "p" returns true for any elements of -"itr". """ -any +applicable doc""" - all(p, itr) -> Bool + ascii(::Array{UInt8, 1}) -Determine whether predicate "p" returns true for all elements of -"itr". +Create an ASCII string from a byte array. - julia> all(i->(4<=i<=6), [4,5,6]) - true -""" -all + ascii(s) -doc""" - map(f, c...) -> collection +Convert a string to a contiguous ASCII string (all characters must +be valid ASCII characters). -Transform collection "c" by applying "f" to each element. For -multiple collection arguments, apply "f" elementwise. + ascii(::Ptr{UInt8}[, length]) - julia> map((x) -> x * 2, [1, 2, 3]) - 3-element Array{Int64,1}: - 2 - 4 - 6 +Create an ASCII string from the address of a C (0-terminated) +string encoded in ASCII. A copy is made; the ptr can be safely +freed. If "length" is specified, the string does not have to be +0-terminated. - julia> map(+, [1, 2, 3], [10, 20, 30]) - 3-element Array{Int64,1}: - 11 - 22 - 33 """ -map +ascii doc""" - map!(function, collection) + asec(x) + +Compute the inverse secant of "x", where the output is in radians -In-place version of "map()". """ -map! +asec doc""" - map!(function, destination, collection...) + asecd(x) + +Compute the inverse secant of "x", where the output is in degrees -Like "map()", but stores the result in "destination" rather -than a new collection. "destination" must be at least as large as -the first collection. """ -map! +asecd doc""" - mapreduce(f, op, v0, itr) + asech(x) -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 +Compute the inverse hyperbolic secant of "x" -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. """ -mapreduce +asech doc""" - mapreduce(f, op, itr) + asin(x) + +Compute the inverse sine of "x", where the output is in radians -Like "mapreduce(f, op, v0, itr)". In general, this cannot be used -with empty collections (see "reduce(op, itr)"). """ -mapreduce +asin doc""" - mapfoldl(f, op, v0, itr) + asind(x) + +Compute the inverse sine of "x", where the output is in degrees -Like "mapreduce()", but with guaranteed left associativity. -"v0" will be used exactly once. """ -mapfoldl +asind doc""" - mapfoldl(f, op, itr) + asinh(x) + +Compute the inverse hyperbolic sine of "x" -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)"). """ -mapfoldl +asinh doc""" - mapfoldr(f, op, v0, itr) + assert(cond) + +Throw an "AssertionError" if "cond" is false. Also available as +the macro "@assert expr". -Like "mapreduce()", but with guaranteed right associativity. -"v0" will be used exactly once. """ -mapfoldr +assert doc""" - mapfoldr(f, op, itr) + atan(x) + +Compute the inverse tangent of "x", where the output is in +radians -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)"). """ -mapfoldr +atan doc""" - first(coll) + atan2(y, x) + +Compute the inverse tangent of "y/x", using the signs of both +"x" and "y" to determine the quadrant of the return value. -Get the first element of an iterable collection. Returns the start -point of a "Range" even if it is empty. """ -first +atan2 doc""" - last(coll) + atand(x) + +Compute the inverse tangent of "x", where the output is in +degrees -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. """ -last +atand doc""" - step(r) + atanh(x) + +Compute the inverse hyperbolic tangent of "x" -Get the step size of a "Range" object. """ -step +atanh doc""" - collect(collection) + atexit(f) + +Register a zero-argument function to be called at exit. -Return an array of all items in a collection. For associative -collections, returns (key, value) tuples. """ -collect +atexit doc""" - collect(element_type, collection) + atreplinit(f) + +Register a one-argument function to be called before the REPL +interface is initialized in interactive sessions; this is useful to +customize the interface. The argument of "f" is the REPL object. +This function should be called from within the ".juliarc.jl" +initialization file. -Return an array of type "Array{element_type,1}" of all items in a -collection. """ -collect +atreplinit doc""" - issubset(a, b) -⊆(A, S) -> Bool -⊈(A, S) -> Bool -⊊(A, S) -> Bool + backtrace() + +Get a backtrace object for the current program point. -Determine whether every element of "a" is also in "b", using -"in()". """ -issubset +backtrace doc""" - filter(function, collection) + base(base, n[, pad]) + +Convert an integer to a string in the given base, optionally +specifying a number of digits to pad to. The base can be specified +as either an integer, or as a "UInt8" array of character values +to use as digit symbols. -Return a copy of "collection", removing elements for which -"function" is false. For associative collections, the function is -passed two arguments (key and value). """ -filter +base doc""" - filter!(function, collection) + base64decode(string) + +Decodes the base64-encoded "string" and returns a +"Vector{UInt8}" of the decoded bytes. -Update "collection", removing elements for which "function" is -false. For associative collections, the function is passed two -arguments (key and value). """ -filter! +base64decode doc""" - getindex(collection, key...) + base64encode(writefunc, args...) +base64encode(args...) + +Given a "write"-like function "writefunc", which takes an I/O +stream as its first argument, "base64(writefunc, args...)" calls +"writefunc" to write "args..." to a base64-encoded string, and +returns the string. "base64(args...)" is equivalent to +"base64(write, args...)": it converts its arguments into bytes +using the standard "write" functions and returns the +base64-encoded string. -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, ...)". """ -getindex +base64encode doc""" - setindex!(collection, value, key...) + basename(path::AbstractString) -> AbstractString + +Get the file name part of a path. -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, ...)". """ -setindex! +basename doc""" - Dict([itr]) + besselh(nu, k, x) -"Dict{K,V}()" constructs a hash table with keys of type "K" and -values of type "V". +Bessel function of the third kind of order "nu" (Hankel +function). "k" is either 1 or 2, selecting "hankelh1" or +"hankelh2", respectively. -Given a single iterable argument, constructs a "Dict" whose key- -value pairs are taken from 2-tuples "(key,value)" generated by -the argument. +""" +besselh - julia> Dict([("A", 1), ("B", 2)]) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 +doc""" + besseli(nu, x) -Alternatively, a sequence of pair arguments may be passed. +Modified Bessel function of the first kind of order "nu", +I_\nu(x). - julia> Dict("A"=>1, "B"=>2) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 """ -Dict +besseli doc""" - haskey(collection, key) -> Bool + besselix(nu, x) + +Scaled modified Bessel function of the first kind of order "nu", +I_\nu(x) e^{- | \operatorname{Re}(x) |}. -Determine whether a collection has a mapping for a given key. """ -haskey +besselix doc""" - get(collection, key, default) + besselj(nu, x) + +Bessel function of the first kind of order "nu", J_\nu(x). -Return the value stored for the given key, or the given default -value if no mapping for the key is present. """ -get +besselj doc""" - 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. + besselj0(x) -This is intended to be called using "do" block syntax: +Bessel function of the first kind of order 0, J_0(x). - get(dict, key) do - # default value calculated here - time() - end """ -get +besselj0 doc""" - get!(collection, key, default) + besselj1(x) + +Bessel function of the first kind of order 1, J_1(x). -Return the value stored for the given key, or if no mapping for the -key is present, store "key => default", and return "default". """ -get! +besselj1 doc""" - 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()". + besseljx(nu, x) -This is intended to be called using "do" block syntax: +Scaled Bessel function of the first kind of order "nu", J_\nu(x) +e^{- | \operatorname{Im}(x) |}. - get!(dict, key) do - # default value calculated here - time() - end """ -get! +besseljx doc""" - getkey(collection, key, default) + besselk(nu, x) + +Modified Bessel function of the second kind of order "nu", +K_\nu(x). -Return the key matching argument "key" if one exists in -"collection", otherwise return "default". """ -getkey +besselk doc""" - delete!(collection, key) + besselkx(nu, x) + +Scaled modified Bessel function of the second kind of order "nu", +K_\nu(x) e^x. -Delete the mapping for the given key in a collection, and return -the collection. """ -delete! +besselkx doc""" - pop!(collection, key[, default]) + bessely(nu, x) + +Bessel function of the second kind of order "nu", Y_\nu(x). -Delete and return the mapping for "key" if it exists in -"collection", otherwise return "default", or throw an error if -default is not specified. """ -pop! +bessely doc""" - keys(collection) + bessely0(x) + +Bessel function of the second kind of order 0, Y_0(x). -Return an iterator over all keys in a collection. -"collect(keys(d))" returns an array of keys. """ -keys +bessely0 doc""" - values(collection) + bessely1(x) + +Bessel function of the second kind of order 1, Y_1(x). -Return an iterator over all values in a collection. -"collect(values(d))" returns an array of values. """ -values +bessely1 doc""" - merge(collection, others...) + besselyx(nu, x) -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. +Scaled Bessel function of the second kind of order "nu", +Y_\nu(x) e^{- | \operatorname{Im}(x) |}. - julia> a = Dict("foo" => 0.0, "bar" => 42.0) - Dict{ASCIIString,Float64} with 2 entries: - "bar" => 42.0 - "foo" => 0.0 +""" +besselyx - julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) - Dict{UTF8String,Int64} with 2 entries: - "bar" => 4711 - "baz" => 17 +doc""" + beta(x, y) - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 +Euler integral of the first kind \operatorname{B}(x,y) = +\Gamma(x)\Gamma(y)/\Gamma(x+y). - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 42.0 - "baz" => 17.0 - "foo" => 0.0 """ -merge +beta doc""" - merge!(collection, others...) + bfft(A[, dims]) + +Similar to "ifft()", but computes an unnormalized inverse +(backward) transform, which must be divided by the product of the +sizes of the transformed dimensions in order to obtain the inverse. +(This is slightly more efficient than "ifft()" because it omits a +scaling step, which in some applications can be combined with other +computational steps elsewhere.) + + \operatorname{BDFT}(A)[k] = \operatorname{length}(A) + \operatorname{IDFT}(A)[k] -Update collection with pairs from the other collections """ -merge! +bfft doc""" - sizehint!(s, n) + bfft!(A[, dims]) + +Same as "bfft()", but operates in-place on "A". -Suggest that collection "s" reserve capacity for at least "n" -elements. This can improve performance. """ -sizehint! +bfft! doc""" - Set([itr]) + big(x) + +Convert a number to a maximum precision representation (typically +"BigInt" or "BigFloat"). See "BigFloat" for information about +some pitfalls with floating-point numbers. -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. """ -Set +big doc""" - IntSet([itr]) + bin(n[, pad]) + +Convert an integer to a binary string, optionally specifying a +number of digits to pad to. -Construct a sorted set of the integers generated by the given -iterable object, or an empty set. Implemented as a bit string, and -therefore designed for dense integer sets. Only non-negative -integers can be stored. If the set will be sparse (for example -holding a single very large integer), use "Set" instead. """ -IntSet +bin doc""" - union(s1, s2...) -∪(s1, s2) + bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + +Bind "socket" to the given "host:port". Note that *0.0.0.0* +will listen on all devices. -Construct the union of two or more sets. Maintains order with -arrays. """ -union +bind doc""" - union!(s, iterable) + binomial(n, k) + +Number of ways to choose "k" out of "n" items -Union each element of "iterable" into set "s" in-place. """ -union! +binomial doc""" - intersect(s1, s2...) -∩(s1, s2) + bitbroadcast(f, As...) + +Like "broadcast", but allocates a "BitArray" to store the +result, rather then an "Array". -Construct the intersection of two or more sets. Maintains order and -multiplicity of the first argument for arrays and ranges. """ -intersect +bitbroadcast doc""" - setdiff(s1, s2) + bitpack(A::AbstractArray{T, N}) -> BitArray + +Converts a numeric array to a packed boolean array -Construct the set of elements in "s1" but not "s2". 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. """ -setdiff +bitpack doc""" - setdiff!(s, iterable) + bitrand([rng][, dims...]) + +Generate a "BitArray" of random boolean values. -Remove each element of "iterable" from set "s" in-place. """ -setdiff! +bitrand doc""" - symdiff(s1, s2...) + bits(n) + +A string giving the literal bit representation of a number. -Construct the symmetric difference of elements in the passed in -sets or arrays. Maintains order with arrays. """ -symdiff +bits doc""" - symdiff!(s, n) + bitunpack(B::BitArray{N}) -> Array{Bool,N} + +Converts a packed boolean array to an array of booleans -The set "s" is destructively modified to toggle the inclusion of -integer "n". """ -symdiff! +bitunpack doc""" - symdiff!(s, itr) + bkfact(A) -> BunchKaufman + +Compute the Bunch-Kaufman [Bunch1977] factorization of a real +symmetric or complex Hermitian matrix "A" and return a +"BunchKaufman" object. The following functions are available for +"BunchKaufman" objects: "size", "\", "inv", "issym", +"ishermitian". -For each element in "itr", destructively toggle its inclusion in -set "s". """ -symdiff! +bkfact doc""" - symdiff!(s1, s2) + bkfact!(A) -> BunchKaufman + +"bkfact!" is the same as "bkfact()", but saves space by +overwriting the input "A", instead of creating a copy. -Construct the symmetric difference of sets "s1" and "s2", -storing the result in "s1". """ -symdiff! +bkfact! doc""" - complement(s) + blkdiag(A...) + +Concatenate matrices block-diagonally. Currently only implemented +for sparse matrices. -Returns the set-complement of "IntSet" "s". """ -complement +blkdiag doc""" - complement!(s) + brfft(A, d[, dims]) + +Similar to "irfft()" but computes an unnormalized inverse +transform (similar to "bfft()"), which must be divided by the +product of the sizes of the transformed dimensions (of the real +output array) in order to obtain the inverse transform. -Mutates "IntSet" "s" into its set-complement. """ -complement! +brfft doc""" - intersect!(s1, s2) + broadcast(f, As...) + +Broadcasts the arrays "As" to a common size by expanding +singleton dimensions, and returns an array of the results +"f(as...)" for each position. -Intersects sets "s1" and "s2" and overwrites the set "s1" -with the result. If needed, "s1" will be expanded to the size of -"s2". """ -intersect! +broadcast doc""" - issubset(A, S) -> Bool -⊆(A, S) -> Bool + broadcast!(f, dest, As...) + +Like "broadcast", but store the result of "broadcast(f, As...)" +in the "dest" array. Note that "dest" is only used to store the +result, and does not supply arguments to "f" unless it is also +listed in the "As", as in "broadcast!(f, A, A, B)" to perform +"A[:] = broadcast(f, A, B)". -True if A is a subset of or equal to S. """ -issubset +broadcast! doc""" - push!(collection, items...) -> collection - -Insert one or more "items" at the end of "collection". + broadcast!_function(f) - julia> push!([1, 2, 3], 4, 5, 6) - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 +Like "broadcast_function", but for "broadcast!". -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])". """ -push! +broadcast!_function doc""" - pop!(collection) -> item + broadcast_function(f) -Remove the last item in "collection" and return it. +Returns a function "broadcast_f" such that +"broadcast_function(f)(As...) === broadcast(f, As...)". Most +useful in the form "const broadcast_f = broadcast_function(f)". - julia> A=[1, 2, 3, 4, 5, 6] - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 +""" +broadcast_function - julia> pop!(A) - 6 +doc""" + broadcast_getindex(A, inds...) + +Broadcasts the "inds" arrays to a common size like "broadcast", +and returns an array of the results "A[ks...]", where "ks" goes +over the positions in the broadcast. - julia> A - 5-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 """ -pop! +broadcast_getindex doc""" - unshift!(collection, items...) -> collection + broadcast_setindex!(A, X, inds...) -Insert one or more "items" at the beginning of "collection". +Broadcasts the "X" and "inds" arrays to a common size and +stores the value from each position in "X" at the indices given +by the same positions in "inds". - julia> unshift!([1, 2, 3, 4], 5, 6) - 6-element Array{Int64,1}: - 5 - 6 - 1 - 2 - 3 - 4 """ -unshift! +broadcast_setindex! doc""" - shift!(collection) -> item + bswap(n) -Remove the first "item" from "collection". +Byte-swap an integer - julia> A = [1, 2, 3, 4, 5, 6] - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 +""" +bswap + +doc""" + bytes2hex(bin_arr::Array{UInt8, 1}) + +Convert an array of bytes to its hexadecimal representation. All +characters are in lower-case. Returns an ASCIIString. + +""" +bytes2hex + +doc""" + bytestring(::Ptr{UInt8}[, length]) + +Create a string from the address of a C (0-terminated) string +encoded in ASCII or UTF-8. A copy is made; the ptr can be safely +freed. If "length" is specified, the string does not have to be +0-terminated. + + bytestring(s) + +Convert a string to a contiguous byte array representation +appropriate for passing it to C functions. The string will be +encoded as either ASCII or UTF-8. + +""" +bytestring + +doc""" + call(x, args...) + +If "x" is not a "Function", then "x(args...)" is equivalent +to "call(x, args...)". This means that function-like behavior +can be added to any type by defining new "call" methods. + +""" +call + +doc""" + cartesianmap(f, dims) + +Given a "dims" tuple of integers "(m, n, ...)", call "f" on +all combinations of integers in the ranges "1:m", "1:n", etc. + + julia> cartesianmap(println, (2,2)) + 11 + 21 + 12 + 22 + +""" +cartesianmap + +doc""" + cat(dims, A...) + +Concatenate the input arrays along the specified dimensions in the +iterable "dims". For dimensions not in "dims", all input arrays +should have the same size, which will also be the size of the +output array along that dimension. For dimensions in "dims", the +size of the output array is the sum of the sizes of the input +arrays along that dimension. If "dims" is a single number, the +different arrays are tightly stacked along that dimension. If +"dims" is an iterable containing several dimensions, this allows +to construct block diagonal matrices and their higher-dimensional +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 with *matrices[1]*, *matrices[2]*, ... as diagonal +blocks and matching zero blocks away from the diagonal. + +""" +cat + +doc""" + catalan + +Catalan's constant + +""" +catalan + +doc""" + catch_backtrace() + +Get the backtrace of the current exception, for use within +"catch" blocks. + +""" +catch_backtrace + +doc""" + cbrt(x) + +Return x^{1/3}. The prefix operator "∛" is equivalent to +"cbrt". + +""" +cbrt + +doc""" + cconvert(T, x) + +Convert "x" to a value of type "T", typically by calling +"convert(T,x)" + +In cases where "x" cannot be safely converted to "T", unlike +"convert", "cconvert" may return an object of a type different +from "T", which however is suitable for "unsafe_convert" to +handle. + +Neither "convert" nor "cconvert" should take a Julia object and +turn it into a "Ptr". + +""" +cconvert + +doc""" + cd(dir::AbstractString) + +Set the current working directory. + + cd(f[, dir]) + +Temporarily changes the current working directory (HOME if not +specified) and applies function f before returning. + +""" +cd + +doc""" + ceil([T], x[, digits[, base]]) + +"ceil(x)" returns the nearest integral value of the same type as +"x" that is greater than or equal to "x". + +"ceil(T, x)" converts the result to type "T", throwing an +"InexactError" if the value is not representable. + +"digits" and "base" work as for "round()". + +""" +ceil + +doc""" + cell(dims) + +Construct an uninitialized cell array (heterogeneous array). +"dims" can be either a tuple or a series of integer arguments. + +""" +cell + +doc""" + cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) + +Generate C-callable function pointer from Julia function. Type +annotation of the return value in the callback function is a must +for situations where Julia cannot infer the return type +automatically. + +For example: + + function foo() + # body + + retval::Float64 + end + + bar = cfunction(foo, Float64, ()) + +""" +cfunction + +doc""" + cglobal((symbol, library)[, type=Void]) + +Obtain a pointer to a global variable in a C-exported shared +library, specified exactly as in "ccall". Returns a +"Ptr{Type}", defaulting to "Ptr{Void}" if no Type argument is +supplied. The values can be read or written by "unsafe_load" or +"unsafe_store!", respectively. + +""" +cglobal + +doc""" + charwidth(c) + +Gives the number of columns needed to print a character. + +""" +charwidth + +doc""" + checkbounds(array, indexes...) + +Throw an error if the specified indexes are not in bounds for the +given array. + +""" +checkbounds + +doc""" + chmod(path, mode) + +Change the permissions mode of "path" to "mode". Only integer +"mode"s (e.g. 0o777) are currently supported. + +""" +chmod + +doc""" + chol(A[, LU]) -> F + +Compute the Cholesky factorization of a symmetric positive definite +matrix "A" and return the matrix "F". If "LU" is "Val{:U}" +(Upper), "F" is of type "UpperTriangular" and "A = F'*F". If +"LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" +and "A = F*F'". "LU" defaults to "Val{:U}". + +""" +chol + +doc""" + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + +Compute the Cholesky factorization of a dense symmetric positive +(semi)definite matrix "A" and return either a "Cholesky" if +"pivot==Val{false}" or "CholeskyPivoted" if +"pivot==Val{true}". "LU" may be ":L" for using the lower part +or ":U" for the upper part. The default is to use ":U". The +triangular matrix can be obtained from the factorization "F" +with: "F[:L]" and "F[:U]". The following functions are +available for "Cholesky" objects: "size", "\", "inv", +"det". For "CholeskyPivoted" there is also defined a "rank". +If "pivot==Val{false}" a "PosDefException" exception is thrown +in case the matrix is not positive definite. The argument "tol" +determines the tolerance for determining the rank. For negative +values, the tolerance is the machine precision. + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + +Compute the Cholesky factorization of a sparse positive definite +matrix "A". A fill-reducing permutation is used. "F = +cholfact(A)" is most frequently used to solve systems of equations +with "F\b", but also the methods "diag", "det", "logdet" +are defined for "F". You can also extract individual factors +from "F", using "F[:L]". However, since pivoting is on by +default, the factorization is internally represented as "A == +P'*L*L'*P" with a permutation matrix "P"; using just "L" +without accounting for "P" will give incorrect answers. To +include the effects of permutation, it's typically preferable to +extact "combined" factors like "PtL = F[:PtL]" (the equivalent +of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + +Setting optional "shift" keyword argument computes the +factorization of "A+shift*I" instead of "A". If the "perm" +argument is nonempty, it should be a permutation of *1:size(A,1)* +giving the ordering to use (instead of CHOLMOD's default AMD +ordering). + +The function calls the C library CHOLMOD and many other functions +from the library are wrapped but not exported. + +""" +cholfact + +doc""" + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + +"cholfact!" is the same as "cholfact()", but saves space by +overwriting the input "A", instead of creating a copy. +"cholfact!" can also reuse the symbolic factorization from a +different matrix "F" with the same structure when used as: +"cholfact!(F::CholmodFactor, A)". + +""" +cholfact! + +doc""" + chomp(string) - julia> shift!(A) - 1 +Remove a trailing newline from a string - julia> A - 5-element Array{Int64,1}: - 2 - 3 - 4 - 5 - 6 """ -shift! +chomp doc""" - insert!(collection, index, item) + chop(string) -Insert an "item" into "collection" at the given "index". -"index" is the index of "item" in the resulting "collection". +Remove the last character from a string - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 """ -insert! +chop doc""" - deleteat!(collection, index) + chr2ind(string, i) -Remove the item at the given "index" and return the modified -"collection". Subsequent items are shifted to fill the resulting -gap. +Convert a character index to a byte index - julia> deleteat!([6, 5, 4, 3, 2, 1], 2) - 5-element Array{Int64,1}: - 6 - 4 - 3 - 2 - 1 """ -deleteat! +chr2ind doc""" - deleteat!(collection, itr) - -Remove the items at the indices given by "itr", and return the -modified "collection". Subsequent items are shifted to fill the -resulting gap. "itr" must be sorted and unique. + circshift(A, shifts) - julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5) - 3-element Array{Int64,1}: - 5 - 3 - 1 +Circularly shift the data in an array. The second argument is a +vector giving the amount to shift in each dimension. - julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 """ -deleteat! +circshift doc""" - splice!(collection, index[, replacement]) -> item + cis(z) -Remove the item at the given index, and return the removed item. -Subsequent items are shifted down to fill the resulting gap. If -specified, replacement values from an ordered collection will be -spliced in place of the removed item. +Return \exp(iz). - julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5) - 2 +""" +cis - julia> A - 5-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 1 +doc""" + clamp(x, lo, hi) - julia> splice!(A, 5, -1) - 1 +Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x > +hi", return "hi". Arguments are promoted to a common type. +Operates elementwise over "x" if it is an array. - julia> A - 5-element Array{Int64,1}: - 6 - 5 - 4 - 3 - -1 +""" +clamp - julia> splice!(A, 1, [-1, -2, -3]) - 6 +doc""" + cld(x, y) - julia> A - 7-element Array{Int64,1}: - -1 - -2 - -3 - 5 - 4 - 3 - -1 +Smallest integer larger than or equal to "x/y". -To insert "replacement" before an index "n" without removing -any items, use "splice!(collection, n:n-1, replacement)". """ -splice! +cld doc""" - splice!(collection, range[, replacement]) -> items + clipboard(x) -Remove items in the specified index range, and return a collection -containing the removed items. Subsequent items are shifted down to -fill the resulting gap. If specified, replacement values from an -ordered collection will be spliced in place of the removed items. +Send a printed form of "x" to the operating system clipboard +("copy"). -To insert "replacement" before an index "n" without removing -any items, use "splice!(collection, n:n-1, replacement)". + clipboard() -> AbstractString - julia> splice!(A, 4:3, 2) - 0-element Array{Int64,1} +Return a string with the contents of the operating system clipboard +("paste"). - julia> A - 8-element Array{Int64,1}: - -1 - -2 - -3 - 2 - 5 - 4 - 3 - -1 """ -splice! +clipboard doc""" - resize!(collection, n) -> collection - -Resize "collection" 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. + close(stream) - julia> resize!([6, 5, 4, 3, 2, 1], 3) - 3-element Array{Int64,1}: - 6 - 5 - 4 +Close an I/O stream. Performs a "flush" first. - julia> resize!([6, 5, 4, 3, 2, 1], 8) - 8-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 - 0 - 0 """ -resize! +close doc""" - append!(collection, collection2) -> collection. + cmp(x, y) -Add the elements of "collection2" to the end of "collection". +Return -1, 0, or 1 depending on whether "x" is less than, equal +to, or greater than "y", respectively. Uses the total order +implemented by "isless". For floating-point numbers, uses "<" +but throws an error for unordered arguments. - julia> append!([1],[2,3]) - 3-element Array{Int64,1}: - 1 - 2 - 3 +""" +cmp - julia> append!([1, 2, 3], [4, 5, 6]) - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 +doc""" + code_llvm(f, types) + +Prints the LLVM bitcodes generated for running the method matching +the given generic function and type signature to "STDOUT". + +All metadata and dbg.* calls are removed from the printed bitcode. +Use code_llvm_raw for the full IR. -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)". """ -append! +code_llvm doc""" - prepend!(collection, items) -> collection + code_lowered(f, types) -Insert the elements of "items" to the beginning of -"collection". +Returns an array of lowered ASTs for the methods matching the given +generic function and type signature. - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 """ -prepend! +code_lowered doc""" - PriorityQueue(K, V[, ord]) + code_native(f, types) + +Prints the native assembly instructions generated for running the +method matching the given generic function and type signature to +STDOUT. -Construct a new "PriorityQueue", with keys of type "K" and -values/priorites of type "V". If an order is not given, the -priority queue is min-ordered using the default comparison for -"V". """ -Base.Collections.PriorityQueue +code_native doc""" - enqueue!(pq, k, v) + code_typed(f, types; optimize=true) + +Returns an array of lowered and type-inferred ASTs for the methods +matching the given generic function and type signature. The keyword +argument "optimize" controls whether additional optimizations, +such as inlining, are also applied. -Insert the a key "k" into a priority queue "pq" with priority -"v". """ -Base.Collections.enqueue! +code_typed doc""" - dequeue!(pq) + code_warntype(f, types) + +Displays lowered and type-inferred ASTs for the methods matching +the given generic function and type signature. The ASTs are +annotated in such a way as to cause "non-leaf" types to be +emphasized (if color is available, displayed in red). This serves +as a warning of potential type instability. Not all non-leaf types +are particularly problematic for performance, so the results need +to be used judiciously. See *@code_warntype* for more information. -Remove and return the lowest priority key from a priority queue. """ -Base.Collections.dequeue! +code_warntype doc""" - peek(pq) + collect(collection) + +Return an array of all items in a collection. For associative +collections, returns (key, value) tuples. + + collect(element_type, collection) + +Return an array of type "Array{element_type,1}" of all items in a +collection. -Return the lowest priority key from a priority queue without -removing that key from the queue. """ -Base.Collections.peek +collect doc""" - heapify(v[, ord]) + colon(start[, step], stop) + +Called by ":" syntax for constructing ranges. -Return a new vector in binary heap order, optionally using the -given ordering. """ -Base.Collections.heapify +colon doc""" - heapify!(v[, ord]) + combinations(array, n) + +Generate all combinations of "n" elements from an indexable +object. Because the number of combinations can be very large, this +function returns an iterator object. Use +"collect(combinations(array,n))" to get an array of all +combinations. -In-place "heapify()". """ -Base.Collections.heapify! +combinations doc""" - isheap(v[, ord]) + complement(s) + +Returns the set-complement of "IntSet" "s". -Return true iff an array is heap-ordered according to the given -order. """ -Base.Collections.isheap +complement doc""" - heappush!(v, x[, ord]) + complement!(s) + +Mutates "IntSet" "s" into its set-complement. -Given a binary heap-ordered array, push a new element "x", -preserving the heap property. For efficiency, this function does -not check that the array is indeed heap-ordered. """ -Base.Collections.heappush! +complement! doc""" - heappop!(v[, ord]) + complex(r[, i]) + +Convert real numbers or arrays to complex. "i" defaults to zero. -Given a binary heap-ordered array, remove and return the lowest -ordered element. For efficiency, this function does not check that -the array is indeed heap-ordered. """ -Base.Collections.heappop! +complex doc""" - nothing + cond(M[, p]) + +Condition number of the matrix "M", computed using the operator +"p"-norm. Valid values for "p" are "1", "2" (default), or +"Inf". -The singleton instance of type "Void", used by convention when -there is no value to return (as in a C "void" function). Can be -converted to an empty "Nullable" value. """ -nothing +cond doc""" - OS_NAME + condskeel(M[, x, p]) -A symbol representing the name of the operating system. Possible -values are ":Linux", ":Darwin" (OS X), or ":Windows". -""" -OS_NAME + \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \right\Vert_p \\ + \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert + \left\vert M^{-1} \right\vert \left\vert x \right\vert + \right\Vert_p -doc""" - ARGS +Skeel condition number \kappa_S of the matrix "M", optionally +with respect to the vector "x", as computed using the operator +"p"-norm. "p" is "Inf" by default, if not provided. Valid +values for "p" are "1", "2", or "Inf". + +This quantity is also known in the literature as the Bauer +condition number, relative condition number, or componentwise +relative condition number. -An array of the command line arguments passed to Julia, as strings. """ -ARGS +condskeel doc""" - C_NULL + conj(z) + +Compute the complex conjugate of a complex number "z" -The C null pointer constant, sometimes used when calling external -code. """ -C_NULL +conj doc""" - WORD_SIZE + conj!(A) + +Convert an array to its complex conjugate in-place -Standard word size on the current machine, in bits. """ -WORD_SIZE +conj! doc""" - VERSION + connect([host], port) -> TcpSocket -An object describing which version of Julia is in use. -""" -VERSION +Connect to the host "host" on port "port" -doc""" - LOAD_PATH + connect(path) -> Pipe -An array of paths (as strings) where the "require" function looks -for code. -""" -LOAD_PATH +Connect to the Named Pipe/Domain Socket at "path" -doc""" - ANY + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) -Equivalent to "Any" for dispatch purposes, but signals the -compiler to skip code generation specialization for that field -""" -ANY +Implemented by cluster managers using custom transports. It should +establish a logical connection to worker with id "pid", specified +by "config" and return a pair of "AsyncStream" objects. +Messages from "pid" to current process will be read off +"instrm", while messages to be sent to "pid" will be written to +"outstrm". The custom transport implementation must ensure that +messages are delivered and received completely and in order. +"Base.connect(manager::ClusterManager.....)" sets up TCP/IP +socket connections in-between workers. -doc""" - Period """ -Dates.Period +connect doc""" - Year -""" -Dates.Year + consume(task, values...) -doc""" - Month -""" -Dates.Month +Receive the next value passed to "produce" by the specified task. +Additional arguments may be passed, to be returned from the last +"produce" call in the producer. -doc""" - Week """ -Dates.Week +consume doc""" - Day -""" -Dates.Day + contains(haystack, needle) -doc""" - Hour -""" -Dates.Hour +Determine whether the second argument is a substring of the first. -doc""" - Minute """ -Dates.Minute +contains doc""" - Second -""" -Dates.Second + conv(u, v) -doc""" - Millisecond +Convolution of two vectors. Uses FFT algorithm. -"Period" types represent discrete, human representations of time. """ -Dates.Millisecond +conv doc""" - Instant + conv2(u, v, A) -"Instant" types represent integer-based, machine representations -of time as continuous timelines starting from an epoch. -""" -Dates.Instant +2-D convolution of the matrix "A" with the 2-D separable kernel +generated by the vectors "u" and "v". Uses 2-D FFT algorithm -doc""" - TimeType + conv2(B, A) + +2-D convolution of the matrix "B" with the matrix "A". Uses +2-D FFT algorithm -"TimeType" types wrap "Instant" machine instances to provide -human representations of the machine instant. """ -Dates.TimeType +conv2 doc""" - DateTime + convert(T, x) -"DateTime" wraps a "UTInstant{Millisecond}" and interprets it -according to the proleptic Gregorian calendar. -""" -Dates.DateTime +Convert "x" to a value of type "T". -doc""" - Date +If "T" is an "Integer" type, an "InexactError" will be raised +if "x" is not representable by "T", for example if "x" is not +integer-valued, or is outside the range supported by "T". -"Date" wraps a "UTInstant{Day}" and interprets it according to -the proleptic Gregorian calendar. -""" -Dates.Date + julia> convert(Int, 3.0) + 3 -doc""" - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:196 -Construct a DateTime type by parts. Arguments must be convertible -to "Int64". -""" -Dates.DateTime +If "T" is a "FloatingPoint" or "Rational" type, then it will +return the closest value to "x" representable by "T". -doc""" - DateTime(periods::Period...) -> DateTime + julia> x = 1/3 + 0.3333333333333333 -Constuct a DateTime type by "Period" type parts. Arguments may be -in any order. DateTime parts not provided will default to the value -of "Dates.default(period)". -""" -Dates.DateTime + julia> convert(Float32, x) + 0.33333334f0 -doc""" - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 -Create a DateTime through the adjuster API. The starting point will -be constructed from the provided "y, m, d..." arguments, and will -be adjusted until "f::Function" returns true. The step size in -adjusting can be provided manually through the "step" keyword. If -"negate=true", then the adjusting will stop when "f::Function" -returns false instead of true. "limit" provides a limit to the -max number of iterations the adjustment API will pursue before -throwing an error (in the case that "f::Function" is never -satisfied). """ -Dates.DateTime +convert doc""" - DateTime(dt::Date) -> DateTime + copy(x) + +Create a shallow copy of "x": the outer structure is copied, but +not all internal values. For example, copying an array produces a +new array with identically-same elements as the original. -Converts a "Date" type to a "DateTime". The hour, minute, -second, and millisecond parts of the new "DateTime" are assumed -to be zero. """ -Dates.DateTime +copy doc""" - DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + copy!(dest, src) -Construct a DateTime type by parsing the "dt" date string -following the pattern given in the "format" string. The following -codes can be used for constructing format strings: +Copy all elements from collection "src" to array "dest". +Returns "dest". -+-----------------+-----------+-----------------------------------------------------------------+ -| Code | Matches | Comment | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"y\" | 1996, 96 | Returns year of 1996, 0096 | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"m\" | 1, 01 | Matches 1 or 2-digit months | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"u\" | Jan | Matches abbreviated months according to the \"locale\" keyword | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"U\" | January | Matches full month names according to the \"locale\" keyword | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"d\" | 1, 01 | Matches 1 or 2-digit days | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"H\" | 00 | Matches hours | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"M\" | 00 | Matches minutes | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"S\" | 00 | Matches seconds | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"s\" | .500 | Matches milliseconds | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"e\" | Mon, Tues | Matches abbreviated days of the week | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"E\" | Monday | Matches full name days of the week | -+-----------------+-----------+-----------------------------------------------------------------+ -| \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and day | -+-----------------+-----------+-----------------------------------------------------------------+ + copy!(dest, do, src, so, N) + +Copy "N" elements from collection "src" starting at offset +"so", to array "dest" starting at offset "do". Returns +"dest". -All characters not listed above are treated as delimiters between -date and time slots. So a "dt" string of -"1996-01-15T00:00:00.0" would have a "format" string like -"y-m-dTH:M:S.s". """ -Dates.DateTime +copy! doc""" - Dates.DateFormat(format::AbstractString) -> DateFormat + copysign(x, y) + +Return "x" such that it has the same sign as "y" -Construct a date formatting object that can be passed repeatedly -for parsing similarly formatted date strings. "format" is a -format string in the form described above (e.g. ""yyyy-mm- -dd""). """ -Dates.Dates +copysign doc""" - DateTime(dt::AbstractString, df::DateFormat) -> DateTime + cor(v1[, v2][, vardim=1, mean=nothing]) + +Compute the Pearson correlation between the vector(s) in "v1" and +"v2". + +Users can use the keyword argument "vardim" to specify the +variable dimension, and "mean" to supply pre-computed mean +values. -Similar form as above for parsing a "DateTime", but passes a -"DateFormat" object instead of a raw formatting string. It is -more efficient if similarly formatted date strings will be parsed -repeatedly to first create a "DateFormat" object then use this -method for parsing. """ -Dates.DateTime +cor doc""" - Date(y[, m, d]) -> Date + cos(x) + +Compute cosine of "x", where "x" is in radians -Construct a "Date" type by parts. Arguments must be convertible -to "Int64". """ -Dates.Date +cos doc""" - Date(period::Period...) -> Date + cosc(x) + +Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq +0, and 0 if x = 0. This is the derivative of "sinc(x)". -Constuct a Date type by "Period" type parts. Arguments may be in -any order. Date parts not provided will default to the value of -"Dates.default(period)". """ -Dates.Date +cosc doc""" - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + cosd(x) + +Compute cosine of "x", where "x" is in degrees -Create a Date through the adjuster API. The starting point will be -constructed from the provided "y, m" arguments, and will be -adjusted until "f::Function" returns true. The step size in -adjusting can be provided manually through the "step" keyword. If -"negate=true", then the adjusting will stop when "f::Function" -returns false instead of true. "limit" provides a limit to the -max number of iterations the adjustment API will pursue before -throwing an error (given that "f::Function" is never satisfied). """ -Dates.Date +cosd doc""" - Date(dt::DateTime) -> Date + cosh(x) + +Compute hyperbolic cosine of "x" -Converts a "DateTime" type to a "Date". The hour, minute, -second, and millisecond parts of the "DateTime" are truncated, so -only the year, month and day parts are used in construction. """ -Dates.Date +cosh doc""" - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + cospi(x) + +Compute \cos(\pi x) more accurately than "cos(pi*x)", +especially for large "x". -Construct a Date type by parsing a "dt" date string following the -pattern given in the "format" string. Follows the same -conventions as "DateTime" above. """ -Dates.Date +cospi doc""" - Date(dt::AbstractString, df::DateFormat) -> Date + cot(x) + +Compute the cotangent of "x", where "x" is in radians -Parse a date from a date string "dt" using a "DateFormat" -object "df". """ -Dates.Date +cot doc""" - now() -> DateTime + cotd(x) + +Compute the cotangent of "x", where "x" is in degrees -Returns a DateTime corresponding to the user's system time -including the system timezone locale. """ -Dates.now +cotd doc""" - now(::Type{UTC}) -> DateTime + coth(x) + +Compute the hyperbolic cotangent of "x" -Returns a DateTime corresponding to the user's system time as -UTC/GMT. """ -Dates.now +coth doc""" - eps(::DateTime) -> Millisecond -eps(::Date) -> Day + count(p, itr) -> Integer + +Count the number of elements in "itr" for which predicate "p" +returns true. -Returns "Millisecond(1)" for "DateTime" values and "Day(1)" -for "Date" values. """ -Dates.eps +count doc""" - year(dt::TimeType) -> Int64 -month(dt::TimeType) -> Int64 -week(dt::TimeType) -> Int64 -day(dt::TimeType) -> Int64 -hour(dt::TimeType) -> Int64 -minute(dt::TimeType) -> Int64 -second(dt::TimeType) -> Int64 -millisecond(dt::TimeType) -> Int64 + count_ones(x::Integer) -> Integer + +Number of ones in the binary representation of "x". + + julia> count_ones(7) + 3 -Return the field part of a Date or DateTime as an "Int64". """ -Dates.year +count_ones doc""" - Year(dt::TimeType) -> Year -Month(dt::TimeType) -> Month -Week(dt::TimeType) -> Week -Day(dt::TimeType) -> Day -Hour(dt::TimeType) -> Hour -Minute(dt::TimeType) -> Minute -Second(dt::TimeType) -> Second -Millisecond(dt::TimeType) -> Millisecond + count_zeros(x::Integer) -> Integer + +Number of zeros in the binary representation of "x". + + julia> count_zeros(Int32(2 ^ 16 - 1)) + 16 -Return the field part of a Date or DateTime as a "Period" type. """ -Dates.Year +count_zeros doc""" - yearmonth(dt::TimeType) -> (Int64, Int64) + countfrom(start=1, step=1) + +An iterator that counts forever, starting at "start" and +incrementing by "step". -Simultaneously return the year and month parts of a Date or -DateTime. """ -Dates.yearmonth +countfrom doc""" - monthday(dt::TimeType) -> (Int64, Int64) + countlines(io[, eol::Char]) + +Read io until the end of the stream/file and count the number of +non-empty lines. To specify a file pass the filename as the first +argument. EOL markers other than '\n' are supported by passing +them as the second argument. -Simultaneously return the month and day parts of a Date or -DateTime. """ -Dates.monthday +countlines doc""" - yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) + countnz(A) + +Counts the number of nonzero values in array A (dense or sparse). +Note that this is not a constant-time operation. For sparse +matrices, one should usually use "nnz", which returns the number +of stored values. -Simultaneously return the year, month, and day parts of a Date or -DateTime. """ -Dates.yearmonthday +countnz doc""" - dayname(dt::TimeType; locale="english") -> AbstractString + cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) -Return the full day name corresponding to the day of the week of -the Date or DateTime in the given "locale". -""" -Dates.dayname +Compute the Pearson covariance between the vector(s) in "v1" and +"v2". Here, "v1" and "v2" can be either vectors or matrices. + +This function accepts three keyword arguments: + +* "vardim": the dimension of variables. When "vardim = 1", + variables are considered in columns while observations in rows; + when "vardim = 2", variables are in rows while observations in + columns. By default, it is set to "1". + +* "corrected": whether to apply Bessel's correction (divide by + "n-1" instead of "n"). By default, it is set to "true". + +* "mean": allow users to supply mean values that are known. By + default, it is set to "nothing", which indicates that the + mean(s) are unknown, and the function will compute the mean. + Users can use "mean=0" to indicate that the input data are + centered, and hence there's no need to subtract the mean. + +The size of the result depends on the size of "v1" and "v2". +When both "v1" and "v2" are vectors, it returns the covariance +between them as a scalar. When either one is a matrix, it returns a +covariance matrix of size "(n1, n2)", where "n1" and "n2" are +the numbers of slices in "v1" and "v2", which depend on the +setting of "vardim". -doc""" - dayabbr(dt::TimeType; locale="english") -> AbstractString +Note: "v2" can be omitted, which indicates "v2 = v1". -Return the abbreviated name corresponding to the day of the week of -the Date or DateTime in the given "locale". """ -Dates.dayabbr +cov doc""" - dayofweek(dt::TimeType) -> Int64 + cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) -Returns the day of the week as an "Int64" with "1 = Monday, 2 = -Tuesday, etc.". -""" -Dates.dayofweek +Copy the file, link, or directory from *src* to *dest*. +"remove_destination=true" will first remove an existing *dst*. -doc""" - dayofweekofmonth(dt::TimeType) -> Int +If *follow_symlinks=false*, and src is a symbolic link, dst will be +created as a symbolic link. If *follow_symlinks=true* and src is a +symbolic link, dst will be a copy of the file or directory *src* +refers to. -For the day of week of "dt", returns which number it is in -"dt"'s month. So if the day of the week of "dt" is Monday, then -"1 = First Monday of the month, 2 = Second Monday of the month, -etc." In the range 1:5. """ -Dates.dayofweekofmonth +cp doc""" - daysofweekinmonth(dt::TimeType) -> Int - -For the day of week of "dt", returns the total number of that day -of the week in "dt"'s month. Returns 4 or 5. Useful in temporal -expressions for specifying the last day of a week in a month by -including "dayofweekofmonth(dt) == daysofweekinmonth(dt)" in the -adjuster function. -""" -Dates.daysofweekinmonth + cross(x, y) +×(x, y) -doc""" - monthname(dt::TimeType; locale="english") -> AbstractString +Compute the cross product of two 3-vectors. -Return the full name of the month of the Date or DateTime in the -given "locale". """ -Dates.monthname +cross doc""" - monthabbr(dt::TimeType; locale="english") -> AbstractString - -Return the abbreviated month name of the Date or DateTime in the -given "locale". -""" -Dates.monthabbr + csc(x) -doc""" - daysinmonth(dt::TimeType) -> Int +Compute the cosecant of "x", where "x" is in radians -Returns the number of days in the month of "dt". Value will be -28, 29, 30, or 31. """ -Dates.daysinmonth +csc doc""" - isleapyear(dt::TimeType) -> Bool - -Returns true if the year of "dt" is a leap year. -""" -Dates.isleapyear + cscd(x) -doc""" - dayofyear(dt::TimeType) -> Int +Compute the cosecant of "x", where "x" is in degrees -Returns the day of the year for "dt" with January 1st being day -1. """ -Dates.dayofyear +cscd doc""" - daysinyear(dt::TimeType) -> Int - -Returns 366 if the year of "dt" is a leap year, otherwise returns -365. -""" -Dates.daysinyear + csch(x) -doc""" - quarterofyear(dt::TimeType) -> Int +Compute the hyperbolic cosecant of "x" -Returns the quarter that "dt" resides in. Range of value is 1:4. """ -Dates.quarterofyear +csch doc""" - dayofquarter(dt::TimeType) -> Int + ctime(file) + +Equivalent to stat(file).ctime -Returns the day of the current quarter of "dt". Range of value is -1:92. """ -Dates.dayofquarter +ctime doc""" - trunc(dt::TimeType, ::Type{Period}) -> TimeType + ctranspose(A) + +The conjugate transposition operator ("'"). -Truncates the value of "dt" according to the provided "Period" -type. E.g. if "dt" is "1996-01-01T12:30:00", then -"trunc(dt,Day) == 1996-01-01T00:00:00". """ -Dates.trunc +ctranspose doc""" - firstdayofweek(dt::TimeType) -> TimeType + ctranspose!(dest, src) + +Conjugate transpose array "src" and store the result in the +preallocated array "dest", which should have a size corresponding +to "(size(src,2),size(src,1))". No in-place transposition is +supported and unexpected results will happen if *src* and *dest* +have overlapping memory regions. -Adjusts "dt" to the Monday of its week. """ -Dates.firstdayofweek +ctranspose! doc""" - lastdayofweek(dt::TimeType) -> TimeType + cummax(A[, dim]) + +Cumulative maximum along a dimension. The dimension defaults to 1. -Adjusts "dt" to the Sunday of its week. """ -Dates.lastdayofweek +cummax doc""" - firstdayofmonth(dt::TimeType) -> TimeType + cummin(A[, dim]) + +Cumulative minimum along a dimension. The dimension defaults to 1. -Adjusts "dt" to the first day of its month. """ -Dates.firstdayofmonth +cummin doc""" - lastdayofmonth(dt::TimeType) -> TimeType + cumprod(A[, dim]) + +Cumulative product along a dimension "dim" (defaults to 1). See +also "cumprod!()" to use a preallocated output array, both for +performance and to control the precision of the output (e.g. to +avoid overflow). -Adjusts "dt" to the last day of its month. """ -Dates.lastdayofmonth +cumprod doc""" - firstdayofyear(dt::TimeType) -> TimeType + cumprod!(B, A[, dim]) + +Cumulative product of "A" along a dimension, storing the result +in "B". The dimension defaults to 1. -Adjusts "dt" to the first day of its year. """ -Dates.firstdayofyear +cumprod! doc""" - lastdayofyear(dt::TimeType) -> TimeType + cumsum(A[, dim]) + +Cumulative sum along a dimension "dim" (defaults to 1). See also +"cumsum!()" to use a preallocated output array, both for +performance and to control the precision of the output (e.g. to +avoid overflow). -Adjusts "dt" to the last day of its year. """ -Dates.lastdayofyear +cumsum doc""" - firstdayofquarter(dt::TimeType) -> TimeType + cumsum!(B, A[, dim]) + +Cumulative sum of "A" along a dimension, storing the result in +"B". The dimension defaults to 1. -Adjusts "dt" to the first day of its quarter. """ -Dates.firstdayofquarter +cumsum! doc""" - lastdayofquarter(dt::TimeType) -> TimeType + cumsum_kbn(A[, dim]) + +Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier +compensated summation algorithm for additional accuracy. The +dimension defaults to 1. -Adjusts "dt" to the last day of its quarter. """ -Dates.lastdayofquarter +cumsum_kbn doc""" - tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + current_module() -> Module + +Get the *dynamically* current module, which is the module code is +currently being read from. In general, this is not the same as the +module containing the call to this function. -Adjusts "dt" to the next day of week corresponding to "dow" -with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows -the current "dt" to be considered as the next "dow", allowing -for no adjustment to occur. """ -Dates.tonext +current_module doc""" - toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + current_task() + +Get the currently running Task. -Adjusts "dt" to the previous day of week corresponding to "dow" -with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows -the current "dt" to be considered as the previous "dow", -allowing for no adjustment to occur. """ -Dates.toprev +current_task doc""" - tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType + cycle(iter) + +An iterator that cycles through "iter" forever. -Adjusts "dt" to the first "dow" of its month. Alternatively, -"of=Year" will adjust to the first "dow" of the year. """ -Dates.tofirst +cycle doc""" - tolast(dt::TimeType, dow::Int;of=Month) -> TimeType + dawson(x) + +Compute the Dawson function (scaled imaginary error function) of +"x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} +\operatorname{erfi}(x). -Adjusts "dt" to the last "dow" of its month. Alternatively, -"of=Year" will adjust to the last "dow" of the year. """ -Dates.tolast +dawson doc""" - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType + dct(A[, dims]) + +Performs a multidimensional type-II discrete cosine transform (DCT) +of the array "A", using the unitary normalization of the DCT. The +optional "dims" argument specifies an iterable subset of +dimensions (e.g. an integer, range, tuple, or array) to transform +along. Most efficient if the size of "A" along the transformed +dimensions is a product of small primes; see "nextprod()". See +also "plan_dct()" for even greater efficiency. -Adjusts "dt" by iterating at most "limit" iterations by -"step" increments until "func" returns true. "func" must take -a single "TimeType" argument and return a "Bool". "same" -allows "dt" to be considered in satisfying "func". "negate" -will make the adjustment process terminate when "func" returns -false instead of true. """ -Dates.tonext +dct doc""" - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType + dct!(A[, dims]) + +Same as "dct!()", except that it operates in-place on "A", +which must be an array of real or complex floating-point values. -Adjusts "dt" by iterating at most "limit" iterations by -"step" increments until "func" returns true. "func" must take -a single "TimeType" argument and return a "Bool". "same" -allows "dt" to be considered in satisfying "func". "negate" -will make the adjustment process terminate when "func" returns -false instead of true. """ -Dates.toprev +dct! doc""" - Year(v) -Month(v) -Week(v) -Day(v) -Hour(v) -Minute(v) -Second(v) -Millisecond(v) + dec(n[, pad]) + +Convert an integer to a decimal string, optionally specifying a +number of digits to pad to. -Construct a "Period" type with the given "v" value. Input must -be losslessly convertible to an "Int64". """ -Dates.Year +dec doc""" - default(p::Period) -> Period + deconv(b, a) + +Construct vector "c" such that "b = conv(a,c) + r". Equivalent +to polynomial division. -Returns a sensible "default" value for the input Period by -returning "one(p)" for Year, Month, and Day, and "zero(p)" for -Hour, Minute, Second, and Millisecond. """ -Dates.default +deconv doc""" - today() -> Date + deepcopy(x) -Returns the date portion of "now()". -""" -Dates.today +Create a deep copy of "x": everything is copied recursively, +resulting in a fully independent object. For example, deep-copying +an array produces a new array whose elements are deep copies of the +original elements. Calling *deepcopy* on an object should generally +have the same effect as serializing and then deserializing it. -doc""" - unix2datetime(x) -> DateTime +As a special case, functions can only be actually deep-copied if +they are anonymous, otherwise they are just copied. The difference +is only relevant in the case of closures, i.e. functions which may +contain hidden internal references. + +While it isn't normally necessary, user-defined types can override +the default "deepcopy" behavior by defining a specialized version +of the function "deepcopy_internal(x::T, dict::ObjectIdDict)" +(which shouldn't otherwise be used), where "T" is the type to be +specialized for, and "dict" keeps track of objects copied so far +within the recursion. Within the definition, "deepcopy_internal" +should be used in place of "deepcopy", and the "dict" variable +should be updated as appropriate before returning. -Takes the number of seconds since unix epoch -"1970-01-01T00:00:00" and converts to the corresponding DateTime. """ -Dates.unix2datetime +deepcopy doc""" - datetime2unix(dt::DateTime) -> Float64 + deg2rad(x) + +Convert "x" from degrees to radians -Takes the given DateTime and returns the number of seconds since -the unix epoch as a "Float64". """ -Dates.datetime2unix +deg2rad doc""" - julian2datetime(julian_days) -> DateTime + delete!(collection, key) + +Delete the mapping for the given key in a collection, and return +the collection. -Takes the number of Julian calendar days since epoch -"-4713-11-24T12:00:00" and returns the corresponding DateTime. """ -Dates.julian2datetime +delete! doc""" - datetime2julian(dt::DateTime) -> Float64 + deleteat!(collection, index) + +Remove the item at the given "index" and return the modified +"collection". 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 + + deleteat!(collection, itr) + +Remove the items at the indices given by "itr", and return the +modified "collection". Subsequent items are shifted to fill the +resulting gap. "itr" must be sorted and unique. + + 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], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:631 -Takes the given DateTime and returns the number of Julian calendar -days since the julian epoch as a "Float64". """ -Dates.datetime2julian +deleteat! doc""" - rata2datetime(days) -> DateTime + den(x) + +Denominator of the rational representation of "x" -Takes the number of Rata Die days since epoch -"0000-12-31T00:00:00" and returns the corresponding DateTime. """ -Dates.rata2datetime +den doc""" - datetime2rata(dt::TimeType) -> Int64 + deserialize(stream) + +Read a value written by "serialize". -Returns the number of Rata Die days since epoch from the given Date -or DateTime. """ -Dates.datetime2rata +deserialize doc""" - pwd() -> AbstractString + det(M) + +Matrix determinant -Get the current working directory. """ -pwd +det doc""" - cd(dir::AbstractString) + detach(command) + +Mark a command object so that it will be run in a new process +group, allowing it to outlive the julia process, and not have +Ctrl-C interrupts passed to it. -Set the current working directory. """ -cd +detach doc""" - cd(f[, dir]) + diag(M[, k]) + +The "k"th diagonal of a matrix, as a vector. Use "diagm" to +construct a diagonal matrix. -Temporarily changes the current working directory (HOME if not -specified) and applies function f before returning. """ -cd +diag doc""" - readdir([dir]) -> Vector{ByteString} + diagind(M[, k]) + +A "Range" giving the indices of the "k"th diagonal of the +matrix "M". -Returns the files and directories in the directory *dir* (or the -current working directory if not given). """ -readdir +diagind doc""" - mkdir(path[, mode]) + diagm(v[, k]) + +Construct a diagonal matrix and place "v" on the "k"th +diagonal. -Make a new directory with name "path" and permissions "mode". -"mode" defaults to 0o777, modified by the current file creation -mask. """ -mkdir +diagm doc""" - mkpath(path[, mode]) + diff(A[, dim]) + +Finite difference operator of matrix or vector. -Create all directories in the given "path", with permissions -"mode". "mode" defaults to 0o777, modified by the current file -creation mask. """ -mkpath +diff doc""" - symlink(target, link) + digamma(x) -Creates a symbolic link to "target" with the name "link". +Compute the digamma function of "x" (the logarithmic derivative +of "gamma(x)") -Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. """ -symlink +digamma doc""" - readlink(path) -> AbstractString + digits(n[, base][, pad]) + +Returns an array of the digits of "n" in the given base, +optionally padded with zeros to a specified size. More significant +digits are at higher indexes, such that "n == +sum([digits[k]*base^(k-1) for k=1:length(digits)])". -Returns the value of a symbolic link "path". """ -readlink +digits doc""" - chmod(path, mode) + digits!(array, n[, base]) + +Fills an array of the digits of "n" in the given base. More +significant digits are at higher indexes. If the array length is +insufficient, the least significant digits are filled up to the +array length. If the array length is excessive, the excess portion +is filled with zeros. -Change the permissions mode of "path" to "mode". Only integer -"mode"s (e.g. 0o777) are currently supported. """ -chmod +digits! doc""" - stat(file) + dirname(path::AbstractString) -> AbstractString -Returns a structure whose fields contain information about the -file. The fields of the structure are: +Get the directory part of a path. -+-----------+------------------------------------------------------------------------+ -| size | The size (in bytes) of the file | -+-----------+------------------------------------------------------------------------+ -| device | ID of the device that contains the file | -+-----------+------------------------------------------------------------------------+ -| inode | The inode number of the file | -+-----------+------------------------------------------------------------------------+ -| mode | The protection mode of the file | -+-----------+------------------------------------------------------------------------+ -| nlink | The number of hard links to the file | -+-----------+------------------------------------------------------------------------+ -| uid | The user id of the owner of the file | -+-----------+------------------------------------------------------------------------+ -| gid | The group id of the file owner | -+-----------+------------------------------------------------------------------------+ -| rdev | If this file refers to a device, the ID of the device it refers to | -+-----------+------------------------------------------------------------------------+ -| blksize | The file-system preferred block size for the file | -+-----------+------------------------------------------------------------------------+ -| blocks | The number of such blocks allocated | -+-----------+------------------------------------------------------------------------+ -| mtime | Unix timestamp of when the file was last modified | -+-----------+------------------------------------------------------------------------+ -| ctime | Unix timestamp of when the file was created | -+-----------+------------------------------------------------------------------------+ """ -stat +dirname doc""" - lstat(file) + disable_sigint(f::Function) + +Disable Ctrl-C handler during execution of a function, for calling +external code that is not interrupt safe. Intended to be called +using "do" block syntax as follows: + + disable_sigint() do + # interrupt-unsafe code + ... + end -Like stat, but for symbolic links gets the info for the link itself -rather than the file it refers to. This function must be called on -a file path rather than a file object or a file descriptor. """ -lstat +disable_sigint doc""" - ctime(file) + display(x) +display(d::Display, x) +display(mime, x) +display(d::Display, mime, x) -Equivalent to stat(file).ctime -""" -ctime +Display "x" using the topmost applicable display in the display +stack, typically using the richest supported multimedia output for +"x", with plain-text "STDOUT" output as a fallback. The +"display(d, x)" variant attempts to display "x" on the given +display "d" only, throwing a "MethodError" if "d" cannot +display objects of this type. -doc""" - mtime(file) +There are also two variants with a "mime" argument (a MIME type +string, such as ""image/png""), which attempt to display "x" +using the requested MIME type *only*, throwing a "MethodError" if +this type is not supported by either the display(s) or by "x". +With these variants, one can also supply the "raw" data in the +requested MIME type by passing "x::AbstractString" (for MIME +types with text-based storage, such as text/html or +application/postscript) or "x::Vector{UInt8}" (for binary MIME +types). -Equivalent to stat(file).mtime """ -mtime +display doc""" - filemode(file) - -Equivalent to stat(file).mode -""" -filemode + displayable(mime) -> Bool +displayable(d::Display, mime) -> Bool -doc""" - filesize(path...) +Returns a boolean value indicating whether the given "mime" type +(string) is displayable by any of the displays in the current +display stack, or specifically by the display "d" in the second +variant. -Equivalent to stat(file).size """ -filesize +displayable doc""" - uperm(file) - -Gets the permissions of the owner of the file as a bitfield of + div(x, y) +÷(x, y) -+------+-----------------------+ -| 01 | Execute Permission | -+------+-----------------------+ -| 02 | Write Permission | -+------+-----------------------+ -| 04 | Read Permission | -+------+-----------------------+ +The quotient from Euclidean division. Computes "x/y", truncated +to an integer. -For allowed arguments, see "stat". """ -uperm +div doc""" - gperm(file) + divrem(x, y) + +The quotient and remainder from Euclidean division. Equivalent to +"(x÷y, x%y)". -Like uperm but gets the permissions of the group owning the file """ -gperm +divrem doc""" - operm(file) + done(iter, state) -> Bool + +Test whether we are done iterating -Like uperm but gets the permissions for people who neither own the -file nor are a member of the group owning the file """ -operm +done doc""" - cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + dot(x, y) +⋅(x, y) -Copy the file, link, or directory from *src* to *dest*. -"remove_destination=true" will first remove an existing *dst*. +Compute the dot product. For complex vectors, the first vector is +conjugated. -If *follow_symlinks=false*, and src is a symbolic link, dst will be -created as a symbolic link. If *follow_symlinks=true* and src is a -symbolic link, dst will be a copy of the file or directory *src* -refers to. """ -cp +dot doc""" download(url[, localfile]) @@ -5779,624 +6016,684 @@ availability of external tools such as "curl", "wget" or "fetch" to download the file and is provided for convenience. For production use or situations in which more options are need, please use a package that provides the desired functionality instead. + """ download doc""" - mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - -Move the file, link, or directory from *src* to *dest*. -"remove_destination=true" will first remove an existing *dst*. -""" -mv + drop(iter, n) -doc""" - rm(path::AbstractString; recursive=false) +An iterator that generates all but the first "n" elements of +"iter". -Delete the file, link, or empty directory at the given path. If -"recursive=true" is passed and the path is a directory, then all -contents are removed recursively. """ -rm +drop doc""" - touch(path::AbstractString) - -Update the last-modified timestamp on a file to the current time. -""" -touch + dump(x) -doc""" - tempname() +Show all user-visible structure of a value. -Generate a unique temporary file path. """ -tempname +dump doc""" - tempdir() - -Obtain the path of a temporary directory (possibly shared with -other processes). -""" -tempdir + e +eu -doc""" - mktemp([parent=tempdir()]) +The constant e -Returns "(path, io)", where "path" is the path of a new -temporary file in "parent" and "io" is an open file object for -this path. """ -mktemp +e doc""" - mktempdir([parent=tempdir()]) + eachindex(A...) -Create a temporary directory in the "parent" directory and return -its path. -""" -mktempdir +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 (like "Array"), this is +simply the range "1: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 non-integer indices). -doc""" - isblockdev(path) -> Bool +Example for a sparse 2-d array: -Returns "true" if "path" is a block device, "false" -otherwise. -""" -isblockdev + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 -doc""" - ischardev(path) -> Bool + 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] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 -Returns "true" if "path" is a character device, "false" -otherwise. """ -ischardev +eachindex doc""" - isdir(path) -> Bool - -Returns "true" if "path" is a directory, "false" otherwise. -""" -isdir + eachline(stream) -doc""" - isexecutable(path) -> Bool +Create an iterable object that will yield each line from a stream. -Returns "true" if the current user has permission to execute -"path", "false" otherwise. """ -isexecutable +eachline doc""" - isfifo(path) -> Bool - -Returns "true" if "path" is a FIFO, "false" otherwise. -""" -isfifo + eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) -doc""" - isfile(path) -> Bool +Search for all matches of a the regular expression "r" in "s" +and return a iterator over the matches. If overlap is true, the +matching sequences are allowed to overlap indices in the original +string, otherwise they must be from distinct character ranges. -Returns "true" if "path" is a regular file, "false" -otherwise. """ -isfile +eachmatch doc""" - islink(path) -> Bool + edit(file::AbstractString[, line]) -Returns "true" if "path" is a symbolic link, "false" -otherwise. -""" -islink +Edit a file optionally providing a line number to edit at. Returns +to the julia prompt when you quit the editor. -doc""" - ismount(path) -> Bool + edit(function[, types]) + +Edit the definition of a function, optionally specifying a tuple of +types to indicate which method to edit. -Returns "true" if "path" is a mount point, "false" otherwise. """ -ismount +edit doc""" - ispath(path) -> Bool + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V -Returns "true" if "path" is a valid filesystem path, "false" -otherwise. -""" -ispath +Computes eigenvalues and eigenvectors of "A". See "eigfact()" +for details on the "balance" keyword argument. -doc""" - isreadable(path) -> Bool + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) -Returns "true" if the current user has permission to read -"path", "false" otherwise. -""" -isreadable +"eig" is a wrapper around "eigfact()", extracting all parts of +the factorization to a tuple; where possible, using "eigfact()" +is recommended. -doc""" - issetgid(path) -> Bool + eig(A, B) -> D, V -Returns "true" if "path" has the setgid flag set, "false" -otherwise. -""" -issetgid +Computes generalized eigenvalues and vectors of "A" with respect +to "B". -doc""" - issetuid(path) -> Bool +"eig" is a wrapper around "eigfact()", extracting all parts of +the factorization to a tuple; where possible, using "eigfact()" +is recommended. -Returns "true" if "path" has the setuid flag set, "false" -otherwise. """ -issetuid +eig doc""" - issocket(path) -> Bool + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen -Returns "true" if "path" is a socket, "false" otherwise. -""" -issocket +Computes the eigenvalue decomposition of "A", returning an +"Eigen" factorization object "F" which contains the eigenvalues +in "F[:values]" and the eigenvectors in the columns of the matrix +"F[:vectors]". (The "k"th eigenvector can be obtained from the +slice "F[:vectors][:, k]".) -doc""" - issticky(path) -> Bool +The following functions are available for "Eigen" objects: +"inv", "det". -Returns "true" if "path" has the sticky bit set, "false" -otherwise. -""" -issticky +If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it +is possible to calculate only a subset of the eigenvalues by +specifying either a "UnitRange" "irange" covering indices of +the sorted eigenvalues or a pair "vl" and "vu" for the lower +and upper boundaries of the eigenvalues. -doc""" - iswritable(path) -> Bool +For general nonsymmetric matrices it is possible to specify how the +matrix is balanced before the eigenvector calculation. The option +"permute=true" permutes the matrix to become closer to upper +triangular, and "scale=true" scales the matrix by its diagonal +elements to make rows and columns more equal in norm. The default +is "true" for both options. -Returns "true" if the current user has permission to write to -"path", "false" otherwise. -""" -iswritable + eigfact(A, B) -> GeneralizedEigen -doc""" - homedir() -> AbstractString +Computes the generalized eigenvalue decomposition of "A" and +"B", returning a "GeneralizedEigen" factorization object "F" +which contains the generalized eigenvalues in "F[:values]" and +the generalized eigenvectors in the columns of the matrix +"F[:vectors]". (The "k"th generalized eigenvector can be +obtained from the slice "F[:vectors][:, k]".) -Return the current user's home directory. """ -homedir +eigfact doc""" - dirname(path::AbstractString) -> AbstractString + eigfact!(A[, B]) + +Same as "eigfact()", but saves space by overwriting the input +"A" (and "B"), instead of creating a copy. -Get the directory part of a path. """ -dirname +eigfact! doc""" - basename(path::AbstractString) -> AbstractString + eigmax(A) + +Returns the largest eigenvalue of "A". -Get the file name part of a path. """ -basename +eigmax doc""" - @__FILE__() -> AbstractString + eigmin(A) + +Returns the smallest eigenvalue of "A". -"@__FILE__" expands to a string with the absolute path and file -name of the script being run. Returns "nothing" if run from a -REPL or an empty string if evaluated by "julia -e ". """ -@__FILE__ +eigmin doc""" - isabspath(path::AbstractString) -> Bool + eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) -Determines whether a path is absolute (begins at the root -directory). -""" -isabspath +Computes eigenvalues "d" of "A" using Lanczos or Arnoldi +iterations for real symmetric or general nonsymmetric matrices +respectively. If "B" is provided, the generalized eigenproblem is +solved. -doc""" - isdirpath(path::AbstractString) -> Bool +The following keyword arguments are supported: + * "nev": Number of eigenvalues -Determines whether a path refers to a directory (for example, ends -with a path separator). -""" -isdirpath + * "ncv": Number of Krylov vectors used in the computation; + should satisfy -doc""" - joinpath(parts...) -> AbstractString + "nev+1 <= ncv <= n" for real symmetric problems and + "nev+2 <= ncv <= n" for other problems, where "n" is + the size of the input matrix "A". The default is "ncv = + max(20,2*nev+1)". Note that these restrictions limit the + input matrix "A" to be of dimension at least 2. -Join path components into a full path. If some argument is an -absolute path, then prior components are dropped. -""" -joinpath + * "which": type of eigenvalues to compute. See the note + below. -doc""" - abspath(path::AbstractString) -> AbstractString + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \"which\" | type of eigenvalues | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LM\" | eigenvalues of largest magnitude (default) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SM\" | eigenvalues of smallest magnitude | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LR\" | eigenvalues of largest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SR\" | eigenvalues of smallest real part | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | + +-----------+-----------------------------------------------------------------------------------------------------------------------------+ -Convert a path to an absolute path by adding the current directory -if necessary. -""" -abspath + * "tol": tolerance (tol \le 0.0 defaults to + "DLAMCH('EPS')") -doc""" - normpath(path::AbstractString) -> AbstractString + * "maxiter": Maximum number of iterations (default = 300) -Normalize a path, removing "." and ".." entries. -""" -normpath + * "sigma": Specifies the level shift used in inverse + iteration. If "nothing" (default), defaults to ordinary + (forward) iterations. Otherwise, find eigenvalues close to + "sigma" using shift and invert iterations. -doc""" - realpath(path::AbstractString) -> AbstractString + * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) + if "true" -Canonicalize a path by expanding symbolic links and removing "." -and ".." entries. -""" -realpath + * "v0": starting vector from which to start the iterations -doc""" - relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString +"eigs" returns the "nev" requested eigenvalues in "d", the +corresponding Ritz vectors "v" (only if "ritzvec=true"), the +number of converged eigenvalues "nconv", the number of iterations +"niter" and the number of matrix vector multiplications +"nmult", as well as the final residual vector "resid". -Return a relative filepath to path either from the current -directory or from an optional start directory. This is a path -computation: the filesystem is not accessed to confirm the -existence or nature of path or startpath. -""" -relpath +Note: The "sigma" and "which" keywords interact: the + description of eigenvalues searched for by "which" do _not_ + necessarily refer to the eigenvalues of "A", but rather the + linear operator constructed by the specification of the iteration + mode implied by "sigma". -doc""" - expanduser(path::AbstractString) -> AbstractString + +-----------------+------------------------------------+------------------------------------+ + | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | + +-----------------+------------------------------------+------------------------------------+ + | \"nothing\" | ordinary (forward) | A | + +-----------------+------------------------------------+------------------------------------+ + | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | + +-----------------+------------------------------------+------------------------------------+ -On Unix systems, replace a tilde character at the start of a path -with the current user's home directory. """ -expanduser +eigs doc""" - splitdir(path::AbstractString) -> (AbstractString, AbstractString) + eigvals(A,[irange,][vl,][vu]) -Split a path into a tuple of the directory name and file name. -""" -splitdir +Returns the eigenvalues of "A". If "A" is "Symmetric", +"Hermitian" or "SymTridiagonal", it is possible to calculate +only a subset of the eigenvalues by specifying either a +"UnitRange" "irange" covering indices of the sorted +eigenvalues, or a pair "vl" and "vu" for the lower and upper +boundaries of the eigenvalues. -doc""" - splitdrive(path::AbstractString) -> (AbstractString, AbstractString) +For general non-symmetric matrices it is possible to specify how +the matrix is balanced before the eigenvector calculation. The +option "permute=true" permutes the matrix to become closer to +upper triangular, and "scale=true" scales the matrix by its +diagonal elements to make rows and columns more equal in norm. The +default is "true" for both options. -On Windows, split a path into the drive letter part and the path -part. On Unix systems, the first component is always the empty -string. """ -splitdrive +eigvals doc""" - splitext(path::AbstractString) -> (AbstractString, AbstractString) + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + +Returns a matrix "M" whose columns are the eigenvectors of "A". +(The "k"th eigenvector can be obtained from the slice "M[:, +k]".) The "permute" and "scale" keywords are the same as for +"eigfact()". + +For "SymTridiagonal" matrices, if the optional vector of +eigenvalues "eigvals" is specified, returns the specific +corresponding eigenvectors. -If the last component of a path contains a dot, split the path into -everything before the dot and everything including and after the -dot. Otherwise, return a tuple of the argument unmodified and the -empty string. """ -splitext +eigvecs doc""" - open(file_name[, read, write, create, truncate, append]) -> IOStream + 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 "(key,value)" tuple type. 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. -Open a file in a mode specified by five boolean arguments. The -default is to open files for reading only. Returns a stream for -accessing the file. """ -open +eltype doc""" - open(file_name[, mode]) -> IOStream + empty!(collection) -> collection -Alternate syntax for open, where a string-based mode specifier is -used instead of the five booleans. The values of "mode" -correspond to those from "fopen(3)" or Perl "open", and are -equivalent to setting the following boolean groups: +Remove all elements from a "collection". -+------+-----------------------------------+ -| r | read | -+------+-----------------------------------+ -| r+ | read, write | -+------+-----------------------------------+ -| w | write, create, truncate | -+------+-----------------------------------+ -| w+ | read, write, create, truncate | -+------+-----------------------------------+ -| a | write, create, append | -+------+-----------------------------------+ -| a+ | read, write, create, append | -+------+-----------------------------------+ """ -open +empty! doc""" - open(f::function, args...) + endof(collection) -> Integer -Apply the function "f" to the result of "open(args...)" and -close the resulting file descriptor upon completion. +Returns the last index of the collection. + + julia> endof([1,2,4]) + 3 -**Example**: "open(readall, "file.txt")" """ -open +endof doc""" - IOBuffer() -> IOBuffer + endswith(string, suffix | chars) + +Returns "true" if "string" ends with "suffix". If the second +argument is a vector or set of characters, tests whether the last +character of "string" belongs to that set. -Create an in-memory I/O stream. """ -IOBuffer +endswith doc""" - IOBuffer(size::Int) + enumerate(iter) -Create a fixed size IOBuffer. The buffer will not grow dynamically. -""" -IOBuffer +An iterator that yields "(i, x)" where "i" is an index starting +at 1, and "x" is the "i"th value from the given iterator. It's +useful when you need not only the values "x" over which you are +iterating, but also the index "i" of the iterations. -doc""" - IOBuffer(string) + julia> a = ["a", "b", "c"]; + + julia> for (index, value) in enumerate(a) + println("\$index \$value") + end + 1 a + 2 b + 3 c -Create a read-only IOBuffer on the data underlying the given string """ -IOBuffer +enumerate doc""" - IOBuffer([data][, readable, writable[, maxsize]]) + eof(stream) -> Bool + +Tests whether an I/O stream is at end-of-file. If the stream is not +yet exhausted, this function will block to wait for more data if +necessary, and then return "false". Therefore it is always safe +to read one byte after seeing "eof" return "false". "eof" +will return "false" as long as buffered data is still available, +even if the remote end of a connection is closed. -Create an IOBuffer, which may optionally operate on a pre-existing -array. If the readable/writable arguments are given, they restrict -whether or not the buffer may be read from or written to -respectively. By default the buffer is readable but not writable. -The last argument optionally specifies a size beyond which the -buffer may not be grown. """ -IOBuffer +eof doc""" - takebuf_array(b::IOBuffer) + eps([type]) + +The distance between 1.0 and the next larger representable +floating-point value of "type". Only floating-point types are +sensible arguments. If "type" is omitted, then "eps(Float64)" +is returned. + + eps(x) + +The distance between "x" and the next larger representable +floating-point value of the same type as "x". -Obtain the contents of an "IOBuffer" as an array, without -copying. Afterwards, the IOBuffer is reset to its initial state. """ -takebuf_array +eps doc""" - takebuf_string(b::IOBuffer) + erf(x) + +Compute the error function of "x", defined by +\frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex +"x". -Obtain the contents of an "IOBuffer" as a string, without -copying. Afterwards, the IOBuffer is reset to its initial state. """ -takebuf_string +erf doc""" - fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + erfc(x) + +Compute the complementary error function of "x", defined by 1 - +\operatorname{erf}(x). -Create an "IOStream" object from an integer file descriptor. If -"own" is true, closing this object will close the underlying -descriptor. By default, an "IOStream" is closed when it is -garbage collected. "name" allows you to associate the descriptor -with a named file. """ -fdio +erfc doc""" - flush(stream) + erfcinv(x) + +Compute the inverse error complementary function of a real "x", +defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. -Commit all currently buffered writes to the given stream. """ -flush +erfcinv doc""" - close(stream) + erfcx(x) + +Compute the scaled complementary error function of "x", defined +by e^{x^2} \operatorname{erfc}(x). Note also that +\operatorname{erfcx}(-ix) computes the Faddeeva function w(x). -Close an I/O stream. Performs a "flush" first. """ -close +erfcx doc""" - write(stream, x) + erfi(x) + +Compute the imaginary error function of "x", defined by -i +\operatorname{erf}(ix). -Write the canonical binary representation of a value to the given -stream. """ -write +erfi doc""" - read(stream, type) + erfinv(x) + +Compute the inverse error function of a real "x", defined by +\operatorname{erf}(\operatorname{erfinv}(x)) = x. -Read a value of the given type from a stream, in canonical binary -representation. """ -read +erfinv doc""" - read(stream, type, dims) + error(message::AbstractString) + +Raise an "ErrorException" with the given message -Read a series of values of the given type from a stream, in -canonical binary representation. "dims" is either a tuple or a -series of integer arguments specifying the size of "Array" to -return. """ -read +error doc""" - read!(stream, array::Array) + esc(e::ANY) + +Only valid in the context of an Expr returned from a macro. +Prevents the macro hygiene pass from turning embedded variables +into gensym variables. See the *Macros* section of the +Metaprogramming chapter of the manual for more details and +examples. -Read binary data from a stream, filling in the argument "array". """ -read! +esc doc""" - readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + escape_string(str::AbstractString) -> AbstractString + +General escaping of traditional C and Unicode escape sequences. See +"print_escaped()" for more general escaping. -Read at most "nb" bytes from the stream into "b", returning the -number of bytes read (increasing the size of "b" as needed). """ -readbytes! +escape_string doc""" - readbytes(stream, nb=typemax(Int)) + eta(x) + +Dirichlet eta function \eta(s) = +\sum^\infty_{n=1}(-)^{n-1}/n^{s}. -Read at most "nb" bytes from the stream, returning a -"Vector{UInt8}" of the bytes read. """ -readbytes +eta doc""" - position(s) + etree(A[, post]) + +Compute the elimination tree of a symmetric sparse matrix "A" +from "triu(A)" and, optionally, its post-ordering permutation. -Get the current position of a stream. """ -position +etree doc""" - seek(s, pos) + eval([m::Module], expr::Expr) + +Evaluate an expression in the given module and return the result. +Every module (except those defined with "baremodule") has its own +1-argument definition of "eval", which evaluates expressions in +that module. -Seek a stream to the given position. """ -seek +eval doc""" - seekstart(s) + evalfile(path::AbstractString) + +Load the file using "include", evaluate all expressions, and +return the value of the last one. -Seek a stream to its beginning. """ -seekstart +evalfile doc""" - seekend(s) + exit([code]) + +Quit (or control-D at the prompt). The default exit code is zero, +indicating that the processes completed successfully. -Seek a stream to its end. """ -seekend +exit doc""" - skip(s, offset) + exp(x) + +Compute e^x -Seek a stream relative to the current position. """ -skip +exp doc""" - mark(s) + exp10(x) -Add a mark at the current position of stream "s". Returns the -marked position. +Compute 10^x -See also "unmark()", "reset()", "ismarked()" """ -mark +exp10 doc""" - unmark(s) + exp2(x) -Remove a mark from stream "s". Returns "true" if the stream was -marked, "false" otherwise. +Compute 2^x -See also "mark()", "reset()", "ismarked()" """ -unmark +exp2 doc""" - reset(s) + expand(x) -Reset a stream "s" to a previously marked position, and remove -the mark. Returns the previously marked position. Throws an error -if the stream is not marked. +Takes the expression x and returns an equivalent expression in +lowered form -See also "mark()", "unmark()", "ismarked()" """ -reset +expand doc""" - ismarked(s) + expanduser(path::AbstractString) -> AbstractString -Returns true if stream "s" is marked. +On Unix systems, replace a tilde character at the start of a path +with the current user's home directory. -See also "mark()", "unmark()", "reset()" """ -ismarked +expanduser doc""" - eof(stream) -> Bool + expm(A) + +Matrix exponential. -Tests whether an I/O stream is at end-of-file. If the stream is not -yet exhausted, this function will block to wait for more data if -necessary, and then return "false". Therefore it is always safe -to read one byte after seeing "eof" return "false". "eof" -will return "false" as long as buffered data is still available, -even if the remote end of a connection is closed. """ -eof +expm doc""" - isreadonly(stream) -> Bool + expm1(x) + +Accurately compute e^x-1 -Determine whether a stream is read-only. """ -isreadonly +expm1 doc""" - isopen(stream) -> Bool + exponent(x) -> Int + +Get the exponent of a normalized floating-point number. -Determine whether a stream is open (i.e. has not been closed yet). -If the connection has been closed remotely (in case of e.g. a -socket), "isopen" will return "false" even though buffered data -may still be available. Use "eof" to check if necessary. """ -isopen +exponent doc""" - serialize(stream, value) + extrema(itr) + +Compute both the minimum and maximum element in a single pass, and +return them as a 2-tuple. -Write an arbitrary value to a stream in an opaque format, such that -it can be read back by "deserialize". The read-back value will be -as identical as possible to the original. In general, this process -will not work if the reading and writing are done by different -versions of Julia, or an instance of Julia with a different system -image. """ -serialize +extrema doc""" - deserialize(stream) + eye(n) + +n-by-n identity matrix + + eye(m, n) + +m-by-n identity matrix + + eye(A) + +Constructs an identity matrix of the same dimensions and type as +"A". -Read a value written by "serialize". """ -deserialize +eye doc""" - print_escaped(io, str::AbstractString, esc::AbstractString) + factor(n) -> Dict + +Compute the prime factorization of an integer "n". Returns a +dictionary. The keys of the dictionary correspond to the factors, +and hence are of the same type as "n". The value associated with +each key indicates the number of times the factor appears in the +factorization. + + julia> factor(100) # == 2*2*5*5 + Dict{Int64,Int64} with 2 entries: + 2 => 2 + 5 => 2 -General escaping of traditional C and Unicode escape sequences, -plus any characters in esc are also escaped (with a backslash). """ -print_escaped +factor doc""" - print_unescaped(io, s::AbstractString) + factorial(n) + +Factorial of "n". If "n" is an "Integer", the factorial is +computed as an integer (promoted to at least 64 bits). Note that +this may overflow if "n" is not small, but you can use +"factorial(big(n))" to compute the result exactly in arbitrary +precision. If "n" is not an "Integer", "factorial(n)" is +equivalent to "gamma(n+1)". + + factorial(n, k) + +Compute "factorial(n)/factorial(k)" -General unescaping of traditional C and Unicode escape sequences. -Reverse of "print_escaped()". """ -print_unescaped +factorial doc""" - print_joined(io, items, delim[, last]) + factorize(A) + +Compute a convenient factorization (including LU, Cholesky, Bunch- +Kaufman, LowerTriangular, UpperTriangular) of A, based upon the +type of the input matrix. The return value can then be reused for +efficient solving of multiple systems. For example: +"A=factorize(A); x=A\\b; y=A\\C". -Print elements of "items" to "io" with "delim" between them. -If "last" is specified, it is used as the final delimiter instead -of "delim". """ -print_joined +factorize doc""" - print_shortest(io, x) + falses(dims) + +Create a "BitArray" with all values set to false -Print the shortest possible representation, with the minimum number -of consecutive non-zero digits, of number "x", ensuring that it -would parse to the exact same number. """ -print_shortest +falses doc""" fd(stream) @@ -6404,8217 +6701,8667 @@ doc""" Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. + """ fd doc""" - redirect_stdout() + fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream + +Create an "IOStream" object from an integer file descriptor. If +"own" is true, closing this object will close the underlying +descriptor. By default, an "IOStream" is closed when it is +garbage collected. "name" allows you to associate the descriptor +with a named file. -Create a pipe to which all C and Julia level STDOUT output will be -redirected. Returns a tuple (rd,wr) representing the pipe ends. -Data written to STDOUT may now be read from the rd end of the pipe. -The wr end is given for convenience in case the old STDOUT object -was cached by the user and needs to be replaced elsewhere. """ -redirect_stdout +fdio doc""" - redirect_stdout(stream) + fetch(RemoteRef) + +Wait for and get the value of a remote reference. -Replace STDOUT by stream for all C and julia level output to -STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. """ -redirect_stdout +fetch doc""" - redirect_stderr([stream]) + fft(A[, dims]) + +Performs a multidimensional FFT of the array "A". The optional +"dims" argument specifies an iterable subset of dimensions (e.g. +an integer, range, tuple, or array) to transform along. Most +efficient if the size of "A" along the transformed dimensions is +a product of small primes; see "nextprod()". See also +"plan_fft()" for even greater efficiency. + +A one-dimensional FFT computes the one-dimensional discrete Fourier +transform (DFT) as defined by + + \operatorname{DFT}(A)[k] = + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(-i\frac{2\pi + (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. + +A multidimensional FFT simply performs this operation along each +transformed dimension of "A". + +Higher performance is usually possible with multi-threading. Use +*FFTW.set_num_threads(np)* to use *np* threads, if you have *np* +processors. -Like redirect_stdout, but for STDERR """ -redirect_stderr +fft doc""" - redirect_stdin([stream]) + fft!(A[, dims]) + +Same as "fft()", but operates in-place on "A", which must be an +array of complex floating-point numbers. -Like redirect_stdout, but for STDIN. Note that the order of the -return tuple is still (rd,wr), i.e. data to be read from STDIN, may -be written to wr. """ -redirect_stdin +fft! doc""" - readchomp(x) + fftshift(x) + +Swap the first and second halves of each dimension of "x". + + fftshift(x, dim) + +Swap the first and second halves of the given dimension of array +"x". -Read the entirety of x as a string but remove trailing newlines. -Equivalent to chomp(readall(x)). """ -readchomp +fftshift doc""" - truncate(file, n) + fieldnames(x::DataType) + +Get an array of the fields of a data type. -Resize the file or buffer given by the first argument to exactly -*n* bytes, filling previously unallocated space with '\0' if the -file or buffer is grown """ -truncate +fieldnames doc""" - skipchars(stream, predicate; linecomment::Char) + fieldoffsets(type) + +The byte offset of each field of a type relative to the data start. +For example, we could use it in the following manner to summarize +information about a struct type: + + julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; + + julia> structinfo(StatStruct) + 12-element Array{Tuple{Int64,Symbol,DataType},1}: + (0,:device,UInt64) + (8,:inode,UInt64) + (16,:mode,UInt64) + (24,:nlink,Int64) + (32,:uid,UInt64) + (40,:gid,UInt64) + (48,:rdev,UInt64) + (56,:size,Int64) + (64,:blksize,Int64) + (72,:blocks,Int64) + (80,:mtime,Float64) + (88,:ctime,Float64) -Advance the stream until before the first character for which -"predicate" returns false. For example "skipchars(stream, -isspace)" will skip all whitespace. If keyword argument -"linecomment" is specified, characters from that character -through the end of a line will also be skipped. """ -skipchars +fieldoffsets doc""" - countlines(io[, eol::Char]) + fieldtype(type, name::Symbol | index::Int) + +Determine the declared type of a field (specified by name or index) +in a composite type. -Read io until the end of the stream/file and count the number of -non-empty lines. To specify a file pass the filename as the first -argument. EOL markers other than '\n' are supported by passing -them as the second argument. """ -countlines +fieldtype doc""" - PipeBuffer() + filemode(file) + +Equivalent to stat(file).mode -An IOBuffer that allows reading and performs writes by appending. -Seeking and truncating are not supported. See IOBuffer for the -available constructors. """ -PipeBuffer +filemode doc""" - PipeBuffer(data::Vector{UInt8}[, maxsize]) + filesize(path...) + +Equivalent to stat(file).size + +""" +filesize + +doc""" + fill(x, dims) + +Create an array filled with the value "x". For example, +"fill(1.0, (10,10))" returns a 10x10 array of floats, with each +element initialized to 1.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 evaluating "Foo()" once. -Create a PipeBuffer to operate on a data vector, optionally -specifying a size beyond which the underlying Array may not be -grown. """ -PipeBuffer +fill doc""" - readavailable(stream) + fill!(A, x) + +Fill array "A" with the value "x". If "x" is an object +reference, all elements will refer to the same object. "fill!(A, +Foo())" will return "A" filled with the result of evaluating +"Foo()" once. -Read all available data on the stream, blocking the task only if no -data is available. The result is a "Vector{UInt8,1}". """ -readavailable +fill! doc""" - show(x) + filt(b, a, x[, si]) + +Apply filter described by vectors "a" and "b" to vector "x", +with an optional initial filter state vector "si" (defaults to +zeros). -Write an informative text representation of a value to the current -output stream. New types should overload "show(io, x)" where the -first argument is a stream. The representation used by "show" -generally includes Julia-specific formatting and type information. """ -show +filt doc""" - showcompact(x) + filt!(out, b, a, x[, si]) + +Same as "filt()" but writes the result into the "out" argument, +which may alias the input "x" to modify it in-place. -Show a more compact representation of a value. This is used for -printing array elements. If a new type has a different compact -representation, it should overload "showcompact(io, x)" where the -first argument is a stream. """ -showcompact +filt! doc""" - showall(x) + 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). -Similar to "show", except shows all elements of arrays. """ -showall +filter doc""" - summary(x) + filter!(function, collection) + +Update "collection", removing elements for which "function" is +false. For associative collections, the function is passed two +arguments (key and value). -Return a string giving a brief description of a value. By default -returns "string(typeof(x))". For arrays, returns strings like -"2x2 Float64 Array". """ -summary +filter! doc""" - print(x) + finalize(x) + +Immediately run finalizers registered for object "x". -Write (to the default output stream) a canonical (un-decorated) -text representation of a value if there is one, otherwise call -"show". The representation used by "print" includes minimal -formatting and tries to avoid Julia-specific details. """ -print +finalize doc""" - println(x) + finalizer(x, function) + +Register a function "f(x)" to be called when there are no +program-accessible references to "x". The behavior of this +function is unpredictable if "x" is of a bits type. -Print (using "print()") "x" followed by a newline. """ -println +finalizer doc""" - print_with_color(color::Symbol[, io], strings...) + find(A) -Print strings in a color specified as a symbol, for example -":red" or ":blue". -""" -print_with_color +Return a vector of the linear indexes of the non-zeros in "A" +(determined by "A[i]!=0"). A common use of this is to convert a +boolean array to an array of indexes of the "true" elements. -doc""" - info(msg) + find(f, A) + +Return a vector of the linear indexes of "A" where "f" returns +true. -Display an informational message. """ -info +find doc""" - warn(msg) + findfirst(A) -Display a warning. -""" -warn +Return the index of the first non-zero value in "A" (determined +by "A[i]!=0"). -doc""" - @printf([io::IOStream], "%Fmt", args...) + findfirst(A, v) -Print arg(s) using C "printf()" style format specification -string. Optionally, an IOStream may be passed as the first argument -to redirect output. -""" -@printf +Return the index of the first element equal to "v" in "A". -doc""" - @sprintf("%Fmt", args...) + findfirst(predicate, A) + +Return the index of the first element of "A" for which +"predicate" returns true. -Return "@printf" formatted output as string. """ -@sprintf +findfirst doc""" - sprint(f::Function, args...) + findin(a, b) + +Returns the indices of elements in collection "a" that appear in +collection "b" -Call the given function with an I/O stream and the supplied extra -arguments. Everything written to this I/O stream is returned as a -string. """ -sprint +findin doc""" - showerror(io, e) + findlast(A) -Show a descriptive representation of an exception object. -""" -showerror +Return the index of the last non-zero value in "A" (determined by +"A[i]!=0"). -doc""" - dump(x) + findlast(A, v) -Show all user-visible structure of a value. -""" -dump +Return the index of the last element equal to "v" in "A". -doc""" - xdump(x) + findlast(predicate, A) + +Return the index of the last element of "A" for which +"predicate" returns true. -Show all structure of a value, including all fields of objects. """ -xdump +findlast doc""" - readall(stream::IO) + findmax(itr) -> (x, index) -Read the entire contents of an I/O stream as a string. -""" -readall +Returns the maximum element and its index. -doc""" - readall(filename::AbstractString) + findmax(A, dims) -> (maxval, index) + +For an array input, returns the value and index of the maximum over +the given dimensions. -Open "filename", read the entire contents as a string, then close -the file. Equivalent to "open(readall, filename)". """ -readall +findmax doc""" - readline(stream=STDIN) + findmin(itr) -> (x, index) -Read a single line of text, including a trailing newline character -(if one is reached before the end of the input), from the given -"stream" (defaults to "STDIN"), -""" -readline +Returns the minimum element and its index. -doc""" - readuntil(stream, delim) + findmin(A, dims) -> (minval, index) + +For an array input, returns the value and index of the minimum over +the given dimensions. -Read a string, up to and including the given delimiter byte. """ -readuntil +findmin doc""" - readlines(stream) + findn(A) + +Return a vector of indexes for each dimension giving the locations +of the non-zeros in "A" (determined by "A[i]!=0"). -Read all lines as an array. """ -readlines +findn doc""" - eachline(stream) + findnext(A, i) -Create an iterable object that will yield each line from a stream. -""" -eachline +Find the next index >= "i" of a non-zero element of "A", or +"0" if not found. -doc""" - readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + findnext(predicate, A, i) -Read a matrix from the source where each line (separated by -"eol") gives one row, with elements separated by the given -delimeter. The source can be a text file, stream or byte array. -Memory mapped files can be used by passing the byte array -representation of the mapped segment as source. +Find the next index >= "i" of an element of "A" for which +"predicate" returns true, or "0" if not found. -If "T" is a numeric type, the result is an array of that type, -with any non-numeric elements as "NaN" for floating-point types, -or zero. Other useful values of "T" include "ASCIIString", -"AbstractString", and "Any". + findnext(A, v, i) -If "header" is "true", the first row of data will be read as -header and the tuple "(data_cells, header_cells)" is returned -instead of only "data_cells". +Find the next index >= "i" of an element of "A" equal to "v" +(using "=="), or "0" if not found. -Specifying "skipstart" will ignore the corresponding number of -initial lines from the input. +""" +findnext -If "skipblanks" is "true", blank lines in the input will be -ignored. +doc""" + findnz(A) -If "use_mmap" is "true", the file specified by "source" is -memory mapped for potential speedups. Default is "true" except on -Windows. On Windows, you may want to specify "true" if the file -is large, and is only read once and not written to. +Return a tuple "(I, J, V)" where "I" and "J" are the row and +column indexes of the non-zero values in matrix "A", and "V" is +a vector of the non-zero values. -If "ignore_invalid_chars" is "true", bytes in "source" with -invalid character encoding will be ignored. Otherwise an error is -thrown indicating the offending character position. +""" +findnz -If "quotes" is "true", column enclosed within double-quote (``) -characters are allowed to contain new lines and column delimiters. -Double-quote characters within a quoted field must be escaped with -another double-quote. +doc""" + findprev(A, i) + +Find the previous index <= "i" of a non-zero element of "A", or +0 if not found. + + findprev(predicate, A, i) + +Find the previous index <= "i" of an element of "A" for which +"predicate" returns true, or "0" if not found. -Specifying "dims" as a tuple of the expected rows and columns -(including header, if any) may speed up reading of large files. + findprev(A, v, i) + +Find the previous index <= "i" of an element of "A" equal to +"v" (using "=="), or "0" if not found. -If "comments" is "true", lines beginning with "comment_char" -and text following "comment_char" in any line are ignored. """ -readdlm +findprev doc""" - readdlm(source, delim::Char, eol::Char; options...) + first(coll) + +Get the first element of an iterable collection. Returns the start +point of a "Range" even if it is empty. -If all data is numeric, the result will be a numeric array. If some -elements cannot be parsed as numbers, a cell array of numbers and -strings is returned. """ -readdlm +first doc""" - readdlm(source, delim::Char, T::Type; options...) + fld(x, y) + +Largest integer less than or equal to "x/y". -The end of line delimiter is taken as "\n". """ -readdlm +fld doc""" - readdlm(source, delim::Char; options...) + fldmod(x, y) + +The floored quotient and modulus after division. Equivalent to +"(fld(x,y), mod(x,y))". -The end of line delimiter is taken as "\n". If all data is -numeric, the result will be a numeric array. If some elements -cannot be parsed as numbers, a cell array of numbers and strings is -returned. """ -readdlm +fldmod doc""" - readdlm(source, T::Type; options...) + flipbits!(B::BitArray{N}) -> BitArray{N} + +Performs a bitwise not operation on B. See *~ operator*. -The columns are assumed to be separated by one or more whitespaces. -The end of line delimiter is taken as "\n". """ -readdlm +flipbits! doc""" - readdlm(source; options...) + flipdim(A, d) + +Reverse "A" in dimension "d". -The columns are assumed to be separated by one or more whitespaces. -The end of line delimiter is taken as "\n". If all data is -numeric, the result will be a numeric array. If some elements -cannot be parsed as numbers, a cell array of numbers and strings is -returned. """ -readdlm +flipdim doc""" - writedlm(f, A, delim='\t') + flipsign(x, y) -Write "A" (a vector, matrix or an iterable collection of iterable -rows) as text to "f" (either a filename string or an "IO" -stream) using the given delimeter "delim" (which defaults to tab, -but can be any printable Julia object, typically a "Char" or -"AbstractString"). +Return "x" with its sign flipped if "y" is negative. For +example "abs(x) = flipsign(x,x)". -For example, two vectors "x" and "y" of the same length can be -written as two columns of tab-delimited text to "f" by either -"writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". """ -writedlm +flipsign doc""" - readcsv(source, [T::Type]; options...) + float(x) + +Convert a number, array, or string to a "FloatingPoint" data +type. For numeric data, the smallest suitable "FloatingPoint" +type is used. Converts strings to "Float64". -Equivalent to "readdlm" with "delim" set to comma. """ -readcsv +float doc""" - writecsv(filename, A) + floor([T], x[, digits[, base]]) + +"floor(x)" returns the nearest integral value of the same type as +"x" that is less than or equal to "x". + +"floor(T, x)" converts the result to type "T", throwing an +"InexactError" if the value is not representable. + +"digits" and "base" work as for "round()". -Equivalent to "writedlm" with "delim" set to comma. """ -writecsv +floor doc""" - Base64EncodePipe(ostream) + flush(stream) + +Commit all currently buffered writes to the given stream. -Returns a new write-only I/O stream, which converts any bytes -written to it into base64-encoded ASCII bytes written to -"ostream". Calling "close" on the "Base64Pipe" stream is -necessary to complete the encoding (but does not close -"ostream"). """ -Base64EncodePipe +flush doc""" - Base64DecodePipe(istream) + fma(x, y, z) + +Computes "x*y+z" without rounding the intermediate result +"x*y". On some systems this is significantly more expensive than +"x*y+z". "fma" is used to improve accuracy in certain +algorithms. See "muladd". -Returns a new read-only I/O stream, which decodes base64-encoded -data read from "istream". """ -Base64DecodePipe +fma doc""" - base64encode(writefunc, args...) -base64encode(args...) + foldl(op, v0, itr) + +Like "reduce()", but with guaranteed left associativity. "v0" +will be used exactly once. + + 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)"). -Given a "write"-like function "writefunc", which takes an I/O -stream as its first argument, "base64(writefunc, args...)" calls -"writefunc" to write "args..." to a base64-encoded string, and -returns the string. "base64(args...)" is equivalent to -"base64(write, args...)": it converts its arguments into bytes -using the standard "write" functions and returns the -base64-encoded string. """ -base64encode +foldl doc""" - base64decode(string) + foldr(op, v0, itr) + +Like "reduce()", but with guaranteed right associativity. "v0" +will be used exactly once. + + 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)"). -Decodes the base64-encoded "string" and returns a -"Vector{UInt8}" of the decoded bytes. """ -base64decode +foldr doc""" - display(x) -display(d::Display, x) -display(mime, x) -display(d::Display, mime, x) + frexp(val) -Display "x" using the topmost applicable display in the display -stack, typically using the richest supported multimedia output for -"x", with plain-text "STDOUT" output as a fallback. The -"display(d, x)" variant attempts to display "x" on the given -display "d" only, throwing a "MethodError" if "d" cannot -display objects of this type. +Return "(x,exp)" such that "x" has a magnitude in the interval +"[1/2, 1)" or 0, and val = x \times 2^{exp}. -There are also two variants with a "mime" argument (a MIME type -string, such as ""image/png""), which attempt to display "x" -using the requested MIME type *only*, throwing a "MethodError" if -this type is not supported by either the display(s) or by "x". -With these variants, one can also supply the "raw" data in the -requested MIME type by passing "x::AbstractString" (for MIME -types with text-based storage, such as text/html or -application/postscript) or "x::Vector{UInt8}" (for binary MIME -types). """ -display +frexp doc""" - redisplay(x) -redisplay(d::Display, x) -redisplay(mime, x) -redisplay(d::Display, mime, x) + full(S) + +Convert a sparse matrix "S" into a dense matrix. + + full(F) + +Reconstruct the matrix "A" from the factorization +"F=factorize(A)". + + full(QRCompactWYQ[, thin=true]) -> Matrix + +Converts an orthogonal or unitary matrix stored as a +"QRCompactWYQ" object, i.e. in the compact WY format +[Bischof1987], to a dense matrix. + +Optionally takes a "thin" Boolean argument, which if "true" +omits the columns that span the rows of "R" in the QR +factorization that are zero. The resulting matrix is the "Q" in a +thin QR factorization (sometimes called the reduced QR +factorization). If "false", returns a "Q" that spans all rows +of "R" in its corresponding QR factorization. -By default, the "redisplay" functions simply call "display". -However, some display backends may override "redisplay" to modify -an existing display of "x" (if any). Using "redisplay" is -also a hint to the backend that "x" may be redisplayed several -times, and the backend may choose to defer the display until (for -example) the next interactive prompt. """ -redisplay +full doc""" - displayable(mime) -> Bool -displayable(d::Display, mime) -> Bool + fullname(m::Module) + +Get the fully-qualified name of a module as a tuple of symbols. For +example, "fullname(Base.Pkg)" gives "(:Base,:Pkg)", and +"fullname(Main)" gives "()". -Returns a boolean value indicating whether the given "mime" type -(string) is displayable by any of the displays in the current -display stack, or specifically by the display "d" in the second -variant. """ -displayable +fullname doc""" - writemime(stream, mime, x) + function_module(f::Function, types) -> Module -The "display" functions ultimately call "writemime" in order to -write an object "x" as a given "mime" type to a given I/O -"stream" (usually a memory buffer), if possible. In order to -provide a rich multimedia representation of a user-defined type -"T", it is only necessary to define a new "writemime" method -for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", -where "mime" is a MIME-type string and the function body calls -"write" (or similar) to write that representation of "x" to -"stream". (Note that the "MIME\""" notation only supports -literal strings; to construct "MIME" types in a more flexible -manner use "MIME{symbol("")}".) +Determine the module containing a given definition of a generic +function. -For example, if you define a "MyImage" type and know how to write -it to a PNG file, you could define a function "writemime(stream, -::MIME"image/png", x::MyImage) = ...`" to allow your images to -be displayed on any PNG-capable "Display" (such as IJulia). As -usual, be sure to "import Base.writemime" in order to add new -methods to the built-in Julia function "writemime". +""" +function_module + +doc""" + function_name(f::Function) -> Symbol + +Get the name of a generic function as a symbol, or ":anonymous". -Technically, the "MIME"mime"" macro defines a singleton type -for the given "mime" string, which allows us to exploit Julia's -dispatch mechanisms in determining how to display objects of any -given type. """ -writemime +function_name doc""" - mimewritable(mime, x) + functionloc(f::Function, types) + +Returns a tuple "(filename,line)" giving the location of a method +definition. + + functionloc(m::Method) + +Returns a tuple "(filename,line)" giving the location of a method +definition. -Returns a boolean value indicating whether or not the object "x" -can be written as the given "mime" type. (By default, this is -determined automatically by the existence of the corresponding -"writemime" function for "typeof(x)".) """ -mimewritable +functionloc doc""" - reprmime(mime, x) + gamma(x) -Returns an "AbstractString" or "Vector{UInt8}" containing the -representation of "x" in the requested "mime" type, as written -by "writemime" (throwing a "MethodError" if no appropriate -"writemime" is available). An "AbstractString" is returned for -MIME types with textual representations (such as ""text/html"" -or ""application/postscript""), whereas binary data is returned -as "Vector{UInt8}". (The function "istext(mime)" returns -whether or not Julia treats a given "mime" type as text.) +Compute the gamma function of "x" -As a special case, if "x" is an "AbstractString" (for textual -MIME types) or a "Vector{UInt8}" (for binary MIME types), the -"reprmime" function assumes that "x" is already in the -requested "mime" format and simply returns "x". """ -reprmime +gamma doc""" - stringmime(mime, x) + gc() + +Perform garbage collection. This should not generally be used. -Returns an "AbstractString" containing the representation of -"x" in the requested "mime" type. This is similar to -"reprmime" except that binary data is base64-encoded as an ASCII -string. """ -stringmime +gc doc""" - pushdisplay(d::Display) + gc_enable(on::Bool) + +Control whether garbage collection is enabled using a boolean +argument (true for enabled, false for disabled). Returns previous +GC state. Disabling garbage collection should be used only with +extreme caution, as it can cause memory use to grow without bound. -Pushes a new display "d" on top of the global display-backend -stack. Calling "display(x)" or "display(mime, x)" will display -"x" on the topmost compatible backend in the stack (i.e., the -topmost backend that does not throw a "MethodError"). """ -pushdisplay +gc_enable doc""" - popdisplay() -popdisplay(d::Display) + gcd(x, y) + +Greatest common (positive) divisor (or zero if x and y are both +zero). -Pop the topmost backend off of the display-backend stack, or the -topmost copy of "d" in the second variant. """ -popdisplay +gcd doc""" - TextDisplay(stream) + gcdx(x, y) + +Computes the greatest common (positive) divisor of "x" and "y" +and their Bézout coefficients, i.e. the integer coefficients "u" +and "v" that satisfy ux+vy = d = gcd(x,y). + + julia> gcdx(12, 42) + (6,-3,1) + + julia> gcdx(240, 46) + (2,-9,47) + +Note: Bézout coefficients are *not* uniquely defined. "gcdx" + returns the minimal Bézout coefficients that are computed by the + extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, + Algorithm X.) These coefficients "u" and "v" are minimal in + the sense that |u| < |\frac y d and |v| < |\frac x d. + Furthermore, the signs of "u" and "v" are chosen so that + "d" is positive. -Returns a "TextDisplay <: Display", which can display any object -as the text/plain MIME type (only), writing the text representation -to the given I/O stream. (The text representation is the same as -the way an object is printed in the Julia REPL.) """ -TextDisplay +gcdx doc""" - istext(m::MIME) + gensym([tag]) + +Generates a symbol which will not conflict with other variable +names. -Determine whether a MIME type is text data. """ -istext +gensym doc""" - mmap_array(type, dims, stream[, offset]) + get(x) -Create an "Array" whose values are linked to a file, using -memory-mapping. This provides a convenient way of working with data -too large to fit in the computer's memory. +Attempt to access the value of the "Nullable" object, "x". +Returns the value if it is present; otherwise, throws a +"NullException". -The type determines how the bytes of the array are interpreted. -Note that the file must be stored in binary format, and no format -conversions are possible (this is a limitation of operating -systems, not Julia). + get(x, y) -"dims" is a tuple specifying the size of the array. +Attempt to access the value of the "Nullable{T}" object, "x". +Returns the value if it is present; otherwise, returns "convert(T, +y)". -The file is passed via the stream argument. When you initialize -the stream, use ""r"" for a "read-only" array, and ""w+"" -to create a new array used to write values to disk. + get(collection, key, default) -Optionally, you can specify an offset (in bytes) if, for example, -you want to skip over a header in the file. The default value for -the offset is the current stream position. +Return the value stored for the given key, or the given default +value if no mapping for the key is present. -For example, the following code: + get(f::Function, collection, key) - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open("/tmp/mmap.bin", "w+") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) +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. - # Test by reading it back in - s = open("/tmp/mmap.bin") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) +This is intended to be called using "do" block syntax: -creates a "m"-by-"n" "Matrix{Int}", linked to the file -associated with stream "s". + get(dict, key) do + # default value calculated here + time() + end -A more portable file would need to encode the word size---32 bit or -64 bit---and endianness information in the header. In practice, -consider encoding binary data using standard formats like HDF5 -(which can be used with memory-mapping). """ -mmap_array +get doc""" - mmap_bitarray([type], dims, stream[, offset]) - -Create a "BitArray" whose values are linked to a file, using -memory-mapping; it has the same purpose, works in the same way, and -has the same arguments, as "mmap_array()", but the byte -representation is different. The "type" parameter is optional, -and must be "Bool" if given. + get!(collection, key, default) -**Example**: "B = mmap_bitarray((25,30000), s)" +Return the value stored for the given key, or if no mapping for the +key is present, store "key => default", and return "default". -This would create a 25-by-30000 "BitArray", linked to the file -associated with stream "s". -""" -mmap_bitarray + get!(f::Function, collection, key) -doc""" - msync(array) +Return the value stored for the given key, or if no mapping for the +key is present, store "key => f()", and return "f()". -Forces synchronization between the in-memory version of a memory- -mapped "Array" or "BitArray" and the on-disk version. -""" -msync +This is intended to be called using "do" block syntax: -doc""" - connect([host], port) -> TcpSocket + get!(dict, key) do + # default value calculated here + time() + end -Connect to the host "host" on port "port" """ -connect +get! doc""" - connect(path) -> Pipe + get_bigfloat_precision() + +Get the precision (in bits) currently used for BigFloat arithmetic. -Connect to the Named Pipe/Domain Socket at "path" """ -connect +get_bigfloat_precision doc""" - listen([addr], port) -> TcpServer + get_rounding(T) -Listen on port on the address specified by "addr". By default -this listens on localhost only. To listen on all interfaces pass, -"IPv4(0)" or "IPv6(0)" as appropriate. -""" -listen +Get the current floating point rounding mode for type "T", +controlling the rounding of basic arithmetic functions ("+()", +"-()", "*()", "/()" and "sqrt()") and type conversion. -doc""" - listen(path) -> PipeServer +Valid modes are "RoundNearest", "RoundToZero", "RoundUp", +"RoundDown", and "RoundFromZero" ("BigFloat" only). -Listens on/Creates a Named Pipe/Domain Socket """ -listen +get_rounding doc""" getaddrinfo(host) Gets the IP address of the "host" (may have to do a DNS lookup) + """ getaddrinfo doc""" - parseip(addr) + getfield(value, name::Symbol) + +Extract a named field from a value of composite type. The syntax +"a.b" calls "getfield(a, :b)", and the syntax "a.(b)" calls +"getfield(a, b)". -Parse a string specifying an IPv4 or IPv6 ip address. """ -parseip +getfield doc""" - IPv4(host::Integer) -> IPv4 + gethostname() -> AbstractString + +Get the local machine's host name. -Returns IPv4 object from ip address formatted as Integer """ -IPv4 +gethostname doc""" - IPv6(host::Integer) -> IPv6 + getindex(type[, elements...]) -Returns IPv6 object from ip address formatted as Integer -""" -IPv6 +Construct a 1-d array of the specified type. This is usually called +with the syntax "Type[]". Element values can be specified using +"Type[a,b,c,...]". -doc""" - nb_available(stream) + getindex(A, inds...) -Returns the number of bytes available for reading before a read -from this stream or buffer will block. -""" -nb_available +Returns a subset of array "A" as specified by "inds", where +each "ind" may be an "Int", a "Range", or a "Vector". See +the manual section on *array indexing* for details. -doc""" - accept(server[, client]) + 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, ...)". -Accepts a connection on the given server and returns a connection -to the client. An uninitialized client stream may be provided, in -which case it will be used instead of creating a new stream. """ -accept +getindex doc""" - listenany(port_hint) -> (UInt16, TcpServer) + getipaddr() -> AbstractString + +Get the IP address of the local machine, as a string of the form +"x.x.x.x". -Create a TcpServer on any port, using hint as a starting point. -Returns a tuple of the actual port that the server was created on -and the server itself. """ -listenany +getipaddr doc""" - watch_file(cb=false, s; poll=false) + getkey(collection, key, default) + +Return the key matching argument "key" if one exists in +"collection", otherwise return "default". -Watch file or directory "s" and run callback "cb" when "s" is -modified. The "poll" parameter specifies whether to use file -system event monitoring or polling. The callback function "cb" -should accept 3 arguments: "(filename, events, status)" where -"filename" is the name of file that was modified, "events" is -an object with boolean fields "changed" and "renamed" when -using file system event monitoring, or "readable" and -"writable" when using polling, and "status" is always 0. Pass -"false" for "cb" to not use a callback function. """ -watch_file +getkey doc""" - poll_fd(fd, seconds::Real; readable=false, writable=false) + getpid() -> Int32 + +Get julia's process ID. -Poll a file descriptor fd for changes in the read or write -availability and with a timeout given by the second argument. If -the timeout is not needed, use "wait(fd)" instead. The keyword -arguments determine which of read and/or write status should be -monitored and at least one of them needs to be set to true. The -returned value is an object with boolean fields "readable", -"writable", and "timedout", giving the result of the polling. """ -poll_fd +getpid doc""" - poll_file(s, interval_seconds::Real, seconds::Real) + gperm(file) + +Like uperm but gets the permissions of the group owning the file -Monitor a file for changes by polling every *interval_seconds* -seconds for *seconds* seconds. A return value of true indicates the -file changed, a return value of false indicates a timeout. """ -poll_file +gperm doc""" - bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + gradient(F[, h]) + +Compute differences along vector "F", using "h" as the spacing +between points. The default spacing is one. -Bind "socket" to the given "host:port". Note that *0.0.0.0* -will listen on all devices. """ -bind +gradient doc""" - send(socket::UDPSocket, host::IPv4, port::Integer, msg) + graphemes(s) -> iterator over substrings of s + +Returns an iterator over substrings of "s" that correspond to the +extended graphemes in the string, as defined by Unicode UAX #29. +(Roughly, these are what users would perceive as single characters, +even though they may contain more than one codepoint; for example a +letter combined with an accent mark is a single grapheme.) -Send "msg" over "socket to ``host:port". """ -send +graphemes doc""" - recv(socket::UDPSocket) + hankelh1(nu, x) + +Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). -Read a UDP packet from the specified socket, and return the bytes -received. This call blocks. """ -recv +hankelh1 doc""" - recvfrom(socket::UDPSocket) -> (address, data) + hankelh1x(nu, x) + +Scaled Bessel function of the third kind of order "nu", +H^{(1)}_\nu(x) e^{-x i}. -Read a UDP packet from the specified socket, returning a tuple of -(address, data), where address will be either IPv4 or IPv6 as -appropriate. """ -recvfrom +hankelh1x doc""" - setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + hankelh2(nu, x) + +Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). -Set UDP socket options. "multicast_loop": loopback for multicast -packets (default: true). "multicast_ttl": TTL for multicast -packets. "enable_broadcast": flag must be set to true if socket -will be used for broadcast messages, or else the UDP system will -return an access error (default: false). "ttl": Time-to-live of -packets sent on the socket. """ -setopt +hankelh2 doc""" - ntoh(x) + hankelh2x(nu, x) + +Scaled Bessel function of the third kind of order "nu", +H^{(2)}_\nu(x) e^{x i}. -Converts the endianness of a value from Network byte order (big- -endian) to that used by the Host. """ -ntoh +hankelh2x doc""" - hton(x) + hash(x[, h]) -Converts the endianness of a value from that used by the Host to -Network byte order (big-endian). -""" -hton +Compute an integer hash code such that "isequal(x,y)" implies +"hash(x)==hash(y)". The optional second argument "h" is a hash +code to be mixed with the result. -doc""" - ltoh(x) +New types should implement the 2-argument form, typically by +calling the 2-argument "hash" method recursively in order to mix +hashes of the contents with each other (and with "h"). +Typically, any type that implements "hash" should also implement +its own "==" (hence "isequal") to guarantee the property +mentioned above. -Converts the endianness of a value from Little-endian to that used -by the Host. """ -ltoh +hash doc""" - htol(x) + haskey(collection, key) -> Bool + +Determine whether a collection has a mapping for a given key. -Converts the endianness of a value from that used by the Host to -Little-endian. """ -htol +haskey doc""" - ENDIAN_BOM + hcat(A...) + +Concatenate along dimension 2 -The 32-bit byte-order-mark indicates the native byte order of the -host machine. Little-endian machines will contain the value -0x04030201. Big-endian machines will contain the value 0x01020304. """ -ENDIAN_BOM +hcat doc""" - malloc(size::Integer) -> Ptr{Void} + hessfact(A) + +Compute the Hessenberg decomposition of "A" and return a +"Hessenberg" object. If "F" is the factorization object, the +unitary matrix can be accessed with "F[:Q]" and the Hessenberg +matrix with "F[:H]". When "Q" is extracted, the resulting type +is the "HessenbergQ" object, and may be converted to a regular +matrix with "full()". -Call "malloc" from the C standard library. """ -Libc.malloc +hessfact doc""" - calloc(num::Integer, size::Integer) -> Ptr{Void} + hessfact!(A) + +"hessfact!" is the same as "hessfact()", but saves space by +overwriting the input A, instead of creating a copy. -Call "calloc" from the C standard library. """ -Libc.calloc +hessfact! doc""" - realloc(addr::Ptr, size::Integer) -> Ptr{Void} + hex(n[, pad]) -Call "realloc" from the C standard library. +Convert an integer to a hexadecimal string, optionally specifying a +number of digits to pad to. -See warning in the documentation for "free" regarding only using -this on memory originally obtained from "malloc". """ -Libc.realloc +hex doc""" - free(addr::Ptr) + hex2bytes(s::ASCIIString) + +Convert an arbitrarily long hexadecimal string to its binary +representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. -Call "free" from the C standard library. Only use this on memory -obtained from "malloc", not on pointers retrieved from other C -libraries. "Ptr" objects obtained from C libraries should be -freed by the free functions defined in that library, to avoid -assertion failures if multiple "libc" libraries exist on the -system. """ -Libc.free +hex2bytes doc""" - errno([code]) + hex2num(str) -Get the value of the C library's "errno". If an argument is -specified, it is used to set the value of "errno". +Convert a hexadecimal string to the floating point number it +represents -The value of "errno" is only valid immediately after a "ccall" -to a C library routine that sets it. Specifically, you cannot call -"errno" at the next prompt in a REPL, because lots of code is -executed between prompts. """ -Libc.errno +hex2num doc""" - strerror(n) + hist(v[, n]) -> e, counts -Convert a system call error code to a descriptive string -""" -Libc.strerror +Compute the histogram of "v", optionally using approximately +"n" bins. The return values are a range "e", which correspond +to the edges of the bins, and "counts" containing the number of +elements of "v" in each bin. Note: Julia does not ignore "NaN" +values in the computation. -doc""" - time(t::TmStruct) + hist(v, e) -> e, counts + +Compute the histogram of "v" using a vector/range "e" as the +edges for the bins. The result will be a vector of length +"length(e) - 1", such that the element at location "i" +satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not +ignore "NaN" values in the computation. -Converts a "TmStruct" struct to a number of seconds since the -epoch. """ -Libc.time +hist doc""" - strftime([format], time) + hist!(counts, v, e) -> e, counts + +Compute the histogram of "v", using a vector/range "e" as the +edges for the bins. This function writes the resultant counts to a +pre-allocated array "counts". -Convert time, given as a number of seconds since the epoch or a -"TmStruct", to a formatted string using the given format. -Supported formats are the same as those in the standard C library. """ -Libc.strftime +hist! doc""" - strptime([format], timestr) + hist2d(M, e1, e2) -> (edge1, edge2, counts) + +Compute a "2d histogram" of a set of N points specified by N-by-2 +matrix "M". Arguments "e1" and "e2" are bins for each +dimension, specified either as integer bin counts or vectors of bin +edges. The result is a tuple of "edge1" (the bin edges used in +the first dimension), "edge2" (the bin edges used in the second +dimension), and "counts", a histogram matrix of size +"(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore +"NaN" values in the computation. -Parse a formatted time string into a "TmStruct" giving the -seconds, minute, hour, date, etc. Supported formats are the same as -those in the standard C library. On some platforms, timezones will -not be parsed correctly. If the result of this function will be -passed to "time" to convert it to seconds since the epoch, the -"isdst" field should be filled in manually. Setting it to "-1" -will tell the C library to use the current system settings to -determine the timezone. """ -Libc.strptime +hist2d doc""" - TmStruct([seconds]) + hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + +Compute a "2d histogram" with respect to the bins delimited by +the edges given in "e1" and "e2". This function writes the +results to a pre-allocated array "counts". -Convert a number of seconds since the epoch to broken-down format, -with fields "sec", "min", "hour", "mday", "month", -"year", "wday", "yday", and "isdst". """ -Libc.TmStruct +hist2d! doc""" - flush_cstdio() + histrange(v, n) + +Compute *nice* bin ranges for the edges of a histogram of "v", +using approximately "n" bins. The resulting step sizes will be 1, +2 or 5 multiplied by a power of 10. Note: Julia does not ignore +"NaN" values in the computation. -Flushes the C "stdout" and "stderr" streams (which may have -been written to by external C code). """ -Libc.flush_cstdio +histrange doc""" - msync(ptr, len[, flags]) + homedir() -> AbstractString -Forces synchronization of the "mmap()"ped memory region from -"ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a -combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See -your platform man page for specifics. The flags argument is not -valid on Windows. +Return the current user's home directory. -You may not need to call "msync", because synchronization is -performed at intervals automatically by the operating system. -However, you can call this directly if, for example, you are -concerned about losing the result of a long-running calculation. """ -Libc.msync +homedir doc""" - MS_ASYNC + htol(x) + +Converts the endianness of a value from that used by the Host to +Little-endian. -Enum constant for "msync()". See your platform man page for -details. (not available on Windows). """ -Libc.MS_ASYNC +htol doc""" - MS_SYNC + hton(x) + +Converts the endianness of a value from that used by the Host to +Network byte order (big-endian). -Enum constant for "msync()". See your platform man page for -details. (not available on Windows). """ -Libc.MS_SYNC +hton doc""" - MS_INVALIDATE + hvcat(rows::Tuple{Vararg{Int}}, values...) -Enum constant for "msync()". See your platform man page for -details. (not available on Windows). -""" -Libc.MS_INVALIDATE +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. For example, +"[a b;c d e]" calls "hvcat((2,3),a,b,c,d,e)". -doc""" - mmap(len, prot, flags, fd, offset) +If the first argument is a single integer "n", then all block +rows are assumed to have "n" block columns. -Low-level interface to the "mmap" system call. See the man page. """ -Libc.mmap +hvcat doc""" - munmap(pointer, len) + hypot(x, y) + +Compute the \sqrt{x^2+y^2} avoiding overflow and underflow -Low-level interface for unmapping memory (see the man page). With -"mmap_array()" you do not need to call this directly; the memory -is unmapped for you when the array goes out of scope. """ -Libc.munmap +hypot doc""" - dlopen(libfile::AbstractString[, flags::Integer]) + idct(A[, dims]) -Load a shared library, returning an opaque handle. +Computes the multidimensional inverse discrete cosine transform +(DCT) of the array "A" (technically, a type-III DCT with the +unitary normalization). The optional "dims" argument specifies an +iterable subset of dimensions (e.g. an integer, range, tuple, or +array) to transform along. Most efficient if the size of "A" +along the transformed dimensions is a product of small primes; see +"nextprod()". See also "plan_idct()" for even greater +efficiency. -The optional flags argument is a bitwise-or of zero or more of -"RTLD_LOCAL", "RTLD_GLOBAL", "RTLD_LAZY", "RTLD_NOW", -"RTLD_NODELETE", "RTLD_NOLOAD", "RTLD_DEEPBIND", and -"RTLD_FIRST". These are converted to the corresponding flags of -the POSIX (and/or GNU libc and/or MacOS) dlopen command, if -possible, or are ignored if the specified functionality is not -available on the current platform. The default is -"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL". An important usage of -these flags, on POSIX platforms, is to specify -"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL" in order for the library's -symbols to be available for usage in other shared libraries, in -situations where there are dependencies between shared libraries. """ -Libdl.dlopen +idct doc""" - dlopen_e(libfile::AbstractString[, flags::Integer]) + idct!(A[, dims]) + +Same as "idct!()", but operates in-place on "A". -Similar to "dlopen()", except returns a "NULL" pointer instead -of raising errors. """ -Libdl.dlopen_e +idct! doc""" - RTLD_DEEPBIND + identity(x) + +The identity function. Returns its argument. -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_DEEPBIND +identity doc""" - RTLD_FIRST + ifelse(condition::Bool, x, y) + +Return "x" if "condition" is true, otherwise return "y". This +differs from "?" or "if" in that it is an ordinary function, so +all the arguments are evaluated first. In some cases, using +"ifelse" instead of an "if" statement can eliminate the branch +in generated code and provide higher performance in tight loops. -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_FIRST +ifelse doc""" - RTLD_GLOBAL + ifft(A[, dims]) + +Multidimensional inverse FFT. + +A one-dimensional inverse FFT computes + + \operatorname{IDFT}(A)[k] = + \frac{1}{\operatorname{length}(A)} + \sum_{n=1}^{\operatorname{length}(A)} + \exp\left(+i\frac{2\pi (n-1)(k-1)} + {\operatorname{length}(A)} \right) A[n]. + +A multidimensional inverse FFT simply performs this operation along +each transformed dimension of "A". -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_GLOBAL +ifft doc""" - RTLD_LAZY + ifft!(A[, dims]) + +Same as "ifft()", but operates in-place on "A". -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_LAZY +ifft! doc""" - RTLD_LOCAL + ifftshift(x[, dim]) + +Undoes the effect of "fftshift". -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_LOCAL +ifftshift doc""" - RTLD_NODELETE + ignorestatus(command) + +Mark a command object so that running it will not throw an error if +the result code is non-zero. -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_NODELETE +ignorestatus doc""" - RTLD_NOLOAD + im + +The imaginary unit -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_NOLOAD +im doc""" - RTLD_NOW + imag(z) + +Return the imaginary part of the complex number "z" -Enum constant for "dlopen()". See your platform man page for -details, if applicable. """ -Libdl.RTLD_NOW +imag doc""" - dlsym(handle, sym) + include(path::AbstractString) + +Evaluate the contents of a source file in the current context. +During including, a task-local include path is set to the directory +containing the file. Nested calls to "include" will search +relative to that path. All paths refer to files on node 1 when +running in parallel, and files will be fetched from node 1. This +function is typically used to load source interactively, or to +combine files in packages that are broken into multiple source +files. -Look up a symbol from a shared library handle, return callable -function pointer on success. """ -Libdl.dlsym +include doc""" - dlsym_e(handle, sym) + include_string(code::AbstractString) + +Like "include", except reads code from the given string rather +than from a file. Since there is no file path involved, no path +processing or fetching from node 1 is done. -Look up a symbol from a shared library handle, silently return NULL -pointer on lookup failure. """ -Libdl.dlsym_e +include_string doc""" - dlclose(handle) + ind2chr(string, i) + +Convert a byte index to a character index -Close shared library referenced by handle. """ -Libdl.dlclose +ind2chr doc""" - find_library(names, locations) + ind2sub(dims, index) -> subscripts + +Returns a tuple of subscripts into an array with dimensions +"dims", corresponding to the linear index "index" + +**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 index "index" -Searches for the first library in "names" in the paths in the -"locations" list, "DL_LOAD_PATH", or system library paths (in -that order) which can successfully be dlopen'd. On success, the -return value will be one of the names (potentially prefixed by one -of the paths in locations). This string can be assigned to a -"global const" and used as the library name in future -"ccall"'s. On failure, it returns the empty string. """ -Libdl.find_library +ind2sub + +doc""" + indexin(a, b) -doc""" - DL_LOAD_PATH +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". -When calling "dlopen", the paths in this list will be searched -first, in order, before searching the system locations for a valid -library handle. """ -Libdl.DL_LOAD_PATH +indexin doc""" - *(A, B) + indexpids(S::SharedArray) + +Returns the index of the current worker into the "pids" vector, +i.e., the list of workers mapping the SharedArray -Matrix multiplication """ -Base.(:(*)) +indexpids doc""" - \(A, B) + indmax(itr) -> Integer -Matrix division using a polyalgorithm. For input matrices "A" and -"B", the result "X" is such that "A*X == B" when "A" is -square. The solver that is used depends upon the structure of -"A". A direct solver is used for upper- or lower triangular -"A". For Hermitian "A" (equivalent to symmetric "A" for non- -complex "A") the "BunchKaufman" factorization is used. -Otherwise an LU factorization is used. For rectangular "A" the -result is the minimum-norm least squares solution computed by a -pivoted QR factorization of "A" and a rank estimate of A based on -the R factor. +Returns the index of the maximum element in a collection. -When "A" is sparse, a similar polyalgorithm is used. For -indefinite matrices, the LDLt factorization does not use pivoting -during the numerical factorization and therefore the procedure can -fail even for invertible matrices. """ -Base.(:(\)) +indmax doc""" - dot(x, y) -⋅(x, y) + indmin(itr) -> Integer + +Returns the index of the minimum element in a collection. -Compute the dot product. For complex vectors, the first vector is -conjugated. """ -dot +indmin doc""" - vecdot(x, y) + inf(f) + +Returns positive infinity of the floating point type "f" or of +the same floating point type as "f" -For any iterable containers "x" and "y" (including arrays of -any dimension) of numbers (or any element type for which "dot" is -defined), compute the Euclidean dot product (the sum of -"dot(x[i],y[i])") as if they were vectors. """ -vecdot +inf doc""" - cross(x, y) -×(x, y) + info(msg) + +Display an informational message. -Compute the cross product of two 3-vectors. """ -cross +info doc""" - factorize(A) + init_worker(manager::FooManager) + +Called by cluster managers implementing custom transports. It +initializes a newly launched process as a worker. Command line +argument "--worker" has the effect of initializing a process as a +worker using TCP/IP sockets for transport. -Compute a convenient factorization (including LU, Cholesky, Bunch- -Kaufman, LowerTriangular, UpperTriangular) of A, based upon the -type of the input matrix. The return value can then be reused for -efficient solving of multiple systems. For example: -"A=factorize(A); x=A\\b; y=A\\C". """ -factorize +init_worker doc""" - full(F) + insert!(collection, index, item) + +Insert an "item" into "collection" at the given "index". +"index" is the index of "item" in the resulting "collection". + + julia> insert!([6, 5, 4, 2, 1], 4, 3) + 6-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 -Reconstruct the matrix "A" from the factorization -"F=factorize(A)". """ -full +insert! doc""" - lu(A) -> L, U, p + instances(T::Type) + +Return a collection of all instances of the given type, if +applicable. Mostly used for enumerated types (see "@enum"). -Compute the LU factorization of "A", such that "A[p,:] = L*U". """ -lu +instances doc""" - lufact(A[, pivot=Val{true}]) -> F + interrupt([pids...]) -Compute the LU factorization of "A". The return type of "F" -depends on the type of "A". In most cases, if "A" is a subtype -"S" of AbstractMatrix with an element type "T`" supporting -"+", "-", "*" and "/" the return type is "LU{T,S{T}}". If -pivoting is chosen (default) the element type should also support -"abs" and "<". When "A" is sparse and have element of type -"Float32", "Float64", "Complex{Float32}", or -"Complex{Float64}" the return type is "UmfpackLU". Some -examples are shown in the table below. +Interrupt the current executing task on the specified workers. This +is equivalent to pressing Ctrl-C on the local machine. If no +arguments are given, all workers are interrupted. - +-------------------------+---------------------------+----------------------------------------------+ - | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | - +-------------------------+---------------------------+----------------------------------------------+ - | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | - +-------------------------+---------------------------+----------------------------------------------+ +""" +interrupt -The individual components of the factorization "F" can be -accessed by indexing: +doc""" + intersect(s1, s2...) +∩(s1, s2) - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ +Construct the intersection of two or more sets. Maintains order and +multiplicity of the first argument for arrays and ranges. - +--------------------+--------+--------------------------+---------------+ - | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +--------------------+--------+--------------------------+---------------+ - | \"/\" | ✓ | | | - +--------------------+--------+--------------------------+---------------+ - | \"\\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"cond\" | ✓ | | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"det\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"logdet\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | \"logabsdet\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | \"size\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ """ -lufact +intersect doc""" - lufact!(A) -> LU + intersect!(s1, s2) + +Intersects sets "s1" and "s2" and overwrites the set "s1" +with the result. If needed, "s1" will be expanded to the size of +"s2". -"lufact!" is the same as "lufact()", but saves space by -overwriting the input A, instead of creating a copy. For sparse -"A" the "nzval" field is not overwritten but the index fields, -"colptr" and "rowval" are decremented in place, converting from -1-based indices to 0-based indices. """ -lufact! +intersect! doc""" - chol(A[, LU]) -> F + inv(M) + +Matrix inverse -Compute the Cholesky factorization of a symmetric positive definite -matrix "A" and return the matrix "F". If "LU" is "Val{:U}" -(Upper), "F" is of type "UpperTriangular" and "A = F'*F". If -"LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" -and "A = F*F'". "LU" defaults to "Val{:U}". """ -chol +inv doc""" - cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + invdigamma(x) + +Compute the inverse digamma function of "x". -Compute the Cholesky factorization of a dense symmetric positive -(semi)definite matrix "A" and return either a "Cholesky" if -"pivot==Val{false}" or "CholeskyPivoted" if -"pivot==Val{true}". "LU" may be ":L" for using the lower part -or ":U" for the upper part. The default is to use ":U". The -triangular matrix can be obtained from the factorization "F" -with: "F[:L]" and "F[:U]". The following functions are -available for "Cholesky" objects: "size", "\", "inv", -"det". For "CholeskyPivoted" there is also defined a "rank". -If "pivot==Val{false}" a "PosDefException" exception is thrown -in case the matrix is not positive definite. The argument "tol" -determines the tolerance for determining the rank. For negative -values, the tolerance is the machine precision. """ -cholfact +invdigamma doc""" - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - -Compute the Cholesky factorization of a sparse positive definite -matrix "A". A fill-reducing permutation is used. "F = -cholfact(A)" is most frequently used to solve systems of equations -with "F\b", but also the methods "diag", "det", "logdet" -are defined for "F". You can also extract individual factors -from "F", using "F[:L]". However, since pivoting is on by -default, the factorization is internally represented as "A == -P'*L*L'*P" with a permutation matrix "P"; using just "L" -without accounting for "P" will give incorrect answers. To -include the effects of permutation, it's typically preferable to -extact "combined" factors like "PtL = F[:PtL]" (the equivalent -of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). + invmod(x, m) -Setting optional "shift" keyword argument computes the -factorization of "A+shift*I" instead of "A". If the "perm" -argument is nonempty, it should be a permutation of *1:size(A,1)* -giving the ordering to use (instead of CHOLMOD's default AMD -ordering). +Take the inverse of "x" modulo "m": "y" such that xy = 1 +\pmod m -The function calls the C library CHOLMOD and many other functions -from the library are wrapped but not exported. """ -cholfact +invmod doc""" - cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + invoke(f, (types...), args...) + +Invoke a method for the given generic function matching the +specified types (as a tuple), on the specified arguments. The +arguments must be compatible with the specified types. This allows +invoking a method other than the most specific matching method, +which is useful when the behavior of a more general definition is +explicitly needed (often as part of the implementation of a more +specific method of the same function). -"cholfact!" is the same as "cholfact()", but saves space by -overwriting the input "A", instead of creating a copy. -"cholfact!" can also reuse the symbolic factorization from a -different matrix "F" with the same structure when used as: -"cholfact!(F::CholmodFactor, A)". """ -cholfact! +invoke doc""" - ldltfact(A) -> LDLtFactorization + invperm(v) + +Return the inverse permutation of v. -Compute a factorization of a positive definite matrix "A" such -that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular -matrix and "d" is a vector with non-negative elements. """ -ldltfact +invperm doc""" - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - -Compute the LDLt factorization of a sparse symmetric or Hermitian -matrix "A". A fill-reducing permutation is used. "F = -ldltfact(A)" is most frequently used to solve systems of equations -with "F\b", but also the methods "diag", "det", "logdet" -are defined for "F". You can also extract individual factors from -"F", using "F[:L]". However, since pivoting is on by default, -the factorization is internally represented as "A == P'*L*D*L'*P" -with a permutation matrix "P"; using just "L" without -accounting for "P" will give incorrect answers. To include the -effects of permutation, it's typically preferable to extact -"combined" factors like "PtL = F[:PtL]" (the equivalent of -"P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The -complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, -:DU, :PtLD, :DUP". + ipermute!(v, p) -Setting optional "shift" keyword argument computes the -factorization of "A+shift*I" instead of "A". If the "perm" -argument is nonempty, it should be a permutation of *1:size(A,1)* -giving the ordering to use (instead of CHOLMOD's default AMD -ordering). +Like permute!, but the inverse of the given permutation is applied. -The function calls the C library CHOLMOD and many other functions -from the library are wrapped but not exported. """ -ldltfact +ipermute! doc""" - qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + ipermutedims(A, perm) + +Like "permutedims()", except the inverse of the given permutation +is applied. -Compute the (pivoted) QR factorization of "A" such that either -"A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default -is to compute a thin factorization. Note that "R" is not extended -with zeros when the full "Q" is requested. """ -qr +ipermutedims doc""" - qrfact(A[, pivot=Val{false}]) -> F - -Computes the QR factorization of "A". The return type of "F" -depends on the element type of "A" and whether pivoting is -specified (with "pivot==Val{true}"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ + irfft(A, d[, dims]) -"BlasFloat" refers to any of: "Float32", "Float64", -"Complex64" or "Complex128". +Inverse of "rfft()": for a complex array "A", gives the +corresponding real array whose FFT yields "A" in the first half. +As for "rfft()", "dims" is an optional subset of dimensions to +transform, defaulting to "1:ndims(A)". -The individual components of the factorization "F" can be -accessed by indexing: +"d" is the length of the transformed real array along the +"dims[1]" dimension, which must satisfy "d == +floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred +from "size(A)" due to the possibility of rounding by the +"floor" function here.) - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:p]\" | pivot \"Vector\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ +""" +irfft -The following functions are available for the "QR" objects: -"size", "\". When "A" is rectangular, "\" will return a -least squares solution and if the solution is not unique, the one -with smallest norm is returned. +doc""" + is(x, y) -> Bool +===(x, y) -> Bool +≡(x, y) -> Bool -Multiplication with respect to either thin or full "Q" is -allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A -"Q" matrix can be converted into a regular matrix with "full()" -which has a named argument "thin". +Determine whether "x" and "y" are identical, in the sense that +no program could distinguish them. Compares mutable objects by +address in memory, and compares immutable objects (such as numbers) +by contents at the bit level. This function is sometimes called +"egal". -Note: "qrfact" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the "Q" and "R" matrices can be stored compactly rather - as two separate dense matrices.The data contained in "QR" or - "QRPivoted" can be used to construct the "QRPackedQ" type, - which is a compact representation of the rotation matrix: +""" +is - Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) +doc""" + is_assigned_char(c) -> Bool - where \tau_i is the scale factor and v_i is the projection - vector associated with the i^{th} Householder elementary - reflector.The data contained in "QRCompactWY" can be used to - construct the "QRCompactWYQ" type, which is a compact - representation of the rotation matrix +Returns true if the given char or integer is an assigned Unicode +code point. - Q = I + Y T Y^T +""" +is_assigned_char - where "Y" is m \times r lower trapezoidal and "T" is r - \times r upper triangular. The *compact WY* representation - [Schreiber1989] is not to be confused with the older, *WY* - representation [Bischof1987]. (The LAPACK documentation uses - "V" in lieu of "Y".) +doc""" + isa(x, type) -> Bool -[Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 +Determine whether "x" is of the given "type". -[Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 """ -qrfact +isa doc""" - qrfact(A) -> SPQR.Factorization + isabspath(path::AbstractString) -> Bool + +Determines whether a path is absolute (begins at the root +directory). -Compute the QR factorization of a sparse matrix "A". A fill- -reducing permutation is used. The main application of this type is -to solve least squares problems with "\". The function calls the -C library SPQR and a few additional functions from the library are -wrapped but not exported. """ -qrfact +isabspath doc""" - qrfact!(A[, pivot=Val{false}]) + isalnum(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is alphanumeric, or whether this is true +for all elements of a string. A character is classified as +alphabetic if it belongs to the Unicode general category Letter or +Number, i.e. a character whose category code begins with 'L' or +'N'. -"qrfact!" is the same as "qrfact()" when A is a subtype of -"StridedMatrix", but saves space by overwriting the input "A", -instead of creating a copy. """ -qrfact! +isalnum doc""" - full(QRCompactWYQ[, thin=true]) -> Matrix + isalpha(c::Union{Char, AbstractString}) -> Bool -Converts an orthogonal or unitary matrix stored as a -"QRCompactWYQ" object, i.e. in the compact WY format -[Bischof1987], to a dense matrix. +Tests whether a character is alphabetic, or whether this is true +for all elements of a string. A character is classified as +alphabetic if it belongs to the Unicode general category Letter, +i.e. a character whose category code begins with 'L'. -Optionally takes a "thin" Boolean argument, which if "true" -omits the columns that span the rows of "R" in the QR -factorization that are zero. The resulting matrix is the "Q" in a -thin QR factorization (sometimes called the reduced QR -factorization). If "false", returns a "Q" that spans all rows -of "R" in its corresponding QR factorization. """ -full +isalpha doc""" - bkfact(A) -> BunchKaufman + isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) -Compute the Bunch-Kaufman [Bunch1977] factorization of a real -symmetric or complex Hermitian matrix "A" and return a -"BunchKaufman" object. The following functions are available for -"BunchKaufman" objects: "size", "\", "inv", "issym", -"ishermitian". -""" -bkfact +Inexact equality comparison - behaves slightly different depending +on types of input args: -doc""" - bkfact!(A) -> BunchKaufman +* For "FloatingPoint" numbers, "isapprox" returns "true" if + "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". + +* For "Integer" and "Rational" numbers, "isapprox" returns + "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. + If one of "x" and "y" is "FloatingPoint", the other is + promoted, and the method above is called instead. + +* For "Complex" numbers, the distance in the complex plane is + compared, using the same criterion as above. + +For default tolerance arguments, "maxeps = max(eps(abs(x)), +eps(abs(y)))". -"bkfact!" is the same as "bkfact()", but saves space by -overwriting the input "A", instead of creating a copy. """ -bkfact! +isapprox doc""" - sqrtm(A) + isascii(c::Union{Char, AbstractString}) -> Bool -Compute the matrix square root of "A". If "B = sqrtm(A)", then -"B*B == A" within roundoff error. +Tests whether a character belongs to the ASCII character set, or +whether this is true for all elements of a string. -"sqrtm" uses a polyalgorithm, computing the matrix square root -using Schur factorizations ("schurfact()") unless it detects the -matrix to be Hermitian or real symmetric, in which case it computes -the matrix square root from an eigendecomposition ("eigfact()"). -In the latter situation for positive definite matrices, the matrix -square root has "Real" elements, otherwise it has "Complex" -elements. """ -sqrtm +isascii doc""" - eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + isbits(T) -Computes eigenvalues and eigenvectors of "A". See "eigfact()" -for details on the "balance" keyword argument. +True if "T" is a "plain data" type, meaning it is immutable and +contains no references to other values. Typical examples are +numeric types such as "UInt8", "Float64", and +"Complex{Float64}". - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) + julia> isbits(Complex{Float64}) + true + + julia> isbits(Complex) + false -"eig" is a wrapper around "eigfact()", extracting all parts of -the factorization to a tuple; where possible, using "eigfact()" -is recommended. """ -eig +isbits doc""" - eig(A, B) -> D, V + isblockdev(path) -> Bool -Computes generalized eigenvalues and vectors of "A" with respect -to "B". +Returns "true" if "path" is a block device, "false" +otherwise. -"eig" is a wrapper around "eigfact()", extracting all parts of -the factorization to a tuple; where possible, using "eigfact()" -is recommended. """ -eig +isblockdev doc""" - eigvals(A,[irange,][vl,][vu]) + ischardev(path) -> Bool -Returns the eigenvalues of "A". If "A" is "Symmetric", -"Hermitian" or "SymTridiagonal", it is possible to calculate -only a subset of the eigenvalues by specifying either a -"UnitRange" "irange" covering indices of the sorted -eigenvalues, or a pair "vl" and "vu" for the lower and upper -boundaries of the eigenvalues. +Returns "true" if "path" is a character device, "false" +otherwise. -For general non-symmetric matrices it is possible to specify how -the matrix is balanced before the eigenvector calculation. The -option "permute=true" permutes the matrix to become closer to -upper triangular, and "scale=true" scales the matrix by its -diagonal elements to make rows and columns more equal in norm. The -default is "true" for both options. """ -eigvals +ischardev doc""" - eigmax(A) + iscntrl(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a control character, or whether this +is true for all elements of a string. Control characters are the +non-printing characters of the Latin-1 subset of Unicode. -Returns the largest eigenvalue of "A". """ -eigmax +iscntrl doc""" - eigmin(A) + isconst([m::Module], s::Symbol) -> Bool + +Determine whether a global is declared "const" in a given module. +The default module argument is "current_module()". -Returns the smallest eigenvalue of "A". """ -eigmin +isconst doc""" - eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + isdefined([object], index | symbol) -Returns a matrix "M" whose columns are the eigenvectors of "A". -(The "k"th eigenvector can be obtained from the slice "M[:, -k]".) The "permute" and "scale" keywords are the same as for -"eigfact()". +Tests whether an assignable location is defined. The arguments can +be an array and index, a composite object and field name (as a +symbol), or a module and a symbol. With a single symbol argument, +tests whether a global variable with that name is defined in +"current_module()". -For "SymTridiagonal" matrices, if the optional vector of -eigenvalues "eigvals" is specified, returns the specific -corresponding eigenvectors. """ -eigvecs +isdefined doc""" - eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - -Computes the eigenvalue decomposition of "A", returning an -"Eigen" factorization object "F" which contains the eigenvalues -in "F[:values]" and the eigenvectors in the columns of the matrix -"F[:vectors]". (The "k"th eigenvector can be obtained from the -slice "F[:vectors][:, k]".) - -The following functions are available for "Eigen" objects: -"inv", "det". + isdiag(A) -> Bool -If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it -is possible to calculate only a subset of the eigenvalues by -specifying either a "UnitRange" "irange" covering indices of -the sorted eigenvalues or a pair "vl" and "vu" for the lower -and upper boundaries of the eigenvalues. +Test whether a matrix is diagonal. -For general nonsymmetric matrices it is possible to specify how the -matrix is balanced before the eigenvector calculation. The option -"permute=true" permutes the matrix to become closer to upper -triangular, and "scale=true" scales the matrix by its diagonal -elements to make rows and columns more equal in norm. The default -is "true" for both options. """ -eigfact +isdiag doc""" - eigfact(A, B) -> GeneralizedEigen + isdigit(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a numeric digit (0-9), or whether this +is true for all elements of a string. -Computes the generalized eigenvalue decomposition of "A" and -"B", returning a "GeneralizedEigen" factorization object "F" -which contains the generalized eigenvalues in "F[:values]" and -the generalized eigenvectors in the columns of the matrix -"F[:vectors]". (The "k"th generalized eigenvector can be -obtained from the slice "F[:vectors][:, k]".) """ -eigfact +isdigit doc""" - eigfact!(A[, B]) + isdir(path) -> Bool + +Returns "true" if "path" is a directory, "false" otherwise. -Same as "eigfact()", but saves space by overwriting the input -"A" (and "B"), instead of creating a copy. """ -eigfact! +isdir doc""" - hessfact(A) + isdirpath(path::AbstractString) -> Bool + +Determines whether a path refers to a directory (for example, ends +with a path separator). -Compute the Hessenberg decomposition of "A" and return a -"Hessenberg" object. If "F" is the factorization object, the -unitary matrix can be accessed with "F[:Q]" and the Hessenberg -matrix with "F[:H]". When "Q" is extracted, the resulting type -is the "HessenbergQ" object, and may be converted to a regular -matrix with "full()". """ -hessfact +isdirpath doc""" - hessfact!(A) + iseltype(A, T) + +Tests whether A or its elements are of type T -"hessfact!" is the same as "hessfact()", but saves space by -overwriting the input A, instead of creating a copy. """ -hessfact! +iseltype doc""" - schurfact(A) -> Schur + isempty(collection) -> Bool -Computes the Schur factorization of the matrix "A". The (quasi) -triangular Schur factor can be obtained from the "Schur" object -"F" with either "F[:Schur]" or "F[:T]" and the -unitary/orthogonal Schur vectors can be obtained with -"F[:vectors]" or "F[:Z]" such that -"A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" -can be obtained with "F[:values]". -""" -schurfact +Determine whether a collection is empty (has no elements). -doc""" - schurfact!(A) + julia> isempty([]) + true + + julia> isempty([1 2 3]) + false -Computes the Schur factorization of "A", overwriting "A" in the -process. See "schurfact()" """ -schurfact! +isempty doc""" - schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + isequal(x, y) -See "schurfact()" -""" -schur +Similar to "==", except treats all floating-point "NaN" values +as equal to each other, and treats "-0.0" as unequal to "0.0". +The default implementation of "isequal" calls "==", so if you +have a type that doesn't have these floating-point subtleties then +you probably only need to define "==". -doc""" - ordschur(Q, T, select) -> Schur +"isequal" is the comparison function used by hash tables +("Dict"). "isequal(x,y)" must imply that "hash(x) == +hash(y)". + +This typically means that if you define your own "==" function +then you must define a corresponding "hash" (and vice versa). +Collections typically implement "isequal" by calling "isequal" +recursively on all contents. + +Scalar types generally do not need to implement "isequal" +separate from "==", unless they represent floating-point numbers +amenable to a more efficient implementation than that provided as a +generic fallback (based on "isnan", "signbit", and "=="). -Reorders the Schur factorization of a real matrix "A=Q*T*Q'" -according to the logical array "select" returning a Schur object -"F". The selected eigenvalues appear in the leading diagonal of -"F[:Schur]" and the the corresponding leading columns of -"F[:vectors]" form an orthonormal basis of the corresponding -right invariant subspace. A complex conjugate pair of eigenvalues -must be either both included or excluded via "select". """ -ordschur +isequal doc""" - ordschur!(Q, T, select) -> Schur + iseven(x::Integer) -> Bool + +Returns "true" is "x" is even (that is, divisible by 2), and +"false" otherwise. + + julia> iseven(9) + false + + julia> iseven(10) + true -Reorders the Schur factorization of a real matrix "A=Q*T*Q'", -overwriting "Q" and "T" in the process. See "ordschur()" """ -ordschur! +iseven doc""" - ordschur(S, select) -> Schur + isexecutable(path) -> Bool + +Returns "true" if the current user has permission to execute +"path", "false" otherwise. -Reorders the Schur factorization "S" of type "Schur". """ -ordschur +isexecutable doc""" - ordschur!(S, select) -> Schur + isfifo(path) -> Bool + +Returns "true" if "path" is a FIFO, "false" otherwise. -Reorders the Schur factorization "S" of type "Schur", -overwriting "S" in the process. See "ordschur()" """ -ordschur! +isfifo doc""" - schurfact(A, B) -> GeneralizedSchur + isfile(path) -> Bool + +Returns "true" if "path" is a regular file, "false" +otherwise. -Computes the Generalized Schur (or QZ) factorization of the -matrices "A" and "B". The (quasi) triangular Schur factors can -be obtained from the "Schur" object "F" with "F[:S]" and -"F[:T]", the left unitary/orthogonal Schur vectors can be -obtained with "F[:left]" or "F[:Q]" and the right -unitary/orthogonal Schur vectors can be obtained with "F[:right]" -or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and -"B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of -"A" and "B" can be obtained with "F[:alpha]./F[:beta]". """ -schurfact +isfile doc""" - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + isfinite(f) -> Bool + +Test whether a number is finite -See "schurfact()" """ -schur +isfinite doc""" - ordschur(S, T, Q, Z, select) -> GeneralizedSchur - -Reorders the Generalized Schur factorization of a matrix "(A, B) = -(Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" -and returns a GeneralizedSchur object "GS". The selected -eigenvalues appear in the leading diagonal of both``(GS[:S], -GS[:T])`` and the left and right unitary/orthogonal Schur vectors -are also reordered such that "(A, B) = GS[:Q]*(GS[:S], -GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of -"A" and "B" can still be obtained with -"GS[:alpha]./GS[:beta]". + isgeneric(f::Function) -> Bool + +Determine whether a function is generic. + """ -ordschur +isgeneric doc""" - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + isgraph(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is printable, and not a space, or whether +this is true for all elements of a string. Any character that +would cause a printer to use ink should be classified with +isgraph(c)==true. -Reorders the Generalized Schur factorization of a matrix by -overwriting the matrices "(S, T, Q, Z)" in the process. See -"ordschur()". """ -ordschur! +isgraph doc""" - ordschur(GS, select) -> GeneralizedSchur + ishermitian(A) -> Bool + +Test whether a matrix is Hermitian. -Reorders the Generalized Schur factorization of a Generalized Schur -object. See "ordschur()". """ -ordschur +ishermitian doc""" - ordschur!(GS, select) -> GeneralizedSchur + isimmutable(v) + +True if value "v" is immutable. See *Immutable Composite Types* +for a discussion of immutability. Note that this function works on +values, so if you give it a type, it will tell you that a value of +"DataType" is mutable. -Reorders the Generalized Schur factorization of a Generalized Schur -object by overwriting the object with the new factorization. See -"ordschur()". """ -ordschur! +isimmutable doc""" - svdfact(A[, thin=true]) -> SVD + isinf(f) -> Bool + +Test whether a number is infinite -Compute the Singular Value Decomposition (SVD) of "A" and return -an "SVD" object. "U", "S", "V" and "Vt" can be obtained -from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" -and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is -"true", an economy mode decomposition is returned. The algorithm -produces "Vt" and hence "Vt" is more efficient to extract than -"V". The default is to produce a thin decomposition. """ -svdfact +isinf doc""" - svdfact!(A[, thin=true]) -> SVD + isinteger(x) -> Bool + +Test whether "x" or all its elements are numerically equal to +some integer -"svdfact!" is the same as "svdfact()", but saves space by -overwriting the input A, instead of creating a copy. If "thin" is -"true", an economy mode decomposition is returned. The default is -to produce a thin decomposition. """ -svdfact! +isinteger doc""" - svd(A[, thin=true]) -> U, S, V + isinteractive() -> Bool + +Determine whether Julia is running an interactive session. -Wrapper around "svdfact" extracting all parts the factorization -to a tuple. Direct use of "svdfact" is therefore generally more -efficient. Computes the SVD of A, returning "U", vector "S", -and "V" such that "A == U*diagm(S)*V'". If "thin" is -"true", an economy mode decomposition is returned. The default is -to produce a thin decomposition. """ -svd +isinteractive doc""" - svdvals(A) + isleaftype(T) + +Determine whether "T" is a concrete type that can have instances, +meaning its only subtypes are itself and "None" (but "T" itself +is not "None"). -Returns the singular values of "A". """ -svdvals +isleaftype doc""" - svdvals!(A) + isless(x, y) + +Test whether "x" is less than "y", according to a canonical +total order. Values that are normally unordered, such as "NaN", +are ordered in an arbitrary but consistent fashion. This is the +default comparison used by "sort". Non-numeric types with a +canonical total order should implement this function. Numeric types +only need to implement it if they have special values such as +"NaN". -Returns the singular values of "A", while saving space by -overwriting the input. """ -svdvals! +isless doc""" - svdfact(A, B) -> GeneralizedSVD + islink(path) -> Bool + +Returns "true" if "path" is a symbolic link, "false" +otherwise. -Compute the generalized SVD of "A" and "B", returning a -"GeneralizedSVD" Factorization object "F", such that "A = -F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = -F[:V]*F[:D2]*F[:R0]*F[:Q]'". """ -svdfact +islink doc""" - svd(A, B) -> U, V, Q, D1, D2, R0 + islower(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a lowercase letter, or whether this is +true for all elements of a string. A character is classified as +lowercase if it belongs to Unicode category Ll, Letter: Lowercase. -Wrapper around "svdfact" extracting all parts the factorization -to a tuple. Direct use of "svdfact" is therefore generally more -efficient. The function returns the generalized SVD of "A" and -"B", returning "U", "V", "Q", "D1", "D2", and "R0" -such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". """ -svd +islower doc""" - svdvals(A, B) + ismarked(s) + +Returns true if stream "s" is marked. + +See also "mark()", "unmark()", "reset()" -Return only the singular values from the generalized singular value -decomposition of "A" and "B". """ -svdvals +ismarked doc""" - triu(M) + ismatch(r::Regex, s::AbstractString) -> Bool + +Test whether a string contains a match of the given regular +expression. -Upper triangle of a matrix. """ -triu +ismatch doc""" - triu(M, k) + ismount(path) -> Bool + +Returns "true" if "path" is a mount point, "false" otherwise. -Returns the upper triangle of "M" starting from the "k"th -superdiagonal. """ -triu +ismount doc""" - triu!(M) + isnan(f) -> Bool + +Test whether a floating point number is not a number (NaN) -Upper triangle of a matrix, overwriting "M" in the process. """ -triu! +isnan doc""" - triu!(M, k) + isnull(x) + +Is the "Nullable" object "x" null, i.e. missing a value? -Returns the upper triangle of "M" starting from the "k"th -superdiagonal, overwriting "M" in the process. """ -triu! +isnull doc""" - tril(M) + isnumber(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is numeric, or whether this is true for +all elements of a string. A character is classified as numeric if +it belongs to the Unicode general category Number, i.e. a character +whose category code begins with 'N'. -Lower triangle of a matrix. """ -tril +isnumber doc""" - tril(M, k) + isodd(x::Integer) -> Bool + +Returns "true" if "x" is odd (that is, not divisible by 2), and +"false" otherwise. + + julia> isodd(9) + true + + julia> isodd(10) + false -Returns the lower triangle of "M" starting from the "k"th -subdiagonal. """ -tril +isodd doc""" - tril!(M) + isopen(stream) -> Bool + +Determine whether a stream is open (i.e. has not been closed yet). +If the connection has been closed remotely (in case of e.g. a +socket), "isopen" will return "false" even though buffered data +may still be available. Use "eof" to check if necessary. -Lower triangle of a matrix, overwriting "M" in the process. """ -tril! +isopen doc""" - tril!(M, k) + ispath(path) -> Bool + +Returns "true" if "path" is a valid filesystem path, "false" +otherwise. -Returns the lower triangle of "M" starting from the "k"th -subdiagonal, overwriting "M" in the process. """ -tril! +ispath doc""" - diagind(M[, k]) + isperm(v) -> Bool + +Returns true if v is a valid permutation. -A "Range" giving the indices of the "k"th diagonal of the -matrix "M". """ -diagind +isperm doc""" - diag(M[, k]) + isposdef(A) -> Bool + +Test whether a matrix is positive definite. -The "k"th diagonal of a matrix, as a vector. Use "diagm" to -construct a diagonal matrix. """ -diag +isposdef doc""" - diagm(v[, k]) + isposdef!(A) -> Bool + +Test whether a matrix is positive definite, overwriting "A" in +the processes. -Construct a diagonal matrix and place "v" on the "k"th -diagonal. """ -diagm +isposdef! doc""" - scale(A, b) + ispow2(n) -> Bool + +Test whether "n" is a power of two + """ -scale +ispow2 doc""" - scale(b, A) + isprime(x::Integer) -> Bool -Scale an array "A" by a scalar "b", returning a new array. +Returns "true" if "x" is prime, and "false" otherwise. -If "A" is a matrix and "b" is a vector, then "scale(A,b)" -scales each column "i" of "A" by "b[i]" (similar to -"A*diagm(b)"), while "scale(b,A)" scales each row "i" of -"A" by "b[i]" (similar to "diagm(b)*A"), returning a new -array. + julia> isprime(3) + true + + isprime(x::BigInt[, reps = 25]) -> Bool + +Probabilistic primality test. Returns "true" if "x" is prime; +and "false" if "x" is not prime with high probability. The +false positive rate is about "0.25^reps". "reps = 25" is +considered safe for cryptographic applications (Knuth, +Seminumerical Algorithms). -Note: for large "A", "scale" can be much faster than "A .* b" -or "b .* A", due to the use of BLAS. -""" -scale + julia> isprime(big(3)) + true -doc""" - scale!(A, b) """ -scale! +isprime doc""" - scale!(b, A) + isprint(c::Union{Char, AbstractString}) -> Bool -Scale an array "A" by a scalar "b", similar to "scale()" but -overwriting "A" in-place. +Tests whether a character is printable, including spaces, but not a +control character. For strings, tests whether this is true for all +elements of the string. -If "A" is a matrix and "b" is a vector, then "scale!(A,b)" -scales each column "i" of "A" by "b[i]" (similar to -"A*diagm(b)"), while "scale!(b,A)" scales each row "i" of -"A" by "b[i]" (similar to "diagm(b)*A"), again operating in- -place on "A". """ -scale! +isprint doc""" - Tridiagonal(dl, d, du) + ispunct(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character belongs to the Unicode general category +Punctuation, i.e. a character whose category code begins with 'P'. +For strings, tests whether this is true for all elements of the +string. -Construct a tridiagonal matrix from the lower diagonal, diagonal, -and upper diagonal, respectively. The result is of type -"Tridiagonal" and provides efficient specialized linear solvers, -but may be converted into a regular matrix with "full()". """ -Tridiagonal +ispunct doc""" - Bidiagonal(dv, ev, isupper) + isqrt(n) + +Integer square root: the largest integer "m" such that "m*m <= +n". -Constructs an upper ("isupper=true") or lower ("isupper=false") -bidiagonal matrix using the given diagonal ("dv") and off- -diagonal ("ev") vectors. The result is of type "Bidiagonal" -and provides efficient specialized linear solvers, but may be -converted into a regular matrix with "full()". """ -Bidiagonal +isqrt doc""" - SymTridiagonal(d, du) + isreadable(path) -> Bool + +Returns "true" if the current user has permission to read +"path", "false" otherwise. -Construct a real symmetric tridiagonal matrix from the diagonal and -upper diagonal, respectively. The result is of type -"SymTridiagonal" and provides efficient specialized eigensolvers, -but may be converted into a regular matrix with "full()". """ -SymTridiagonal +isreadable doc""" - rank(M) + isreadonly(stream) -> Bool + +Determine whether a stream is read-only. -Compute the rank of a matrix. """ -rank +isreadonly doc""" - norm(A[, p]) + isready(r::RemoteRef) -Compute the "p"-norm of a vector or the operator norm of a matrix -"A", defaulting to the "p=2"-norm. +Determine whether a "RemoteRef" has a value stored to it. Note +that this function can cause race conditions, since by the time you +receive its result it may no longer be true. It is recommended that +this function only be used on a "RemoteRef" that is assigned +once. -For vectors, "p" can assume any numeric value (even though not -all values produce a mathematically valid vector norm). In -particular, "norm(A, Inf)" returns the largest value in -"abs(A)", whereas "norm(A, -Inf)" returns the smallest. +If the argument "RemoteRef" is owned by a different node, this +call will block to wait for the answer. It is recommended to wait +for "r" in a separate task instead, or to use a local +"RemoteRef" as a proxy: + + rr = RemoteRef() + @async put!(rr, remotecall_fetch(p, long_computation)) + isready(rr) # will not block -For matrices, valid values of "p" are "1", "2", or "Inf". -(Note that for sparse matrices, "p=2" is currently not -implemented.) Use "vecnorm()" to compute the Frobenius norm. """ -norm +isready doc""" - vecnorm(A[, p]) + isreal(x) -> Bool -For any iterable container "A" (including arrays of any -dimension) of numbers (or any element type for which "norm" is -defined), compute the "p"-norm (defaulting to "p=2") as if -"A" were a vector of the corresponding length. +Test whether "x" or all its elements are numerically equal to +some real number -For example, if "A" is a matrix and "p=2", then this is -equivalent to the Frobenius norm. """ -vecnorm +isreal doc""" - cond(M[, p]) + issetgid(path) -> Bool + +Returns "true" if "path" has the setgid flag set, "false" +otherwise. -Condition number of the matrix "M", computed using the operator -"p"-norm. Valid values for "p" are "1", "2" (default), or -"Inf". """ -cond +issetgid doc""" - condskeel(M[, x, p]) - - \kappa_S(M, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \right\Vert_p \\ - \kappa_S(M, x, p) & = \left\Vert \left\vert M \right\vert - \left\vert M^{-1} \right\vert \left\vert x \right\vert - \right\Vert_p + issetuid(path) -> Bool -Skeel condition number \kappa_S of the matrix "M", optionally -with respect to the vector "x", as computed using the operator -"p"-norm. "p" is "Inf" by default, if not provided. Valid -values for "p" are "1", "2", or "Inf". +Returns "true" if "path" has the setuid flag set, "false" +otherwise. -This quantity is also known in the literature as the Bauer -condition number, relative condition number, or componentwise -relative condition number. """ -condskeel +issetuid doc""" - trace(M) + issocket(path) -> Bool + +Returns "true" if "path" is a socket, "false" otherwise. -Matrix trace """ -trace +issocket doc""" - det(M) + issorted(v, [by=,] [lt=,] [rev=false]) + +Test whether a vector is in sorted order. The "by", "lt" and +"rev" keywords modify what order is considered to be sorted just +as they do for "sort". -Matrix determinant """ -det +issorted doc""" - logdet(M) + isspace(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is any whitespace character. Includes +ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', +Latin-1 character U+0085, and characters in Unicode category Zs. +For strings, tests whether this is true for all elements of the +string. -Log of matrix determinant. Equivalent to "log(det(M))", but may -provide increased accuracy and/or speed. """ -logdet +isspace doc""" - logabsdet(M) + issparse(S) + +Returns "true" if "S" is sparse, and "false" otherwise. -Log of absolute value of determinant of real matrix. Equivalent to -"(log(abs(det(M))), sign(det(M)))", but may provide increased -accuracy and/or speed. """ -logabsdet +issparse doc""" - inv(M) + issticky(path) -> Bool + +Returns "true" if "path" has the sticky bit set, "false" +otherwise. -Matrix inverse """ -inv +issticky doc""" - pinv(M[, tol]) - -Computes the Moore-Penrose pseudoinverse. + issubnormal(f) -> Bool -For matrices "M" with floating point elements, it is convenient -to compute the pseudoinverse by inverting only singular values -above a given threshold, "tol". +Test whether a floating point number is subnormal -The optimal choice of "tol" varies both with the value of "M" -and the intended application of the pseudoinverse. The default -value of "tol" is -"eps(real(float(one(eltype(M)))))*maximum(size(A))", which is -essentially machine epsilon for the real part of a matrix element -multiplied by the larger matrix dimension. For inverting dense ill- -conditioned matrices in a least-squares sense, "tol = -sqrt(eps(real(float(one(eltype(M))))))" is recommended. +""" +issubnormal -For more information, see [8859], [B96], [S84], [KY88]. +doc""" + issubset(a, b) +⊆(A, S) -> Bool +⊈(A, S) -> Bool +⊊(A, S) -> Bool -[8859] Issue 8859, "Fix least squares", - https://github.com/JuliaLang/julia/pull/8859 +Determine whether every element of "a" is also in "b", using +"in()". -[B96] Åke Björck, "Numerical Methods for Least Squares - Problems", SIAM Press, Philadelphia, 1996, "Other Titles in - Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 + issubset(A, S) -> Bool +⊆(A, S) -> Bool -[S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 +True if A is a subset of or equal to S. -[KY88] Konstantinos Konstantinides and Kung Yao, - "Statistical analysis of effective singular values in - matrix rank determination", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 """ -pinv +issubset doc""" - nullspace(M) + issubtype(type1, type2) + +True if and only if all values of "type1" are also of "type2". +Can also be written using the "<:" infix operator as "type1 <: +type2". -Basis for nullspace of "M". """ -nullspace +issubtype doc""" - repmat(A, n, m) + issym(A) -> Bool + +Test whether a matrix is symmetric. -Construct a matrix by repeating the given matrix "n" times in -dimension 1 and "m" times in dimension 2. """ -repmat +issym doc""" - repeat(A, inner = Int[], outer = Int[]) + istaskdone(task) -> Bool + +Tell whether a task has exited. -Construct an array by repeating the entries of "A". The i-th -element of "inner" specifies the number of times that the -individual entries of the i-th dimension of "A" should be -repeated. The i-th element of "outer" specifies the number of -times that a slice along the i-th dimension of "A" should be -repeated. """ -repeat +istaskdone doc""" - kron(A, B) + istaskstarted(task) -> Bool + +Tell whether a task has started executing. -Kronecker tensor product of two vectors or two matrices. """ -kron +istaskstarted doc""" - blkdiag(A...) + istext(m::MIME) + +Determine whether a MIME type is text data. -Concatenate matrices block-diagonally. Currently only implemented -for sparse matrices. """ -blkdiag +istext doc""" - linreg(x, y) -> [a; b] - -Linear Regression. Returns "a" and "b" such that "a+b*x" is -the closest line to the given points "(x,y)". In other words, -this function determines parameters "[a, b]" that minimize the -squared error between "y" and "a+b*x". + istril(A) -> Bool -**Example**: +Test whether a matrix is lower triangular. - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, "o") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression """ -linreg +istril doc""" - linreg(x, y, w) + istriu(A) -> Bool + +Test whether a matrix is upper triangular. -Weighted least-squares linear regression. """ -linreg +istriu doc""" - expm(A) + isupper(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is an uppercase letter, or whether this +is true for all elements of a string. A character is classified +as uppercase if it belongs to Unicode category Lu, Letter: +Uppercase, or Lt, Letter: Titlecase. -Matrix exponential. """ -expm +isupper doc""" - lyap(A, C) + isvalid(value) -> Bool + +Returns true if the given value is valid for its type, which +currently can be one of "Char", "ASCIIString", "UTF8String", +"UTF16String", or "UTF32String" + + isvalid(T, value) -> Bool + +Returns true if the given value is valid for that type. Types +currently can be "Char", "ASCIIString", "UTF8String", +"UTF16String", or "UTF32String" Values for "Char" can be of +type "Char" or "UInt32" Values for "ASCIIString" and +"UTF8String" can be of that type, or "Vector{UInt8}" Values for +"UTF16String" can be "UTF16String" or "Vector{UInt16}" Values +for "UTF32String" can be "UTF32String", "Vector{Char}" or +"Vector{UInt32}" + + isvalid(str, i) + +Tells whether index "i" is valid for the given string -Computes the solution "X" to the continuous Lyapunov equation -"AX + XA' + C = 0", where no eigenvalue of "A" has a zero real -part and no two eigenvalues are negative complex conjugates of each -other. """ -lyap +isvalid doc""" - sylvester(A, B, C) + iswritable(path) -> Bool + +Returns "true" if the current user has permission to write to +"path", "false" otherwise. -Computes the solution "X" to the Sylvester equation "AX + XB + C -= 0", where "A", "B" and "C" have compatible dimensions and -"A" and "-B" have no eigenvalues with equal real part. """ -sylvester +iswritable doc""" - issym(A) -> Bool + isxdigit(c::Union{Char, AbstractString}) -> Bool + +Tests whether a character is a valid hexadecimal digit, or whether +this is true for all elements of a string. -Test whether a matrix is symmetric. """ -issym +isxdigit doc""" - isposdef(A) -> Bool + join(strings, delim[, last]) + +Join an array of "strings" into a single string, inserting the +given delimiter between adjacent strings. If "last" is given, it +will be used instead of "delim" between the last two strings. For +example, "join(["apples", "bananas", "pineapples"], ", ", +" and ") == "apples, bananas and pineapples"". + +"strings" can be any iterable over elements "x" which are +convertible to strings via "print(io::IOBuffer, x)". -Test whether a matrix is positive definite. """ -isposdef +join doc""" - isposdef!(A) -> Bool + joinpath(parts...) -> AbstractString + +Join path components into a full path. If some argument is an +absolute path, then prior components are dropped. -Test whether a matrix is positive definite, overwriting "A" in -the processes. """ -isposdef! +joinpath doc""" - istril(A) -> Bool + keys(collection) + +Return an iterator over all keys in a collection. +"collect(keys(d))" returns an array of keys. -Test whether a matrix is lower triangular. """ -istril +keys doc""" - istriu(A) -> Bool + kill(p::Process, signum=SIGTERM) + +Send a signal to a process. The default is to terminate the +process. + + kill(manager::FooManager, pid::Int, config::WorkerConfig) + +Implemented by cluster managers. It is called on the master +process, by "rmprocs". It should cause the remote worker +specified by "pid" to exit. +"Base.kill(manager::ClusterManager.....)" executes a remote +"exit()" on "pid" -Test whether a matrix is upper triangular. """ -istriu +kill doc""" - isdiag(A) -> Bool + kron(A, B) + +Kronecker tensor product of two vectors or two matrices. -Test whether a matrix is diagonal. """ -isdiag +kron doc""" - ishermitian(A) -> Bool + 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. -Test whether a matrix is Hermitian. """ -ishermitian +last doc""" - transpose(A) + launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + +Implemented by cluster managers. For every Julia worker launched by +this function, it should append a "WorkerConfig" entry to +"launched" and notify "launch_ntfy". The function MUST exit +once all workers, requested by "manager" have been launched. +"params" is a dictionary of all keyword arguments "addprocs" +was called with. -The transposition operator (".'"). """ -transpose +launch doc""" - transpose!(dest, src) + lbeta(x, y) + +Natural logarithm of the absolute value of the beta function +\log(|\operatorname{B}(x,y)|). -Transpose array "src" and store the result in the preallocated -array "dest", which should have a size corresponding to -"(size(src,2),size(src,1))". No in-place transposition is -supported and unexpected results will happen if *src* and *dest* -have overlapping memory regions. """ -transpose! +lbeta doc""" - ctranspose(A) + lcfirst(string) + +Returns "string" with the first character converted to lowercase. -The conjugate transposition operator ("'"). """ -ctranspose +lcfirst doc""" - ctranspose!(dest, src) + lcm(x, y) + +Least common (non-negative) multiple. -Conjugate transpose array "src" and store the result in the -preallocated array "dest", which should have a size corresponding -to "(size(src,2),size(src,1))". No in-place transposition is -supported and unexpected results will happen if *src* and *dest* -have overlapping memory regions. """ -ctranspose! +lcm doc""" - eigs(A[, B], ; nev=6, which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - -Computes eigenvalues "d" of "A" using Lanczos or Arnoldi -iterations for real symmetric or general nonsymmetric matrices -respectively. If "B" is provided, the generalized eigenproblem is -solved. + ldexp(x, n) -The following keyword arguments are supported: - * "nev": Number of eigenvalues +Compute x \times 2^n - * "ncv": Number of Krylov vectors used in the computation; - should satisfy +""" +ldexp - "nev+1 <= ncv <= n" for real symmetric problems and - "nev+2 <= ncv <= n" for other problems, where "n" is - the size of the input matrix "A". The default is "ncv = - max(20,2*nev+1)". Note that these restrictions limit the - input matrix "A" to be of dimension at least 2. +doc""" + ldltfact(A) -> LDLtFactorization - * "which": type of eigenvalues to compute. See the note - below. +Compute a factorization of a positive definite matrix "A" such +that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular +matrix and "d" is a vector with non-negative elements. - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \"which\" | type of eigenvalues | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LM\" | eigenvalues of largest magnitude (default) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SM\" | eigenvalues of smallest magnitude | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LR\" | eigenvalues of largest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SR\" | eigenvalues of smallest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - * "tol": tolerance (tol \le 0.0 defaults to - "DLAMCH('EPS')") +Compute the LDLt factorization of a sparse symmetric or Hermitian +matrix "A". A fill-reducing permutation is used. "F = +ldltfact(A)" is most frequently used to solve systems of equations +with "F\b", but also the methods "diag", "det", "logdet" +are defined for "F". You can also extract individual factors from +"F", using "F[:L]". However, since pivoting is on by default, +the factorization is internally represented as "A == P'*L*D*L'*P" +with a permutation matrix "P"; using just "L" without +accounting for "P" will give incorrect answers. To include the +effects of permutation, it's typically preferable to extact +"combined" factors like "PtL = F[:PtL]" (the equivalent of +"P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The +complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, +:DU, :PtLD, :DUP". - * "maxiter": Maximum number of iterations (default = 300) +Setting optional "shift" keyword argument computes the +factorization of "A+shift*I" instead of "A". If the "perm" +argument is nonempty, it should be a permutation of *1:size(A,1)* +giving the ordering to use (instead of CHOLMOD's default AMD +ordering). - * "sigma": Specifies the level shift used in inverse - iteration. If "nothing" (default), defaults to ordinary - (forward) iterations. Otherwise, find eigenvalues close to - "sigma" using shift and invert iterations. +The function calls the C library CHOLMOD and many other functions +from the library are wrapped but not exported. - * "ritzvec": Returns the Ritz vectors "v" (eigenvectors) - if "true" +""" +ldltfact - * "v0": starting vector from which to start the iterations +doc""" + leading_ones(x::Integer) -> Integer -"eigs" returns the "nev" requested eigenvalues in "d", the -corresponding Ritz vectors "v" (only if "ritzvec=true"), the -number of converged eigenvalues "nconv", the number of iterations -"niter" and the number of matrix vector multiplications -"nmult", as well as the final residual vector "resid". +Number of ones leading the binary representation of "x". -Note: The "sigma" and "which" keywords interact: the - description of eigenvalues searched for by "which" do _not_ - necessarily refer to the eigenvalues of "A", but rather the - linear operator constructed by the specification of the iteration - mode implied by "sigma". + julia> leading_ones(UInt32(2 ^ 32 - 2)) + 31 - +-----------------+------------------------------------+------------------------------------+ - | \"sigma\" | iteration mode | \"which\" refers to eigenvalues of | - +-----------------+------------------------------------+------------------------------------+ - | \"nothing\" | ordinary (forward) | A | - +-----------------+------------------------------------+------------------------------------+ - | real or complex | inverse with level shift \"sigma\" | (A - \\sigma I )^{-1} | - +-----------------+------------------------------------+------------------------------------+ """ -eigs +leading_ones doc""" - svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + leading_zeros(x::Integer) -> Integer -"svds" computes largest singular values "s" of "A" using -Lanczos or Arnoldi iterations. Uses "eigs()" underneath. +Number of zeros leading the binary representation of "x". -Inputs are: - * "A": Linear operator. It can either subtype of - "AbstractArray" (e.g., sparse matrix) or duck typed. For - duck typing "A" has to support "size(A)", "eltype(A)", - "A * vector" and "A' * vector". + julia> leading_zeros(Int32(1)) + 31 - * "nsv": Number of singular values. +""" +leading_zeros - * "ritzvec": Whether to return the left and right singular - vectors "left_sv" and "right_sv", default is "true". If - "false" the singular vectors are omitted from the output. +doc""" + length(A) -> Integer - * "tol": tolerance, see "eigs()". +Returns the number of elements in A - * "maxiter": Maximum number of iterations, see "eigs()". + length(collection) -> Integer -**Example**: +For ordered, indexable collections, the maximum index "i" for +which "getindex(collection, i)" is valid. For unordered +collections, the number of elements. + + length(s) + +The number of characters in string "s". - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) """ -svds +length doc""" - peakflops(n; parallel=false) + less(file::AbstractString[, line]) -"peakflops" computes the peak flop rate of the computer by using -double precision "Base.LinAlg.BLAS.gemm!()". By default, if no -arguments are specified, it multiplies a matrix of size "n x n", -where "n = 2000". If the underlying BLAS is using multiple -threads, higher flop rates are realized. The number of BLAS threads -can be set with "blas_set_num_threads(n)". +Show a file using the default pager, optionally providing a +starting line number. Returns to the julia prompt when you quit the +pager. -If the keyword argument "parallel" is set to "true", -"peakflops" is run in parallel on all the worker processors. The -flop rate of the entire parallel computer is returned. When running -in parallel, only 1 BLAS thread is used. The argument "n" still -refers to the size of the problem that is solved on each processor. -""" -peakflops + less(function[, types]) -doc""" - dot(n, X, incx, Y, incy) +Show the definition of a function using the default pager, +optionally specifying a tuple of types to indicate which method to +see. -Dot product of two vectors consisting of "n" elements of array -"X" with stride "incx" and "n" elements of array "Y" with -stride "incy". """ -Base.LinAlg.BLAS.dot +less doc""" - dotu(n, X, incx, Y, incy) + lexcmp(x, y) + +Compare "x" and "y" lexicographically and return -1, 0, or 1 +depending on whether "x" is less than, equal to, or greater than +"y", respectively. This function should be defined for +lexicographically comparable types, and "lexless" will call +"lexcmp" by default. -Dot function for two complex vectors. """ -Base.LinAlg.BLAS.dotu +lexcmp doc""" - dotc(n, X, incx, U, incy) + lexless(x, y) + +Determine whether "x" is lexicographically less than "y". -Dot function for two complex vectors conjugating the first vector. """ -Base.LinAlg.BLAS.dotc +lexless doc""" - blascopy!(n, X, incx, Y, incy) + lfact(x) + +Compute the logarithmic factorial of "x" -Copy "n" elements of array "X" with stride "incx" to array -"Y" with stride "incy". Returns "Y". """ -Base.LinAlg.BLAS.blascopy! +lfact doc""" - nrm2(n, X, incx) + lgamma(x) + +Compute the logarithm of the absolute value of "gamma()" for +"Real" "x", while for "Complex" "x" it computes the +logarithm of "gamma(x)". -2-norm of a vector consisting of "n" elements of array "X" with -stride "incx". """ -Base.LinAlg.BLAS.nrm2 +lgamma doc""" - asum(n, X, incx) + Base.linearindexing(A) -sum of the absolute values of the first "n" elements of array -"X" with stride "incx". -""" -Base.LinAlg.BLAS.asum +"linearindexing" defines how an AbstractArray most efficiently +accesses its elements. If "Base.linearindexing(A)" returns +"Base.LinearFast()", this means that linear indexing with only +one index is an efficient operation. If it instead returns +"Base.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 +traits-based mechanism to enable efficient generic code for all +array types. -doc""" - axpy!(a, X, Y) +An abstract array subtype "MyArray" that wishes to opt into fast +linear indexing behaviors should define "linearindexing" in the +type-domain: + + Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() -Overwrite "Y" with "a*X + Y". Returns "Y". """ -Base.LinAlg.BLAS.axpy! +linearindexing doc""" - scal!(n, a, X, incx) + linreg(x, y) -> [a; b] -Overwrite "X" with "a*X". Returns "X". -""" -Base.LinAlg.BLAS.scal! +Linear Regression. Returns "a" and "b" such that "a+b*x" is +the closest line to the given points "(x,y)". In other words, +this function determines parameters "[a, b]" that minimize the +squared error between "y" and "a+b*x". -doc""" - scal(n, a, X, incx) +**Example**: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + + linreg(x, y, w) + +Weighted least-squares linear regression. -Returns "a*X". """ -Base.LinAlg.BLAS.scal +linreg doc""" - ger!(alpha, x, y, A) + linspace(start, stop, n=100) + +Construct a range of "n" linearly spaced elements from "start" +to "stop". -Rank-1 update of the matrix "A" with vectors "x" and "y" as -"alpha*x*y' + A". """ -Base.LinAlg.BLAS.ger! +linspace doc""" - syr!(uplo, alpha, x, A) + listen([addr], port) -> TcpServer + +Listen on port on the address specified by "addr". By default +this listens on localhost only. To listen on all interfaces pass, +"IPv4(0)" or "IPv6(0)" as appropriate. + + listen(path) -> PipeServer + +Listens on/Creates a Named Pipe/Domain Socket -Rank-1 update of the symmetric matrix "A" with vector "x" as -"alpha*x*x.' + A". When "uplo" is 'U' the upper triangle of -"A" is updated ('L' for lower triangle). Returns "A". """ -Base.LinAlg.BLAS.syr! +listen doc""" - syrk!(uplo, trans, alpha, A, beta, C) + listenany(port_hint) -> (UInt16, TcpServer) + +Create a TcpServer on any port, using hint as a starting point. +Returns a tuple of the actual port that the server was created on +and the server itself. -Rank-k update of the symmetric matrix "C" as "alpha*A*A.' + -beta*C" or "alpha*A.'*A + beta*C" according to whether "trans" -is 'N' or 'T'. When "uplo" is 'U' the upper triangle of "C" is -updated ('L' for lower triangle). Returns "C". """ -Base.LinAlg.BLAS.syrk! +listenany doc""" - syrk(uplo, trans, alpha, A) + lock(l::ReentrantLock) + +Associates "l" with the current task. If "l" is already locked +by a different task, waits for it to become available. The same +task can acquire the lock multiple times. Each "lock" must be +matched by an "unlock" -Returns either the upper triangle or the lower triangle, according -to "uplo" ('U' or 'L'), of "alpha*A*A.'" or "alpha*A.'*A", -according to "trans" ('N' or 'T'). """ -Base.LinAlg.BLAS.syrk +lock doc""" - her!(uplo, alpha, x, A) + log(x) + +Compute the natural logarithm of "x". Throws "DomainError" for +negative "Real" arguments. Use complex negative arguments to +obtain complex results. + +There is an experimental variant in the "Base.Math.JuliaLibm" +module, which is typically faster and more accurate. + + log(b, x) + +Compute the base "b" logarithm of "x". Throws "DomainError" +for negative "Real" arguments. -Methods for complex arrays only. Rank-1 update of the Hermitian -matrix "A" with vector "x" as "alpha*x*x' + A". When -"uplo" is 'U' the upper triangle of "A" is updated ('L' for -lower triangle). Returns "A". """ -Base.LinAlg.BLAS.her! +log doc""" - herk!(uplo, trans, alpha, A, beta, C) + log10(x) + +Compute the logarithm of "x" to base 10. Throws "DomainError" +for negative "Real" arguments. -Methods for complex arrays only. Rank-k update of the Hermitian -matrix "C" as "alpha*A*A' + beta*C" or "alpha*A'*A + beta*C" -according to whether "trans" is 'N' or 'T'. When "uplo" is 'U' -the upper triangle of "C" is updated ('L' for lower triangle). -Returns "C". """ -Base.LinAlg.BLAS.herk! +log10 doc""" - herk(uplo, trans, alpha, A) + log1p(x) -Methods for complex arrays only. Returns either the upper triangle -or the lower triangle, according to "uplo" ('U' or 'L'), of -"alpha*A*A'" or "alpha*A'*A", according to "trans" ('N' or -'T'). -""" -Base.LinAlg.BLAS.herk +Accurate natural logarithm of "1+x". Throws "DomainError" for +"Real" arguments less than -1. -doc""" - gbmv!(trans, m, kl, ku, alpha, A, x, beta, y) +There is an experimental variant in the "Base.Math.JuliaLibm" +module, which is typically faster and more accurate. -Update vector "y" as "alpha*A*x + beta*y" or "alpha*A'*x + -beta*y" according to "trans" ('N' or 'T'). The matrix "A" is -a general band matrix of dimension "m" by "size(A,2)" with -"kl" sub-diagonals and "ku" super-diagonals. Returns the -updated "y". """ -Base.LinAlg.BLAS.gbmv! +log1p doc""" - gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + log2(x) + +Compute the logarithm of "x" to base 2. Throws "DomainError" +for negative "Real" arguments. -Returns "alpha*A*x" or "alpha*A'*x" according to "trans" ('N' -or 'T'). The matrix "A" is a general band matrix of dimension -"m" by "size(A,2)" with "kl" sub-diagonals and "ku" super- -diagonals. """ -Base.LinAlg.BLAS.gbmv +log2 doc""" - sbmv!(uplo, k, alpha, A, x, beta, y) + logabsdet(M) -Update vector "y" as "alpha*A*x + beta*y" where "A" is a a -symmetric band matrix of order "size(A,2)" with "k" super- -diagonals stored in the argument "A". The storage layout for -"A" is described the reference BLAS module, level-2 BLAS at -http://www.netlib.org/lapack/explore-html/. +Log of absolute value of determinant of real matrix. Equivalent to +"(log(abs(det(M))), sign(det(M)))", but may provide increased +accuracy and/or speed. -Returns the updated "y". """ -Base.LinAlg.BLAS.sbmv! +logabsdet doc""" - sbmv(uplo, k, alpha, A, x) + logdet(M) + +Log of matrix determinant. Equivalent to "log(det(M))", but may +provide increased accuracy and/or speed. -Returns "alpha*A*x" where "A" is a symmetric band matrix of -order "size(A,2)" with "k" super-diagonals stored in the -argument "A". """ -Base.LinAlg.BLAS.sbmv +logdet doc""" - sbmv(uplo, k, A, x) + logspace(start, stop, n=50) + +Construct a vector of "n" logarithmically spaced numbers from +"10^start" to "10^stop". -Returns "A*x" where "A" is a symmetric band matrix of order -"size(A,2)" with "k" super-diagonals stored in the argument -"A". """ -Base.LinAlg.BLAS.sbmv +logspace doc""" - gemm!(tA, tB, alpha, A, B, beta, C) + lowercase(string) + +Returns "string" with all characters converted to lowercase. -Update "C" as "alpha*A*B + beta*C" or the other three variants -according to "tA" (transpose "A") and "tB". Returns the -updated "C". """ -Base.LinAlg.BLAS.gemm! +lowercase doc""" - gemm(tA, tB, alpha, A, B) + lpad(string, n, p) + +Make a string at least "n" columns wide when printed, by padding +on the left with copies of "p". -Returns "alpha*A*B" or the other three variants according to -"tA" (transpose "A") and "tB". """ -Base.LinAlg.BLAS.gemm +lpad doc""" - gemm(tA, tB, A, B) + lstat(file) + +Like stat, but for symbolic links gets the info for the link itself +rather than the file it refers to. This function must be called on +a file path rather than a file object or a file descriptor. -Returns "A*B" or the other three variants according to "tA" -(transpose "A") and "tB". """ -Base.LinAlg.BLAS.gemm +lstat doc""" - gemv!(tA, alpha, A, x, beta, y) + lstrip(string[, chars]) + +Return "string" with any leading whitespace removed. If "chars" +(a character, or vector or set of characters) is provided, instead +remove characters contained in it. -Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + -beta*y" according to "tA" (transpose "A"). Returns the updated -"y". """ -Base.LinAlg.BLAS.gemv! +lstrip doc""" - gemv(tA, alpha, A, x) + ltoh(x) + +Converts the endianness of a value from Little-endian to that used +by the Host. -Returns "alpha*A*x" or "alpha*A'x" according to "tA" -(transpose "A"). """ -Base.LinAlg.BLAS.gemv +ltoh doc""" - gemv(tA, A, x) + lu(A) -> L, U, p + +Compute the LU factorization of "A", such that "A[p,:] = L*U". -Returns "A*x" or "A'x" according to "tA" (transpose "A"). """ -Base.LinAlg.BLAS.gemv +lu doc""" - symm!(side, ul, alpha, A, B, beta, C) + lufact(A[, pivot=Val{true}]) -> F -Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" -according to "side". "A" is assumed to be symmetric. Only the -"ul" triangle of "A" is used. Returns the updated "C". -""" -Base.LinAlg.BLAS.symm! +Compute the LU factorization of "A". The return type of "F" +depends on the type of "A". In most cases, if "A" is a subtype +"S" of AbstractMatrix with an element type "T`" supporting +"+", "-", "*" and "/" the return type is "LU{T,S{T}}". If +pivoting is chosen (default) the element type should also support +"abs" and "<". When "A" is sparse and have element of type +"Float32", "Float64", "Complex{Float32}", or +"Complex{Float64}" the return type is "UmfpackLU". Some +examples are shown in the table below. -doc""" - symm(side, ul, alpha, A, B) + +-------------------------+---------------------------+----------------------------------------------+ + | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | + +-------------------------+---------------------------+----------------------------------------------+ + | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | + +-------------------------+---------------------------+----------------------------------------------+ + | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | + +-------------------------+---------------------------+----------------------------------------------+ + +The individual components of the factorization "F" can be +accessed by indexing: + + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | + +-------------+-----------------------------------------+--------+--------------------------+---------------+ + + +--------------------+--------+--------------------------+---------------+ + | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | + +--------------------+--------+--------------------------+---------------+ + | \"/\" | ✓ | | | + +--------------------+--------+--------------------------+---------------+ + | \"\\\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"cond\" | ✓ | | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"det\" | ✓ | ✓ | ✓ | + +--------------------+--------+--------------------------+---------------+ + | \"logdet\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \"logabsdet\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ + | \"size\" | ✓ | ✓ | | + +--------------------+--------+--------------------------+---------------+ -Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" -is assumed to be symmetric. Only the "ul" triangle of "A" is -used. """ -Base.LinAlg.BLAS.symm +lufact doc""" - symm(side, ul, A, B) + lufact!(A) -> LU + +"lufact!" is the same as "lufact()", but saves space by +overwriting the input A, instead of creating a copy. For sparse +"A" the "nzval" field is not overwritten but the index fields, +"colptr" and "rowval" are decremented in place, converting from +1-based indices to 0-based indices. -Returns "A*B" or "B*A" according to "side". "A" is assumed -to be symmetric. Only the "ul" triangle of "A" is used. """ -Base.LinAlg.BLAS.symm +lufact! doc""" - symm(tA, tB, alpha, A, B) + lyap(A, C) + +Computes the solution "X" to the continuous Lyapunov equation +"AX + XA' + C = 0", where no eigenvalue of "A" has a zero real +part and no two eigenvalues are negative complex conjugates of each +other. -Returns "alpha*A*B" or the other three variants according to -"tA" (transpose "A") and "tB". """ -Base.LinAlg.BLAS.symm +lyap doc""" - symv!(ul, alpha, A, x, beta, y) + macroexpand(x) + +Takes the expression x and returns an equivalent expression with +all macros removed (expanded). -Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed -to be symmetric. Only the "ul" triangle of "A" is used. -Returns the updated "y". """ -Base.LinAlg.BLAS.symv! +macroexpand doc""" - symv(ul, alpha, A, x) + manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) -Returns "alpha*A*x". "A" is assumed to be symmetric. Only the -"ul" triangle of "A" is used. -""" -Base.LinAlg.BLAS.symv +Implemented by cluster managers. It is called on the master +process, during a worker's lifetime, with appropriate "op" +values: + + * with ":register"/":deregister" when a worker is added / + removed from the Julia worker pool. + + * with ":interrupt" when "interrupt(workers)" is called. + The "ClusterManager" should signal the appropriate worker + with an interrupt signal. -doc""" - symv(ul, A, x) + * with ":finalize" for cleanup purposes. -Returns "A*x". "A" is assumed to be symmetric. Only the -"ul" triangle of "A" is used. """ -Base.LinAlg.BLAS.symv +manage doc""" - trmm!(side, ul, tA, dA, alpha, A, B) + map(f, c...) -> collection -Update "B" as "alpha*A*B" or one of the other three variants -determined by "side" (A on left or right) and "tA" (transpose -A). Only the "ul" triangle of "A" is used. "dA" indicates if -"A" is unit-triangular (the diagonal is assumed to be all ones). -Returns the updated "B". -""" -Base.LinAlg.BLAS.trmm! +Transform collection "c" by applying "f" to each element. For +multiple collection arguments, apply "f" elementwise. -doc""" - trmm(side, ul, tA, dA, alpha, A, B) + 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 -Returns "alpha*A*B" or one of the other three variants determined -by "side" (A on left or right) and "tA" (transpose A). Only the -"ul" triangle of "A" is used. "dA" indicates if "A" is -unit-triangular (the diagonal is assumed to be all ones). """ -Base.LinAlg.BLAS.trmm +map doc""" - trsm!(side, ul, tA, dA, alpha, A, B) + map!(function, collection) -Overwrite "B" with the solution to "A*X = alpha*B" or one of -the other three variants determined by "side" (A on left or right -of "X") and "tA" (transpose A). Only the "ul" triangle of -"A" is used. "dA" indicates if "A" is unit-triangular (the -diagonal is assumed to be all ones). Returns the updated "B". -""" -Base.LinAlg.BLAS.trsm! +In-place version of "map()". -doc""" - trsm(side, ul, tA, dA, alpha, A, B) + 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. -Returns the solution to "A*X = alpha*B" or one of the other three -variants determined by "side" (A on left or right of "X") and -"tA" (transpose A). Only the "ul" triangle of "A" is used. -"dA" indicates if "A" is unit-triangular (the diagonal is -assumed to be all ones). """ -Base.LinAlg.BLAS.trsm +map! doc""" - trmv!(side, ul, tA, dA, alpha, A, b) + mapfoldl(f, op, v0, itr) -Update "b" as "alpha*A*b" or one of the other three variants -determined by "side" (A on left or right) and "tA" (transpose -A). Only the "ul" triangle of "A" is used. "dA" indicates if -"A" is unit-triangular (the diagonal is assumed to be all ones). -Returns the updated "b". -""" -Base.LinAlg.BLAS.trmv! +Like "mapreduce()", but with guaranteed left associativity. +"v0" will be used exactly once. -doc""" - trmv(side, ul, tA, dA, alpha, A, b) + 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)"). -Returns "alpha*A*b" or one of the other three variants determined -by "side" (A on left or right) and "tA" (transpose A). Only the -"ul" triangle of "A" is used. "dA" indicates if "A" is -unit-triangular (the diagonal is assumed to be all ones). """ -Base.LinAlg.BLAS.trmv +mapfoldl doc""" - trsv!(ul, tA, dA, A, b) + mapfoldr(f, op, v0, itr) -Overwrite "b" with the solution to "A*x = b" or one of the -other two variants determined by "tA" (transpose A) and "ul" -(triangle of "A" used). "dA" indicates if "A" is unit- -triangular (the diagonal is assumed to be all ones). Returns the -updated "b". -""" -Base.LinAlg.BLAS.trsv! +Like "mapreduce()", but with guaranteed right associativity. +"v0" will be used exactly once. -doc""" - trsv(ul, tA, dA, A, b) + 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)"). -Returns the solution to "A*x = b" or one of the other two -variants determined by "tA" (transpose A) and "ul" (triangle of -"A" is used.) "dA" indicates if "A" is unit-triangular (the -diagonal is assumed to be all ones). """ -Base.LinAlg.BLAS.trsv +mapfoldr doc""" - blas_set_num_threads(n) + mapreduce(f, op, v0, itr) -Set the number of threads the BLAS library should use. -""" -Base.LinAlg.BLAS.blas_set_num_threads +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. -doc""" - I +"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()". -An object of type "UniformScaling", representing an identity -matrix of any size. -""" -Base.LinAlg.BLAS.I + julia> mapreduce(x->x^2, +, [1:3;]) # == 1 + 4 + 9 + 14 -doc""" - -(x) +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. -Unary minus operator. -""" -- + mapreduce(f, op, itr) -doc""" - +(x, y...) +Like "mapreduce(f, op, v0, itr)". In general, this cannot be used +with empty collections (see "reduce(op, itr)"). -Addition operator. "x+y+z+..." calls this function with all -arguments, i.e. "+(x, y, z, ...)". """ -+ +mapreduce doc""" - -(x, y) + mapreducedim(f, op, A, dims[, initial]) + +Evaluates to the same as *reducedim(op, map(f, A), dims, +f(initial))*, but is generally faster because the intermediate +array is avoided. -Subtraction operator. """ -- +mapreducedim doc""" - *(x, y...) + mapslices(f, A, dims) + +Transform the given dimensions of array "A" using function "f". +"f" is called on each slice of "A" of the form +"A[...,:,...,:,...]". "dims" is an integer vector specifying +where the colons go in this expression. The results are +concatenated along the remaining dimensions. For example, if +"dims" is "[1,2]" and A is 4-dimensional, "f" is called on +"A[:,:,i,j]" for all "i" and "j". -Multiplication operator. "x*y*z*..." calls this function with all -arguments, i.e. "*(x, y, z, ...)". """ -Base.(:(*)) +mapslices doc""" - /(x, y) + mark(s) -Right division operator: multiplication of "x" by the inverse of -"y" on the right. Gives floating-point results for integer -arguments. -""" -Base.(:(/)) +Add a mark at the current position of stream "s". Returns the +marked position. -doc""" - \(x, y) +See also "unmark()", "reset()", "ismarked()" -Left division operator: multiplication of "y" by the inverse of -"x" on the left. Gives floating-point results for integer -arguments. """ -Base.(:(\)) +mark doc""" - ^(x, y) + match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + +Search for the first match of the regular expression "r" in "s" +and return a RegexMatch object containing the match, or nothing if +the match failed. The matching substring can be retrieved by +accessing "m.match" and the captured sequences can be retrieved +by accessing "m.captures" The optional "idx" argument specifies +an index at which to start the search. -Exponentiation operator. """ -Base.(:(^)) +match doc""" - .+(x, y) + matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + +Return a vector of the matching substrings from eachmatch. -Element-wise addition operator. """ -Base.(:(.+)) +matchall doc""" - .-(x, y) + max(x, y, ...) + +Return the maximum of the arguments. Operates elementwise over +arrays. -Element-wise subtraction operator. """ -Base.(:(.-)) +max doc""" - .*(x, y) + maxabs(itr) -Element-wise multiplication operator. -""" -Base.(:(.*)) +Compute the maximum absolute value of a collection of values. -doc""" - ./(x, y) + maxabs(A, dims) + +Compute the maximum absolute values over given dimensions. -Element-wise right division operator. """ -Base.(:(./)) +maxabs doc""" - .\(x, y) + maxabs!(r, A) + +Compute the maximum absolute values over the singleton dimensions +of "r", and write values to "r". -Element-wise left division operator. """ -Base.(:(.\)) +maxabs! doc""" - .^(x, y) + maximum(itr) -Element-wise exponentiation operator. -""" -Base.(:(.^)) +Returns the largest element in a collection. -doc""" - fma(x, y, z) + maximum(A, dims) + +Compute the maximum value of an array over the given dimensions. -Computes "x*y+z" without rounding the intermediate result -"x*y". On some systems this is significantly more expensive than -"x*y+z". "fma" is used to improve accuracy in certain -algorithms. See "muladd". """ -fma +maximum doc""" - muladd(x, y, z) + maximum!(r, A) + +Compute the maximum value of "A" over the singleton dimensions of +"r", and write results to "r". -Combined multiply-add, computes "x*y+z" in an efficient manner. -This may on some systems be equivalent to "x*y+z", or to -"fma(x,y,z)". "muladd" is used to improve performance. See -"fma". """ -muladd +maximum! doc""" - div(x, y) -÷(x, y) + maxintfloat(type) + +The largest integer losslessly representable by the given floating- +point type -The quotient from Euclidean division. Computes "x/y", truncated -to an integer. """ -div +maxintfloat doc""" - fld(x, y) + mean(v[, region]) + +Compute the mean of whole array "v", or optionally along the +dimensions in "region". Note: Julia does not ignore "NaN" +values in the computation. For applications requiring the handling +of missing data, the "DataArray" package is recommended. -Largest integer less than or equal to "x/y". """ -fld +mean doc""" - cld(x, y) + mean!(r, v) + +Compute the mean of "v" over the singleton dimensions of "r", +and write results to "r". -Smallest integer larger than or equal to "x/y". """ -cld +mean! doc""" - mod(x, y) + median(v) + +Compute the median of a vector "v". "NaN" is returned if the +data contains any "NaN" values. For applications requiring the +handling of missing data, the "DataArrays" package is +recommended. -Modulus after division, returning in the range [0,``y``), if "y" -is positive, or ("y",0] if "y" is negative. """ -mod +median doc""" - mod2pi(x) + median!(v) -Modulus after division by 2pi, returning in the range [0,2pi). +Like "median", but may overwrite the input vector. -This function computes a floating point representation of the -modulus after division by numerically exact 2pi, and is therefore -not exactly the same as mod(x,2pi), which would compute the modulus -of x relative to division by the floating-point number 2pi. """ -mod2pi +median! doc""" - rem(x, y) -%(x, y) + merge(collection, others...) -Remainder from Euclidean division, returning a value of the same -sign as``x``, and smaller in magnitude than "y". This value is -always exact. -""" -rem +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. -doc""" - divrem(x, y) + julia> a = Dict("foo" => 0.0, "bar" => 42.0) + Dict{ASCIIString,Float64} with 2 entries: + "bar" => 42.0 + "foo" => 0.0 -The quotient and remainder from Euclidean division. Equivalent to -"(x÷y, x%y)". -""" -divrem + julia> b = Dict(utf8("baz") => 17, utf8("bar") => 4711) + Dict{UTF8String,Int64} with 2 entries: + "bar" => 4711 + "baz" => 17 -doc""" - fldmod(x, y) + julia> merge(a, b) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 4711.0 + "baz" => 17.0 + "foo" => 0.0 + + julia> merge(b, a) + Dict{UTF8String,Float64} with 3 entries: + "bar" => 42.0 + "baz" => 17.0 + "foo" => 0.0 -The floored quotient and modulus after division. Equivalent to -"(fld(x,y), mod(x,y))". """ -fldmod +merge doc""" - mod1(x, m) + merge!(collection, others...) + +Update collection with pairs from the other collections -Modulus after division, returning in the range (0,m] """ -mod1 +merge! doc""" - rem1(x, m) + method_exists(f, Tuple type) -> Bool -Remainder after division, returning in the range (0,m] -""" -rem1 +Determine whether the given generic function has a method matching +the given "Tuple" of argument types. -doc""" - //(num, den) + julia> method_exists(length, Tuple{Array}) + true -Divide two integers or rational numbers, giving a "Rational" -result. """ -Base.(:(//)) +method_exists doc""" - rationalize([Type=Int], x; tol=eps(x)) + methods(f[, types]) -Approximate floating point number "x" as a Rational number with -components of the given integer type. The result will differ from -"x" by no more than "tol". -""" -rationalize +Returns the method table for "f". -doc""" - num(x) +If "types" is specified, returns an array of methods whose types +match. -Numerator of the rational representation of "x" """ -num +methods doc""" - den(x) + methodswith(typ[, module or function][, showparents]) -Denominator of the rational representation of "x" -""" -den +Return an array of methods with an argument of type "typ". If +optional "showparents" is "true", also return arguments with a +parent type of "typ", excluding type "Any". -doc""" - <<(x, n) +The optional second argument restricts the search to a particular +module or function. -Left bit shift operator. """ -Base.(:(<<)) +methodswith doc""" - >>(x, n) + middle(x) -Right bit shift operator, preserving the sign of "x". -""" -Base.(:(>>)) +Compute the middle of a scalar value, which is equivalent to "x" +itself, but of the type of "middle(x, x)" for consistency. -doc""" - >>>(x, n) + middle(x, y) + +Compute the middle of two reals "x" and "y", which is +equivalent in both value and type to computing their mean ("(x + +y) / 2"). + + middle(range) + +Compute the middle of a range, which consists in computing the mean +of its extrema. Since a range is sorted, the mean is performed with +the first and last element. + + middle(array) + +Compute the middle of an array, which consists in finding its +extrema and then computing their mean. -Unsigned right bit shift operator. """ -Base.(:(>>>)) +middle doc""" - :(start[, step], stop) + midpoints(e) + +Compute the midpoints of the bins with edges "e". The result is a +vector/range of length "length(e) - 1". Note: Julia does not +ignore "NaN" values in the computation. -Range operator. "a:b" constructs a range from "a" to "b" with -a step size of 1, and "a:s:b" is similar but uses a step size of -"s". These syntaxes call the function "colon". The colon is -also used in indexing to select whole dimensions. """ -Base.(:(:)) +midpoints doc""" - colon(start[, step], stop) + mimewritable(mime, x) + +Returns a boolean value indicating whether or not the object "x" +can be written as the given "mime" type. (By default, this is +determined automatically by the existence of the corresponding +"writemime" function for "typeof(x)".) -Called by ":" syntax for constructing ranges. """ -colon +mimewritable doc""" - range(start[, step], length) + min(x, y, ...) + +Return the minimum of the arguments. Operates elementwise over +arrays. -Construct a range by length, given a starting value and optional -step (defaults to 1). """ -range +min doc""" - ==(x, y) + minabs(itr) -Generic equality operator, giving a single "Bool" result. Falls -back to "===". Should be implemented for all types with a notion -of equality, based on the abstract value that an instance -represents. For example, all numeric types are compared by numeric -value, ignoring type. Strings are compared as sequences of -characters, ignoring encoding. +Compute the minimum absolute value of a collection of values. -Follows IEEE semantics for floating-point numbers. + minabs(A, dims) -Collections should generally implement "==" by calling "==" -recursively on all contents. +Compute the minimum absolute values over given dimensions. -New numeric types should implement this function for two arguments -of the new type, and handle comparison to other types via promotion -rules where possible. """ -Base.(:(==)) +minabs doc""" - !=(x, y) -≠(x, y) + minabs!(r, A) + +Compute the minimum absolute values over the singleton dimensions +of "r", and write values to "r". -Not-equals comparison operator. Always gives the opposite answer as -"==". New types should generally not implement this, and rely on -the fallback definition "!=(x,y) = !(x==y)" instead. """ -Base.(:(!=)) +minabs! doc""" - ===(x, y) -≡(x, y) + minimum(itr) + +Returns the smallest element in a collection. + + minimum(A, dims) + +Compute the minimum value of an array over the given dimensions. -See the "is()" operator """ -Base.(:(===)) +minimum doc""" - !==(x, y) -≢(x, y) + minimum!(r, A) + +Compute the minimum value of "A" over the singleton dimensions of +"r", and write results to "r". -Equivalent to "!is(x, y)" """ -Base.(:(!==)) +minimum! doc""" - <(x, y) + minmax(x, y) + +Return "(min(x,y), max(x,y))". See also: "extrema()" that +returns "(minimum(x), maximum(x))" -Less-than comparison operator. New numeric types should implement -this function for two arguments of the new type. Because of the -behavior of floating-point NaN values, "<" implements a partial -order. Types with a canonical partial order should implement "<", -and types with a canonical total order should implement "isless". """ -Base.(:(<)) +minmax doc""" - <=(x, y) -≤(x, y) + mkdir(path[, mode]) + +Make a new directory with name "path" and permissions "mode". +"mode" defaults to 0o777, modified by the current file creation +mask. -Less-than-or-equals comparison operator. """ -Base.(:(<=)) +mkdir doc""" - >(x, y) + mkpath(path[, mode]) + +Create all directories in the given "path", with permissions +"mode". "mode" defaults to 0o777, modified by the current file +creation mask. -Greater-than comparison operator. Generally, new types should -implement "<" instead of this function, and rely on the fallback -definition ">(x,y) = y)) +mkpath doc""" - >=(x, y) -≥(x, y) + mktemp([parent=tempdir()]) + +Returns "(path, io)", where "path" is the path of a new +temporary file in "parent" and "io" is an open file object for +this path. -Greater-than-or-equals comparison operator. """ -Base.(:(>=)) +mktemp doc""" - .==(x, y) + mktempdir([parent=tempdir()]) + +Create a temporary directory in the "parent" directory and return +its path. -Element-wise equality comparison operator. """ -Base.(:(.==)) +mktempdir doc""" - .!=(x, y) -.≠(x, y) + mmap_array(type, dims, stream[, offset]) -Element-wise not-equals comparison operator. -""" -Base.(:(.!=)) +Create an "Array" whose values are linked to a file, using +memory-mapping. This provides a convenient way of working with data +too large to fit in the computer's memory. -doc""" - .<(x, y) +The type determines how the bytes of the array are interpreted. +Note that the file must be stored in binary format, and no format +conversions are possible (this is a limitation of operating +systems, not Julia). + +"dims" is a tuple specifying the size of the array. + +The file is passed via the stream argument. When you initialize +the stream, use ""r"" for a "read-only" array, and ""w+"" +to create a new array used to write values to disk. + +Optionally, you can specify an offset (in bytes) if, for example, +you want to skip over a header in the file. The default value for +the offset is the current stream position. + +For example, the following code: + + # Create a file for mmapping + # (you could alternatively use mmap_array to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) + + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = mmap_array(Int, (m,n), s) + +creates a "m"-by-"n" "Matrix{Int}", linked to the file +associated with stream "s". + +A more portable file would need to encode the word size---32 bit or +64 bit---and endianness information in the header. In practice, +consider encoding binary data using standard formats like HDF5 +(which can be used with memory-mapping). -Element-wise less-than comparison operator. """ -Base.(:(.<)) +mmap_array doc""" - .<=(x, y) -.≤(x, y) + mmap_bitarray([type], dims, stream[, offset]) + +Create a "BitArray" whose values are linked to a file, using +memory-mapping; it has the same purpose, works in the same way, and +has the same arguments, as "mmap_array()", but the byte +representation is different. The "type" parameter is optional, +and must be "Bool" if given. + +**Example**: "B = mmap_bitarray((25,30000), s)" + +This would create a 25-by-30000 "BitArray", linked to the file +associated with stream "s". -Element-wise less-than-or-equals comparison operator. """ -Base.(:(.<=)) +mmap_bitarray doc""" - .>(x, y) + mod(x, y) + +Modulus after division, returning in the range [0,``y``), if "y" +is positive, or ("y",0] if "y" is negative. -Element-wise greater-than comparison operator. """ -Base.(:(.>)) +mod doc""" - .>=(x, y) -.≥(x, y) + mod1(x, m) + +Modulus after division, returning in the range (0,m] -Element-wise greater-than-or-equals comparison operator. """ -Base.(:(.>=)) +mod1 doc""" - cmp(x, y) + mod2pi(x) + +Modulus after division by 2pi, returning in the range [0,2pi). + +This function computes a floating point representation of the +modulus after division by numerically exact 2pi, and is therefore +not exactly the same as mod(x,2pi), which would compute the modulus +of x relative to division by the floating-point number 2pi. -Return -1, 0, or 1 depending on whether "x" is less than, equal -to, or greater than "y", respectively. Uses the total order -implemented by "isless". For floating-point numbers, uses "<" -but throws an error for unordered arguments. """ -cmp +mod2pi doc""" - ~(x) + modf(x) + +Return a tuple (fpart,ipart) of the fractional and integral parts +of a number. Both parts have the same sign as the argument. -Bitwise not """ -~ +modf doc""" - &(x, y) + module_name(m::Module) -> Symbol + +Get the name of a module as a symbol. -Bitwise and """ -& +module_name doc""" - |(x, y) + module_parent(m::Module) -> Module + +Get a module's enclosing module. "Main" is its own parent. -Bitwise or """ -Base.(:(|)) +module_parent doc""" - \$(x, y) + msync(array) + +Forces synchronization between the in-memory version of a memory- +mapped "Array" or "BitArray" and the on-disk version. -Bitwise exclusive or """ -$ +msync doc""" - !(x) + mtime(file) + +Equivalent to stat(file).mtime -Boolean not """ -! +mtime doc""" - A_ldiv_Bc(a, b) + muladd(x, y, z) + +Combined multiply-add, computes "x*y+z" in an efficient manner. +This may on some systems be equivalent to "x*y+z", or to +"fma(x,y,z)". "muladd" is used to improve performance. See +"fma". -Matrix operator A \ B^H """ -A_ldiv_Bc +muladd doc""" - A_ldiv_Bt(a, b) + mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + +Move the file, link, or directory from *src* to *dest*. +"remove_destination=true" will first remove an existing *dst*. -Matrix operator A \ B^T """ -A_ldiv_Bt +mv doc""" - A_mul_B!(Y, A, B) -> Y - -Calculates the matrix-matrix or matrix-vector product *A B* and -stores the result in *Y*, overwriting the existing value of *Y*. + myid() - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); +Get the id of the current process. - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 """ -A_mul_B! +myid doc""" - A_mul_Bc(...) + names(x::Module[, all=false[, imported=false]]) + +Get an array of the names exported by a module, with optionally +more module globals according to the additional parameters. -Matrix operator A B^H """ -A_mul_Bc +names doc""" - A_mul_Bt(...) + nan(f) + +Returns NaN (not-a-number) of the floating point type "f" or of +the same floating point type as "f" -Matrix operator A B^T """ -A_mul_Bt +nan doc""" - A_rdiv_Bc(...) + nb_available(stream) + +Returns the number of bytes available for reading before a read +from this stream or buffer will block. -Matrix operator A / B^H """ -A_rdiv_Bc +nb_available doc""" - A_rdiv_Bt(a, b) + ndigits(n, b) + +Compute the number of digits in number "n" written in base "b". -Matrix operator A / B^T """ -A_rdiv_Bt +ndigits doc""" - Ac_ldiv_B(...) + ndims(A) -> Integer + +Returns the number of dimensions of A -Matrix operator A^H \ B """ -Ac_ldiv_B +ndims doc""" - Ac_ldiv_Bc(...) + next(iter, state) -> item, state + +For a given iterable object and iteration state, return the current +item and the next iteration state -Matrix operator A^H \ B^H """ -Ac_ldiv_Bc +next doc""" - Ac_mul_B(...) + nextfloat(f) + +Get the next floating point number in lexicographic order -Matrix operator A^H B """ -Ac_mul_B +nextfloat doc""" - Ac_mul_Bc(...) + nextind(str, i) + +Get the next valid string index after "i". Returns a value +greater than "endof(str)" at or after the end of the string. -Matrix operator A^H B^H """ -Ac_mul_Bc +nextind doc""" - Ac_rdiv_B(a, b) + nextpow(a, x) + +The smallest "a^n" not less than "x", where "n" is a non- +negative integer. "a" must be greater than 1, and "x" must be +greater than 0. -Matrix operator A^H / B """ -Ac_rdiv_B +nextpow doc""" - Ac_rdiv_Bc(a, b) + nextpow2(n) + +The smallest power of two not less than "n". Returns 0 for +"n==0", and returns "-nextpow2(-n)" for negative arguments. -Matrix operator A^H / B^H """ -Ac_rdiv_Bc +nextpow2 doc""" - At_ldiv_B(...) + nextprod([k_1, k_2, ...], n) + +Next integer not less than "n" that can be written as \prod +k_i^{p_i} for integers p_1, p_2, etc. -Matrix operator A^T \ B """ -At_ldiv_B +nextprod doc""" - At_ldiv_Bt(...) + nfields(x::DataType) -> Int + +Get the number of fields of a data type. -Matrix operator A^T \ B^T """ -At_ldiv_Bt +nfields doc""" - At_mul_B(...) + nnz(A) + +Returns the number of stored (filled) elements in a sparse matrix. -Matrix operator A^T B """ -At_mul_B +nnz doc""" - At_mul_Bt(...) + nonzeros(A) + +Return a vector of the structural nonzero values in sparse matrix +"A". This includes zeros that are explicitly stored in the sparse +matrix. The returned vector points directly to the internal nonzero +storage of "A", and any modifications to the returned vector will +mutate "A" as well. See "rowvals(A)" and "nzrange(A, col)". -Matrix operator A^T B^T """ -At_mul_Bt +nonzeros doc""" - At_rdiv_B(a, b) + norm(A[, p]) -Matrix operator A^T / B -""" -At_rdiv_B +Compute the "p"-norm of a vector or the operator norm of a matrix +"A", defaulting to the "p=2"-norm. -doc""" - At_rdiv_Bt(a, b) +For vectors, "p" can assume any numeric value (even though not +all values produce a mathematically valid vector norm). In +particular, "norm(A, Inf)" returns the largest value in +"abs(A)", whereas "norm(A, -Inf)" returns the smallest. + +For matrices, valid values of "p" are "1", "2", or "Inf". +(Note that for sparse matrices, "p=2" is currently not +implemented.) Use "vecnorm()" to compute the Frobenius norm. -Matrix operator A^T / B^T """ -At_rdiv_Bt +norm doc""" - isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) + normalize_string(s, normalform::Symbol) -Inexact equality comparison - behaves slightly different depending -on types of input args: +Normalize the string "s" according to one of the four "normal +forms" of the Unicode standard: "normalform" can be ":NFC", +":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical +composition) and D (canonical decomposition) convert different +visually identical representations of the same abstract string into +a single canonical form, with form C being more compact. Normal +forms KC and KD additionally canonicalize "compatibility +equivalents": they convert characters that are abstractly similar +but visually distinct into a single canonical choice (e.g. they +expand ligatures into the individual characters), with form KC +being more compact. -* For "FloatingPoint" numbers, "isapprox" returns "true" if - "abs(x-y) <= atol + rtol*max(abs(x), abs(y))". +Alternatively, finer control and additional transformations may be +be obtained by calling *normalize_string(s; keywords...)*, where +any number of the following boolean keywords options (which all +default to "false" except for "compose") are specified: -* For "Integer" and "Rational" numbers, "isapprox" returns - "true" if "abs(x-y) <= atol". The *rtol* argument is ignored. - If one of "x" and "y" is "FloatingPoint", the other is - promoted, and the method above is called instead. +* "compose=false": do not perform canonical composition -* For "Complex" numbers, the distance in the complex plane is - compared, using the same criterion as above. +* "decompose=true": do canonical decomposition instead of + canonical composition ("compose=true" is ignored if present) -For default tolerance arguments, "maxeps = max(eps(abs(x)), -eps(abs(y)))". -""" -isapprox +* "compat=true": compatibility equivalents are canonicalized -doc""" - sin(x) +* "casefold=true": perform Unicode case folding, e.g. for case- + insensitive string comparison -Compute sine of "x", where "x" is in radians -""" -sin +* "newline2lf=true", "newline2ls=true", or + "newline2ps=true": convert various newline sequences (LF, CRLF, + CR, NEL) into a linefeed (LF), line-separation (LS), or + paragraph-separation (PS) character, respectively -doc""" - cos(x) +* "stripmark=true": strip diacritical marks (e.g. accents) -Compute cosine of "x", where "x" is in radians -""" -cos +* "stripignore=true": strip Unicode's "default ignorable" + characters (e.g. the soft hyphen or the left-to-right marker) -doc""" - tan(x) +* "stripcc=true": strip control characters; horizontal tabs and + form feeds are converted to spaces; newlines are also converted + to spaces unless a newline-conversion flag was specified -Compute tangent of "x", where "x" is in radians -""" -tan +* "rejectna=true": throw an error if unassigned code points are + found -doc""" - sind(x) +* "stable=true": enforce Unicode Versioning Stability + +For example, NFKC corresponds to the options "compose=true, +compat=true, stable=true". -Compute sine of "x", where "x" is in degrees """ -sind +normalize_string doc""" - cosd(x) + normpath(path::AbstractString) -> AbstractString + +Normalize a path, removing "." and ".." entries. -Compute cosine of "x", where "x" is in degrees """ -cosd +normpath doc""" - tand(x) + nothing + +The singleton instance of type "Void", used by convention when +there is no value to return (as in a C "void" function). Can be +converted to an empty "Nullable" value. -Compute tangent of "x", where "x" is in degrees """ -tand +nothing doc""" - sinpi(x) + notify(condition, val=nothing; all=true, error=false) + +Wake up tasks waiting for a condition, passing them "val". If +"all" is true (the default), all waiting tasks are woken, +otherwise only one is. If "error" is true, the passed value is +raised as an exception in the woken tasks. -Compute \sin(\pi x) more accurately than "sin(pi*x)", -especially for large "x". """ -sinpi +notify doc""" - cospi(x) + nprocs() + +Get the number of available processes. -Compute \cos(\pi x) more accurately than "cos(pi*x)", -especially for large "x". """ -cospi +nprocs doc""" - sinh(x) + nthperm(v, k) + +Compute the kth lexicographic permutation of a vector. + + nthperm(p) + +Return the "k" that generated permutation "p". Note that +"nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". -Compute hyperbolic sine of "x" """ -sinh +nthperm doc""" - cosh(x) + nthperm!(v, k) + +In-place version of "nthperm()". -Compute hyperbolic cosine of "x" """ -cosh +nthperm! doc""" - tanh(x) + ntoh(x) + +Converts the endianness of a value from Network byte order (big- +endian) to that used by the Host. -Compute hyperbolic tangent of "x" """ -tanh +ntoh doc""" - asin(x) + ntuple(f::Function, n) + +Create a tuple of length "n", computing each element as "f(i)", +where "i" is the index of the element. -Compute the inverse sine of "x", where the output is in radians """ -asin +ntuple doc""" - acos(x) + nullspace(M) + +Basis for nullspace of "M". -Compute the inverse cosine of "x", where the output is in radians """ -acos +nullspace doc""" - atan(x) + num(x) + +Numerator of the rational representation of "x" -Compute the inverse tangent of "x", where the output is in -radians """ -atan +num doc""" - atan2(y, x) + num2hex(f) + +Get a hexadecimal string of the binary representation of a floating +point number -Compute the inverse tangent of "y/x", using the signs of both -"x" and "y" to determine the quadrant of the return value. """ -atan2 +num2hex doc""" - asind(x) + nworkers() + +Get the number of available worker processes. This is one less than +nprocs(). Equal to nprocs() if nprocs() == 1. -Compute the inverse sine of "x", where the output is in degrees """ -asind +nworkers doc""" - acosd(x) + nzrange(A, col) -Compute the inverse cosine of "x", where the output is in degrees -""" -acosd +Return the range of indices to the structural nonzero values of a +sparse matrix column. In conjunction with "nonzeros(A)" and +"rowvals(A)", this allows for convenient iterating over a sparse +matrix -doc""" - atand(x) + 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 -Compute the inverse tangent of "x", where the output is in -degrees """ -atand +nzrange doc""" - sec(x) + object_id(x) + +Get a unique integer id for "x". "object_id(x)==object_id(y)" +if and only if "is(x,y)". -Compute the secant of "x", where "x" is in radians """ -sec +object_id doc""" - csc(x) + oct(n[, pad]) + +Convert an integer to an octal string, optionally specifying a +number of digits to pad to. -Compute the cosecant of "x", where "x" is in radians """ -csc +oct doc""" - cot(x) + oftype(x, y) + +Convert "y" to the type of "x" ("convert(typeof(x), y)"). -Compute the cotangent of "x", where "x" is in radians """ -cot +oftype doc""" - secd(x) + one(x) + +Get the multiplicative identity element for the type of x (x can +also specify the type itself). For matrices, returns an identity +matrix of the appropriate size and type. -Compute the secant of "x", where "x" is in degrees """ -secd +one doc""" - cscd(x) + ones(type, dims) -Compute the cosecant of "x", where "x" is in degrees -""" -cscd +Create an array of all ones of specified type. The type defaults to +Float64 if not specified. -doc""" - cotd(x) + ones(A) + +Create an array of all ones with the same element type and shape as +A. -Compute the cotangent of "x", where "x" is in degrees """ -cotd +ones doc""" - asec(x) + open(command, mode::AbstractString="r", stdio=DevNull) -Compute the inverse secant of "x", where the output is in radians -""" -asec +Start running "command" asynchronously, and return a tuple +"(stream,process)". If "mode" is ""r"", then "stream" +reads from the process's standard output and "stdio" optionally +specifies the process's standard input stream. If "mode" is +""w"", then "stream" writes to the process's standard input +and "stdio" optionally specifies the process's standard output +stream. -doc""" - acsc(x) + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) -Compute the inverse cosecant of "x", where the output is in -radians -""" -acsc +Similar to "open(command, mode, stdio)", but calls "f(stream)" +on the resulting read or write stream, then closes the stream and +waits for the process to complete. Returns the value returned by +"f". -doc""" - acot(x) + open(file_name[, read, write, create, truncate, append]) -> IOStream -Compute the inverse cotangent of "x", where the output is in -radians -""" -acot +Open a file in a mode specified by five boolean arguments. The +default is to open files for reading only. Returns a stream for +accessing the file. -doc""" - asecd(x) + open(file_name[, mode]) -> IOStream -Compute the inverse secant of "x", where the output is in degrees -""" -asecd +Alternate syntax for open, where a string-based mode specifier is +used instead of the five booleans. The values of "mode" +correspond to those from "fopen(3)" or Perl "open", and are +equivalent to setting the following boolean groups: -doc""" - acscd(x) ++------+-----------------------------------+ +| r | read | ++------+-----------------------------------+ +| r+ | read, write | ++------+-----------------------------------+ +| w | write, create, truncate | ++------+-----------------------------------+ +| w+ | read, write, create, truncate | ++------+-----------------------------------+ +| a | write, create, append | ++------+-----------------------------------+ +| a+ | read, write, create, append | ++------+-----------------------------------+ -Compute the inverse cosecant of "x", where the output is in -degrees -""" -acscd + open(f::function, args...) -doc""" - acotd(x) +Apply the function "f" to the result of "open(args...)" and +close the resulting file descriptor upon completion. + +**Example**: "open(readall, "file.txt")" -Compute the inverse cotangent of "x", where the output is in -degrees """ -acotd +open doc""" - sech(x) + operm(file) + +Like uperm but gets the permissions for people who neither own the +file nor are a member of the group owning the file -Compute the hyperbolic secant of "x" """ -sech +operm doc""" - csch(x) + ordschur(Q, T, select) -> Schur -Compute the hyperbolic cosecant of "x" -""" -csch +Reorders the Schur factorization of a real matrix "A=Q*T*Q'" +according to the logical array "select" returning a Schur object +"F". The selected eigenvalues appear in the leading diagonal of +"F[:Schur]" and the the corresponding leading columns of +"F[:vectors]" form an orthonormal basis of the corresponding +right invariant subspace. A complex conjugate pair of eigenvalues +must be either both included or excluded via "select". -doc""" - coth(x) + ordschur(S, select) -> Schur -Compute the hyperbolic cotangent of "x" -""" -coth +Reorders the Schur factorization "S" of type "Schur". -doc""" - asinh(x) + ordschur(S, T, Q, Z, select) -> GeneralizedSchur -Compute the inverse hyperbolic sine of "x" -""" -asinh +Reorders the Generalized Schur factorization of a matrix "(A, B) = +(Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" +and returns a GeneralizedSchur object "GS". The selected +eigenvalues appear in the leading diagonal of both``(GS[:S], +GS[:T])`` and the left and right unitary/orthogonal Schur vectors +are also reordered such that "(A, B) = GS[:Q]*(GS[:S], +GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of +"A" and "B" can still be obtained with +"GS[:alpha]./GS[:beta]". -doc""" - acosh(x) + ordschur(GS, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a Generalized Schur +object. See "ordschur()". -Compute the inverse hyperbolic cosine of "x" """ -acosh +ordschur doc""" - atanh(x) + ordschur!(Q, T, select) -> Schur + +Reorders the Schur factorization of a real matrix "A=Q*T*Q'", +overwriting "Q" and "T" in the process. See "ordschur()" + + ordschur!(S, select) -> Schur + +Reorders the Schur factorization "S" of type "Schur", +overwriting "S" in the process. See "ordschur()" + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a matrix by +overwriting the matrices "(S, T, Q, Z)" in the process. See +"ordschur()". + + ordschur!(GS, select) -> GeneralizedSchur + +Reorders the Generalized Schur factorization of a Generalized Schur +object by overwriting the object with the new factorization. See +"ordschur()". -Compute the inverse hyperbolic tangent of "x" """ -atanh +ordschur! doc""" - asech(x) + parent(A) + +Returns the "parent array" of an array view type (e.g., +SubArray), or the array itself if it is not a view -Compute the inverse hyperbolic secant of "x" """ -asech +parent doc""" - acsch(x) + parentindexes(A) + +From an array view "A", returns the corresponding indexes in the +parent -Compute the inverse hyperbolic cosecant of "x" """ -acsch +parentindexes doc""" - acoth(x) + parse(str, start; greedy=true, raise=true) -Compute the inverse hyperbolic cotangent of "x" -""" -acoth +Parse the expression string and return an expression (which could +later be passed to eval for execution). Start is the index of the +first character to start parsing. If "greedy" is true (default), +"parse" will try to consume as much input as it can; otherwise, +it will stop as soon as it has parsed a valid expression. +Incomplete but otherwise syntactically valid expressions will +return "Expr(:incomplete, "(error message)")". If "raise" is +true (default), syntax errors other than incomplete expressions +will raise an error. If "raise" is false, "parse" will return +an expression that will raise an error upon evaluation. -doc""" - sinc(x) + parse(str; raise=true) -Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. -""" -sinc +Parse the whole string greedily, returning a single expression. An +error is thrown if there are additional characters after the first +expression. If "raise" is true (default), syntax errors will +raise an error; otherwise, "parse" will return an expression that +will raise an error upon evaluation. -doc""" - cosc(x) + parse(type, str[, base]) + +Parse a string as a number. If the type is an integer type, then a +base can be specified (the default is 10). If the type is a +floating point type, the string is parsed as a decimal floating +point number. If the string does not contain a valid number, an +error is raised. -Compute \cos(\pi x) / x - \sin(\pi x) / (\pi x^2) if x \neq -0, and 0 if x = 0. This is the derivative of "sinc(x)". """ -cosc +parse doc""" - deg2rad(x) + parseip(addr) + +Parse a string specifying an IPv4 or IPv6 ip address. -Convert "x" from degrees to radians """ -deg2rad +parseip doc""" - rad2deg(x) + partitions(n) -Convert "x" from radians to degrees -""" -rad2deg +Generate all integer arrays that sum to "n". Because the number +of partitions can be very large, this function returns an iterator +object. Use "collect(partitions(n))" to get an array of all +partitions. The number of partitions to generate can be efficiently +computed using "length(partitions(n))". -doc""" - hypot(x, y) + partitions(n, m) -Compute the \sqrt{x^2+y^2} avoiding overflow and underflow -""" -hypot +Generate all arrays of "m" integers that sum to "n". Because +the number of partitions can be very large, this function returns +an iterator object. Use "collect(partitions(n,m))" to get an +array of all partitions. The number of partitions to generate can +be efficiently computed using "length(partitions(n,m))". -doc""" - log(x) + partitions(array) -Compute the natural logarithm of "x". Throws "DomainError" for -negative "Real" arguments. Use complex negative arguments to -obtain complex results. +Generate all set partitions of the elements of an array, +represented as arrays of arrays. Because the number of partitions +can be very large, this function returns an iterator object. Use +"collect(partitions(array))" to get an array of all partitions. +The number of partitions to generate can be efficiently computed +using "length(partitions(array))". -There is an experimental variant in the "Base.Math.JuliaLibm" -module, which is typically faster and more accurate. -""" -log + partitions(array, m) -doc""" - log(b, x) +Generate all set partitions of the elements of an array into +exactly m subsets, represented as arrays of arrays. Because the +number of partitions can be very large, this function returns an +iterator object. Use "collect(partitions(array,m))" to get an +array of all partitions. The number of partitions into m subsets is +equal to the Stirling number of the second kind and can be +efficiently computed using "length(partitions(array,m))". -Compute the base "b" logarithm of "x". Throws "DomainError" -for negative "Real" arguments. """ -log +partitions doc""" - log2(x) + peakflops(n; parallel=false) -Compute the logarithm of "x" to base 2. Throws "DomainError" -for negative "Real" arguments. -""" -log2 +"peakflops" computes the peak flop rate of the computer by using +double precision "Base.LinAlg.BLAS.gemm!()". By default, if no +arguments are specified, it multiplies a matrix of size "n x n", +where "n = 2000". If the underlying BLAS is using multiple +threads, higher flop rates are realized. The number of BLAS threads +can be set with "blas_set_num_threads(n)". -doc""" - log10(x) +If the keyword argument "parallel" is set to "true", +"peakflops" is run in parallel on all the worker processors. The +flop rate of the entire parallel computer is returned. When running +in parallel, only 1 BLAS thread is used. The argument "n" still +refers to the size of the problem that is solved on each processor. -Compute the logarithm of "x" to base 10. Throws "DomainError" -for negative "Real" arguments. """ -log10 +peakflops doc""" - log1p(x) + permutations(array) -Accurate natural logarithm of "1+x". Throws "DomainError" for -"Real" arguments less than -1. +Generate all permutations of an indexable object. Because the +number of permutations can be very large, this function returns an +iterator object. Use "collect(permutations(array))" to get an +array of all permutations. -There is an experimental variant in the "Base.Math.JuliaLibm" -module, which is typically faster and more accurate. """ -log1p +permutations doc""" - frexp(val) + permute!(v, p) -Return "(x,exp)" such that "x" has a magnitude in the interval -"[1/2, 1)" or 0, and val = x \times 2^{exp}. -""" -frexp +Permute vector "v" in-place, according to permutation "p". No +checking is done to verify that "p" is a permutation. -doc""" - exp(x) +To return a new permutation, use "v[p]". Note that this is +generally faster than "permute!(v,p)" for large vectors. -Compute e^x """ -exp +permute! doc""" - exp2(x) + permutedims(A, perm) + +Permute the dimensions of array "A". "perm" is a vector +specifying a permutation of length "ndims(A)". This is a +generalization of transpose for multi-dimensional arrays. Transpose +is equivalent to "permutedims(A, [2,1])". -Compute 2^x """ -exp2 +permutedims doc""" - exp10(x) + permutedims!(dest, src, perm) + +Permute the dimensions of array "src" and store the result in the +array "dest". "perm" is a vector specifying a permutation of +length "ndims(src)". The preallocated array "dest" should have +"size(dest) == size(src)[perm]" and is completely overwritten. No +in-place permutation is supported and unexpected results will +happen if *src* and *dest* have overlapping memory regions. -Compute 10^x """ -exp10 +permutedims! doc""" - ldexp(x, n) + pi +π + +The constant pi -Compute x \times 2^n """ -ldexp +pi doc""" - modf(x) + pinv(M[, tol]) -Return a tuple (fpart,ipart) of the fractional and integral parts -of a number. Both parts have the same sign as the argument. -""" -modf +Computes the Moore-Penrose pseudoinverse. -doc""" - expm1(x) +For matrices "M" with floating point elements, it is convenient +to compute the pseudoinverse by inverting only singular values +above a given threshold, "tol". -Accurately compute e^x-1 -""" -expm1 +The optimal choice of "tol" varies both with the value of "M" +and the intended application of the pseudoinverse. The default +value of "tol" is +"eps(real(float(one(eltype(M)))))*maximum(size(A))", which is +essentially machine epsilon for the real part of a matrix element +multiplied by the larger matrix dimension. For inverting dense ill- +conditioned matrices in a least-squares sense, "tol = +sqrt(eps(real(float(one(eltype(M))))))" is recommended. -doc""" - round([T], x[, digits[, base]][, r::RoundingMode]) +For more information, see [8859], [B96], [S84], [KY88]. -"round(x)" rounds "x" to an integer value according to the -default rounding mode (see "get_rounding()"), returning a value -of the same type as "x". By default ("RoundNearest"), this will -round to the nearest integer, with ties (fractional values of 0.5) -being rounded to the even integer. +[8859] Issue 8859, "Fix least squares", + https://github.com/JuliaLang/julia/pull/8859 - julia> round(1.7) - 2.0 +[B96] Åke Björck, "Numerical Methods for Least Squares + Problems", SIAM Press, Philadelphia, 1996, "Other Titles in + Applied Mathematics", Vol. 51. doi:10.1137/1.9781611971484 - julia> round(1.5) - 2.0 +[S84] G. W. Stewart, "Rank Degeneracy", SIAM Journal on + Scientific and Statistical Computing, 5(2), 1984, 403-413. + doi:10.1137/0905030 - julia> round(2.5) - 2.0 +[KY88] Konstantinos Konstantinides and Kung Yao, + "Statistical analysis of effective singular values in + matrix rank determination", IEEE Transactions on Acoustics, + Speech and Signal Processing, 36(5), 1988, 757-763. + doi:10.1109/29.1585 -The optional "RoundingMode" argument will change how the number -gets rounded. +""" +pinv -"round(T, x, [r::RoundingMode])" converts the result to type -"T", throwing an "InexactError" if the value is not -representable. +doc""" + pipe(from, to, ...) -"round(x, digits)" rounds to the specified number of digits after -the decimal place (or before if negative). "round(x, digits, -base)" rounds using a base other than 10. +Create a pipeline from a data source to a destination. The source +and destination can be commands, I/O streams, strings, or results +of other "pipe" calls. At least one argument must be a command. +Strings refer to filenames. When called with more than two +arguments, they are chained together from left to right. For +example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". +This provides a more concise way to specify multi-stage pipelines. - julia> round(pi, 2) - 3.14 +**Examples**: + * "run(pipe(`ls`, `grep xyz`))" - julia> round(pi, 3, 2) - 3.125 + * "run(pipe(`ls`, "out.txt"))" -Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the "Float64" value represented by "1.15" is - actually *less* than 1.15, yet will be rounded to 1.2. + * "run(pipe("out.txt", `grep xyz`))" - julia> x = 1.15 - 1.15 + pipe(command; stdin, stdout, stderr, append=false) - julia> @sprintf "%.20f" x - "1.14999999999999991118" +Redirect I/O to or from the given "command". Keyword arguments +specify which of the command's streams should be redirected. +"append" controls whether file output appends to the file. This +is a more general version of the 2-argument "pipe" function. +"pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when +"from" is a command, and to "pipe(to, stdin=from)" when +"from" is another kind of data source. - julia> x < 115//100 - true +**Examples**: + * "run(pipe(`dothings`, stdout="out.txt", + stderr="errs.txt"))" + + * "run(pipe(`update`, stdout="log.txt", append=true))" - julia> round(x, 1) - 1.2 """ -round +pipe doc""" - RoundingMode - -A type which controls rounding behavior. Currently supported -rounding modes are: - -* "RoundNearest" (default) + plan_bfft(A[, dims[, flags[, timelimit]]]) -* "RoundNearestTiesAway" +Same as "plan_fft()", but produces a plan that performs an +unnormalized backwards transform "bfft()". -* "RoundNearestTiesUp" +""" +plan_bfft -* "RoundToZero" +doc""" + plan_bfft!(A[, dims[, flags[, timelimit]]]) -* "RoundUp" +Same as "plan_bfft()", but operates in-place on "A". -* "RoundDown" """ -RoundingMode +plan_bfft! doc""" - RoundNearest + plan_brfft(A, d[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized real-input unnormalized transform, similar to +"plan_rfft()" except for "brfft()" instead of "rfft()". The +first two arguments and the size of the transformed result, are the +same as for "brfft()". -The default rounding mode. Rounds to the nearest integer, with ties -(fractional values of 0.5) being rounded to the nearest even -integer. """ -RoundNearest +plan_brfft doc""" - RoundNearestTiesAway + plan_dct(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized discrete cosine transform (DCT), similar to +"plan_fft()" except producing a function that computes "dct()". +The first two arguments have the same meaning as for "dct()". -Rounds to nearest integer, with ties rounded away from zero (C/C++ -"round()" behaviour). """ -RoundNearestTiesAway +plan_dct doc""" - RoundNearestTiesUp + plan_dct!(A[, dims[, flags[, timelimit]]]) + +Same as "plan_dct()", but operates in-place on "A". -Rounds to nearest integer, with ties rounded toward positive -infinity (Java/JavaScript "round()" behaviour). """ -RoundNearestTiesUp +plan_dct! doc""" - RoundToZero + plan_fft(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized FFT along given dimensions ("dims") of +arrays matching the shape and type of "A". (The first two +arguments have the same meaning as for "fft()".) Returns a +function "plan(A)" that computes "fft(A, dims)" quickly. + +The "flags" argument is a bitwise-or of FFTW planner flags, +defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or +"FFTW.PATIENT" will instead spend several seconds (or more) +benchmarking different possible FFT algorithms and picking the +fastest one; see the FFTW manual for more information on planner +flags. The optional "timelimit" argument specifies a rough upper +bound on the allowed planning time, in seconds. Passing +"FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array +"A" to be overwritten with zeros during plan creation. + +"plan_fft!()" is the same as "plan_fft()" but creates a plan +that operates in-place on its argument (which must be an array of +complex floating-point numbers). "plan_ifft()" and so on are +similar but produce plans that perform the equivalent of the +inverse transforms "ifft()" and so on. -"round()" using this rounding mode is an alias for "trunc()". """ -RoundToZero +plan_fft doc""" - RoundUp + plan_fft!(A[, dims[, flags[, timelimit]]]) + +Same as "plan_fft()", but operates in-place on "A". -"round()" using this rounding mode is an alias for "ceil()". """ -RoundUp +plan_fft! doc""" - RoundDown + plan_idct(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized inverse discrete cosine transform (DCT), +similar to "plan_fft()" except producing a function that computes +"idct()". The first two arguments have the same meaning as for +"idct()". -"round()" using this rounding mode is an alias for "floor()". """ -RoundDown +plan_idct doc""" - round(z, RoundingModeReal, RoundingModeImaginary) + plan_idct!(A[, dims[, flags[, timelimit]]]) + +Same as "plan_idct()", but operates in-place on "A". -Returns the nearest integral value of the same type as the complex- -valued "z" to "z", breaking ties using the specified -"RoundingMode"s. The first "RoundingMode" is used for rounding -the real components while the second is used for rounding the -imaginary components. """ -round +plan_idct! doc""" - ceil([T], x[, digits[, base]]) - -"ceil(x)" returns the nearest integral value of the same type as -"x" that is greater than or equal to "x". + plan_ifft(A[, dims[, flags[, timelimit]]]) -"ceil(T, x)" converts the result to type "T", throwing an -"InexactError" if the value is not representable. +Same as "plan_fft()", but produces a plan that performs inverse +transforms "ifft()". -"digits" and "base" work as for "round()". """ -ceil +plan_ifft doc""" - floor([T], x[, digits[, base]]) - -"floor(x)" returns the nearest integral value of the same type as -"x" that is less than or equal to "x". + plan_ifft!(A[, dims[, flags[, timelimit]]]) -"floor(T, x)" converts the result to type "T", throwing an -"InexactError" if the value is not representable. +Same as "plan_ifft()", but operates in-place on "A". -"digits" and "base" work as for "round()". """ -floor +plan_ifft! doc""" - trunc([T], x[, digits[, base]]) - -"trunc(x)" returns the nearest integral value of the same type as -"x" whose absolute value is less than or equal to "x". + plan_irfft(A, d[, dims[, flags[, timelimit]]]) -"trunc(T, x)" converts the result to type "T", throwing an -"InexactError" if the value is not representable. +Pre-plan an optimized inverse real-input FFT, similar to +"plan_rfft()" except for "irfft()" and "brfft()", +respectively. The first three arguments have the same meaning as +for "irfft()". -"digits" and "base" work as for "round()". """ -trunc +plan_irfft doc""" - unsafe_trunc(T, x) + plan_rfft(A[, dims[, flags[, timelimit]]]) + +Pre-plan an optimized real-input FFT, similar to "plan_fft()" +except for "rfft()" instead of "fft()". The first two +arguments, and the size of the transformed result, are the same as +for "rfft()". -"unsafe_trunc(T, x)" returns the nearest integral value of type -"T" whose absolute value is less than or equal to "x". If the -value is not representable by "T", an arbitrary value will be -returned. """ -unsafe_trunc +plan_rfft doc""" - signif(x, digits[, base]) + pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + +Transform collections "lsts" by applying "f" to each element in +parallel. If "nprocs() > 1", the calling process will be +dedicated to assigning tasks. All other available processes will be +used as parallel workers, or on the processes specified by +"pids". + +If "err_retry" is true, it retries a failed application of "f" +on a different worker. If "err_stop" is true, it takes precedence +over the value of "err_retry" and "pmap" stops execution on the +first error. -Rounds (in the sense of "round") "x" so that there are -"digits" significant digits, under a base "base" -representation, default 10. E.g., "signif(123.456, 2)" is -"120.0", and "signif(357.913, 4, 2)" is "352.0". """ -signif +pmap doc""" - min(x, y, ...) + pointer(array[, index]) + +Get the native address of an array or string element. Be careful to +ensure that a julia reference to "a" exists as long as this +pointer will be used. This function is "unsafe" like +"unsafe_convert". + +Calling "Ref(array[, index])" is generally preferable to this +function. -Return the minimum of the arguments. Operates elementwise over -arrays. """ -min +pointer doc""" - max(x, y, ...) + pointer_from_objref(object_instance) + +Get the memory address of a Julia object as a "Ptr". The +existence of the resulting "Ptr" will not protect the object from +garbage collection, so you must ensure that the object remains +referenced for the whole time that the "Ptr" will be used. -Return the maximum of the arguments. Operates elementwise over -arrays. """ -max +pointer_from_objref doc""" - minmax(x, y) + pointer_to_array(pointer, dims[, take_ownership::Bool]) + +Wrap a native pointer as a Julia Array object. The pointer element +type determines the array element type. "own" optionally +specifies whether Julia should take ownership of the memory, +calling "free" on the pointer when the array is no longer +referenced. -Return "(min(x,y), max(x,y))". See also: "extrema()" that -returns "(minimum(x), maximum(x))" """ -minmax +pointer_to_array doc""" - clamp(x, lo, hi) + poll_fd(fd, seconds::Real; readable=false, writable=false) + +Poll a file descriptor fd for changes in the read or write +availability and with a timeout given by the second argument. If +the timeout is not needed, use "wait(fd)" instead. The keyword +arguments determine which of read and/or write status should be +monitored and at least one of them needs to be set to true. The +returned value is an object with boolean fields "readable", +"writable", and "timedout", giving the result of the polling. -Return x if "lo <= x <= hi". If "x < lo", return "lo". If "x > -hi", return "hi". Arguments are promoted to a common type. -Operates elementwise over "x" if it is an array. """ -clamp +poll_fd doc""" - abs(x) + poll_file(s, interval_seconds::Real, seconds::Real) + +Monitor a file for changes by polling every *interval_seconds* +seconds for *seconds* seconds. A return value of true indicates the +file changed, a return value of false indicates a timeout. -Absolute value of "x" """ -abs +poll_file doc""" - abs2(x) + polygamma(m, x) + +Compute the polygamma function of order "m" of argument "x" +(the "(m+1)th" derivative of the logarithm of "gamma(x)") -Squared absolute value of "x" """ -abs2 +polygamma doc""" - copysign(x, y) + pop!(collection, key[, default]) -Return "x" such that it has the same sign as "y" -""" -copysign +Delete and return the mapping for "key" if it exists in +"collection", otherwise return "default", or throw an error if +default is not specified. -doc""" - sign(x) + pop!(collection) -> item -Return "+1" if "x" is positive, "0" if "x == 0", and "-1" -if "x" is negative. -""" -sign +Remove the last item in "collection" and return it. -doc""" - signbit(x) + julia> A=[1, 2, 3, 4, 5, 6] + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 -Returns "true" if the value of the sign of "x" is negative, -otherwise "false". -""" -signbit + julia> pop!(A) + 6 -doc""" - flipsign(x, y) + julia> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 -Return "x" with its sign flipped if "y" is negative. For -example "abs(x) = flipsign(x,x)". """ -flipsign +pop! doc""" - sqrt(x) + popdisplay() +popdisplay(d::Display) + +Pop the topmost backend off of the display-backend stack, or the +topmost copy of "d" in the second variant. -Return \sqrt{x}. Throws "DomainError" for negative "Real" -arguments. Use complex negative arguments instead. The prefix -operator "√" is equivalent to "sqrt". """ -sqrt +popdisplay doc""" - isqrt(n) + position(s) + +Get the current position of a stream. -Integer square root: the largest integer "m" such that "m*m <= -n". """ -isqrt +position doc""" - cbrt(x) + powermod(x, p, m) + +Compute x^p \pmod m -Return x^{1/3}. The prefix operator "∛" is equivalent to -"cbrt". """ -cbrt +powermod doc""" - erf(x) + precision(num::FloatingPoint) + +Get the precision of a floating point number, as defined by the +effective number of bits in the mantissa. -Compute the error function of "x", defined by -\frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt for arbitrary complex -"x". """ -erf +precision doc""" - erfc(x) + precompile(f, args::Tuple{Vararg{Any}}) + +Compile the given function "f" for the argument tuple (of types) +"args", but do not execute it. -Compute the complementary error function of "x", defined by 1 - -\operatorname{erf}(x). """ -erfc +precompile doc""" - erfcx(x) + prepend!(collection, items) -> collection -Compute the scaled complementary error function of "x", defined -by e^{x^2} \operatorname{erfc}(x). Note also that -\operatorname{erfcx}(-ix) computes the Faddeeva function w(x). -""" -erfcx +Insert the elements of "items" to the beginning of +"collection". -doc""" - erfi(x) + julia> prepend!([3],[1,2]) + 3-element Array{Int64,1}: + 1 + 2 + 3 -Compute the imaginary error function of "x", defined by -i -\operatorname{erf}(ix). """ -erfi +prepend! doc""" - dawson(x) + prevfloat(f) -> FloatingPoint + +Get the previous floating point number in lexicographic order -Compute the Dawson function (scaled imaginary error function) of -"x", defined by \frac{\sqrt{\pi}}{2} e^{-x^2} -\operatorname{erfi}(x). """ -dawson +prevfloat doc""" - erfinv(x) + prevind(str, i) + +Get the previous valid string index before "i". Returns a value +less than "1" at the beginning of the string. -Compute the inverse error function of a real "x", defined by -\operatorname{erf}(\operatorname{erfinv}(x)) = x. """ -erfinv +prevind doc""" - erfcinv(x) + prevpow(a, x) + +The largest "a^n" not greater than "x", where "n" is a non- +negative integer. "a" must be greater than 1, and "x" must not +be less than 1. -Compute the inverse error complementary function of a real "x", -defined by \operatorname{erfc}(\operatorname{erfcinv}(x)) = x. """ -erfcinv +prevpow doc""" - real(z) + prevpow2(n) + +The largest power of two not greater than "n". Returns 0 for +"n==0", and returns "-prevpow2(-n)" for negative arguments. -Return the real part of the complex number "z" """ -real +prevpow2 doc""" - imag(z) + prevprod([k_1, k_2, ...], n) + +Previous integer not greater than "n" that can be written as +\prod k_i^{p_i} for integers p_1, p_2, etc. -Return the imaginary part of the complex number "z" """ -imag +prevprod doc""" - reim(z) + primes(n) + +Returns a collection of the prime numbers <= "n". -Return both the real and imaginary parts of the complex number -"z" """ -reim +primes doc""" - conj(z) + print(x) + +Write (to the default output stream) a canonical (un-decorated) +text representation of a value if there is one, otherwise call +"show". The representation used by "print" includes minimal +formatting and tries to avoid Julia-specific details. -Compute the complex conjugate of a complex number "z" """ -conj +print doc""" - angle(z) + print_escaped(io, str::AbstractString, esc::AbstractString) + +General escaping of traditional C and Unicode escape sequences, +plus any characters in esc are also escaped (with a backslash). -Compute the phase angle in radians of a complex number "z" """ -angle +print_escaped doc""" - cis(z) + print_joined(io, items, delim[, last]) + +Print elements of "items" to "io" with "delim" between them. +If "last" is specified, it is used as the final delimiter instead +of "delim". -Return \exp(iz). """ -cis +print_joined doc""" - binomial(n, k) + print_shortest(io, x) + +Print the shortest possible representation, with the minimum number +of consecutive non-zero digits, of number "x", ensuring that it +would parse to the exact same number. -Number of ways to choose "k" out of "n" items """ -binomial +print_shortest doc""" - factorial(n) + print_unescaped(io, s::AbstractString) + +General unescaping of traditional C and Unicode escape sequences. +Reverse of "print_escaped()". -Factorial of "n". If "n" is an "Integer", the factorial is -computed as an integer (promoted to at least 64 bits). Note that -this may overflow if "n" is not small, but you can use -"factorial(big(n))" to compute the result exactly in arbitrary -precision. If "n" is not an "Integer", "factorial(n)" is -equivalent to "gamma(n+1)". """ -factorial +print_unescaped doc""" - factorial(n, k) + print_with_color(color::Symbol[, io], strings...) + +Print strings in a color specified as a symbol, for example +":red" or ":blue". -Compute "factorial(n)/factorial(k)" """ -factorial +print_with_color doc""" - factor(n) -> Dict - -Compute the prime factorization of an integer "n". Returns a -dictionary. The keys of the dictionary correspond to the factors, -and hence are of the same type as "n". The value associated with -each key indicates the number of times the factor appears in the -factorization. + println(x) + +Print (using "print()") "x" followed by a newline. - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 """ -factor +println doc""" - gcd(x, y) + process_exited(p::Process) + +Determine whether a process has exited. -Greatest common (positive) divisor (or zero if x and y are both -zero). """ -gcd +process_exited doc""" - lcm(x, y) + process_running(p::Process) + +Determine whether a process is currently running. -Least common (non-negative) multiple. """ -lcm +process_running doc""" - gcdx(x, y) + procs() -Computes the greatest common (positive) divisor of "x" and "y" -and their Bézout coefficients, i.e. the integer coefficients "u" -and "v" that satisfy ux+vy = d = gcd(x,y). +Returns a list of all process identifiers. - julia> gcdx(12, 42) - (6,-3,1) + procs(S::SharedArray) - julia> gcdx(240, 46) - (2,-9,47) +Get the vector of processes that have mapped the shared array -Note: Bézout coefficients are *not* uniquely defined. "gcdx" - returns the minimal Bézout coefficients that are computed by the - extended Euclid algorithm. (Ref: D. Knuth, TAoCP, 2/e, p. 325, - Algorithm X.) These coefficients "u" and "v" are minimal in - the sense that |u| < |\frac y d and |v| < |\frac x d. - Furthermore, the signs of "u" and "v" are chosen so that - "d" is positive. """ -gcdx +procs doc""" - ispow2(n) -> Bool + prod(itr) -Test whether "n" is a power of two -""" -ispow2 +Returns the product of all elements of a collection. -doc""" - nextpow2(n) + prod(A, dims) + +Multiply elements of an array over the given dimensions. -The smallest power of two not less than "n". Returns 0 for -"n==0", and returns "-nextpow2(-n)" for negative arguments. """ -nextpow2 +prod doc""" - prevpow2(n) + prod!(r, A) + +Multiply elements of "A" over the singleton dimensions of "r", +and write results to "r". -The largest power of two not greater than "n". Returns 0 for -"n==0", and returns "-prevpow2(-n)" for negative arguments. """ -prevpow2 +prod! doc""" - nextpow(a, x) + produce(value) + +Send the given value to the last "consume" call, switching to the +consumer task. If the next "consume" call passes any values, they +are returned by "produce". -The smallest "a^n" not less than "x", where "n" is a non- -negative integer. "a" must be greater than 1, and "x" must be -greater than 0. """ -nextpow +produce doc""" - prevpow(a, x) + promote(xs...) + +Convert all arguments to their common promotion type (if any), and +return them all (as a tuple). -The largest "a^n" not greater than "x", where "n" is a non- -negative integer. "a" must be greater than 1, and "x" must not -be less than 1. """ -prevpow +promote doc""" - nextprod([k_1, k_2, ...], n) + promote_rule(type1, type2) + +Specifies what type should be used by "promote" when given values +of types "type1" and "type2". This function should not be +called directly, but should have definitions added to it for new +types as appropriate. -Next integer not less than "n" that can be written as \prod -k_i^{p_i} for integers p_1, p_2, etc. """ -nextprod +promote_rule doc""" - prevprod([k_1, k_2, ...], n) + promote_shape(s1, s2) + +Check two array shapes for compatibility, allowing trailing +singleton dimensions, and return whichever shape has more +dimensions. -Previous integer not greater than "n" that can be written as -\prod k_i^{p_i} for integers p_1, p_2, etc. """ -prevprod +promote_shape doc""" - invmod(x, m) + promote_type(type1, type2) + +Determine a type big enough to hold values of each argument type +without loss, whenever possible. In some cases, where no type +exists to which both types can be promoted losslessly, some loss is +tolerated; for example, "promote_type(Int64,Float64)" returns +"Float64" even though strictly, not all "Int64" values can be +represented exactly as "Float64" values. -Take the inverse of "x" modulo "m": "y" such that xy = 1 -\pmod m """ -invmod +promote_type doc""" - powermod(x, p, m) + 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])". -Compute x^p \pmod m """ -powermod +push! doc""" - gamma(x) + pushdisplay(d::Display) + +Pushes a new display "d" on top of the global display-backend +stack. Calling "display(x)" or "display(mime, x)" will display +"x" on the topmost compatible backend in the stack (i.e., the +topmost backend that does not throw a "MethodError"). -Compute the gamma function of "x" """ -gamma +pushdisplay doc""" - lgamma(x) + put!(RemoteRef, value) + +Store a value to a remote reference. Implements "shared queue of +length 1" semantics: if a value is already present, blocks until +the value is removed with "take!". Returns its first argument. -Compute the logarithm of the absolute value of "gamma()" for -"Real" "x", while for "Complex" "x" it computes the -logarithm of "gamma(x)". """ -lgamma +put! doc""" - lfact(x) + pwd() -> AbstractString + +Get the current working directory. -Compute the logarithmic factorial of "x" """ -lfact +pwd doc""" - digamma(x) + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] + +Compute the (pivoted) QR factorization of "A" such that either +"A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default +is to compute a thin factorization. Note that "R" is not extended +with zeros when the full "Q" is requested. -Compute the digamma function of "x" (the logarithmic derivative -of "gamma(x)") """ -digamma +qr doc""" - invdigamma(x) + qrfact(A[, pivot=Val{false}]) -> F -Compute the inverse digamma function of "x". -""" -invdigamma +Computes the QR factorization of "A". The return type of "F" +depends on the element type of "A" and whether pivoting is +specified (with "pivot==Val{true}"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + +"BlasFloat" refers to any of: "Float32", "Float64", +"Complex64" or "Complex128". + +The individual components of the factorization "F" can be +accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:p]\" | pivot \"Vector\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + +The following functions are available for the "QR" objects: +"size", "\". When "A" is rectangular, "\" will return a +least squares solution and if the solution is not unique, the one +with smallest norm is returned. + +Multiplication with respect to either thin or full "Q" is +allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A +"Q" matrix can be converted into a regular matrix with "full()" +which has a named argument "thin". + +Note: "qrfact" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the "Q" and "R" matrices can be stored compactly rather + as two separate dense matrices.The data contained in "QR" or + "QRPivoted" can be used to construct the "QRPackedQ" type, + which is a compact representation of the rotation matrix: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where \tau_i is the scale factor and v_i is the projection + vector associated with the i^{th} Householder elementary + reflector.The data contained in "QRCompactWY" can be used to + construct the "QRCompactWYQ" type, which is a compact + representation of the rotation matrix + + Q = I + Y T Y^T + + where "Y" is m \times r lower trapezoidal and "T" is r + \times r upper triangular. The *compact WY* representation + [Schreiber1989] is not to be confused with the older, *WY* + representation [Bischof1987]. (The LAPACK documentation uses + "V" in lieu of "Y".) + +[Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + +[Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 -doc""" - trigamma(x) + qrfact(A) -> SPQR.Factorization + +Compute the QR factorization of a sparse matrix "A". A fill- +reducing permutation is used. The main application of this type is +to solve least squares problems with "\". The function calls the +C library SPQR and a few additional functions from the library are +wrapped but not exported. -Compute the trigamma function of "x" (the logarithmic second -derivative of "gamma(x)") """ -trigamma +qrfact doc""" - polygamma(m, x) + qrfact!(A[, pivot=Val{false}]) + +"qrfact!" is the same as "qrfact()" when A is a subtype of +"StridedMatrix", but saves space by overwriting the input "A", +instead of creating a copy. -Compute the polygamma function of order "m" of argument "x" -(the "(m+1)th" derivative of the logarithm of "gamma(x)") """ -polygamma +qrfact! doc""" - airy(k, x) + quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) -kth derivative of the Airy function \operatorname{Ai}(x). -""" -airy +Numerically integrate the function "f(x)" from "a" to "b", +and optionally over additional intervals "b" to "c" and so on. +Keyword options include a relative error tolerance "reltol" +(defaults to "sqrt(eps)" in the precision of the endpoints), an +absolute error tolerance "abstol" (defaults to 0), a maximum +number of function evaluations "maxevals" (defaults to "10^7"), +and the "order" of the integration rule (defaults to 7). -doc""" - airyai(x) +Returns a pair "(I,E)" of the estimated integral "I" and an +estimated upper bound on the absolute error "E". If "maxevals" +is not exceeded then "E <= max(abstol, reltol*norm(I))" will +hold. (Note that it is useful to specify a positive "abstol" in +cases where "norm(I)" may be zero.) -Airy function \operatorname{Ai}(x). -""" -airyai +The endpoints "a" etcetera can also be complex (in which case the +integral is performed over straight-line segments in the complex +plane). If the endpoints are "BigFloat", then the integration +will be performed in "BigFloat" precision as well (note: it is +advisable to increase the integration "order" in rough proportion +to the precision, for smooth integrands). More generally, the +precision is set by the precision of the integration endpoints +(promoted to floating-point types). -doc""" - airyprime(x) +The integrand "f(x)" can return any numeric scalar, vector, or +matrix type, or in fact any type supporting "+", "-", +multiplication by real values, and a "norm" (i.e., any normed +vector space). Alternatively, a different norm can be specified by +passing a *norm*-like function as the *norm* keyword argument +(which defaults to *vecnorm*). -Airy function derivative \operatorname{Ai}'(x). -""" -airyprime +[Only one-dimensional integrals are provided by this function. For +multi-dimensional integration (cubature), there are many different +algorithms (often much better than simple nested 1d integrals) and +the optimal choice tends to be very problem-dependent. See the +Julia external-package listing for available algorithms for +multidimensional integration or other specialized tasks (such as +integrals of highly oscillatory or singular functions).] -doc""" - airyaiprime(x) +The algorithm is an adaptive Gauss-Kronrod integration technique: +the integral in each interval is estimated using a Kronrod rule +("2*order+1" points) and the error is estimated using an embedded +Gauss rule ("order" points). The interval with the largest +error is then subdivided into two intervals and the process is +repeated until the desired error tolerance is achieved. -Airy function derivative \operatorname{Ai}'(x). -""" -airyaiprime +These quadrature rules work best for smooth functions within each +interval, so if your function has a known discontinuity or other +singularity, it is best to subdivide your interval to put the +singularity at an endpoint. For example, if "f" has a +discontinuity at "x=0.7" and you want to integrate from 0 to 1, +you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at +the point of discontinuity. The integrand is never evaluated +exactly at the endpoints of the intervals, so it is possible to +integrate functions that diverge at the endpoints as long as the +singularity is integrable (for example, a "log(x)" or +"1/sqrt(x)" singularity). -doc""" - airybi(x) +For real-valued endpoints, the starting and/or ending points may be +infinite. (A coordinate transformation is performed internally to +map the infinite interval to a finite one.) -Airy function \operatorname{Bi}(x). """ -airybi +quadgk doc""" - airybiprime(x) + quantile(v, p) -Airy function derivative \operatorname{Bi}'(x). -""" -airybiprime +Compute the quantiles of a vector "v" at a specified set of +probability values "p". Note: Julia does not ignore "NaN" +values in the computation. -doc""" - airyx(k, x) + quantile(v, p) + +Compute the quantile of a vector "v" at the probability "p". +Note: Julia does not ignore "NaN" values in the computation. -scaled kth derivative of the Airy function, return -\operatorname{Ai}(x) e^{\frac{2}{3} x \sqrt{x}} for "k == 0 || -k == 1", and \operatorname{Ai}(x) e^{- \left| \operatorname{Re} -\left( \frac{2}{3} x \sqrt{x} \right) \right|} for "k == 2 || -k == 3". """ -airyx +quantile doc""" - besselj0(x) + quantile!(v, p) + +Like "quantile", but overwrites the input vector. -Bessel function of the first kind of order 0, J_0(x). """ -besselj0 +quantile! doc""" - besselj1(x) + quit() + +Quit the program indicating that the processes completed +successfully. This function calls "exit(0)" (see "exit()"). -Bessel function of the first kind of order 1, J_1(x). """ -besselj1 +quit doc""" - besselj(nu, x) + rad2deg(x) + +Convert "x" from radians to degrees -Bessel function of the first kind of order "nu", J_\nu(x). """ -besselj +rad2deg doc""" - besseljx(nu, x) + rand([rng][, S][, dims...]) -Scaled Bessel function of the first kind of order "nu", J_\nu(x) -e^{- | \operatorname{Im}(x) |}. -""" -besseljx +Pick a random element or array of random elements from the set of +values specified by "S"; "S" can be -doc""" - bessely0(x) +* an indexable collection (for example "1:n" or + "['x','y','z']"), or -Bessel function of the second kind of order 0, Y_0(x). -""" -bessely0 +* a type: the set of values to pick from is then equivalent to + "typemin(S):typemax(S)" for integers (this is not applicable to + "BigInt"), and to [0,1) for floating point numbers; -doc""" - bessely1(x) +"S" defaults to "Float64". -Bessel function of the second kind of order 1, Y_1(x). """ -bessely1 +rand doc""" - bessely(nu, x) + rand!([rng], A[, coll]) + +Populate the array A with random values. If the indexable +collection "coll" is specified, the values are picked randomly +from "coll". This is equivalent to "copy!(A, rand(rng, coll, +size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but +without allocating a new array. -Bessel function of the second kind of order "nu", Y_\nu(x). """ -bessely +rand! doc""" - besselyx(nu, x) + randcycle([rng], n) + +Construct a random cyclic permutation of length "n". The optional +"rng" argument specifies a random number generator, see *Random +Numbers*. -Scaled Bessel function of the second kind of order "nu", -Y_\nu(x) e^{- | \operatorname{Im}(x) |}. """ -besselyx +randcycle doc""" - hankelh1(nu, x) + randexp([rng][, dims...]) + +Generate a random number according to the exponential distribution +with scale 1. Optionally generate an array of such random numbers. -Bessel function of the third kind of order "nu", H^{(1)}_\nu(x). """ -hankelh1 +randexp doc""" - hankelh1x(nu, x) + randexp!([rng], A::Array{Float64, N}) + +Fill the array A with random numbers following the exponential +distribution (with scale 1). -Scaled Bessel function of the third kind of order "nu", -H^{(1)}_\nu(x) e^{-x i}. """ -hankelh1x +randexp! doc""" - hankelh2(nu, x) + randn([rng][, dims...]) + +Generate a normally-distributed random number with mean 0 and +standard deviation 1. Optionally generate an array of normally- +distributed random numbers. -Bessel function of the third kind of order "nu", H^{(2)}_\nu(x). """ -hankelh2 +randn doc""" - hankelh2x(nu, x) + randn!([rng], A::Array{Float64, N}) + +Fill the array A with normally-distributed (mean 0, standard +deviation 1) random numbers. Also see the rand function. -Scaled Bessel function of the third kind of order "nu", -H^{(2)}_\nu(x) e^{x i}. """ -hankelh2x +randn! doc""" - besselh(nu, k, x) + randperm([rng], n) + +Construct a random permutation of length "n". The optional +"rng" argument specifies a random number generator, see *Random +Numbers*. -Bessel function of the third kind of order "nu" (Hankel -function). "k" is either 1 or 2, selecting "hankelh1" or -"hankelh2", respectively. """ -besselh +randperm doc""" - besseli(nu, x) + randstring([rng], len=8) + +Create a random ASCII string of length "len", consisting of +upper- and lower-case letters and the digits 0-9. The optional +"rng" argument specifies a random number generator, see *Random +Numbers*. -Modified Bessel function of the first kind of order "nu", -I_\nu(x). """ -besseli +randstring doc""" - besselix(nu, x) + randsubseq(A, p) -> Vector + +Return a vector consisting of a random subsequence of the given +array "A", where each element of "A" is included (in order) +with independent probability "p". (Complexity is linear in +"p*length(A)", so this function is efficient even if "p" is +small and "A" is large.) Technically, this process is known as +"Bernoulli sampling" of "A". -Scaled modified Bessel function of the first kind of order "nu", -I_\nu(x) e^{- | \operatorname{Re}(x) |}. """ -besselix +randsubseq doc""" - besselk(nu, x) + randsubseq!(S, A, p) + +Like "randsubseq", but the results are stored in "S" (which is +resized as needed). -Modified Bessel function of the second kind of order "nu", -K_\nu(x). """ -besselk +randsubseq! doc""" - besselkx(nu, x) + range(start[, step], length) + +Construct a range by length, given a starting value and optional +step (defaults to 1). -Scaled modified Bessel function of the second kind of order "nu", -K_\nu(x) e^x. """ -besselkx +range doc""" - beta(x, y) + rank(M) + +Compute the rank of a matrix. -Euler integral of the first kind \operatorname{B}(x,y) = -\Gamma(x)\Gamma(y)/\Gamma(x+y). """ -beta +rank doc""" - lbeta(x, y) + rationalize([Type=Int], x; tol=eps(x)) + +Approximate floating point number "x" as a Rational number with +components of the given integer type. The result will differ from +"x" by no more than "tol". -Natural logarithm of the absolute value of the beta function -\log(|\operatorname{B}(x,y)|). """ -lbeta +rationalize doc""" - eta(x) + read(stream, type) -Dirichlet eta function \eta(s) = -\sum^\infty_{n=1}(-)^{n-1}/n^{s}. -""" -eta +Read a value of the given type from a stream, in canonical binary +representation. -doc""" - zeta(s) + read(stream, type, dims) + +Read a series of values of the given type from a stream, in +canonical binary representation. "dims" is either a tuple or a +series of integer arguments specifying the size of "Array" to +return. -Riemann zeta function \zeta(s). """ -zeta +read doc""" - zeta(s, z) + read!(stream, array::Array) + +Read binary data from a stream, filling in the argument "array". -Hurwitz zeta function \zeta(s, z). (This is equivalent to the -Riemann zeta function \zeta(s) for the case of "z=1".) """ -zeta +read! doc""" - ndigits(n, b) + readall(stream::IO) -Compute the number of digits in number "n" written in base "b". -""" -ndigits +Read the entire contents of an I/O stream as a string. -doc""" - widemul(x, y) + readall(filename::AbstractString) + +Open "filename", read the entire contents as a string, then close +the file. Equivalent to "open(readall, filename)". -Multiply "x" and "y", giving the result as a larger type. """ -widemul +readall doc""" - @evalpoly(z, c...) + readandwrite(command) + +Starts running a command asynchronously, and returns a tuple +(stdout,stdin,process) of the output stream and input stream of the +process, and the process object itself. -Evaluate the polynomial \sum_k c[k] z^{k-1} for the coefficients -"c[1]", "c[2]", ...; that is, the coefficients are given in -ascending order by power of "z". This macro expands to efficient -inline code that uses either Horner's method or, for complex "z", -a more efficient Goertzel-like algorithm. """ -@evalpoly +readandwrite doc""" - mean(v[, region]) + readavailable(stream) + +Read all available data on the stream, blocking the task only if no +data is available. The result is a "Vector{UInt8,1}". -Compute the mean of whole array "v", or optionally along the -dimensions in "region". Note: Julia does not ignore "NaN" -values in the computation. For applications requiring the handling -of missing data, the "DataArray" package is recommended. """ -mean +readavailable doc""" - mean!(r, v) + readbytes(stream, nb=typemax(Int)) + +Read at most "nb" bytes from the stream, returning a +"Vector{UInt8}" of the bytes read. -Compute the mean of "v" over the singleton dimensions of "r", -and write results to "r". """ -mean! +readbytes doc""" - std(v[, region]) + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) + +Read at most "nb" bytes from the stream into "b", returning the +number of bytes read (increasing the size of "b" as needed). -Compute the sample standard deviation of a vector or array "v", -optionally along dimensions in "region". The algorithm returns an -estimator of the generative distribution's standard deviation under -the assumption that each entry of "v" is an IID drawn from that -generative distribution. This computation is equivalent to -calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". -Note: Julia does not ignore "NaN" values in the computation. For -applications requiring the handling of missing data, the -"DataArray" package is recommended. """ -std +readbytes! doc""" - stdm(v, m) + readchomp(x) + +Read the entirety of x as a string but remove trailing newlines. +Equivalent to chomp(readall(x)). -Compute the sample standard deviation of a vector "v" with known -mean "m". Note: Julia does not ignore "NaN" values in the -computation. """ -stdm +readchomp doc""" - var(v[, region]) + readcsv(source, [T::Type]; options...) + +Equivalent to "readdlm" with "delim" set to comma. -Compute the sample variance of a vector or array "v", optionally -along dimensions in "region". The algorithm will return an -estimator of the generative distribution's variance under the -assumption that each entry of "v" is an IID drawn from that -generative distribution. This computation is equivalent to -calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: -Julia does not ignore "NaN" values in the computation. For -applications requiring the handling of missing data, the -"DataArray" package is recommended. """ -var +readcsv doc""" - varm(v, m) + readdir([dir]) -> Vector{ByteString} + +Returns the files and directories in the directory *dir* (or the +current working directory if not given). -Compute the sample variance of a vector "v" with known mean -"m". Note: Julia does not ignore "NaN" values in the -computation. """ -varm +readdir doc""" - middle(x) + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') -Compute the middle of a scalar value, which is equivalent to "x" -itself, but of the type of "middle(x, x)" for consistency. -""" -middle +Read a matrix from the source where each line (separated by +"eol") gives one row, with elements separated by the given +delimeter. The source can be a text file, stream or byte array. +Memory mapped files can be used by passing the byte array +representation of the mapped segment as source. -doc""" - middle(x, y) +If "T" is a numeric type, the result is an array of that type, +with any non-numeric elements as "NaN" for floating-point types, +or zero. Other useful values of "T" include "ASCIIString", +"AbstractString", and "Any". -Compute the middle of two reals "x" and "y", which is -equivalent in both value and type to computing their mean ("(x + -y) / 2"). -""" -middle +If "header" is "true", the first row of data will be read as +header and the tuple "(data_cells, header_cells)" is returned +instead of only "data_cells". -doc""" - middle(range) +Specifying "skipstart" will ignore the corresponding number of +initial lines from the input. -Compute the middle of a range, which consists in computing the mean -of its extrema. Since a range is sorted, the mean is performed with -the first and last element. -""" -middle +If "skipblanks" is "true", blank lines in the input will be +ignored. -doc""" - middle(array) +If "use_mmap" is "true", the file specified by "source" is +memory mapped for potential speedups. Default is "true" except on +Windows. On Windows, you may want to specify "true" if the file +is large, and is only read once and not written to. -Compute the middle of an array, which consists in finding its -extrema and then computing their mean. -""" -middle +If "ignore_invalid_chars" is "true", bytes in "source" with +invalid character encoding will be ignored. Otherwise an error is +thrown indicating the offending character position. -doc""" - median(v) +If "quotes" is "true", column enclosed within double-quote (``) +characters are allowed to contain new lines and column delimiters. +Double-quote characters within a quoted field must be escaped with +another double-quote. + +Specifying "dims" as a tuple of the expected rows and columns +(including header, if any) may speed up reading of large files. + +If "comments" is "true", lines beginning with "comment_char" +and text following "comment_char" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + +If all data is numeric, the result will be a numeric array. If some +elements cannot be parsed as numbers, a cell array of numbers and +strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + +The end of line delimiter is taken as "\n". + + readdlm(source, delim::Char; options...) + +The end of line delimiter is taken as "\n". If all data is +numeric, the result will be a numeric array. If some elements +cannot be parsed as numbers, a cell array of numbers and strings is +returned. + + readdlm(source, T::Type; options...) + +The columns are assumed to be separated by one or more whitespaces. +The end of line delimiter is taken as "\n". + + readdlm(source; options...) + +The columns are assumed to be separated by one or more whitespaces. +The end of line delimiter is taken as "\n". If all data is +numeric, the result will be a numeric array. If some elements +cannot be parsed as numbers, a cell array of numbers and strings is +returned. -Compute the median of a vector "v". "NaN" is returned if the -data contains any "NaN" values. For applications requiring the -handling of missing data, the "DataArrays" package is -recommended. """ -median +readdlm doc""" - median!(v) + readline(stream=STDIN) + +Read a single line of text, including a trailing newline character +(if one is reached before the end of the input), from the given +"stream" (defaults to "STDIN"), -Like "median", but may overwrite the input vector. """ -median! +readline doc""" - hist(v[, n]) -> e, counts + readlines(stream) + +Read all lines as an array. -Compute the histogram of "v", optionally using approximately -"n" bins. The return values are a range "e", which correspond -to the edges of the bins, and "counts" containing the number of -elements of "v" in each bin. Note: Julia does not ignore "NaN" -values in the computation. """ -hist +readlines doc""" - hist(v, e) -> e, counts + readlink(path) -> AbstractString + +Returns the value of a symbolic link "path". -Compute the histogram of "v" using a vector/range "e" as the -edges for the bins. The result will be a vector of length -"length(e) - 1", such that the element at location "i" -satisfies "sum(e[i] .< v .<= e[i+1])". Note: Julia does not -ignore "NaN" values in the computation. """ -hist +readlink doc""" - hist!(counts, v, e) -> e, counts + readuntil(stream, delim) + +Read a string, up to and including the given delimiter byte. -Compute the histogram of "v", using a vector/range "e" as the -edges for the bins. This function writes the resultant counts to a -pre-allocated array "counts". """ -hist! +readuntil doc""" - hist2d(M, e1, e2) -> (edge1, edge2, counts) + real(z) + +Return the real part of the complex number "z" -Compute a "2d histogram" of a set of N points specified by N-by-2 -matrix "M". Arguments "e1" and "e2" are bins for each -dimension, specified either as integer bin counts or vectors of bin -edges. The result is a tuple of "edge1" (the bin edges used in -the first dimension), "edge2" (the bin edges used in the second -dimension), and "counts", a histogram matrix of size -"(length(edge1)-1, length(edge2)-1)". Note: Julia does not ignore -"NaN" values in the computation. """ -hist2d +real doc""" - hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + realmax(type) + +The highest finite value representable by the given floating-point +type -Compute a "2d histogram" with respect to the bins delimited by -the edges given in "e1" and "e2". This function writes the -results to a pre-allocated array "counts". """ -hist2d! +realmax doc""" - histrange(v, n) + realmin(type) + +The smallest in absolute value non-subnormal value representable by +the given floating-point type -Compute *nice* bin ranges for the edges of a histogram of "v", -using approximately "n" bins. The resulting step sizes will be 1, -2 or 5 multiplied by a power of 10. Note: Julia does not ignore -"NaN" values in the computation. """ -histrange +realmin doc""" - midpoints(e) + realpath(path::AbstractString) -> AbstractString + +Canonicalize a path by expanding symbolic links and removing "." +and ".." entries. -Compute the midpoints of the bins with edges "e". The result is a -vector/range of length "length(e) - 1". Note: Julia does not -ignore "NaN" values in the computation. """ -midpoints +realpath doc""" - quantile(v, p) + recv(socket::UDPSocket) + +Read a UDP packet from the specified socket, and return the bytes +received. This call blocks. -Compute the quantiles of a vector "v" at a specified set of -probability values "p". Note: Julia does not ignore "NaN" -values in the computation. """ -quantile +recv doc""" - quantile(v, p) + recvfrom(socket::UDPSocket) -> (address, data) + +Read a UDP packet from the specified socket, returning a tuple of +(address, data), where address will be either IPv4 or IPv6 as +appropriate. -Compute the quantile of a vector "v" at the probability "p". -Note: Julia does not ignore "NaN" values in the computation. """ -quantile +recvfrom doc""" - quantile!(v, p) + redirect_stderr([stream]) + +Like redirect_stdout, but for STDERR -Like "quantile", but overwrites the input vector. """ -quantile! +redirect_stderr doc""" - cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) + redirect_stdin([stream]) -Compute the Pearson covariance between the vector(s) in "v1" and -"v2". Here, "v1" and "v2" can be either vectors or matrices. +Like redirect_stdout, but for STDIN. Note that the order of the +return tuple is still (rd,wr), i.e. data to be read from STDIN, may +be written to wr. -This function accepts three keyword arguments: +""" +redirect_stdin -* "vardim": the dimension of variables. When "vardim = 1", - variables are considered in columns while observations in rows; - when "vardim = 2", variables are in rows while observations in - columns. By default, it is set to "1". +doc""" + redirect_stdout() -* "corrected": whether to apply Bessel's correction (divide by - "n-1" instead of "n"). By default, it is set to "true". +Create a pipe to which all C and Julia level STDOUT output will be +redirected. Returns a tuple (rd,wr) representing the pipe ends. +Data written to STDOUT may now be read from the rd end of the pipe. +The wr end is given for convenience in case the old STDOUT object +was cached by the user and needs to be replaced elsewhere. -* "mean": allow users to supply mean values that are known. By - default, it is set to "nothing", which indicates that the - mean(s) are unknown, and the function will compute the mean. - Users can use "mean=0" to indicate that the input data are - centered, and hence there's no need to subtract the mean. + redirect_stdout(stream) -The size of the result depends on the size of "v1" and "v2". -When both "v1" and "v2" are vectors, it returns the covariance -between them as a scalar. When either one is a matrix, it returns a -covariance matrix of size "(n1, n2)", where "n1" and "n2" are -the numbers of slices in "v1" and "v2", which depend on the -setting of "vardim". +Replace STDOUT by stream for all C and julia level output to +STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. -Note: "v2" can be omitted, which indicates "v2 = v1". """ -cov +redirect_stdout doc""" - cor(v1[, v2][, vardim=1, mean=nothing]) + redisplay(x) +redisplay(d::Display, x) +redisplay(mime, x) +redisplay(d::Display, mime, x) -Compute the Pearson correlation between the vector(s) in "v1" and -"v2". +By default, the "redisplay" functions simply call "display". +However, some display backends may override "redisplay" to modify +an existing display of "x" (if any). Using "redisplay" is +also a hint to the backend that "x" may be redisplayed several +times, and the backend may choose to defer the display until (for +example) the next interactive prompt. -Users can use the keyword argument "vardim" to specify the -variable dimension, and "mean" to supply pre-computed mean -values. """ -cor +redisplay doc""" - fft(A[, dims]) + reduce(op, v0, itr) -Performs a multidimensional FFT of the array "A". The optional -"dims" argument specifies an iterable subset of dimensions (e.g. -an integer, range, tuple, or array) to transform along. Most -efficient if the size of "A" along the transformed dimensions is -a product of small primes; see "nextprod()". See also -"plan_fft()" for even greater efficiency. +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. -A one-dimensional FFT computes the one-dimensional discrete Fourier -transform (DFT) as defined by +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)". - \operatorname{DFT}(A)[k] = - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(-i\frac{2\pi - (n-1)(k-1)}{\operatorname{length}(A)} \right) A[n]. +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. -A multidimensional FFT simply performs this operation along each -transformed dimension of "A". +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. + + 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". -Higher performance is usually possible with multi-threading. Use -*FFTW.set_num_threads(np)* to use *np* threads, if you have *np* -processors. """ -fft +reduce doc""" - fft!(A[, dims]) + reducedim(f, A, dims[, initial]) + +Reduce 2-argument function "f" along dimensions of "A". +"dims" is a vector specifying the dimensions to reduce, and +"initial" is the initial value to use in the reductions. For *+*, +***, *max* and *min* the *initial* argument is optional. + +The associativity of the reduction is implementation-dependent; if +you need a particular associativity, e.g. left-to-right, you should +write your own loop. See documentation for "reduce". -Same as "fft()", but operates in-place on "A", which must be an -array of complex floating-point numbers. """ -fft! +reducedim doc""" - ifft(A[, dims]) + reenable_sigint(f::Function) -Multidimensional inverse FFT. +Re-enable Ctrl-C handler during execution of a function. +Temporarily reverses the effect of "disable_sigint". -A one-dimensional inverse FFT computes +""" +reenable_sigint - \operatorname{IDFT}(A)[k] = - \frac{1}{\operatorname{length}(A)} - \sum_{n=1}^{\operatorname{length}(A)} - \exp\left(+i\frac{2\pi (n-1)(k-1)} - {\operatorname{length}(A)} \right) A[n]. +doc""" + reim(z) + +Return both the real and imaginary parts of the complex number +"z" -A multidimensional inverse FFT simply performs this operation along -each transformed dimension of "A". """ -ifft +reim doc""" - ifft!(A[, dims]) + reinterpret(type, A) + +Change the type-interpretation of a block of memory. For example, +"reinterpret(Float32, UInt32(7))" interprets the 4 bytes +corresponding to "UInt32(7)" as a "Float32". For arrays, this +constructs an array with the same binary data as the given array, +but with the specified element type. -Same as "ifft()", but operates in-place on "A". """ -ifft! +reinterpret doc""" - bfft(A[, dims]) + reload(file::AbstractString) -Similar to "ifft()", but computes an unnormalized inverse -(backward) transform, which must be divided by the product of the -sizes of the transformed dimensions in order to obtain the inverse. -(This is slightly more efficient than "ifft()" because it omits a -scaling step, which in some applications can be combined with other -computational steps elsewhere.) +Like "require", except forces loading of files regardless of +whether they have been loaded before. Typically used when +interactively developing libraries. - \operatorname{BDFT}(A)[k] = \operatorname{length}(A) - \operatorname{IDFT}(A)[k] """ -bfft +reload doc""" - bfft!(A[, dims]) + relpath(path::AbstractString, startpath::AbstractString = ".") -> AbstractString + +Return a relative filepath to path either from the current +directory or from an optional start directory. This is a path +computation: the filesystem is not accessed to confirm the +existence or nature of path or startpath. -Same as "bfft()", but operates in-place on "A". """ -bfft! +relpath doc""" - plan_fft(A[, dims[, flags[, timelimit]]]) - -Pre-plan an optimized FFT along given dimensions ("dims") of -arrays matching the shape and type of "A". (The first two -arguments have the same meaning as for "fft()".) Returns a -function "plan(A)" that computes "fft(A, dims)" quickly. + rem(x, y) +%(x, y) -The "flags" argument is a bitwise-or of FFTW planner flags, -defaulting to "FFTW.ESTIMATE". e.g. passing "FFTW.MEASURE" or -"FFTW.PATIENT" will instead spend several seconds (or more) -benchmarking different possible FFT algorithms and picking the -fastest one; see the FFTW manual for more information on planner -flags. The optional "timelimit" argument specifies a rough upper -bound on the allowed planning time, in seconds. Passing -"FFTW.MEASURE" or "FFTW.PATIENT" may cause the input array -"A" to be overwritten with zeros during plan creation. +Remainder from Euclidean division, returning a value of the same +sign as``x``, and smaller in magnitude than "y". This value is +always exact. -"plan_fft!()" is the same as "plan_fft()" but creates a plan -that operates in-place on its argument (which must be an array of -complex floating-point numbers). "plan_ifft()" and so on are -similar but produce plans that perform the equivalent of the -inverse transforms "ifft()" and so on. """ -plan_fft +rem doc""" - plan_ifft(A[, dims[, flags[, timelimit]]]) + rem1(x, m) + +Remainder after division, returning in the range (0,m] -Same as "plan_fft()", but produces a plan that performs inverse -transforms "ifft()". """ -plan_ifft +rem1 doc""" - plan_bfft(A[, dims[, flags[, timelimit]]]) + remotecall(id, func, args...) + +Call a function asynchronously on the given arguments on the +specified process. Returns a "RemoteRef". -Same as "plan_fft()", but produces a plan that performs an -unnormalized backwards transform "bfft()". """ -plan_bfft +remotecall doc""" - plan_fft!(A[, dims[, flags[, timelimit]]]) + remotecall_fetch(id, func, args...) + +Perform "fetch(remotecall(...))" in one message. -Same as "plan_fft()", but operates in-place on "A". """ -plan_fft! +remotecall_fetch doc""" - plan_ifft!(A[, dims[, flags[, timelimit]]]) + remotecall_wait(id, func, args...) + +Perform "wait(remotecall(...))" in one message. -Same as "plan_ifft()", but operates in-place on "A". """ -plan_ifft! +remotecall_wait doc""" - plan_bfft!(A[, dims[, flags[, timelimit]]]) + repeat(A, inner = Int[], outer = Int[]) + +Construct an array by repeating the entries of "A". The i-th +element of "inner" specifies the number of times that the +individual entries of the i-th dimension of "A" should be +repeated. The i-th element of "outer" specifies the number of +times that a slice along the i-th dimension of "A" should be +repeated. -Same as "plan_bfft()", but operates in-place on "A". """ -plan_bfft! +repeat doc""" - rfft(A[, dims]) + repeated(x[, n::Int]) -Multidimensional FFT of a real array A, exploiting the fact that -the transform has conjugate symmetry in order to save roughly half -the computational time and storage costs compared with "fft()". -If "A" has size "(n_1, ..., n_d)", the result has size -"(floor(n_1/2)+1, ..., n_d)". +An iterator that generates the value "x" forever. If "n" is +specified, generates "x" that many times (equivalent to +"take(repeated(x), n)"). -The optional "dims" argument specifies an iterable subset of one -or more dimensions of "A" to transform, similar to "fft()". -Instead of (roughly) halving the first dimension of "A" in the -result, the "dims[1]" dimension is (roughly) halved in the same -way. """ -rfft +repeated doc""" - irfft(A, d[, dims]) + replace(string, pat, r[, n]) -Inverse of "rfft()": for a complex array "A", gives the -corresponding real array whose FFT yields "A" in the first half. -As for "rfft()", "dims" is an optional subset of dimensions to -transform, defaulting to "1:ndims(A)". +Search for the given pattern "pat", and replace each occurrence +with "r". If "n" is provided, replace at most "n" +occurrences. As with search, the second argument may be a single +character, a vector or a set of characters, a string, or a regular +expression. If "r" is a function, each occurrence is replaced +with "r(s)" where "s" is the matched substring. -"d" is the length of the transformed real array along the -"dims[1]" dimension, which must satisfy "d == -floor(size(A,dims[1])/2)+1". (This parameter cannot be inferred -from "size(A)" due to the possibility of rounding by the -"floor" function here.) """ -irfft +replace doc""" - brfft(A, d[, dims]) + repmat(A, n, m) + +Construct a matrix by repeating the given matrix "n" times in +dimension 1 and "m" times in dimension 2. -Similar to "irfft()" but computes an unnormalized inverse -transform (similar to "bfft()"), which must be divided by the -product of the sizes of the transformed dimensions (of the real -output array) in order to obtain the inverse transform. """ -brfft +repmat doc""" - plan_rfft(A[, dims[, flags[, timelimit]]]) + repr(x) + +Create a string from any value using the "showall" function. -Pre-plan an optimized real-input FFT, similar to "plan_fft()" -except for "rfft()" instead of "fft()". The first two -arguments, and the size of the transformed result, are the same as -for "rfft()". """ -plan_rfft +repr doc""" - plan_brfft(A, d[, dims[, flags[, timelimit]]]) + reprmime(mime, x) -Pre-plan an optimized real-input unnormalized transform, similar to -"plan_rfft()" except for "brfft()" instead of "rfft()". The -first two arguments and the size of the transformed result, are the -same as for "brfft()". -""" -plan_brfft +Returns an "AbstractString" or "Vector{UInt8}" containing the +representation of "x" in the requested "mime" type, as written +by "writemime" (throwing a "MethodError" if no appropriate +"writemime" is available). An "AbstractString" is returned for +MIME types with textual representations (such as ""text/html"" +or ""application/postscript""), whereas binary data is returned +as "Vector{UInt8}". (The function "istext(mime)" returns +whether or not Julia treats a given "mime" type as text.) -doc""" - plan_irfft(A, d[, dims[, flags[, timelimit]]]) +As a special case, if "x" is an "AbstractString" (for textual +MIME types) or a "Vector{UInt8}" (for binary MIME types), the +"reprmime" function assumes that "x" is already in the +requested "mime" format and simply returns "x". -Pre-plan an optimized inverse real-input FFT, similar to -"plan_rfft()" except for "irfft()" and "brfft()", -respectively. The first three arguments have the same meaning as -for "irfft()". """ -plan_irfft +reprmime doc""" - dct(A[, dims]) + require(file::AbstractString...) + +Load source files once, in the context of the "Main" module, on +every active node, searching standard locations for files. +"require" is considered a top-level operation, so it sets the +current "include" path but does not use it to search for files +(see help for "include"). This function is typically used to load +library code, and is implicitly called by "using" to load +packages. + +When searching for files, "require" first looks in the current +working directory, then looks for package code under "Pkg.dir()", +then tries paths in the global array "LOAD_PATH". -Performs a multidimensional type-II discrete cosine transform (DCT) -of the array "A", using the unitary normalization of the DCT. The -optional "dims" argument specifies an iterable subset of -dimensions (e.g. an integer, range, tuple, or array) to transform -along. Most efficient if the size of "A" along the transformed -dimensions is a product of small primes; see "nextprod()". See -also "plan_dct()" for even greater efficiency. """ -dct +require doc""" - dct!(A[, dims]) + reset(s) + +Reset a stream "s" to a previously marked position, and remove +the mark. Returns the previously marked position. Throws an error +if the stream is not marked. + +See also "mark()", "unmark()", "ismarked()" -Same as "dct!()", except that it operates in-place on "A", -which must be an array of real or complex floating-point values. """ -dct! +reset doc""" - idct(A[, dims]) + reshape(A, dims) + +Create an array with the same data as the given array, but with +different dimensions. An implementation for a particular type of +array may choose whether the data is copied or shared. -Computes the multidimensional inverse discrete cosine transform -(DCT) of the array "A" (technically, a type-III DCT with the -unitary normalization). The optional "dims" argument specifies an -iterable subset of dimensions (e.g. an integer, range, tuple, or -array) to transform along. Most efficient if the size of "A" -along the transformed dimensions is a product of small primes; see -"nextprod()". See also "plan_idct()" for even greater -efficiency. """ -idct +reshape doc""" - idct!(A[, dims]) + resize!(collection, n) -> collection -Same as "idct!()", but operates in-place on "A". -""" -idct! +Resize "collection" 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 -doc""" - plan_dct(A[, dims[, flags[, timelimit]]]) + julia> resize!([6, 5, 4, 3, 2, 1], 8) + 8-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 2 + 1 + 0 + 0 -Pre-plan an optimized discrete cosine transform (DCT), similar to -"plan_fft()" except producing a function that computes "dct()". -The first two arguments have the same meaning as for "dct()". """ -plan_dct +resize! doc""" - plan_dct!(A[, dims[, flags[, timelimit]]]) + rest(iter, state) + +An iterator that yields the same elements as "iter", but starting +at the given "state". -Same as "plan_dct()", but operates in-place on "A". """ -plan_dct! +rest doc""" - plan_idct(A[, dims[, flags[, timelimit]]]) + rethrow([e]) + +Throw an object without changing the current exception backtrace. +The default argument is the current exception (if called within a +"catch" block). -Pre-plan an optimized inverse discrete cosine transform (DCT), -similar to "plan_fft()" except producing a function that computes -"idct()". The first two arguments have the same meaning as for -"idct()". """ -plan_idct +rethrow doc""" - plan_idct!(A[, dims[, flags[, timelimit]]]) + reverse(v[, start=1[, stop=length(v)]]) + +Return a copy of "v" reversed from start to stop. -Same as "plan_idct()", but operates in-place on "A". """ -plan_idct! +reverse doc""" - fftshift(x) + reverse!(v[, start=1[, stop=length(v)]]) -> v + +In-place version of "reverse()". -Swap the first and second halves of each dimension of "x". """ -fftshift +reverse! doc""" - fftshift(x, dim) + reverseind(v, i) + +Given an index "i" in "reverse(v)", return the corresponding +index in "v" so that "v[reverseind(v,i)] == reverse(v)[i]". +(This can be nontrivial in the case where "v" is a Unicode +string.) -Swap the first and second halves of the given dimension of array -"x". """ -fftshift +reverseind doc""" - ifftshift(x[, dim]) + rfft(A[, dims]) -Undoes the effect of "fftshift". -""" -ifftshift +Multidimensional FFT of a real array A, exploiting the fact that +the transform has conjugate symmetry in order to save roughly half +the computational time and storage costs compared with "fft()". +If "A" has size "(n_1, ..., n_d)", the result has size +"(floor(n_1/2)+1, ..., n_d)". -doc""" - filt(b, a, x[, si]) +The optional "dims" argument specifies an iterable subset of one +or more dimensions of "A" to transform, similar to "fft()". +Instead of (roughly) halving the first dimension of "A" in the +result, the "dims[1]" dimension is (roughly) halved in the same +way. -Apply filter described by vectors "a" and "b" to vector "x", -with an optional initial filter state vector "si" (defaults to -zeros). """ -filt +rfft doc""" - filt!(out, b, a, x[, si]) + rm(path::AbstractString; recursive=false) + +Delete the file, link, or empty directory at the given path. If +"recursive=true" is passed and the path is a directory, then all +contents are removed recursively. -Same as "filt()" but writes the result into the "out" argument, -which may alias the input "x" to modify it in-place. """ -filt! +rm doc""" - deconv(b, a) + rmprocs(pids...) + +Removes the specified workers. -Construct vector "c" such that "b = conv(a,c) + r". Equivalent -to polynomial division. """ -deconv +rmprocs doc""" - conv(u, v) + rol(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a left rotation operation. -Convolution of two vectors. Uses FFT algorithm. """ -conv +rol doc""" - conv2(u, v, A) + rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} -2-D convolution of the matrix "A" with the 2-D separable kernel -generated by the vectors "u" and "v". Uses 2-D FFT algorithm -""" -conv2 +Performs a left rotation operation on "src" and put the result +into "dest". -doc""" - conv2(B, A) + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a left rotation operation on B. -2-D convolution of the matrix "B" with the matrix "A". Uses -2-D FFT algorithm """ -conv2 +rol! doc""" - xcorr(u, v) + ror(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a right rotation operation. -Compute the cross-correlation of two vectors. """ -xcorr +ror doc""" - r2r(A, kind[, dims]) - -Performs a multidimensional real-input/real-output (r2r) transform -of type "kind" of the array "A", as defined in the FFTW manual. -"kind" specifies either a discrete cosine transform of various -types ("FFTW.REDFT00", "FFTW.REDFT01", "FFTW.REDFT10", or -"FFTW.REDFT11"), a discrete sine transform of various types -("FFTW.RODFT00", "FFTW.RODFT01", "FFTW.RODFT10", or -"FFTW.RODFT11"), a real-input DFT with halfcomplex-format output -("FFTW.R2HC" and its inverse "FFTW.HC2R"), or a discrete -Hartley transform ("FFTW.DHT"). The "kind" argument may be an -array or tuple in order to specify different transform types along -the different dimensions of "A"; "kind[end]" is used for any -unspecified dimensions. See the FFTW manual for precise -definitions of these transform types, at http://www.fftw.org/doc. + ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} -The optional "dims" argument specifies an iterable subset of -dimensions (e.g. an integer, range, tuple, or array) to transform -along. "kind[i]" is then the transform type for "dims[i]", with -"kind[end]" being used for "i > length(kind)". +Performs a right rotation operation on "src" and put the result +into "dest". -See also "plan_r2r()" to pre-plan optimized r2r transforms. -""" -Base.FFTW.r2r + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} -doc""" - r2r!(A, kind[, dims]) +Performs a right rotation operation on B. -Same as "r2r()", but operates in-place on "A", which must be an -array of real or complex floating-point numbers. """ -Base.FFTW.r2r! +ror! doc""" - plan_r2r(A, kind[, dims[, flags[, timelimit]]]) + rot180(A) -Pre-plan an optimized r2r transform, similar to "Base.plan_fft()" -except that the transforms (and the first three arguments) -correspond to "r2r()" and "r2r!()", respectively. -""" -Base.FFTW.plan_r2r +Rotate matrix "A" 180 degrees. -doc""" - plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) + rot180(A, k) + +Rotate matrix "A" 180 degrees an integer "k" number of times. +If "k" is even, this is equivalent to a "copy". -Similar to "Base.plan_fft()", but corresponds to "r2r!()". """ -Base.FFTW.plan_r2r! +rot180 doc""" - quadgk(f, a, b, c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + rotl90(A) -Numerically integrate the function "f(x)" from "a" to "b", -and optionally over additional intervals "b" to "c" and so on. -Keyword options include a relative error tolerance "reltol" -(defaults to "sqrt(eps)" in the precision of the endpoints), an -absolute error tolerance "abstol" (defaults to 0), a maximum -number of function evaluations "maxevals" (defaults to "10^7"), -and the "order" of the integration rule (defaults to 7). +Rotate matrix "A" left 90 degrees. -Returns a pair "(I,E)" of the estimated integral "I" and an -estimated upper bound on the absolute error "E". If "maxevals" -is not exceeded then "E <= max(abstol, reltol*norm(I))" will -hold. (Note that it is useful to specify a positive "abstol" in -cases where "norm(I)" may be zero.) + rotl90(A, k) -The endpoints "a" etcetera can also be complex (in which case the -integral is performed over straight-line segments in the complex -plane). If the endpoints are "BigFloat", then the integration -will be performed in "BigFloat" precision as well (note: it is -advisable to increase the integration "order" in rough proportion -to the precision, for smooth integrands). More generally, the -precision is set by the precision of the integration endpoints -(promoted to floating-point types). +Rotate matrix "A" left 90 degrees an integer "k" number of +times. If "k" is zero or a multiple of four, this is equivalent +to a "copy". -The integrand "f(x)" can return any numeric scalar, vector, or -matrix type, or in fact any type supporting "+", "-", -multiplication by real values, and a "norm" (i.e., any normed -vector space). Alternatively, a different norm can be specified by -passing a *norm*-like function as the *norm* keyword argument -(which defaults to *vecnorm*). +""" +rotl90 -[Only one-dimensional integrals are provided by this function. For -multi-dimensional integration (cubature), there are many different -algorithms (often much better than simple nested 1d integrals) and -the optimal choice tends to be very problem-dependent. See the -Julia external-package listing for available algorithms for -multidimensional integration or other specialized tasks (such as -integrals of highly oscillatory or singular functions).] +doc""" + rotr90(A) -The algorithm is an adaptive Gauss-Kronrod integration technique: -the integral in each interval is estimated using a Kronrod rule -("2*order+1" points) and the error is estimated using an embedded -Gauss rule ("order" points). The interval with the largest -error is then subdivided into two intervals and the process is -repeated until the desired error tolerance is achieved. +Rotate matrix "A" right 90 degrees. -These quadrature rules work best for smooth functions within each -interval, so if your function has a known discontinuity or other -singularity, it is best to subdivide your interval to put the -singularity at an endpoint. For example, if "f" has a -discontinuity at "x=0.7" and you want to integrate from 0 to 1, -you should use "quadgk(f, 0,0.7,1)" to subdivide the interval at -the point of discontinuity. The integrand is never evaluated -exactly at the endpoints of the intervals, so it is possible to -integrate functions that diverge at the endpoints as long as the -singularity is integrable (for example, a "log(x)" or -"1/sqrt(x)" singularity). + rotr90(A, k) + +Rotate matrix "A" right 90 degrees an integer "k" number of +times. If "k" is zero or a multiple of four, this is equivalent +to a "copy". -For real-valued endpoints, the starting and/or ending points may be -infinite. (A coordinate transformation is performed internally to -map the infinite interval to a finite one.) """ -quadgk +rotr90 doc""" - bin(n[, pad]) + round([T], x[, digits[, base]][, r::RoundingMode]) -Convert an integer to a binary string, optionally specifying a -number of digits to pad to. -""" -bin +"round(x)" rounds "x" to an integer value according to the +default rounding mode (see "get_rounding()"), returning a value +of the same type as "x". By default ("RoundNearest"), this will +round to the nearest integer, with ties (fractional values of 0.5) +being rounded to the even integer. -doc""" - hex(n[, pad]) + julia> round(1.7) + 2.0 -Convert an integer to a hexadecimal string, optionally specifying a -number of digits to pad to. -""" -hex + julia> round(1.5) + 2.0 -doc""" - dec(n[, pad]) + julia> round(2.5) + 2.0 -Convert an integer to a decimal string, optionally specifying a -number of digits to pad to. -""" -dec +The optional "RoundingMode" argument will change how the number +gets rounded. -doc""" - oct(n[, pad]) +"round(T, x, [r::RoundingMode])" converts the result to type +"T", throwing an "InexactError" if the value is not +representable. -Convert an integer to an octal string, optionally specifying a -number of digits to pad to. -""" -oct +"round(x, digits)" rounds to the specified number of digits after +the decimal place (or before if negative). "round(x, digits, +base)" rounds using a base other than 10. -doc""" - base(base, n[, pad]) + julia> round(pi, 2) + 3.14 -Convert an integer to a string in the given base, optionally -specifying a number of digits to pad to. The base can be specified -as either an integer, or as a "UInt8" array of character values -to use as digit symbols. -""" -base + julia> round(pi, 3, 2) + 3.125 -doc""" - digits(n[, base][, pad]) +Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the "Float64" value represented by "1.15" is + actually *less* than 1.15, yet will be rounded to 1.2. + + julia> x = 1.15 + 1.15 + + julia> @sprintf "%.20f" x + "1.14999999999999991118" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + + round(z, RoundingModeReal, RoundingModeImaginary) + +Returns the nearest integral value of the same type as the complex- +valued "z" to "z", breaking ties using the specified +"RoundingMode"s. The first "RoundingMode" is used for rounding +the real components while the second is used for rounding the +imaginary components. -Returns an array of the digits of "n" in the given base, -optionally padded with zeros to a specified size. More significant -digits are at higher indexes, such that "n == -sum([digits[k]*base^(k-1) for k=1:length(digits)])". """ -digits +round doc""" - digits!(array, n[, base]) + rowvals(A) + +Return a vector of the row indices of "A", and any modifications +to the returned vector will mutate "A" as well. Given the +internal storage format of sparse matrices, providing access to how +the row indices are stored internally can be useful in conjuction +with iterating over structural nonzero values. See "nonzeros(A)" +and "nzrange(A, col)". -Fills an array of the digits of "n" in the given base. More -significant digits are at higher indexes. If the array length is -insufficient, the least significant digits are filled up to the -array length. If the array length is excessive, the excess portion -is filled with zeros. """ -digits! +rowvals doc""" - bits(n) + rpad(string, n, p) + +Make a string at least "n" columns wide when printed, by padding +on the right with copies of "p". -A string giving the literal bit representation of a number. """ -bits +rpad doc""" - parse(type, str[, base]) + rsearch(string, chars[, start]) + +Similar to "search", but returning the last occurrence of the +given characters within the given string, searching in reverse from +"start". -Parse a string as a number. If the type is an integer type, then a -base can be specified (the default is 10). If the type is a -floating point type, the string is parsed as a decimal floating -point number. If the string does not contain a valid number, an -error is raised. """ -parse +rsearch doc""" - tryparse(type, str[, base]) + rsearchindex(string, substring[, start]) + +Similar to "rsearch", but return only the start index at which +the substring is found, or 0 if it is not. -Like "parse", but returns a "Nullable" of the requested type. -The result will be null if the string does not contain a valid -number. """ -tryparse +rsearchindex doc""" - big(x) + rsplit(string, [chars]; limit=0, keep=true) + +Similar to "split", but starting from the end of the string. -Convert a number to a maximum precision representation (typically -"BigInt" or "BigFloat"). See "BigFloat" for information about -some pitfalls with floating-point numbers. """ -big +rsplit doc""" - signed(x) + rstrip(string[, chars]) + +Return "string" with any trailing whitespace removed. If +"chars" (a character, or vector or set of characters) is +provided, instead remove characters contained in it. -Convert a number to a signed integer. If the argument is unsigned, -it is reinterpreted as signed without checking for overflow. """ -signed +rstrip doc""" - unsigned(x) -> Unsigned + run(command) + +Run a command object, constructed with backticks. Throws an error +if anything goes wrong, including the process exiting with a non- +zero status. -Convert a number to an unsigned integer. If the argument is signed, -it is reinterpreted as unsigned without checking for negative -values. """ -unsigned +run doc""" - float(x) + runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) + +Run the Julia unit tests listed in "tests", which can be either a +string or an array of strings, using "numcores" processors. (not +exported) -Convert a number, array, or string to a "FloatingPoint" data -type. For numeric data, the smallest suitable "FloatingPoint" -type is used. Converts strings to "Float64". """ -float +runtests doc""" - significand(x) + scale(A, b) -Extract the significand(s) (a.k.a. mantissa), in binary -representation, of a floating-point number or array. If "x" is a -non-zero finite number, than the result will be a number of the -same type on the interval [1,2). Otherwise "x" is returned. + scale(b, A) - julia> significand(15.2)/15.2 - 0.125 +Scale an array "A" by a scalar "b", returning a new array. - julia> significand(15.2)*8 - 15.2 -""" -significand +If "A" is a matrix and "b" is a vector, then "scale(A,b)" +scales each column "i" of "A" by "b[i]" (similar to +"A*diagm(b)"), while "scale(b,A)" scales each row "i" of +"A" by "b[i]" (similar to "diagm(b)*A"), returning a new +array. -doc""" - exponent(x) -> Int +Note: for large "A", "scale" can be much faster than "A .* b" +or "b .* A", due to the use of BLAS. -Get the exponent of a normalized floating-point number. """ -exponent +scale doc""" - complex(r[, i]) + scale!(A, b) -Convert real numbers or arrays to complex. "i" defaults to zero. -""" -complex + scale!(b, A) -doc""" - bswap(n) +Scale an array "A" by a scalar "b", similar to "scale()" but +overwriting "A" in-place. + +If "A" is a matrix and "b" is a vector, then "scale!(A,b)" +scales each column "i" of "A" by "b[i]" (similar to +"A*diagm(b)"), while "scale!(b,A)" scales each row "i" of +"A" by "b[i]" (similar to "diagm(b)*A"), again operating in- +place on "A". -Byte-swap an integer """ -bswap +scale! doc""" - num2hex(f) + schedule(t::Task, [val]; error=false) -Get a hexadecimal string of the binary representation of a floating -point number -""" -num2hex +Add a task to the scheduler's queue. This causes the task to run +constantly when the system is otherwise idle, unless the task +performs a blocking operation such as "wait". -doc""" - hex2num(str) +If a second argument is provided, it will be passed to the task +(via the return value of "yieldto") when it runs again. If +"error" is true, the value is raised as an exception in the woken +task. -Convert a hexadecimal string to the floating point number it -represents """ -hex2num +schedule doc""" - hex2bytes(s::ASCIIString) + schur(A) -> Schur[:T], Schur[:Z], Schur[:values] -Convert an arbitrarily long hexadecimal string to its binary -representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. -""" -hex2bytes +See "schurfact()" -doc""" - bytes2hex(bin_arr::Array{UInt8, 1}) + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + +See "schurfact()" -Convert an array of bytes to its hexadecimal representation. All -characters are in lower-case. Returns an ASCIIString. """ -bytes2hex +schur doc""" - one(x) + schurfact(A) -> Schur -Get the multiplicative identity element for the type of x (x can -also specify the type itself). For matrices, returns an identity -matrix of the appropriate size and type. -""" -one +Computes the Schur factorization of the matrix "A". The (quasi) +triangular Schur factor can be obtained from the "Schur" object +"F" with either "F[:Schur]" or "F[:T]" and the +unitary/orthogonal Schur vectors can be obtained with +"F[:vectors]" or "F[:Z]" such that +"A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" +can be obtained with "F[:values]". -doc""" - zero(x) + schurfact(A, B) -> GeneralizedSchur + +Computes the Generalized Schur (or QZ) factorization of the +matrices "A" and "B". The (quasi) triangular Schur factors can +be obtained from the "Schur" object "F" with "F[:S]" and +"F[:T]", the left unitary/orthogonal Schur vectors can be +obtained with "F[:left]" or "F[:Q]" and the right +unitary/orthogonal Schur vectors can be obtained with "F[:right]" +or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and +"B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of +"A" and "B" can be obtained with "F[:alpha]./F[:beta]". -Get the additive identity element for the type of x (x can also -specify the type itself). """ -zero +schurfact doc""" - pi -π + schurfact!(A) + +Computes the Schur factorization of "A", overwriting "A" in the +process. See "schurfact()" -The constant pi """ -pi +schurfact! doc""" - im + sdata(S::SharedArray) + +Returns the actual "Array" object backing "S" -The imaginary unit """ -im +sdata doc""" - e -eu + search(string, chars[, start]) -The constant e -""" -e +Search for the first occurrence of the given characters within the +given string. The second argument may be a single character, a +vector or a set of characters, a string, or a regular expression +(though regular expressions are only allowed on contiguous strings, +such as ASCII or UTF-8 strings). The third argument optionally +specifies a starting index. The return value is a range of indexes +where the matching sequence is found, such that "s[search(s,x)] == +x": -doc""" - catalan +"search(string, "substring")" = "start:end" such that +"string[start:end] == "substring"", or "0:-1" if unmatched. + +"search(string, 'c')" = "index" such that +"string[index] == 'c'", or "0" if unmatched. -Catalan's constant """ -catalan +search doc""" - γ -eulergamma + searchindex(string, substring[, start]) + +Similar to "search", but return only the start index at which the +substring is found, or 0 if it is not. -Euler's constant """ -γ +searchindex doc""" - φ -golden + searchsorted(a, x, [by=,] [lt=,] [rev=false]) + +Returns the range of indices of "a" which compare as equal to +"x" according to the order specified by the "by", "lt" and +"rev" keywords, assuming that "a" is already sorted in that +order. Returns an empty range located at the insertion point if +"a" does not contain values equal to "x". -The golden ratio """ -φ +searchsorted doc""" - Inf + searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + +Returns the index of the first value in "a" greater than or equal +to "x", according to the specified order. Returns "length(a)+1" +if "x" is greater than all values in "a". -Positive infinity of type Float64 """ -Inf +searchsortedfirst doc""" - Inf32 + searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + +Returns the index of the last value in "a" less than or equal to +"x", according to the specified order. Returns "0" if "x" is +less than all values in "a". -Positive infinity of type Float32 """ -Inf32 +searchsortedlast doc""" - Inf16 + sec(x) + +Compute the secant of "x", where "x" is in radians -Positive infinity of type Float16 """ -Inf16 +sec doc""" - NaN + secd(x) + +Compute the secant of "x", where "x" is in degrees -A not-a-number value of type Float64 """ -NaN +secd doc""" - NaN32 + sech(x) + +Compute the hyperbolic secant of "x" -A not-a-number value of type Float32 """ -NaN32 +sech doc""" - NaN16 + seek(s, pos) + +Seek a stream to the given position. -A not-a-number value of type Float16 """ -NaN16 +seek doc""" - issubnormal(f) -> Bool + seekend(s) + +Seek a stream to its end. -Test whether a floating point number is subnormal """ -issubnormal +seekend doc""" - isfinite(f) -> Bool + seekstart(s) + +Seek a stream to its beginning. -Test whether a number is finite """ -isfinite +seekstart doc""" - isinf(f) -> Bool + select(v, k, [by=,] [lt=,] [rev=false]) + +Variant of "select!" which copies "v" before partially sorting +it, thereby returning the same thing as "select!" but leaving +"v" unmodified. -Test whether a number is infinite """ -isinf +select doc""" - isnan(f) -> Bool + select!(v, k, [by=,] [lt=,] [rev=false]) + +Partially sort the vector "v" in place, according to the order +specified by "by", "lt" and "rev" so that the value at index +"k" (or range of adjacent values if "k" is a range) occurs at +the position where it would appear if the array were fully sorted +via a non-stable algorithm. If "k" is a single index, that value +is returned; if "k" is a range, an array of values at those +indices is returned. Note that "select!" does not fully sort the +input array. -Test whether a floating point number is not a number (NaN) """ -isnan +select! doc""" - inf(f) + send(socket::UDPSocket, host::IPv4, port::Integer, msg) + +Send "msg" over "socket to ``host:port". -Returns positive infinity of the floating point type "f" or of -the same floating point type as "f" """ -inf +send doc""" - nan(f) + serialize(stream, value) + +Write an arbitrary value to a stream in an opaque format, such that +it can be read back by "deserialize". The read-back value will be +as identical as possible to the original. In general, this process +will not work if the reading and writing are done by different +versions of Julia, or an instance of Julia with a different system +image. -Returns NaN (not-a-number) of the floating point type "f" or of -the same floating point type as "f" """ -nan +serialize doc""" - nextfloat(f) + set_bigfloat_precision(x::Int64) + +Set the precision (in bits) to be used to BigFloat arithmetic. -Get the next floating point number in lexicographic order """ -nextfloat +set_bigfloat_precision doc""" - prevfloat(f) -> FloatingPoint + set_rounding(T, mode) -Get the previous floating point number in lexicographic order -""" -prevfloat +Set the rounding mode of floating point type "T", controlling the +rounding of basic arithmetic functions ("+()", "-()", "*()", +"/()" and "sqrt()") and type conversion. -doc""" - isinteger(x) -> Bool +Note that this may affect other types, for instance changing the +rounding mode of "Float64" will change the rounding mode of +"Float32". See "get_rounding" for available modes -Test whether "x" or all its elements are numerically equal to -some integer """ -isinteger +set_rounding doc""" - isreal(x) -> Bool + setdiff(s1, s2) + +Construct the set of elements in "s1" but not "s2". 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. -Test whether "x" or all its elements are numerically equal to -some real number """ -isreal +setdiff doc""" - Float32(x[, mode::RoundingMode]) - -Create a Float32 from "x". If "x" is not exactly representable -then "mode" determines how "x" is rounded. - - julia> Float32(1/3, RoundDown) - 0.3333333f0 + setdiff!(s, iterable) - julia> Float32(1/3, RoundUp) - 0.33333334f0 +Remove each element of "iterable" from set "s" in-place. -See "get_rounding" for available rounding modes. """ -Float32 +setdiff! doc""" - Float64(x[, mode::RoundingMode]) - -Create a Float64 from "x". If "x" is not exactly representable -then "mode" determines how "x" is rounded. + setenv(command, env; dir=working_dir) - julia> Float64(pi, RoundDown) - 3.141592653589793 +Set environment variables to use when running the given command. +"env" is either a dictionary mapping strings to strings, an array +of strings of the form ""var=val"", or zero or more +""var"=>val" pair arguments. In order to modify (rather than +replace) the existing environment, create "env" by "copy(ENV)" +and then setting "env["var"]=val" as desired, or use +"withenv". - julia> Float64(pi, RoundUp) - 3.1415926535897936 +The "dir" keyword argument can be used to specify a working +directory for the command. -See "get_rounding" for available rounding modes. """ -Float64 +setenv doc""" - BigInt(x) + setfield!(value, name::Symbol, x) -Create an arbitrary precision integer. "x" may be an "Int" (or -anything that can be converted to an "Int"). The usual -mathematical operators are defined for this type, and results are -promoted to a "BigInt". +Assign "x" to a named field in "value" of composite type. The +syntax "a.b = c" calls "setfield!(a, :b, c)", and the syntax +"a.(b) = c" calls "setfield!(a, b, c)". -Instances can be constructed from strings via "parse()", or using -the "big" string literal. """ -BigInt +setfield! doc""" - BigFloat(x) + setindex!(A, X, inds...) -Create an arbitrary precision floating point number. "x" may be -an "Integer", a "Float64" or a "BigInt". The usual -mathematical operators are defined for this type, and results are -promoted to a "BigFloat". +Store values from array "X" within some subset of "A" as +specified by "inds". -Note that because decimal literals are converted to floating point -numbers when parsed, "BigFloat(2.1)" may not yield what you -expect. You may instead prefer to initialize constants from strings -via "parse()", or using the "big" string literal. + 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, ...)". - julia> big"2.1" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision """ -BigFloat +setindex! doc""" - get_rounding(T) + setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) -Get the current floating point rounding mode for type "T", -controlling the rounding of basic arithmetic functions ("+()", -"-()", "*()", "/()" and "sqrt()") and type conversion. +Set UDP socket options. "multicast_loop": loopback for multicast +packets (default: true). "multicast_ttl": TTL for multicast +packets. "enable_broadcast": flag must be set to true if socket +will be used for broadcast messages, or else the UDP system will +return an access error (default: false). "ttl": Time-to-live of +packets sent on the socket. -Valid modes are "RoundNearest", "RoundToZero", "RoundUp", -"RoundDown", and "RoundFromZero" ("BigFloat" only). """ -get_rounding +setopt doc""" - set_rounding(T, mode) - -Set the rounding mode of floating point type "T", controlling the -rounding of basic arithmetic functions ("+()", "-()", "*()", -"/()" and "sqrt()") and type conversion. + shift!(collection) -> item -Note that this may affect other types, for instance changing the -rounding mode of "Float64" will change the rounding mode of -"Float32". See "get_rounding" for available modes -""" -set_rounding +Remove the first "item" from "collection". -doc""" - with_rounding(f::Function, T, mode) + julia> A = [1, 2, 3, 4, 5, 6] + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 -Change the rounding mode of floating point type "T" for the -duration of "f". It is logically equivalent to: + julia> shift!(A) + 1 - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) + julia> A + 5-element Array{Int64,1}: + 2 + 3 + 4 + 5 + 6 -See "get_rounding" for available rounding modes. """ -with_rounding +shift! doc""" - count_ones(x::Integer) -> Integer + show(x) -Number of ones in the binary representation of "x". +Write an informative text representation of a value to the current +output stream. New types should overload "show(io, x)" where the +first argument is a stream. The representation used by "show" +generally includes Julia-specific formatting and type information. - julia> count_ones(7) - 3 """ -count_ones +show doc""" - count_zeros(x::Integer) -> Integer + showall(x) -Number of zeros in the binary representation of "x". +Similar to "show", except shows all elements of arrays. - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 """ -count_zeros +showall doc""" - leading_zeros(x::Integer) -> Integer + showcompact(x) -Number of zeros leading the binary representation of "x". +Show a more compact representation of a value. This is used for +printing array elements. If a new type has a different compact +representation, it should overload "showcompact(io, x)" where the +first argument is a stream. - julia> leading_zeros(Int32(1)) - 31 """ -leading_zeros +showcompact doc""" - leading_ones(x::Integer) -> Integer + showerror(io, e) -Number of ones leading the binary representation of "x". +Show a descriptive representation of an exception object. - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 """ -leading_ones +showerror doc""" - trailing_zeros(x::Integer) -> Integer + shuffle([rng], v) -Number of zeros trailing the binary representation of "x". +Return a randomly permuted copy of "v". The optional "rng" +argument specifies a random number generator, see *Random Numbers*. - julia> trailing_zeros(2) - 1 """ -trailing_zeros +shuffle doc""" - trailing_ones(x::Integer) -> Integer + shuffle!([rng], v) -Number of ones trailing the binary representation of "x". +In-place version of "shuffle()". - julia> trailing_ones(3) - 2 """ -trailing_ones +shuffle! doc""" - isprime(x::Integer) -> Bool + sign(x) -Returns "true" if "x" is prime, and "false" otherwise. +Return "+1" if "x" is positive, "0" if "x == 0", and "-1" +if "x" is negative. - julia> isprime(3) - true """ -isprime +sign doc""" - isprime(x::BigInt[, reps = 25]) -> Bool + signbit(x) -Probabilistic primality test. Returns "true" if "x" is prime; -and "false" if "x" is not prime with high probability. The -false positive rate is about "0.25^reps". "reps = 25" is -considered safe for cryptographic applications (Knuth, -Seminumerical Algorithms). +Returns "true" if the value of the sign of "x" is negative, +otherwise "false". - julia> isprime(big(3)) - true """ -isprime +signbit doc""" - primes(n) + signed(x) + +Convert a number to a signed integer. If the argument is unsigned, +it is reinterpreted as signed without checking for overflow. -Returns a collection of the prime numbers <= "n". """ -primes +signed doc""" - isodd(x::Integer) -> Bool - -Returns "true" if "x" is odd (that is, not divisible by 2), and -"false" otherwise. + signif(x, digits[, base]) - julia> isodd(9) - true +Rounds (in the sense of "round") "x" so that there are +"digits" significant digits, under a base "base" +representation, default 10. E.g., "signif(123.456, 2)" is +"120.0", and "signif(357.913, 4, 2)" is "352.0". - julia> isodd(10) - false """ -isodd +signif doc""" - iseven(x::Integer) -> Bool - -Returns "true" is "x" is even (that is, divisible by 2), and -"false" otherwise. + significand(x) - julia> iseven(9) - false +Extract the significand(s) (a.k.a. mantissa), in binary +representation, of a floating-point number or array. If "x" is a +non-zero finite number, than the result will be a number of the +same type on the interval [1,2). Otherwise "x" is returned. - julia> iseven(10) - true -""" -iseven + julia> significand(15.2)/15.2 + 0.125 -doc""" - precision(num::FloatingPoint) + julia> significand(15.2)*8 + 15.2 -Get the precision of a floating point number, as defined by the -effective number of bits in the mantissa. """ -precision +significand doc""" - get_bigfloat_precision() + similar(array, element_type, dims) + +Create an uninitialized array of the same type as the given array, +but with the specified element type and dimensions. The second and +third arguments are both optional. The "dims" argument may be a +tuple or a series of integer arguments. For some special +"AbstractArray" objects which are not real containers (like +ranges), this function returns a standard "Array" to allow +operating on elements. -Get the precision (in bits) currently used for BigFloat arithmetic. """ -get_bigfloat_precision +similar doc""" - set_bigfloat_precision(x::Int64) + sin(x) + +Compute sine of "x", where "x" is in radians -Set the precision (in bits) to be used to BigFloat arithmetic. """ -set_bigfloat_precision +sin doc""" - with_bigfloat_precision(f::Function, precision::Integer) + sinc(x) -Change the BigFloat arithmetic precision (in bits) for the duration -of "f". It is logically equivalent to: +Compute \sin(\pi x) / (\pi x) if x \neq 0, and 1 if x = 0. - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) """ -with_bigfloat_precision +sinc doc""" - srand([rng][, seed]) + sind(x) + +Compute sine of "x", where "x" is in degrees -Reseed the random number generator. If a "seed" is provided, the -RNG will give a reproducible sequence of numbers, otherwise Julia -will get entropy from the system. For "MersenneTwister", the -"seed" may be a non-negative integer, a vector of "UInt32" -integers or a filename, in which case the seed is read from a file. -"RandomDevice" does not support seeding. """ -srand +sind doc""" - MersenneTwister([seed]) + sinh(x) + +Compute hyperbolic sine of "x" -Create a "MersenneTwister" RNG object. Different RNG objects can -have their own seeds, which may be useful for generating different -streams of random numbers. """ -MersenneTwister +sinh doc""" - RandomDevice() + sinpi(x) + +Compute \sin(\pi x) more accurately than "sin(pi*x)", +especially for large "x". -Create a "RandomDevice" RNG object. Two such objects will always -generate different streams of random numbers. """ -RandomDevice +sinpi doc""" - rand([rng][, S][, dims...]) + size(A[, dim...]) -Pick a random element or array of random elements from the set of -values specified by "S"; "S" can be +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.: -* an indexable collection (for example "1:n" or - "['x','y','z']"), or + julia> A = rand(2,3,4); -* a type: the set of values to pick from is then equivalent to - "typemin(S):typemax(S)" for integers (this is not applicable to - "BigInt"), and to [0,1) for floating point numbers; + julia> size(A, 2) + 3 + + julia> size(A,3,2) + (4,3) -"S" defaults to "Float64". """ -rand +size doc""" - rand!([rng], A[, coll]) + sizehint!(s, n) + +Suggest that collection "s" reserve capacity for at least "n" +elements. This can improve performance. -Populate the array A with random values. If the indexable -collection "coll" is specified, the values are picked randomly -from "coll". This is equivalent to "copy!(A, rand(rng, coll, -size(A)))" or "copy!(A, rand(rng, eltype(A), size(A)))" but -without allocating a new array. """ -rand! +sizehint! doc""" - bitrand([rng][, dims...]) + sizeof(type) -Generate a "BitArray" of random boolean values. -""" -bitrand +Size, in bytes, of the canonical binary representation of the given +type, if any. -doc""" - randn([rng][, dims...]) + sizeof(s::AbstractString) + +The number of bytes in string "s". -Generate a normally-distributed random number with mean 0 and -standard deviation 1. Optionally generate an array of normally- -distributed random numbers. """ -randn +sizeof doc""" - randn!([rng], A::Array{Float64, N}) + skip(s, offset) + +Seek a stream relative to the current position. -Fill the array A with normally-distributed (mean 0, standard -deviation 1) random numbers. Also see the rand function. """ -randn! +skip doc""" - randexp([rng][, dims...]) + skipchars(stream, predicate; linecomment::Char) + +Advance the stream until before the first character for which +"predicate" returns false. For example "skipchars(stream, +isspace)" will skip all whitespace. If keyword argument +"linecomment" is specified, characters from that character +through the end of a line will also be skipped. -Generate a random number according to the exponential distribution -with scale 1. Optionally generate an array of such random numbers. """ -randexp +skipchars doc""" - randexp!([rng], A::Array{Float64, N}) + sleep(seconds) + +Block the current task for a specified number of seconds. The +minimum sleep time is 1 millisecond or input of "0.001". -Fill the array A with random numbers following the exponential -distribution (with scale 1). """ -randexp! +sleep doc""" - Task(func) + slice(A, inds...) + +Returns a view of array "A" with the given indices like +"sub()", but drops all dimensions indexed with scalars. -Create a "Task" (i.e. thread, or coroutine) to execute the given -function (which must be callable with no arguments). The task exits -when this function returns. """ -Task +slice doc""" - yieldto(task, arg = nothing) + slicedim(A, d, i) + +Return all the data of "A" where the index for dimension "d" +equals "i". Equivalent to "A[:,:,...,i,:,:,...]" where "i" is +in position "d". -Switch to the given task. The first time a task is switched to, the -task's function is called with no arguments. On subsequent -switches, "arg" is returned from the task's last call to -"yieldto". This is a low-level call that only switches tasks, not -considering states or scheduling in any way. Its use is -discouraged. """ -yieldto +slicedim doc""" - current_task() + sort(v, [alg=,] [by=,] [lt=,] [rev=false]) -Get the currently running Task. -""" -current_task +Variant of "sort!" that returns a sorted copy of "v" leaving +"v" itself unmodified. -doc""" - istaskdone(task) -> Bool + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort a multidimensional array "A" along the given dimension. -Tell whether a task has exited. """ -istaskdone +sort doc""" - istaskstarted(task) -> Bool + sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the vector "v" in place. "QuickSort" is used by default +for numeric arrays while "MergeSort" is used for other arrays. +You can specify an algorithm to use via the "alg" keyword (see +Sorting Algorithms for available algorithms). The "by" keyword +lets you provide a function that will be applied to each element +before comparison; the "lt" keyword allows providing a custom +"less than" function; use "rev=true" to reverse the sorting +order. These options are independent and can be used together in +all possible combinations: if both "by" and "lt" are specified, +the "lt" function is applied to the result of the "by" +function; "rev=true" reverses whatever ordering specified via the +"by" and "lt" keywords. -Tell whether a task has started executing. """ -istaskstarted +sort! doc""" - consume(task, values...) + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the columns of matrix "A" lexicographically. -Receive the next value passed to "produce" by the specified task. -Additional arguments may be passed, to be returned from the last -"produce" call in the producer. """ -consume +sortcols doc""" - produce(value) + sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + +Return a permutation vector of indices of "v" that puts it in +sorted order. Specify "alg" to choose a particular sorting +algorithm (see Sorting Algorithms). "MergeSort" is used by +default, and since it is stable, the resulting permutation will be +the lexicographically first one that puts the input array into +sorted order – i.e. indices of equal elements appear in ascending +order. If you choose a non-stable sorting algorithm such as +"QuickSort", a different permutation that puts the array into +order may be returned. The order is specified using the same +keywords as "sort!". + +See also "sortperm!()" -Send the given value to the last "consume" call, switching to the -consumer task. If the next "consume" call passes any values, they -are returned by "produce". """ -produce +sortperm doc""" - yield() + sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + +Like "sortperm", but accepts a preallocated index vector "ix". +If "initialized" is "false" (the default), ix is initialized to +contain the values "1:length(v)". + +See also "sortperm()" -Switch to the scheduler to allow another scheduled task to run. A -task that calls this function is still runnable, and will be -restarted immediately if there are no other runnable tasks. """ -yield +sortperm! doc""" - task_local_storage(symbol) + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the rows of matrix "A" lexicographically. -Look up the value of a symbol in the current task's task-local -storage. """ -task_local_storage +sortrows doc""" - task_local_storage(symbol, value) + sparse(I, J, V[, m, n, combine]) + +Create a sparse matrix "S" of dimensions "m x n" such that +"S[I[k], J[k]] = V[k]". The "combine" function is used to +combine duplicates. If "m" and "n" are not specified, they are +set to "max(I)" and "max(J)" respectively. If the "combine" +function is not supplied, duplicates are added by default. + + sparse(A) + +Convert an AbstractMatrix "A" into a sparse matrix. -Assign a value to a symbol in the current task's task-local -storage. """ -task_local_storage +sparse doc""" - task_local_storage(body, symbol, value) + sparsevec(I, V[, m, combine]) -Call the function "body" with a modified task-local storage, in -which "value" is assigned to "symbol"; the previous value of -"symbol", or lack thereof, is restored afterwards. Useful for -emulating dynamic scoping. -""" -task_local_storage +Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] += V[k]". Duplicates are combined using the "combine" function, +which defaults to "+" if it is not provided. In julia, sparse +vectors are really just sparse matrices with one column. Given +Julia's Compressed Sparse Columns (CSC) storage format, a sparse +column matrix with one column is sparse, whereas a sparse row +matrix with one row ends up being dense. + + sparsevec(D::Dict[, m]) + +Create a sparse matrix of size "m x 1" where the row values are +keys from the dictionary, and the nonzero values are the values +from the dictionary. -doc""" - Condition() + sparsevec(A) + +Convert a dense vector "A" into a sparse matrix of size "m x +1". In julia, sparse vectors are really just sparse matrices with +one column. -Create an edge-triggered event source that tasks can wait for. -Tasks that call "wait" on a "Condition" are suspended and -queued. Tasks are woken up when "notify" is later called on the -"Condition". Edge triggering means that only tasks waiting at the -time "notify" is called can be woken up. For level-triggered -notifications, you must keep extra state to keep track of whether a -notification has happened. The "RemoteRef" type does this, and so -can be used for level-triggered events. """ -Condition +sparsevec doc""" - notify(condition, val=nothing; all=true, error=false) + spawn(command) + +Run a command object asynchronously, returning the resulting +"Process" object. -Wake up tasks waiting for a condition, passing them "val". If -"all" is true (the default), all waiting tasks are woken, -otherwise only one is. If "error" is true, the passed value is -raised as an exception in the woken tasks. """ -notify +spawn doc""" - schedule(t::Task, [val]; error=false) + spdiagm(B, d[, m, n]) -Add a task to the scheduler's queue. This causes the task to run -constantly when the system is otherwise idle, unless the task -performs a blocking operation such as "wait". +Construct a sparse diagonal matrix. "B" is a tuple of vectors +containing the diagonals and "d" is a tuple containing the +positions of the diagonals. In the case the input contains only one +diagonaly, "B" can be a vector (instead of a tuple) and "d" can +be the diagonal position (instead of a tuple), defaulting to 0 +(diagonal). Optionally, "m" and "n" specify the size of the +resulting sparse matrix. -If a second argument is provided, it will be passed to the task -(via the return value of "yieldto") when it runs again. If -"error" is true, the value is raised as an exception in the woken -task. """ -schedule +spdiagm doc""" - @schedule() + speye(type, m[, n]) + +Create a sparse identity matrix of specified type of size "m x +m". In case "n" is supplied, create a sparse identity matrix of +size "m x n". -Wrap an expression in a Task and add it to the scheduler's queue. """ -@schedule +speye doc""" - @task() + splice!(collection, index[, replacement]) -> item -Wrap an expression in a Task without executing it, and return the -Task. This only creates a task, and does not run it. -""" -@task +Remove the item at the given index, and return the removed item. +Subsequent items are shifted down to fill the resulting gap. If +specified, replacement values from an ordered collection will be +spliced in place of the removed item. -doc""" - sleep(seconds) + julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5) + 2 -Block the current task for a specified number of seconds. The -minimum sleep time is 1 millisecond or input of "0.001". -""" -sleep + julia> A + 5-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 1 -doc""" - ReentrantLock() + julia> splice!(A, 5, -1) + 1 -Creates a reentrant lock. The same task can acquire the lock as -many times as required. Each lock must be matched with an unlock. -""" -ReentrantLock + julia> A + 5-element Array{Int64,1}: + 6 + 5 + 4 + 3 + -1 -doc""" - lock(l::ReentrantLock) + julia> splice!(A, 1, [-1, -2, -3]) + 6 -Associates "l" with the current task. If "l" is already locked -by a different task, waits for it to become available. The same -task can acquire the lock multiple times. Each "lock" must be -matched by an "unlock" -""" -lock + julia> A + 7-element Array{Int64,1}: + -1 + -2 + -3 + 5 + 4 + 3 + -1 -doc""" - unlock(l::ReentrantLock) +To insert "replacement" before an index "n" without removing +any items, use "splice!(collection, n:n-1, replacement)". -Releases ownership of the lock by the current task. If the lock had -been acquired before, it just decrements an internal counter and -returns immediately. -""" -unlock + splice!(collection, range[, replacement]) -> items -doc""" - addprocs(n::Integer; exeflags=``) -> List of process identifiers +Remove items in the specified index range, and return a collection +containing the removed items. Subsequent items are shifted down to +fill the resulting gap. If specified, replacement values from an +ordered collection will be spliced in place of the removed items. -Launches workers using the in-built "LocalManager" which only -launches workers on the local host. This can be used to take -advantage of multiple cores. "addprocs(4)" will add 4 processes -on the local machine. -""" -addprocs +To insert "replacement" before an index "n" without removing +any items, use "splice!(collection, n:n-1, replacement)". -doc""" - addprocs() -> List of process identifiers + 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 -Equivalent to "addprocs(CPU_CORES)" """ -addprocs +splice! doc""" - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + split(string, [chars]; limit=0, keep=true) -Add processes on remote machines via SSH. Requires julia to be -installed in the same location on each node, or to be available via -a shared file system. +Return an array of substrings by splitting the given string on +occurrences of the given character delimiters, which may be +specified in any of the formats allowed by "search"'s second +argument (i.e. a single character, collection of characters, +string, or regular expression). If "chars" is omitted, it +defaults to the set of all space characters, and "keep" is taken +to be false. The two keyword arguments are optional: they are are a +maximum size for the result and a flag determining whether empty +fields should be kept in the result. -"machines" is a vector of machine specifications. Worker are -started for each specification. +""" +split -A machine specification is either a string "machine_spec" or a -tuple - "(machine_spec, count)" +doc""" + splitdir(path::AbstractString) -> (AbstractString, AbstractString) -"machine_spec" is a string of the form "[user@]host[:port] -[bind_addr[:port]]". "user" defaults to current user, "port" -to the standard ssh port. If "[bind_addr[:port]]" is specified, -other workers will connect to this worker at the specified -"bind_addr" and "port". +Split a path into a tuple of the directory name and file name. -"count" is the number of workers to be launched on the specified -host. If specified as ":auto" it will launch as many workers as -the number of cores on the specific host. +""" +splitdir -Keyword arguments: +doc""" + splitdrive(path::AbstractString) -> (AbstractString, AbstractString) -"tunnel" : if "true" then SSH tunneling will be used to connect -to the worker from the master process. +On Windows, split a path into the drive letter part and the path +part. On Unix systems, the first component is always the empty +string. -"sshflags" : specifies additional ssh options, e.g. -"sshflags=`-i /home/foo/bar.pem`" . +""" +splitdrive -"max_parallel" : specifies the maximum number of workers -connected to in parallel at a host. Defaults to 10. +doc""" + splitext(path::AbstractString) -> (AbstractString, AbstractString) -"dir" : specifies the working directory on the workers. Defaults -to the host's current directory (as found by *pwd()*) +If the last component of a path contains a dot, split the path into +everything before the dot and everything including and after the +dot. Otherwise, return a tuple of the argument unmodified and the +empty string. -"exename" : name of the julia executable. Defaults to -"\$JULIA_HOME/julia" or "\$JULIA_HOME/julia-debug" as the case -may be. +""" +splitext -"exeflags" : additional flags passed to the worker processes. +doc""" + spones(S) -Environment variables : +Create a sparse matrix with the same structure as that of "S", +but with every nonzero element having the value "1.0". -If the master process fails to establish a connection with a newly -launched worker within 60.0 seconds, the worker treats it a fatal -situation and terminates. This timeout can be controlled via -environment variable "JULIA_WORKER_TIMEOUT". The value of -"JULIA_WORKER_TIMEOUT" on the master process, specifies the -number of seconds a newly launched worker waits for connection -establishment. """ -addprocs +spones doc""" - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - -Launches worker processes via the specified cluster manager. + sprand([rng], m, n, p[, rfn]) -For example Beowulf clusters are supported via a custom cluster -manager implemented in package "ClusterManagers". +Create a random "m" by "n" sparse matrix, in which the +probability of any element being nonzero is independently given by +"p" (and hence the mean density of nonzeros is also exactly +"p"). Nonzero values are sampled from the distribution specified +by "rfn". The uniform distribution is used in case "rfn" is not +specified. The optional "rng" argument specifies a random number +generator, see *Random Numbers*. -The number of seconds a newly launched worker waits for connection -establishment from the master can be specified via variable -"JULIA_WORKER_TIMEOUT" in the worker process's environment. -Relevant only when using TCP/IP as transport. """ -addprocs +sprand doc""" - nprocs() + sprandbool(m, n, p) + +Create a random "m" by "n" sparse boolean matrix with the +specified (independent) probability "p" of any entry being +"true". -Get the number of available processes. """ -nprocs +sprandbool doc""" - nworkers() + sprandn(m, n, p) + +Create a random "m" by "n" sparse matrix with the specified +(independent) probability "p" of any entry being nonzero, where +nonzero values are sampled from the normal distribution. -Get the number of available worker processes. This is one less than -nprocs(). Equal to nprocs() if nprocs() == 1. """ -nworkers +sprandn doc""" - procs() + sprint(f::Function, args...) + +Call the given function with an I/O stream and the supplied extra +arguments. Everything written to this I/O stream is returned as a +string. -Returns a list of all process identifiers. """ -procs +sprint doc""" - workers() + spzeros(m, n) + +Create a sparse matrix of size "m x n". This sparse matrix will +not contain any nonzero values. No storage will be allocated for +nonzero values during construction. -Returns a list of all worker process identifiers. """ -workers +spzeros doc""" - rmprocs(pids...) + sqrt(x) + +Return \sqrt{x}. Throws "DomainError" for negative "Real" +arguments. Use complex negative arguments instead. The prefix +operator "√" is equivalent to "sqrt". -Removes the specified workers. """ -rmprocs +sqrt doc""" - interrupt([pids...]) + sqrtm(A) + +Compute the matrix square root of "A". If "B = sqrtm(A)", then +"B*B == A" within roundoff error. + +"sqrtm" uses a polyalgorithm, computing the matrix square root +using Schur factorizations ("schurfact()") unless it detects the +matrix to be Hermitian or real symmetric, in which case it computes +the matrix square root from an eigendecomposition ("eigfact()"). +In the latter situation for positive definite matrices, the matrix +square root has "Real" elements, otherwise it has "Complex" +elements. -Interrupt the current executing task on the specified workers. This -is equivalent to pressing Ctrl-C on the local machine. If no -arguments are given, all workers are interrupted. """ -interrupt +sqrtm doc""" - myid() + squeeze(A, dims) + +Remove the dimensions specified by "dims" from array "A". +Elements of "dims" must be unique and within the range +"1:ndims(A)". -Get the id of the current process. """ -myid +squeeze doc""" - pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + srand([rng][, seed]) -Transform collections "lsts" by applying "f" to each element in -parallel. If "nprocs() > 1", the calling process will be -dedicated to assigning tasks. All other available processes will be -used as parallel workers, or on the processes specified by -"pids". +Reseed the random number generator. If a "seed" is provided, the +RNG will give a reproducible sequence of numbers, otherwise Julia +will get entropy from the system. For "MersenneTwister", the +"seed" may be a non-negative integer, a vector of "UInt32" +integers or a filename, in which case the seed is read from a file. +"RandomDevice" does not support seeding. -If "err_retry" is true, it retries a failed application of "f" -on a different worker. If "err_stop" is true, it takes precedence -over the value of "err_retry" and "pmap" stops execution on the -first error. """ -pmap +srand doc""" - remotecall(id, func, args...) + start(iter) -> state + +Get initial iteration state for an iterable object -Call a function asynchronously on the given arguments on the -specified process. Returns a "RemoteRef". """ -remotecall +start doc""" - wait([x]) + startswith(string, prefix | chars) -Block the current task until some event occurs, depending on the -type of the argument: +Returns "true" if "string" starts with "prefix". If the +second argument is a vector or set of characters, tests whether the +first character of "string" belongs to that set. -* "RemoteRef": Wait for a value to become available for the - specified remote reference. +""" +startswith -* "Condition": Wait for "notify" on a condition. +doc""" + stat(file) -* "Process": Wait for a process or process chain to exit. The - "exitcode" field of a process can be used to determine success - or failure. +Returns a structure whose fields contain information about the +file. The fields of the structure are: -* "Task": Wait for a "Task" to finish, returning its result - value. If the task fails with an exception, the exception is - propagated (re-thrown in the task that called "wait"). ++-----------+------------------------------------------------------------------------+ +| size | The size (in bytes) of the file | ++-----------+------------------------------------------------------------------------+ +| device | ID of the device that contains the file | ++-----------+------------------------------------------------------------------------+ +| inode | The inode number of the file | ++-----------+------------------------------------------------------------------------+ +| mode | The protection mode of the file | ++-----------+------------------------------------------------------------------------+ +| nlink | The number of hard links to the file | ++-----------+------------------------------------------------------------------------+ +| uid | The user id of the owner of the file | ++-----------+------------------------------------------------------------------------+ +| gid | The group id of the file owner | ++-----------+------------------------------------------------------------------------+ +| rdev | If this file refers to a device, the ID of the device it refers to | ++-----------+------------------------------------------------------------------------+ +| blksize | The file-system preferred block size for the file | ++-----------+------------------------------------------------------------------------+ +| blocks | The number of such blocks allocated | ++-----------+------------------------------------------------------------------------+ +| mtime | Unix timestamp of when the file was last modified | ++-----------+------------------------------------------------------------------------+ +| ctime | Unix timestamp of when the file was created | ++-----------+------------------------------------------------------------------------+ -* "RawFD": Wait for changes on a file descriptor (see *poll_fd* - for keyword arguments and return code) +""" +stat -If no argument is passed, the task blocks for an undefined period. -If the task's state is set to ":waiting", it can only be -restarted by an explicit call to "schedule" or "yieldto". If -the task's state is ":runnable", it might be restarted -unpredictably. +doc""" + std(v[, region]) + +Compute the sample standard deviation of a vector or array "v", +optionally along dimensions in "region". The algorithm returns an +estimator of the generative distribution's standard deviation under +the assumption that each entry of "v" is an IID drawn from that +generative distribution. This computation is equivalent to +calculating "sqrt(sum((v - mean(v)).^2) / (length(v) - 1))". +Note: Julia does not ignore "NaN" values in the computation. For +applications requiring the handling of missing data, the +"DataArray" package is recommended. -Often "wait" is called within a "while" loop to ensure a -waited-for condition is met before proceeding. """ -wait +std doc""" - fetch(RemoteRef) + stdm(v, m) + +Compute the sample standard deviation of a vector "v" with known +mean "m". Note: Julia does not ignore "NaN" values in the +computation. -Wait for and get the value of a remote reference. """ -fetch +stdm doc""" - remotecall_wait(id, func, args...) + step(r) + +Get the step size of a "Range" object. -Perform "wait(remotecall(...))" in one message. """ -remotecall_wait +step doc""" - remotecall_fetch(id, func, args...) + stride(A, k) + +Returns the distance in memory (in number of elements) between +adjacent elements in dimension k -Perform "fetch(remotecall(...))" in one message. """ -remotecall_fetch +stride doc""" - put!(RemoteRef, value) + strides(A) + +Returns a tuple of the memory strides in each dimension -Store a value to a remote reference. Implements "shared queue of -length 1" semantics: if a value is already present, blocks until -the value is removed with "take!". Returns its first argument. """ -put! +strides doc""" - take!(RemoteRef) + string(xs...) + +Create a string from any values using the "print" function. -Fetch the value of a remote reference, removing it so that the -reference is empty again. """ -take! +string doc""" - isready(r::RemoteRef) - -Determine whether a "RemoteRef" has a value stored to it. Note -that this function can cause race conditions, since by the time you -receive its result it may no longer be true. It is recommended that -this function only be used on a "RemoteRef" that is assigned -once. + stringmime(mime, x) -If the argument "RemoteRef" is owned by a different node, this -call will block to wait for the answer. It is recommended to wait -for "r" in a separate task instead, or to use a local -"RemoteRef" as a proxy: +Returns an "AbstractString" containing the representation of +"x" in the requested "mime" type. This is similar to +"reprmime" except that binary data is base64-encoded as an ASCII +string. - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block """ -isready +stringmime doc""" - RemoteRef() + strip(string[, chars]) + +Return "string" with any leading and trailing whitespace removed. +If "chars" (a character, or vector or set of characters) is +provided, instead remove characters contained in it. -Make an uninitialized remote reference on the local machine. """ -RemoteRef +strip doc""" - RemoteRef(n) + strwidth(s) + +Gives the number of columns needed to print a string. -Make an uninitialized remote reference on process "n". """ -RemoteRef +strwidth doc""" - timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + sub(A, inds...) + +Like "getindex()", but returns a view into the parent array "A" +with the given indices instead of making a copy. Calling +"getindex()" or "setindex!()" on the returned "SubArray" +computes the indices to the parent array on the fly without +checking bounds. -Waits till "testcb" returns "true" or for "secs`" seconds, -whichever is earlier. "testcb" is polled every "pollint" -seconds. """ -timedwait +sub doc""" - @spawn() + sub2ind(dims, i, j, k...) -> index + +The inverse of "ind2sub", returns the linear index corresponding +to the provided subscripts -Execute an expression on an automatically-chosen process, returning -a "RemoteRef" to the result. """ -@spawn +sub2ind doc""" - @spawnat() + subtypes(T::DataType) + +Return a list of immediate subtypes of DataType T. Note that all +currently loaded subtypes are included, including those not visible +in the current module. -Accepts two arguments, "p" and an expression, and runs the -expression asynchronously on process "p", returning a -"RemoteRef" to the result. """ -@spawnat +subtypes doc""" - @fetch() + success(command) + +Run a command object, constructed with backticks, and tell whether +it was successful (exited with a code of 0). An exception is raised +if the process cannot be started. -Equivalent to "fetch(@spawn expr)". """ -@fetch +success doc""" - @fetchfrom() + sum(itr) + +Returns the sum of all elements in a collection. + + sum(A, dims) + +Sum elements of an array over the given dimensions. + + sum(f, itr) + +Sum the results of calling function "f" on each element of +"itr". -Equivalent to "fetch(@spawnat p expr)". """ -@fetchfrom +sum doc""" - @async() + sum!(r, A) + +Sum elements of "A" over the singleton dimensions of "r", and +write results to "r". -Schedule an expression to run on the local machine, also adding it -to the set of items that the nearest enclosing "@sync" waits for. """ -@async +sum! doc""" - @sync() + sum_kbn(A) + +Returns the sum of all array elements, using the Kahan-Babuska- +Neumaier compensated summation algorithm for additional accuracy. -Wait until all dynamically-enclosed uses of "@async", "@spawn", -"@spawnat" and "@parallel" are complete. """ -@sync +sum_kbn doc""" - @parallel() - -A parallel for loop of the form + sumabs(itr) - @parallel [reducer] for var = range - body - end +Sum absolute values of all elements in a collection. This is +equivalent to *sum(abs(itr))* but faster. -The specified range is partitioned and locally executed across all -workers. In case an optional reducer function is specified, -@parallel performs local reductions on each worker with a final -reduction on the calling process. + sumabs(A, dims) -Note that without a reducer function, @parallel executes -asynchronously, i.e. it spawns independent tasks on all available -workers and returns immediately without waiting for completion. To -wait for completion, prefix the call with "@sync", like +Sum absolute values of elements of an array over the given +dimensions. - @sync @parallel for var = range - body - end """ -@parallel +sumabs doc""" - SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - -Construct a SharedArray of a bitstype "T" and size "dims" -across the processes specified by "pids" - all of which have to -be on the same host. + sumabs!(r, A) -If "pids" is left unspecified, the shared array will be mapped -across all processes on the current host, including the master. -But, "localindexes" and "indexpids" will only refer to worker -processes. This facilitates work distribution code to use workers -for actual computation with the master process acting as a driver. +Sum absolute values of elements of "A" over the singleton +dimensions of "r", and write results to "r". -If an "init" function of the type "initfn(S::SharedArray)" is -specified, it is called on all the participating workers. """ -SharedArray +sumabs! doc""" - procs(S::SharedArray) + sumabs2(itr) + +Sum squared absolute values of all elements in a collection. This +is equivalent to *sum(abs2(itr))* but faster. + + sumabs2(A, dims) + +Sum squared absolute values of elements of an array over the given +dimensions. -Get the vector of processes that have mapped the shared array """ -procs +sumabs2 doc""" - sdata(S::SharedArray) + sumabs2!(r, A) + +Sum squared absolute values of elements of "A" over the singleton +dimensions of "r", and write results to "r". -Returns the actual "Array" object backing "S" """ -sdata +sumabs2! doc""" - indexpids(S::SharedArray) + summary(x) + +Return a string giving a brief description of a value. By default +returns "string(typeof(x))". For arrays, returns strings like +"2x2 Float64 Array". -Returns the index of the current worker into the "pids" vector, -i.e., the list of workers mapping the SharedArray """ -indexpids +summary doc""" - launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) + super(T::DataType) + +Return the supertype of DataType T -Implemented by cluster managers. For every Julia worker launched by -this function, it should append a "WorkerConfig" entry to -"launched" and notify "launch_ntfy". The function MUST exit -once all workers, requested by "manager" have been launched. -"params" is a dictionary of all keyword arguments "addprocs" -was called with. """ -launch +super doc""" - manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + svd(A[, thin=true]) -> U, S, V -Implemented by cluster managers. It is called on the master -process, during a worker's lifetime, with appropriate "op" -values: +Wrapper around "svdfact" extracting all parts the factorization +to a tuple. Direct use of "svdfact" is therefore generally more +efficient. Computes the SVD of A, returning "U", vector "S", +and "V" such that "A == U*diagm(S)*V'". If "thin" is +"true", an economy mode decomposition is returned. The default is +to produce a thin decomposition. - * with ":register"/":deregister" when a worker is added / - removed from the Julia worker pool. + svd(A, B) -> U, V, Q, D1, D2, R0 - * with ":interrupt" when "interrupt(workers)" is called. - The "ClusterManager" should signal the appropriate worker - with an interrupt signal. +Wrapper around "svdfact" extracting all parts the factorization +to a tuple. Direct use of "svdfact" is therefore generally more +efficient. The function returns the generalized SVD of "A" and +"B", returning "U", "V", "Q", "D1", "D2", and "R0" +such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". - * with ":finalize" for cleanup purposes. """ -manage +svd doc""" - kill(manager::FooManager, pid::Int, config::WorkerConfig) + svdfact(A[, thin=true]) -> SVD -Implemented by cluster managers. It is called on the master -process, by "rmprocs". It should cause the remote worker -specified by "pid" to exit. -"Base.kill(manager::ClusterManager.....)" executes a remote -"exit()" on "pid" -""" -kill +Compute the Singular Value Decomposition (SVD) of "A" and return +an "SVD" object. "U", "S", "V" and "Vt" can be obtained +from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" +and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is +"true", an economy mode decomposition is returned. The algorithm +produces "Vt" and hence "Vt" is more efficient to extract than +"V". The default is to produce a thin decomposition. -doc""" - init_worker(manager::FooManager) + svdfact(A, B) -> GeneralizedSVD + +Compute the generalized SVD of "A" and "B", returning a +"GeneralizedSVD" Factorization object "F", such that "A = +F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = +F[:V]*F[:D2]*F[:R0]*F[:Q]'". -Called by cluster managers implementing custom transports. It -initializes a newly launched process as a worker. Command line -argument "--worker" has the effect of initializing a process as a -worker using TCP/IP sockets for transport. """ -init_worker +svdfact doc""" - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + svdfact!(A[, thin=true]) -> SVD + +"svdfact!" is the same as "svdfact()", but saves space by +overwriting the input A, instead of creating a copy. If "thin" is +"true", an economy mode decomposition is returned. The default is +to produce a thin decomposition. -Implemented by cluster managers using custom transports. It should -establish a logical connection to worker with id "pid", specified -by "config" and return a pair of "AsyncStream" objects. -Messages from "pid" to current process will be read off -"instrm", while messages to be sent to "pid" will be written to -"outstrm". The custom transport implementation must ensure that -messages are delivered and received completely and in order. -"Base.connect(manager::ClusterManager.....)" sets up TCP/IP -socket connections in-between workers. """ -connect +svdfact! doc""" - Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) -Called by cluster managers using custom transports. It should be -called when the custom transport implementation receives the first -message from a remote worker. The custom transport must manage a -logical connection to the remote worker and provide two AsyncStream -objects, one for incoming messages and the other for messages -addressed to the remote worker. -""" -Base +"svds" computes largest singular values "s" of "A" using +Lanczos or Arnoldi iterations. Uses "eigs()" underneath. -doc""" - dir() -> AbstractString +Inputs are: + * "A": Linear operator. It can either subtype of + "AbstractArray" (e.g., sparse matrix) or duck typed. For + duck typing "A" has to support "size(A)", "eltype(A)", + "A * vector" and "A' * vector". -Returns the absolute path of the package directory. This defaults -to "joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION -.minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell -syntax). If the "JULIA_PKGDIR" environment variable is set, then -that path is used in the returned value as "joinpath(ENV["JULIA_ -PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")". If -"JULIA_PKGDIR" is a relative path, it is interpreted relative to -whatever the current working directory is. -""" -Base.Pkg.dir + * "nsv": Number of singular values. + + * "ritzvec": Whether to return the left and right singular + vectors "left_sv" and "right_sv", default is "true". If + "false" the singular vectors are omitted from the output. -doc""" - dir(names...) -> AbstractString + * "tol": tolerance, see "eigs()". -Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends -path components to the package directory and normalizes the -resulting path. In particular, "Pkg.dir(pkg)" returns the path to -the package "pkg". -""" -Base.Pkg.dir + * "maxiter": Maximum number of iterations, see "eigs()". -doc""" - init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) +**Example**: + + X = sprand(10, 5, 0.2) + svds(X, nsv = 2) -Initialize "Pkg.dir()" as a package directory. This will be done -automatically when the "JULIA_PKGDIR" is not set and -"Pkg.dir()" uses its default value. As part of this process, -clones a local METADATA git repository from the site and branch -specified by its arguments, which are typically not provided. -Explicit (non-default) arguments can be used to support a custom -METADATA setup. """ -Base.Pkg.init +svds doc""" - resolve() + svdvals(A) -Determines an optimal, consistent set of package versions to -install or upgrade to. The optimal set of package versions is based -on the contents of "Pkg.dir("REQUIRE")" and the state of -installed packages in "Pkg.dir()", Packages that are no longer -required are moved into "Pkg.dir(".trash")". -""" -Base.Pkg.resolve +Returns the singular values of "A". -doc""" - edit() + svdvals(A, B) + +Return only the singular values from the generalized singular value +decomposition of "A" and "B". -Opens "Pkg.dir("REQUIRE")" in the editor specified by the -"VISUAL" or "EDITOR" environment variables; when the editor -command returns, it runs "Pkg.resolve()" to determine and install -a new optimal set of installed package versions. """ -Base.Pkg.edit +svdvals doc""" - add(pkg, vers...) + svdvals!(A) + +Returns the singular values of "A", while saving space by +overwriting the input. -Add a requirement entry for "pkg" to "Pkg.dir("REQUIRE")" and -call "Pkg.resolve()". If "vers" are given, they must be -"VersionNumber" objects and they specify acceptable version -intervals for "pkg". """ -Base.Pkg.add +svdvals! doc""" - rm(pkg) + sylvester(A, B, C) + +Computes the solution "X" to the Sylvester equation "AX + XB + C += 0", where "A", "B" and "C" have compatible dimensions and +"A" and "-B" have no eigenvalues with equal real part. -Remove all requirement entries for "pkg" from -"Pkg.dir("REQUIRE")" and call "Pkg.resolve()". """ -Base.Pkg.rm +sylvester doc""" - clone(url[, pkg]) + symbol(x...) -> Symbol + +Create a "Symbol" by concatenating the string representations of +the arguments together. -Clone a package directly from the git URL "url". The package does -not need to be a registered in "Pkg.dir("METADATA")". The -package repo is cloned by the name "pkg" if provided; if not -provided, "pkg" is determined automatically from "url". """ -Base.Pkg.clone +symbol doc""" - clone(pkg) + symdiff(s1, s2...) + +Construct the symmetric difference of elements in the passed in +sets or arrays. Maintains order with arrays. -If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone -it from that URL on the default branch. The package does not need -to have any registered versions. """ -Base.Pkg.clone +symdiff doc""" - available() -> Vector{ASCIIString} + symdiff!(s, n) -Returns the names of available packages. -""" -Base.Pkg.available +The set "s" is destructively modified to toggle the inclusion of +integer "n". -doc""" - available(pkg) -> Vector{VersionNumber} + symdiff!(s, itr) -Returns the version numbers available for package "pkg". -""" -Base.Pkg.available +For each element in "itr", destructively toggle its inclusion in +set "s". -doc""" - installed() -> Dict{ASCIIString,VersionNumber} + symdiff!(s1, s2) + +Construct the symmetric difference of sets "s1" and "s2", +storing the result in "s1". -Returns a dictionary mapping installed package names to the -installed version number of each package. """ -Base.Pkg.installed +symdiff! doc""" - installed(pkg) -> Void | VersionNumber + symlink(target, link) -If "pkg" is installed, return the installed version number, -otherwise return "nothing". -""" -Base.Pkg.installed +Creates a symbolic link to "target" with the name "link". -doc""" - status() +Note: This function raises an error under operating systems that + do not support soft symbolic links, such as Windows XP. -Prints out a summary of what packages are installed and what -version and state they're in. """ -Base.Pkg.status +symlink doc""" - update() + symperm(A, p) + +Return the symmetric permutation of A, which is "A[p,p]". A +should be symmetric and sparse, where only the upper triangular +part of the matrix is stored. This algorithm ignores the lower +triangular part of the matrix. Only the upper triangular part of +the result is returned as well. -Update package the metadata repo – kept in -"Pkg.dir("METADATA")" – then update any fixed packages that can -safely be pulled from their origin; then call "Pkg.resolve()" to -determine a new optimal set of packages versions. """ -Base.Pkg.update +symperm doc""" - checkout(pkg[, branch="master"]) + systemerror(sysfunc, iftrue) + +Raises a "SystemError" for "errno" with the descriptive string +"sysfunc" if "bool" is true -Checkout the "Pkg.dir(pkg)" repo to the branch "branch". -Defaults to checking out the "master" branch. To go back to using -the newest compatible released version, use "Pkg.free(pkg)" """ -Base.Pkg.checkout +systemerror doc""" - pin(pkg) + take(iter, n) + +An iterator that generates at most the first "n" elements of +"iter". -Pin "pkg" at the current version. To go back to using the newest -compatible released version, use "Pkg.free(pkg)" """ -Base.Pkg.pin +take doc""" - pin(pkg, version) + take!(RemoteRef) + +Fetch the value of a remote reference, removing it so that the +reference is empty again. -Pin "pkg" at registered version "version". """ -Base.Pkg.pin +take! doc""" - free(pkg) + takebuf_array(b::IOBuffer) -Free the package "pkg" to be managed by the package manager -again. It calls "Pkg.resolve()" to determine optimal package -versions after. This is an inverse for both "Pkg.checkout" and -"Pkg.pin". +Obtain the contents of an "IOBuffer" as an array, without +copying. Afterwards, the IOBuffer is reset to its initial state. -You can also supply an iterable collection of package names, e.g., -"Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at -once. """ -Base.Pkg.free +takebuf_array doc""" - build() + takebuf_string(b::IOBuffer) + +Obtain the contents of an "IOBuffer" as a string, without +copying. Afterwards, the IOBuffer is reset to its initial state. -Run the build scripts for all installed packages in depth-first -recursive order. """ -Base.Pkg.build +takebuf_string doc""" - build(pkgs...) + tan(x) + +Compute tangent of "x", where "x" is in radians -Run the build script in "deps/build.jl" for each package in -"pkgs" and all of their dependencies in depth-first recursive -order. This is called automatically by "Pkg.resolve()" on all -installed or updated packages. """ -Base.Pkg.build +tan doc""" - generate(pkg, license) + tand(x) + +Compute tangent of "x", where "x" is in degrees -Generate a new package named "pkg" with one of these license -keys: ""MIT"", ""BSD"" or ""ASL"". If you want to make -a package with a different license, you can edit it afterwards. -Generate creates a git repo at "Pkg.dir(pkg)" for the package and -inside it "LICENSE.md", "README.md", the julia entrypoint -"\$pkg/src/\$pkg.jl", and a travis test file, ".travis.yml". """ -Base.Pkg.generate +tand doc""" - register(pkg[, url]) + tanh(x) + +Compute hyperbolic tangent of "x" -Register "pkg" at the git URL "url", defaulting to the -configured origin URL of the git repo "Pkg.dir(pkg)". """ -Base.Pkg.register +tanh doc""" - tag(pkg[, ver[, commit]]) + task_local_storage(symbol) -Tag "commit" as version "ver" of package "pkg" and create a -version entry in "METADATA". If not provided, "commit" defaults -to the current commit of the "pkg" repo. If "ver" is one of the -symbols ":patch", ":minor", ":major" the next patch, minor or -major version is used. If "ver" is not provided, it defaults to -":patch". -""" -Base.Pkg.tag +Look up the value of a symbol in the current task's task-local +storage. -doc""" - publish() + task_local_storage(symbol, value) -For each new package version tagged in "METADATA" not already -published, make sure that the tagged package commits have been -pushed to the repo at the registered URL for the package and if -they all have, open a pull request to "METADATA". -""" -Base.Pkg.publish +Assign a value to a symbol in the current task's task-local +storage. -doc""" - test() + task_local_storage(body, symbol, value) + +Call the function "body" with a modified task-local storage, in +which "value" is assigned to "symbol"; the previous value of +"symbol", or lack thereof, is restored afterwards. Useful for +emulating dynamic scoping. -Run the tests for all installed packages ensuring that each -package's test dependencies are installed for the duration of the -test. A package is tested by running its "test/runtests.jl" file -and test dependencies are specified in "test/REQUIRE". """ -Base.Pkg.test +task_local_storage doc""" - test(pkgs...) + tempdir() + +Obtain the path of a temporary directory (possibly shared with +other processes). -Run the tests for each package in "pkgs" ensuring that each -package's test dependencies are installed for the duration of the -test. A package is tested by running its "test/runtests.jl" file -and test dependencies are specified in "test/REQUIRE". """ -Base.Pkg.test +tempdir doc""" - @profile() + tempname() + +Generate a unique temporary file path. -"@profile " runs your expression while taking -periodic backtraces. These are appended to an internal buffer of -backtraces. """ -@profile +tempname doc""" - clear() + throw(e) + +Throw an object as an exception -Clear any existing backtraces from the internal buffer. """ -Base.Profile.clear +throw doc""" - print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + tic() + +Set a timer to be read by the next call to "toc()" or "toq()". +The macro call "@time expr" can also be used to time evaluation. -Prints profiling results to "io" (by default, "STDOUT"). If you -do not supply a "data" vector, the internal buffer of accumulated -backtraces will be used. "format" can be ":tree" or ":flat". -If "C==true", backtraces from C and Fortran code are shown. -"combine==true" merges instruction pointers that correspond to -the same line of code. "cols" controls the width of the display. """ -Base.Profile.print +tic doc""" - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + time() + +Get the system time in seconds since the epoch, with fairly high +(typically, microsecond) resolution. -Prints profiling results to "io". This variant is used to examine -results exported by a previous call to "retrieve()". Supply the -vector "data" of backtraces and a dictionary "lidict" of line -information. """ -Base.Profile.print +time doc""" - init(; n::Integer, delay::Float64) + time_ns() + +Get the time in nanoseconds. The time corresponding to 0 is +undefined, and wraps every 5.8 years. -Configure the "delay" between backtraces (measured in seconds), -and the number "n" of instruction pointers that may be stored. -Each instruction pointer corresponds to a single line of code; -backtraces generally consist of a long list of instruction -pointers. Default settings can be obtained by calling this function -with no arguments, and each can be set independently using keywords -or in the order "(n, delay)". """ -Base.Profile.init +time_ns doc""" - fetch() -> data + timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) + +Waits till "testcb" returns "true" or for "secs`" seconds, +whichever is earlier. "testcb" is polled every "pollint" +seconds. -Returns a reference to the internal buffer of backtraces. Note that -subsequent operations, like "clear()", can affect "data" unless -you first make a copy. Note that the values in "data" have -meaning only on this machine in the current session, because it -depends on the exact memory addresses used in JIT-compiling. This -function is primarily for internal use; "retrieve()" may be a -better choice for most users. """ -Base.Profile.fetch +timedwait doc""" - retrieve() -> data, lidict + toc() + +Print and return the time elapsed since the last "tic()". -"Exports" profiling results in a portable format, returning the -set of all backtraces ("data") and a dictionary that maps the -(session-specific) instruction pointers in "data" to "LineInfo" -values that store the file name, function name, and line number. -This function allows you to save profiling results for future -analysis. """ -Base.Profile.retrieve +toc doc""" - callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} + toq() + +Return, but do not print, the time elapsed since the last +"tic()". -Given a previous profiling run, determine who called a particular -function. Supplying the filename (and optionally, range of line -numbers over which the function is defined) allows you to -disambiguate an overloaded method. The returned value is a vector -containing a count of the number of calls and line information -about the caller. One can optionally supply backtrace data -obtained from "retrieve()"; otherwise, the current internal -profile buffer is used. """ -Base.Profile.callers +toq doc""" - clear_malloc_data() + touch(path::AbstractString) + +Update the last-modified timestamp on a file to the current time. -Clears any stored memory allocation data when running julia with " ---track-allocation". Execute the command(s) you want to test (to -force JIT-compilation), then call "clear_malloc_data()". Then -execute your command(s) again, quit Julia, and examine the -resulting "*.mem" files. """ -Base.Profile.clear_malloc_data +touch doc""" - sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) + trace(M) + +Matrix trace -Sort the vector "v" in place. "QuickSort" is used by default -for numeric arrays while "MergeSort" is used for other arrays. -You can specify an algorithm to use via the "alg" keyword (see -Sorting Algorithms for available algorithms). The "by" keyword -lets you provide a function that will be applied to each element -before comparison; the "lt" keyword allows providing a custom -"less than" function; use "rev=true" to reverse the sorting -order. These options are independent and can be used together in -all possible combinations: if both "by" and "lt" are specified, -the "lt" function is applied to the result of the "by" -function; "rev=true" reverses whatever ordering specified via the -"by" and "lt" keywords. """ -sort! +trace doc""" - sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + trailing_ones(x::Integer) -> Integer -Variant of "sort!" that returns a sorted copy of "v" leaving -"v" itself unmodified. -""" -sort +Number of ones trailing the binary representation of "x". -doc""" - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + julia> trailing_ones(3) + 2 -Sort a multidimensional array "A" along the given dimension. """ -sort +trailing_ones doc""" - sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) + trailing_zeros(x::Integer) -> Integer -Return a permutation vector of indices of "v" that puts it in -sorted order. Specify "alg" to choose a particular sorting -algorithm (see Sorting Algorithms). "MergeSort" is used by -default, and since it is stable, the resulting permutation will be -the lexicographically first one that puts the input array into -sorted order – i.e. indices of equal elements appear in ascending -order. If you choose a non-stable sorting algorithm such as -"QuickSort", a different permutation that puts the array into -order may be returned. The order is specified using the same -keywords as "sort!". +Number of zeros trailing the binary representation of "x". + + julia> trailing_zeros(2) + 1 -See also "sortperm!()" """ -sortperm +trailing_zeros doc""" - sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + transpose(A) -Like "sortperm", but accepts a preallocated index vector "ix". -If "initialized" is "false" (the default), ix is initialized to -contain the values "1:length(v)". +The transposition operator (".'"). -See also "sortperm()" """ -sortperm! +transpose doc""" - sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + transpose!(dest, src) + +Transpose array "src" and store the result in the preallocated +array "dest", which should have a size corresponding to +"(size(src,2),size(src,1))". No in-place transposition is +supported and unexpected results will happen if *src* and *dest* +have overlapping memory regions. -Sort the rows of matrix "A" lexicographically. """ -sortrows +transpose! doc""" - sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + trigamma(x) + +Compute the trigamma function of "x" (the logarithmic second +derivative of "gamma(x)") -Sort the columns of matrix "A" lexicographically. """ -sortcols +trigamma doc""" - issorted(v, [by=,] [lt=,] [rev=false]) + tril(M) + +Lower triangle of a matrix. + + tril(M, k) + +Returns the lower triangle of "M" starting from the "k"th +subdiagonal. -Test whether a vector is in sorted order. The "by", "lt" and -"rev" keywords modify what order is considered to be sorted just -as they do for "sort". """ -issorted +tril doc""" - searchsorted(a, x, [by=,] [lt=,] [rev=false]) + tril!(M) + +Lower triangle of a matrix, overwriting "M" in the process. + + tril!(M, k) + +Returns the lower triangle of "M" starting from the "k"th +subdiagonal, overwriting "M" in the process. -Returns the range of indices of "a" which compare as equal to -"x" according to the order specified by the "by", "lt" and -"rev" keywords, assuming that "a" is already sorted in that -order. Returns an empty range located at the insertion point if -"a" does not contain values equal to "x". """ -searchsorted +tril! doc""" - searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) + triu(M) + +Upper triangle of a matrix. + + triu(M, k) + +Returns the upper triangle of "M" starting from the "k"th +superdiagonal. -Returns the index of the first value in "a" greater than or equal -to "x", according to the specified order. Returns "length(a)+1" -if "x" is greater than all values in "a". """ -searchsortedfirst +triu doc""" - searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) + triu!(M) + +Upper triangle of a matrix, overwriting "M" in the process. + + triu!(M, k) + +Returns the upper triangle of "M" starting from the "k"th +superdiagonal, overwriting "M" in the process. -Returns the index of the last value in "a" less than or equal to -"x", according to the specified order. Returns "0" if "x" is -less than all values in "a". """ -searchsortedlast +triu! doc""" - select!(v, k, [by=,] [lt=,] [rev=false]) + trues(dims) + +Create a "BitArray" with all values set to true -Partially sort the vector "v" in place, according to the order -specified by "by", "lt" and "rev" so that the value at index -"k" (or range of adjacent values if "k" is a range) occurs at -the position where it would appear if the array were fully sorted -via a non-stable algorithm. If "k" is a single index, that value -is returned; if "k" is a range, an array of values at those -indices is returned. Note that "select!" does not fully sort the -input array. """ -select! +trues doc""" - select(v, k, [by=,] [lt=,] [rev=false]) + trunc([T], x[, digits[, base]]) -Variant of "select!" which copies "v" before partially sorting -it, thereby returning the same thing as "select!" but leaving -"v" unmodified. -""" -select +"trunc(x)" returns the nearest integral value of the same type as +"x" whose absolute value is less than or equal to "x". -doc""" - length(s) +"trunc(T, x)" converts the result to type "T", throwing an +"InexactError" if the value is not representable. + +"digits" and "base" work as for "round()". -The number of characters in string "s". """ -length +trunc doc""" - sizeof(s::AbstractString) + truncate(file, n) + +Resize the file or buffer given by the first argument to exactly +*n* bytes, filling previously unallocated space with '\0' if the +file or buffer is grown -The number of bytes in string "s". """ -sizeof +truncate doc""" - *(s, t) + tryparse(type, str[, base]) -Concatenate strings. The "*" operator is an alias to this -function. +Like "parse", but returns a "Nullable" of the requested type. +The result will be null if the string does not contain a valid +number. - julia> "Hello " * "world" - "Hello world" """ -Base.(:(*)) +tryparse doc""" - ^(s, n) + tuple(xs...) -Repeat "n" times the string "s". The "^" operator is an alias -to this function. +Construct a tuple of the given objects. - julia> "Test "^3 - "Test Test Test " """ -Base.(:(^)) +tuple doc""" - string(xs...) + typeintersect(T, S) + +Compute a type that contains the intersection of "T" and "S". +Usually this will be the smallest such type or one close to it. -Create a string from any values using the "print" function. """ -string +typeintersect doc""" - repr(x) + typejoin(T, S) + +Compute a type that contains both "T" and "S". -Create a string from any value using the "showall" function. """ -repr +typejoin doc""" - bytestring(::Ptr{UInt8}[, length]) + typemax(type) + +The highest value representable by the given (real) numeric type. -Create a string from the address of a C (0-terminated) string -encoded in ASCII or UTF-8. A copy is made; the ptr can be safely -freed. If "length" is specified, the string does not have to be -0-terminated. """ -bytestring +typemax doc""" - bytestring(s) + typemin(type) + +The lowest value representable by the given (real) numeric type. -Convert a string to a contiguous byte array representation -appropriate for passing it to C functions. The string will be -encoded as either ASCII or UTF-8. """ -bytestring +typemin doc""" - ascii(::Array{UInt8, 1}) + typeof(x) + +Get the concrete type of "x". -Create an ASCII string from a byte array. """ -ascii +typeof doc""" - ascii(s) + ucfirst(string) + +Returns "string" with the first character converted to uppercase. -Convert a string to a contiguous ASCII string (all characters must -be valid ASCII characters). """ -ascii +ucfirst doc""" - ascii(::Ptr{UInt8}[, length]) + unescape_string(s::AbstractString) -> AbstractString + +General unescaping of traditional C and Unicode escape sequences. +Reverse of "escape_string()". See also "print_unescaped()". -Create an ASCII string from the address of a C (0-terminated) -string encoded in ASCII. A copy is made; the ptr can be safely -freed. If "length" is specified, the string does not have to be -0-terminated. """ -ascii +unescape_string doc""" - utf8(::Array{UInt8, 1}) + union(s1, s2...) +∪(s1, s2) + +Construct the union of two or more sets. Maintains order with +arrays. -Create a UTF-8 string from a byte array. """ -utf8 +union doc""" - utf8(::Ptr{UInt8}[, length]) + union!(s, iterable) + +Union each element of "iterable" into set "s" in-place. -Create a UTF-8 string from the address of a C (0-terminated) string -encoded in UTF-8. A copy is made; the ptr can be safely freed. If -"length" is specified, the string does not have to be -0-terminated. """ -utf8 +union! doc""" - utf8(s) + 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". -Convert a string to a contiguous UTF-8 string (all characters must -be valid UTF-8 characters). """ -utf8 +unique doc""" - normalize_string(s, normalform::Symbol) - -Normalize the string "s" according to one of the four "normal -forms" of the Unicode standard: "normalform" can be ":NFC", -":NFD", ":NFKC", or ":NFKD". Normal forms C (canonical -composition) and D (canonical decomposition) convert different -visually identical representations of the same abstract string into -a single canonical form, with form C being more compact. Normal -forms KC and KD additionally canonicalize "compatibility -equivalents": they convert characters that are abstractly similar -but visually distinct into a single canonical choice (e.g. they -expand ligatures into the individual characters), with form KC -being more compact. + unlock(l::ReentrantLock) -Alternatively, finer control and additional transformations may be -be obtained by calling *normalize_string(s; keywords...)*, where -any number of the following boolean keywords options (which all -default to "false" except for "compose") are specified: +Releases ownership of the lock by the current task. If the lock had +been acquired before, it just decrements an internal counter and +returns immediately. -* "compose=false": do not perform canonical composition +""" +unlock -* "decompose=true": do canonical decomposition instead of - canonical composition ("compose=true" is ignored if present) +doc""" + unmark(s) -* "compat=true": compatibility equivalents are canonicalized +Remove a mark from stream "s". Returns "true" if the stream was +marked, "false" otherwise. -* "casefold=true": perform Unicode case folding, e.g. for case- - insensitive string comparison +See also "mark()", "reset()", "ismarked()" -* "newline2lf=true", "newline2ls=true", or - "newline2ps=true": convert various newline sequences (LF, CRLF, - CR, NEL) into a linefeed (LF), line-separation (LS), or - paragraph-separation (PS) character, respectively +""" +unmark -* "stripmark=true": strip diacritical marks (e.g. accents) +doc""" + unsafe_convert(T, x) -* "stripignore=true": strip Unicode's "default ignorable" - characters (e.g. the soft hyphen or the left-to-right marker) +Convert "x" to a value of type "T" -* "stripcc=true": strip control characters; horizontal tabs and - form feeds are converted to spaces; newlines are also converted - to spaces unless a newline-conversion flag was specified +In cases where "convert" would need to take a Julia object and +turn it into a "Ptr", this function should be used to define and +perform that conversion. -* "rejectna=true": throw an error if unassigned code points are - found +Be careful to ensure that a julia reference to "x" exists as long +as the result of this function will be used. Accordingly, the +argument "x" to this function should never be an expression, only +a variable name or field reference. For example, "x=a.b.c" is +acceptable, but "x=[a,b,c]" is not. -* "stable=true": enforce Unicode Versioning Stability +The "unsafe" prefix on this function indicates that using the +result of this function after the "x" argument to this function +is no longer accessible to the program may cause undefined +behavior, including program corruption or segfaults, at any later +time. -For example, NFKC corresponds to the options "compose=true, -compat=true, stable=true". """ -normalize_string +unsafe_convert doc""" - graphemes(s) -> iterator over substrings of s + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) -Returns an iterator over substrings of "s" that correspond to the -extended graphemes in the string, as defined by Unicode UAX #29. -(Roughly, these are what users would perceive as single characters, -even though they may contain more than one codepoint; for example a -letter combined with an accent mark is a single grapheme.) -""" -graphemes +Copy "N" elements from a source pointer to a destination, with no +checking. The size of an element is determined by the type of the +pointers. -doc""" - isvalid(value) -> Bool +The "unsafe" prefix on this function indicates that no validation +is performed on the pointers "dest" and "src" to ensure that +they are valid. Incorrect usage may corrupt or segfault your +program, in the same manner as C. -Returns true if the given value is valid for its type, which -currently can be one of "Char", "ASCIIString", "UTF8String", -"UTF16String", or "UTF32String" -""" -isvalid + unsafe_copy!(dest::Array, do, src::Array, so, N) -doc""" - isvalid(T, value) -> Bool +Copy "N" elements from a source array to a destination, starting +at offset "so" in the source and "do" in the destination +(1-indexed). + +The "unsafe" prefix on this function indicates that no validation +is performed to ensure that N is inbounds on either array. +Incorrect usage may corrupt or segfault your program, in the same +manner as C. -Returns true if the given value is valid for that type. Types -currently can be "Char", "ASCIIString", "UTF8String", -"UTF16String", or "UTF32String" Values for "Char" can be of -type "Char" or "UInt32" Values for "ASCIIString" and -"UTF8String" can be of that type, or "Vector{UInt8}" Values for -"UTF16String" can be "UTF16String" or "Vector{UInt16}" Values -for "UTF32String" can be "UTF32String", "Vector{Char}" or -"Vector{UInt32}" """ -isvalid +unsafe_copy! doc""" - is_assigned_char(c) -> Bool + unsafe_load(p::Ptr{T}, i::Integer) -Returns true if the given char or integer is an assigned Unicode -code point. -""" -is_assigned_char +Load a value of type "T" from the address of the ith element +(1-indexed) starting at "p". This is equivalent to the C +expression "p[i-1]". -doc""" - ismatch(r::Regex, s::AbstractString) -> Bool +The "unsafe" prefix on this function indicates that no validation +is performed on the pointer "p" to ensure that it is valid. +Incorrect usage may segfault your program or return garbage +answers, in the same manner as C. -Test whether a string contains a match of the given regular -expression. """ -ismatch +unsafe_load doc""" - match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) + unsafe_pointer_to_objref(p::Ptr) + +Convert a "Ptr" to an object reference. Assumes the pointer +refers to a valid heap-allocated Julia object. If this is not the +case, undefined behavior results, hence this function is considered +"unsafe" and should be used with care. -Search for the first match of the regular expression "r" in "s" -and return a RegexMatch object containing the match, or nothing if -the match failed. The matching substring can be retrieved by -accessing "m.match" and the captured sequences can be retrieved -by accessing "m.captures" The optional "idx" argument specifies -an index at which to start the search. """ -match +unsafe_pointer_to_objref doc""" - eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) + unsafe_store!(p::Ptr{T}, x, i::Integer) + +Store a value of type "T" to the address of the ith element +(1-indexed) starting at "p". This is equivalent to the C +expression "p[i-1] = x". + +The "unsafe" prefix on this function indicates that no validation +is performed on the pointer "p" to ensure that it is valid. +Incorrect usage may corrupt or segfault your program, in the same +manner as C. -Search for all matches of a the regular expression "r" in "s" -and return a iterator over the matches. If overlap is true, the -matching sequences are allowed to overlap indices in the original -string, otherwise they must be from distinct character ranges. """ -eachmatch +unsafe_store! doc""" - matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + unsafe_trunc(T, x) + +"unsafe_trunc(T, x)" returns the nearest integral value of type +"T" whose absolute value is less than or equal to "x". If the +value is not representable by "T", an arbitrary value will be +returned. -Return a vector of the matching substrings from eachmatch. """ -matchall +unsafe_trunc doc""" - lpad(string, n, p) + 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 -Make a string at least "n" columns wide when printed, by padding -on the left with copies of "p". """ -lpad +unshift! doc""" - rpad(string, n, p) + unsigned(x) -> Unsigned + +Convert a number to an unsigned integer. If the argument is signed, +it is reinterpreted as unsigned without checking for negative +values. -Make a string at least "n" columns wide when printed, by padding -on the right with copies of "p". """ -rpad +unsigned doc""" - search(string, chars[, start]) + uperm(file) -Search for the first occurrence of the given characters within the -given string. The second argument may be a single character, a -vector or a set of characters, a string, or a regular expression -(though regular expressions are only allowed on contiguous strings, -such as ASCII or UTF-8 strings). The third argument optionally -specifies a starting index. The return value is a range of indexes -where the matching sequence is found, such that "s[search(s,x)] == -x": +Gets the permissions of the owner of the file as a bitfield of -"search(string, "substring")" = "start:end" such that -"string[start:end] == "substring"", or "0:-1" if unmatched. ++------+-----------------------+ +| 01 | Execute Permission | ++------+-----------------------+ +| 02 | Write Permission | ++------+-----------------------+ +| 04 | Read Permission | ++------+-----------------------+ + +For allowed arguments, see "stat". -"search(string, 'c')" = "index" such that -"string[index] == 'c'", or "0" if unmatched. """ -search +uperm doc""" - rsearch(string, chars[, start]) + uppercase(string) + +Returns "string" with all characters converted to uppercase. -Similar to "search", but returning the last occurrence of the -given characters within the given string, searching in reverse from -"start". """ -rsearch +uppercase doc""" - searchindex(string, substring[, start]) + utf16(s) -Similar to "search", but return only the start index at which the -substring is found, or 0 if it is not. -""" -searchindex +Create a UTF-16 string from a byte array, array of "UInt16", or +any other string type. (Data must be valid UTF-16. Conversions of +byte arrays check for a byte-order marker in the first two bytes, +and do not include it in the resulting string.) -doc""" - rsearchindex(string, substring[, start]) +Note that the resulting "UTF16String" data is terminated by the +NUL codepoint (16-bit zero), which is not treated as a character in +the string (so that it is mostly invisible in Julia); this allows +the string to be passed directly to external functions requiring +NUL-terminated data. This NUL is appended automatically by the +*utf16(s)* conversion function. If you have a "UInt16" array +"A" that is already NUL-terminated valid UTF-16 data, then you +can instead use *UTF16String(A)`* to construct the string without +making a copy of the data and treating the NUL as a terminator +rather than as part of the string. -Similar to "rsearch", but return only the start index at which -the substring is found, or 0 if it is not. -""" -rsearchindex + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) -doc""" - contains(haystack, needle) +Create a string from the address of a NUL-terminated UTF-16 string. +A copy is made; the pointer can be safely freed. If "length" is +specified, the string does not have to be NUL-terminated. -Determine whether the second argument is a substring of the first. """ -contains +utf16 doc""" - replace(string, pat, r[, n]) + utf32(s) -Search for the given pattern "pat", and replace each occurrence -with "r". If "n" is provided, replace at most "n" -occurrences. As with search, the second argument may be a single -character, a vector or a set of characters, a string, or a regular -expression. If "r" is a function, each occurrence is replaced -with "r(s)" where "s" is the matched substring. -""" -replace +Create a UTF-32 string from a byte array, array of "Char" or +"UInt32", or any other string type. (Conversions of byte arrays +check for a byte-order marker in the first four bytes, and do not +include it in the resulting string.) -doc""" - split(string, [chars]; limit=0, keep=true) +Note that the resulting "UTF32String" data is terminated by the +NUL codepoint (32-bit zero), which is not treated as a character in +the string (so that it is mostly invisible in Julia); this allows +the string to be passed directly to external functions requiring +NUL-terminated data. This NUL is appended automatically by the +*utf32(s)* conversion function. If you have a "Char" or +"UInt32" array "A" that is already NUL-terminated UTF-32 data, +then you can instead use *UTF32String(A)`* to construct the string +without making a copy of the data and treating the NUL as a +terminator rather than as part of the string. -Return an array of substrings by splitting the given string on -occurrences of the given character delimiters, which may be -specified in any of the formats allowed by "search"'s second -argument (i.e. a single character, collection of characters, -string, or regular expression). If "chars" is omitted, it -defaults to the set of all space characters, and "keep" is taken -to be false. The two keyword arguments are optional: they are are a -maximum size for the result and a flag determining whether empty -fields should be kept in the result. -""" -split + utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) -doc""" - rsplit(string, [chars]; limit=0, keep=true) +Create a string from the address of a NUL-terminated UTF-32 string. +A copy is made; the pointer can be safely freed. If "length" is +specified, the string does not have to be NUL-terminated. -Similar to "split", but starting from the end of the string. """ -rsplit +utf32 doc""" - strip(string[, chars]) + utf8(::Array{UInt8, 1}) + +Create a UTF-8 string from a byte array. + + utf8(::Ptr{UInt8}[, length]) + +Create a UTF-8 string from the address of a C (0-terminated) string +encoded in UTF-8. A copy is made; the ptr can be safely freed. If +"length" is specified, the string does not have to be +0-terminated. + + utf8(s) + +Convert a string to a contiguous UTF-8 string (all characters must +be valid UTF-8 characters). -Return "string" with any leading and trailing whitespace removed. -If "chars" (a character, or vector or set of characters) is -provided, instead remove characters contained in it. """ -strip +utf8 doc""" - lstrip(string[, chars]) + values(collection) + +Return an iterator over all values in a collection. +"collect(values(d))" returns an array of values. -Return "string" with any leading whitespace removed. If "chars" -(a character, or vector or set of characters) is provided, instead -remove characters contained in it. """ -lstrip +values doc""" - rstrip(string[, chars]) + var(v[, region]) + +Compute the sample variance of a vector or array "v", optionally +along dimensions in "region". The algorithm will return an +estimator of the generative distribution's variance under the +assumption that each entry of "v" is an IID drawn from that +generative distribution. This computation is equivalent to +calculating "sum((v - mean(v)).^2) / (length(v) - 1)". Note: +Julia does not ignore "NaN" values in the computation. For +applications requiring the handling of missing data, the +"DataArray" package is recommended. -Return "string" with any trailing whitespace removed. If -"chars" (a character, or vector or set of characters) is -provided, instead remove characters contained in it. """ -rstrip +var doc""" - startswith(string, prefix | chars) + varm(v, m) + +Compute the sample variance of a vector "v" with known mean +"m". Note: Julia does not ignore "NaN" values in the +computation. -Returns "true" if "string" starts with "prefix". If the -second argument is a vector or set of characters, tests whether the -first character of "string" belongs to that set. """ -startswith +varm doc""" - endswith(string, suffix | chars) + vcat(A...) + +Concatenate along dimension 1 -Returns "true" if "string" ends with "suffix". If the second -argument is a vector or set of characters, tests whether the last -character of "string" belongs to that set. """ -endswith +vcat doc""" - uppercase(string) + vec(Array) -> Vector + +Vectorize an array using column-major convention. -Returns "string" with all characters converted to uppercase. """ -uppercase +vec doc""" - lowercase(string) + vecdot(x, y) + +For any iterable containers "x" and "y" (including arrays of +any dimension) of numbers (or any element type for which "dot" is +defined), compute the Euclidean dot product (the sum of +"dot(x[i],y[i])") as if they were vectors. -Returns "string" with all characters converted to lowercase. """ -lowercase +vecdot doc""" - ucfirst(string) + vecnorm(A[, p]) -Returns "string" with the first character converted to uppercase. -""" -ucfirst +For any iterable container "A" (including arrays of any +dimension) of numbers (or any element type for which "norm" is +defined), compute the "p"-norm (defaulting to "p=2") as if +"A" were a vector of the corresponding length. -doc""" - lcfirst(string) +For example, if "A" is a matrix and "p=2", then this is +equivalent to the Frobenius norm. -Returns "string" with the first character converted to lowercase. """ -lcfirst +vecnorm doc""" - join(strings, delim[, last]) + versioninfo([verbose::Bool]) -Join an array of "strings" into a single string, inserting the -given delimiter between adjacent strings. If "last" is given, it -will be used instead of "delim" between the last two strings. For -example, "join(["apples", "bananas", "pineapples"], ", ", -" and ") == "apples, bananas and pineapples"". +Print information about the version of Julia in use. If the +"verbose" argument is true, detailed system information is shown +as well. -"strings" can be any iterable over elements "x" which are -convertible to strings via "print(io::IOBuffer, x)". """ -join +versioninfo doc""" - chop(string) + wait([x]) -Remove the last character from a string -""" -chop +Block the current task until some event occurs, depending on the +type of the argument: -doc""" - chomp(string) +* "RemoteRef": Wait for a value to become available for the + specified remote reference. -Remove a trailing newline from a string -""" -chomp +* "Condition": Wait for "notify" on a condition. -doc""" - ind2chr(string, i) +* "Process": Wait for a process or process chain to exit. The + "exitcode" field of a process can be used to determine success + or failure. -Convert a byte index to a character index -""" -ind2chr +* "Task": Wait for a "Task" to finish, returning its result + value. If the task fails with an exception, the exception is + propagated (re-thrown in the task that called "wait"). -doc""" - chr2ind(string, i) +* "RawFD": Wait for changes on a file descriptor (see *poll_fd* + for keyword arguments and return code) -Convert a character index to a byte index -""" -chr2ind +If no argument is passed, the task blocks for an undefined period. +If the task's state is set to ":waiting", it can only be +restarted by an explicit call to "schedule" or "yieldto". If +the task's state is ":runnable", it might be restarted +unpredictably. -doc""" - isvalid(str, i) +Often "wait" is called within a "while" loop to ensure a +waited-for condition is met before proceeding. -Tells whether index "i" is valid for the given string """ -isvalid +wait doc""" - nextind(str, i) + warn(msg) + +Display a warning. -Get the next valid string index after "i". Returns a value -greater than "endof(str)" at or after the end of the string. """ -nextind +warn doc""" - prevind(str, i) + watch_file(cb=false, s; poll=false) + +Watch file or directory "s" and run callback "cb" when "s" is +modified. The "poll" parameter specifies whether to use file +system event monitoring or polling. The callback function "cb" +should accept 3 arguments: "(filename, events, status)" where +"filename" is the name of file that was modified, "events" is +an object with boolean fields "changed" and "renamed" when +using file system event monitoring, or "readable" and +"writable" when using polling, and "status" is always 0. Pass +"false" for "cb" to not use a callback function. -Get the previous valid string index before "i". Returns a value -less than "1" at the beginning of the string. """ -prevind +watch_file doc""" - randstring([rng], len=8) + which(f, types) -Create a random ASCII string of length "len", consisting of -upper- and lower-case letters and the digits 0-9. The optional -"rng" argument specifies a random number generator, see *Random -Numbers*. -""" -randstring +Returns the method of "f" (a "Method" object) that would be +called for arguments of the given types. -doc""" - charwidth(c) +If "types" is an abstract type, then the method that would be +called by "invoke" is returned. -Gives the number of columns needed to print a character. -""" -charwidth + which(symbol) -doc""" - strwidth(s) +Return the module in which the binding for the variable referenced +by "symbol" was created. -Gives the number of columns needed to print a string. """ -strwidth +which doc""" - isalnum(c::Union{Char, AbstractString}) -> Bool + whos([Module,] [pattern::Regex]) + +Print information about exported global variables in a module, +optionally restricted to those matching "pattern". -Tests whether a character is alphanumeric, or whether this is true -for all elements of a string. A character is classified as -alphabetic if it belongs to the Unicode general category Letter or -Number, i.e. a character whose category code begins with 'L' or -'N'. """ -isalnum +whos doc""" - isalpha(c::Union{Char, AbstractString}) -> Bool + widemul(x, y) + +Multiply "x" and "y", giving the result as a larger type. -Tests whether a character is alphabetic, or whether this is true -for all elements of a string. A character is classified as -alphabetic if it belongs to the Unicode general category Letter, -i.e. a character whose category code begins with 'L'. """ -isalpha +widemul doc""" - isascii(c::Union{Char, AbstractString}) -> Bool + widen(type | x) -Tests whether a character belongs to the ASCII character set, or -whether this is true for all elements of a string. -""" -isascii +If the argument is a type, return a "larger" type (for numeric +types, this will be a type with at least as much range and +precision as the argument, and usually more). Otherwise the +argument "x" is converted to "widen(typeof(x))". -doc""" - iscntrl(c::Union{Char, AbstractString}) -> Bool + julia> widen(Int32) + Int64 + + julia> widen(1.5f0) + 1.5 -Tests whether a character is a control character, or whether this -is true for all elements of a string. Control characters are the -non-printing characters of the Latin-1 subset of Unicode. """ -iscntrl +widen doc""" - isdigit(c::Union{Char, AbstractString}) -> Bool + with_bigfloat_precision(f::Function, precision::Integer) + +Change the BigFloat arithmetic precision (in bits) for the duration +of "f". It is logically equivalent to: + + old = get_bigfloat_precision() + set_bigfloat_precision(precision) + f() + set_bigfloat_precision(old) -Tests whether a character is a numeric digit (0-9), or whether this -is true for all elements of a string. """ -isdigit +with_bigfloat_precision doc""" - isgraph(c::Union{Char, AbstractString}) -> Bool + with_rounding(f::Function, T, mode) + +Change the rounding mode of floating point type "T" for the +duration of "f". It is logically equivalent to: + + old = get_rounding(T) + set_rounding(T, mode) + f() + set_rounding(T, old) + +See "get_rounding" for available rounding modes. -Tests whether a character is printable, and not a space, or whether -this is true for all elements of a string. Any character that -would cause a printer to use ink should be classified with -isgraph(c)==true. """ -isgraph +with_rounding doc""" - islower(c::Union{Char, AbstractString}) -> Bool + withenv(f::Function, kv::Pair...) + +Execute "f()" in an environment that is temporarily modified (not +replaced as in "setenv") by zero or more ""var"=>val" +arguments "kv". "withenv" is generally used via the +"withenv(kv...) do ... end" syntax. A value of "nothing" can +be used to temporarily unset an environment variable (if it is +set). When "withenv" returns, the original environment has been +restored. -Tests whether a character is a lowercase letter, or whether this is -true for all elements of a string. A character is classified as -lowercase if it belongs to Unicode category Ll, Letter: Lowercase. """ -islower +withenv doc""" - isnumber(c::Union{Char, AbstractString}) -> Bool + workers() + +Returns a list of all worker process identifiers. -Tests whether a character is numeric, or whether this is true for -all elements of a string. A character is classified as numeric if -it belongs to the Unicode general category Number, i.e. a character -whose category code begins with 'N'. """ -isnumber +workers doc""" - isprint(c::Union{Char, AbstractString}) -> Bool + workspace() -Tests whether a character is printable, including spaces, but not a -control character. For strings, tests whether this is true for all -elements of the string. -""" -isprint +Replace the top-level module ("Main") with a new one, providing a +clean workspace. The previous "Main" module is made available as +"LastMain". A previously-loaded package can be accessed using a +statement such as "using LastMain.Package". -doc""" - ispunct(c::Union{Char, AbstractString}) -> Bool +This function should only be used interactively. -Tests whether a character belongs to the Unicode general category -Punctuation, i.e. a character whose category code begins with 'P'. -For strings, tests whether this is true for all elements of the -string. """ -ispunct +workspace doc""" - isspace(c::Union{Char, AbstractString}) -> Bool + write(stream, x) + +Write the canonical binary representation of a value to the given +stream. -Tests whether a character is any whitespace character. Includes -ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', -Latin-1 character U+0085, and characters in Unicode category Zs. -For strings, tests whether this is true for all elements of the -string. """ -isspace +write doc""" - isupper(c::Union{Char, AbstractString}) -> Bool + writecsv(filename, A) + +Equivalent to "writedlm" with "delim" set to comma. -Tests whether a character is an uppercase letter, or whether this -is true for all elements of a string. A character is classified -as uppercase if it belongs to Unicode category Lu, Letter: -Uppercase, or Lt, Letter: Titlecase. """ -isupper +writecsv doc""" - isxdigit(c::Union{Char, AbstractString}) -> Bool + writedlm(f, A, delim='\t') -Tests whether a character is a valid hexadecimal digit, or whether -this is true for all elements of a string. -""" -isxdigit +Write "A" (a vector, matrix or an iterable collection of iterable +rows) as text to "f" (either a filename string or an "IO" +stream) using the given delimeter "delim" (which defaults to tab, +but can be any printable Julia object, typically a "Char" or +"AbstractString"). -doc""" - symbol(x...) -> Symbol +For example, two vectors "x" and "y" of the same length can be +written as two columns of tab-delimited text to "f" by either +"writedlm(f, [x y])" or by "writedlm(f, zip(x, y))". -Create a "Symbol" by concatenating the string representations of -the arguments together. """ -symbol +writedlm doc""" - escape_string(str::AbstractString) -> AbstractString + writemime(stream, mime, x) + +The "display" functions ultimately call "writemime" in order to +write an object "x" as a given "mime" type to a given I/O +"stream" (usually a memory buffer), if possible. In order to +provide a rich multimedia representation of a user-defined type +"T", it is only necessary to define a new "writemime" method +for "T", via: "writemime(stream, ::MIME"mime", x::T) = ...", +where "mime" is a MIME-type string and the function body calls +"write" (or similar) to write that representation of "x" to +"stream". (Note that the "MIME\""" notation only supports +literal strings; to construct "MIME" types in a more flexible +manner use "MIME{symbol("")}".) + +For example, if you define a "MyImage" type and know how to write +it to a PNG file, you could define a function "writemime(stream, +::MIME"image/png", x::MyImage) = ...`" to allow your images to +be displayed on any PNG-capable "Display" (such as IJulia). As +usual, be sure to "import Base.writemime" in order to add new +methods to the built-in Julia function "writemime". + +Technically, the "MIME"mime"" macro defines a singleton type +for the given "mime" string, which allows us to exploit Julia's +dispatch mechanisms in determining how to display objects of any +given type. -General escaping of traditional C and Unicode escape sequences. See -"print_escaped()" for more general escaping. """ -escape_string +writemime doc""" - unescape_string(s::AbstractString) -> AbstractString + wstring(s) + +This is a synonym for either "utf32(s)" or "utf16(s)", +depending on whether "Cwchar_t" is 32 or 16 bits, respectively. +The synonym "WString" for "UTF32String" or "UTF16String" is +also provided. -General unescaping of traditional C and Unicode escape sequences. -Reverse of "escape_string()". See also "print_unescaped()". """ -unescape_string +wstring doc""" - utf16(s) + xcorr(u, v) -Create a UTF-16 string from a byte array, array of "UInt16", or -any other string type. (Data must be valid UTF-16. Conversions of -byte arrays check for a byte-order marker in the first two bytes, -and do not include it in the resulting string.) +Compute the cross-correlation of two vectors. -Note that the resulting "UTF16String" data is terminated by the -NUL codepoint (16-bit zero), which is not treated as a character in -the string (so that it is mostly invisible in Julia); this allows -the string to be passed directly to external functions requiring -NUL-terminated data. This NUL is appended automatically by the -*utf16(s)* conversion function. If you have a "UInt16" array -"A" that is already NUL-terminated valid UTF-16 data, then you -can instead use *UTF16String(A)`* to construct the string without -making a copy of the data and treating the NUL as a terminator -rather than as part of the string. """ -utf16 +xcorr doc""" - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) + xdump(x) + +Show all structure of a value, including all fields of objects. -Create a string from the address of a NUL-terminated UTF-16 string. -A copy is made; the pointer can be safely freed. If "length" is -specified, the string does not have to be NUL-terminated. """ -utf16 +xdump doc""" - utf32(s) + yield() -Create a UTF-32 string from a byte array, array of "Char" or -"UInt32", or any other string type. (Conversions of byte arrays -check for a byte-order marker in the first four bytes, and do not -include it in the resulting string.) +Switch to the scheduler to allow another scheduled task to run. A +task that calls this function is still runnable, and will be +restarted immediately if there are no other runnable tasks. -Note that the resulting "UTF32String" data is terminated by the -NUL codepoint (32-bit zero), which is not treated as a character in -the string (so that it is mostly invisible in Julia); this allows -the string to be passed directly to external functions requiring -NUL-terminated data. This NUL is appended automatically by the -*utf32(s)* conversion function. If you have a "Char" or -"UInt32" array "A" that is already NUL-terminated UTF-32 data, -then you can instead use *UTF32String(A)`* to construct the string -without making a copy of the data and treating the NUL as a -terminator rather than as part of the string. """ -utf32 +yield doc""" - utf32(::Union{Ptr{Char}, Ptr{UInt32}, Ptr{Int32}}[, length]) + yieldto(task, arg = nothing) + +Switch to the given task. The first time a task is switched to, the +task's function is called with no arguments. On subsequent +switches, "arg" is returned from the task's last call to +"yieldto". This is a low-level call that only switches tasks, not +considering states or scheduling in any way. Its use is +discouraged. -Create a string from the address of a NUL-terminated UTF-32 string. -A copy is made; the pointer can be safely freed. If "length" is -specified, the string does not have to be NUL-terminated. """ -utf32 +yieldto doc""" - wstring(s) + zero(x) + +Get the additive identity element for the type of x (x can also +specify the type itself). -This is a synonym for either "utf32(s)" or "utf16(s)", -depending on whether "Cwchar_t" is 32 or 16 bits, respectively. -The synonym "WString" for "UTF32String" or "UTF16String" is -also provided. """ -wstring +zero doc""" - runtests([tests=["all"][, numcores=iceil(CPU_CORES/2)]]) + 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. -Run the Julia unit tests listed in "tests", which can be either a -string or an array of strings, using "numcores" processors. (not -exported) """ -runtests +zeros doc""" - @test(ex) + zeta(s) + +Riemann zeta function \zeta(s). + + zeta(s, z) + +Hurwitz zeta function \zeta(s, z). (This is equivalent to the +Riemann zeta function \zeta(s) for the case of "z=1".) -Test the expression "ex" and calls the current handler to handle -the result. """ -Base.Test.@test +zeta doc""" - @test_throws(extype, ex) + zip(iters...) + +For a set of iterable objects, returns an iterable of tuples, where +the "i"th tuple contains the "i"th component of each input +iterable. + +Note that "zip()" is its own inverse: +"collect(zip(zip(a...)...)) == collect(a)". -Test that the expression "ex" throws an exception of type -"extype" and calls the current handler to handle the result. """ -Base.Test.@test_throws +zip doc""" - @test_approx_eq(a, b) + ~(x) + +Bitwise not -Test two floating point numbers "a" and "b" for equality taking -in account small numerical errors. """ -Base.Test.@test_approx_eq +~ doc""" - @test_approx_eq_eps(a, b, tol) + γ +eulergamma + +Euler's constant -Test two floating point numbers "a" and "b" for equality taking -in account a margin of tolerance given by "tol". """ -Base.Test.@test_approx_eq_eps +γ doc""" - with_handler(f, handler) + φ +golden -Run the function "f" using the "handler" as the handler. -""" -Base.Test.with_handler +The golden ratio +""" +φ diff --git a/doc/helpdb.jl b/doc/helpdb.jl index 369eaac64cb26..92aa9335f2754 100644 --- a/doc/helpdb.jl +++ b/doc/helpdb.jl @@ -31,7 +31,17 @@ Any[ "), -("Base","length","length(s) +("Base","length","length(A) -> Integer + + Returns the number of elements in A + + length(collection) -> Integer + + For ordered, indexable collections, the maximum index \"i\" for + which \"getindex(collection, i)\" is valid. For unordered + collections, the number of elements. + + length(s) The number of characters in string \"s\". @@ -126,14 +136,30 @@ Any[ "), -("Base","ind2sub","ind2sub(a, index) -> subscripts +("Base","ind2sub","ind2sub(dims, index) -> subscripts + + Returns a tuple of subscripts into an array with dimensions + \"dims\", corresponding to the linear index \"index\" + + **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 index \"index\" "), -("Base","ind2sub","ind2sub(a, index) -> subscripts +("Base","ind2sub","ind2sub(dims, index) -> subscripts + + Returns a tuple of subscripts into an array with dimensions + \"dims\", corresponding to the linear index \"index\" + + **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 index \"index\" @@ -156,7 +182,19 @@ Any[ "), -("Base","getindex","getindex(collection, key...) +("Base","getindex","getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called + with the syntax \"Type[]\". Element values can be specified using + \"Type[a,b,c,...]\". + + getindex(A, inds...) + + Returns a subset of array \"A\" as specified by \"inds\", where + each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See + the manual section on *array indexing* for details. + + 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 @@ -171,28 +209,48 @@ Any[ "), -("Base","zeros","zeros(A) +("Base","zeros","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. "), -("Base","zeros","zeros(A) +("Base","zeros","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. "), -("Base","ones","ones(A) +("Base","ones","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. "), -("Base","ones","ones(A) +("Base","ones","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. @@ -262,21 +320,45 @@ Any[ "), -("Base","eye","eye(A) +("Base","eye","eye(n) + + n-by-n identity matrix + + eye(m, n) + + m-by-n identity matrix + + eye(A) Constructs an identity matrix of the same dimensions and type as \"A\". "), -("Base","eye","eye(A) +("Base","eye","eye(n) + + n-by-n identity matrix + + eye(m, n) + + m-by-n identity matrix + + eye(A) Constructs an identity matrix of the same dimensions and type as \"A\". "), -("Base","eye","eye(A) +("Base","eye","eye(n) + + n-by-n identity matrix + + eye(m, n) + + m-by-n identity matrix + + eye(A) Constructs an identity matrix of the same dimensions and type as \"A\". @@ -336,7 +418,19 @@ Any[ "), -("Base","getindex","getindex(collection, key...) +("Base","getindex","getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called + with the syntax \"Type[]\". Element values can be specified using + \"Type[a,b,c,...]\". + + getindex(A, inds...) + + Returns a subset of array \"A\" as specified by \"inds\", where + each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See + the manual section on *array indexing* for details. + + 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 @@ -383,7 +477,12 @@ Any[ "), -("Base","setindex!","setindex!(collection, value, key...) +("Base","setindex!","setindex!(A, X, inds...) + + Store values from array \"X\" within some subset of \"A\" as + specified by \"inds\". + + 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 @@ -463,14 +562,26 @@ Any[ "), -("Base","find","find(f, A) +("Base","find","find(A) + + Return a vector of the linear indexes of the non-zeros in \"A\" + (determined by \"A[i]!=0\"). A common use of this is to convert a + boolean array to an array of indexes of the \"true\" elements. + + find(f, A) Return a vector of the linear indexes of \"A\" where \"f\" returns true. "), -("Base","find","find(f, A) +("Base","find","find(A) + + Return a vector of the linear indexes of the non-zeros in \"A\" + (determined by \"A[i]!=0\"). A common use of this is to convert a + boolean array to an array of indexes of the \"true\" elements. + + find(f, A) Return a vector of the linear indexes of \"A\" where \"f\" returns true. @@ -492,84 +603,198 @@ Any[ "), -("Base","findfirst","findfirst(predicate, A) +("Base","findfirst","findfirst(A) + + Return the index of the first non-zero value in \"A\" (determined + by \"A[i]!=0\"). + + findfirst(A, v) + + Return the index of the first element equal to \"v\" in \"A\". + + findfirst(predicate, A) Return the index of the first element of \"A\" for which \"predicate\" returns true. "), -("Base","findfirst","findfirst(predicate, A) +("Base","findfirst","findfirst(A) + + Return the index of the first non-zero value in \"A\" (determined + by \"A[i]!=0\"). + + findfirst(A, v) + + Return the index of the first element equal to \"v\" in \"A\". + + findfirst(predicate, A) Return the index of the first element of \"A\" for which \"predicate\" returns true. "), -("Base","findfirst","findfirst(predicate, A) +("Base","findfirst","findfirst(A) + + Return the index of the first non-zero value in \"A\" (determined + by \"A[i]!=0\"). + + findfirst(A, v) + + Return the index of the first element equal to \"v\" in \"A\". + + findfirst(predicate, A) Return the index of the first element of \"A\" for which \"predicate\" returns true. "), -("Base","findlast","findlast(predicate, A) +("Base","findlast","findlast(A) + + Return the index of the last non-zero value in \"A\" (determined by + \"A[i]!=0\"). + + findlast(A, v) + + Return the index of the last element equal to \"v\" in \"A\". + + findlast(predicate, A) Return the index of the last element of \"A\" for which \"predicate\" returns true. "), -("Base","findlast","findlast(predicate, A) +("Base","findlast","findlast(A) + + Return the index of the last non-zero value in \"A\" (determined by + \"A[i]!=0\"). + + findlast(A, v) + + Return the index of the last element equal to \"v\" in \"A\". + + findlast(predicate, A) Return the index of the last element of \"A\" for which \"predicate\" returns true. "), -("Base","findlast","findlast(predicate, A) +("Base","findlast","findlast(A) + + Return the index of the last non-zero value in \"A\" (determined by + \"A[i]!=0\"). + + findlast(A, v) + + Return the index of the last element equal to \"v\" in \"A\". + + findlast(predicate, A) Return the index of the last element of \"A\" for which \"predicate\" returns true. "), -("Base","findnext","findnext(A, v, i) +("Base","findnext","findnext(A, i) + + Find the next index >= \"i\" of a non-zero element of \"A\", or + \"0\" if not found. + + findnext(predicate, A, i) + + Find the next index >= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + + findnext(A, v, i) Find the next index >= \"i\" of an element of \"A\" equal to \"v\" (using \"==\"), or \"0\" if not found. "), -("Base","findnext","findnext(A, v, i) +("Base","findnext","findnext(A, i) + + Find the next index >= \"i\" of a non-zero element of \"A\", or + \"0\" if not found. + + findnext(predicate, A, i) + + Find the next index >= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + + findnext(A, v, i) Find the next index >= \"i\" of an element of \"A\" equal to \"v\" (using \"==\"), or \"0\" if not found. "), -("Base","findnext","findnext(A, v, i) +("Base","findnext","findnext(A, i) + + Find the next index >= \"i\" of a non-zero element of \"A\", or + \"0\" if not found. + + findnext(predicate, A, i) + + Find the next index >= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + + findnext(A, v, i) Find the next index >= \"i\" of an element of \"A\" equal to \"v\" (using \"==\"), or \"0\" if not found. "), -("Base","findprev","findprev(A, v, i) +("Base","findprev","findprev(A, i) + + Find the previous index <= \"i\" of a non-zero element of \"A\", or + 0 if not found. + + findprev(predicate, A, i) + + Find the previous index <= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + + findprev(A, v, i) Find the previous index <= \"i\" of an element of \"A\" equal to \"v\" (using \"==\"), or \"0\" if not found. "), -("Base","findprev","findprev(A, v, i) +("Base","findprev","findprev(A, i) + + Find the previous index <= \"i\" of a non-zero element of \"A\", or + 0 if not found. + + findprev(predicate, A, i) + + Find the previous index <= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + + findprev(A, v, i) Find the previous index <= \"i\" of an element of \"A\" equal to \"v\" (using \"==\"), or \"0\" if not found. "), -("Base","findprev","findprev(A, v, i) +("Base","findprev","findprev(A, i) + + Find the previous index <= \"i\" of a non-zero element of \"A\", or + 0 if not found. + + findprev(predicate, A, i) + + Find the previous index <= \"i\" of an element of \"A\" for which + \"predicate\" returns true, or \"0\" if not found. + + findprev(A, v, i) Find the previous index <= \"i\" of an element of \"A\" equal to \"v\" (using \"==\"), or \"0\" if not found. @@ -715,21 +940,33 @@ Any[ "), -("Base","rot180","rot180(A, k) +("Base","rot180","rot180(A) + + Rotate matrix \"A\" 180 degrees. + + rot180(A, k) Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. If \"k\" is even, this is equivalent to a \"copy\". "), -("Base","rot180","rot180(A, k) +("Base","rot180","rot180(A) + + Rotate matrix \"A\" 180 degrees. + + rot180(A, k) Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. If \"k\" is even, this is equivalent to a \"copy\". "), -("Base","rotl90","rotl90(A, k) +("Base","rotl90","rotl90(A) + + Rotate matrix \"A\" left 90 degrees. + + rotl90(A, k) Rotate matrix \"A\" left 90 degrees an integer \"k\" number of times. If \"k\" is zero or a multiple of four, this is equivalent @@ -737,7 +974,11 @@ Any[ "), -("Base","rotl90","rotl90(A, k) +("Base","rotl90","rotl90(A) + + Rotate matrix \"A\" left 90 degrees. + + rotl90(A, k) Rotate matrix \"A\" left 90 degrees an integer \"k\" number of times. If \"k\" is zero or a multiple of four, this is equivalent @@ -745,7 +986,11 @@ Any[ "), -("Base","rotr90","rotr90(A, k) +("Base","rotr90","rotr90(A) + + Rotate matrix \"A\" right 90 degrees. + + rotr90(A, k) Rotate matrix \"A\" right 90 degrees an integer \"k\" number of times. If \"k\" is zero or a multiple of four, this is equivalent @@ -753,7 +998,11 @@ Any[ "), -("Base","rotr90","rotr90(A, k) +("Base","rotr90","rotr90(A) + + Rotate matrix \"A\" right 90 degrees. + + rotr90(A, k) Rotate matrix \"A\" right 90 degrees an integer \"k\" number of times. If \"k\" is zero or a multiple of four, this is equivalent @@ -814,14 +1063,22 @@ Any[ "), -("Base","nthperm","nthperm(p) +("Base","nthperm","nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + + nthperm(p) Return the \"k\" that generated permutation \"p\". Note that \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". "), -("Base","nthperm","nthperm(p) +("Base","nthperm","nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + + nthperm(p) Return the \"k\" that generated permutation \"p\". Note that \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". @@ -931,7 +1188,32 @@ Any[ "), -("Base","partitions","partitions(array, m) +("Base","partitions","partitions(n) + + Generate all integer arrays that sum to \"n\". Because the number + of partitions can be very large, this function returns an iterator + object. Use \"collect(partitions(n))\" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using \"length(partitions(n))\". + + partitions(n, m) + + Generate all arrays of \"m\" integers that sum to \"n\". Because + the number of partitions can be very large, this function returns + an iterator object. Use \"collect(partitions(n,m))\" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using \"length(partitions(n,m))\". + + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + \"collect(partitions(array))\" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using \"length(partitions(array))\". + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the @@ -943,7 +1225,32 @@ Any[ "), -("Base","partitions","partitions(array, m) +("Base","partitions","partitions(n) + + Generate all integer arrays that sum to \"n\". Because the number + of partitions can be very large, this function returns an iterator + object. Use \"collect(partitions(n))\" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using \"length(partitions(n))\". + + partitions(n, m) + + Generate all arrays of \"m\" integers that sum to \"n\". Because + the number of partitions can be very large, this function returns + an iterator object. Use \"collect(partitions(n,m))\" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using \"length(partitions(n,m))\". + + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + \"collect(partitions(array))\" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using \"length(partitions(array))\". + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the @@ -955,7 +1262,32 @@ Any[ "), -("Base","partitions","partitions(array, m) +("Base","partitions","partitions(n) + + Generate all integer arrays that sum to \"n\". Because the number + of partitions can be very large, this function returns an iterator + object. Use \"collect(partitions(n))\" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using \"length(partitions(n))\". + + partitions(n, m) + + Generate all arrays of \"m\" integers that sum to \"n\". Because + the number of partitions can be very large, this function returns + an iterator object. Use \"collect(partitions(n,m))\" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using \"length(partitions(n,m))\". + + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + \"collect(partitions(array))\" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using \"length(partitions(array))\". + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the @@ -967,7 +1299,32 @@ Any[ "), -("Base","partitions","partitions(array, m) +("Base","partitions","partitions(n) + + Generate all integer arrays that sum to \"n\". Because the number + of partitions can be very large, this function returns an iterator + object. Use \"collect(partitions(n))\" to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using \"length(partitions(n))\". + + partitions(n, m) + + Generate all arrays of \"m\" integers that sum to \"n\". Because + the number of partitions can be very large, this function returns + an iterator object. Use \"collect(partitions(n,m))\" to get an + array of all partitions. The number of partitions to generate can + be efficiently computed using \"length(partitions(n,m))\". + + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + \"collect(partitions(array))\" to get an array of all partitions. + The number of partitions to generate can be efficiently computed + using \"length(partitions(array))\". + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the @@ -997,13 +1354,23 @@ Any[ "), -("Base","rol!","rol!(B::BitArray{1}, i::Integer) -> BitArray{1} +("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on \"src\" and put the result + into \"dest\". + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. "), -("Base","rol!","rol!(B::BitArray{1}, i::Integer) -> BitArray{1} +("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on \"src\" and put the result + into \"dest\". + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. @@ -1015,13 +1382,23 @@ Any[ "), -("Base","ror!","ror!(B::BitArray{1}, i::Integer) -> BitArray{1} +("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on \"src\" and put the result + into \"dest\". + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. "), -("Base","ror!","ror!(B::BitArray{1}, i::Integer) -> BitArray{1} +("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on \"src\" and put the result + into \"dest\". + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. @@ -1033,13 +1410,37 @@ Any[ "), -("Base","sparse","sparse(A) +("Base","sparse","sparse(I, J, V[, m, n, combine]) + + Create a sparse matrix \"S\" of dimensions \"m x n\" such that + \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to + combine duplicates. If \"m\" and \"n\" are not specified, they are + set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" + function is not supplied, duplicates are added by default. + + sparse(A) Convert an AbstractMatrix \"A\" into a sparse matrix. "), -("Base","sparsevec","sparsevec(A) +("Base","sparsevec","sparsevec(I, V[, m, combine]) + + Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] + = V[k]\". Duplicates are combined using the \"combine\" function, + which defaults to \"+\" if it is not provided. In julia, sparse + vectors are really just sparse matrices with one column. Given + Julia's Compressed Sparse Columns (CSC) storage format, a sparse + column matrix with one column is sparse, whereas a sparse row + matrix with one row ends up being dense. + + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size \"m x 1\" where the row values are + keys from the dictionary, and the nonzero values are the values + from the dictionary. + + sparsevec(A) Convert a dense vector \"A\" into a sparse matrix of size \"m x 1\". In julia, sparse vectors are really just sparse matrices with @@ -1047,7 +1448,23 @@ Any[ "), -("Base","sparsevec","sparsevec(A) +("Base","sparsevec","sparsevec(I, V[, m, combine]) + + Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] + = V[k]\". Duplicates are combined using the \"combine\" function, + which defaults to \"+\" if it is not provided. In julia, sparse + vectors are really just sparse matrices with one column. Given + Julia's Compressed Sparse Columns (CSC) storage format, a sparse + column matrix with one column is sparse, whereas a sparse row + matrix with one row ends up being dense. + + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size \"m x 1\" where the row values are + keys from the dictionary, and the nonzero values are the values + from the dictionary. + + sparsevec(A) Convert a dense vector \"A\" into a sparse matrix of size \"m x 1\". In julia, sparse vectors are really just sparse matrices with @@ -1061,13 +1478,37 @@ Any[ "), -("Base","sparse","sparse(A) +("Base","sparse","sparse(I, J, V[, m, n, combine]) + + Create a sparse matrix \"S\" of dimensions \"m x n\" such that + \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to + combine duplicates. If \"m\" and \"n\" are not specified, they are + set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" + function is not supplied, duplicates are added by default. + + sparse(A) Convert an AbstractMatrix \"A\" into a sparse matrix. "), -("Base","sparsevec","sparsevec(A) +("Base","sparsevec","sparsevec(I, V[, m, combine]) + + Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] + = V[k]\". Duplicates are combined using the \"combine\" function, + which defaults to \"+\" if it is not provided. In julia, sparse + vectors are really just sparse matrices with one column. Given + Julia's Compressed Sparse Columns (CSC) storage format, a sparse + column matrix with one column is sparse, whereas a sparse row + matrix with one row ends up being dense. + + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size \"m x 1\" where the row values are + keys from the dictionary, and the nonzero values are the values + from the dictionary. + + sparsevec(A) Convert a dense vector \"A\" into a sparse matrix of size \"m x 1\". In julia, sparse vectors are really just sparse matrices with @@ -1075,7 +1516,16 @@ Any[ "), -("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix +("Base","full","full(S) + + Convert a sparse matrix \"S\" into a dense matrix. + + full(F) + + Reconstruct the matrix \"A\" from the factorization + \"F=factorize(A)\". + + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a \"QRCompactWYQ\" object, i.e. in the compact WY format @@ -1261,14 +1711,24 @@ Any[ "), -("Base","edit","edit(function[, types]) +("Base","edit","edit(file::AbstractString[, line]) + + Edit a file optionally providing a line number to edit at. Returns + to the julia prompt when you quit the editor. + + edit(function[, types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. "), -("Base","edit","edit(function[, types]) +("Base","edit","edit(file::AbstractString[, line]) + + Edit a file optionally providing a line number to edit at. Returns + to the julia prompt when you quit the editor. + + edit(function[, types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. @@ -1282,7 +1742,13 @@ Any[ "), -("Base","less","less(function[, types]) +("Base","less","less(file::AbstractString[, line]) + + Show a file using the default pager, optionally providing a + starting line number. Returns to the julia prompt when you quit the + pager. + + less(function[, types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to @@ -1290,7 +1756,13 @@ Any[ "), -("Base","less","less(function[, types]) +("Base","less","less(file::AbstractString[, line]) + + Show a file using the default pager, optionally providing a + starting line number. Returns to the julia prompt when you quit the + pager. + + less(function[, types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to @@ -1305,14 +1777,24 @@ Any[ "), -("Base","clipboard","clipboard() -> AbstractString +("Base","clipboard","clipboard(x) + + Send a printed form of \"x\" to the operating system clipboard + (\"copy\"). + + clipboard() -> AbstractString Return a string with the contents of the operating system clipboard (\"paste\"). "), -("Base","clipboard","clipboard() -> AbstractString +("Base","clipboard","clipboard(x) + + Send a printed form of \"x\" to the operating system clipboard + (\"copy\"). + + clipboard() -> AbstractString Return a string with the contents of the operating system clipboard (\"paste\"). @@ -1376,14 +1858,30 @@ Any[ "), -("Base","which","which(symbol) +("Base","which","which(f, types) + + Returns the method of \"f\" (a \"Method\" object) that would be + called for arguments of the given types. + + If \"types\" is an abstract type, then the method that would be + called by \"invoke\" is returned. + + which(symbol) Return the module in which the binding for the variable referenced by \"symbol\" was created. "), -("Base","which","which(symbol) +("Base","which","which(f, types) + + Returns the method of \"f\" (a \"Method\" object) that would be + called for arguments of the given types. + + If \"types\" is an abstract type, then the method that would be + called by \"invoke\" is returned. + + which(symbol) Return the module in which the binding for the variable referenced by \"symbol\" was created. @@ -1452,11 +1950,15 @@ Any[ "), -("Base","===","===(x, y) +("Base","is","is(x, y) -> Bool - ≡(x, y) + ===(x, y) -> Bool ≡(x, y) -> Bool - See the \"is()\" operator + Determine whether \"x\" and \"y\" are identical, in the sense that + no program could distinguish them. Compares mutable objects by + address in memory, and compares immutable objects (such as numbers) + by contents at the bit level. This function is sometimes called + \"egal\". "), @@ -1697,15 +2199,19 @@ Any[ "), -("Base","<:","<:(T1, T2) +("Base","issubtype","issubtype(type1, type2) - Subtype operator, equivalent to \"issubtype(T1,T2)\". + True if and only if all values of \"type1\" are also of \"type2\". + Can also be written using the \"<:\" infix operator as \"type1 <: + type2\". "), -("Base","<:","<:(T1, T2) +("Base","issubtype","issubtype(type1, type2) - Subtype operator, equivalent to \"issubtype(T1,T2)\". + True if and only if all values of \"type1\" are also of \"type2\". + Can also be written using the \"<:\" infix operator as \"type1 <: + type2\". "), @@ -1750,27 +2256,42 @@ Any[ "), -("Base","sizeof","sizeof(s::AbstractString) +("Base","sizeof","sizeof(type) + + Size, in bytes, of the canonical binary representation of the given + type, if any. + + sizeof(s::AbstractString) The number of bytes in string \"s\". "), -("Base","eps","eps(::DateTime) -> Millisecond +("Base","eps","eps([type]) - eps(::Date) -> Day + The distance between 1.0 and the next larger representable + floating-point value of \"type\". Only floating-point types are + sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" + is returned. - Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" - for \"Date\" values. + eps(x) + + The distance between \"x\" and the next larger representable + floating-point value of the same type as \"x\". "), -("Base","eps","eps(::DateTime) -> Millisecond +("Base","eps","eps([type]) + + The distance between 1.0 and the next larger representable + floating-point value of \"type\". Only floating-point types are + sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" + is returned. - eps(::Date) -> Day + eps(x) - Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" - for \"Date\" values. + The distance between \"x\" and the next larger representable + floating-point value of the same type as \"x\". "), @@ -2025,7 +2546,28 @@ Any[ "), -("Base","parse","parse(type, str[, base]) +("Base","parse","parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could + later be passed to eval for execution). Start is the index of the + first character to start parsing. If \"greedy\" is true (default), + \"parse\" will try to consume as much input as it can; otherwise, + it will stop as soon as it has parsed a valid expression. + Incomplete but otherwise syntactically valid expressions will + return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is + true (default), syntax errors other than incomplete expressions + will raise an error. If \"raise\" is false, \"parse\" will return + an expression that will raise an error upon evaluation. + + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An + error is thrown if there are additional characters after the first + expression. If \"raise\" is true (default), syntax errors will + raise an error; otherwise, \"parse\" will return an expression that + will raise an error upon evaluation. + + parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a @@ -2035,7 +2577,28 @@ Any[ "), -("Base","parse","parse(type, str[, base]) +("Base","parse","parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could + later be passed to eval for execution). Start is the index of the + first character to start parsing. If \"greedy\" is true (default), + \"parse\" will try to consume as much input as it can; otherwise, + it will stop as soon as it has parsed a valid expression. + Incomplete but otherwise syntactically valid expressions will + return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is + true (default), syntax errors other than incomplete expressions + will raise an error. If \"raise\" is false, \"parse\" will return + an expression that will raise an error upon evaluation. + + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An + error is thrown if there are additional characters after the first + expression. If \"raise\" is true (default), syntax errors will + raise an error; otherwise, \"parse\" will return an expression that + will raise an error upon evaluation. + + parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a @@ -2054,7 +2617,24 @@ Any[ "), -("Base","get","get(f::Function, collection, key) +("Base","get","get(x) + + Attempt to access the value of the \"Nullable\" object, \"x\". + Returns the value if it is present; otherwise, throws a + \"NullException\". + + get(x, y) + + Attempt to access the value of the \"Nullable{T}\" object, \"x\". + Returns the value if it is present; otherwise, returns \"convert(T, + y)\". + + 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. + + 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 @@ -2069,7 +2649,24 @@ Any[ "), -("Base","get","get(f::Function, collection, key) +("Base","get","get(x) + + Attempt to access the value of the \"Nullable\" object, \"x\". + Returns the value if it is present; otherwise, throws a + \"NullException\". + + get(x, y) + + Attempt to access the value of the \"Nullable{T}\" object, \"x\". + Returns the value if it is present; otherwise, returns \"convert(T, + y)\". + + 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. + + 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 @@ -2133,7 +2730,12 @@ Any[ "), -("Base","kill","kill(manager::FooManager, pid::Int, config::WorkerConfig) +("Base","kill","kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the + process. + + kill(manager::FooManager, pid::Int, config::WorkerConfig) Implemented by cluster managers. It is called on the master process, by \"rmprocs\". It should cause the remote worker @@ -2143,7 +2745,45 @@ Any[ "), -("Base","open","open(f::function, args...) +("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) + + Start running \"command\" asynchronously, and return a tuple + \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" + reads from the process's standard output and \"stdio\" optionally + specifies the process's standard input stream. If \"mode\" is + \"\"w\"\", then \"stream\" writes to the process's standard input + and \"stdio\" optionally specifies the process's standard output + stream. + + open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) + + Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + \"f\". + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of \"mode\" + correspond to those from \"fopen(3)\" or Perl \"open\", and are + equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read + | +–––+–––––––––––––––––-+ | r+ | read, write + | +–––+–––––––––––––––––-+ | w | write, create, truncate + | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate + | +–––+–––––––––––––––––-+ | a | write, create, append + | +–––+–––––––––––––––––-+ | a+ | read, write, create, append + | +–––+–––––––––––––––––-+ + + open(f::function, args...) Apply the function \"f\" to the result of \"open(args...)\" and close the resulting file descriptor upon completion. @@ -2152,7 +2792,45 @@ Any[ "), -("Base","open","open(f::function, args...) +("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) + + Start running \"command\" asynchronously, and return a tuple + \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" + reads from the process's standard output and \"stdio\" optionally + specifies the process's standard input stream. If \"mode\" is + \"\"w\"\", then \"stream\" writes to the process's standard input + and \"stdio\" optionally specifies the process's standard output + stream. + + open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) + + Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + \"f\". + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of \"mode\" + correspond to those from \"fopen(3)\" or Perl \"open\", and are + equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read + | +–––+–––––––––––––––––-+ | r+ | read, write + | +–––+–––––––––––––––––-+ | w | write, create, truncate + | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate + | +–––+–––––––––––––––––-+ | a | write, create, append + | +–––+–––––––––––––––––-+ | a+ | read, write, create, append + | +–––+–––––––––––––––––-+ + + open(f::function, args...) Apply the function \"f\" to the result of \"open(args...)\" and close the resulting file descriptor upon completion. @@ -2225,7 +2903,23 @@ Any[ "), -("Base","pipe","pipe(command; stdin, stdout, stderr, append=false) +("Base","pipe","pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source + and destination can be commands, I/O streams, strings, or results + of other \"pipe\" calls. At least one argument must be a command. + Strings refer to filenames. When called with more than two + arguments, they are chained together from left to right. For + example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". + This provides a more concise way to specify multi-stage pipelines. + + **Examples**: * \"run(pipe(\"ls\", \"grep xyz\"))\" + + * \"run(pipe(`ls`, \"out.txt\"))\" + + * \"run(pipe(\"out.txt\", `grep xyz`))\" + + pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given \"command\". Keyword arguments specify which of the command's streams should be redirected. @@ -2242,7 +2936,23 @@ Any[ "), -("Base","pipe","pipe(command; stdin, stdout, stderr, append=false) +("Base","pipe","pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source + and destination can be commands, I/O streams, strings, or results + of other \"pipe\" calls. At least one argument must be a command. + Strings refer to filenames. When called with more than two + arguments, they are chained together from left to right. For + example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". + This provides a more concise way to specify multi-stage pipelines. + + **Examples**: * \"run(pipe(\"ls\", \"grep xyz\"))\" + + * \"run(pipe(`ls`, \"out.txt\"))\" + + * \"run(pipe(\"out.txt\", `grep xyz`))\" + + pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given \"command\". Keyword arguments specify which of the command's streams should be redirected. @@ -2278,10 +2988,10 @@ Any[ "), -("Base","time","time(t::TmStruct) +("Base","time","time() - Converts a \"TmStruct\" struct to a number of seconds since the - epoch. + Get the system time in seconds since the epoch, with fairly high + (typically, microsecond) resolution. "), @@ -2610,14 +3320,32 @@ Any[ "), -("Base","Timer","Timer(delay, repeat=0) +("Base","Timer","Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. The callback is + passed one argument, the timer object itself. The callback will be + invoked after the specified initial delay, and then repeating with + the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is + only triggered once. Times are in seconds. A timer is stopped and + has its resources freed by calling \"close\" on it. + + Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling \"wait\" on the timer object) at a specified interval. "), -("Base","Timer","Timer(delay, repeat=0) +("Base","Timer","Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. The callback is + passed one argument, the timer object itself. The callback will be + invoked after the specified initial delay, and then repeating with + the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is + only triggered once. Times are in seconds. A timer is stopped and + has its resources freed by calling \"close\" on it. + + Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling \"wait\" on the timer object) at a specified interval. @@ -2697,14 +3425,24 @@ Any[ "), -("Base","functionloc","functionloc(m::Method) +("Base","functionloc","functionloc(f::Function, types) + + Returns a tuple \"(filename,line)\" giving the location of a method + definition. + + functionloc(m::Method) Returns a tuple \"(filename,line)\" giving the location of a method definition. "), -("Base","functionloc","functionloc(m::Method) +("Base","functionloc","functionloc(f::Function, types) + + Returns a tuple \"(filename,line)\" giving the location of a method + definition. + + functionloc(m::Method) Returns a tuple \"(filename,line)\" giving the location of a method definition. @@ -2940,7 +3678,18 @@ Any[ "), -("Base","unsafe_copy!","unsafe_copy!(dest::Array, do, src::Array, so, N) +("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy \"N\" elements from a source pointer to a destination, with no + checking. The size of an element is determined by the type of the + pointers. + + The \"unsafe\" prefix on this function indicates that no validation + is performed on the pointers \"dest\" and \"src\" to ensure that + they are valid. Incorrect usage may corrupt or segfault your + program, in the same manner as C. + + unsafe_copy!(dest::Array, do, src::Array, so, N) Copy \"N\" elements from a source array to a destination, starting at offset \"so\" in the source and \"do\" in the destination @@ -2953,7 +3702,18 @@ Any[ "), -("Base","unsafe_copy!","unsafe_copy!(dest::Array, do, src::Array, so, N) +("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy \"N\" elements from a source pointer to a destination, with no + checking. The size of an element is determined by the type of the + pointers. + + The \"unsafe\" prefix on this function indicates that no validation + is performed on the pointers \"dest\" and \"src\" to ensure that + they are valid. Incorrect usage may corrupt or segfault your + program, in the same manner as C. + + unsafe_copy!(dest::Array, do, src::Array, so, N) Copy \"N\" elements from a source array to a destination, starting at offset \"so\" in the source and \"do\" in the destination @@ -2966,7 +3726,12 @@ Any[ "), -("Base","copy!","copy!(dest, do, src, so, N) +("Base","copy!","copy!(dest, src) + + Copy all elements from collection \"src\" to array \"dest\". + Returns \"dest\". + + copy!(dest, do, src, so, N) Copy \"N\" elements from collection \"src\" starting at offset \"so\", to array \"dest\" starting at offset \"do\". Returns @@ -2974,7 +3739,12 @@ Any[ "), -("Base","copy!","copy!(dest, do, src, so, N) +("Base","copy!","copy!(dest, src) + + Copy all elements from collection \"src\" to array \"dest\". + Returns \"dest\". + + copy!(dest, do, src, so, N) Copy \"N\" elements from collection \"src\" starting at offset \"so\", to array \"dest\" starting at offset \"do\". Returns @@ -3294,7 +4064,17 @@ Any[ "), -("Base","length","length(s) +("Base","length","length(A) -> Integer + + Returns the number of elements in A + + length(collection) -> Integer + + For ordered, indexable collections, the maximum index \"i\" for + which \"getindex(collection, i)\" is valid. For unordered + collections, the number of elements. + + length(s) The number of characters in string \"s\". @@ -3360,7 +4140,30 @@ Any[ "), -("Base","reduce","reduce(op, itr) +("Base","reduce","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. + + 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 @@ -3369,7 +4172,30 @@ Any[ "), -("Base","reduce","reduce(op, itr) +("Base","reduce","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. + + 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 @@ -3378,7 +4204,12 @@ Any[ "), -("Base","foldl","foldl(op, itr) +("Base","foldl","foldl(op, v0, itr) + + Like \"reduce()\", but with guaranteed left associativity. \"v0\" + will be used exactly once. + + 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 @@ -3386,7 +4217,12 @@ Any[ "), -("Base","foldl","foldl(op, itr) +("Base","foldl","foldl(op, v0, itr) + + Like \"reduce()\", but with guaranteed left associativity. \"v0\" + will be used exactly once. + + 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 @@ -3394,7 +4230,12 @@ Any[ "), -("Base","foldr","foldr(op, itr) +("Base","foldr","foldr(op, v0, itr) + + Like \"reduce()\", but with guaranteed right associativity. \"v0\" + will be used exactly once. + + 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 @@ -3402,7 +4243,12 @@ Any[ "), -("Base","foldr","foldr(op, itr) +("Base","foldr","foldr(op, v0, itr) + + Like \"reduce()\", but with guaranteed right associativity. \"v0\" + will be used exactly once. + + 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 @@ -3410,13 +4256,21 @@ Any[ "), -("Base","maximum","maximum(A, dims) +("Base","maximum","maximum(itr) + + Returns the largest element in a collection. + + maximum(A, dims) Compute the maximum value of an array over the given dimensions. "), -("Base","maximum","maximum(A, dims) +("Base","maximum","maximum(itr) + + Returns the largest element in a collection. + + maximum(A, dims) Compute the maximum value of an array over the given dimensions. @@ -3429,13 +4283,21 @@ Any[ "), -("Base","minimum","minimum(A, dims) +("Base","minimum","minimum(itr) + + Returns the smallest element in a collection. + + minimum(A, dims) Compute the minimum value of an array over the given dimensions. "), -("Base","minimum","minimum(A, dims) +("Base","minimum","minimum(itr) + + Returns the smallest element in a collection. + + minimum(A, dims) Compute the minimum value of an array over the given dimensions. @@ -3467,41 +4329,65 @@ Any[ "), -("Base","findmax","findmax(A, dims) -> (maxval, index) +("Base","findmax","findmax(itr) -> (x, index) + + Returns the maximum element and its index. + + findmax(A, dims) -> (maxval, index) For an array input, returns the value and index of the maximum over the given dimensions. "), -("Base","findmax","findmax(A, dims) -> (maxval, index) +("Base","findmax","findmax(itr) -> (x, index) + + Returns the maximum element and its index. + + findmax(A, dims) -> (maxval, index) For an array input, returns the value and index of the maximum over the given dimensions. "), -("Base","findmin","findmin(A, dims) -> (minval, index) +("Base","findmin","findmin(itr) -> (x, index) + + Returns the minimum element and its index. + + findmin(A, dims) -> (minval, index) For an array input, returns the value and index of the minimum over the given dimensions. "), -("Base","findmin","findmin(A, dims) -> (minval, index) +("Base","findmin","findmin(itr) -> (x, index) + + Returns the minimum element and its index. + + findmin(A, dims) -> (minval, index) For an array input, returns the value and index of the minimum over the given dimensions. "), -("Base","maxabs","maxabs(A, dims) +("Base","maxabs","maxabs(itr) + + Compute the maximum absolute value of a collection of values. + + maxabs(A, dims) Compute the maximum absolute values over given dimensions. "), -("Base","maxabs","maxabs(A, dims) +("Base","maxabs","maxabs(itr) + + Compute the maximum absolute value of a collection of values. + + maxabs(A, dims) Compute the maximum absolute values over given dimensions. @@ -3514,13 +4400,21 @@ Any[ "), -("Base","minabs","minabs(A, dims) +("Base","minabs","minabs(itr) + + Compute the minimum absolute value of a collection of values. + + minabs(A, dims) Compute the minimum absolute values over given dimensions. "), -("Base","minabs","minabs(A, dims) +("Base","minabs","minabs(itr) + + Compute the minimum absolute value of a collection of values. + + minabs(A, dims) Compute the minimum absolute values over given dimensions. @@ -3533,14 +4427,30 @@ Any[ "), -("Base","sum","sum(f, itr) +("Base","sum","sum(itr) + + Returns the sum of all elements in a collection. + + sum(A, dims) + + Sum elements of an array over the given dimensions. + + sum(f, itr) Sum the results of calling function \"f\" on each element of \"itr\". "), -("Base","sum","sum(f, itr) +("Base","sum","sum(itr) + + Returns the sum of all elements in a collection. + + sum(A, dims) + + Sum elements of an array over the given dimensions. + + sum(f, itr) Sum the results of calling function \"f\" on each element of \"itr\". @@ -3554,21 +4464,39 @@ Any[ "), -("Base","sum","sum(f, itr) +("Base","sum","sum(itr) + + Returns the sum of all elements in a collection. + + sum(A, dims) + + Sum elements of an array over the given dimensions. + + sum(f, itr) Sum the results of calling function \"f\" on each element of \"itr\". "), -("Base","sumabs","sumabs(A, dims) +("Base","sumabs","sumabs(itr) + + Sum absolute values of all elements in a collection. This is + equivalent to *sum(abs(itr))* but faster. + + sumabs(A, dims) Sum absolute values of elements of an array over the given dimensions. "), -("Base","sumabs","sumabs(A, dims) +("Base","sumabs","sumabs(itr) + + Sum absolute values of all elements in a collection. This is + equivalent to *sum(abs(itr))* but faster. + + sumabs(A, dims) Sum absolute values of elements of an array over the given dimensions. @@ -3582,14 +4510,24 @@ Any[ "), -("Base","sumabs2","sumabs2(A, dims) +("Base","sumabs2","sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This + is equivalent to *sum(abs2(itr))* but faster. + + sumabs2(A, dims) Sum squared absolute values of elements of an array over the given dimensions. "), -("Base","sumabs2","sumabs2(A, dims) +("Base","sumabs2","sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This + is equivalent to *sum(abs2(itr))* but faster. + + sumabs2(A, dims) Sum squared absolute values of elements of an array over the given dimensions. @@ -3603,13 +4541,21 @@ Any[ "), -("Base","prod","prod(A, dims) +("Base","prod","prod(itr) + + Returns the product of all elements of a collection. + + prod(A, dims) Multiply elements of an array over the given dimensions. "), -("Base","prod","prod(A, dims) +("Base","prod","prod(itr) + + Returns the product of all elements of a collection. + + prod(A, dims) Multiply elements of an array over the given dimensions. @@ -3622,14 +4568,32 @@ Any[ "), -("Base","any","any(p, itr) -> Bool +("Base","any","any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + any(A, dims) + + Test whether any values along the given dimensions of an array are + true. + + any(p, itr) -> Bool Determine whether predicate \"p\" returns true for any elements of \"itr\". "), -("Base","any","any(p, itr) -> Bool +("Base","any","any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + any(A, dims) + + Test whether any values along the given dimensions of an array are + true. + + any(p, itr) -> Bool Determine whether predicate \"p\" returns true for any elements of \"itr\". @@ -3643,7 +4607,16 @@ Any[ "), -("Base","all","all(p, itr) -> Bool +("Base","all","all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + + all(A, dims) + + Test whether all values along the given dimensions of an array are + true. + + all(p, itr) -> Bool Determine whether predicate \"p\" returns true for all elements of \"itr\". @@ -3653,7 +4626,16 @@ Any[ "), -("Base","all","all(p, itr) -> Bool +("Base","all","all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + + all(A, dims) + + Test whether all values along the given dimensions of an array are + true. + + all(p, itr) -> Bool Determine whether predicate \"p\" returns true for all elements of \"itr\". @@ -3677,14 +4659,32 @@ Any[ "), -("Base","any","any(p, itr) -> Bool +("Base","any","any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + any(A, dims) + + Test whether any values along the given dimensions of an array are + true. + + any(p, itr) -> Bool Determine whether predicate \"p\" returns true for any elements of \"itr\". "), -("Base","all","all(p, itr) -> Bool +("Base","all","all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + + all(A, dims) + + Test whether all values along the given dimensions of an array are + true. + + all(p, itr) -> Bool Determine whether predicate \"p\" returns true for all elements of \"itr\". @@ -3713,7 +4713,11 @@ Any[ "), -("Base","map!","map!(function, destination, collection...) +("Base","map!","map!(function, collection) + + In-place version of \"map()\". + + 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 @@ -3721,7 +4725,11 @@ Any[ "), -("Base","map!","map!(function, destination, collection...) +("Base","map!","map!(function, collection) + + In-place version of \"map()\". + + 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 @@ -3729,21 +4737,70 @@ Any[ "), -("Base","mapreduce","mapreduce(f, op, itr) +("Base","mapreduce","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. + + mapreduce(f, op, itr) Like \"mapreduce(f, op, v0, itr)\". In general, this cannot be used with empty collections (see \"reduce(op, itr)\"). "), -("Base","mapreduce","mapreduce(f, op, itr) +("Base","mapreduce","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. + + 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","mapfoldl(f, op, itr) +("Base","mapfoldl","mapfoldl(f, op, v0, itr) + + Like \"mapreduce()\", but with guaranteed left associativity. + \"v0\" will be used exactly once. + + 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 @@ -3751,7 +4808,12 @@ Any[ "), -("Base","mapfoldl","mapfoldl(f, op, itr) +("Base","mapfoldl","mapfoldl(f, op, v0, itr) + + Like \"mapreduce()\", but with guaranteed left associativity. + \"v0\" will be used exactly once. + + 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 @@ -3759,7 +4821,12 @@ Any[ "), -("Base","mapfoldr","mapfoldr(f, op, itr) +("Base","mapfoldr","mapfoldr(f, op, v0, itr) + + Like \"mapreduce()\", but with guaranteed right associativity. + \"v0\" will be used exactly once. + + 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 @@ -3767,7 +4834,12 @@ Any[ "), -("Base","mapfoldr","mapfoldr(f, op, itr) +("Base","mapfoldr","mapfoldr(f, op, v0, itr) + + Like \"mapreduce()\", but with guaranteed right associativity. + \"v0\" will be used exactly once. + + 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 @@ -3797,21 +4869,38 @@ Any[ "), -("Base","collect","collect(element_type, collection) +("Base","collect","collect(collection) + + Return an array of all items in a collection. For associative + collections, returns (key, value) tuples. + + collect(element_type, collection) Return an array of type \"Array{element_type,1}\" of all items in a collection. "), -("Base","collect","collect(element_type, collection) +("Base","collect","collect(collection) + + Return an array of all items in a collection. For associative + collections, returns (key, value) tuples. + + collect(element_type, collection) Return an array of type \"Array{element_type,1}\" of all items in a collection. "), -("Base","issubset","issubset(A, S) -> Bool +("Base","issubset","issubset(a, b) + + ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool + + Determine whether every element of \"a\" is also in \"b\", using + \"in()\". + + issubset(A, S) -> Bool ⊆(A, S) -> Bool @@ -3835,7 +4924,19 @@ Any[ "), -("Base","getindex","getindex(collection, key...) +("Base","getindex","getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called + with the syntax \"Type[]\". Element values can be specified using + \"Type[a,b,c,...]\". + + getindex(A, inds...) + + Returns a subset of array \"A\" as specified by \"inds\", where + each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See + the manual section on *array indexing* for details. + + 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 @@ -3843,7 +4944,12 @@ Any[ "), -("Base","setindex!","setindex!(collection, value, key...) +("Base","setindex!","setindex!(A, X, inds...) + + Store values from array \"X\" within some subset of \"A\" as + specified by \"inds\". + + 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 @@ -3880,7 +4986,24 @@ Any[ "), -("Base","get","get(f::Function, collection, key) +("Base","get","get(x) + + Attempt to access the value of the \"Nullable\" object, \"x\". + Returns the value if it is present; otherwise, throws a + \"NullException\". + + get(x, y) + + Attempt to access the value of the \"Nullable{T}\" object, \"x\". + Returns the value if it is present; otherwise, returns \"convert(T, + y)\". + + 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. + + 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 @@ -3895,7 +5018,24 @@ Any[ "), -("Base","get","get(f::Function, collection, key) +("Base","get","get(x) + + Attempt to access the value of the \"Nullable\" object, \"x\". + Returns the value if it is present; otherwise, throws a + \"NullException\". + + get(x, y) + + Attempt to access the value of the \"Nullable{T}\" object, \"x\". + Returns the value if it is present; otherwise, returns \"convert(T, + y)\". + + 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. + + 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 @@ -3914,7 +5054,12 @@ Any[ "), -("Base","get!","get!(f::Function, collection, key) +("Base","get!","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\". + + 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()\". @@ -3928,7 +5073,12 @@ Any[ "), -("Base","get!","get!(f::Function, collection, key) +("Base","get!","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\". + + 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()\". @@ -3960,7 +5110,13 @@ Any[ "), -("Base","pop!","pop!(collection) -> item +("Base","pop!","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. + + pop!(collection) -> item Remove the last item in \"collection\" and return it. @@ -4110,21 +5266,51 @@ Any[ "), -("Base","symdiff!","symdiff!(s1, s2) +("Base","symdiff!","symdiff!(s, n) + + The set \"s\" is destructively modified to toggle the inclusion of + integer \"n\". + + symdiff!(s, itr) + + For each element in \"itr\", destructively toggle its inclusion in + set \"s\". + + symdiff!(s1, s2) Construct the symmetric difference of sets \"s1\" and \"s2\", storing the result in \"s1\". "), -("Base","symdiff!","symdiff!(s1, s2) +("Base","symdiff!","symdiff!(s, n) + + The set \"s\" is destructively modified to toggle the inclusion of + integer \"n\". + + symdiff!(s, itr) + + For each element in \"itr\", destructively toggle its inclusion in + set \"s\". + + symdiff!(s1, s2) Construct the symmetric difference of sets \"s1\" and \"s2\", storing the result in \"s1\". "), -("Base","symdiff!","symdiff!(s1, s2) +("Base","symdiff!","symdiff!(s, n) + + The set \"s\" is destructively modified to toggle the inclusion of + integer \"n\". + + symdiff!(s, itr) + + For each element in \"itr\", destructively toggle its inclusion in + set \"s\". + + symdiff!(s1, s2) Construct the symmetric difference of sets \"s1\" and \"s2\", storing the result in \"s1\". @@ -4151,7 +5337,14 @@ Any[ "), -("Base","issubset","issubset(A, S) -> Bool +("Base","issubset","issubset(a, b) + + ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool + + Determine whether every element of \"a\" is also in \"b\", using + \"in()\". + + issubset(A, S) -> Bool ⊆(A, S) -> Bool @@ -4178,7 +5371,13 @@ Any[ "), -("Base","pop!","pop!(collection) -> item +("Base","pop!","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. + + pop!(collection) -> item Remove the last item in \"collection\" and return it. @@ -4261,7 +5460,21 @@ Any[ "), -("Base","deleteat!","deleteat!(collection, itr) +("Base","deleteat!","deleteat!(collection, index) + + Remove the item at the given \"index\" and return the modified + \"collection\". 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 + + deleteat!(collection, itr) Remove the items at the indices given by \"itr\", and return the modified \"collection\". Subsequent items are shifted to fill the @@ -4279,7 +5492,21 @@ Any[ "), -("Base","deleteat!","deleteat!(collection, itr) +("Base","deleteat!","deleteat!(collection, index) + + Remove the item at the given \"index\" and return the modified + \"collection\". 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 + + deleteat!(collection, itr) Remove the items at the indices given by \"itr\", and return the modified \"collection\". Subsequent items are shifted to fill the @@ -4297,7 +5524,52 @@ Any[ "), -("Base","splice!","splice!(collection, range[, replacement]) -> items +("Base","splice!","splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. + Subsequent items are shifted down 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)\". + + splice!(collection, range[, replacement]) -> items Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down to @@ -4323,7 +5595,52 @@ Any[ "), -("Base","splice!","splice!(collection, range[, replacement]) -> items +("Base","splice!","splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. + Subsequent items are shifted down 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)\". + + splice!(collection, range[, replacement]) -> items Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down to @@ -4620,7 +5937,82 @@ Any[ "), -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime +("Dates","DateTime","DateTime() + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + + DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code + | Matches | Comment + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" + | 1996, 96 | Returns year of 1996, 0096 + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" + | 1, 01 | Matches 1 or 2-digit months + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" + | Jan | Matches abbreviated months according to the + \"locale\" keyword | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" + | January | Matches full month names according to the \"locale\" + keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"d\" | 1, 01 | Matches 1 or 2-digit days + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" + | 00 | Matches hours + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" + | 00 | Matches minutes + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" + | 00 | Matches seconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" + | .500 | Matches milliseconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" + | Mon, Tues | Matches abbreviated days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" + | Monday | Matches full name days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and + day | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a \"DateTime\", but passes a \"DateFormat\" object instead of a raw formatting string. It is @@ -4630,7 +6022,82 @@ Any[ "), -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime +("Dates","DateTime","DateTime() + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + + DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code + | Matches | Comment + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" + | 1996, 96 | Returns year of 1996, 0096 + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" + | 1, 01 | Matches 1 or 2-digit months + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" + | Jan | Matches abbreviated months according to the + \"locale\" keyword | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" + | January | Matches full month names according to the \"locale\" + keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"d\" | 1, 01 | Matches 1 or 2-digit days + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" + | 00 | Matches hours + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" + | 00 | Matches minutes + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" + | 00 | Matches seconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" + | .500 | Matches milliseconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" + | Mon, Tues | Matches abbreviated days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" + | Monday | Matches full name days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and + day | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a \"DateTime\", but passes a \"DateFormat\" object instead of a raw formatting string. It is @@ -4640,7 +6107,82 @@ Any[ "), -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime +("Dates","DateTime","DateTime() + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + + DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code + | Matches | Comment + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" + | 1996, 96 | Returns year of 1996, 0096 + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" + | 1, 01 | Matches 1 or 2-digit months + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" + | Jan | Matches abbreviated months according to the + \"locale\" keyword | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" + | January | Matches full month names according to the \"locale\" + keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"d\" | 1, 01 | Matches 1 or 2-digit days + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" + | 00 | Matches hours + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" + | 00 | Matches minutes + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" + | 00 | Matches seconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" + | .500 | Matches milliseconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" + | Mon, Tues | Matches abbreviated days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" + | Monday | Matches full name days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and + day | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a \"DateTime\", but passes a \"DateFormat\" object instead of a raw formatting string. It is @@ -4650,7 +6192,82 @@ Any[ "), -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime +("Dates","DateTime","DateTime() + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + + DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code + | Matches | Comment + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" + | 1996, 96 | Returns year of 1996, 0096 + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" + | 1, 01 | Matches 1 or 2-digit months + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" + | Jan | Matches abbreviated months according to the + \"locale\" keyword | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" + | January | Matches full month names according to the \"locale\" + keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"d\" | 1, 01 | Matches 1 or 2-digit days + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" + | 00 | Matches hours + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" + | 00 | Matches minutes + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" + | 00 | Matches seconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" + | .500 | Matches milliseconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" + | Mon, Tues | Matches abbreviated days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" + | Monday | Matches full name days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and + day | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a \"DateTime\", but passes a \"DateFormat\" object instead of a raw formatting string. It is @@ -4660,7 +6277,82 @@ Any[ "), -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime +("Dates","DateTime","DateTime() + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + + DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code + | Matches | Comment + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" + | 1996, 96 | Returns year of 1996, 0096 + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" + | 1, 01 | Matches 1 or 2-digit months + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" + | Jan | Matches abbreviated months according to the + \"locale\" keyword | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" + | January | Matches full month names according to the \"locale\" + keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"d\" | 1, 01 | Matches 1 or 2-digit days + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" + | 00 | Matches hours + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" + | 00 | Matches minutes + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" + | 00 | Matches seconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" + | .500 | Matches milliseconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" + | Mon, Tues | Matches abbreviated days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" + | Monday | Matches full name days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and + day | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a \"DateTime\", but passes a \"DateFormat\" object instead of a raw formatting string. It is @@ -4679,7 +6371,82 @@ Any[ "), -("Dates","DateTime","DateTime(dt::AbstractString, df::DateFormat) -> DateTime +("Dates","DateTime","DateTime() + + \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it + according to the proleptic Gregorian calendar. + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible + to \"Int64\". + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by \"Period\" type parts. Arguments may be + in any order. DateTime parts not provided will default to the value + of \"Dates.default(period)\". + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will + be constructed from the provided \"y, m, d...\" arguments, and will + be adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (in the case that \"f::Function\" is never + satisfied). + + DateTime(dt::Date) -> DateTime + + Converts a \"Date\" type to a \"DateTime\". The hour, minute, + second, and millisecond parts of the new \"DateTime\" are assumed + to be zero. + + DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime + + Construct a DateTime type by parsing the \"dt\" date string + following the pattern given in the \"format\" string. The following + codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code + | Matches | Comment + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" + | 1996, 96 | Returns year of 1996, 0096 + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" + | 1, 01 | Matches 1 or 2-digit months + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" + | Jan | Matches abbreviated months according to the + \"locale\" keyword | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" + | January | Matches full month names according to the \"locale\" + keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"d\" | 1, 01 | Matches 1 or 2-digit days + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" + | 00 | Matches hours + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" + | 00 | Matches minutes + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" + | 00 | Matches seconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" + | .500 | Matches milliseconds + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" + | Mon, Tues | Matches abbreviated days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" + | Monday | Matches full name days of the week + | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | + \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and + day | + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between + date and time slots. So a \"dt\" string of + \"1996-01-15T00:00:00.0\" would have a \"format\" string like + \"y-m-dTH:M:S.s\". + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a \"DateTime\", but passes a \"DateFormat\" object instead of a raw formatting string. It is @@ -4689,68 +6456,317 @@ Any[ "), -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date +("Dates","Date","Date() + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + + Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + + Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + + Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. + + Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date + + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string \"dt\" using a \"DateFormat\" object \"df\". "), -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date +("Dates","Date","Date() + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + + Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + + Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + + Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. + + Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date + + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string \"dt\" using a \"DateFormat\" object \"df\". "), -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date +("Dates","Date","Date() + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + + Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + + Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + + Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. + + Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date + + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string \"dt\" using a \"DateFormat\" object \"df\". "), -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date +("Dates","Date","Date() + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + + Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + + Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + + Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. + + Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date + + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. + + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string \"dt\" using a \"DateFormat\" + object \"df\". + +"), + +("Dates","Date","Date() + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + + Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + + Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + + Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. + + Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date + + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string \"dt\" using a \"DateFormat\" object \"df\". "), -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date +("Dates","Date","Date() + + \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to + the proleptic Gregorian calendar. + + Date(y[, m, d]) -> Date + + Construct a \"Date\" type by parts. Arguments must be convertible + to \"Int64\". + + Date(period::Period...) -> Date + + Constuct a Date type by \"Period\" type parts. Arguments may be in + any order. Date parts not provided will default to the value of + \"Dates.default(period)\". + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be + constructed from the provided \"y, m\" arguments, and will be + adjusted until \"f::Function\" returns true. The step size in + adjusting can be provided manually through the \"step\" keyword. If + \"negate=true\", then the adjusting will stop when \"f::Function\" + returns false instead of true. \"limit\" provides a limit to the + max number of iterations the adjustment API will pursue before + throwing an error (given that \"f::Function\" is never satisfied). + + Date(dt::DateTime) -> Date + + Converts a \"DateTime\" type to a \"Date\". The hour, minute, + second, and millisecond parts of the \"DateTime\" are truncated, so + only the year, month and day parts are used in construction. - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". + Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date -"), + Construct a Date type by parsing a \"dt\" date string following the + pattern given in the \"format\" string. Follows the same + conventions as \"DateTime\" above. -("Dates","Date","Date(dt::AbstractString, df::DateFormat) -> Date + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string \"dt\" using a \"DateFormat\" object \"df\". "), -("Dates","now","now(::Type{UTC}) -> DateTime +("Dates","now","now() -> DateTime + + Returns a DateTime corresponding to the user's system time + including the system timezone locale. + + now(::Type{UTC}) -> DateTime Returns a DateTime corresponding to the user's system time as UTC/GMT. "), -("Dates","now","now(::Type{UTC}) -> DateTime +("Dates","now","now() -> DateTime + + Returns a DateTime corresponding to the user's system time + including the system timezone locale. + + now(::Type{UTC}) -> DateTime Returns a DateTime corresponding to the user's system time as UTC/GMT. "), -("Dates","eps","eps(::DateTime) -> Millisecond +("Dates","eps","eps([type]) + + The distance between 1.0 and the next larger representable + floating-point value of \"type\". Only floating-point types are + sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" + is returned. - eps(::Date) -> Day + eps(x) - Returns \"Millisecond(1)\" for \"DateTime\" values and \"Day(1)\" - for \"Date\" values. + The distance between \"x\" and the next larger representable + floating-point value of the same type as \"x\". "), @@ -4767,6 +6783,19 @@ Any[ ("Dates","Year","Year(v) + Year + + Year(dt::TimeType) -> Year + + Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week + Day(dt::TimeType) -> Day Hour(dt::TimeType) -> Hour + Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second + Millisecond(dt::TimeType) -> Millisecond + + Return the field part of a Date or DateTime as a \"Period\" type. + + Year(v) + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) Construct a \"Period\" type with the given \"v\" value. Input must @@ -4949,7 +6978,14 @@ Any[ "), -("Dates","tonext","tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType +("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts \"dt\" to the next day of week corresponding to \"dow\" + with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows + the current \"dt\" to be considered as the next \"dow\", allowing + for no adjustment to occur. + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType Adjusts \"dt\" by iterating at most \"limit\" iterations by \"step\" increments until \"func\" returns true. \"func\" must take @@ -4960,7 +6996,14 @@ Any[ "), -("Dates","toprev","toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType +("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts \"dt\" to the previous day of week corresponding to \"dow\" + with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows + the current \"dt\" to be considered as the previous \"dow\", + allowing for no adjustment to occur. + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType Adjusts \"dt\" by iterating at most \"limit\" iterations by \"step\" increments until \"func\" returns true. \"func\" must take @@ -4985,7 +7028,14 @@ Any[ "), -("Dates","tonext","tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType +("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts \"dt\" to the next day of week corresponding to \"dow\" + with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows + the current \"dt\" to be considered as the next \"dow\", allowing + for no adjustment to occur. + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType Adjusts \"dt\" by iterating at most \"limit\" iterations by \"step\" increments until \"func\" returns true. \"func\" must take @@ -4996,7 +7046,14 @@ Any[ "), -("Dates","toprev","toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType +("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts \"dt\" to the previous day of week corresponding to \"dow\" + with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows + the current \"dt\" to be considered as the previous \"dow\", + allowing for no adjustment to occur. + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType Adjusts \"dt\" by iterating at most \"limit\" iterations by \"step\" increments until \"func\" returns true. \"func\" must take @@ -5020,6 +7077,19 @@ Any[ ("Dates","Year","Year(v) + Year + + Year(dt::TimeType) -> Year + + Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week + Day(dt::TimeType) -> Day Hour(dt::TimeType) -> Hour + Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second + Millisecond(dt::TimeType) -> Millisecond + + Return the field part of a Date or DateTime as a \"Period\" type. + + Year(v) + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) Construct a \"Period\" type with the given \"v\" value. Input must @@ -5089,14 +7159,22 @@ Any[ "), -("Base","cd","cd(f[, dir]) +("Base","cd","cd(dir::AbstractString) + + Set the current working directory. + + cd(f[, dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. "), -("Base","cd","cd(f[, dir]) +("Base","cd","cd(dir::AbstractString) + + Set the current working directory. + + cd(f[, dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. @@ -5537,7 +7615,45 @@ Any[ "), -("Base","open","open(f::function, args...) +("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) + + Start running \"command\" asynchronously, and return a tuple + \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" + reads from the process's standard output and \"stdio\" optionally + specifies the process's standard input stream. If \"mode\" is + \"\"w\"\", then \"stream\" writes to the process's standard input + and \"stdio\" optionally specifies the process's standard output + stream. + + open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) + + Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + \"f\". + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of \"mode\" + correspond to those from \"fopen(3)\" or Perl \"open\", and are + equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read + | +–––+–––––––––––––––––-+ | r+ | read, write + | +–––+–––––––––––––––––-+ | w | write, create, truncate + | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate + | +–––+–––––––––––––––––-+ | a | write, create, append + | +–––+–––––––––––––––––-+ | a+ | read, write, create, append + | +–––+–––––––––––––––––-+ + + open(f::function, args...) Apply the function \"f\" to the result of \"open(args...)\" and close the resulting file descriptor upon completion. @@ -5546,7 +7662,45 @@ Any[ "), -("Base","open","open(f::function, args...) +("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) + + Start running \"command\" asynchronously, and return a tuple + \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" + reads from the process's standard output and \"stdio\" optionally + specifies the process's standard input stream. If \"mode\" is + \"\"w\"\", then \"stream\" writes to the process's standard input + and \"stdio\" optionally specifies the process's standard output + stream. + + open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) + + Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + \"f\". + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of \"mode\" + correspond to those from \"fopen(3)\" or Perl \"open\", and are + equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read + | +–––+–––––––––––––––––-+ | r+ | read, write + | +–––+–––––––––––––––––-+ | w | write, create, truncate + | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate + | +–––+–––––––––––––––––-+ | a | write, create, append + | +–––+–––––––––––––––––-+ | a+ | read, write, create, append + | +–––+–––––––––––––––––-+ + + open(f::function, args...) Apply the function \"f\" to the result of \"open(args...)\" and close the resulting file descriptor upon completion. @@ -5555,7 +7709,45 @@ Any[ "), -("Base","open","open(f::function, args...) +("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) + + Start running \"command\" asynchronously, and return a tuple + \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" + reads from the process's standard output and \"stdio\" optionally + specifies the process's standard input stream. If \"mode\" is + \"\"w\"\", then \"stream\" writes to the process's standard input + and \"stdio\" optionally specifies the process's standard output + stream. + + open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) + + Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" + on the resulting read or write stream, then closes the stream and + waits for the process to complete. Returns the value returned by + \"f\". + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The + default is to open files for reading only. Returns a stream for + accessing the file. + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is + used instead of the five booleans. The values of \"mode\" + correspond to those from \"fopen(3)\" or Perl \"open\", and are + equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read + | +–––+–––––––––––––––––-+ | r+ | read, write + | +–––+–––––––––––––––––-+ | w | write, create, truncate + | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate + | +–––+–––––––––––––––––-+ | a | write, create, append + | +–––+–––––––––––––––––-+ | a+ | read, write, create, append + | +–––+–––––––––––––––––-+ + + open(f::function, args...) Apply the function \"f\" to the result of \"open(args...)\" and close the resulting file descriptor upon completion. @@ -5564,7 +7756,19 @@ Any[ "), -("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) +("Base","IOBuffer","IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict @@ -5575,7 +7779,19 @@ Any[ "), -("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) +("Base","IOBuffer","IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict @@ -5586,7 +7802,19 @@ Any[ "), -("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) +("Base","IOBuffer","IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict @@ -5597,7 +7825,19 @@ Any[ "), -("Base","IOBuffer","IOBuffer([data][, readable, writable[, maxsize]]) +("Base","IOBuffer","IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict @@ -5651,7 +7891,12 @@ Any[ "), -("Base","read","read(stream, type, dims) +("Base","read","read(stream, type) + + Read a value of the given type from a stream, in canonical binary + representation. + + read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. \"dims\" is either a tuple or a @@ -5660,7 +7905,12 @@ Any[ "), -("Base","read","read(stream, type, dims) +("Base","read","read(stream, type) + + Read a value of the given type from a stream, in canonical binary + representation. + + read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. \"dims\" is either a tuple or a @@ -5836,14 +8086,30 @@ Any[ "), -("Base","redirect_stdout","redirect_stdout(stream) +("Base","redirect_stdout","redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be + redirected. Returns a tuple (rd,wr) representing the pipe ends. + Data written to STDOUT may now be read from the rd end of the pipe. + The wr end is given for convenience in case the old STDOUT object + was cached by the user and needs to be replaced elsewhere. + + redirect_stdout(stream) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. "), -("Base","redirect_stdout","redirect_stdout(stream) +("Base","redirect_stdout","redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be + redirected. Returns a tuple (rd,wr) representing the pipe ends. + Data written to STDOUT may now be read from the rd end of the pipe. + The wr end is given for convenience in case the old STDOUT object + was cached by the user and needs to be replaced elsewhere. + + redirect_stdout(stream) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. @@ -5898,7 +8164,13 @@ Any[ "), -("Base","PipeBuffer","PipeBuffer(data::Vector{UInt8}[, maxsize]) +("Base","PipeBuffer","PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. + Seeking and truncating are not supported. See IOBuffer for the + available constructors. + + PipeBuffer(data::Vector{UInt8}[, maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be @@ -5906,7 +8178,13 @@ Any[ "), -("Base","PipeBuffer","PipeBuffer(data::Vector{UInt8}[, maxsize]) +("Base","PipeBuffer","PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. + Seeking and truncating are not supported. See IOBuffer for the + available constructors. + + PipeBuffer(data::Vector{UInt8}[, maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be @@ -6027,14 +8305,22 @@ Any[ "), -("Base","readall","readall(filename::AbstractString) +("Base","readall","readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + + readall(filename::AbstractString) Open \"filename\", read the entire contents as a string, then close the file. Equivalent to \"open(readall, filename)\". "), -("Base","readall","readall(filename::AbstractString) +("Base","readall","readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + + readall(filename::AbstractString) Open \"filename\", read the entire contents as a string, then close the file. Equivalent to \"open(readall, filename)\". @@ -6067,7 +8353,72 @@ Any[ "), -("Base","readdlm","readdlm(source; options...) +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"n\". + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \"n\". If all data is @@ -6077,7 +8428,72 @@ Any[ "), -("Base","readdlm","readdlm(source; options...) +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"n\". + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \"n\". If all data is @@ -6087,7 +8503,72 @@ Any[ "), -("Base","readdlm","readdlm(source; options...) +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"n\". + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \"n\". If all data is @@ -6097,7 +8578,72 @@ Any[ "), -("Base","readdlm","readdlm(source; options...) +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"n\". + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \"n\". If all data is @@ -6107,7 +8653,72 @@ Any[ "), -("Base","readdlm","readdlm(source; options...) +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"n\". + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \"n\". If all data is @@ -6117,7 +8728,72 @@ Any[ "), -("Base","readdlm","readdlm(source; options...) +("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by + \"eol\") gives one row, with elements separated by the given + delimeter. The source can be a text file, stream or byte array. + Memory mapped files can be used by passing the byte array + representation of the mapped segment as source. + + If \"T\" is a numeric type, the result is an array of that type, + with any non-numeric elements as \"NaN\" for floating-point types, + or zero. Other useful values of \"T\" include \"ASCIIString\", + \"AbstractString\", and \"Any\". + + If \"header\" is \"true\", the first row of data will be read as + header and the tuple \"(data_cells, header_cells)\" is returned + instead of only \"data_cells\". + + Specifying \"skipstart\" will ignore the corresponding number of + initial lines from the input. + + If \"skipblanks\" is \"true\", blank lines in the input will be + ignored. + + If \"use_mmap\" is \"true\", the file specified by \"source\" is + memory mapped for potential speedups. Default is \"true\" except on + Windows. On Windows, you may want to specify \"true\" if the file + is large, and is only read once and not written to. + + If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with + invalid character encoding will be ignored. Otherwise an error is + thrown indicating the offending character position. + + If \"quotes\" is \"true\", column enclosed within double-quote (``) + characters are allowed to contain new lines and column delimiters. + Double-quote characters within a quoted field must be escaped with + another double-quote. + + Specifying \"dims\" as a tuple of the expected rows and columns + (including header, if any) may speed up reading of large files. + + If \"comments\" is \"true\", lines beginning with \"comment_char\" + and text following \"comment_char\" in any line are ignored. + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some + elements cannot be parsed as numbers, a cell array of numbers and + strings is returned. + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as \"n\". + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as \"n\". If all data is + numeric, the result will be a numeric array. If some elements + cannot be parsed as numbers, a cell array of numbers and strings is + returned. + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. + The end of line delimiter is taken as \"n\". + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as \"n\". If all data is @@ -6402,22 +9078,22 @@ Any[ "), -("Base","msync","msync(ptr, len[, flags]) +("Base","msync","msync(array) - Forces synchronization of the \"mmap()\"ped memory region from - \"ptr\" to \"ptr+len\". Flags defaults to \"MS_SYNC\", but can be a - combination of \"MS_ASYNC\", \"MS_SYNC\", or \"MS_INVALIDATE\". See - your platform man page for specifics. The flags argument is not - valid on Windows. - - You may not need to call \"msync\", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. + Forces synchronization between the in-memory version of a memory- + mapped \"Array\" or \"BitArray\" and the on-disk version. "), -("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +("Base","connect","connect([host], port) -> TcpSocket + + Connect to the host \"host\" on port \"port\" + + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at \"path\" + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id \"pid\", specified @@ -6431,7 +9107,15 @@ Any[ "), -("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +("Base","connect","connect([host], port) -> TcpSocket + + Connect to the host \"host\" on port \"port\" + + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at \"path\" + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id \"pid\", specified @@ -6443,15 +9127,27 @@ Any[ \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP socket connections in-between workers. -"), +"), + +("Base","listen","listen([addr], port) -> TcpServer + + Listen on port on the address specified by \"addr\". By default + this listens on localhost only. To listen on all interfaces pass, + \"IPv4(0)\" or \"IPv6(0)\" as appropriate. -("Base","listen","listen(path) -> PipeServer + listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket "), -("Base","listen","listen(path) -> PipeServer +("Base","listen","listen([addr], port) -> TcpServer + + Listen on port on the address specified by \"addr\". By default + this listens on localhost only. To listen on all interfaces pass, + \"IPv4(0)\" or \"IPv6(0)\" as appropriate. + + listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket @@ -6663,10 +9359,10 @@ Any[ "), -("Libc","time","time(t::TmStruct) +("Libc","time","time() - Converts a \"TmStruct\" struct to a number of seconds since the - epoch. + Get the system time in seconds since the epoch, with fairly high + (typically, microsecond) resolution. "), @@ -6706,18 +9402,10 @@ Any[ "), -("Libc","msync","msync(ptr, len[, flags]) - - Forces synchronization of the \"mmap()\"ped memory region from - \"ptr\" to \"ptr+len\". Flags defaults to \"MS_SYNC\", but can be a - combination of \"MS_ASYNC\", \"MS_SYNC\", or \"MS_INVALIDATE\". See - your platform man page for specifics. The flags argument is not - valid on Windows. +("Libc","msync","msync(array) - You may not need to call \"msync\", because synchronization is - performed at intervals automatically by the operating system. - However, you can call this directly if, for example, you are - concerned about losing the result of a long-running calculation. + Forces synchronization between the in-memory version of a memory- + mapped \"Array\" or \"BitArray\" and the on-disk version. "), @@ -6878,7 +9566,16 @@ Any[ "), -("Base","*","*(s, t) +("Base","*","*(A, B) + + Matrix multiplication + + *(x, y...) + + Multiplication operator. \"x*y*z*...\" calls this function with all + arguments, i.e. \">>*<<(x, y, z, ...)\". + + *(s, t) Concatenate strings. The \"*\" operator is an alias to this function. @@ -6944,7 +9641,16 @@ Any[ "), -("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix +("Base","full","full(S) + + Convert a sparse matrix \"S\" into a dense matrix. + + full(F) + + Reconstruct the matrix \"A\" from the factorization + \"F=factorize(A)\". + + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a \"QRCompactWYQ\" object, i.e. in the compact WY format @@ -7052,7 +9758,23 @@ Any[ "), -("Base","cholfact","cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +("Base","cholfact","cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive + (semi)definite matrix \"A\" and return either a \"Cholesky\" if + \"pivot==Val{false}\" or \"CholeskyPivoted\" if + \"pivot==Val{true}\". \"LU\" may be \":L\" for using the lower part + or \":U\" for the upper part. The default is to use \":U\". The + triangular matrix can be obtained from the factorization \"F\" + with: \"F[:L]\" and \"F[:U]\". The following functions are + available for \"Cholesky\" objects: \"size\", \"\", \"inv\", + \"det\". For \"CholeskyPivoted\" there is also defined a \"rank\". + If \"pivot==Val{false}\" a \"PosDefException\" exception is thrown + in case the matrix is not positive definite. The argument \"tol\" + determines the tolerance for determining the rank. For negative + values, the tolerance is the machine precision. + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the Cholesky factorization of a sparse positive definite matrix \"A\". A fill-reducing permutation is used. \"F = @@ -7079,7 +9801,23 @@ Any[ "), -("Base","cholfact","cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +("Base","cholfact","cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive + (semi)definite matrix \"A\" and return either a \"Cholesky\" if + \"pivot==Val{false}\" or \"CholeskyPivoted\" if + \"pivot==Val{true}\". \"LU\" may be \":L\" for using the lower part + or \":U\" for the upper part. The default is to use \":U\". The + triangular matrix can be obtained from the factorization \"F\" + with: \"F[:L]\" and \"F[:U]\". The following functions are + available for \"Cholesky\" objects: \"size\", \"\", \"inv\", + \"det\". For \"CholeskyPivoted\" there is also defined a \"rank\". + If \"pivot==Val{false}\" a \"PosDefException\" exception is thrown + in case the matrix is not positive definite. The argument \"tol\" + determines the tolerance for determining the rank. For negative + values, the tolerance is the machine precision. + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the Cholesky factorization of a sparse positive definite matrix \"A\". A fill-reducing permutation is used. \"F = @@ -7116,7 +9854,13 @@ Any[ "), -("Base","ldltfact","ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +("Base","ldltfact","ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix \"A\" such + that \"A=L*Diagonal(d)*L'\" where \"L\" is a unit lower triangular + matrix and \"d\" is a vector with non-negative elements. + + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the LDLt factorization of a sparse symmetric or Hermitian matrix \"A\". A fill-reducing permutation is used. \"F = @@ -7144,7 +9888,13 @@ Any[ "), -("Base","ldltfact","ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +("Base","ldltfact","ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix \"A\" such + that \"A=L*Diagonal(d)*L'\" where \"L\" is a unit lower triangular + matrix and \"d\" is a vector with non-negative elements. + + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the LDLt factorization of a sparse symmetric or Hermitian matrix \"A\". A fill-reducing permutation is used. \"F = @@ -7181,7 +9931,85 @@ Any[ "), -("Base","qrfact","qrfact(A) -> SPQR.Factorization +("Base","qrfact","qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of \"A\". The return type of \"F\" + depends on the element type of \"A\" and whether pivoting is + specified (with \"pivot==Val{true}\"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + + \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", + \"Complex64\" or \"Complex128\". + + The individual components of the factorization \"F\" can be + accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:p]\" | pivot \"Vector\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the \"QR\" objects: + \"size\", \"\". When \"A\" is rectangular, \"\" will return a least + squares solution and if the solution is not unique, the one with + smallest norm is returned. + + Multiplication with respect to either thin or full \"Q\" is + allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A + \"Q\" matrix can be converted into a regular matrix with \"full()\" + which has a named argument \"thin\". + + Note: \"qrfact\" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the \"Q\" and \"R\" matrices can be stored compactly rather + as two separate dense matrices.The data contained in \"QR\" or + \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, + which is a compact representation of the rotation matrix: + + Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) + + where tau_i is the scale factor and v_i is the projection vector + associated with the i^{th} Householder elementary reflector.The + data contained in \"QRCompactWY\" can be used to construct the + \"QRCompactWYQ\" type, which is a compact representation of the + rotation matrix + + Q = I + Y T Y^T + + where \"Y\" is m times r lower trapezoidal and \"T\" is r times r + upper triangular. The *compact WY* representation [Schreiber1989] + is not to be confused with the older, *WY* representation + [Bischof1987]. (The LAPACK documentation uses \"V\" in lieu of + \"Y\".) + + [Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 + + qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix \"A\". A fill- reducing permutation is used. The main application of this type is @@ -7191,7 +10019,85 @@ Any[ "), -("Base","qrfact","qrfact(A) -> SPQR.Factorization +("Base","qrfact","qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of \"A\". The return type of \"F\" + depends on the element type of \"A\" and whether pivoting is + specified (with \"pivot==Val{true}\"). + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | + +------------------+-------------------+----------------+---------------------------------------+ + + \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", + \"Complex64\" or \"Complex128\". + + The individual components of the factorization \"F\" can be + accessed by indexing: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:p]\" | pivot \"Vector\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the \"QR\" objects: + \"size\", \"\". When \"A\" is rectangular, \"\" will return a least + squares solution and if the solution is not unique, the one with + smallest norm is returned. + + Multiplication with respect to either thin or full \"Q\" is + allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A + \"Q\" matrix can be converted into a regular matrix with \"full()\" + which has a named argument \"thin\". + + Note: \"qrfact\" returns multiple types because LAPACK uses + several representations that minimize the memory storage + requirements of products of Householder elementary reflectors, so + that the \"Q\" and \"R\" matrices can be stored compactly rather + as two separate dense matrices.The data contained in \"QR\" or + \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, + which is a compact representation of the rotation matrix: + + Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) + + where tau_i is the scale factor and v_i is the projection vector + associated with the i^{th} Householder elementary reflector.The + data contained in \"QRCompactWY\" can be used to construct the + \"QRCompactWYQ\" type, which is a compact representation of the + rotation matrix + + Q = I + Y T Y^T + + where \"Y\" is m times r lower trapezoidal and \"T\" is r times r + upper triangular. The *compact WY* representation [Schreiber1989] + is not to be confused with the older, *WY* representation + [Bischof1987]. (The LAPACK documentation uses \"V\" in lieu of + \"Y\".) + + [Bischof1987] C Bischof and C Van Loan, The WY + representation for products of Householder matrices, + SIAM J Sci Stat Comput 8 (1987), s2-s13. + doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A + storage-efficient WY representation for products of + Householder transformations, SIAM J Sci Stat Comput + 10 (1989), 53-57. doi:10.1137/0910005 + + qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix \"A\". A fill- reducing permutation is used. The main application of this type is @@ -7209,7 +10115,16 @@ Any[ "), -("Base","full","full(QRCompactWYQ[, thin=true]) -> Matrix +("Base","full","full(S) + + Convert a sparse matrix \"S\" into a dense matrix. + + full(F) + + Reconstruct the matrix \"A\" from the factorization + \"F=factorize(A)\". + + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a \"QRCompactWYQ\" object, i.e. in the compact WY format @@ -7256,7 +10171,23 @@ Any[ "), -("Base","eig","eig(A, B) -> D, V +("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" + for details on the \"balance\" keyword argument. + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + \"eig\" is a wrapper around \"eigfact()\", extracting all parts of + the factorization to a tuple; where possible, using \"eigfact()\" + is recommended. + + eig(A, B) -> D, V Computes generalized eigenvalues and vectors of \"A\" with respect to \"B\". @@ -7267,7 +10198,23 @@ Any[ "), -("Base","eig","eig(A, B) -> D, V +("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" + for details on the \"balance\" keyword argument. + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + \"eig\" is a wrapper around \"eigfact()\", extracting all parts of + the factorization to a tuple; where possible, using \"eigfact()\" + is recommended. + + eig(A, B) -> D, V Computes generalized eigenvalues and vectors of \"A\" with respect to \"B\". @@ -7321,7 +10268,31 @@ Any[ "), -("Base","eigfact","eigfact(A, B) -> GeneralizedEigen +("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of \"A\", returning an + \"Eigen\" factorization object \"F\" which contains the eigenvalues + in \"F[:values]\" and the eigenvectors in the columns of the matrix + \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the + slice \"F[:vectors][:, k]\".) + + The following functions are available for \"Eigen\" objects: + \"inv\", \"det\". + + If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it + is possible to calculate only a subset of the eigenvalues by + specifying either a \"UnitRange\" \"irange\" covering indices of + the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower + and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the + matrix is balanced before the eigenvector calculation. The option + \"permute=true\" permutes the matrix to become closer to upper + triangular, and \"scale=true\" scales the matrix by its diagonal + elements to make rows and columns more equal in norm. The default + is \"true\" for both options. + + eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of \"A\" and \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" @@ -7332,7 +10303,31 @@ Any[ "), -("Base","eigfact","eigfact(A, B) -> GeneralizedEigen +("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of \"A\", returning an + \"Eigen\" factorization object \"F\" which contains the eigenvalues + in \"F[:values]\" and the eigenvectors in the columns of the matrix + \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the + slice \"F[:vectors][:, k]\".) + + The following functions are available for \"Eigen\" objects: + \"inv\", \"det\". + + If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it + is possible to calculate only a subset of the eigenvalues by + specifying either a \"UnitRange\" \"irange\" covering indices of + the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower + and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the + matrix is balanced before the eigenvector calculation. The option + \"permute=true\" permutes the matrix to become closer to upper + triangular, and \"scale=true\" scales the matrix by its diagonal + elements to make rows and columns more equal in norm. The default + is \"true\" for both options. + + eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of \"A\" and \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" @@ -7368,7 +10363,17 @@ Any[ "), -("Base","schurfact","schurfact(A, B) -> GeneralizedSchur +("Base","schurfact","schurfact(A) -> Schur + + Computes the Schur factorization of the matrix \"A\". The (quasi) + triangular Schur factor can be obtained from the \"Schur\" object + \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the + unitary/orthogonal Schur vectors can be obtained with + \"F[:vectors]\" or \"F[:Z]\" such that + \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" + can be obtained with \"F[:values]\". + + schurfact(A, B) -> GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices \"A\" and \"B\". The (quasi) triangular Schur factors can @@ -7389,20 +10394,66 @@ Any[ "), -("Base","schur","schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] +("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + + See \"schurfact()\" + + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See \"schurfact()\" "), -("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur +("Base","ordschur","ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" + according to the logical array \"select\" returning a Schur object + \"F\". The selected eigenvalues appear in the leading diagonal of + \"F[:Schur]\" and the the corresponding leading columns of + \"F[:vectors]\" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via \"select\". + + ordschur(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\". + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix \"(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" + and returns a GeneralizedSchur object \"GS\". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of + \"A\" and \"B\" can still be obtained with + \"GS[:alpha]./GS[:beta]\". + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur +("Base","ordschur!","ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", + overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\", + overwriting \"S\" in the process. See \"ordschur()\" + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices \"(S, T, Q, Z)\" in the process. See + \"ordschur()\". + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See @@ -7410,14 +10461,56 @@ Any[ "), -("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur +("Base","ordschur","ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" + according to the logical array \"select\" returning a Schur object + \"F\". The selected eigenvalues appear in the leading diagonal of + \"F[:Schur]\" and the the corresponding leading columns of + \"F[:vectors]\" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via \"select\". + + ordschur(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\". + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix \"(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" + and returns a GeneralizedSchur object \"GS\". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of + \"A\" and \"B\" can still be obtained with + \"GS[:alpha]./GS[:beta]\". + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur +("Base","ordschur!","ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", + overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\", + overwriting \"S\" in the process. See \"ordschur()\" + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices \"(S, T, Q, Z)\" in the process. See + \"ordschur()\". + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See @@ -7425,7 +10518,17 @@ Any[ "), -("Base","schurfact","schurfact(A, B) -> GeneralizedSchur +("Base","schurfact","schurfact(A) -> Schur + + Computes the Schur factorization of the matrix \"A\". The (quasi) + triangular Schur factor can be obtained from the \"Schur\" object + \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the + unitary/orthogonal Schur vectors can be obtained with + \"F[:vectors]\" or \"F[:Z]\" such that + \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" + can be obtained with \"F[:values]\". + + schurfact(A, B) -> GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices \"A\" and \"B\". The (quasi) triangular Schur factors can @@ -7439,20 +10542,66 @@ Any[ "), -("Base","schur","schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] +("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + + See \"schurfact()\" + + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See \"schurfact()\" "), -("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur +("Base","ordschur","ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" + according to the logical array \"select\" returning a Schur object + \"F\". The selected eigenvalues appear in the leading diagonal of + \"F[:Schur]\" and the the corresponding leading columns of + \"F[:vectors]\" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via \"select\". + + ordschur(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\". + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix \"(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" + and returns a GeneralizedSchur object \"GS\". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of + \"A\" and \"B\" can still be obtained with + \"GS[:alpha]./GS[:beta]\". + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur +("Base","ordschur!","ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", + overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\", + overwriting \"S\" in the process. See \"ordschur()\" + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices \"(S, T, Q, Z)\" in the process. See + \"ordschur()\". + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See @@ -7460,14 +10609,56 @@ Any[ "), -("Base","ordschur","ordschur(GS, select) -> GeneralizedSchur +("Base","ordschur","ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" + according to the logical array \"select\" returning a Schur object + \"F\". The selected eigenvalues appear in the leading diagonal of + \"F[:Schur]\" and the the corresponding leading columns of + \"F[:vectors]\" form an orthonormal basis of the corresponding + right invariant subspace. A complex conjugate pair of eigenvalues + must be either both included or excluded via \"select\". + + ordschur(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\". + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix \"(A, B) = + (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" + and returns a GeneralizedSchur object \"GS\". The selected + eigenvalues appear in the leading diagonal of both``(GS[:S], + GS[:T])`` and the left and right unitary/orthogonal Schur vectors + are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], + GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of + \"A\" and \"B\" can still be obtained with + \"GS[:alpha]./GS[:beta]\". + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See \"ordschur()\". "), -("Base","ordschur!","ordschur!(GS, select) -> GeneralizedSchur +("Base","ordschur!","ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", + overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization \"S\" of type \"Schur\", + overwriting \"S\" in the process. See \"ordschur()\" + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by + overwriting the matrices \"(S, T, Q, Z)\" in the process. See + \"ordschur()\". + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See @@ -7475,7 +10666,17 @@ Any[ "), -("Base","svdfact","svdfact(A, B) -> GeneralizedSVD +("Base","svdfact","svdfact(A[, thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of \"A\" and return + an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained + from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" + and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is + \"true\", an economy mode decomposition is returned. The algorithm + produces \"Vt\" and hence \"Vt\" is more efficient to extract than + \"V\". The default is to produce a thin decomposition. + + svdfact(A, B) -> GeneralizedSVD Compute the generalized SVD of \"A\" and \"B\", returning a \"GeneralizedSVD\" Factorization object \"F\", such that \"A = @@ -7493,7 +10694,16 @@ Any[ "), -("Base","svd","svd(A, B) -> U, V, Q, D1, D2, R0 +("Base","svd","svd(A[, thin=true]) -> U, S, V + + Wrapper around \"svdfact\" extracting all parts the factorization + to a tuple. Direct use of \"svdfact\" is therefore generally more + efficient. Computes the SVD of A, returning \"U\", vector \"S\", + and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is + \"true\", an economy mode decomposition is returned. The default is + to produce a thin decomposition. + + svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around \"svdfact\" extracting all parts the factorization to a tuple. Direct use of \"svdfact\" is therefore generally more @@ -7503,7 +10713,11 @@ Any[ "), -("Base","svdvals","svdvals(A, B) +("Base","svdvals","svdvals(A) + + Returns the singular values of \"A\". + + svdvals(A, B) Return only the singular values from the generalized singular value decomposition of \"A\" and \"B\". @@ -7517,7 +10731,17 @@ Any[ "), -("Base","svdfact","svdfact(A, B) -> GeneralizedSVD +("Base","svdfact","svdfact(A[, thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of \"A\" and return + an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained + from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" + and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is + \"true\", an economy mode decomposition is returned. The algorithm + produces \"Vt\" and hence \"Vt\" is more efficient to extract than + \"V\". The default is to produce a thin decomposition. + + svdfact(A, B) -> GeneralizedSVD Compute the generalized SVD of \"A\" and \"B\", returning a \"GeneralizedSVD\" Factorization object \"F\", such that \"A = @@ -7526,7 +10750,16 @@ Any[ "), -("Base","svd","svd(A, B) -> U, V, Q, D1, D2, R0 +("Base","svd","svd(A[, thin=true]) -> U, S, V + + Wrapper around \"svdfact\" extracting all parts the factorization + to a tuple. Direct use of \"svdfact\" is therefore generally more + efficient. Computes the SVD of A, returning \"U\", vector \"S\", + and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is + \"true\", an economy mode decomposition is returned. The default is + to produce a thin decomposition. + + svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around \"svdfact\" extracting all parts the factorization to a tuple. Direct use of \"svdfact\" is therefore generally more @@ -7536,63 +10769,99 @@ Any[ "), -("Base","svdvals","svdvals(A, B) +("Base","svdvals","svdvals(A) + + Returns the singular values of \"A\". + + svdvals(A, B) Return only the singular values from the generalized singular value decomposition of \"A\" and \"B\". "), -("Base","triu","triu(M, k) +("Base","triu","triu(M) + + Upper triangle of a matrix. + + triu(M, k) Returns the upper triangle of \"M\" starting from the \"k\"th superdiagonal. "), -("Base","triu","triu(M, k) +("Base","triu","triu(M) + + Upper triangle of a matrix. + + triu(M, k) Returns the upper triangle of \"M\" starting from the \"k\"th superdiagonal. "), -("Base","triu!","triu!(M, k) +("Base","triu!","triu!(M) + + Upper triangle of a matrix, overwriting \"M\" in the process. + + triu!(M, k) Returns the upper triangle of \"M\" starting from the \"k\"th superdiagonal, overwriting \"M\" in the process. "), -("Base","triu!","triu!(M, k) +("Base","triu!","triu!(M) + + Upper triangle of a matrix, overwriting \"M\" in the process. + + triu!(M, k) Returns the upper triangle of \"M\" starting from the \"k\"th superdiagonal, overwriting \"M\" in the process. "), -("Base","tril","tril(M, k) +("Base","tril","tril(M) + + Lower triangle of a matrix. + + tril(M, k) Returns the lower triangle of \"M\" starting from the \"k\"th subdiagonal. "), -("Base","tril","tril(M, k) +("Base","tril","tril(M) + + Lower triangle of a matrix. + + tril(M, k) Returns the lower triangle of \"M\" starting from the \"k\"th subdiagonal. "), -("Base","tril!","tril!(M, k) +("Base","tril!","tril!(M) + + Lower triangle of a matrix, overwriting \"M\" in the process. + + tril!(M, k) Returns the lower triangle of \"M\" starting from the \"k\"th subdiagonal, overwriting \"M\" in the process. "), -("Base","tril!","tril!(M, k) +("Base","tril!","tril!(M) + + Lower triangle of a matrix, overwriting \"M\" in the process. + + tril!(M, k) Returns the lower triangle of \"M\" starting from the \"k\"th subdiagonal, overwriting \"M\" in the process. @@ -7622,6 +10891,10 @@ Any[ ("Base","scale","scale(b, A) + scale(A, b) + + scale(b, A) + Scale an array \"A\" by a scalar \"b\", returning a new array. If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" @@ -7637,6 +10910,10 @@ Any[ ("Base","scale","scale(b, A) + scale(A, b) + + scale(b, A) + Scale an array \"A\" by a scalar \"b\", returning a new array. If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" @@ -7652,6 +10929,10 @@ Any[ ("Base","scale!","scale!(b, A) + scale!(A, b) + + scale!(b, A) + Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but overwriting \"A\" in-place. @@ -7665,6 +10946,10 @@ Any[ ("Base","scale!","scale!(b, A) + scale!(A, b) + + scale!(b, A) + Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but overwriting \"A\" in-place. @@ -7876,13 +11161,45 @@ Any[ "), -("Base","linreg","linreg(x, y, w) +("Base","linreg","linreg(x, y) -> [a; b] + + Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is + the closest line to the given points \"(x,y)\". In other words, + this function determines parameters \"[a, b]\" that minimize the + squared error between \"y\" and \"a+b*x\". + + **Example**: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, \"o\") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + + linreg(x, y, w) Weighted least-squares linear regression. "), -("Base","linreg","linreg(x, y, w) +("Base","linreg","linreg(x, y) -> [a; b] + + Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is + the closest line to the given points \"(x,y)\". In other words, + this function determines parameters \"[a, b]\" that minimize the + squared error between \"y\" and \"a+b*x\". + + **Example**: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, \"o\") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + + linreg(x, y, w) Weighted least-squares linear regression. @@ -8258,7 +11575,13 @@ Any[ "), -("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, A, x) +("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, alpha, A, x) + + Returns \"alpha*A*x\" where \"A\" is a symmetric band matrix of + order \"size(A,2)\" with \"k\" super-diagonals stored in the + argument \"A\". + + sbmv(uplo, k, A, x) Returns \"A*x\" where \"A\" is a symmetric band matrix of order \"size(A,2)\" with \"k\" super-diagonals stored in the argument @@ -8266,7 +11589,13 @@ Any[ "), -("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, A, x) +("Base.LinAlg.BLAS","sbmv","sbmv(uplo, k, alpha, A, x) + + Returns \"alpha*A*x\" where \"A\" is a symmetric band matrix of + order \"size(A,2)\" with \"k\" super-diagonals stored in the + argument \"A\". + + sbmv(uplo, k, A, x) Returns \"A*x\" where \"A\" is a symmetric band matrix of order \"size(A,2)\" with \"k\" super-diagonals stored in the argument @@ -8282,14 +11611,24 @@ Any[ "), -("Base.LinAlg.BLAS","gemm","gemm(tA, tB, A, B) +("Base.LinAlg.BLAS","gemm","gemm(tA, tB, alpha, A, B) + + Returns \"alpha*A*B\" or the other three variants according to + \"tA\" (transpose \"A\") and \"tB\". + + gemm(tA, tB, A, B) Returns \"A*B\" or the other three variants according to \"tA\" (transpose \"A\") and \"tB\". "), -("Base.LinAlg.BLAS","gemm","gemm(tA, tB, A, B) +("Base.LinAlg.BLAS","gemm","gemm(tA, tB, alpha, A, B) + + Returns \"alpha*A*B\" or the other three variants according to + \"tA\" (transpose \"A\") and \"tB\". + + gemm(tA, tB, A, B) Returns \"A*B\" or the other three variants according to \"tA\" (transpose \"A\") and \"tB\". @@ -8304,13 +11643,23 @@ Any[ "), -("Base.LinAlg.BLAS","gemv","gemv(tA, A, x) +("Base.LinAlg.BLAS","gemv","gemv(tA, alpha, A, x) + + Returns \"alpha*A*x\" or \"alpha*A'x\" according to \"tA\" + (transpose \"A\"). + + gemv(tA, A, x) Returns \"A*x\" or \"A'x\" according to \"tA\" (transpose \"A\"). "), -("Base.LinAlg.BLAS","gemv","gemv(tA, A, x) +("Base.LinAlg.BLAS","gemv","gemv(tA, alpha, A, x) + + Returns \"alpha*A*x\" or \"alpha*A'x\" according to \"tA\" + (transpose \"A\"). + + gemv(tA, A, x) Returns \"A*x\" or \"A'x\" according to \"tA\" (transpose \"A\"). @@ -8324,21 +11673,54 @@ Any[ "), -("Base.LinAlg.BLAS","symm","symm(tA, tB, alpha, A, B) +("Base.LinAlg.BLAS","symm","symm(side, ul, alpha, A, B) + + Returns \"alpha*A*B\" or \"alpha*B*A\" according to \"side\". \"A\" + is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is + used. + + symm(side, ul, A, B) + + Returns \"A*B\" or \"B*A\" according to \"side\". \"A\" is assumed + to be symmetric. Only the \"ul\" triangle of \"A\" is used. + + symm(tA, tB, alpha, A, B) Returns \"alpha*A*B\" or the other three variants according to \"tA\" (transpose \"A\") and \"tB\". "), -("Base.LinAlg.BLAS","symm","symm(tA, tB, alpha, A, B) +("Base.LinAlg.BLAS","symm","symm(side, ul, alpha, A, B) + + Returns \"alpha*A*B\" or \"alpha*B*A\" according to \"side\". \"A\" + is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is + used. + + symm(side, ul, A, B) + + Returns \"A*B\" or \"B*A\" according to \"side\". \"A\" is assumed + to be symmetric. Only the \"ul\" triangle of \"A\" is used. + + symm(tA, tB, alpha, A, B) Returns \"alpha*A*B\" or the other three variants according to \"tA\" (transpose \"A\") and \"tB\". "), -("Base.LinAlg.BLAS","symm","symm(tA, tB, alpha, A, B) +("Base.LinAlg.BLAS","symm","symm(side, ul, alpha, A, B) + + Returns \"alpha*A*B\" or \"alpha*B*A\" according to \"side\". \"A\" + is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is + used. + + symm(side, ul, A, B) + + Returns \"A*B\" or \"B*A\" according to \"side\". \"A\" is assumed + to be symmetric. Only the \"ul\" triangle of \"A\" is used. + + symm(tA, tB, alpha, A, B) Returns \"alpha*A*B\" or the other three variants according to \"tA\" (transpose \"A\") and \"tB\". @@ -8353,14 +11735,24 @@ Any[ "), -("Base.LinAlg.BLAS","symv","symv(ul, A, x) +("Base.LinAlg.BLAS","symv","symv(ul, alpha, A, x) + + Returns \"alpha*A*x\". \"A\" is assumed to be symmetric. Only the + \"ul\" triangle of \"A\" is used. + + symv(ul, A, x) Returns \"A*x\". \"A\" is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is used. "), -("Base.LinAlg.BLAS","symv","symv(ul, A, x) +("Base.LinAlg.BLAS","symv","symv(ul, alpha, A, x) + + Returns \"alpha*A*x\". \"A\" is assumed to be symmetric. Only the + \"ul\" triangle of \"A\" is used. + + symv(ul, A, x) Returns \"A*x\". \"A\" is assumed to be symmetric. Only the \"ul\" triangle of \"A\" is used. @@ -8457,7 +11849,11 @@ Any[ "), -("Base","-","-(x, y) +("Base","-","-(x) + + Unary minus operator. + + -(x, y) Subtraction operator. @@ -8470,13 +11866,26 @@ Any[ "), -("Base","-","-(x, y) +("Base","-","-(x) + + Unary minus operator. + + -(x, y) Subtraction operator. "), -("Base","*","*(s, t) +("Base","*","*(A, B) + + Matrix multiplication + + *(x, y...) + + Multiplication operator. \"x*y*z*...\" calls this function with all + arguments, i.e. \">>*<<(x, y, z, ...)\". + + *(s, t) Concatenate strings. The \"*\" operator is an alias to this function. @@ -8502,7 +11911,11 @@ Any[ "), -("Base","^","^(s, n) +("Base","^","^(x, y) + + Exponentiation operator. + + ^(s, n) Repeat \"n\" times the string \"s\". The \"^\" operator is an alias to this function. @@ -8738,11 +12151,15 @@ Any[ "), -("Base","===","===(x, y) +("Base","is","is(x, y) -> Bool - ≡(x, y) + ===(x, y) -> Bool ≡(x, y) -> Bool - See the \"is()\" operator + Determine whether \"x\" and \"y\" are identical, in the sense that + no program could distinguish them. Compares mutable objects by + address in memory, and compares immutable objects (such as numbers) + by contents at the bit level. This function is sometimes called + \"egal\". "), @@ -9299,14 +12716,32 @@ Any[ "), -("Base","log","log(b, x) +("Base","log","log(x) + + Compute the natural logarithm of \"x\". Throws \"DomainError\" for + negative \"Real\" arguments. Use complex negative arguments to + obtain complex results. + + There is an experimental variant in the \"Base.Math.JuliaLibm\" + module, which is typically faster and more accurate. + + log(b, x) Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" for negative \"Real\" arguments. "), -("Base","log","log(b, x) +("Base","log","log(x) + + Compute the natural logarithm of \"x\". Throws \"DomainError\" for + negative \"Real\" arguments. Use complex negative arguments to + obtain complex results. + + There is an experimental variant in the \"Base.Math.JuliaLibm\" + module, which is typically faster and more accurate. + + log(b, x) Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" for negative \"Real\" arguments. @@ -9375,13 +12810,64 @@ Any[ "), -("Base","expm1","expm1(x) +("Base","expm1","expm1(x) + + Accurately compute e^x-1 + +"), + +("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) + + \"round(x)\" rounds \"x\" to an integer value according to the + default rounding mode (see \"get_rounding()\"), returning a value + of the same type as \"x\". By default (\"RoundNearest\"), this will + round to the nearest integer, with ties (fractional values of 0.5) + being rounded to the even integer. + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional \"RoundingMode\" argument will change how the number + gets rounded. + + \"round(T, x, [r::RoundingMode])\" converts the result to type + \"T\", throwing an \"InexactError\" if the value is not + representable. + + \"round(x, digits)\" rounds to the specified number of digits after + the decimal place (or before if negative). \"round(x, digits, + base)\" rounds using a base other than 10. + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the \"Float64\" value represented by \"1.15\" is + actually *less* than 1.15, yet will be rounded to 1.2. + + julia> x = 1.15 + 1.15 + + julia> @sprintf \"%.20f\" x + \"1.14999999999999991118\" - Accurately compute e^x-1 + julia> x < 115//100 + true -"), + julia> round(x, 1) + 1.2 -("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) + round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex- valued \"z\" to \"z\", breaking ties using the specified @@ -9471,7 +12957,58 @@ Any[ "), -("Base","round","round(z, RoundingModeReal, RoundingModeImaginary) +("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) + + \"round(x)\" rounds \"x\" to an integer value according to the + default rounding mode (see \"get_rounding()\"), returning a value + of the same type as \"x\". By default (\"RoundNearest\"), this will + round to the nearest integer, with ties (fractional values of 0.5) + being rounded to the even integer. + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional \"RoundingMode\" argument will change how the number + gets rounded. + + \"round(T, x, [r::RoundingMode])\" converts the result to type + \"T\", throwing an \"InexactError\" if the value is not + representable. + + \"round(x, digits)\" rounds to the specified number of digits after + the decimal place (or before if negative). \"round(x, digits, + base)\" rounds using a base other than 10. + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be + inexact when operating on binary floating point numbers. For + example, the \"Float64\" value represented by \"1.15\" is + actually *less* than 1.15, yet will be rounded to 1.2. + + julia> x = 1.15 + 1.15 + + julia> @sprintf \"%.20f\" x + \"1.14999999999999991118\" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + + round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex- valued \"z\" to \"z\", breaking ties using the specified @@ -9626,7 +13163,28 @@ Any[ "), -("Base","parse","parse(type, str[, base]) +("Base","parse","parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could + later be passed to eval for execution). Start is the index of the + first character to start parsing. If \"greedy\" is true (default), + \"parse\" will try to consume as much input as it can; otherwise, + it will stop as soon as it has parsed a valid expression. + Incomplete but otherwise syntactically valid expressions will + return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is + true (default), syntax errors other than incomplete expressions + will raise an error. If \"raise\" is false, \"parse\" will return + an expression that will raise an error upon evaluation. + + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An + error is thrown if there are additional characters after the first + expression. If \"raise\" is true (default), syntax errors will + raise an error; otherwise, \"parse\" will return an expression that + will raise an error upon evaluation. + + parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a @@ -10041,7 +13599,14 @@ golden "), -("Base","isprime","isprime(x::BigInt[, reps = 25]) -> Bool +("Base","isprime","isprime(x::Integer) -> Bool + + Returns \"true\" if \"x\" is prime, and \"false\" otherwise. + + julia> isprime(3) + true + + isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns \"true\" if \"x\" is prime; and \"false\" if \"x\" is not prime with high probability. The @@ -10054,7 +13619,14 @@ golden "), -("Base","isprime","isprime(x::BigInt[, reps = 25]) -> Bool +("Base","isprime","isprime(x::Integer) -> Bool + + Returns \"true\" if \"x\" is prime, and \"false\" otherwise. + + julia> isprime(3) + true + + isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns \"true\" if \"x\" is prime; and \"false\" if \"x\" is not prime with high probability. The @@ -10278,7 +13850,17 @@ golden "), -("Base","task_local_storage","task_local_storage(body, symbol, value) +("Base","task_local_storage","task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local + storage. + + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local + storage. + + task_local_storage(body, symbol, value) Call the function \"body\" with a modified task-local storage, in which \"value\" is assigned to \"symbol\"; the previous value of @@ -10287,7 +13869,17 @@ golden "), -("Base","task_local_storage","task_local_storage(body, symbol, value) +("Base","task_local_storage","task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local + storage. + + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local + storage. + + task_local_storage(body, symbol, value) Call the function \"body\" with a modified task-local storage, in which \"value\" is assigned to \"symbol\"; the previous value of @@ -10296,7 +13888,17 @@ golden "), -("Base","task_local_storage","task_local_storage(body, symbol, value) +("Base","task_local_storage","task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local + storage. + + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local + storage. + + task_local_storage(body, symbol, value) Call the function \"body\" with a modified task-local storage, in which \"value\" is assigned to \"symbol\"; the previous value of @@ -10384,7 +13986,70 @@ golden "), -("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built \"LocalManager\" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. \"addprocs(4)\" will add 4 processes + on the local machine. + + addprocs() -> List of process identifiers + + Equivalent to \"addprocs(CPU_CORES)\" + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + \"machines\" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string \"machine_spec\" or a + tuple - \"(machine_spec, count)\" + + \"machine_spec\" is a string of the form \"[user@]host[:port] + [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" + to the standard ssh port. If \"[bind_addr[:port]]\" is specified, + other workers will connect to this worker at the specified + \"bind_addr\" and \"port\". + + \"count\" is the number of workers to be launched on the specified + host. If specified as \":auto\" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + \"tunnel\" : if \"true\" then SSH tunneling will be used to connect + to the worker from the master process. + + \"sshflags\" : specifies additional ssh options, e.g. + \"sshflags=``-i /home/foo/bar.pem``\" . + + \"max_parallel\" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + \"dir\" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + \"exename\" : name of the julia executable. Defaults to + \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case + may be. + + \"exeflags\" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable \"JULIA_WORKER_TIMEOUT\". The value of + \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -10398,7 +14063,70 @@ golden "), -("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built \"LocalManager\" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. \"addprocs(4)\" will add 4 processes + on the local machine. + + addprocs() -> List of process identifiers + + Equivalent to \"addprocs(CPU_CORES)\" + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + \"machines\" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string \"machine_spec\" or a + tuple - \"(machine_spec, count)\" + + \"machine_spec\" is a string of the form \"[user@]host[:port] + [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" + to the standard ssh port. If \"[bind_addr[:port]]\" is specified, + other workers will connect to this worker at the specified + \"bind_addr\" and \"port\". + + \"count\" is the number of workers to be launched on the specified + host. If specified as \":auto\" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + \"tunnel\" : if \"true\" then SSH tunneling will be used to connect + to the worker from the master process. + + \"sshflags\" : specifies additional ssh options, e.g. + \"sshflags=``-i /home/foo/bar.pem``\" . + + \"max_parallel\" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + \"dir\" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + \"exename\" : name of the julia executable. Defaults to + \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case + may be. + + \"exeflags\" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable \"JULIA_WORKER_TIMEOUT\". The value of + \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -10412,7 +14140,70 @@ golden "), -("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built \"LocalManager\" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. \"addprocs(4)\" will add 4 processes + on the local machine. + + addprocs() -> List of process identifiers + + Equivalent to \"addprocs(CPU_CORES)\" + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + \"machines\" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string \"machine_spec\" or a + tuple - \"(machine_spec, count)\" + + \"machine_spec\" is a string of the form \"[user@]host[:port] + [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" + to the standard ssh port. If \"[bind_addr[:port]]\" is specified, + other workers will connect to this worker at the specified + \"bind_addr\" and \"port\". + + \"count\" is the number of workers to be launched on the specified + host. If specified as \":auto\" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + \"tunnel\" : if \"true\" then SSH tunneling will be used to connect + to the worker from the master process. + + \"sshflags\" : specifies additional ssh options, e.g. + \"sshflags=``-i /home/foo/bar.pem``\" . + + \"max_parallel\" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + \"dir\" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + \"exename\" : name of the julia executable. Defaults to + \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case + may be. + + \"exeflags\" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable \"JULIA_WORKER_TIMEOUT\". The value of + \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -10426,7 +14217,70 @@ golden "), -("Base","addprocs","addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built \"LocalManager\" which only + launches workers on the local host. This can be used to take + advantage of multiple cores. \"addprocs(4)\" will add 4 processes + on the local machine. + + addprocs() -> List of process identifiers + + Equivalent to \"addprocs(CPU_CORES)\" + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be + installed in the same location on each node, or to be available via + a shared file system. + + \"machines\" is a vector of machine specifications. Worker are + started for each specification. + + A machine specification is either a string \"machine_spec\" or a + tuple - \"(machine_spec, count)\" + + \"machine_spec\" is a string of the form \"[user@]host[:port] + [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" + to the standard ssh port. If \"[bind_addr[:port]]\" is specified, + other workers will connect to this worker at the specified + \"bind_addr\" and \"port\". + + \"count\" is the number of workers to be launched on the specified + host. If specified as \":auto\" it will launch as many workers as + the number of cores on the specific host. + + Keyword arguments: + + \"tunnel\" : if \"true\" then SSH tunneling will be used to connect + to the worker from the master process. + + \"sshflags\" : specifies additional ssh options, e.g. + \"sshflags=``-i /home/foo/bar.pem``\" . + + \"max_parallel\" : specifies the maximum number of workers + connected to in parallel at a host. Defaults to 10. + + \"dir\" : specifies the working directory on the workers. Defaults + to the host's current directory (as found by *pwd()*) + + \"exename\" : name of the julia executable. Defaults to + \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case + may be. + + \"exeflags\" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly + launched worker within 60.0 seconds, the worker treats it a fatal + situation and terminates. This timeout can be controlled via + environment variable \"JULIA_WORKER_TIMEOUT\". The value of + \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the + number of seconds a newly launched worker waits for connection + establishment. + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -10453,7 +14307,11 @@ golden "), -("Base","procs","procs(S::SharedArray) +("Base","procs","procs() + + Returns a list of all process identifiers. + + procs(S::SharedArray) Get the vector of processes that have mapped the shared array @@ -10592,13 +14450,21 @@ golden "), -("Base","RemoteRef","RemoteRef(n) +("Base","RemoteRef","RemoteRef() + + Make an uninitialized remote reference on the local machine. + + RemoteRef(n) Make an uninitialized remote reference on process \"n\". "), -("Base","RemoteRef","RemoteRef(n) +("Base","RemoteRef","RemoteRef() + + Make an uninitialized remote reference on the local machine. + + RemoteRef(n) Make an uninitialized remote reference on process \"n\". @@ -10694,7 +14560,11 @@ golden "), -("Base","procs","procs(S::SharedArray) +("Base","procs","procs() + + Returns a list of all process identifiers. + + procs(S::SharedArray) Get the vector of processes that have mapped the shared array @@ -10741,7 +14611,12 @@ golden "), -("Base","kill","kill(manager::FooManager, pid::Int, config::WorkerConfig) +("Base","kill","kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the + process. + + kill(manager::FooManager, pid::Int, config::WorkerConfig) Implemented by cluster managers. It is called on the master process, by \"rmprocs\". It should cause the remote worker @@ -10760,7 +14635,15 @@ golden "), -("Base","connect","connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +("Base","connect","connect([host], port) -> TcpSocket + + Connect to the host \"host\" on port \"port\" + + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at \"path\" + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id \"pid\", specified @@ -10785,7 +14668,19 @@ golden "), -("Base.Pkg","dir","dir(names...) -> AbstractString +("Base.Pkg","dir","dir() -> AbstractString + + Returns the absolute path of the package directory. This defaults + to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION + .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell + syntax). If the \"JULIA_PKGDIR\" environment variable is set, then + that path is used in the returned value as + \"joinpath(ENV[\">>JULIA_<< + PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If + \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to + whatever the current working directory is. + + dir(names...) -> AbstractString Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends path components to the package directory and normalizes the @@ -10794,7 +14689,19 @@ golden "), -("Base.Pkg","dir","dir(names...) -> AbstractString +("Base.Pkg","dir","dir() -> AbstractString + + Returns the absolute path of the package directory. This defaults + to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION + .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell + syntax). If the \"JULIA_PKGDIR\" environment variable is set, then + that path is used in the returned value as + \"joinpath(ENV[\">>JULIA_<< + PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If + \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to + whatever the current working directory is. + + dir(names...) -> AbstractString Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends path components to the package directory and normalizes the @@ -10850,7 +14757,14 @@ golden "), -("Base.Pkg","clone","clone(pkg) +("Base.Pkg","clone","clone(url[, pkg]) + + Clone a package directly from the git URL \"url\". The package does + not need to be a registered in \"Pkg.dir(\"METADATA\")\". The + package repo is cloned by the name \"pkg\" if provided; if not + provided, \"pkg\" is determined automatically from \"url\". + + clone(pkg) If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone it from that URL on the default branch. The package does not need @@ -10858,7 +14772,14 @@ golden "), -("Base.Pkg","clone","clone(pkg) +("Base.Pkg","clone","clone(url[, pkg]) + + Clone a package directly from the git URL \"url\". The package does + not need to be a registered in \"Pkg.dir(\"METADATA\")\". The + package repo is cloned by the name \"pkg\" if provided; if not + provided, \"pkg\" is determined automatically from \"url\". + + clone(pkg) If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone it from that URL on the default branch. The package does not need @@ -10866,26 +14787,44 @@ golden "), -("Base.Pkg","available","available(pkg) -> Vector{VersionNumber} +("Base.Pkg","available","available() -> Vector{ASCIIString} + + Returns the names of available packages. + + available(pkg) -> Vector{VersionNumber} Returns the version numbers available for package \"pkg\". "), -("Base.Pkg","available","available(pkg) -> Vector{VersionNumber} +("Base.Pkg","available","available() -> Vector{ASCIIString} + + Returns the names of available packages. + + available(pkg) -> Vector{VersionNumber} Returns the version numbers available for package \"pkg\". "), -("Base.Pkg","installed","installed(pkg) -> Void | VersionNumber +("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the + installed version number of each package. + + installed(pkg) -> Void | VersionNumber If \"pkg\" is installed, return the installed version number, otherwise return \"nothing\". "), -("Base.Pkg","installed","installed(pkg) -> Void | VersionNumber +("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the + installed version number of each package. + + installed(pkg) -> Void | VersionNumber If \"pkg\" is installed, return the installed version number, otherwise return \"nothing\". @@ -10916,13 +14855,23 @@ golden "), -("Base.Pkg","pin","pin(pkg, version) +("Base.Pkg","pin","pin(pkg) + + Pin \"pkg\" at the current version. To go back to using the newest + compatible released version, use \"Pkg.free(pkg)\" + + pin(pkg, version) Pin \"pkg\" at registered version \"version\". "), -("Base.Pkg","pin","pin(pkg, version) +("Base.Pkg","pin","pin(pkg) + + Pin \"pkg\" at the current version. To go back to using the newest + compatible released version, use \"Pkg.free(pkg)\" + + pin(pkg, version) Pin \"pkg\" at registered version \"version\". @@ -10941,7 +14890,12 @@ golden "), -("Base.Pkg","build","build(pkgs...) +("Base.Pkg","build","build() + + Run the build scripts for all installed packages in depth-first + recursive order. + + build(pkgs...) Run the build script in \"deps/build.jl\" for each package in \"pkgs\" and all of their dependencies in depth-first recursive @@ -10950,7 +14904,12 @@ golden "), -("Base.Pkg","build","build(pkgs...) +("Base.Pkg","build","build() + + Run the build scripts for all installed packages in depth-first + recursive order. + + build(pkgs...) Run the build script in \"deps/build.jl\" for each package in \"pkgs\" and all of their dependencies in depth-first recursive @@ -10997,7 +14956,14 @@ golden "), -("Base.Pkg","test","test(pkgs...) +("Base.Pkg","test","test() + + Run the tests for all installed packages ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its \"test/runtests.jl\" file + and test dependencies are specified in \"test/REQUIRE\". + + test(pkgs...) Run the tests for each package in \"pkgs\" ensuring that each package's test dependencies are installed for the duration of the @@ -11006,7 +14972,14 @@ golden "), -("Base.Pkg","test","test(pkgs...) +("Base.Pkg","test","test() + + Run the tests for all installed packages ensuring that each + package's test dependencies are installed for the duration of the + test. A package is tested by running its \"test/runtests.jl\" file + and test dependencies are specified in \"test/REQUIRE\". + + test(pkgs...) Run the tests for each package in \"pkgs\" ensuring that each package's test dependencies are installed for the duration of the @@ -11029,7 +15002,16 @@ golden "), -("Base.Profile","print","print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) +("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to \"io\" (by default, \"STDOUT\"). If you + do not supply a \"data\" vector, the internal buffer of accumulated + backtraces will be used. \"format\" can be \":tree\" or \":flat\". + If \"C==true\", backtraces from C and Fortran code are shown. + \"combine==true\" merges instruction pointers that correspond to + the same line of code. \"cols\" controls the width of the display. + + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) Prints profiling results to \"io\". This variant is used to examine results exported by a previous call to \"retrieve()\". Supply the @@ -11038,7 +15020,16 @@ golden "), -("Base.Profile","print","print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) +("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to \"io\" (by default, \"STDOUT\"). If you + do not supply a \"data\" vector, the internal buffer of accumulated + backtraces will be used. \"format\" can be \":tree\" or \":flat\". + If \"C==true\", backtraces from C and Fortran code are shown. + \"combine==true\" merges instruction pointers that correspond to + the same line of code. \"cols\" controls the width of the display. + + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) Prints profiling results to \"io\". This variant is used to examine results exported by a previous call to \"retrieve()\". Supply the @@ -11123,13 +15114,23 @@ golden "), -("Base","sort","sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) +("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of \"sort!\" that returns a sorted copy of \"v\" leaving + \"v\" itself unmodified. + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) Sort a multidimensional array \"A\" along the given dimension. "), -("Base","sort","sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) +("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of \"sort!\" that returns a sorted copy of \"v\" leaving + \"v\" itself unmodified. + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) Sort a multidimensional array \"A\" along the given dimension. @@ -11229,19 +15230,43 @@ golden "), -("Base","length","length(s) +("Base","length","length(A) -> Integer + + Returns the number of elements in A + + length(collection) -> Integer + + For ordered, indexable collections, the maximum index \"i\" for + which \"getindex(collection, i)\" is valid. For unordered + collections, the number of elements. + + length(s) The number of characters in string \"s\". "), -("Base","sizeof","sizeof(s::AbstractString) +("Base","sizeof","sizeof(type) + + Size, in bytes, of the canonical binary representation of the given + type, if any. + + sizeof(s::AbstractString) The number of bytes in string \"s\". "), -("Base","*","*(s, t) +("Base","*","*(A, B) + + Matrix multiplication + + *(x, y...) + + Multiplication operator. \"x*y*z*...\" calls this function with all + arguments, i.e. \">>*<<(x, y, z, ...)\". + + *(s, t) Concatenate strings. The \"*\" operator is an alias to this function. @@ -11255,7 +15280,11 @@ golden "), -("Base","^","^(s, n) +("Base","^","^(x, y) + + Exponentiation operator. + + ^(s, n) Repeat \"n\" times the string \"s\". The \"^\" operator is an alias to this function. @@ -11277,7 +15306,14 @@ golden "), -("Base","bytestring","bytestring(s) +("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) + + Create a string from the address of a C (0-terminated) string + encoded in ASCII or UTF-8. A copy is made; the ptr can be safely + freed. If \"length\" is specified, the string does not have to be + 0-terminated. + + bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be @@ -11285,7 +15321,14 @@ golden "), -("Base","bytestring","bytestring(s) +("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) + + Create a string from the address of a C (0-terminated) string + encoded in ASCII or UTF-8. A copy is made; the ptr can be safely + freed. If \"length\" is specified, the string does not have to be + 0-terminated. + + bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be @@ -11293,7 +15336,16 @@ golden "), -("Base","ascii","ascii(::Ptr{UInt8}[, length]) +("Base","ascii","ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must + be valid ASCII characters). + + ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely @@ -11302,7 +15354,16 @@ golden "), -("Base","ascii","ascii(::Ptr{UInt8}[, length]) +("Base","ascii","ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must + be valid ASCII characters). + + ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely @@ -11311,7 +15372,16 @@ golden "), -("Base","ascii","ascii(::Ptr{UInt8}[, length]) +("Base","ascii","ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must + be valid ASCII characters). + + ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely @@ -11320,21 +15390,54 @@ golden "), -("Base","utf8","utf8(s) +("Base","utf8","utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string + encoded in UTF-8. A copy is made; the ptr can be safely freed. If + \"length\" is specified, the string does not have to be + 0-terminated. + + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). "), -("Base","utf8","utf8(s) +("Base","utf8","utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string + encoded in UTF-8. A copy is made; the ptr can be safely freed. If + \"length\" is specified, the string does not have to be + 0-terminated. + + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). "), -("Base","utf8","utf8(s) +("Base","utf8","utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string + encoded in UTF-8. A copy is made; the ptr can be safely freed. If + \"length\" is specified, the string does not have to be + 0-terminated. + + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). @@ -11405,13 +15508,47 @@ golden "), -("Base","isvalid","isvalid(str, i) +("Base","isvalid","isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which + currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" + + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types + currently can be \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of + type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and + \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for + \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values + for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or + \"Vector{UInt32}\" + + isvalid(str, i) Tells whether index \"i\" is valid for the given string "), -("Base","isvalid","isvalid(str, i) +("Base","isvalid","isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which + currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" + + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types + currently can be \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of + type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and + \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for + \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values + for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or + \"Vector{UInt32}\" + + isvalid(str, i) Tells whether index \"i\" is valid for the given string @@ -11650,7 +15787,24 @@ golden "), -("Base","isvalid","isvalid(str, i) +("Base","isvalid","isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which + currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" + + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types + currently can be \"Char\", \"ASCIIString\", \"UTF8String\", + \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of + type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and + \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for + \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values + for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or + \"Vector{UInt32}\" + + isvalid(str, i) Tells whether index \"i\" is valid for the given string @@ -11822,7 +15976,25 @@ golden "), -("Base","utf16","utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) +("Base","utf16","utf16(s) + + Create a UTF-16 string from a byte array, array of \"UInt16\", or + any other string type. (Data must be valid UTF-16. Conversions of + byte arrays check for a byte-order marker in the first two bytes, + and do not include it in the resulting string.) + + Note that the resulting \"UTF16String\" data is terminated by the + NUL codepoint (16-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf16(s)* conversion function. If you have a \"UInt16\" array + \"A\" that is already NUL-terminated valid UTF-16 data, then you + can instead use *UTF16String(A)`* to construct the string without + making a copy of the data and treating the NUL as a terminator + rather than as part of the string. + + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If \"length\" is @@ -11830,7 +16002,25 @@ golden "), -("Base","utf16","utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) +("Base","utf16","utf16(s) + + Create a UTF-16 string from a byte array, array of \"UInt16\", or + any other string type. (Data must be valid UTF-16. Conversions of + byte arrays check for a byte-order marker in the first two bytes, + and do not include it in the resulting string.) + + Note that the resulting \"UTF16String\" data is terminated by the + NUL codepoint (16-bit zero), which is not treated as a character in + the string (so that it is mostly invisible in Julia); this allows + the string to be passed directly to external functions requiring + NUL-terminated data. This NUL is appended automatically by the + *utf16(s)* conversion function. If you have a \"UInt16\" array + \"A\" that is already NUL-terminated valid UTF-16 data, then you + can instead use *UTF16String(A)`* to construct the string without + making a copy of the data and treating the NUL as a terminator + rather than as part of the string. + + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If \"length\" is diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index dcc0697227fe4..644e7bb89ab0d 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -32,7 +32,19 @@ Basic functions Tests whether A or its elements are of type T -.. function:: length(s) +.. function:: length(A) -> Integer + + Returns the number of elements in A + + :: + + length(collection) -> Integer + + For ordered, indexable collections, the maximum index "i" for which "getindex(collection, i)" is valid. For unordered collections, the number of elements. + + :: + + length(s) The number of characters in string "s". @@ -108,12 +120,28 @@ largest range along each dimension. Returns a tuple of the memory strides in each dimension -.. function:: ind2sub(a, index) -> subscripts +.. function:: ind2sub(dims, index) -> subscripts + + Returns a tuple of subscripts into an array with dimensions "dims", corresponding to the linear index "index" + + **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 index "index" -.. function:: ind2sub(a, index) -> subscripts +.. function:: ind2sub(dims, index) -> subscripts + + Returns a tuple of subscripts into an array with dimensions "dims", corresponding to the linear index "index" + + **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 index "index" @@ -131,7 +159,19 @@ Constructors "Array{T}(dims)" constructs an uninitialized dense array with element type "T". "dims" may be a tuple or a series of integer arguments. The syntax "Array(T, dims)" is also available, but deprecated. -.. function:: getindex(collection, key...) +.. function:: getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called with the syntax "Type[]". Element values can be specified using "Type[a,b,c,...]". + + :: + + getindex(A, inds...) + + Returns a subset of array "A" as specified by "inds", where each "ind" may be an "Int", a "Range", or a "Vector". See the manual section on *array indexing* for details. + + :: + + 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, ...)". @@ -141,22 +181,46 @@ Constructors Construct an uninitialized cell array (heterogeneous array). "dims" can be either a tuple or a series of integer arguments. -.. function:: zeros(A) +.. function:: 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. -.. function:: zeros(A) +.. function:: 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. -.. function:: ones(A) +.. function:: 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. -.. function:: ones(A) +.. function:: 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. @@ -198,17 +262,53 @@ Constructors Change the type-interpretation of a block of memory. For example, "reinterpret(Float32, UInt32(7))" interprets the 4 bytes corresponding to "UInt32(7)" as a "Float32". For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. -.. function:: eye(A) +.. function:: eye(n) + + n-by-n identity matrix + + :: + + eye(m, n) + + m-by-n identity matrix + + :: + + eye(A) Constructs an identity matrix of the same dimensions and type as "A". -.. function:: eye(A) +.. function:: eye(n) + + n-by-n identity matrix + + :: + + eye(m, n) + + m-by-n identity matrix + + :: + + eye(A) Constructs an identity matrix of the same dimensions and type as "A". -.. function:: eye(A) +.. function:: eye(n) + + n-by-n identity matrix + + :: + + eye(m, n) + + m-by-n identity matrix + + :: + + eye(A) Constructs an identity matrix of the same dimensions and type as "A". @@ -256,7 +356,19 @@ All mathematical operations and functions are supported for arrays Indexing, Assignment, and Concatenation --------------------------------------- -.. function:: getindex(collection, key...) +.. function:: getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called with the syntax "Type[]". Element values can be specified using "Type[a,b,c,...]". + + :: + + getindex(A, inds...) + + Returns a subset of array "A" as specified by "inds", where each "ind" may be an "Int", a "Range", or a "Vector". See the manual section on *array indexing* for details. + + :: + + 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, ...)". @@ -286,7 +398,13 @@ Indexing, Assignment, and Concatenation Returns a view of array "A" with the given indices like "sub()", but drops all dimensions indexed with scalars. -.. function:: setindex!(collection, value, key...) +.. function:: setindex!(A, X, inds...) + + Store values from array "X" within some subset of "A" as specified by "inds". + + :: + + 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, ...)". @@ -333,12 +451,24 @@ Indexing, Assignment, and Concatenation Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. -.. function:: find(f, A) +.. function:: find(A) + + Return a vector of the linear indexes of the non-zeros in "A" (determined by "A[i]!=0"). A common use of this is to convert a boolean array to an array of indexes of the "true" elements. + + :: + + find(f, A) Return a vector of the linear indexes of "A" where "f" returns true. -.. function:: find(f, A) +.. function:: find(A) + + Return a vector of the linear indexes of the non-zeros in "A" (determined by "A[i]!=0"). A common use of this is to convert a boolean array to an array of indexes of the "true" elements. + + :: + + find(f, A) Return a vector of the linear indexes of "A" where "f" returns true. @@ -353,62 +483,206 @@ Indexing, Assignment, and Concatenation Return a tuple "(I, J, V)" where "I" and "J" are the row and column indexes of the non-zero values in matrix "A", and "V" is a vector of the non-zero values. -.. function:: findfirst(predicate, A) +.. function:: findfirst(A) + + Return the index of the first non-zero value in "A" (determined by "A[i]!=0"). + + :: + + findfirst(A, v) + + Return the index of the first element equal to "v" in "A". + + :: + + findfirst(predicate, A) Return the index of the first element of "A" for which "predicate" returns true. -.. function:: findfirst(predicate, A) +.. function:: findfirst(A) + + Return the index of the first non-zero value in "A" (determined by "A[i]!=0"). + + :: + + findfirst(A, v) + + Return the index of the first element equal to "v" in "A". + + :: + + findfirst(predicate, A) Return the index of the first element of "A" for which "predicate" returns true. -.. function:: findfirst(predicate, A) +.. function:: findfirst(A) + + Return the index of the first non-zero value in "A" (determined by "A[i]!=0"). + + :: + + findfirst(A, v) + + Return the index of the first element equal to "v" in "A". + + :: + + findfirst(predicate, A) Return the index of the first element of "A" for which "predicate" returns true. -.. function:: findlast(predicate, A) +.. function:: findlast(A) + + Return the index of the last non-zero value in "A" (determined by "A[i]!=0"). + + :: + + findlast(A, v) + + Return the index of the last element equal to "v" in "A". + + :: + + findlast(predicate, A) Return the index of the last element of "A" for which "predicate" returns true. -.. function:: findlast(predicate, A) +.. function:: findlast(A) + + Return the index of the last non-zero value in "A" (determined by "A[i]!=0"). + + :: + + findlast(A, v) + + Return the index of the last element equal to "v" in "A". + + :: + + findlast(predicate, A) Return the index of the last element of "A" for which "predicate" returns true. -.. function:: findlast(predicate, A) +.. function:: findlast(A) + + Return the index of the last non-zero value in "A" (determined by "A[i]!=0"). + + :: + + findlast(A, v) + + Return the index of the last element equal to "v" in "A". + + :: + + findlast(predicate, A) Return the index of the last element of "A" for which "predicate" returns true. -.. function:: findnext(A, v, i) +.. function:: findnext(A, i) + + Find the next index >= "i" of a non-zero element of "A", or "0" if not found. + + :: + + findnext(predicate, A, i) + + Find the next index >= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. + + :: + + findnext(A, v, i) Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. -.. function:: findnext(A, v, i) +.. function:: findnext(A, i) + + Find the next index >= "i" of a non-zero element of "A", or "0" if not found. + + :: + + findnext(predicate, A, i) + + Find the next index >= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. + + :: + + findnext(A, v, i) Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. -.. function:: findnext(A, v, i) +.. function:: findnext(A, i) + + Find the next index >= "i" of a non-zero element of "A", or "0" if not found. + + :: + + findnext(predicate, A, i) + + Find the next index >= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. + + :: + + findnext(A, v, i) Find the next index >= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. -.. function:: findprev(A, v, i) +.. function:: findprev(A, i) + + Find the previous index <= "i" of a non-zero element of "A", or 0 if not found. + + :: + + findprev(predicate, A, i) + + Find the previous index <= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. + + :: + + findprev(A, v, i) Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. -.. function:: findprev(A, v, i) +.. function:: findprev(A, i) + + Find the previous index <= "i" of a non-zero element of "A", or 0 if not found. + + :: + + findprev(predicate, A, i) + + Find the previous index <= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. + + :: + + findprev(A, v, i) Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. -.. function:: findprev(A, v, i) +.. function:: findprev(A, i) + + Find the previous index <= "i" of a non-zero element of "A", or 0 if not found. + + :: + + findprev(predicate, A, i) + + Find the previous index <= "i" of an element of "A" for which "predicate" returns true, or "0" if not found. + + :: + + findprev(A, v, i) Find the previous index <= "i" of an element of "A" equal to "v" (using "=="), or "0" if not found. @@ -506,32 +780,68 @@ Array functions Compute differences along vector "F", using "h" as the spacing between points. The default spacing is one. -.. function:: rot180(A, k) +.. function:: rot180(A) + + Rotate matrix "A" 180 degrees. + + :: + + rot180(A, k) Rotate matrix "A" 180 degrees an integer "k" number of times. If "k" is even, this is equivalent to a "copy". -.. function:: rot180(A, k) +.. function:: rot180(A) + + Rotate matrix "A" 180 degrees. + + :: + + rot180(A, k) Rotate matrix "A" 180 degrees an integer "k" number of times. If "k" is even, this is equivalent to a "copy". -.. function:: rotl90(A, k) +.. function:: rotl90(A) + + Rotate matrix "A" left 90 degrees. + + :: + + rotl90(A, k) Rotate matrix "A" left 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". -.. function:: rotl90(A, k) +.. function:: rotl90(A) + + Rotate matrix "A" left 90 degrees. + + :: + + rotl90(A, k) Rotate matrix "A" left 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". -.. function:: rotr90(A, k) +.. function:: rotr90(A) + + Rotate matrix "A" right 90 degrees. + + :: + + rotr90(A, k) Rotate matrix "A" right 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". -.. function:: rotr90(A, k) +.. function:: rotr90(A) + + Rotate matrix "A" right 90 degrees. + + :: + + rotr90(A, k) Rotate matrix "A" right 90 degrees an integer "k" number of times. If "k" is zero or a multiple of four, this is equivalent to a "copy". @@ -574,12 +884,24 @@ Array functions Combinatorics ------------- -.. function:: nthperm(p) +.. function:: nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + + :: + + nthperm(p) Return the "k" that generated permutation "p". Note that "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". -.. function:: nthperm(p) +.. function:: nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + + :: + + nthperm(p) Return the "k" that generated permutation "p". Note that "nthperm(nthperm([1:n], k)) == k" for "1 <= k <= factorial(n)". @@ -656,22 +978,94 @@ Combinatorics Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use "collect(permutations(array))" to get an array of all permutations. -.. function:: partitions(array, m) +.. function:: partitions(n) + + Generate all integer arrays that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n))". + + :: + + partitions(n, m) + + Generate all arrays of "m" integers that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n,m))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n,m))". + + :: + + partitions(array) + + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(array))". + + :: + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". -.. function:: partitions(array, m) +.. function:: partitions(n) + + Generate all integer arrays that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n))". + + :: + + partitions(n, m) + + Generate all arrays of "m" integers that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n,m))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n,m))". + + :: + + partitions(array) + + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(array))". + + :: + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". -.. function:: partitions(array, m) +.. function:: partitions(n) + + Generate all integer arrays that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n))". + + :: + + partitions(n, m) + + Generate all arrays of "m" integers that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n,m))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n,m))". + + :: + + partitions(array) + + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(array))". + + :: + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". -.. function:: partitions(array, m) +.. function:: partitions(n) + + Generate all integer arrays that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n))". + + :: + + partitions(n, m) + + Generate all arrays of "m" integers that sum to "n". Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(n,m))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(n,m))". + + :: + + partitions(array) + + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array))" to get an array of all partitions. The number of partitions to generate can be efficiently computed using "length(partitions(array))". + + :: + + partitions(array, m) Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use "collect(partitions(array,m))" to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using "length(partitions(array,m))". @@ -694,12 +1088,24 @@ BitArrays Performs a bitwise not operation on B. See *~ operator*. -.. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on "src" and put the result into "dest". + + :: + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. -.. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on "src" and put the result into "dest". + + :: + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. @@ -709,12 +1115,24 @@ BitArrays Performs a left rotation operation. -.. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on "src" and put the result into "dest". + + :: + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. -.. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on "src" and put the result into "dest". + + :: + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. @@ -731,17 +1149,47 @@ Sparse Matrices Sparse matrices support much of the same set of operations as dense matrices. The following functions are specific to sparse matrices. -.. function:: sparse(A) +.. function:: sparse(I, J, V[, m, n, combine]) + + Create a sparse matrix "S" of dimensions "m x n" such that "S[I[k], J[k]] = V[k]". The "combine" function is used to combine duplicates. If "m" and "n" are not specified, they are set to "max(I)" and "max(J)" respectively. If the "combine" function is not supplied, duplicates are added by default. + + :: + + sparse(A) Convert an AbstractMatrix "A" into a sparse matrix. -.. function:: sparsevec(A) +.. function:: sparsevec(I, V[, m, combine]) + + Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] = V[k]". Duplicates are combined using the "combine" function, which defaults to "+" if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + + :: + + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size "m x 1" where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + + :: + + sparsevec(A) Convert a dense vector "A" into a sparse matrix of size "m x 1". In julia, sparse vectors are really just sparse matrices with one column. -.. function:: sparsevec(A) +.. function:: sparsevec(I, V[, m, combine]) + + Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] = V[k]". Duplicates are combined using the "combine" function, which defaults to "+" if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + + :: + + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size "m x 1" where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + + :: + + sparsevec(A) Convert a dense vector "A" into a sparse matrix of size "m x 1". In julia, sparse vectors are really just sparse matrices with one column. @@ -751,17 +1199,47 @@ Sparse matrices support much of the same set of operations as dense matrices. Th Returns "true" if "S" is sparse, and "false" otherwise. -.. function:: sparse(A) +.. function:: sparse(I, J, V[, m, n, combine]) + + Create a sparse matrix "S" of dimensions "m x n" such that "S[I[k], J[k]] = V[k]". The "combine" function is used to combine duplicates. If "m" and "n" are not specified, they are set to "max(I)" and "max(J)" respectively. If the "combine" function is not supplied, duplicates are added by default. + + :: + + sparse(A) Convert an AbstractMatrix "A" into a sparse matrix. -.. function:: sparsevec(A) +.. function:: sparsevec(I, V[, m, combine]) + + Create a sparse matrix "S" of size "m x 1" such that "S[I[k]] = V[k]". Duplicates are combined using the "combine" function, which defaults to "+" if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + + :: + + sparsevec(D::Dict[, m]) + + Create a sparse matrix of size "m x 1" where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + + :: + + sparsevec(A) Convert a dense vector "A" into a sparse matrix of size "m x 1". In julia, sparse vectors are really just sparse matrices with one column. -.. function:: full(QRCompactWYQ[, thin=true]) -> Matrix +.. function:: full(S) + + Convert a sparse matrix "S" into a dense matrix. + + :: + + full(F) + + Reconstruct the matrix "A" from the factorization "F=factorize(A)". + + :: + + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a "QRCompactWYQ" object, i.e. in the compact WY format [Bischof1987], to a dense matrix. diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index aa1091e26f8c2..c680710f47c01 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -50,12 +50,24 @@ Getting Around Print information about exported global variables in a module, optionally restricted to those matching "pattern". -.. function:: edit(function[, types]) +.. function:: edit(file::AbstractString[, line]) + + Edit a file optionally providing a line number to edit at. Returns to the julia prompt when you quit the editor. + + :: + + edit(function[, types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. -.. function:: edit(function[, types]) +.. function:: edit(file::AbstractString[, line]) + + Edit a file optionally providing a line number to edit at. Returns to the julia prompt when you quit the editor. + + :: + + edit(function[, types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. @@ -65,12 +77,24 @@ Getting Around Evaluates the arguments to the function call, determines their types, and calls the "edit" function on the resulting expression -.. function:: less(function[, types]) +.. function:: less(file::AbstractString[, line]) + + Show a file using the default pager, optionally providing a starting line number. Returns to the julia prompt when you quit the pager. + + :: + + less(function[, types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. -.. function:: less(function[, types]) +.. function:: less(file::AbstractString[, line]) + + Show a file using the default pager, optionally providing a starting line number. Returns to the julia prompt when you quit the pager. + + :: + + less(function[, types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. @@ -80,12 +104,24 @@ Getting Around Evaluates the arguments to the function call, determines their types, and calls the "less" function on the resulting expression -.. function:: clipboard() -> AbstractString +.. function:: clipboard(x) + + Send a printed form of "x" to the operating system clipboard ("copy"). + + :: + + clipboard() -> AbstractString Return a string with the contents of the operating system clipboard ("paste"). -.. function:: clipboard() -> AbstractString +.. function:: clipboard(x) + + Send a printed form of "x" to the operating system clipboard ("copy"). + + :: + + clipboard() -> AbstractString Return a string with the contents of the operating system clipboard ("paste"). @@ -120,12 +156,28 @@ Getting Around Search documentation for functions related to ``string``. -.. function:: which(symbol) +.. function:: which(f, types) + + Returns the method of "f" (a "Method" object) that would be called for arguments of the given types. + + If "types" is an abstract type, then the method that would be called by "invoke" is returned. + + :: + + which(symbol) Return the module in which the binding for the variable referenced by "symbol" was created. -.. function:: which(symbol) +.. function:: which(f, types) + + Returns the method of "f" (a "Method" object) that would be called for arguments of the given types. + + If "types" is an abstract type, then the method that would be called by "invoke" is returned. + + :: + + which(symbol) Return the module in which the binding for the variable referenced by "symbol" was created. @@ -174,11 +226,11 @@ Getting Around All Objects ----------- -.. function:: ===(x, y) +.. function:: is(x, y) -> Bool - ≡(x, y) + ===(x, y) -> Bool ≡(x, y) -> Bool - See the "is()" operator + Determine whether "x" and "y" are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called "egal". .. function:: isa(x, type) -> Bool @@ -341,14 +393,14 @@ Types Return the supertype of DataType T -.. function:: <:(T1, T2) +.. function:: issubtype(type1, type2) - Subtype operator, equivalent to "issubtype(T1,T2)". + True if and only if all values of "type1" are also of "type2". Can also be written using the "<:" infix operator as "type1 <: type2". -.. function:: <:(T1, T2) +.. function:: issubtype(type1, type2) - Subtype operator, equivalent to "issubtype(T1,T2)". + True if and only if all values of "type1" are also of "type2". Can also be written using the "<:" infix operator as "type1 <: type2". .. function:: subtypes(T::DataType) @@ -381,23 +433,37 @@ Types The largest integer losslessly representable by the given floating- point type -.. function:: sizeof(s::AbstractString) +.. function:: sizeof(type) + + Size, in bytes, of the canonical binary representation of the given type, if any. + + :: + + sizeof(s::AbstractString) The number of bytes in string "s". -.. function:: eps(::DateTime) -> Millisecond +.. function:: eps([type]) - eps(::Date) -> Day + The distance between 1.0 and the next larger representable floating-point value of "type". Only floating-point types are sensible arguments. If "type" is omitted, then "eps(Float64)" is returned. - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" for "Date" values. + :: + eps(x) -.. function:: eps(::DateTime) -> Millisecond + The distance between "x" and the next larger representable floating-point value of the same type as "x". - eps(::Date) -> Day - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" for "Date" values. +.. function:: eps([type]) + + The distance between 1.0 and the next larger representable floating-point value of "type". Only floating-point types are sensible arguments. If "type" is omitted, then "eps(Float64)" is returned. + + :: + + eps(x) + + The distance between "x" and the next larger representable floating-point value of the same type as "x". .. function:: promote_type(type1, type2) @@ -592,12 +658,36 @@ Syntax Generates a gensym symbol for a variable. For example, "@gensym x y" is transformed into "x = gensym("x"); y = gensym("y")". -.. function:: parse(type, str[, base]) +.. function:: parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If "greedy" is true (default), "parse" will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return "Expr(:incomplete, "(error message)")". If "raise" is true (default), syntax errors other than incomplete expressions will raise an error. If "raise" is false, "parse" will return an expression that will raise an error upon evaluation. + + :: + + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If "raise" is true (default), syntax errors will raise an error; otherwise, "parse" will return an expression that will raise an error upon evaluation. + + :: + + parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. -.. function:: parse(type, str[, base]) +.. function:: parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If "greedy" is true (default), "parse" will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return "Expr(:incomplete, "(error message)")". If "raise" is true (default), syntax errors other than incomplete expressions will raise an error. If "raise" is false, "parse" will return an expression that will raise an error upon evaluation. + + :: + + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If "raise" is true (default), syntax errors will raise an error; otherwise, "parse" will return an expression that will raise an error upon evaluation. + + :: + + parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. @@ -610,7 +700,25 @@ Nullables Wrap value "x" in an object of type "Nullable", which indicates whether a value is present. "Nullable(x)" yields a non-empty wrapper, and "Nullable{T}()" yields an empty instance of a wrapper that might contain a value of type "T". -.. function:: get(f::Function, collection, key) +.. function:: get(x) + + Attempt to access the value of the "Nullable" object, "x". Returns the value if it is present; otherwise, throws a "NullException". + + :: + + get(x, y) + + Attempt to access the value of the "Nullable{T}" object, "x". Returns the value if it is present; otherwise, returns "convert(T, y)". + + :: + + 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. + + :: + + 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. @@ -624,7 +732,25 @@ Nullables end -.. function:: get(f::Function, collection, key) +.. function:: get(x) + + Attempt to access the value of the "Nullable" object, "x". Returns the value if it is present; otherwise, throws a "NullException". + + :: + + get(x, y) + + Attempt to access the value of the "Nullable{T}" object, "x". Returns the value if it is present; otherwise, returns "convert(T, y)". + + :: + + 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. + + :: + + 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. @@ -676,19 +802,77 @@ System Determine whether a process has exited. -.. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) +.. function:: kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the process. + + :: + + kill(manager::FooManager, pid::Int, config::WorkerConfig) Implemented by cluster managers. It is called on the master process, by "rmprocs". It should cause the remote worker specified by "pid" to exit. "Base.kill(manager::ClusterManager.....)" executes a remote "exit()" on "pid" -.. function:: open(f::function, args...) +.. function:: open(command, mode::AbstractString="r", stdio=DevNull) + + Start running "command" asynchronously, and return a tuple "(stream,process)". If "mode" is ""r"", then "stream" reads from the process's standard output and "stdio" optionally specifies the process's standard input stream. If "mode" is ""w"", then "stream" writes to the process's standard input and "stdio" optionally specifies the process's standard output stream. + + :: + + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to "open(command, mode, stdio)", but calls "f(stream)" on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by "f". + + :: + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of "mode" correspond to those from "fopen(3)" or Perl "open", and are equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read | +–––+–––––––––––––––––-+ | r+ | read, write | +–––+–––––––––––––––––-+ | w | write, create, truncate | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate | +–––+–––––––––––––––––-+ | a | write, create, append | +–––+–––––––––––––––––-+ | a+ | read, write, create, append | +–––+–––––––––––––––––-+ + + :: + + open(f::function, args...) Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. **Example**: "open(readall, "file.txt")" -.. function:: open(f::function, args...) +.. function:: open(command, mode::AbstractString="r", stdio=DevNull) + + Start running "command" asynchronously, and return a tuple "(stream,process)". If "mode" is ""r"", then "stream" reads from the process's standard output and "stdio" optionally specifies the process's standard input stream. If "mode" is ""w"", then "stream" writes to the process's standard input and "stdio" optionally specifies the process's standard output stream. + + :: + + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to "open(command, mode, stdio)", but calls "f(stream)" on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by "f". + + :: + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of "mode" correspond to those from "fopen(3)" or Perl "open", and are equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read | +–––+–––––––––––––––––-+ | r+ | read, write | +–––+–––––––––––––––––-+ | w | write, create, truncate | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate | +–––+–––––––––––––––––-+ | a | write, create, append | +–––+–––––––––––––––––-+ | a+ | read, write, create, append | +–––+–––––––––––––––––-+ + + :: + + open(f::function, args...) Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. @@ -730,7 +914,19 @@ System Execute "f()" in an environment that is temporarily modified (not replaced as in "setenv") by zero or more ""var"=>val" arguments "kv". "withenv" is generally used via the "withenv(kv...) do ... end" syntax. A value of "nothing" can be used to temporarily unset an environment variable (if it is set). When "withenv" returns, the original environment has been restored. -.. function:: pipe(command; stdin, stdout, stderr, append=false) +.. function:: pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source and destination can be commands, I/O streams, strings, or results of other "pipe" calls. At least one argument must be a command. Strings refer to filenames. When called with more than two arguments, they are chained together from left to right. For example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". This provides a more concise way to specify multi-stage pipelines. + + **Examples**: * "run(pipe(``ls``, ``grep xyz``))" + + :: + + * "run(pipe(`ls`, "out.txt"))" + + * "run(pipe("out.txt", `grep xyz`))" + + pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given "command". Keyword arguments specify which of the command's streams should be redirected. "append" controls whether file output appends to the file. This is a more general version of the 2-argument "pipe" function. "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when "from" is a command, and to "pipe(to, stdin=from)" when "from" is another kind of data source. @@ -741,7 +937,19 @@ System * "run(pipe(`update`, stdout="log.txt", append=true))" -.. function:: pipe(command; stdin, stdout, stderr, append=false) +.. function:: pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source and destination can be commands, I/O streams, strings, or results of other "pipe" calls. At least one argument must be a command. Strings refer to filenames. When called with more than two arguments, they are chained together from left to right. For example "pipe(a,b,c)" is equivalent to "pipe(pipe(a,b),c)". This provides a more concise way to specify multi-stage pipelines. + + **Examples**: * "run(pipe(``ls``, ``grep xyz``))" + + :: + + * "run(pipe(`ls`, "out.txt"))" + + * "run(pipe("out.txt", `grep xyz`))" + + pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given "command". Keyword arguments specify which of the command's streams should be redirected. "append" controls whether file output appends to the file. This is a more general version of the 2-argument "pipe" function. "pipe(from, to)" is equivalent to "pipe(from, stdout=to)" when "from" is a command, and to "pipe(to, stdin=from)" when "from" is another kind of data source. @@ -767,9 +975,9 @@ System Get julia's process ID. -.. function:: time(t::TmStruct) +.. function:: time() - Converts a "TmStruct" struct to a number of seconds since the epoch. + Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. .. function:: time_ns() @@ -1006,12 +1214,24 @@ Errors Events ------ -.. function:: Timer(delay, repeat=0) +.. function:: Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. The callback is passed one argument, the timer object itself. The callback will be invoked after the specified initial delay, and then repeating with the given "repeat" interval. If "repeat" is "0", the timer is only triggered once. Times are in seconds. A timer is stopped and has its resources freed by calling "close" on it. + + :: + + Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling "wait" on the timer object) at a specified interval. -.. function:: Timer(delay, repeat=0) +.. function:: Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. The callback is passed one argument, the timer object itself. The callback will be invoked after the specified initial delay, and then repeating with the given "repeat" interval. If "repeat" is "0", the timer is only triggered once. Times are in seconds. A timer is stopped and has its resources freed by calling "close" on it. + + :: + + Timer(delay, repeat=0) Create a timer that wakes up tasks waiting for it (by calling "wait" on the timer object) at a specified interval. @@ -1074,12 +1294,24 @@ Reflection Determine the module containing a given definition of a generic function. -.. function:: functionloc(m::Method) +.. function:: functionloc(f::Function, types) Returns a tuple "(filename,line)" giving the location of a method definition. + :: + + functionloc(m::Method) + + Returns a tuple "(filename,line)" giving the location of a method definition. + + +.. function:: functionloc(f::Function, types) + + Returns a tuple "(filename,line)" giving the location of a method definition. + + :: -.. function:: functionloc(m::Method) + functionloc(m::Method) Returns a tuple "(filename,line)" giving the location of a method definition. diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index e3363ea4b7db3..77a0bd02a8bee 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -69,26 +69,54 @@ The "unsafe" prefix on this function indicates that no validation is performed on the pointer "p" to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. -.. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) +.. function:: unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy "N" elements from a source pointer to a destination, with no checking. The size of an element is determined by the type of the pointers. + + The "unsafe" prefix on this function indicates that no validation is performed on the pointers "dest" and "src" to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. + + :: + + unsafe_copy!(dest::Array, do, src::Array, so, N) Copy "N" elements from a source array to a destination, starting at offset "so" in the source and "do" in the destination (1-indexed). The "unsafe" prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. -.. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) +.. function:: unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy "N" elements from a source pointer to a destination, with no checking. The size of an element is determined by the type of the pointers. + + The "unsafe" prefix on this function indicates that no validation is performed on the pointers "dest" and "src" to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. + + :: + + unsafe_copy!(dest::Array, do, src::Array, so, N) Copy "N" elements from a source array to a destination, starting at offset "so" in the source and "do" in the destination (1-indexed). The "unsafe" prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. -.. function:: copy!(dest, do, src, so, N) +.. function:: copy!(dest, src) + + Copy all elements from collection "src" to array "dest". Returns "dest". + + :: + + copy!(dest, do, src, so, N) Copy "N" elements from collection "src" starting at offset "so", to array "dest" starting at offset "do". Returns "dest". -.. function:: copy!(dest, do, src, so, N) +.. function:: copy!(dest, src) + + Copy all elements from collection "src" to array "dest". Returns "dest". + + :: + + copy!(dest, do, src, so, N) Copy "N" elements from collection "src" starting at offset "so", to array "dest" starting at offset "do". Returns "dest". diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index f7ee5380aed81..0667609dd2a47 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -130,7 +130,19 @@ General Collections Remove all elements from a "collection". -.. function:: length(s) +.. function:: length(A) -> Integer + + Returns the number of elements in A + + :: + + length(collection) -> Integer + + For ordered, indexable collections, the maximum index "i" for which "getindex(collection, i)" is valid. For unordered collections, the number of elements. + + :: + + length(s) The number of characters in string "s". @@ -188,42 +200,102 @@ Iterable Collections 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". -.. function:: reduce(op, itr) +.. function:: 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. + + :: + + 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". -.. function:: reduce(op, itr) +.. function:: 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. + + :: + + 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". -.. function:: foldl(op, itr) +.. function:: foldl(op, v0, itr) + + Like "reduce()", but with guaranteed left associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: foldl(op, itr) +.. function:: foldl(op, v0, itr) + + Like "reduce()", but with guaranteed left associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: foldr(op, itr) +.. function:: foldr(op, v0, itr) + + Like "reduce()", but with guaranteed right associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: foldr(op, itr) +.. function:: foldr(op, v0, itr) + + Like "reduce()", but with guaranteed right associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: maximum(A, dims) +.. function:: maximum(itr) + + Returns the largest element in a collection. + + :: + + maximum(A, dims) Compute the maximum value of an array over the given dimensions. -.. function:: maximum(A, dims) +.. function:: maximum(itr) + + Returns the largest element in a collection. + + :: + + maximum(A, dims) Compute the maximum value of an array over the given dimensions. @@ -233,12 +305,24 @@ Iterable Collections Compute the maximum value of "A" over the singleton dimensions of "r", and write results to "r". -.. function:: minimum(A, dims) +.. function:: minimum(itr) + + Returns the smallest element in a collection. + + :: + + minimum(A, dims) Compute the minimum value of an array over the given dimensions. -.. function:: minimum(A, dims) +.. function:: minimum(itr) + + Returns the smallest element in a collection. + + :: + + minimum(A, dims) Compute the minimum value of an array over the given dimensions. @@ -263,32 +347,68 @@ Iterable Collections Returns the index of the minimum element in a collection. -.. function:: findmax(A, dims) -> (maxval, index) +.. function:: findmax(itr) -> (x, index) + + Returns the maximum element and its index. + + :: + + findmax(A, dims) -> (maxval, index) For an array input, returns the value and index of the maximum over the given dimensions. -.. function:: findmax(A, dims) -> (maxval, index) +.. function:: findmax(itr) -> (x, index) + + Returns the maximum element and its index. + + :: + + findmax(A, dims) -> (maxval, index) For an array input, returns the value and index of the maximum over the given dimensions. -.. function:: findmin(A, dims) -> (minval, index) +.. function:: findmin(itr) -> (x, index) + + Returns the minimum element and its index. + + :: + + findmin(A, dims) -> (minval, index) For an array input, returns the value and index of the minimum over the given dimensions. -.. function:: findmin(A, dims) -> (minval, index) +.. function:: findmin(itr) -> (x, index) + + Returns the minimum element and its index. + + :: + + findmin(A, dims) -> (minval, index) For an array input, returns the value and index of the minimum over the given dimensions. -.. function:: maxabs(A, dims) +.. function:: maxabs(itr) + + Compute the maximum absolute value of a collection of values. + + :: + + maxabs(A, dims) Compute the maximum absolute values over given dimensions. -.. function:: maxabs(A, dims) +.. function:: maxabs(itr) + + Compute the maximum absolute value of a collection of values. + + :: + + maxabs(A, dims) Compute the maximum absolute values over given dimensions. @@ -298,12 +418,24 @@ Iterable Collections Compute the maximum absolute values over the singleton dimensions of "r", and write values to "r". -.. function:: minabs(A, dims) +.. function:: minabs(itr) + + Compute the minimum absolute value of a collection of values. + + :: + + minabs(A, dims) Compute the minimum absolute values over given dimensions. -.. function:: minabs(A, dims) +.. function:: minabs(itr) + + Compute the minimum absolute value of a collection of values. + + :: + + minabs(A, dims) Compute the minimum absolute values over given dimensions. @@ -313,12 +445,36 @@ Iterable Collections Compute the minimum absolute values over the singleton dimensions of "r", and write values to "r". -.. function:: sum(f, itr) +.. function:: sum(itr) + + Returns the sum of all elements in a collection. + + :: + + sum(A, dims) + + Sum elements of an array over the given dimensions. + + :: + + sum(f, itr) Sum the results of calling function "f" on each element of "itr". -.. function:: sum(f, itr) +.. function:: sum(itr) + + Returns the sum of all elements in a collection. + + :: + + sum(A, dims) + + Sum elements of an array over the given dimensions. + + :: + + sum(f, itr) Sum the results of calling function "f" on each element of "itr". @@ -328,17 +484,41 @@ Iterable Collections Sum elements of "A" over the singleton dimensions of "r", and write results to "r". -.. function:: sum(f, itr) +.. function:: sum(itr) + + Returns the sum of all elements in a collection. + + :: + + sum(A, dims) + + Sum elements of an array over the given dimensions. + + :: + + sum(f, itr) Sum the results of calling function "f" on each element of "itr". -.. function:: sumabs(A, dims) +.. function:: sumabs(itr) + + Sum absolute values of all elements in a collection. This is equivalent to *sum(abs(itr))* but faster. + + :: + + sumabs(A, dims) Sum absolute values of elements of an array over the given dimensions. -.. function:: sumabs(A, dims) +.. function:: sumabs(itr) + + Sum absolute values of all elements in a collection. This is equivalent to *sum(abs(itr))* but faster. + + :: + + sumabs(A, dims) Sum absolute values of elements of an array over the given dimensions. @@ -348,12 +528,24 @@ Iterable Collections Sum absolute values of elements of "A" over the singleton dimensions of "r", and write results to "r". -.. function:: sumabs2(A, dims) +.. function:: sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This is equivalent to *sum(abs2(itr))* but faster. + + :: + + sumabs2(A, dims) Sum squared absolute values of elements of an array over the given dimensions. -.. function:: sumabs2(A, dims) +.. function:: sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This is equivalent to *sum(abs2(itr))* but faster. + + :: + + sumabs2(A, dims) Sum squared absolute values of elements of an array over the given dimensions. @@ -363,12 +555,24 @@ Iterable Collections Sum squared absolute values of elements of "A" over the singleton dimensions of "r", and write results to "r". -.. function:: prod(A, dims) +.. function:: prod(itr) + + Returns the product of all elements of a collection. + + :: + + prod(A, dims) Multiply elements of an array over the given dimensions. -.. function:: prod(A, dims) +.. function:: prod(itr) + + Returns the product of all elements of a collection. + + :: + + prod(A, dims) Multiply elements of an array over the given dimensions. @@ -378,12 +582,36 @@ Iterable Collections Multiply elements of "A" over the singleton dimensions of "r", and write results to "r". -.. function:: any(p, itr) -> Bool +.. function:: any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + :: + + any(A, dims) + + Test whether any values along the given dimensions of an array are true. + + :: + + any(p, itr) -> Bool Determine whether predicate "p" returns true for any elements of "itr". -.. function:: any(p, itr) -> Bool +.. function:: any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + :: + + any(A, dims) + + Test whether any values along the given dimensions of an array are true. + + :: + + any(p, itr) -> Bool Determine whether predicate "p" returns true for any elements of "itr". @@ -393,7 +621,19 @@ Iterable Collections Test whether any values in "A" along the singleton dimensions of "r" are true, and write results to "r". -.. function:: all(p, itr) -> Bool +.. function:: all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + + :: + + all(A, dims) + + Test whether all values along the given dimensions of an array are true. + + :: + + all(p, itr) -> Bool Determine whether predicate "p" returns true for all elements of "itr". @@ -403,7 +643,19 @@ Iterable Collections true -.. function:: all(p, itr) -> Bool +.. function:: all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + + :: + + all(A, dims) + + Test whether all values along the given dimensions of an array are true. + + :: + + all(p, itr) -> Bool Determine whether predicate "p" returns true for all elements of "itr". @@ -423,12 +675,36 @@ Iterable Collections Count the number of elements in "itr" for which predicate "p" returns true. -.. function:: any(p, itr) -> Bool +.. function:: any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + :: + + any(A, dims) + + Test whether any values along the given dimensions of an array are true. + + :: + + any(p, itr) -> Bool Determine whether predicate "p" returns true for any elements of "itr". -.. function:: all(p, itr) -> Bool +.. function:: all(itr) -> Bool + + Test whether all elements of a boolean collection are true. + + :: + + all(A, dims) + + Test whether all values along the given dimensions of an array are true. + + :: + + all(p, itr) -> Bool Determine whether predicate "p" returns true for all elements of "itr". @@ -457,42 +733,108 @@ Iterable Collections 33 -.. function:: map!(function, destination, collection...) +.. function:: map!(function, collection) + + In-place version of "map()". + + :: + + 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. -.. function:: map!(function, destination, collection...) +.. function:: map!(function, collection) + + In-place version of "map()". + + :: + + 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. -.. function:: mapreduce(f, op, itr) +.. function:: 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. + + :: + + mapreduce(f, op, itr) Like "mapreduce(f, op, v0, itr)". In general, this cannot be used with empty collections (see "reduce(op, itr)"). -.. function:: mapreduce(f, op, itr) +.. function:: 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. + + :: + + mapreduce(f, op, itr) Like "mapreduce(f, op, v0, itr)". In general, this cannot be used with empty collections (see "reduce(op, itr)"). -.. function:: mapfoldl(f, op, itr) +.. function:: mapfoldl(f, op, v0, itr) + + Like "mapreduce()", but with guaranteed left associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: mapfoldl(f, op, itr) +.. function:: mapfoldl(f, op, v0, itr) + + Like "mapreduce()", but with guaranteed left associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: mapfoldr(f, op, itr) +.. function:: mapfoldr(f, op, v0, itr) + + Like "mapreduce()", but with guaranteed right associativity. "v0" will be used exactly once. + + :: + + 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)"). -.. function:: mapfoldr(f, op, itr) +.. function:: mapfoldr(f, op, v0, itr) + + Like "mapreduce()", but with guaranteed right associativity. "v0" will be used exactly once. + + :: + + 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)"). @@ -512,17 +854,37 @@ Iterable Collections Get the step size of a "Range" object. -.. function:: collect(element_type, collection) +.. function:: collect(collection) + + Return an array of all items in a collection. For associative collections, returns (key, value) tuples. + + :: + + collect(element_type, collection) Return an array of type "Array{element_type,1}" of all items in a collection. -.. function:: collect(element_type, collection) +.. function:: collect(collection) + + Return an array of all items in a collection. For associative collections, returns (key, value) tuples. + + :: + + collect(element_type, collection) Return an array of type "Array{element_type,1}" of all items in a collection. -.. function:: issubset(A, S) -> Bool +.. function:: issubset(a, b) + + ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool + + Determine whether every element of "a" is also in "b", using "in()". + + :: + + issubset(A, S) -> Bool ⊆(A, S) -> Bool @@ -542,12 +904,30 @@ Iterable Collections Indexable Collections --------------------- -.. function:: getindex(collection, key...) +.. function:: getindex(type[, elements...]) + + Construct a 1-d array of the specified type. This is usually called with the syntax "Type[]". Element values can be specified using "Type[a,b,c,...]". + + :: + + getindex(A, inds...) + + Returns a subset of array "A" as specified by "inds", where each "ind" may be an "Int", a "Range", or a "Vector". See the manual section on *array indexing* for details. + + :: + + 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, ...)". -.. function:: setindex!(collection, value, key...) +.. function:: setindex!(A, X, inds...) + + Store values from array "X" within some subset of "A" as specified by "inds". + + :: + + 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, ...)". @@ -615,7 +995,25 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if Determine whether a collection has a mapping for a given key. -.. function:: get(f::Function, collection, key) +.. function:: get(x) + + Attempt to access the value of the "Nullable" object, "x". Returns the value if it is present; otherwise, throws a "NullException". + + :: + + get(x, y) + + Attempt to access the value of the "Nullable{T}" object, "x". Returns the value if it is present; otherwise, returns "convert(T, y)". + + :: + + 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. + + :: + + 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. @@ -629,7 +1027,25 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if end -.. function:: get(f::Function, collection, key) +.. function:: get(x) + + Attempt to access the value of the "Nullable" object, "x". Returns the value if it is present; otherwise, throws a "NullException". + + :: + + get(x, y) + + Attempt to access the value of the "Nullable{T}" object, "x". Returns the value if it is present; otherwise, returns "convert(T, y)". + + :: + + 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. + + :: + + 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. @@ -646,7 +1062,13 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if time() end -.. function:: get!(f::Function, collection, key) +.. function:: 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". + + :: + + 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()". @@ -660,7 +1082,13 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if end -.. function:: get!(f::Function, collection, key) +.. function:: 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". + + :: + + 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()". @@ -687,7 +1115,13 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if Delete the mapping for the given key in a collection, and return the collection. -.. function:: pop!(collection) -> item +.. function:: 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. + + :: + + pop!(collection) -> item Remove the last item in "collection" and return it. @@ -824,17 +1258,53 @@ Set-Like Collections Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. -.. function:: symdiff!(s1, s2) +.. function:: symdiff!(s, n) + + The set "s" is destructively modified to toggle the inclusion of integer "n". + + :: + + symdiff!(s, itr) + + For each element in "itr", destructively toggle its inclusion in set "s". + + :: + + symdiff!(s1, s2) Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". -.. function:: symdiff!(s1, s2) +.. function:: symdiff!(s, n) + + The set "s" is destructively modified to toggle the inclusion of integer "n". + + :: + + symdiff!(s, itr) + + For each element in "itr", destructively toggle its inclusion in set "s". + + :: + + symdiff!(s1, s2) Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". -.. function:: symdiff!(s1, s2) +.. function:: symdiff!(s, n) + + The set "s" is destructively modified to toggle the inclusion of integer "n". + + :: + + symdiff!(s, itr) + + For each element in "itr", destructively toggle its inclusion in set "s". + + :: + + symdiff!(s1, s2) Construct the symmetric difference of sets "s1" and "s2", storing the result in "s1". @@ -854,7 +1324,15 @@ Set-Like Collections Intersects sets "s1" and "s2" and overwrites the set "s1" with the result. If needed, "s1" will be expanded to the size of "s2". -.. function:: issubset(A, S) -> Bool +.. function:: issubset(a, b) + + ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool + + Determine whether every element of "a" is also in "b", using "in()". + + :: + + issubset(A, S) -> Bool ⊆(A, S) -> Bool @@ -891,7 +1369,13 @@ Dequeues 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])". -.. function:: pop!(collection) -> item +.. function:: 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. + + :: + + pop!(collection) -> item Remove the last item in "collection" and return it. @@ -977,7 +1461,21 @@ Dequeues 1 -.. function:: deleteat!(collection, itr) +.. function:: deleteat!(collection, index) + + Remove the item at the given "index" and return the modified "collection". 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 + + deleteat!(collection, itr) Remove the items at the indices given by "itr", and return the modified "collection". Subsequent items are shifted to fill the resulting gap. "itr" must be sorted and unique. @@ -994,7 +1492,21 @@ Dequeues in deleteat! at array.jl:631 -.. function:: deleteat!(collection, itr) +.. function:: deleteat!(collection, index) + + Remove the item at the given "index" and return the modified "collection". 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 + + deleteat!(collection, itr) Remove the items at the indices given by "itr", and return the modified "collection". Subsequent items are shifted to fill the resulting gap. "itr" must be sorted and unique. @@ -1011,7 +1523,52 @@ Dequeues in deleteat! at array.jl:631 -.. function:: splice!(collection, range[, replacement]) -> items +.. function:: splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. Subsequent items are shifted down 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)". + + :: + + splice!(collection, range[, replacement]) -> items Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down to fill the resulting gap. If specified, replacement values from an ordered collection will be spliced in place of the removed items. @@ -1034,7 +1591,52 @@ Dequeues -1 -.. function:: splice!(collection, range[, replacement]) -> items +.. function:: splice!(collection, index[, replacement]) -> item + + Remove the item at the given index, and return the removed item. Subsequent items are shifted down 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)". + + :: + + splice!(collection, range[, replacement]) -> items Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down to fill the resulting gap. If specified, replacement values from an ordered collection will be spliced in place of the removed items. diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index 49be03c0b8f98..f030bc103d17e 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -47,27 +47,227 @@ to use all other ``Dates`` functions, you'll need to prefix each function call w alternatively, you could call ``using Dates`` to bring all exported functions into ``Main`` to be used without the ``Dates.`` prefix. -.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime +.. function:: DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it according to the proleptic Gregorian calendar. + + :: + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to "Int64". + + :: + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be in any order. DateTime parts not provided will default to the value of "Dates.default(period)". + + :: + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the provided "y, m, d..." arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that "f::Function" is never satisfied). + + :: + + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, second, and millisecond parts of the new "DateTime" are assumed to be zero. + + :: + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string following the pattern given in the "format" string. The following codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code | Matches | Comment | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "y" | 1996, 96 | Returns year of 1996, 0096 | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "m" | 1, 01 | Matches 1 or 2-digit months | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "u" | Jan | Matches abbreviated months according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "U" | January | Matches full month names according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "d" | 1, 01 | Matches 1 or 2-digit days | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "H" | 00 | Matches hours | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "M" | 00 | Matches minutes | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "S" | 00 | Matches seconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "s" | .500 | Matches milliseconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "e" | Mon, Tues | Matches abbreviated days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "E" | Monday | Matches full name days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "yyyymmdd" | 19960101 | Matches fixed-width year, month, and day | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between date and time slots. So a "dt" string of "1996-01-15T00:00:00.0" would have a "format" string like "y-m-dTH:M:S.s". + + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. -.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime +.. function:: DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it according to the proleptic Gregorian calendar. + + :: + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to "Int64". + + :: + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be in any order. DateTime parts not provided will default to the value of "Dates.default(period)". + + :: + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the provided "y, m, d..." arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that "f::Function" is never satisfied). + + :: + + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, second, and millisecond parts of the new "DateTime" are assumed to be zero. + + :: + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string following the pattern given in the "format" string. The following codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code | Matches | Comment | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "y" | 1996, 96 | Returns year of 1996, 0096 | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "m" | 1, 01 | Matches 1 or 2-digit months | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "u" | Jan | Matches abbreviated months according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "U" | January | Matches full month names according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "d" | 1, 01 | Matches 1 or 2-digit days | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "H" | 00 | Matches hours | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "M" | 00 | Matches minutes | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "S" | 00 | Matches seconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "s" | .500 | Matches milliseconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "e" | Mon, Tues | Matches abbreviated days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "E" | Monday | Matches full name days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "yyyymmdd" | 19960101 | Matches fixed-width year, month, and day | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between date and time slots. So a "dt" string of "1996-01-15T00:00:00.0" would have a "format" string like "y-m-dTH:M:S.s". + + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. -.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime +.. function:: DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it according to the proleptic Gregorian calendar. + + :: + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to "Int64". + + :: + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be in any order. DateTime parts not provided will default to the value of "Dates.default(period)". + + :: + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the provided "y, m, d..." arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that "f::Function" is never satisfied). + + :: + + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, second, and millisecond parts of the new "DateTime" are assumed to be zero. + + :: + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string following the pattern given in the "format" string. The following codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code | Matches | Comment | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "y" | 1996, 96 | Returns year of 1996, 0096 | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "m" | 1, 01 | Matches 1 or 2-digit months | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "u" | Jan | Matches abbreviated months according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "U" | January | Matches full month names according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "d" | 1, 01 | Matches 1 or 2-digit days | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "H" | 00 | Matches hours | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "M" | 00 | Matches minutes | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "S" | 00 | Matches seconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "s" | .500 | Matches milliseconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "e" | Mon, Tues | Matches abbreviated days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "E" | Monday | Matches full name days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "yyyymmdd" | 19960101 | Matches fixed-width year, month, and day | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between date and time slots. So a "dt" string of "1996-01-15T00:00:00.0" would have a "format" string like "y-m-dTH:M:S.s". + + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. -.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime +.. function:: DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it according to the proleptic Gregorian calendar. + + :: + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to "Int64". + + :: + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be in any order. DateTime parts not provided will default to the value of "Dates.default(period)". + + :: + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the provided "y, m, d..." arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that "f::Function" is never satisfied). + + :: + + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, second, and millisecond parts of the new "DateTime" are assumed to be zero. + + :: + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string following the pattern given in the "format" string. The following codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code | Matches | Comment | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "y" | 1996, 96 | Returns year of 1996, 0096 | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "m" | 1, 01 | Matches 1 or 2-digit months | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "u" | Jan | Matches abbreviated months according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "U" | January | Matches full month names according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "d" | 1, 01 | Matches 1 or 2-digit days | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "H" | 00 | Matches hours | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "M" | 00 | Matches minutes | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "S" | 00 | Matches seconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "s" | .500 | Matches milliseconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "e" | Mon, Tues | Matches abbreviated days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "E" | Monday | Matches full name days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "yyyymmdd" | 19960101 | Matches fixed-width year, month, and day | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between date and time slots. So a "dt" string of "1996-01-15T00:00:00.0" would have a "format" string like "y-m-dTH:M:S.s". + + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. -.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime +.. function:: DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it according to the proleptic Gregorian calendar. + + :: + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to "Int64". + + :: + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be in any order. DateTime parts not provided will default to the value of "Dates.default(period)". + + :: + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the provided "y, m, d..." arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that "f::Function" is never satisfied). + + :: + + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, second, and millisecond parts of the new "DateTime" are assumed to be zero. + + :: + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string following the pattern given in the "format" string. The following codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code | Matches | Comment | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "y" | 1996, 96 | Returns year of 1996, 0096 | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "m" | 1, 01 | Matches 1 or 2-digit months | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "u" | Jan | Matches abbreviated months according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "U" | January | Matches full month names according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "d" | 1, 01 | Matches 1 or 2-digit days | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "H" | 00 | Matches hours | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "M" | 00 | Matches minutes | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "S" | 00 | Matches seconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "s" | .500 | Matches milliseconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "e" | Mon, Tues | Matches abbreviated days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "E" | Monday | Matches full name days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "yyyymmdd" | 19960101 | Matches fixed-width year, month, and day | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between date and time slots. So a "dt" string of "1996-01-15T00:00:00.0" would have a "format" string like "y-m-dTH:M:S.s". + + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. @@ -76,56 +276,328 @@ alternatively, you could call ``using Dates`` to bring all exported functions in Construct a date formatting object that can be passed repeatedly for parsing similarly formatted date strings. ``format`` is a format string in the form described above (e.g. ``"yyyy-mm-dd"``). -.. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime +.. function:: DateTime + + "DateTime" wraps a "UTInstant{Millisecond}" and interprets it according to the proleptic Gregorian calendar. + + :: + + DateTime(y[, m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to "Int64". + + :: + + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by "Period" type parts. Arguments may be in any order. DateTime parts not provided will default to the value of "Dates.default(period)". + + :: + + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the provided "y, m, d..." arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that "f::Function" is never satisfied). + + :: + + DateTime(dt::Date) -> DateTime + + Converts a "Date" type to a "DateTime". The hour, minute, second, and millisecond parts of the new "DateTime" are assumed to be zero. + + :: + + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the "dt" date string following the pattern given in the "format" string. The following codes can be used for constructing format strings: + + +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code | Matches | Comment | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "y" | 1996, 96 | Returns year of 1996, 0096 | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "m" | 1, 01 | Matches 1 or 2-digit months | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "u" | Jan | Matches abbreviated months according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "U" | January | Matches full month names according to the "locale" keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "d" | 1, 01 | Matches 1 or 2-digit days | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "H" | 00 | Matches hours | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "M" | 00 | Matches minutes | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "S" | 00 | Matches seconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "s" | .500 | Matches milliseconds | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "e" | Mon, Tues | Matches abbreviated days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "E" | Monday | Matches full name days of the week | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | "yyyymmdd" | 19960101 | Matches fixed-width year, month, and day | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ + + All characters not listed above are treated as delimiters between date and time slots. So a "dt" string of "1996-01-15T00:00:00.0" would have a "format" string like "y-m-dTH:M:S.s". + + :: + + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a "DateTime", but passes a "DateFormat" object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a "DateFormat" object then use this method for parsing. -.. function:: Date(dt::AbstractString, df::DateFormat) -> Date +.. function:: Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to the proleptic Gregorian calendar. + + :: + + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible to "Int64". + + :: + + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in any order. Date parts not provided will default to the value of "Dates.default(period)". + + :: + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the provided "y, m" arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that "f::Function" is never satisfied). + + :: + + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, second, and millisecond parts of the "DateTime" are truncated, so only the year, month and day parts are used in construction. + + :: + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the pattern given in the "format" string. Follows the same conventions as "DateTime" above. + + :: + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string "dt" using a "DateFormat" object "df". -.. function:: Date(dt::AbstractString, df::DateFormat) -> Date +.. function:: Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to the proleptic Gregorian calendar. + + :: + + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible to "Int64". + + :: + + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in any order. Date parts not provided will default to the value of "Dates.default(period)". + + :: + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the provided "y, m" arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that "f::Function" is never satisfied). + + :: + + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, second, and millisecond parts of the "DateTime" are truncated, so only the year, month and day parts are used in construction. + + :: + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the pattern given in the "format" string. Follows the same conventions as "DateTime" above. + + :: + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string "dt" using a "DateFormat" object "df". -.. function:: Date(dt::AbstractString, df::DateFormat) -> Date +.. function:: Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to the proleptic Gregorian calendar. + + :: + + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible to "Int64". + + :: + + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in any order. Date parts not provided will default to the value of "Dates.default(period)". + + :: + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the provided "y, m" arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that "f::Function" is never satisfied). + + :: + + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, second, and millisecond parts of the "DateTime" are truncated, so only the year, month and day parts are used in construction. + + :: + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the pattern given in the "format" string. Follows the same conventions as "DateTime" above. + + :: + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string "dt" using a "DateFormat" object "df". -.. function:: Date(dt::AbstractString, df::DateFormat) -> Date +.. function:: Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to the proleptic Gregorian calendar. + + :: + + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible to "Int64". + + :: + + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in any order. Date parts not provided will default to the value of "Dates.default(period)". + + :: + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the provided "y, m" arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that "f::Function" is never satisfied). + + :: + + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, second, and millisecond parts of the "DateTime" are truncated, so only the year, month and day parts are used in construction. + + :: + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the pattern given in the "format" string. Follows the same conventions as "DateTime" above. + + :: + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string "dt" using a "DateFormat" object "df". -.. function:: Date(dt::AbstractString, df::DateFormat) -> Date +.. function:: Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to the proleptic Gregorian calendar. + + :: + + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible to "Int64". + + :: + + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in any order. Date parts not provided will default to the value of "Dates.default(period)". + + :: + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the provided "y, m" arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that "f::Function" is never satisfied). + + :: + + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, second, and millisecond parts of the "DateTime" are truncated, so only the year, month and day parts are used in construction. + + :: + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the pattern given in the "format" string. Follows the same conventions as "DateTime" above. + + :: + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string "dt" using a "DateFormat" object "df". -.. function:: Date(dt::AbstractString, df::DateFormat) -> Date +.. function:: Date + + "Date" wraps a "UTInstant{Day}" and interprets it according to the proleptic Gregorian calendar. + + :: + + Date(y[, m, d]) -> Date + + Construct a "Date" type by parts. Arguments must be convertible to "Int64". + + :: + + Date(period::Period...) -> Date + + Constuct a Date type by "Period" type parts. Arguments may be in any order. Date parts not provided will default to the value of "Dates.default(period)". + + :: + + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the provided "y, m" arguments, and will be adjusted until "f::Function" returns true. The step size in adjusting can be provided manually through the "step" keyword. If "negate=true", then the adjusting will stop when "f::Function" returns false instead of true. "limit" provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that "f::Function" is never satisfied). + + :: + + Date(dt::DateTime) -> Date + + Converts a "DateTime" type to a "Date". The hour, minute, second, and millisecond parts of the "DateTime" are truncated, so only the year, month and day parts are used in construction. + + :: + + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a "dt" date string following the pattern given in the "format" string. Follows the same conventions as "DateTime" above. + + :: + + Date(dt::AbstractString, df::DateFormat) -> Date Parse a date from a date string "dt" using a "DateFormat" object "df". -.. function:: now(::Type{UTC}) -> DateTime +.. function:: now() -> DateTime + + Returns a DateTime corresponding to the user's system time including the system timezone locale. + + :: + + now(::Type{UTC}) -> DateTime Returns a DateTime corresponding to the user's system time as UTC/GMT. -.. function:: now(::Type{UTC}) -> DateTime +.. function:: now() -> DateTime + + Returns a DateTime corresponding to the user's system time including the system timezone locale. + + :: + + now(::Type{UTC}) -> DateTime Returns a DateTime corresponding to the user's system time as UTC/GMT. -.. function:: eps(::DateTime) -> Millisecond +.. function:: eps([type]) - eps(::Date) -> Day + The distance between 1.0 and the next larger representable floating-point value of "type". Only floating-point types are sensible arguments. If "type" is omitted, then "eps(Float64)" is returned. - Returns "Millisecond(1)" for "DateTime" values and "Day(1)" for "Date" values. + :: + + eps(x) + + The distance between "x" and the next larger representable floating-point value of the same type as "x". Accessor Functions @@ -140,6 +612,20 @@ Accessor Functions .. function:: Year(v) + :: + + Year + + Year(dt::TimeType) -> Year + + Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week Day(dt::TimeType) -> Day Hour(dt::TimeType) -> Hour Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second Millisecond(dt::TimeType) -> Millisecond + + Return the field part of a Date or DateTime as a "Period" type. + + :: + + Year(v) + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) Construct a "Period" type with the given "v" value. Input must be losslessly convertible to an "Int64". @@ -280,12 +766,24 @@ Adjuster Functions Adjusts "dt" to the last day of its quarter. -.. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType +.. function:: tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts "dt" to the next day of week corresponding to "dow" with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows the current "dt" to be considered as the next "dow", allowing for no adjustment to occur. + + :: + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. -.. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType +.. function:: toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts "dt" to the previous day of week corresponding to "dow" with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows the current "dt" to be considered as the previous "dow", allowing for no adjustment to occur. + + :: + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. @@ -300,12 +798,24 @@ Adjuster Functions Adjusts "dt" to the last "dow" of its month. Alternatively, "of=Year" will adjust to the last "dow" of the year. -.. function:: tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType +.. function:: tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts "dt" to the next day of week corresponding to "dow" with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows the current "dt" to be considered as the next "dow", allowing for no adjustment to occur. + + :: + + tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. -.. function:: toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType +.. function:: toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType + + Adjusts "dt" to the previous day of week corresponding to "dow" with "1 = Monday, 2 = Tuesday, etc". Setting "same=true" allows the current "dt" to be considered as the previous "dow", allowing for no adjustment to occur. + + :: + + toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType Adjusts "dt" by iterating at most "limit" iterations by "step" increments until "func" returns true. "func" must take a single "TimeType" argument and return a "Bool". "same" allows "dt" to be considered in satisfying "func". "negate" will make the adjustment process terminate when "func" returns false instead of true. @@ -323,6 +833,20 @@ Periods .. function:: Year(v) + :: + + Year + + Year(dt::TimeType) -> Year + + Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week Day(dt::TimeType) -> Day Hour(dt::TimeType) -> Hour Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second Millisecond(dt::TimeType) -> Millisecond + + Return the field part of a Date or DateTime as a "Period" type. + + :: + + Year(v) + Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) Construct a "Period" type with the given "v" value. Input must be losslessly convertible to an "Int64". diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index e27ce87709d55..533142175c277 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -10,12 +10,24 @@ Get the current working directory. -.. function:: cd(f[, dir]) +.. function:: cd(dir::AbstractString) + + Set the current working directory. + + :: + + cd(f[, dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. -.. function:: cd(f[, dir]) +.. function:: cd(dir::AbstractString) + + Set the current working directory. + + :: + + cd(f[, dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 6b365d4d096a7..90f805ff6db2f 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -19,43 +19,193 @@ General I/O Global variable referring to the standard input stream. -.. function:: open(f::function, args...) +.. function:: open(command, mode::AbstractString="r", stdio=DevNull) + + Start running "command" asynchronously, and return a tuple "(stream,process)". If "mode" is ""r"", then "stream" reads from the process's standard output and "stdio" optionally specifies the process's standard input stream. If "mode" is ""w"", then "stream" writes to the process's standard input and "stdio" optionally specifies the process's standard output stream. + + :: + + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to "open(command, mode, stdio)", but calls "f(stream)" on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by "f". + + :: + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of "mode" correspond to those from "fopen(3)" or Perl "open", and are equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read | +–––+–––––––––––––––––-+ | r+ | read, write | +–––+–––––––––––––––––-+ | w | write, create, truncate | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate | +–––+–––––––––––––––––-+ | a | write, create, append | +–––+–––––––––––––––––-+ | a+ | read, write, create, append | +–––+–––––––––––––––––-+ + + :: + + open(f::function, args...) Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. **Example**: "open(readall, "file.txt")" -.. function:: open(f::function, args...) +.. function:: open(command, mode::AbstractString="r", stdio=DevNull) + + Start running "command" asynchronously, and return a tuple "(stream,process)". If "mode" is ""r"", then "stream" reads from the process's standard output and "stdio" optionally specifies the process's standard input stream. If "mode" is ""w"", then "stream" writes to the process's standard input and "stdio" optionally specifies the process's standard output stream. + + :: + + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to "open(command, mode, stdio)", but calls "f(stream)" on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by "f". + + :: + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of "mode" correspond to those from "fopen(3)" or Perl "open", and are equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read | +–––+–––––––––––––––––-+ | r+ | read, write | +–––+–––––––––––––––––-+ | w | write, create, truncate | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate | +–––+–––––––––––––––––-+ | a | write, create, append | +–––+–––––––––––––––––-+ | a+ | read, write, create, append | +–––+–––––––––––––––––-+ + + :: + + open(f::function, args...) Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. **Example**: "open(readall, "file.txt")" -.. function:: open(f::function, args...) +.. function:: open(command, mode::AbstractString="r", stdio=DevNull) + + Start running "command" asynchronously, and return a tuple "(stream,process)". If "mode" is ""r"", then "stream" reads from the process's standard output and "stdio" optionally specifies the process's standard input stream. If "mode" is ""w"", then "stream" writes to the process's standard input and "stdio" optionally specifies the process's standard output stream. + + :: + + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to "open(command, mode, stdio)", but calls "f(stream)" on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by "f". + + :: + + open(file_name[, read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + + open(file_name[, mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of "mode" correspond to those from "fopen(3)" or Perl "open", and are equivalent to setting the following boolean groups: + + +–––+–––––––––––––––––-+ | r | read | +–––+–––––––––––––––––-+ | r+ | read, write | +–––+–––––––––––––––––-+ | w | write, create, truncate | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate | +–––+–––––––––––––––––-+ | a | write, create, append | +–––+–––––––––––––––––-+ | a+ | read, write, create, append | +–––+–––––––––––––––––-+ + + :: + + open(f::function, args...) Apply the function "f" to the result of "open(args...)" and close the resulting file descriptor upon completion. **Example**: "open(readall, "file.txt")" -.. function:: IOBuffer([data][, readable, writable[, maxsize]]) +.. function:: IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. -.. function:: IOBuffer([data][, readable, writable[, maxsize]]) +.. function:: IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. -.. function:: IOBuffer([data][, readable, writable[, maxsize]]) +.. function:: IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. -.. function:: IOBuffer([data][, readable, writable[, maxsize]]) +.. function:: IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + + IOBuffer([data][, readable, writable[, maxsize]]) Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. @@ -90,12 +240,24 @@ General I/O Write the canonical binary representation of a value to the given stream. -.. function:: read(stream, type, dims) +.. function:: read(stream, type) + + Read a value of the given type from a stream, in canonical binary representation. + + :: + + read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. "dims" is either a tuple or a series of integer arguments specifying the size of "Array" to return. -.. function:: read(stream, type, dims) +.. function:: read(stream, type) + + Read a value of the given type from a stream, in canonical binary representation. + + :: + + read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. "dims" is either a tuple or a series of integer arguments specifying the size of "Array" to return. @@ -218,12 +380,24 @@ General I/O Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous *File*'s and *IOStream*'s not to any of the asynchronous streams. -.. function:: redirect_stdout(stream) +.. function:: redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be replaced elsewhere. + + :: + + redirect_stdout(stream) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. -.. function:: redirect_stdout(stream) +.. function:: redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be replaced elsewhere. + + :: + + redirect_stdout(stream) Replace STDOUT by stream for all C and julia level output to STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. @@ -258,12 +432,24 @@ General I/O Read io until the end of the stream/file and count the number of non-empty lines. To specify a file pass the filename as the first argument. EOL markers other than '\n' are supported by passing them as the second argument. -.. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) +.. function:: PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. + + :: + + PipeBuffer(data::Vector{UInt8}[, maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. -.. function:: PipeBuffer(data::Vector{UInt8}[, maxsize]) +.. function:: PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. + + :: + + PipeBuffer(data::Vector{UInt8}[, maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. @@ -351,12 +537,24 @@ Text I/O Show all structure of a value, including all fields of objects. -.. function:: readall(filename::AbstractString) +.. function:: readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + + :: + + readall(filename::AbstractString) Open "filename", read the entire contents as a string, then close the file. Equivalent to "open(readall, filename)". -.. function:: readall(filename::AbstractString) +.. function:: readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + + :: + + readall(filename::AbstractString) Open "filename", read the entire contents as a string, then close the file. Equivalent to "open(readall, filename)". @@ -381,32 +579,320 @@ Text I/O Create an iterable object that will yield each line from a stream. -.. function:: readdlm(source; options...) +.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by "eol") gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, with any non-numeric elements as "NaN" for floating-point types, or zero. Other useful values of "T" include "ASCIIString", "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as header and the tuple "(data_cells, header_cells)" is returned instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be ignored. + + If "use_mmap" is "true", the file specified by "source" is memory mapped for potential speedups. Default is "true" except on Windows. On Windows, you may want to specify "true" if the file is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. + + :: + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + + :: + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". + + :: + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source; options...) +.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by "eol") gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, with any non-numeric elements as "NaN" for floating-point types, or zero. Other useful values of "T" include "ASCIIString", "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as header and the tuple "(data_cells, header_cells)" is returned instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be ignored. + + If "use_mmap" is "true", the file specified by "source" is memory mapped for potential speedups. Default is "true" except on Windows. On Windows, you may want to specify "true" if the file is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. + + :: + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + + :: + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". + + :: + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source; options...) +.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by "eol") gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, with any non-numeric elements as "NaN" for floating-point types, or zero. Other useful values of "T" include "ASCIIString", "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as header and the tuple "(data_cells, header_cells)" is returned instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be ignored. + + If "use_mmap" is "true", the file specified by "source" is memory mapped for potential speedups. Default is "true" except on Windows. On Windows, you may want to specify "true" if the file is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. + + :: + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + + :: + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". + + :: + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source; options...) +.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by "eol") gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, with any non-numeric elements as "NaN" for floating-point types, or zero. Other useful values of "T" include "ASCIIString", "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as header and the tuple "(data_cells, header_cells)" is returned instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be ignored. + + If "use_mmap" is "true", the file specified by "source" is memory mapped for potential speedups. Default is "true" except on Windows. On Windows, you may want to specify "true" if the file is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. + + :: + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + + :: + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". + + :: + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source; options...) +.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by "eol") gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, with any non-numeric elements as "NaN" for floating-point types, or zero. Other useful values of "T" include "ASCIIString", "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as header and the tuple "(data_cells, header_cells)" is returned instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be ignored. + + If "use_mmap" is "true", the file specified by "source" is memory mapped for potential speedups. Default is "true" except on Windows. On Windows, you may want to specify "true" if the file is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. + + :: + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + + :: + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". + + :: + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. -.. function:: readdlm(source; options...) +.. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by "eol") gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If "T" is a numeric type, the result is an array of that type, with any non-numeric elements as "NaN" for floating-point types, or zero. Other useful values of "T" include "ASCIIString", "AbstractString", and "Any". + + If "header" is "true", the first row of data will be read as header and the tuple "(data_cells, header_cells)" is returned instead of only "data_cells". + + Specifying "skipstart" will ignore the corresponding number of initial lines from the input. + + If "skipblanks" is "true", blank lines in the input will be ignored. + + If "use_mmap" is "true", the file specified by "source" is memory mapped for potential speedups. Default is "true" except on Windows. On Windows, you may want to specify "true" if the file is large, and is only read once and not written to. + + If "ignore_invalid_chars" is "true", bytes in "source" with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If "quotes" is "true", column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying "dims" as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If "comments" is "true", lines beginning with "comment_char" and text following "comment_char" in any line are ignored. + + :: + + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as "\n". + + :: + + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". + + :: + + readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as "\n". If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. @@ -618,32 +1104,66 @@ Memory-mapped I/O This would create a 25-by-30000 "BitArray", linked to the file associated with stream "s". -.. function:: msync(ptr, len[, flags]) +.. function:: msync(array) - Forces synchronization of the "mmap()"ped memory region from "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See your platform man page for specifics. The flags argument is not valid on Windows. - - You may not need to call "msync", because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + Forces synchronization between the in-memory version of a memory- mapped "Array" or "BitArray" and the on-disk version. Network I/O ----------- -.. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +.. function:: connect([host], port) -> TcpSocket + + Connect to the host "host" on port "port" + + :: + + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at "path" + + :: + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id "pid", specified by "config" and return a pair of "AsyncStream" objects. Messages from "pid" to current process will be read off "instrm", while messages to be sent to "pid" will be written to "outstrm". The custom transport implementation must ensure that messages are delivered and received completely and in order. "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. -.. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +.. function:: connect([host], port) -> TcpSocket + + Connect to the host "host" on port "port" + + :: + + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at "path" + + :: + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id "pid", specified by "config" and return a pair of "AsyncStream" objects. Messages from "pid" to current process will be read off "instrm", while messages to be sent to "pid" will be written to "outstrm". The custom transport implementation must ensure that messages are delivered and received completely and in order. "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. -.. function:: listen(path) -> PipeServer +.. function:: listen([addr], port) -> TcpServer + + Listen on port on the address specified by "addr". By default this listens on localhost only. To listen on all interfaces pass, "IPv4(0)" or "IPv6(0)" as appropriate. + + :: + + listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket -.. function:: listen(path) -> PipeServer +.. function:: listen([addr], port) -> TcpServer + + Listen on port on the address specified by "addr". By default this listens on localhost only. To listen on all interfaces pass, "IPv4(0)" or "IPv6(0)" as appropriate. + + :: + + listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index a566f072eeb66..17c663f4f7c0a 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -38,9 +38,9 @@ Convert a system call error code to a descriptive string -.. function:: time(t::TmStruct) +.. function:: time() - Converts a "TmStruct" struct to a number of seconds since the epoch. + Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. .. function:: strftime([format], time) @@ -63,11 +63,9 @@ Flushes the C "stdout" and "stderr" streams (which may have been written to by external C code). -.. function:: msync(ptr, len[, flags]) +.. function:: msync(array) - Forces synchronization of the "mmap()"ped memory region from "ptr" to "ptr+len". Flags defaults to "MS_SYNC", but can be a combination of "MS_ASYNC", "MS_SYNC", or "MS_INVALIDATE". See your platform man page for specifics. The flags argument is not valid on Windows. - - You may not need to call "msync", because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. + Forces synchronization between the in-memory version of a memory- mapped "Array" or "BitArray" and the on-disk version. .. data:: MS_ASYNC diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 43cb0c55f06f0..f0d1ff5e088ec 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -13,7 +13,19 @@ Standard Functions Linear algebra functions in Julia are largely implemented by calling functions from `LAPACK `_. Sparse factorizations call functions from `SuiteSparse `_. -.. function:: *(s, t) +.. function:: *(A, B) + + Matrix multiplication + + :: + + *(x, y...) + + Multiplication operator. "x*y*z*..." calls this function with all arguments, i.e. "*(x, y, z, ...)". + + :: + + *(s, t) Concatenate strings. The "*" operator is an alias to this function. @@ -54,7 +66,19 @@ Linear algebra functions in Julia are largely implemented by calling functions f Compute a convenient factorization (including LU, Cholesky, Bunch- Kaufman, LowerTriangular, UpperTriangular) of A, based upon the type of the input matrix. The return value can then be reused for efficient solving of multiple systems. For example: "A=factorize(A); x=A\b; y=A\C". -.. function:: full(QRCompactWYQ[, thin=true]) -> Matrix +.. function:: full(S) + + Convert a sparse matrix "S" into a dense matrix. + + :: + + full(F) + + Reconstruct the matrix "A" from the factorization "F=factorize(A)". + + :: + + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a "QRCompactWYQ" object, i.e. in the compact WY format [Bischof1987], to a dense matrix. @@ -135,7 +159,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f Compute the Cholesky factorization of a symmetric positive definite matrix "A" and return the matrix "F". If "LU" is "Val{:U}" (Upper), "F" is of type "UpperTriangular" and "A = F'*F". If "LU" is "Val{:L}" (Lower), "F" is of type "LowerTriangular" and "A = F*F'". "LU" defaults to "Val{:U}". -.. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +.. function:: cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix "A" and return either a "Cholesky" if "pivot==Val{false}" or "CholeskyPivoted" if "pivot==Val{true}". "LU" may be ":L" for using the lower part or ":U" for the upper part. The default is to use ":U". The triangular matrix can be obtained from the factorization "F" with: "F[:L]" and "F[:U]". The following functions are available for "Cholesky" objects: "size", "", "inv", "det". For "CholeskyPivoted" there is also defined a "rank". If "pivot==Val{false}" a "PosDefException" exception is thrown in case the matrix is not positive definite. The argument "tol" determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. + + :: + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the Cholesky factorization of a sparse positive definite matrix "A". A fill-reducing permutation is used. "F = cholfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). @@ -144,7 +174,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. -.. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +.. function:: cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix "A" and return either a "Cholesky" if "pivot==Val{false}" or "CholeskyPivoted" if "pivot==Val{true}". "LU" may be ":L" for using the lower part or ":U" for the upper part. The default is to use ":U". The triangular matrix can be obtained from the factorization "F" with: "F[:L]" and "F[:U]". The following functions are available for "Cholesky" objects: "size", "", "inv", "det". For "CholeskyPivoted" there is also defined a "rank". If "pivot==Val{false}" a "PosDefException" exception is thrown in case the matrix is not positive definite. The argument "tol" determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. + + :: + + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the Cholesky factorization of a sparse positive definite matrix "A". A fill-reducing permutation is used. "F = cholfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). @@ -158,7 +194,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f "cholfact!" is the same as "cholfact()", but saves space by overwriting the input "A", instead of creating a copy. "cholfact!" can also reuse the symbolic factorization from a different matrix "F" with the same structure when used as: "cholfact!(F::CholmodFactor, A)". -.. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +.. function:: ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix "A" such that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular matrix and "d" is a vector with non-negative elements. + + :: + + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the LDLt factorization of a sparse symmetric or Hermitian matrix "A". A fill-reducing permutation is used. "F = ldltfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*D*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, :DU, :PtLD, :DUP". @@ -167,7 +209,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. -.. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor +.. function:: ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix "A" such that "A=L*Diagonal(d)*L'" where "L" is a unit lower triangular matrix and "d" is a vector with non-negative elements. + + :: + + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor Compute the LDLt factorization of a sparse symmetric or Hermitian matrix "A". A fill-reducing permutation is used. "F = ldltfact(A)" is most frequently used to solve systems of equations with "F\b", but also the methods "diag", "det", "logdet" are defined for "F". You can also extract individual factors from "F", using "F[:L]". However, since pivoting is on by default, the factorization is internally represented as "A == P'*L*D*L'*P" with a permutation matrix "P"; using just "L" without accounting for "P" will give incorrect answers. To include the effects of permutation, it's typically preferable to extact "combined" factors like "PtL = F[:PtL]" (the equivalent of "P'*L") and "LtP = F[:UP]" (the equivalent of "L'*P"). The complete list of supported factors is ":L, :PtL, :D, :UP, :U, :LD, :DU, :PtLD, :DUP". @@ -181,12 +229,128 @@ Linear algebra functions in Julia are largely implemented by calling functions f Compute the (pivoted) QR factorization of "A" such that either "A = Q*R" or "A[:,p] = Q*R". Also see "qrfact". The default is to compute a thin factorization. Note that "R" is not extended with zeros when the full "Q" is requested. -.. function:: qrfact(A) -> SPQR.Factorization +.. function:: qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of "A". The return type of "F" depends on the element type of "A" and whether pivoting is specified (with "pivot==Val{true}"). + + :: + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | "eltype(A)" | "pivot" | Relationship between "F" and "A" | + +------------------+-------------------+----------------+---------------------------------------+ + | "QR" | not "BlasFloat" | either | "A==F[:Q]*F[:R]" | + +------------------+-------------------+----------------+---------------------------------------+ + | "QRCompactWY" | "BlasFloat" | "Val{false}" | "A==F[:Q]*F[:R]" | + +------------------+-------------------+----------------+---------------------------------------+ + | "QRPivoted" | "BlasFloat" | "Val{true}" | "A[:,F[:p]]==F[:Q]*F[:R]" | + +------------------+-------------------+----------------+---------------------------------------+ + + "BlasFloat" refers to any of: "Float32", "Float64", "Complex64" or "Complex128". + + The individual components of the factorization "F" can be accessed by indexing: + + :: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | "QR" | "QRCompactWY" | "QRPivoted" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:Q]" | "Q" (orthogonal/unitary) part of "QR" | ✓ ("QRPackedQ") | ✓ ("QRCompactWYQ") | ✓ ("QRPackedQ") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:R]" | "R" (upper right triangular) part of "QR" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:p]" | pivot "Vector" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:P]" | (pivot) permutation "Matrix" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the "QR" objects: "size", "". When "A" is rectangular, "" will return a least squares solution and if the solution is not unique, the one with smallest norm is returned. + + Multiplication with respect to either thin or full "Q" is allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A "Q" matrix can be converted into a regular matrix with "full()" which has a named argument "thin". + + Note: "qrfact" returns multiple types because LAPACK uses several representations that minimize the memory storage requirements of products of Householder elementary reflectors, so that the "Q" and "R" matrices can be stored compactly rather as two separate dense matrices.The data contained in "QR" or "QRPivoted" can be used to construct the "QRPackedQ" type, which is a compact representation of the rotation matrix: + + :: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where \tau_i is the scale factor and v_i is the projection vector associated with the i^{th} Householder elementary reflector.The data contained in "QRCompactWY" can be used to construct the "QRCompactWYQ" type, which is a compact representation of the rotation matrix + + :: + + Q = I + Y T Y^T + + where "Y" is m \times r lower trapezoidal and "T" is r \times r upper triangular. The *compact WY* representation [Schreiber1989] is not to be confused with the older, *WY* representation [Bischof1987]. (The LAPACK documentation uses "V" in lieu of "Y".) + + [Bischof1987] C Bischof and C Van Loan, The WY representation for products of Householder matrices, SIAM J Sci Stat Comput 8 (1987), s2-s13. doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A storage-efficient WY representation for products of Householder transformations, SIAM J Sci Stat Comput 10 (1989), 53-57. doi:10.1137/0910005 + + :: + + qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix "A". A fill- reducing permutation is used. The main application of this type is to solve least squares problems with "". The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. -.. function:: qrfact(A) -> SPQR.Factorization +.. function:: qrfact(A[, pivot=Val{false}]) -> F + + Computes the QR factorization of "A". The return type of "F" depends on the element type of "A" and whether pivoting is specified (with "pivot==Val{true}"). + + :: + + +------------------+-------------------+----------------+---------------------------------------+ + | Return type | "eltype(A)" | "pivot" | Relationship between "F" and "A" | + +------------------+-------------------+----------------+---------------------------------------+ + | "QR" | not "BlasFloat" | either | "A==F[:Q]*F[:R]" | + +------------------+-------------------+----------------+---------------------------------------+ + | "QRCompactWY" | "BlasFloat" | "Val{false}" | "A==F[:Q]*F[:R]" | + +------------------+-------------------+----------------+---------------------------------------+ + | "QRPivoted" | "BlasFloat" | "Val{true}" | "A[:,F[:p]]==F[:Q]*F[:R]" | + +------------------+-------------------+----------------+---------------------------------------+ + + "BlasFloat" refers to any of: "Float32", "Float64", "Complex64" or "Complex128". + + The individual components of the factorization "F" can be accessed by indexing: + + :: + + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | Component | Description | "QR" | "QRCompactWY" | "QRPivoted" | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:Q]" | "Q" (orthogonal/unitary) part of "QR" | ✓ ("QRPackedQ") | ✓ ("QRCompactWYQ") | ✓ ("QRPackedQ") | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:R]" | "R" (upper right triangular) part of "QR" | ✓ | ✓ | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:p]" | pivot "Vector" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + | "F[:P]" | (pivot) permutation "Matrix" | | | ✓ | + +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ + + The following functions are available for the "QR" objects: "size", "". When "A" is rectangular, "" will return a least squares solution and if the solution is not unique, the one with smallest norm is returned. + + Multiplication with respect to either thin or full "Q" is allowed, i.e. both "F[:Q]*F[:R]" and "F[:Q]*A" are supported. A "Q" matrix can be converted into a regular matrix with "full()" which has a named argument "thin". + + Note: "qrfact" returns multiple types because LAPACK uses several representations that minimize the memory storage requirements of products of Householder elementary reflectors, so that the "Q" and "R" matrices can be stored compactly rather as two separate dense matrices.The data contained in "QR" or "QRPivoted" can be used to construct the "QRPackedQ" type, which is a compact representation of the rotation matrix: + + :: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where \tau_i is the scale factor and v_i is the projection vector associated with the i^{th} Householder elementary reflector.The data contained in "QRCompactWY" can be used to construct the "QRCompactWYQ" type, which is a compact representation of the rotation matrix + + :: + + Q = I + Y T Y^T + + where "Y" is m \times r lower trapezoidal and "T" is r \times r upper triangular. The *compact WY* representation [Schreiber1989] is not to be confused with the older, *WY* representation [Bischof1987]. (The LAPACK documentation uses "V" in lieu of "Y".) + + [Bischof1987] C Bischof and C Van Loan, The WY representation for products of Householder matrices, SIAM J Sci Stat Comput 8 (1987), s2-s13. doi:10.1137/0908009 + + [Schreiber1989] R Schreiber and C Van Loan, A storage-efficient WY representation for products of Householder transformations, SIAM J Sci Stat Comput 10 (1989), 53-57. doi:10.1137/0910005 + + :: + + qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix "A". A fill- reducing permutation is used. The main application of this type is to solve least squares problems with "". The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. @@ -196,7 +360,19 @@ Linear algebra functions in Julia are largely implemented by calling functions f "qrfact!" is the same as "qrfact()" when A is a subtype of "StridedMatrix", but saves space by overwriting the input "A", instead of creating a copy. -.. function:: full(QRCompactWYQ[, thin=true]) -> Matrix +.. function:: full(S) + + Convert a sparse matrix "S" into a dense matrix. + + :: + + full(F) + + Reconstruct the matrix "A" from the factorization "F=factorize(A)". + + :: + + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a "QRCompactWYQ" object, i.e. in the compact WY format [Bischof1987], to a dense matrix. @@ -222,14 +398,48 @@ Linear algebra functions in Julia are largely implemented by calling functions f "sqrtm" uses a polyalgorithm, computing the matrix square root using Schur factorizations ("schurfact()") unless it detects the matrix to be Hermitian or real symmetric, in which case it computes the matrix square root from an eigendecomposition ("eigfact()"). In the latter situation for positive definite matrices, the matrix square root has "Real" elements, otherwise it has "Complex" elements. -.. function:: eig(A, B) -> D, V +.. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of "A". See "eigfact()" for details on the "balance" keyword argument. + + :: + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + "eig" is a wrapper around "eigfact()", extracting all parts of the factorization to a tuple; where possible, using "eigfact()" is recommended. + + :: + + eig(A, B) -> D, V Computes generalized eigenvalues and vectors of "A" with respect to "B". "eig" is a wrapper around "eigfact()", extracting all parts of the factorization to a tuple; where possible, using "eigfact()" is recommended. -.. function:: eig(A, B) -> D, V +.. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of "A". See "eigfact()" for details on the "balance" keyword argument. + + :: + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + "eig" is a wrapper around "eigfact()", extracting all parts of the factorization to a tuple; where possible, using "eigfact()" is recommended. + + :: + + eig(A, B) -> D, V Computes generalized eigenvalues and vectors of "A" with respect to "B". @@ -260,12 +470,36 @@ Linear algebra functions in Julia are largely implemented by calling functions f For "SymTridiagonal" matrices, if the optional vector of eigenvalues "eigvals" is specified, returns the specific corresponding eigenvectors. -.. function:: eigfact(A, B) -> GeneralizedEigen +.. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of "A", returning an "Eigen" factorization object "F" which contains the eigenvalues in "F[:values]" and the eigenvectors in the columns of the matrix "F[:vectors]". (The "k"th eigenvector can be obtained from the slice "F[:vectors][:, k]".) + + The following functions are available for "Eigen" objects: "inv", "det". + + If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it is possible to calculate only a subset of the eigenvalues by specifying either a "UnitRange" "irange" covering indices of the sorted eigenvalues or a pair "vl" and "vu" for the lower and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option "permute=true" permutes the matrix to become closer to upper triangular, and "scale=true" scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is "true" for both options. + + :: + + eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of "A" and "B", returning a "GeneralizedEigen" factorization object "F" which contains the generalized eigenvalues in "F[:values]" and the generalized eigenvectors in the columns of the matrix "F[:vectors]". (The "k"th generalized eigenvector can be obtained from the slice "F[:vectors][:, k]".) -.. function:: eigfact(A, B) -> GeneralizedEigen +.. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of "A", returning an "Eigen" factorization object "F" which contains the eigenvalues in "F[:values]" and the eigenvectors in the columns of the matrix "F[:vectors]". (The "k"th eigenvector can be obtained from the slice "F[:vectors][:, k]".) + + The following functions are available for "Eigen" objects: "inv", "det". + + If "A" is "Symmetric", "Hermitian" or "SymTridiagonal", it is possible to calculate only a subset of the eigenvalues by specifying either a "UnitRange" "irange" covering indices of the sorted eigenvalues or a pair "vl" and "vu" for the lower and upper boundaries of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the matrix is balanced before the eigenvector calculation. The option "permute=true" permutes the matrix to become closer to upper triangular, and "scale=true" scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is "true" for both options. + + :: + + eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of "A" and "B", returning a "GeneralizedEigen" factorization object "F" which contains the generalized eigenvalues in "F[:values]" and the generalized eigenvectors in the columns of the matrix "F[:vectors]". (The "k"th generalized eigenvector can be obtained from the slice "F[:vectors][:, k]".) @@ -285,7 +519,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f "hessfact!" is the same as "hessfact()", but saves space by overwriting the input A, instead of creating a copy. -.. function:: schurfact(A, B) -> GeneralizedSchur +.. function:: schurfact(A) -> Schur + + Computes the Schur factorization of the matrix "A". The (quasi) triangular Schur factor can be obtained from the "Schur" object "F" with either "F[:Schur]" or "F[:T]" and the unitary/orthogonal Schur vectors can be obtained with "F[:vectors]" or "F[:Z]" such that "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" can be obtained with "F[:values]". + + :: + + schurfact(A, B) -> GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices "A" and "B". The (quasi) triangular Schur factors can be obtained from the "Schur" object "F" with "F[:S]" and "F[:T]", the left unitary/orthogonal Schur vectors can be obtained with "F[:left]" or "F[:Q]" and the right unitary/orthogonal Schur vectors can be obtained with "F[:right]" or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of "A" and "B" can be obtained with "F[:alpha]./F[:beta]". @@ -295,62 +535,230 @@ Linear algebra functions in Julia are largely implemented by calling functions f Computes the Schur factorization of "A", overwriting "A" in the process. See "schurfact()" -.. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] +.. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + + See "schurfact()" + + :: + + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See "schurfact()" -.. function:: ordschur(GS, select) -> GeneralizedSchur +.. function:: ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'" according to the logical array "select" returning a Schur object "F". The selected eigenvalues appear in the leading diagonal of "F[:Schur]" and the the corresponding leading columns of "F[:vectors]" form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via "select". + + :: + + ordschur(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur". + + :: + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix "(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" and returns a GeneralizedSchur object "GS". The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that "(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of "A" and "B" can still be obtained with "GS[:alpha]./GS[:beta]". + + :: + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". -.. function:: ordschur!(GS, select) -> GeneralizedSchur +.. function:: ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'", overwriting "Q" and "T" in the process. See "ordschur()" + + :: + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur", overwriting "S" in the process. See "ordschur()" + + :: + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by overwriting the matrices "(S, T, Q, Z)" in the process. See "ordschur()". + + :: + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". -.. function:: ordschur(GS, select) -> GeneralizedSchur +.. function:: ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'" according to the logical array "select" returning a Schur object "F". The selected eigenvalues appear in the leading diagonal of "F[:Schur]" and the the corresponding leading columns of "F[:vectors]" form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via "select". + + :: + + ordschur(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur". + + :: + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix "(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" and returns a GeneralizedSchur object "GS". The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that "(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of "A" and "B" can still be obtained with "GS[:alpha]./GS[:beta]". + + :: + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". -.. function:: ordschur!(GS, select) -> GeneralizedSchur +.. function:: ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'", overwriting "Q" and "T" in the process. See "ordschur()" + + :: + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur", overwriting "S" in the process. See "ordschur()" + + :: + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by overwriting the matrices "(S, T, Q, Z)" in the process. See "ordschur()". + + :: + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". -.. function:: schurfact(A, B) -> GeneralizedSchur +.. function:: schurfact(A) -> Schur + + Computes the Schur factorization of the matrix "A". The (quasi) triangular Schur factor can be obtained from the "Schur" object "F" with either "F[:Schur]" or "F[:T]" and the unitary/orthogonal Schur vectors can be obtained with "F[:vectors]" or "F[:Z]" such that "A=F[:vectors]*F[:Schur]*F[:vectors]'". The eigenvalues of "A" can be obtained with "F[:values]". + + :: + + schurfact(A, B) -> GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices "A" and "B". The (quasi) triangular Schur factors can be obtained from the "Schur" object "F" with "F[:S]" and "F[:T]", the left unitary/orthogonal Schur vectors can be obtained with "F[:left]" or "F[:Q]" and the right unitary/orthogonal Schur vectors can be obtained with "F[:right]" or "F[:Z]" such that "A=F[:left]*F[:S]*F[:right]'" and "B=F[:left]*F[:T]*F[:right]'". The generalized eigenvalues of "A" and "B" can be obtained with "F[:alpha]./F[:beta]". -.. function:: schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] +.. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] See "schurfact()" + :: + + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + + See "schurfact()" + + +.. function:: ordschur(Q, T, select) -> Schur -.. function:: ordschur(GS, select) -> GeneralizedSchur + Reorders the Schur factorization of a real matrix "A=Q*T*Q'" according to the logical array "select" returning a Schur object "F". The selected eigenvalues appear in the leading diagonal of "F[:Schur]" and the the corresponding leading columns of "F[:vectors]" form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via "select". + + :: + + ordschur(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur". + + :: + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix "(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" and returns a GeneralizedSchur object "GS". The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that "(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of "A" and "B" can still be obtained with "GS[:alpha]./GS[:beta]". + + :: + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". -.. function:: ordschur!(GS, select) -> GeneralizedSchur +.. function:: ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'", overwriting "Q" and "T" in the process. See "ordschur()" + + :: + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur", overwriting "S" in the process. See "ordschur()" + + :: + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by overwriting the matrices "(S, T, Q, Z)" in the process. See "ordschur()". + + :: + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". -.. function:: ordschur(GS, select) -> GeneralizedSchur +.. function:: ordschur(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'" according to the logical array "select" returning a Schur object "F". The selected eigenvalues appear in the leading diagonal of "F[:Schur]" and the the corresponding leading columns of "F[:vectors]" form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via "select". + + :: + + ordschur(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur". + + :: + + ordschur(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix "(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})" according to the logical array "select" and returns a GeneralizedSchur object "GS". The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that "(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}" still holds and the generalized eigenvalues of "A" and "B" can still be obtained with "GS[:alpha]./GS[:beta]". + + :: + + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See "ordschur()". -.. function:: ordschur!(GS, select) -> GeneralizedSchur +.. function:: ordschur!(Q, T, select) -> Schur + + Reorders the Schur factorization of a real matrix "A=Q*T*Q'", overwriting "Q" and "T" in the process. See "ordschur()" + + :: + + ordschur!(S, select) -> Schur + + Reorders the Schur factorization "S" of type "Schur", overwriting "S" in the process. See "ordschur()" + + :: + + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + + Reorders the Generalized Schur factorization of a matrix by overwriting the matrices "(S, T, Q, Z)" in the process. See "ordschur()". + + :: + + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See "ordschur()". -.. function:: svdfact(A, B) -> GeneralizedSVD +.. function:: svdfact(A[, thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of "A" and return an "SVD" object. "U", "S", "V" and "Vt" can be obtained from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is "true", an economy mode decomposition is returned. The algorithm produces "Vt" and hence "Vt" is more efficient to extract than "V". The default is to produce a thin decomposition. + + :: + + svdfact(A, B) -> GeneralizedSVD Compute the generalized SVD of "A" and "B", returning a "GeneralizedSVD" Factorization object "F", such that "A = F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = F[:V]*F[:D2]*F[:R0]*F[:Q]'". @@ -360,12 +768,24 @@ Linear algebra functions in Julia are largely implemented by calling functions f "svdfact!" is the same as "svdfact()", but saves space by overwriting the input A, instead of creating a copy. If "thin" is "true", an economy mode decomposition is returned. The default is to produce a thin decomposition. -.. function:: svd(A, B) -> U, V, Q, D1, D2, R0 +.. function:: svd(A[, thin=true]) -> U, S, V + + Wrapper around "svdfact" extracting all parts the factorization to a tuple. Direct use of "svdfact" is therefore generally more efficient. Computes the SVD of A, returning "U", vector "S", and "V" such that "A == U*diagm(S)*V'". If "thin" is "true", an economy mode decomposition is returned. The default is to produce a thin decomposition. + + :: + + svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around "svdfact" extracting all parts the factorization to a tuple. Direct use of "svdfact" is therefore generally more efficient. The function returns the generalized SVD of "A" and "B", returning "U", "V", "Q", "D1", "D2", and "R0" such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". -.. function:: svdvals(A, B) +.. function:: svdvals(A) + + Returns the singular values of "A". + + :: + + svdvals(A, B) Return only the singular values from the generalized singular value decomposition of "A" and "B". @@ -375,57 +795,123 @@ Linear algebra functions in Julia are largely implemented by calling functions f Returns the singular values of "A", while saving space by overwriting the input. -.. function:: svdfact(A, B) -> GeneralizedSVD +.. function:: svdfact(A[, thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of "A" and return an "SVD" object. "U", "S", "V" and "Vt" can be obtained from the factorization "F" with "F[:U]", "F[:S]", "F[:V]" and "F[:Vt]", such that "A = U*diagm(S)*Vt". If "thin" is "true", an economy mode decomposition is returned. The algorithm produces "Vt" and hence "Vt" is more efficient to extract than "V". The default is to produce a thin decomposition. + + :: + + svdfact(A, B) -> GeneralizedSVD Compute the generalized SVD of "A" and "B", returning a "GeneralizedSVD" Factorization object "F", such that "A = F[:U]*F[:D1]*F[:R0]*F[:Q]'" and "B = F[:V]*F[:D2]*F[:R0]*F[:Q]'". -.. function:: svd(A, B) -> U, V, Q, D1, D2, R0 +.. function:: svd(A[, thin=true]) -> U, S, V + + Wrapper around "svdfact" extracting all parts the factorization to a tuple. Direct use of "svdfact" is therefore generally more efficient. Computes the SVD of A, returning "U", vector "S", and "V" such that "A == U*diagm(S)*V'". If "thin" is "true", an economy mode decomposition is returned. The default is to produce a thin decomposition. + + :: + + svd(A, B) -> U, V, Q, D1, D2, R0 Wrapper around "svdfact" extracting all parts the factorization to a tuple. Direct use of "svdfact" is therefore generally more efficient. The function returns the generalized SVD of "A" and "B", returning "U", "V", "Q", "D1", "D2", and "R0" such that "A = U*D1*R0*Q'" and "B = V*D2*R0*Q'". -.. function:: svdvals(A, B) +.. function:: svdvals(A) + + Returns the singular values of "A". + + :: + + svdvals(A, B) Return only the singular values from the generalized singular value decomposition of "A" and "B". -.. function:: triu(M, k) +.. function:: triu(M) + + Upper triangle of a matrix. + + :: + + triu(M, k) Returns the upper triangle of "M" starting from the "k"th superdiagonal. -.. function:: triu(M, k) +.. function:: triu(M) + + Upper triangle of a matrix. + + :: + + triu(M, k) Returns the upper triangle of "M" starting from the "k"th superdiagonal. -.. function:: triu!(M, k) +.. function:: triu!(M) + + Upper triangle of a matrix, overwriting "M" in the process. + + :: + + triu!(M, k) Returns the upper triangle of "M" starting from the "k"th superdiagonal, overwriting "M" in the process. -.. function:: triu!(M, k) +.. function:: triu!(M) + + Upper triangle of a matrix, overwriting "M" in the process. + + :: + + triu!(M, k) Returns the upper triangle of "M" starting from the "k"th superdiagonal, overwriting "M" in the process. -.. function:: tril(M, k) +.. function:: tril(M) + + Lower triangle of a matrix. + + :: + + tril(M, k) Returns the lower triangle of "M" starting from the "k"th subdiagonal. -.. function:: tril(M, k) +.. function:: tril(M) + + Lower triangle of a matrix. + + :: + + tril(M, k) Returns the lower triangle of "M" starting from the "k"th subdiagonal. -.. function:: tril!(M, k) +.. function:: tril!(M) + + Lower triangle of a matrix, overwriting "M" in the process. + + :: + + tril!(M, k) Returns the lower triangle of "M" starting from the "k"th subdiagonal, overwriting "M" in the process. -.. function:: tril!(M, k) +.. function:: tril!(M) + + Lower triangle of a matrix, overwriting "M" in the process. + + :: + + tril!(M, k) Returns the lower triangle of "M" starting from the "k"th subdiagonal, overwriting "M" in the process. @@ -447,6 +933,12 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: scale(b, A) + :: + + scale(A, b) + + scale(b, A) + Scale an array "A" by a scalar "b", returning a new array. If "A" is a matrix and "b" is a vector, then "scale(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), returning a new array. @@ -456,6 +948,12 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: scale(b, A) + :: + + scale(A, b) + + scale(b, A) + Scale an array "A" by a scalar "b", returning a new array. If "A" is a matrix and "b" is a vector, then "scale(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), returning a new array. @@ -465,6 +963,12 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: scale!(b, A) + :: + + scale!(A, b) + + scale!(b, A) + Scale an array "A" by a scalar "b", similar to "scale()" but overwriting "A" in-place. If "A" is a matrix and "b" is a vector, then "scale!(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- place on "A". @@ -472,6 +976,12 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: scale!(b, A) + :: + + scale!(A, b) + + scale!(b, A) + Scale an array "A" by a scalar "b", similar to "scale()" but overwriting "A" in-place. If "A" is a matrix and "b" is a vector, then "scale!(A,b)" scales each column "i" of "A" by "b[i]" (similar to "A*diagm(b)"), while "scale!(b,A)" scales each row "i" of "A" by "b[i]" (similar to "diagm(b)*A"), again operating in- place on "A". @@ -604,12 +1114,42 @@ Linear algebra functions in Julia are largely implemented by calling functions f Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. -.. function:: linreg(x, y, w) +.. function:: linreg(x, y) -> [a; b] + + Linear Regression. Returns "a" and "b" such that "a+b*x" is the closest line to the given points "(x,y)". In other words, this function determines parameters "[a, b]" that minimize the squared error between "y" and "a+b*x". + + **Example**: + + :: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + + linreg(x, y, w) Weighted least-squares linear regression. -.. function:: linreg(x, y, w) +.. function:: linreg(x, y) -> [a; b] + + Linear Regression. Returns "a" and "b" such that "a+b*x" is the closest line to the given points "(x,y)". In other words, this function determines parameters "[a, b]" that minimize the squared error between "y" and "a+b*x". + + **Example**: + + :: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + + linreg(x, y, w) Weighted least-squares linear regression. @@ -888,12 +1428,24 @@ Usually a function has 4 methods defined, one each for ``Float64``, Returns the updated "y". -.. function:: sbmv(uplo, k, A, x) +.. function:: sbmv(uplo, k, alpha, A, x) + + Returns "alpha*A*x" where "A" is a symmetric band matrix of order "size(A,2)" with "k" super-diagonals stored in the argument "A". + + :: + + sbmv(uplo, k, A, x) Returns "A*x" where "A" is a symmetric band matrix of order "size(A,2)" with "k" super-diagonals stored in the argument "A". -.. function:: sbmv(uplo, k, A, x) +.. function:: sbmv(uplo, k, alpha, A, x) + + Returns "alpha*A*x" where "A" is a symmetric band matrix of order "size(A,2)" with "k" super-diagonals stored in the argument "A". + + :: + + sbmv(uplo, k, A, x) Returns "A*x" where "A" is a symmetric band matrix of order "size(A,2)" with "k" super-diagonals stored in the argument "A". @@ -903,12 +1455,24 @@ Usually a function has 4 methods defined, one each for ``Float64``, Update "C" as "alpha*A*B + beta*C" or the other three variants according to "tA" (transpose "A") and "tB". Returns the updated "C". -.. function:: gemm(tA, tB, A, B) +.. function:: gemm(tA, tB, alpha, A, B) + + Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". + + :: + + gemm(tA, tB, A, B) Returns "A*B" or the other three variants according to "tA" (transpose "A") and "tB". -.. function:: gemm(tA, tB, A, B) +.. function:: gemm(tA, tB, alpha, A, B) + + Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". + + :: + + gemm(tA, tB, A, B) Returns "A*B" or the other three variants according to "tA" (transpose "A") and "tB". @@ -918,12 +1482,24 @@ Usually a function has 4 methods defined, one each for ``Float64``, Update the vector "y" as "alpha*A*x + beta*y" or "alpha*A'x + beta*y" according to "tA" (transpose "A"). Returns the updated "y". -.. function:: gemv(tA, A, x) +.. function:: gemv(tA, alpha, A, x) + + Returns "alpha*A*x" or "alpha*A'x" according to "tA" (transpose "A"). + + :: + + gemv(tA, A, x) Returns "A*x" or "A'x" according to "tA" (transpose "A"). -.. function:: gemv(tA, A, x) +.. function:: gemv(tA, alpha, A, x) + + Returns "alpha*A*x" or "alpha*A'x" according to "tA" (transpose "A"). + + :: + + gemv(tA, A, x) Returns "A*x" or "A'x" according to "tA" (transpose "A"). @@ -933,17 +1509,53 @@ Usually a function has 4 methods defined, one each for ``Float64``, Update "C" as "alpha*A*B + beta*C" or "alpha*B*A + beta*C" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. Returns the updated "C". -.. function:: symm(tA, tB, alpha, A, B) +.. function:: symm(side, ul, alpha, A, B) + + Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symm(side, ul, A, B) + + Returns "A*B" or "B*A" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symm(tA, tB, alpha, A, B) Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". -.. function:: symm(tA, tB, alpha, A, B) +.. function:: symm(side, ul, alpha, A, B) + + Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symm(side, ul, A, B) + + Returns "A*B" or "B*A" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symm(tA, tB, alpha, A, B) Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". -.. function:: symm(tA, tB, alpha, A, B) +.. function:: symm(side, ul, alpha, A, B) + + Returns "alpha*A*B" or "alpha*B*A" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symm(side, ul, A, B) + + Returns "A*B" or "B*A" according to "side". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symm(tA, tB, alpha, A, B) Returns "alpha*A*B" or the other three variants according to "tA" (transpose "A") and "tB". @@ -953,12 +1565,24 @@ Usually a function has 4 methods defined, one each for ``Float64``, Update the vector "y" as "alpha*A*x + beta*y". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. Returns the updated "y". -.. function:: symv(ul, A, x) +.. function:: symv(ul, alpha, A, x) + + Returns "alpha*A*x". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symv(ul, A, x) Returns "A*x". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. -.. function:: symv(ul, A, x) +.. function:: symv(ul, alpha, A, x) + + Returns "alpha*A*x". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. + + :: + + symv(ul, A, x) Returns "A*x". "A" is assumed to be symmetric. Only the "ul" triangle of "A" is used. diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index 5d6612092a850..a2aa0e02a5e86 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -9,7 +9,13 @@ Mathematical Operators ---------------------- -.. function:: -(x, y) +.. function:: -(x) + + Unary minus operator. + + :: + + -(x, y) Subtraction operator. @@ -21,13 +27,31 @@ Mathematical Operators .. _-: -.. function:: -(x, y) +.. function:: -(x) + + Unary minus operator. + + :: + + -(x, y) Subtraction operator. .. _*: -.. function:: *(s, t) +.. function:: *(A, B) + + Matrix multiplication + + :: + + *(x, y...) + + Multiplication operator. "x*y*z*..." calls this function with all arguments, i.e. "*(x, y, z, ...)". + + :: + + *(s, t) Concatenate strings. The "*" operator is an alias to this function. @@ -50,7 +74,13 @@ Mathematical Operators Gives floating-point results for integer arguments. .. _^: -.. function:: ^(s, n) +.. function:: ^(x, y) + + Exponentiation operator. + + :: + + ^(s, n) Repeat "n" times the string "s". The "^" operator is an alias to this function. @@ -239,11 +269,11 @@ Mathematical Operators .. _===: -.. function:: ===(x, y) +.. function:: is(x, y) -> Bool - ≡(x, y) + ===(x, y) -> Bool ≡(x, y) -> Bool - See the "is()" operator + Determine whether "x" and "y" are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called "egal". .. _!==: @@ -709,12 +739,28 @@ Mathematical Functions Compute the \sqrt{x^2+y^2} avoiding overflow and underflow -.. function:: log(b, x) +.. function:: log(x) + + Compute the natural logarithm of "x". Throws "DomainError" for negative "Real" arguments. Use complex negative arguments to obtain complex results. + + There is an experimental variant in the "Base.Math.JuliaLibm" module, which is typically faster and more accurate. + + :: + + log(b, x) Compute the base "b" logarithm of "x". Throws "DomainError" for negative "Real" arguments. -.. function:: log(b, x) +.. function:: log(x) + + Compute the natural logarithm of "x". Throws "DomainError" for negative "Real" arguments. Use complex negative arguments to obtain complex results. + + There is an experimental variant in the "Base.Math.JuliaLibm" module, which is typically faster and more accurate. + + :: + + log(b, x) Compute the base "b" logarithm of "x". Throws "DomainError" for negative "Real" arguments. @@ -771,7 +817,52 @@ Mathematical Functions Accurately compute e^x-1 -.. function:: round(z, RoundingModeReal, RoundingModeImaginary) +.. function:: round([T], x[, digits[, base]][, r::RoundingMode]) + + "round(x)" rounds "x" to an integer value according to the default rounding mode (see "get_rounding()"), returning a value of the same type as "x". By default ("RoundNearest"), this will round to the nearest integer, with ties (fractional values of 0.5) being rounded to the even integer. + + :: + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional "RoundingMode" argument will change how the number gets rounded. + + "round(T, x, [r::RoundingMode])" converts the result to type "T", throwing an "InexactError" if the value is not representable. + + "round(x, digits)" rounds to the specified number of digits after the decimal place (or before if negative). "round(x, digits, base)" rounds using a base other than 10. + + :: + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be inexact when operating on binary floating point numbers. For example, the "Float64" value represented by "1.15" is actually *less* than 1.15, yet will be rounded to 1.2. + + :: + + julia> x = 1.15 + 1.15 + + julia> @sprintf "%.20f" x + "1.14999999999999991118" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + + round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex- valued "z" to "z", breaking ties using the specified "RoundingMode"s. The first "RoundingMode" is used for rounding the real components while the second is used for rounding the imaginary components. @@ -841,7 +932,52 @@ Mathematical Functions :func:`round` using this rounding mode is an alias for :func:`floor`. -.. function:: round(z, RoundingModeReal, RoundingModeImaginary) +.. function:: round([T], x[, digits[, base]][, r::RoundingMode]) + + "round(x)" rounds "x" to an integer value according to the default rounding mode (see "get_rounding()"), returning a value of the same type as "x". By default ("RoundNearest"), this will round to the nearest integer, with ties (fractional values of 0.5) being rounded to the even integer. + + :: + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional "RoundingMode" argument will change how the number gets rounded. + + "round(T, x, [r::RoundingMode])" converts the result to type "T", throwing an "InexactError" if the value is not representable. + + "round(x, digits)" rounds to the specified number of digits after the decimal place (or before if negative). "round(x, digits, base)" rounds using a base other than 10. + + :: + + julia> round(pi, 2) + 3.14 + + julia> round(pi, 3, 2) + 3.125 + + Note: Rounding to specified digits in bases other than 2 can be inexact when operating on binary floating point numbers. For example, the "Float64" value represented by "1.15" is actually *less* than 1.15, yet will be rounded to 1.2. + + :: + + julia> x = 1.15 + 1.15 + + julia> @sprintf "%.20f" x + "1.14999999999999991118" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + + round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex- valued "z" to "z", breaking ties using the specified "RoundingMode"s. The first "RoundingMode" is used for rounding the real components while the second is used for rounding the imaginary components. diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 58b78022b070d..6b2298b549217 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -52,7 +52,19 @@ Data Formats A string giving the literal bit representation of a number. -.. function:: parse(type, str[, base]) +.. function:: parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If "greedy" is true (default), "parse" will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return "Expr(:incomplete, "(error message)")". If "raise" is true (default), syntax errors other than incomplete expressions will raise an error. If "raise" is false, "parse" will return an expression that will raise an error upon evaluation. + + :: + + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If "raise" is true (default), syntax errors will raise an error; otherwise, "parse" will return an expression that will raise an error upon evaluation. + + :: + + parse(type, str[, base]) Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. @@ -385,7 +397,16 @@ Integers 2 -.. function:: isprime(x::BigInt[, reps = 25]) -> Bool +.. function:: isprime(x::Integer) -> Bool + + Returns "true" if "x" is prime, and "false" otherwise. + + :: + + julia> isprime(3) + true + + isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns "true" if "x" is prime; and "false" if "x" is not prime with high probability. The false positive rate is about "0.25^reps". "reps = 25" is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). @@ -395,7 +416,16 @@ Integers true -.. function:: isprime(x::BigInt[, reps = 25]) -> Bool +.. function:: isprime(x::Integer) -> Bool + + Returns "true" if "x" is prime, and "false" otherwise. + + :: + + julia> isprime(3) + true + + isprime(x::BigInt[, reps = 25]) -> Bool Probabilistic primality test. Returns "true" if "x" is prime; and "false" if "x" is not prime with high probability. The false positive rate is about "0.25^reps". "reps = 25" is considered safe for cryptographic applications (Knuth, Seminumerical Algorithms). diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 41d8f6a0f61c0..cd4b92ab4225e 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -47,17 +47,53 @@ Tasks Switch to the scheduler to allow another scheduled task to run. A task that calls this function is still runnable, and will be restarted immediately if there are no other runnable tasks. -.. function:: task_local_storage(body, symbol, value) +.. function:: task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local storage. + + :: + + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local storage. + + :: + + task_local_storage(body, symbol, value) Call the function "body" with a modified task-local storage, in which "value" is assigned to "symbol"; the previous value of "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. -.. function:: task_local_storage(body, symbol, value) +.. function:: task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local storage. + + :: + + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local storage. + + :: + + task_local_storage(body, symbol, value) Call the function "body" with a modified task-local storage, in which "value" is assigned to "symbol"; the previous value of "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. -.. function:: task_local_storage(body, symbol, value) +.. function:: task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local storage. + + :: + + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local storage. + + :: + + task_local_storage(body, symbol, value) Call the function "body" with a modified task-local storage, in which "value" is assigned to "symbol"; the previous value of "symbol", or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. @@ -112,7 +148,51 @@ Tasks General Parallel Computing Support ---------------------------------- -.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +.. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built "LocalManager" which only launches workers on the local host. This can be used to take advantage of multiple cores. "addprocs(4)" will add 4 processes on the local machine. + + :: + + addprocs() -> List of process identifiers + + Equivalent to "addprocs(CPU_CORES)" + + :: + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + "machines" is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string "machine_spec" or a tuple - "(machine_spec, count)" + + "machine_spec" is a string of the form "[user@]host[:port] [bind_addr[:port]]". "user" defaults to current user, "port" to the standard ssh port. If "[bind_addr[:port]]" is specified, other workers will connect to this worker at the specified "bind_addr" and "port". + + "count" is the number of workers to be launched on the specified host. If specified as ":auto" it will launch as many workers as the number of cores on the specific host. + + Keyword arguments: + + "tunnel" : if "true" then SSH tunneling will be used to connect to the worker from the master process. + + "sshflags" : specifies additional ssh options, e.g. "sshflags=``-i /home/foo/bar.pem``" . + + "max_parallel" : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + "dir" : specifies the working directory on the workers. Defaults to the host's current directory (as found by *pwd()*) + + "exename" : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + "exeflags" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, the worker treats it a fatal situation and terminates. This timeout can be controlled via environment variable "JULIA_WORKER_TIMEOUT". The value of "JULIA_WORKER_TIMEOUT" on the master process, specifies the number of seconds a newly launched worker waits for connection establishment. + + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -121,7 +201,51 @@ General Parallel Computing Support The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. -.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +.. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built "LocalManager" which only launches workers on the local host. This can be used to take advantage of multiple cores. "addprocs(4)" will add 4 processes on the local machine. + + :: + + addprocs() -> List of process identifiers + + Equivalent to "addprocs(CPU_CORES)" + + :: + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + "machines" is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string "machine_spec" or a tuple - "(machine_spec, count)" + + "machine_spec" is a string of the form "[user@]host[:port] [bind_addr[:port]]". "user" defaults to current user, "port" to the standard ssh port. If "[bind_addr[:port]]" is specified, other workers will connect to this worker at the specified "bind_addr" and "port". + + "count" is the number of workers to be launched on the specified host. If specified as ":auto" it will launch as many workers as the number of cores on the specific host. + + Keyword arguments: + + "tunnel" : if "true" then SSH tunneling will be used to connect to the worker from the master process. + + "sshflags" : specifies additional ssh options, e.g. "sshflags=``-i /home/foo/bar.pem``" . + + "max_parallel" : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + "dir" : specifies the working directory on the workers. Defaults to the host's current directory (as found by *pwd()*) + + "exename" : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + "exeflags" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, the worker treats it a fatal situation and terminates. This timeout can be controlled via environment variable "JULIA_WORKER_TIMEOUT". The value of "JULIA_WORKER_TIMEOUT" on the master process, specifies the number of seconds a newly launched worker waits for connection establishment. + + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -130,7 +254,51 @@ General Parallel Computing Support The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. -.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +.. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built "LocalManager" which only launches workers on the local host. This can be used to take advantage of multiple cores. "addprocs(4)" will add 4 processes on the local machine. + + :: + + addprocs() -> List of process identifiers + + Equivalent to "addprocs(CPU_CORES)" + + :: + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + "machines" is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string "machine_spec" or a tuple - "(machine_spec, count)" + + "machine_spec" is a string of the form "[user@]host[:port] [bind_addr[:port]]". "user" defaults to current user, "port" to the standard ssh port. If "[bind_addr[:port]]" is specified, other workers will connect to this worker at the specified "bind_addr" and "port". + + "count" is the number of workers to be launched on the specified host. If specified as ":auto" it will launch as many workers as the number of cores on the specific host. + + Keyword arguments: + + "tunnel" : if "true" then SSH tunneling will be used to connect to the worker from the master process. + + "sshflags" : specifies additional ssh options, e.g. "sshflags=``-i /home/foo/bar.pem``" . + + "max_parallel" : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + "dir" : specifies the working directory on the workers. Defaults to the host's current directory (as found by *pwd()*) + + "exename" : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + "exeflags" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, the worker treats it a fatal situation and terminates. This timeout can be controlled via environment variable "JULIA_WORKER_TIMEOUT". The value of "JULIA_WORKER_TIMEOUT" on the master process, specifies the number of seconds a newly launched worker waits for connection establishment. + + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -139,7 +307,51 @@ General Parallel Computing Support The number of seconds a newly launched worker waits for connection establishment from the master can be specified via variable "JULIA_WORKER_TIMEOUT" in the worker process's environment. Relevant only when using TCP/IP as transport. -.. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers +.. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built "LocalManager" which only launches workers on the local host. This can be used to take advantage of multiple cores. "addprocs(4)" will add 4 processes on the local machine. + + :: + + addprocs() -> List of process identifiers + + Equivalent to "addprocs(CPU_CORES)" + + :: + + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + "machines" is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string "machine_spec" or a tuple - "(machine_spec, count)" + + "machine_spec" is a string of the form "[user@]host[:port] [bind_addr[:port]]". "user" defaults to current user, "port" to the standard ssh port. If "[bind_addr[:port]]" is specified, other workers will connect to this worker at the specified "bind_addr" and "port". + + "count" is the number of workers to be launched on the specified host. If specified as ":auto" it will launch as many workers as the number of cores on the specific host. + + Keyword arguments: + + "tunnel" : if "true" then SSH tunneling will be used to connect to the worker from the master process. + + "sshflags" : specifies additional ssh options, e.g. "sshflags=``-i /home/foo/bar.pem``" . + + "max_parallel" : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + "dir" : specifies the working directory on the workers. Defaults to the host's current directory (as found by *pwd()*) + + "exename" : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + "exeflags" : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, the worker treats it a fatal situation and terminates. This timeout can be controlled via environment variable "JULIA_WORKER_TIMEOUT". The value of "JULIA_WORKER_TIMEOUT" on the master process, specifies the number of seconds a newly launched worker waits for connection establishment. + + :: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -158,7 +370,13 @@ General Parallel Computing Support Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. -.. function:: procs(S::SharedArray) +.. function:: procs() + + Returns a list of all process identifiers. + + :: + + procs(S::SharedArray) Get the vector of processes that have mapped the shared array @@ -252,12 +470,24 @@ General Parallel Computing Support isready(rr) # will not block -.. function:: RemoteRef(n) +.. function:: RemoteRef() + + Make an uninitialized remote reference on the local machine. + + :: + + RemoteRef(n) Make an uninitialized remote reference on process "n". -.. function:: RemoteRef(n) +.. function:: RemoteRef() + + Make an uninitialized remote reference on the local machine. + + :: + + RemoteRef(n) Make an uninitialized remote reference on process "n". @@ -330,7 +560,13 @@ Shared Arrays (Experimental, UNIX-only feature) If an "init" function of the type "initfn(S::SharedArray)" is specified, it is called on all the participating workers. -.. function:: procs(S::SharedArray) +.. function:: procs() + + Returns a list of all process identifiers. + + :: + + procs(S::SharedArray) Get the vector of processes that have mapped the shared array @@ -373,7 +609,13 @@ Cluster Manager Interface * with ":finalize" for cleanup purposes. -.. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) +.. function:: kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the process. + + :: + + kill(manager::FooManager, pid::Int, config::WorkerConfig) Implemented by cluster managers. It is called on the master process, by "rmprocs". It should cause the remote worker specified by "pid" to exit. "Base.kill(manager::ClusterManager.....)" executes a remote "exit()" on "pid" @@ -383,7 +625,19 @@ Cluster Manager Interface Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument "–worker" has the effect of initializing a process as a worker using TCP/IP sockets for transport. -.. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) +.. function:: connect([host], port) -> TcpSocket + + Connect to the host "host" on port "port" + + :: + + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at "path" + + :: + + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id "pid", specified by "config" and return a pair of "AsyncStream" objects. Messages from "pid" to current process will be read off "instrm", while messages to be sent to "pid" will be written to "outstrm". The custom transport implementation must ensure that messages are delivered and received completely and in order. "Base.connect(manager::ClusterManager.....)" sets up TCP/IP socket connections in-between workers. diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index 0f956463e9cfc..8ef2dd9f93b0a 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -7,12 +7,24 @@ All package manager functions are defined in the ``Pkg`` module. None of the ``Pkg`` module's functions are exported; to use them, you'll need to prefix each function call with an explicit ``Pkg.``, e.g. ``Pkg.status()`` or ``Pkg.dir()``. -.. function:: dir(names...) -> AbstractString +.. function:: dir() -> AbstractString + + Returns the absolute path of the package directory. This defaults to "joinpath(homedir(),".julia","v$(VERSION.major).$(VERSION .minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell syntax). If the "JULIA_PKGDIR" environment variable is set, then that path is used in the returned value as "joinpath(ENV["JULIA_ PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")". If "JULIA_PKGDIR" is a relative path, it is interpreted relative to whatever the current working directory is. + + :: + + dir(names...) -> AbstractString Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, "Pkg.dir(pkg)" returns the path to the package "pkg". -.. function:: dir(names...) -> AbstractString +.. function:: dir() -> AbstractString + + Returns the absolute path of the package directory. This defaults to "joinpath(homedir(),".julia","v$(VERSION.major).$(VERSION .minor)")" on all platforms (i.e. "~/.julia/v0.4" in UNIX shell syntax). If the "JULIA_PKGDIR" environment variable is set, then that path is used in the returned value as "joinpath(ENV["JULIA_ PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")". If "JULIA_PKGDIR" is a relative path, it is interpreted relative to whatever the current working directory is. + + :: + + dir(names...) -> AbstractString Equivalent to "normpath(Pkg.dir(),names...)" – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, "Pkg.dir(pkg)" returns the path to the package "pkg". @@ -42,32 +54,68 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, Remove all requirement entries for "pkg" from "Pkg.dir("REQUIRE")" and call "Pkg.resolve()". -.. function:: clone(pkg) +.. function:: clone(url[, pkg]) + + Clone a package directly from the git URL "url". The package does not need to be a registered in "Pkg.dir("METADATA")". The package repo is cloned by the name "pkg" if provided; if not provided, "pkg" is determined automatically from "url". + + :: + + clone(pkg) If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone it from that URL on the default branch. The package does not need to have any registered versions. -.. function:: clone(pkg) +.. function:: clone(url[, pkg]) + + Clone a package directly from the git URL "url". The package does not need to be a registered in "Pkg.dir("METADATA")". The package repo is cloned by the name "pkg" if provided; if not provided, "pkg" is determined automatically from "url". + + :: + + clone(pkg) If "pkg" has a URL registered in "Pkg.dir("METADATA")", clone it from that URL on the default branch. The package does not need to have any registered versions. -.. function:: available(pkg) -> Vector{VersionNumber} +.. function:: available() -> Vector{ASCIIString} + + Returns the names of available packages. + + :: + + available(pkg) -> Vector{VersionNumber} Returns the version numbers available for package "pkg". -.. function:: available(pkg) -> Vector{VersionNumber} +.. function:: available() -> Vector{ASCIIString} + + Returns the names of available packages. + + :: + + available(pkg) -> Vector{VersionNumber} Returns the version numbers available for package "pkg". -.. function:: installed(pkg) -> Void | VersionNumber +.. function:: installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the installed version number of each package. + + :: + + installed(pkg) -> Void | VersionNumber If "pkg" is installed, return the installed version number, otherwise return "nothing". -.. function:: installed(pkg) -> Void | VersionNumber +.. function:: installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the installed version number of each package. + + :: + + installed(pkg) -> Void | VersionNumber If "pkg" is installed, return the installed version number, otherwise return "nothing". @@ -87,12 +135,24 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, Checkout the "Pkg.dir(pkg)" repo to the branch "branch". Defaults to checking out the "master" branch. To go back to using the newest compatible released version, use "Pkg.free(pkg)" -.. function:: pin(pkg, version) +.. function:: pin(pkg) + + Pin "pkg" at the current version. To go back to using the newest compatible released version, use "Pkg.free(pkg)" + + :: + + pin(pkg, version) Pin "pkg" at registered version "version". -.. function:: pin(pkg, version) +.. function:: pin(pkg) + + Pin "pkg" at the current version. To go back to using the newest compatible released version, use "Pkg.free(pkg)" + + :: + + pin(pkg, version) Pin "pkg" at registered version "version". @@ -104,12 +164,24 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, You can also supply an iterable collection of package names, e.g., "Pkg.free(("Pkg1", "Pkg2"))" to free multiple packages at once. -.. function:: build(pkgs...) +.. function:: build() + + Run the build scripts for all installed packages in depth-first recursive order. + + :: + + build(pkgs...) Run the build script in "deps/build.jl" for each package in "pkgs" and all of their dependencies in depth-first recursive order. This is called automatically by "Pkg.resolve()" on all installed or updated packages. -.. function:: build(pkgs...) +.. function:: build() + + Run the build scripts for all installed packages in depth-first recursive order. + + :: + + build(pkgs...) Run the build script in "deps/build.jl" for each package in "pkgs" and all of their dependencies in depth-first recursive order. This is called automatically by "Pkg.resolve()" on all installed or updated packages. @@ -134,12 +206,24 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, For each new package version tagged in "METADATA" not already published, make sure that the tagged package commits have been pushed to the repo at the registered URL for the package and if they all have, open a pull request to "METADATA". -.. function:: test(pkgs...) +.. function:: test() + + Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its "test/runtests.jl" file and test dependencies are specified in "test/REQUIRE". + + :: + + test(pkgs...) Run the tests for each package in "pkgs" ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its "test/runtests.jl" file and test dependencies are specified in "test/REQUIRE". -.. function:: test(pkgs...) +.. function:: test() + + Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its "test/runtests.jl" file and test dependencies are specified in "test/REQUIRE". + + :: + + test(pkgs...) Run the tests for each package in "pkgs" ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its "test/runtests.jl" file and test dependencies are specified in "test/REQUIRE". diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 0e6e6612f998f..fc759f75987b5 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -21,12 +21,24 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a Clear any existing backtraces from the internal buffer. -.. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) +.. function:: print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to "io" (by default, "STDOUT"). If you do not supply a "data" vector, the internal buffer of accumulated backtraces will be used. "format" can be ":tree" or ":flat". If "C==true", backtraces from C and Fortran code are shown. "combine==true" merges instruction pointers that correspond to the same line of code. "cols" controls the width of the display. + + :: + + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) Prints profiling results to "io". This variant is used to examine results exported by a previous call to "retrieve()". Supply the vector "data" of backtraces and a dictionary "lidict" of line information. -.. function:: print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) +.. function:: print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to "io" (by default, "STDOUT"). If you do not supply a "data" vector, the internal buffer of accumulated backtraces will be used. "format" can be ":tree" or ":flat". If "C==true", backtraces from C and Fortran code are shown. "combine==true" merges instruction pointers that correspond to the same line of code. "cols" controls the width of the display. + + :: + + print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) Prints profiling results to "io". This variant is used to examine results exported by a previous call to "retrieve()". Supply the vector "data" of backtraces and a dictionary "lidict" of line information. diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 05a22e2479be7..6213563bfa5dc 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -122,12 +122,24 @@ Sorting Functions Sort the vector "v" in place. "QuickSort" is used by default for numeric arrays while "MergeSort" is used for other arrays. You can specify an algorithm to use via the "alg" keyword (see Sorting Algorithms for available algorithms). The "by" keyword lets you provide a function that will be applied to each element before comparison; the "lt" keyword allows providing a custom "less than" function; use "rev=true" to reverse the sorting order. These options are independent and can be used together in all possible combinations: if both "by" and "lt" are specified, the "lt" function is applied to the result of the "by" function; "rev=true" reverses whatever ordering specified via the "by" and "lt" keywords. -.. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) +.. function:: sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of "sort!" that returns a sorted copy of "v" leaving "v" itself unmodified. + + :: + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) Sort a multidimensional array "A" along the given dimension. -.. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) +.. function:: sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of "sort!" that returns a sorted copy of "v" leaving "v" itself unmodified. + + :: + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) Sort a multidimensional array "A" along the given dimension. diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index a9f1bdecf47f1..5753670d44857 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -4,17 +4,47 @@ Strings ********* -.. function:: length(s) +.. function:: length(A) -> Integer + + Returns the number of elements in A + + :: + + length(collection) -> Integer + + For ordered, indexable collections, the maximum index "i" for which "getindex(collection, i)" is valid. For unordered collections, the number of elements. + + :: + + length(s) The number of characters in string "s". -.. function:: sizeof(s::AbstractString) +.. function:: sizeof(type) + + Size, in bytes, of the canonical binary representation of the given type, if any. + + :: + + sizeof(s::AbstractString) The number of bytes in string "s". -.. function:: *(s, t) +.. function:: *(A, B) + + Matrix multiplication + + :: + + *(x, y...) + + Multiplication operator. "x*y*z*..." calls this function with all arguments, i.e. "*(x, y, z, ...)". + + :: + + *(s, t) Concatenate strings. The "*" operator is an alias to this function. @@ -27,7 +57,13 @@ julia> "Hello " * "world" "Hello world" -.. function:: ^(s, n) +.. function:: ^(x, y) + + Exponentiation operator. + + :: + + ^(s, n) Repeat "n" times the string "s". The "^" operator is an alias to this function. @@ -47,42 +83,126 @@ Create a string from any value using the "showall" function. -.. function:: bytestring(s) +.. function:: bytestring(::Ptr{UInt8}[, length]) + + Create a string from the address of a C (0-terminated) string encoded in ASCII or UTF-8. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + + :: + + bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. -.. function:: bytestring(s) +.. function:: bytestring(::Ptr{UInt8}[, length]) + + Create a string from the address of a C (0-terminated) string encoded in ASCII or UTF-8. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + + :: + + bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. -.. function:: ascii(::Ptr{UInt8}[, length]) +.. function:: ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + + :: + + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + + :: + + ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. -.. function:: ascii(::Ptr{UInt8}[, length]) +.. function:: ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + + :: + + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + + :: + + ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. -.. function:: ascii(::Ptr{UInt8}[, length]) +.. function:: ascii(::Array{UInt8, 1}) + + Create an ASCII string from a byte array. + + :: + + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + + :: + + ascii(::Ptr{UInt8}[, length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. -.. function:: utf8(s) +.. function:: utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + + :: + + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + + :: + + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). -.. function:: utf8(s) +.. function:: utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + + :: + + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + + :: + + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). -.. function:: utf8(s) +.. function:: utf8(::Array{UInt8, 1}) + + Create a UTF-8 string from a byte array. + + :: + + utf8(::Ptr{UInt8}[, length]) + + Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If "length" is specified, the string does not have to be 0-terminated. + + :: + + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). @@ -121,12 +241,36 @@ Returns an iterator over substrings of "s" that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. (Roughly, these are what users would perceive as single characters, even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) -.. function:: isvalid(str, i) +.. function:: isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which currently can be one of "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" + + :: + + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types currently can be "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" Values for "Char" can be of type "Char" or "UInt32" Values for "ASCIIString" and "UTF8String" can be of that type, or "Vector{UInt8}" Values for "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values for "UTF32String" can be "UTF32String", "Vector{Char}" or "Vector{UInt32}" + + :: + + isvalid(str, i) Tells whether index "i" is valid for the given string -.. function:: isvalid(str, i) +.. function:: isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which currently can be one of "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" + + :: + + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types currently can be "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" Values for "Char" can be of type "Char" or "UInt32" Values for "ASCIIString" and "UTF8String" can be of that type, or "Vector{UInt8}" Values for "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values for "UTF32String" can be "UTF32String", "Vector{Char}" or "Vector{UInt32}" + + :: + + isvalid(str, i) Tells whether index "i" is valid for the given string @@ -282,7 +426,19 @@ Convert a character index to a byte index -.. function:: isvalid(str, i) +.. function:: isvalid(value) -> Bool + + Returns true if the given value is valid for its type, which currently can be one of "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" + + :: + + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. Types currently can be "Char", "ASCIIString", "UTF8String", "UTF16String", or "UTF32String" Values for "Char" can be of type "Char" or "UInt32" Values for "ASCIIString" and "UTF8String" can be of that type, or "Vector{UInt8}" Values for "UTF16String" can be "UTF16String" or "Vector{UInt16}" Values for "UTF32String" can be "UTF32String", "Vector{Char}" or "Vector{UInt32}" + + :: + + isvalid(str, i) Tells whether index "i" is valid for the given string @@ -392,12 +548,28 @@ General unescaping of traditional C and Unicode escape sequences. Reverse of "escape_string()". See also "print_unescaped()". -.. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) +.. function:: utf16(s) + + Create a UTF-16 string from a byte array, array of "UInt16", or any other string type. (Data must be valid UTF-16. Conversions of byte arrays check for a byte-order marker in the first two bytes, and do not include it in the resulting string.) + + Note that the resulting "UTF16String" data is terminated by the NUL codepoint (16-bit zero), which is not treated as a character in the string (so that it is mostly invisible in Julia); this allows the string to be passed directly to external functions requiring NUL-terminated data. This NUL is appended automatically by the *utf16(s)* conversion function. If you have a "UInt16" array "A" that is already NUL-terminated valid UTF-16 data, then you can instead use *UTF16String(A)`* to construct the string without making a copy of the data and treating the NUL as a terminator rather than as part of the string. + + :: + + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If "length" is specified, the string does not have to be NUL-terminated. -.. function:: utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) +.. function:: utf16(s) + + Create a UTF-16 string from a byte array, array of "UInt16", or any other string type. (Data must be valid UTF-16. Conversions of byte arrays check for a byte-order marker in the first two bytes, and do not include it in the resulting string.) + + Note that the resulting "UTF16String" data is terminated by the NUL codepoint (16-bit zero), which is not treated as a character in the string (so that it is mostly invisible in Julia); this allows the string to be passed directly to external functions requiring NUL-terminated data. This NUL is appended automatically by the *utf16(s)* conversion function. If you have a "UInt16" array "A" that is already NUL-terminated valid UTF-16 data, then you can instead use *UTF16String(A)`* to construct the string without making a copy of the data and treating the NUL as a terminator rather than as part of the string. + + :: + + utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If "length" is specified, the string does not have to be NUL-terminated. From 4e861371dff3908b4d6f55d89450f9f01cb21f92 Mon Sep 17 00:00:00 2001 From: Stefan Karpinski Date: Sun, 28 Jun 2015 00:14:36 -0400 Subject: [PATCH 27/27] delete doc/helpdb.jl again --- doc/helpdb.jl | 16101 ------------------------------------------------ 1 file changed, 16101 deletions(-) delete mode 100644 doc/helpdb.jl diff --git a/doc/helpdb.jl b/doc/helpdb.jl deleted file mode 100644 index 92aa9335f2754..0000000000000 --- a/doc/helpdb.jl +++ /dev/null @@ -1,16101 +0,0 @@ -# automatically generated from files in doc/stdlib/ -- do not edit here - -Any[ - -("Base","ndims","ndims(A) -> Integer - - Returns the number of dimensions of A - -"), - -("Base","size","size(A[, 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 = rand(2,3,4); - - julia> size(A, 2) - 3 - - julia> size(A,3,2) - (4,3) - -"), - -("Base","iseltype","iseltype(A, T) - - Tests whether A or its elements are of type T - -"), - -("Base","length","length(A) -> Integer - - Returns the number of elements in A - - length(collection) -> Integer - - For ordered, indexable collections, the maximum index \"i\" for - which \"getindex(collection, i)\" is valid. For unordered - collections, the number of elements. - - length(s) - - The number of characters in string \"s\". - -"), - -("Base","eachindex","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 (like \"Array\"), this is - simply the range \"1: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 non-integer indices). - - Example for a sparse 2-d array: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - 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] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 - -"), - -("Base","Base","Base.linearindexing(A) - - \"linearindexing\" defines how an AbstractArray most efficiently - accesses its elements. If \"Base.linearindexing(A)\" returns - \"Base.LinearFast()\", this means that linear indexing with only - one index is an efficient operation. If it instead returns - \"Base.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 - traits-based 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 define \"linearindexing\" in the - type-domain: - - Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() - -"), - -("Base","countnz","countnz(A) - - Counts the number of nonzero values in array A (dense or sparse). - Note that this is not a constant-time operation. For sparse - matrices, one should usually use \"nnz\", which returns the number - of stored values. - -"), - -("Base","conj!","conj!(A) - - Convert an array to its complex conjugate in-place - -"), - -("Base","stride","stride(A, k) - - Returns the distance in memory (in number of elements) between - adjacent elements in dimension k - -"), - -("Base","strides","strides(A) - - Returns a tuple of the memory strides in each dimension - -"), - -("Base","ind2sub","ind2sub(dims, index) -> subscripts - - Returns a tuple of subscripts into an array with dimensions - \"dims\", corresponding to the linear index \"index\" - - **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 index \"index\" - -"), - -("Base","ind2sub","ind2sub(dims, index) -> subscripts - - Returns a tuple of subscripts into an array with dimensions - \"dims\", corresponding to the linear index \"index\" - - **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 index \"index\" - -"), - -("Base","sub2ind","sub2ind(dims, i, j, k...) -> index - - The inverse of \"ind2sub\", returns the linear index corresponding - to the provided subscripts - -"), - -("Base","Array","Array(dims) - - \"Array{T}(dims)\" constructs an uninitialized dense array with - element type \"T\". \"dims\" may be a tuple or a series of integer - arguments. The syntax \"Array(T, dims)\" is also available, but - deprecated. - -"), - -("Base","getindex","getindex(type[, elements...]) - - Construct a 1-d array of the specified type. This is usually called - with the syntax \"Type[]\". Element values can be specified using - \"Type[a,b,c,...]\". - - getindex(A, inds...) - - Returns a subset of array \"A\" as specified by \"inds\", where - each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See - the manual section on *array indexing* for details. - - 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, ...)\". - -"), - -("Base","cell","cell(dims) - - Construct an uninitialized cell array (heterogeneous array). - \"dims\" can be either a tuple or a series of integer arguments. - -"), - -("Base","zeros","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. - -"), - -("Base","zeros","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. - -"), - -("Base","ones","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. - -"), - -("Base","ones","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. - -"), - -("Base","trues","trues(dims) - - Create a \"BitArray\" with all values set to true - -"), - -("Base","falses","falses(dims) - - Create a \"BitArray\" with all values set to false - -"), - -("Base","fill","fill(x, dims) - - Create an array filled with the value \"x\". For example, - \"fill(1.0, (10,10))\" returns a 10x10 array of floats, with each - element initialized to 1.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 evaluating \"Foo()\" once. - -"), - -("Base","fill!","fill!(A, x) - - Fill array \"A\" with the value \"x\". If \"x\" is an object - reference, all elements will refer to the same object. \"fill!(A, - Foo())\" will return \"A\" filled with the result of evaluating - \"Foo()\" once. - -"), - -("Base","reshape","reshape(A, dims) - - Create an array with the same data as the given array, but with - different dimensions. An implementation for a particular type of - array may choose whether the data is copied or shared. - -"), - -("Base","similar","similar(array, element_type, dims) - - Create an uninitialized array of the same type as the given array, - but with the specified element type and dimensions. The second and - third arguments are both optional. The \"dims\" argument may be a - tuple or a series of integer arguments. For some special - \"AbstractArray\" objects which are not real containers (like - ranges), this function returns a standard \"Array\" to allow - operating on elements. - -"), - -("Base","reinterpret","reinterpret(type, A) - - Change the type-interpretation of a block of memory. For example, - \"reinterpret(Float32, UInt32(7))\" interprets the 4 bytes - corresponding to \"UInt32(7)\" as a \"Float32\". For arrays, this - constructs an array with the same binary data as the given array, - but with the specified element type. - -"), - -("Base","eye","eye(n) - - n-by-n identity matrix - - eye(m, n) - - m-by-n identity matrix - - eye(A) - - Constructs an identity matrix of the same dimensions and type as - \"A\". - -"), - -("Base","eye","eye(n) - - n-by-n identity matrix - - eye(m, n) - - m-by-n identity matrix - - eye(A) - - Constructs an identity matrix of the same dimensions and type as - \"A\". - -"), - -("Base","eye","eye(n) - - n-by-n identity matrix - - eye(m, n) - - m-by-n identity matrix - - eye(A) - - Constructs an identity matrix of the same dimensions and type as - \"A\". - -"), - -("Base","linspace","linspace(start, stop, n=100) - - Construct a range of \"n\" linearly spaced elements from \"start\" - to \"stop\". - -"), - -("Base","logspace","logspace(start, stop, n=50) - - Construct a vector of \"n\" logarithmically spaced numbers from - \"10^start\" to \"10^stop\". - -"), - -("Base","broadcast","broadcast(f, As...) - - Broadcasts the arrays \"As\" to a common size by expanding - singleton dimensions, and returns an array of the results - \"f(as...)\" for each position. - -"), - -("Base","broadcast!","broadcast!(f, dest, As...) - - Like \"broadcast\", but store the result of \"broadcast(f, As...)\" - in the \"dest\" array. Note that \"dest\" is only used to store the - result, and does not supply arguments to \"f\" unless it is also - listed in the \"As\", as in \"broadcast!(f, A, A, B)\" to perform - \"A[:] = broadcast(f, A, B)\". - -"), - -("Base","bitbroadcast","bitbroadcast(f, As...) - - Like \"broadcast\", but allocates a \"BitArray\" to store the - result, rather then an \"Array\". - -"), - -("Base","broadcast_function","broadcast_function(f) - - Returns a function \"broadcast_f\" such that - \"broadcast_function(f)(As...) === broadcast(f, As...)\". Most - useful in the form \"const broadcast_f = broadcast_function(f)\". - -"), - -("Base","broadcast!_function","broadcast!_function(f) - - Like \"broadcast_function\", but for \"broadcast!\". - -"), - -("Base","getindex","getindex(type[, elements...]) - - Construct a 1-d array of the specified type. This is usually called - with the syntax \"Type[]\". Element values can be specified using - \"Type[a,b,c,...]\". - - getindex(A, inds...) - - Returns a subset of array \"A\" as specified by \"inds\", where - each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See - the manual section on *array indexing* for details. - - 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, ...)\". - -"), - -("Base","sub","sub(A, inds...) - - Like \"getindex()\", but returns a view into the parent array \"A\" - with the given indices instead of making a copy. Calling - \"getindex()\" or \"setindex!()\" on the returned \"SubArray\" - computes the indices to the parent array on the fly without - checking bounds. - -"), - -("Base","parent","parent(A) - - Returns the \"parent array\" of an array view type (e.g., - SubArray), or the array itself if it is not a view - -"), - -("Base","parentindexes","parentindexes(A) - - From an array view \"A\", returns the corresponding indexes in the - parent - -"), - -("Base","slicedim","slicedim(A, d, i) - - Return all the data of \"A\" where the index for dimension \"d\" - equals \"i\". Equivalent to \"A[:,:,...,i,:,:,...]\" where \"i\" is - in position \"d\". - -"), - -("Base","slice","slice(A, inds...) - - Returns a view of array \"A\" with the given indices like - \"sub()\", but drops all dimensions indexed with scalars. - -"), - -("Base","setindex!","setindex!(A, X, inds...) - - Store values from array \"X\" within some subset of \"A\" as - specified by \"inds\". - - 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, ...)\". - -"), - -("Base","broadcast_getindex","broadcast_getindex(A, inds...) - - Broadcasts the \"inds\" arrays to a common size like \"broadcast\", - and returns an array of the results \"A[ks...]\", where \"ks\" goes - over the positions in the broadcast. - -"), - -("Base","broadcast_setindex!","broadcast_setindex!(A, X, inds...) - - Broadcasts the \"X\" and \"inds\" arrays to a common size and - stores the value from each position in \"X\" at the indices given - by the same positions in \"inds\". - -"), - -("Base","cat","cat(dims, A...) - - Concatenate the input arrays along the specified dimensions in the - iterable \"dims\". For dimensions not in \"dims\", all input arrays - should have the same size, which will also be the size of the - output array along that dimension. For dimensions in \"dims\", the - size of the output array is the sum of the sizes of the input - arrays along that dimension. If \"dims\" is a single number, the - different arrays are tightly stacked along that dimension. If - \"dims\" is an iterable containing several dimensions, this allows - to construct block diagonal matrices and their higher-dimensional - 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 with *matrices[1]*, *matrices[2]*, ... as diagonal - blocks and matching zero blocks away from the diagonal. - -"), - -("Base","vcat","vcat(A...) - - Concatenate along dimension 1 - -"), - -("Base","hcat","hcat(A...) - - Concatenate along dimension 2 - -"), - -("Base","hvcat","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. For example, - \"[a b;c d e]\" calls \"hvcat((2,3),a,b,c,d,e)\". - - If the first argument is a single integer \"n\", then all block - rows are assumed to have \"n\" block columns. - -"), - -("Base","flipdim","flipdim(A, d) - - Reverse \"A\" in dimension \"d\". - -"), - -("Base","circshift","circshift(A, shifts) - - Circularly shift the data in an array. The second argument is a - vector giving the amount to shift in each dimension. - -"), - -("Base","find","find(A) - - Return a vector of the linear indexes of the non-zeros in \"A\" - (determined by \"A[i]!=0\"). A common use of this is to convert a - boolean array to an array of indexes of the \"true\" elements. - - find(f, A) - - Return a vector of the linear indexes of \"A\" where \"f\" returns - true. - -"), - -("Base","find","find(A) - - Return a vector of the linear indexes of the non-zeros in \"A\" - (determined by \"A[i]!=0\"). A common use of this is to convert a - boolean array to an array of indexes of the \"true\" elements. - - find(f, A) - - Return a vector of the linear indexes of \"A\" where \"f\" returns - true. - -"), - -("Base","findn","findn(A) - - Return a vector of indexes for each dimension giving the locations - of the non-zeros in \"A\" (determined by \"A[i]!=0\"). - -"), - -("Base","findnz","findnz(A) - - Return a tuple \"(I, J, V)\" where \"I\" and \"J\" are the row and - column indexes of the non-zero values in matrix \"A\", and \"V\" is - a vector of the non-zero values. - -"), - -("Base","findfirst","findfirst(A) - - Return the index of the first non-zero value in \"A\" (determined - by \"A[i]!=0\"). - - findfirst(A, v) - - Return the index of the first element equal to \"v\" in \"A\". - - findfirst(predicate, A) - - Return the index of the first element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findfirst","findfirst(A) - - Return the index of the first non-zero value in \"A\" (determined - by \"A[i]!=0\"). - - findfirst(A, v) - - Return the index of the first element equal to \"v\" in \"A\". - - findfirst(predicate, A) - - Return the index of the first element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findfirst","findfirst(A) - - Return the index of the first non-zero value in \"A\" (determined - by \"A[i]!=0\"). - - findfirst(A, v) - - Return the index of the first element equal to \"v\" in \"A\". - - findfirst(predicate, A) - - Return the index of the first element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findlast","findlast(A) - - Return the index of the last non-zero value in \"A\" (determined by - \"A[i]!=0\"). - - findlast(A, v) - - Return the index of the last element equal to \"v\" in \"A\". - - findlast(predicate, A) - - Return the index of the last element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findlast","findlast(A) - - Return the index of the last non-zero value in \"A\" (determined by - \"A[i]!=0\"). - - findlast(A, v) - - Return the index of the last element equal to \"v\" in \"A\". - - findlast(predicate, A) - - Return the index of the last element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findlast","findlast(A) - - Return the index of the last non-zero value in \"A\" (determined by - \"A[i]!=0\"). - - findlast(A, v) - - Return the index of the last element equal to \"v\" in \"A\". - - findlast(predicate, A) - - Return the index of the last element of \"A\" for which - \"predicate\" returns true. - -"), - -("Base","findnext","findnext(A, i) - - Find the next index >= \"i\" of a non-zero element of \"A\", or - \"0\" if not found. - - findnext(predicate, A, i) - - Find the next index >= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - - findnext(A, v, i) - - Find the next index >= \"i\" of an element of \"A\" equal to \"v\" - (using \"==\"), or \"0\" if not found. - -"), - -("Base","findnext","findnext(A, i) - - Find the next index >= \"i\" of a non-zero element of \"A\", or - \"0\" if not found. - - findnext(predicate, A, i) - - Find the next index >= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - - findnext(A, v, i) - - Find the next index >= \"i\" of an element of \"A\" equal to \"v\" - (using \"==\"), or \"0\" if not found. - -"), - -("Base","findnext","findnext(A, i) - - Find the next index >= \"i\" of a non-zero element of \"A\", or - \"0\" if not found. - - findnext(predicate, A, i) - - Find the next index >= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - - findnext(A, v, i) - - Find the next index >= \"i\" of an element of \"A\" equal to \"v\" - (using \"==\"), or \"0\" if not found. - -"), - -("Base","findprev","findprev(A, i) - - Find the previous index <= \"i\" of a non-zero element of \"A\", or - 0 if not found. - - findprev(predicate, A, i) - - Find the previous index <= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - - findprev(A, v, i) - - Find the previous index <= \"i\" of an element of \"A\" equal to - \"v\" (using \"==\"), or \"0\" if not found. - -"), - -("Base","findprev","findprev(A, i) - - Find the previous index <= \"i\" of a non-zero element of \"A\", or - 0 if not found. - - findprev(predicate, A, i) - - Find the previous index <= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - - findprev(A, v, i) - - Find the previous index <= \"i\" of an element of \"A\" equal to - \"v\" (using \"==\"), or \"0\" if not found. - -"), - -("Base","findprev","findprev(A, i) - - Find the previous index <= \"i\" of a non-zero element of \"A\", or - 0 if not found. - - findprev(predicate, A, i) - - Find the previous index <= \"i\" of an element of \"A\" for which - \"predicate\" returns true, or \"0\" if not found. - - findprev(A, v, i) - - Find the previous index <= \"i\" of an element of \"A\" equal to - \"v\" (using \"==\"), or \"0\" if not found. - -"), - -("Base","permutedims","permutedims(A, perm) - - Permute the dimensions of array \"A\". \"perm\" is a vector - specifying a permutation of length \"ndims(A)\". This is a - generalization of transpose for multi-dimensional arrays. Transpose - is equivalent to \"permutedims(A, [2,1])\". - -"), - -("Base","ipermutedims","ipermutedims(A, perm) - - Like \"permutedims()\", except the inverse of the given permutation - is applied. - -"), - -("Base","permutedims!","permutedims!(dest, src, perm) - - Permute the dimensions of array \"src\" and store the result in the - array \"dest\". \"perm\" is a vector specifying a permutation of - length \"ndims(src)\". The preallocated array \"dest\" should have - \"size(dest) == size(src)[perm]\" and is completely overwritten. No - in-place permutation is supported and unexpected results will - happen if *src* and *dest* have overlapping memory regions. - -"), - -("Base","squeeze","squeeze(A, dims) - - Remove the dimensions specified by \"dims\" from array \"A\". - Elements of \"dims\" must be unique and within the range - \"1:ndims(A)\". - -"), - -("Base","vec","vec(Array) -> Vector - - Vectorize an array using column-major convention. - -"), - -("Base","promote_shape","promote_shape(s1, s2) - - Check two array shapes for compatibility, allowing trailing - singleton dimensions, and return whichever shape has more - dimensions. - -"), - -("Base","checkbounds","checkbounds(array, indexes...) - - Throw an error if the specified indexes are not in bounds for the - given array. - -"), - -("Base","randsubseq","randsubseq(A, p) -> Vector - - Return a vector consisting of a random subsequence of the given - array \"A\", where each element of \"A\" is included (in order) - with independent probability \"p\". (Complexity is linear in - \"p*length(A)\", so this function is efficient even if \"p\" is - small and \"A\" is large.) Technically, this process is known as - \"Bernoulli sampling\" of \"A\". - -"), - -("Base","randsubseq!","randsubseq!(S, A, p) - - Like \"randsubseq\", but the results are stored in \"S\" (which is - resized as needed). - -"), - -("Base","cumprod","cumprod(A[, dim]) - - Cumulative product along a dimension \"dim\" (defaults to 1). See - also \"cumprod!()\" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). - -"), - -("Base","cumprod!","cumprod!(B, A[, dim]) - - Cumulative product of \"A\" along a dimension, storing the result - in \"B\". The dimension defaults to 1. - -"), - -("Base","cumsum","cumsum(A[, dim]) - - Cumulative sum along a dimension \"dim\" (defaults to 1). See also - \"cumsum!()\" to use a preallocated output array, both for - performance and to control the precision of the output (e.g. to - avoid overflow). - -"), - -("Base","cumsum!","cumsum!(B, A[, dim]) - - Cumulative sum of \"A\" along a dimension, storing the result in - \"B\". The dimension defaults to 1. - -"), - -("Base","cumsum_kbn","cumsum_kbn(A[, dim]) - - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. The - dimension defaults to 1. - -"), - -("Base","cummin","cummin(A[, dim]) - - Cumulative minimum along a dimension. The dimension defaults to 1. - -"), - -("Base","cummax","cummax(A[, dim]) - - Cumulative maximum along a dimension. The dimension defaults to 1. - -"), - -("Base","diff","diff(A[, dim]) - - Finite difference operator of matrix or vector. - -"), - -("Base","gradient","gradient(F[, h]) - - Compute differences along vector \"F\", using \"h\" as the spacing - between points. The default spacing is one. - -"), - -("Base","rot180","rot180(A) - - Rotate matrix \"A\" 180 degrees. - - rot180(A, k) - - Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. - If \"k\" is even, this is equivalent to a \"copy\". - -"), - -("Base","rot180","rot180(A) - - Rotate matrix \"A\" 180 degrees. - - rot180(A, k) - - Rotate matrix \"A\" 180 degrees an integer \"k\" number of times. - If \"k\" is even, this is equivalent to a \"copy\". - -"), - -("Base","rotl90","rotl90(A) - - Rotate matrix \"A\" left 90 degrees. - - rotl90(A, k) - - Rotate matrix \"A\" left 90 degrees an integer \"k\" number of - times. If \"k\" is zero or a multiple of four, this is equivalent - to a \"copy\". - -"), - -("Base","rotl90","rotl90(A) - - Rotate matrix \"A\" left 90 degrees. - - rotl90(A, k) - - Rotate matrix \"A\" left 90 degrees an integer \"k\" number of - times. If \"k\" is zero or a multiple of four, this is equivalent - to a \"copy\". - -"), - -("Base","rotr90","rotr90(A) - - Rotate matrix \"A\" right 90 degrees. - - rotr90(A, k) - - Rotate matrix \"A\" right 90 degrees an integer \"k\" number of - times. If \"k\" is zero or a multiple of four, this is equivalent - to a \"copy\". - -"), - -("Base","rotr90","rotr90(A) - - Rotate matrix \"A\" right 90 degrees. - - rotr90(A, k) - - Rotate matrix \"A\" right 90 degrees an integer \"k\" number of - times. If \"k\" is zero or a multiple of four, this is equivalent - to a \"copy\". - -"), - -("Base","reducedim","reducedim(f, A, dims[, initial]) - - Reduce 2-argument function \"f\" along dimensions of \"A\". - \"dims\" is a vector specifying the dimensions to reduce, and - \"initial\" is the initial value to use in the reductions. For *+*, - >>**<<*, *max* and *min* the *initial* argument is optional. - - The associativity of the reduction is implementation-dependent; if - you need a particular associativity, e.g. left-to-right, you should - write your own loop. See documentation for \"reduce\". - -"), - -("Base","mapreducedim","mapreducedim(f, op, A, dims[, initial]) - - Evaluates to the same as *reducedim(op, map(f, A), dims, - f(initial))*, but is generally faster because the intermediate - array is avoided. - -"), - -("Base","mapslices","mapslices(f, A, dims) - - Transform the given dimensions of array \"A\" using function \"f\". - \"f\" is called on each slice of \"A\" of the form - \"A[...,:,...,:,...]\". \"dims\" is an integer vector specifying - where the colons go in this expression. The results are - concatenated along the remaining dimensions. For example, if - \"dims\" is \"[1,2]\" and A is 4-dimensional, \"f\" is called on - \"A[:,:,i,j]\" for all \"i\" and \"j\". - -"), - -("Base","sum_kbn","sum_kbn(A) - - Returns the sum of all array elements, using the Kahan-Babuska- - Neumaier compensated summation algorithm for additional accuracy. - -"), - -("Base","cartesianmap","cartesianmap(f, dims) - - Given a \"dims\" tuple of integers \"(m, n, ...)\", call \"f\" on - all combinations of integers in the ranges \"1:m\", \"1:n\", etc. - - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 - -"), - -("Base","nthperm","nthperm(v, k) - - Compute the kth lexicographic permutation of a vector. - - nthperm(p) - - Return the \"k\" that generated permutation \"p\". Note that - \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". - -"), - -("Base","nthperm","nthperm(v, k) - - Compute the kth lexicographic permutation of a vector. - - nthperm(p) - - Return the \"k\" that generated permutation \"p\". Note that - \"nthperm(nthperm([1:n], k)) == k\" for \"1 <= k <= factorial(n)\". - -"), - -("Base","nthperm!","nthperm!(v, k) - - In-place version of \"nthperm()\". - -"), - -("Base","randperm","randperm([rng], n) - - Construct a random permutation of length \"n\". The optional - \"rng\" argument specifies a random number generator, see *Random - Numbers*. - -"), - -("Base","invperm","invperm(v) - - Return the inverse permutation of v. - -"), - -("Base","isperm","isperm(v) -> Bool - - Returns true if v is a valid permutation. - -"), - -("Base","permute!","permute!(v, p) - - Permute vector \"v\" in-place, according to permutation \"p\". No - checking is done to verify that \"p\" is a permutation. - - To return a new permutation, use \"v[p]\". Note that this is - generally faster than \"permute!(v,p)\" for large vectors. - -"), - -("Base","ipermute!","ipermute!(v, p) - - Like permute!, but the inverse of the given permutation is applied. - -"), - -("Base","randcycle","randcycle([rng], n) - - Construct a random cyclic permutation of length \"n\". The optional - \"rng\" argument specifies a random number generator, see *Random - Numbers*. - -"), - -("Base","shuffle","shuffle([rng], v) - - Return a randomly permuted copy of \"v\". The optional \"rng\" - argument specifies a random number generator, see *Random Numbers*. - -"), - -("Base","shuffle!","shuffle!([rng], v) - - In-place version of \"shuffle()\". - -"), - -("Base","reverse","reverse(v[, start=1[, stop=length(v)]]) - - Return a copy of \"v\" reversed from start to stop. - -"), - -("Base","reverseind","reverseind(v, i) - - Given an index \"i\" in \"reverse(v)\", return the corresponding - index in \"v\" so that \"v[reverseind(v,i)] == reverse(v)[i]\". - (This can be nontrivial in the case where \"v\" is a Unicode - string.) - -"), - -("Base","reverse!","reverse!(v[, start=1[, stop=length(v)]]) -> v - - In-place version of \"reverse()\". - -"), - -("Base","combinations","combinations(array, n) - - Generate all combinations of \"n\" elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - \"collect(combinations(array,n))\" to get an array of all - combinations. - -"), - -("Base","permutations","permutations(array) - - Generate all permutations of an indexable object. Because the - number of permutations can be very large, this function returns an - iterator object. Use \"collect(permutations(array))\" to get an - array of all permutations. - -"), - -("Base","partitions","partitions(n) - - Generate all integer arrays that sum to \"n\". Because the number - of partitions can be very large, this function returns an iterator - object. Use \"collect(partitions(n))\" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using \"length(partitions(n))\". - - partitions(n, m) - - Generate all arrays of \"m\" integers that sum to \"n\". Because - the number of partitions can be very large, this function returns - an iterator object. Use \"collect(partitions(n,m))\" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using \"length(partitions(n,m))\". - - partitions(array) - - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - \"collect(partitions(array))\" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using \"length(partitions(array))\". - - partitions(array, m) - - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use \"collect(partitions(array,m))\" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using \"length(partitions(array,m))\". - -"), - -("Base","partitions","partitions(n) - - Generate all integer arrays that sum to \"n\". Because the number - of partitions can be very large, this function returns an iterator - object. Use \"collect(partitions(n))\" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using \"length(partitions(n))\". - - partitions(n, m) - - Generate all arrays of \"m\" integers that sum to \"n\". Because - the number of partitions can be very large, this function returns - an iterator object. Use \"collect(partitions(n,m))\" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using \"length(partitions(n,m))\". - - partitions(array) - - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - \"collect(partitions(array))\" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using \"length(partitions(array))\". - - partitions(array, m) - - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use \"collect(partitions(array,m))\" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using \"length(partitions(array,m))\". - -"), - -("Base","partitions","partitions(n) - - Generate all integer arrays that sum to \"n\". Because the number - of partitions can be very large, this function returns an iterator - object. Use \"collect(partitions(n))\" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using \"length(partitions(n))\". - - partitions(n, m) - - Generate all arrays of \"m\" integers that sum to \"n\". Because - the number of partitions can be very large, this function returns - an iterator object. Use \"collect(partitions(n,m))\" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using \"length(partitions(n,m))\". - - partitions(array) - - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - \"collect(partitions(array))\" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using \"length(partitions(array))\". - - partitions(array, m) - - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use \"collect(partitions(array,m))\" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using \"length(partitions(array,m))\". - -"), - -("Base","partitions","partitions(n) - - Generate all integer arrays that sum to \"n\". Because the number - of partitions can be very large, this function returns an iterator - object. Use \"collect(partitions(n))\" to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using \"length(partitions(n))\". - - partitions(n, m) - - Generate all arrays of \"m\" integers that sum to \"n\". Because - the number of partitions can be very large, this function returns - an iterator object. Use \"collect(partitions(n,m))\" to get an - array of all partitions. The number of partitions to generate can - be efficiently computed using \"length(partitions(n,m))\". - - partitions(array) - - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - \"collect(partitions(array))\" to get an array of all partitions. - The number of partitions to generate can be efficiently computed - using \"length(partitions(array))\". - - partitions(array, m) - - Generate all set partitions of the elements of an array into - exactly m subsets, represented as arrays of arrays. Because the - number of partitions can be very large, this function returns an - iterator object. Use \"collect(partitions(array,m))\" to get an - array of all partitions. The number of partitions into m subsets is - equal to the Stirling number of the second kind and can be - efficiently computed using \"length(partitions(array,m))\". - -"), - -("Base","bitpack","bitpack(A::AbstractArray{T, N}) -> BitArray - - Converts a numeric array to a packed boolean array - -"), - -("Base","bitunpack","bitunpack(B::BitArray{N}) -> Array{Bool,N} - - Converts a packed boolean array to an array of booleans - -"), - -("Base","flipbits!","flipbits!(B::BitArray{N}) -> BitArray{N} - - Performs a bitwise not operation on B. See *~ operator*. - -"), - -("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on \"src\" and put the result - into \"dest\". - - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on B. - -"), - -("Base","rol!","rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on \"src\" and put the result - into \"dest\". - - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation on B. - -"), - -("Base","rol","rol(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a left rotation operation. - -"), - -("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on \"src\" and put the result - into \"dest\". - - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on B. - -"), - -("Base","ror!","ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on \"src\" and put the result - into \"dest\". - - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation on B. - -"), - -("Base","ror","ror(B::BitArray{1}, i::Integer) -> BitArray{1} - - Performs a right rotation operation. - -"), - -("Base","sparse","sparse(I, J, V[, m, n, combine]) - - Create a sparse matrix \"S\" of dimensions \"m x n\" such that - \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to - combine duplicates. If \"m\" and \"n\" are not specified, they are - set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" - function is not supplied, duplicates are added by default. - - sparse(A) - - Convert an AbstractMatrix \"A\" into a sparse matrix. - -"), - -("Base","sparsevec","sparsevec(I, V[, m, combine]) - - Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] - = V[k]\". Duplicates are combined using the \"combine\" function, - which defaults to \"+\" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. - - sparsevec(D::Dict[, m]) - - Create a sparse matrix of size \"m x 1\" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. - - sparsevec(A) - - Convert a dense vector \"A\" into a sparse matrix of size \"m x - 1\". In julia, sparse vectors are really just sparse matrices with - one column. - -"), - -("Base","sparsevec","sparsevec(I, V[, m, combine]) - - Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] - = V[k]\". Duplicates are combined using the \"combine\" function, - which defaults to \"+\" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. - - sparsevec(D::Dict[, m]) - - Create a sparse matrix of size \"m x 1\" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. - - sparsevec(A) - - Convert a dense vector \"A\" into a sparse matrix of size \"m x - 1\". In julia, sparse vectors are really just sparse matrices with - one column. - -"), - -("Base","issparse","issparse(S) - - Returns \"true\" if \"S\" is sparse, and \"false\" otherwise. - -"), - -("Base","sparse","sparse(I, J, V[, m, n, combine]) - - Create a sparse matrix \"S\" of dimensions \"m x n\" such that - \"S[I[k], J[k]] = V[k]\". The \"combine\" function is used to - combine duplicates. If \"m\" and \"n\" are not specified, they are - set to \"max(I)\" and \"max(J)\" respectively. If the \"combine\" - function is not supplied, duplicates are added by default. - - sparse(A) - - Convert an AbstractMatrix \"A\" into a sparse matrix. - -"), - -("Base","sparsevec","sparsevec(I, V[, m, combine]) - - Create a sparse matrix \"S\" of size \"m x 1\" such that \"S[I[k]] - = V[k]\". Duplicates are combined using the \"combine\" function, - which defaults to \"+\" if it is not provided. In julia, sparse - vectors are really just sparse matrices with one column. Given - Julia's Compressed Sparse Columns (CSC) storage format, a sparse - column matrix with one column is sparse, whereas a sparse row - matrix with one row ends up being dense. - - sparsevec(D::Dict[, m]) - - Create a sparse matrix of size \"m x 1\" where the row values are - keys from the dictionary, and the nonzero values are the values - from the dictionary. - - sparsevec(A) - - Convert a dense vector \"A\" into a sparse matrix of size \"m x - 1\". In julia, sparse vectors are really just sparse matrices with - one column. - -"), - -("Base","full","full(S) - - Convert a sparse matrix \"S\" into a dense matrix. - - full(F) - - Reconstruct the matrix \"A\" from the factorization - \"F=factorize(A)\". - - full(QRCompactWYQ[, thin=true]) -> Matrix - - Converts an orthogonal or unitary matrix stored as a - \"QRCompactWYQ\" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. - - Optionally takes a \"thin\" Boolean argument, which if \"true\" - omits the columns that span the rows of \"R\" in the QR - factorization that are zero. The resulting matrix is the \"Q\" in a - thin QR factorization (sometimes called the reduced QR - factorization). If \"false\", returns a \"Q\" that spans all rows - of \"R\" in its corresponding QR factorization. - -"), - -("Base","nnz","nnz(A) - - Returns the number of stored (filled) elements in a sparse matrix. - -"), - -("Base","spzeros","spzeros(m, n) - - Create a sparse matrix of size \"m x n\". This sparse matrix will - not contain any nonzero values. No storage will be allocated for - nonzero values during construction. - -"), - -("Base","spones","spones(S) - - Create a sparse matrix with the same structure as that of \"S\", - but with every nonzero element having the value \"1.0\". - -"), - -("Base","speye","speye(type, m[, n]) - - Create a sparse identity matrix of specified type of size \"m x - m\". In case \"n\" is supplied, create a sparse identity matrix of - size \"m x n\". - -"), - -("Base","spdiagm","spdiagm(B, d[, m, n]) - - Construct a sparse diagonal matrix. \"B\" is a tuple of vectors - containing the diagonals and \"d\" is a tuple containing the - positions of the diagonals. In the case the input contains only one - diagonaly, \"B\" can be a vector (instead of a tuple) and \"d\" can - be the diagonal position (instead of a tuple), defaulting to 0 - (diagonal). Optionally, \"m\" and \"n\" specify the size of the - resulting sparse matrix. - -"), - -("Base","sprand","sprand([rng], m, n, p[, rfn]) - - Create a random \"m\" by \"n\" sparse matrix, in which the - probability of any element being nonzero is independently given by - \"p\" (and hence the mean density of nonzeros is also exactly - \"p\"). Nonzero values are sampled from the distribution specified - by \"rfn\". The uniform distribution is used in case \"rfn\" is not - specified. The optional \"rng\" argument specifies a random number - generator, see *Random Numbers*. - -"), - -("Base","sprandn","sprandn(m, n, p) - - Create a random \"m\" by \"n\" sparse matrix with the specified - (independent) probability \"p\" of any entry being nonzero, where - nonzero values are sampled from the normal distribution. - -"), - -("Base","sprandbool","sprandbool(m, n, p) - - Create a random \"m\" by \"n\" sparse boolean matrix with the - specified (independent) probability \"p\" of any entry being - \"true\". - -"), - -("Base","etree","etree(A[, post]) - - Compute the elimination tree of a symmetric sparse matrix \"A\" - from \"triu(A)\" and, optionally, its post-ordering permutation. - -"), - -("Base","symperm","symperm(A, p) - - Return the symmetric permutation of A, which is \"A[p,p]\". A - should be symmetric and sparse, where only the upper triangular - part of the matrix is stored. This algorithm ignores the lower - triangular part of the matrix. Only the upper triangular part of - the result is returned as well. - -"), - -("Base","nonzeros","nonzeros(A) - - Return a vector of the structural nonzero values in sparse matrix - \"A\". This includes zeros that are explicitly stored in the sparse - matrix. The returned vector points directly to the internal nonzero - storage of \"A\", and any modifications to the returned vector will - mutate \"A\" as well. See \"rowvals(A)\" and \"nzrange(A, col)\". - -"), - -("Base","rowvals","rowvals(A) - - Return a vector of the row indices of \"A\", and any modifications - to the returned vector will mutate \"A\" as well. Given the - internal storage format of sparse matrices, providing access to how - the row indices are stored internally can be useful in conjuction - with iterating over structural nonzero values. See \"nonzeros(A)\" - and \"nzrange(A, col)\". - -"), - -("Base","nzrange","nzrange(A, col) - - Return the range of indices to the structural nonzero values of a - sparse matrix column. In conjunction with \"nonzeros(A)\" and - \"rowvals(A)\", 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 - -"), - -("Base","exit","exit([code]) - - Quit (or control-D at the prompt). The default exit code is zero, - indicating that the processes completed successfully. - -"), - -("Base","quit","quit() - - Quit the program indicating that the processes completed - successfully. This function calls \"exit(0)\" (see \"exit()\"). - -"), - -("Base","atexit","atexit(f) - - Register a zero-argument function to be called at exit. - -"), - -("Base","atreplinit","atreplinit(f) - - Register a one-argument function to be called before the REPL - interface is initialized in interactive sessions; this is useful to - customize the interface. The argument of \"f\" is the REPL object. - This function should be called from within the \".juliarc.jl\" - initialization file. - -"), - -("Base","isinteractive","isinteractive() -> Bool - - Determine whether Julia is running an interactive session. - -"), - -("Base","whos","whos([Module,] [pattern::Regex]) - - Print information about exported global variables in a module, - optionally restricted to those matching \"pattern\". - -"), - -("Base","edit","edit(file::AbstractString[, line]) - - Edit a file optionally providing a line number to edit at. Returns - to the julia prompt when you quit the editor. - - edit(function[, types]) - - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. - -"), - -("Base","edit","edit(file::AbstractString[, line]) - - Edit a file optionally providing a line number to edit at. Returns - to the julia prompt when you quit the editor. - - edit(function[, types]) - - Edit the definition of a function, optionally specifying a tuple of - types to indicate which method to edit. - -"), - -("Base","@edit","@edit() - - Evaluates the arguments to the function call, determines their - types, and calls the \"edit\" function on the resulting expression - -"), - -("Base","less","less(file::AbstractString[, line]) - - Show a file using the default pager, optionally providing a - starting line number. Returns to the julia prompt when you quit the - pager. - - less(function[, types]) - - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. - -"), - -("Base","less","less(file::AbstractString[, line]) - - Show a file using the default pager, optionally providing a - starting line number. Returns to the julia prompt when you quit the - pager. - - less(function[, types]) - - Show the definition of a function using the default pager, - optionally specifying a tuple of types to indicate which method to - see. - -"), - -("Base","@less","@less() - - Evaluates the arguments to the function call, determines their - types, and calls the \"less\" function on the resulting expression - -"), - -("Base","clipboard","clipboard(x) - - Send a printed form of \"x\" to the operating system clipboard - (\"copy\"). - - clipboard() -> AbstractString - - Return a string with the contents of the operating system clipboard - (\"paste\"). - -"), - -("Base","clipboard","clipboard(x) - - Send a printed form of \"x\" to the operating system clipboard - (\"copy\"). - - clipboard() -> AbstractString - - Return a string with the contents of the operating system clipboard - (\"paste\"). - -"), - -("Base","require","require(file::AbstractString...) - - Load source files once, in the context of the \"Main\" module, on - every active node, searching standard locations for files. - \"require\" is considered a top-level operation, so it sets the - current \"include\" path but does not use it to search for files - (see help for \"include\"). This function is typically used to load - library code, and is implicitly called by \"using\" to load - packages. - - When searching for files, \"require\" first looks in the current - working directory, then looks for package code under \"Pkg.dir()\", - then tries paths in the global array \"LOAD_PATH\". - -"), - -("Base","reload","reload(file::AbstractString) - - Like \"require\", except forces loading of files regardless of - whether they have been loaded before. Typically used when - interactively developing libraries. - -"), - -("Base","include","include(\"file.jl\") - - Evaluate the contents of a source file in the current context. - During including, a task-local include path is set to the directory - containing the file. Nested calls to \"include\" will search - relative to that path. All paths refer to files on node 1 when - running in parallel, and files will be fetched from node 1. This - function is typically used to load source interactively, or to - combine files in packages that are broken into multiple source - files. - -"), - -("Base","include_string","include_string(code::AbstractString) - - Like \"include\", except reads code from the given string rather - than from a file. Since there is no file path involved, no path - processing or fetching from node 1 is done. - -"), - -("Base","help","help(name) - - Get help for a function. \"name\" can be an object or a string. - -"), - -("Base","apropos","apropos(string) - - Search documentation for functions related to \"string\". - -"), - -("Base","which","which(f, types) - - Returns the method of \"f\" (a \"Method\" object) that would be - called for arguments of the given types. - - If \"types\" is an abstract type, then the method that would be - called by \"invoke\" is returned. - - which(symbol) - - Return the module in which the binding for the variable referenced - by \"symbol\" was created. - -"), - -("Base","which","which(f, types) - - Returns the method of \"f\" (a \"Method\" object) that would be - called for arguments of the given types. - - If \"types\" is an abstract type, then the method that would be - called by \"invoke\" is returned. - - which(symbol) - - Return the module in which the binding for the variable referenced - by \"symbol\" was created. - -"), - -("Base","@which","@which() - - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the \"Method\" object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the \"which\" function. - -"), - -("Base","methods","methods(f[, types]) - - Returns the method table for \"f\". - - If \"types\" is specified, returns an array of methods whose types - match. - -"), - -("Base","methodswith","methodswith(typ[, module or function][, showparents]) - - Return an array of methods with an argument of type \"typ\". If - optional \"showparents\" is \"true\", also return arguments with a - parent type of \"typ\", excluding type \"Any\". - - The optional second argument restricts the search to a particular - module or function. - -"), - -("Base","@show","@show() - - Show an expression and result, returning the result - -"), - -("Base","versioninfo","versioninfo([verbose::Bool]) - - Print information about the version of Julia in use. If the - \"verbose\" argument is true, detailed system information is shown - as well. - -"), - -("Base","workspace","workspace() - - Replace the top-level module (\"Main\") with a new one, providing a - clean workspace. The previous \"Main\" module is made available as - \"LastMain\". A previously-loaded package can be accessed using a - statement such as \"using LastMain.Package\". - - This function should only be used interactively. - -"), - -("Base","ans","ans - - A variable referring to the last computed value, automatically set - at the interactive prompt. - -"), - -("Base","is","is(x, y) -> Bool - - ===(x, y) -> Bool ≡(x, y) -> Bool - - Determine whether \"x\" and \"y\" are identical, in the sense that - no program could distinguish them. Compares mutable objects by - address in memory, and compares immutable objects (such as numbers) - by contents at the bit level. This function is sometimes called - \"egal\". - -"), - -("Base","isa","isa(x, type) -> Bool - - Determine whether \"x\" is of the given \"type\". - -"), - -("Base","isequal","isequal(x, y) - - Similar to \"==\", except treats all floating-point \"NaN\" values - as equal to each other, and treats \"-0.0\" as unequal to \"0.0\". - The default implementation of \"isequal\" calls \"==\", so if you - have a type that doesn't have these floating-point subtleties then - you probably only need to define \"==\". - - \"isequal\" is the comparison function used by hash tables - (\"Dict\"). \"isequal(x,y)\" must imply that \"hash(x) == - hash(y)\". - - This typically means that if you define your own \"==\" function - then you must define a corresponding \"hash\" (and vice versa). - Collections typically implement \"isequal\" by calling \"isequal\" - recursively on all contents. - - Scalar types generally do not need to implement \"isequal\" - separate from \"==\", unless they represent floating-point numbers - amenable to a more efficient implementation than that provided as a - generic fallback (based on \"isnan\", \"signbit\", and \"==\"). - -"), - -("Base","isless","isless(x, y) - - Test whether \"x\" is less than \"y\", according to a canonical - total order. Values that are normally unordered, such as \"NaN\", - are ordered in an arbitrary but consistent fashion. This is the - default comparison used by \"sort\". Non-numeric types with a - canonical total order should implement this function. Numeric types - only need to implement it if they have special values such as - \"NaN\". - -"), - -("Base","ifelse","ifelse(condition::Bool, x, y) - - Return \"x\" if \"condition\" is true, otherwise return \"y\". This - differs from \"?\" or \"if\" in that it is an ordinary function, so - all the arguments are evaluated first. In some cases, using - \"ifelse\" instead of an \"if\" statement can eliminate the branch - in generated code and provide higher performance in tight loops. - -"), - -("Base","lexcmp","lexcmp(x, y) - - Compare \"x\" and \"y\" lexicographically and return -1, 0, or 1 - depending on whether \"x\" is less than, equal to, or greater than - \"y\", respectively. This function should be defined for - lexicographically comparable types, and \"lexless\" will call - \"lexcmp\" by default. - -"), - -("Base","lexless","lexless(x, y) - - Determine whether \"x\" is lexicographically less than \"y\". - -"), - -("Base","typeof","typeof(x) - - Get the concrete type of \"x\". - -"), - -("Base","tuple","tuple(xs...) - - Construct a tuple of the given objects. - -"), - -("Base","ntuple","ntuple(f::Function, n) - - Create a tuple of length \"n\", computing each element as \"f(i)\", - where \"i\" is the index of the element. - -"), - -("Base","object_id","object_id(x) - - Get a unique integer id for \"x\". \"object_id(x)==object_id(y)\" - if and only if \"is(x,y)\". - -"), - -("Base","hash","hash(x[, h]) - - Compute an integer hash code such that \"isequal(x,y)\" implies - \"hash(x)==hash(y)\". The optional second argument \"h\" is a hash - code to be mixed with the result. - - New types should implement the 2-argument form, typically by - calling the 2-argument \"hash\" method recursively in order to mix - hashes of the contents with each other (and with \"h\"). Typically, - any type that implements \"hash\" should also implement its own - \"==\" (hence \"isequal\") to guarantee the property mentioned - above. - -"), - -("Base","finalizer","finalizer(x, function) - - Register a function \"f(x)\" to be called when there are no - program-accessible references to \"x\". The behavior of this - function is unpredictable if \"x\" is of a bits type. - -"), - -("Base","finalize","finalize(x) - - Immediately run finalizers registered for object \"x\". - -"), - -("Base","copy","copy(x) - - Create a shallow copy of \"x\": the outer structure is copied, but - not all internal values. For example, copying an array produces a - new array with identically-same elements as the original. - -"), - -("Base","deepcopy","deepcopy(x) - - Create a deep copy of \"x\": everything is copied recursively, - resulting in a fully independent object. For example, deep-copying - an array produces a new array whose elements are deep copies of the - original elements. Calling *deepcopy* on an object should generally - have the same effect as serializing and then deserializing it. - - As a special case, functions can only be actually deep-copied if - they are anonymous, otherwise they are just copied. The difference - is only relevant in the case of closures, i.e. functions which may - contain hidden internal references. - - While it isn't normally necessary, user-defined types can override - the default \"deepcopy\" behavior by defining a specialized version - of the function \"deepcopy_internal(x::T, dict::ObjectIdDict)\" - (which shouldn't otherwise be used), where \"T\" is the type to be - specialized for, and \"dict\" keeps track of objects copied so far - within the recursion. Within the definition, \"deepcopy_internal\" - should be used in place of \"deepcopy\", and the \"dict\" variable - should be updated as appropriate before returning. - -"), - -("Base","isdefined","isdefined([object], index | symbol) - - Tests whether an assignable location is defined. The arguments can - be an array and index, a composite object and field name (as a - symbol), or a module and a symbol. With a single symbol argument, - tests whether a global variable with that name is defined in - \"current_module()\". - -"), - -("Base","convert","convert(T, x) - - Convert \"x\" to a value of type \"T\". - - If \"T\" is an \"Integer\" type, an \"InexactError\" will be raised - if \"x\" is not representable by \"T\", for example if \"x\" is not - integer-valued, or is outside the range supported by \"T\". - - julia> convert(Int, 3.0) - 3 - - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 - - If \"T\" is a \"FloatingPoint\" or \"Rational\" type, then it will - return the closest value to \"x\" representable by \"T\". - - julia> x = 1/3 - 0.3333333333333333 - - julia> convert(Float32, x) - 0.33333334f0 - - julia> convert(Rational{Int32}, x) - 1//3 - - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 - -"), - -("Base","promote","promote(xs...) - - Convert all arguments to their common promotion type (if any), and - return them all (as a tuple). - -"), - -("Base","oftype","oftype(x, y) - - Convert \"y\" to the type of \"x\" (\"convert(typeof(x), y)\"). - -"), - -("Base","widen","widen(type | x) - - If the argument is a type, return a \"larger\" type (for numeric - types, this will be a type with at least as much range and - precision as the argument, and usually more). Otherwise the - argument \"x\" is converted to \"widen(typeof(x))\". - - julia> widen(Int32) - Int64 - - julia> widen(1.5f0) - 1.5 - -"), - -("Base","identity","identity(x) - - The identity function. Returns its argument. - -"), - -("Base","super","super(T::DataType) - - Return the supertype of DataType T - -"), - -("Base","issubtype","issubtype(type1, type2) - - True if and only if all values of \"type1\" are also of \"type2\". - Can also be written using the \"<:\" infix operator as \"type1 <: - type2\". - -"), - -("Base","issubtype","issubtype(type1, type2) - - True if and only if all values of \"type1\" are also of \"type2\". - Can also be written using the \"<:\" infix operator as \"type1 <: - type2\". - -"), - -("Base","subtypes","subtypes(T::DataType) - - Return a list of immediate subtypes of DataType T. Note that all - currently loaded subtypes are included, including those not visible - in the current module. - -"), - -("Base","typemin","typemin(type) - - The lowest value representable by the given (real) numeric type. - -"), - -("Base","typemax","typemax(type) - - The highest value representable by the given (real) numeric type. - -"), - -("Base","realmin","realmin(type) - - The smallest in absolute value non-subnormal value representable by - the given floating-point type - -"), - -("Base","realmax","realmax(type) - - The highest finite value representable by the given floating-point - type - -"), - -("Base","maxintfloat","maxintfloat(type) - - The largest integer losslessly representable by the given floating- - point type - -"), - -("Base","sizeof","sizeof(type) - - Size, in bytes, of the canonical binary representation of the given - type, if any. - - sizeof(s::AbstractString) - - The number of bytes in string \"s\". - -"), - -("Base","eps","eps([type]) - - The distance between 1.0 and the next larger representable - floating-point value of \"type\". Only floating-point types are - sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" - is returned. - - eps(x) - - The distance between \"x\" and the next larger representable - floating-point value of the same type as \"x\". - -"), - -("Base","eps","eps([type]) - - The distance between 1.0 and the next larger representable - floating-point value of \"type\". Only floating-point types are - sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" - is returned. - - eps(x) - - The distance between \"x\" and the next larger representable - floating-point value of the same type as \"x\". - -"), - -("Base","promote_type","promote_type(type1, type2) - - Determine a type big enough to hold values of each argument type - without loss, whenever possible. In some cases, where no type - exists to which both types can be promoted losslessly, some loss is - tolerated; for example, \"promote_type(Int64,Float64)\" returns - \"Float64\" even though strictly, not all \"Int64\" values can be - represented exactly as \"Float64\" values. - -"), - -("Base","promote_rule","promote_rule(type1, type2) - - Specifies what type should be used by \"promote\" when given values - of types \"type1\" and \"type2\". This function should not be - called directly, but should have definitions added to it for new - types as appropriate. - -"), - -("Base","getfield","getfield(value, name::Symbol) - - Extract a named field from a value of composite type. The syntax - \"a.b\" calls \"getfield(a, :b)\", and the syntax \"a.(b)\" calls - \"getfield(a, b)\". - -"), - -("Base","setfield!","setfield!(value, name::Symbol, x) - - Assign \"x\" to a named field in \"value\" of composite type. The - syntax \"a.b = c\" calls \"setfield!(a, :b, c)\", and the syntax - \"a.(b) = c\" calls \"setfield!(a, b, c)\". - -"), - -("Base","fieldoffsets","fieldoffsets(type) - - The byte offset of each field of a type relative to the data start. - For example, we could use it in the following manner to summarize - information about a struct type: - - julia> structinfo(T) = [zip(fieldoffsets(T),fieldnames(T),T.types)...]; - - julia> structinfo(StatStruct) - 12-element Array{Tuple{Int64,Symbol,DataType},1}: - (0,:device,UInt64) - (8,:inode,UInt64) - (16,:mode,UInt64) - (24,:nlink,Int64) - (32,:uid,UInt64) - (40,:gid,UInt64) - (48,:rdev,UInt64) - (56,:size,Int64) - (64,:blksize,Int64) - (72,:blocks,Int64) - (80,:mtime,Float64) - (88,:ctime,Float64) - -"), - -("Base","fieldtype","fieldtype(type, name::Symbol | index::Int) - - Determine the declared type of a field (specified by name or index) - in a composite type. - -"), - -("Base","isimmutable","isimmutable(v) - - True if value \"v\" is immutable. See *Immutable Composite Types* - for a discussion of immutability. Note that this function works on - values, so if you give it a type, it will tell you that a value of - \"DataType\" is mutable. - -"), - -("Base","isbits","isbits(T) - - True if \"T\" is a \"plain data\" type, meaning it is immutable and - contains no references to other values. Typical examples are - numeric types such as \"UInt8\", \"Float64\", and - \"Complex{Float64}\". - - julia> isbits(Complex{Float64}) - true - - julia> isbits(Complex) - false - -"), - -("Base","isleaftype","isleaftype(T) - - Determine whether \"T\" is a concrete type that can have instances, - meaning its only subtypes are itself and \"None\" (but \"T\" itself - is not \"None\"). - -"), - -("Base","typejoin","typejoin(T, S) - - Compute a type that contains both \"T\" and \"S\". - -"), - -("Base","typeintersect","typeintersect(T, S) - - Compute a type that contains the intersection of \"T\" and \"S\". - Usually this will be the smallest such type or one close to it. - -"), - -("Base","Val{c}","Val{c}() - - Create a \"value type\" out of \"c\", which must be an \"isbits\" - value. The intent of this construct is to be able to dispatch on - constants, e.g., \"f(Val{false})\" allows you to dispatch directly - (at compile-time) to an implementation \"f(::Type{Val{false}})\", - without having to test the boolean value at runtime. - -"), - -("","@enum EnumName EnumValue1[=x] EnumValue2[=y]","@enum EnumName EnumValue1[=x] EnumValue2[=y] - - Create an \"Enum\" type with name \"EnumName\" and enum member - values of \"EnumValue1\" and \"EnumValue2\" with optional assigned - values of \"x\" and \"y\", respectively. \"EnumName\" can be used - just like other types and enum member values as regular values, - such as - - julia> @enum FRUIT apple=1 orange=2 kiwi=3 - - julia> f(x::FRUIT) = \"I'm a FRUIT with value: \$(Int(x))\" - f (generic function with 1 method) - - julia> f(apple) - \"I'm a FRUIT with value: 1\" - -"), - -("Base","instances","instances(T::Type) - - Return a collection of all instances of the given type, if - applicable. Mostly used for enumerated types (see \"@enum\"). - -"), - -("Base","method_exists","method_exists(f, Tuple type) -> Bool - - Determine whether the given generic function has a method matching - the given \"Tuple\" of argument types. - - julia> method_exists(length, Tuple{Array}) - true - -"), - -("Base","applicable","applicable(f, args...) -> Bool - - Determine whether the given generic function has a method - applicable to the given arguments. - - julia> function f(x, y) - x + y - end; - - julia> applicable(f, 1) - false - - julia> applicable(f, 1, 2) - true - -"), - -("Base","invoke","invoke(f, (types...), args...) - - Invoke a method for the given generic function matching the - specified types (as a tuple), on the specified arguments. The - arguments must be compatible with the specified types. This allows - invoking a method other than the most specific matching method, - which is useful when the behavior of a more general definition is - explicitly needed (often as part of the implementation of a more - specific method of the same function). - -"), - -("Base","|>","|>(x, f) - - Applies a function to the preceding argument. This allows for easy - function chaining. - - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 - -"), - -("Base","call","call(x, args...) - - If \"x\" is not a \"Function\", then \"x(args...)\" is equivalent - to \"call(x, args...)\". This means that function-like behavior - can be added to any type by defining new \"call\" methods. - -"), - -("Base","eval","eval([m::Module], expr::Expr) - - Evaluate an expression in the given module and return the result. - Every module (except those defined with \"baremodule\") has its own - 1-argument definition of \"eval\", which evaluates expressions in - that module. - -"), - -("Base","@eval","@eval() - - Evaluate an expression and return the value. - -"), - -("Base","evalfile","evalfile(path::AbstractString) - - Load the file using \"include\", evaluate all expressions, and - return the value of the last one. - -"), - -("Base","esc","esc(e::ANY) - - Only valid in the context of an Expr returned from a macro. - Prevents the macro hygiene pass from turning embedded variables - into gensym variables. See the *Macros* section of the - Metaprogramming chapter of the manual for more details and - examples. - -"), - -("Base","gensym","gensym([tag]) - - Generates a symbol which will not conflict with other variable - names. - -"), - -("Base","@gensym","@gensym() - - Generates a gensym symbol for a variable. For example, \"@gensym x - y\" is transformed into \"x = gensym(\"x\"); y = gensym(\"y\")\". - -"), - -("Base","parse","parse(str, start; greedy=true, raise=true) - - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If \"greedy\" is true (default), - \"parse\" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is - true (default), syntax errors other than incomplete expressions - will raise an error. If \"raise\" is false, \"parse\" will return - an expression that will raise an error upon evaluation. - - parse(str; raise=true) - - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If \"raise\" is true (default), syntax errors will - raise an error; otherwise, \"parse\" will return an expression that - will raise an error upon evaluation. - - parse(type, str[, base]) - - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. - -"), - -("Base","parse","parse(str, start; greedy=true, raise=true) - - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If \"greedy\" is true (default), - \"parse\" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is - true (default), syntax errors other than incomplete expressions - will raise an error. If \"raise\" is false, \"parse\" will return - an expression that will raise an error upon evaluation. - - parse(str; raise=true) - - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If \"raise\" is true (default), syntax errors will - raise an error; otherwise, \"parse\" will return an expression that - will raise an error upon evaluation. - - parse(type, str[, base]) - - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. - -"), - -("Base","Nullable","Nullable(x) - - Wrap value \"x\" in an object of type \"Nullable\", which indicates - whether a value is present. \"Nullable(x)\" yields a non-empty - wrapper, and \"Nullable{T}()\" yields an empty instance of a - wrapper that might contain a value of type \"T\". - -"), - -("Base","get","get(x) - - Attempt to access the value of the \"Nullable\" object, \"x\". - Returns the value if it is present; otherwise, throws a - \"NullException\". - - get(x, y) - - Attempt to access the value of the \"Nullable{T}\" object, \"x\". - Returns the value if it is present; otherwise, returns \"convert(T, - y)\". - - 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. - - 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 - -"), - -("Base","get","get(x) - - Attempt to access the value of the \"Nullable\" object, \"x\". - Returns the value if it is present; otherwise, throws a - \"NullException\". - - get(x, y) - - Attempt to access the value of the \"Nullable{T}\" object, \"x\". - Returns the value if it is present; otherwise, returns \"convert(T, - y)\". - - 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. - - 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 - -"), - -("Base","isnull","isnull(x) - - Is the \"Nullable\" object \"x\" null, i.e. missing a value? - -"), - -("Base","run","run(command) - - Run a command object, constructed with backticks. Throws an error - if anything goes wrong, including the process exiting with a non- - zero status. - -"), - -("Base","spawn","spawn(command) - - Run a command object asynchronously, returning the resulting - \"Process\" object. - -"), - -("Base","DevNull","DevNull - - Used in a stream redirect to discard all data written to it. - Essentially equivalent to /dev/null on Unix or NUL on Windows. - Usage: \"run(`cat test.txt` |> DevNull)\" - -"), - -("Base","success","success(command) - - Run a command object, constructed with backticks, and tell whether - it was successful (exited with a code of 0). An exception is raised - if the process cannot be started. - -"), - -("Base","process_running","process_running(p::Process) - - Determine whether a process is currently running. - -"), - -("Base","process_exited","process_exited(p::Process) - - Determine whether a process has exited. - -"), - -("Base","kill","kill(p::Process, signum=SIGTERM) - - Send a signal to a process. The default is to terminate the - process. - - kill(manager::FooManager, pid::Int, config::WorkerConfig) - - Implemented by cluster managers. It is called on the master - process, by \"rmprocs\". It should cause the remote worker - specified by \"pid\" to exit. - \"Base.kill(manager::ClusterManager.....)\" executes a remote - \"exit()\" on \"pid\" - -"), - -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) - - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. - - open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) - - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". - - open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - - open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: - - +–––+–––––––––––––––––-+ | r | read - | +–––+–––––––––––––––––-+ | r+ | read, write - | +–––+–––––––––––––––––-+ | w | write, create, truncate - | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate - | +–––+–––––––––––––––––-+ | a | write, create, append - | +–––+–––––––––––––––––-+ | a+ | read, write, create, append - | +–––+–––––––––––––––––-+ - - open(f::function, args...) - - Apply the function \"f\" to the result of \"open(args...)\" and - close the resulting file descriptor upon completion. - - **Example**: \"open(readall, \"file.txt\")\" - -"), - -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) - - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. - - open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) - - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". - - open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - - open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: - - +–––+–––––––––––––––––-+ | r | read - | +–––+–––––––––––––––––-+ | r+ | read, write - | +–––+–––––––––––––––––-+ | w | write, create, truncate - | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate - | +–––+–––––––––––––––––-+ | a | write, create, append - | +–––+–––––––––––––––––-+ | a+ | read, write, create, append - | +–––+–––––––––––––––––-+ - - open(f::function, args...) - - Apply the function \"f\" to the result of \"open(args...)\" and - close the resulting file descriptor upon completion. - - **Example**: \"open(readall, \"file.txt\")\" - -"), - -("Base","Sys","Sys.set_process_title(title::AbstractString) - - Set the process title. No-op on some operating systems. (not - exported) - -"), - -("Base","Sys","Sys.get_process_title() - - Get the process title. On some systems, will always return empty - string. (not exported) - -"), - -("Base","readandwrite","readandwrite(command) - - Starts running a command asynchronously, and returns a tuple - (stdout,stdin,process) of the output stream and input stream of the - process, and the process object itself. - -"), - -("Base","ignorestatus","ignorestatus(command) - - Mark a command object so that running it will not throw an error if - the result code is non-zero. - -"), - -("Base","detach","detach(command) - - Mark a command object so that it will be run in a new process - group, allowing it to outlive the julia process, and not have - Ctrl-C interrupts passed to it. - -"), - -("Base","setenv","setenv(command, env; dir=working_dir) - - Set environment variables to use when running the given command. - \"env\" is either a dictionary mapping strings to strings, an array - of strings of the form \"\"var=val\"\", or zero or more - \"\"var\"=>val\" pair arguments. In order to modify (rather than - replace) the existing environment, create \"env\" by \"copy(ENV)\" - and then setting \"env[\"var\"]=val\" as desired, or use - \"withenv\". - - The \"dir\" keyword argument can be used to specify a working - directory for the command. - -"), - -("Base","withenv","withenv(f::Function, kv::Pair...) - - Execute \"f()\" in an environment that is temporarily modified (not - replaced as in \"setenv\") by zero or more \"\"var\"=>val\" - arguments \"kv\". \"withenv\" is generally used via the - \"withenv(kv...) do ... end\" syntax. A value of \"nothing\" can - be used to temporarily unset an environment variable (if it is - set). When \"withenv\" returns, the original environment has been - restored. - -"), - -("Base","pipe","pipe(from, to, ...) - - Create a pipeline from a data source to a destination. The source - and destination can be commands, I/O streams, strings, or results - of other \"pipe\" calls. At least one argument must be a command. - Strings refer to filenames. When called with more than two - arguments, they are chained together from left to right. For - example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". - This provides a more concise way to specify multi-stage pipelines. - - **Examples**: * \"run(pipe(\"ls\", \"grep xyz\"))\" - - * \"run(pipe(`ls`, \"out.txt\"))\" - - * \"run(pipe(\"out.txt\", `grep xyz`))\" - - pipe(command; stdin, stdout, stderr, append=false) - - Redirect I/O to or from the given \"command\". Keyword arguments - specify which of the command's streams should be redirected. - \"append\" controls whether file output appends to the file. This - is a more general version of the 2-argument \"pipe\" function. - \"pipe(from, to)\" is equivalent to \"pipe(from, stdout=to)\" when - \"from\" is a command, and to \"pipe(to, stdin=from)\" when - \"from\" is another kind of data source. - - **Examples**: * \"run(pipe(\"dothings\", stdout=\"out.txt\", - stderr=\"errs.txt\"))\" - - * \"run(pipe(`update`, stdout=\"log.txt\", append=true))\" - -"), - -("Base","pipe","pipe(from, to, ...) - - Create a pipeline from a data source to a destination. The source - and destination can be commands, I/O streams, strings, or results - of other \"pipe\" calls. At least one argument must be a command. - Strings refer to filenames. When called with more than two - arguments, they are chained together from left to right. For - example \"pipe(a,b,c)\" is equivalent to \"pipe(pipe(a,b),c)\". - This provides a more concise way to specify multi-stage pipelines. - - **Examples**: * \"run(pipe(\"ls\", \"grep xyz\"))\" - - * \"run(pipe(`ls`, \"out.txt\"))\" - - * \"run(pipe(\"out.txt\", `grep xyz`))\" - - pipe(command; stdin, stdout, stderr, append=false) - - Redirect I/O to or from the given \"command\". Keyword arguments - specify which of the command's streams should be redirected. - \"append\" controls whether file output appends to the file. This - is a more general version of the 2-argument \"pipe\" function. - \"pipe(from, to)\" is equivalent to \"pipe(from, stdout=to)\" when - \"from\" is a command, and to \"pipe(to, stdin=from)\" when - \"from\" is another kind of data source. - - **Examples**: * \"run(pipe(\"dothings\", stdout=\"out.txt\", - stderr=\"errs.txt\"))\" - - * \"run(pipe(`update`, stdout=\"log.txt\", append=true))\" - -"), - -("Base","gethostname","gethostname() -> AbstractString - - Get the local machine's host name. - -"), - -("Base","getipaddr","getipaddr() -> AbstractString - - Get the IP address of the local machine, as a string of the form - \"x.x.x.x\". - -"), - -("Base","getpid","getpid() -> Int32 - - Get julia's process ID. - -"), - -("Base","time","time() - - Get the system time in seconds since the epoch, with fairly high - (typically, microsecond) resolution. - -"), - -("Base","time_ns","time_ns() - - Get the time in nanoseconds. The time corresponding to 0 is - undefined, and wraps every 5.8 years. - -"), - -("Base","tic","tic() - - Set a timer to be read by the next call to \"toc()\" or \"toq()\". - The macro call \"@time expr\" can also be used to time evaluation. - -"), - -("Base","toc","toc() - - Print and return the time elapsed since the last \"tic()\". - -"), - -("Base","toq","toq() - - Return, but do not print, the time elapsed since the last - \"tic()\". - -"), - -("Base","@time","@time() - - A macro to execute an expression, printing the time it took to - execute, the number of allocations, and the total number of bytes - its execution caused to be allocated, before returning the value of - the expression. - -"), - -("Base","@timev","@timev() - - This is a verbose version of the \"@time\" macro, it first prints - the same information as \"@time\", then any non-zero memory - allocation counters, and then returns the value of the expression. - -"), - -("Base","@timed","@timed() - - A macro to execute an expression, and return the value of the - expression, elapsed time, total bytes allocated, garbage collection - time, and an object with various memory allocation counters. - -"), - -("Base","@elapsed","@elapsed() - - A macro to evaluate an expression, discarding the resulting value, - instead returning the number of seconds it took to execute as a - floating-point number. - -"), - -("Base","@allocated","@allocated() - - A macro to evaluate an expression, discarding the resulting value, - instead returning the total number of bytes allocated during - evaluation of the expression. Note: the expression is evaluated - inside a local function, instead of the current context, in order - to eliminate the effects of compilation, however, there still may - be some allocations due to JIT compilation. This also makes the - results inconsistent with the \"@time\" macros, which do not try to - adjust for the effects of compilation. - -"), - -("Base","EnvHash","EnvHash() -> EnvHash - - A singleton of this type provides a hash table interface to - environment variables. - -"), - -("Base","ENV","ENV - - Reference to the singleton \"EnvHash\", providing a dictionary - interface to system environment variables. - -"), - -("Base","@unix","@unix() - - Given \"@unix? a : b\", do \"a\" on Unix systems (including Linux - and OS X) and \"b\" elsewhere. See documentation for Handling - Platform Variations in the Calling C and Fortran Code section of - the manual. - -"), - -("Base","@osx","@osx() - - Given \"@osx? a : b\", do \"a\" on OS X and \"b\" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. - -"), - -("Base","@linux","@linux() - - Given \"@linux? a : b\", do \"a\" on Linux and \"b\" elsewhere. See - documentation for Handling Platform Variations in the Calling C and - Fortran Code section of the manual. - -"), - -("Base","@windows","@windows() - - Given \"@windows? a : b\", do \"a\" on Windows and \"b\" elsewhere. - See documentation for Handling Platform Variations in the Calling C - and Fortran Code section of the manual. - -"), - -("Base","error","error(message::AbstractString) - - Raise an \"ErrorException\" with the given message - -"), - -("Base","throw","throw(e) - - Throw an object as an exception - -"), - -("Base","rethrow","rethrow([e]) - - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - \"catch\" block). - -"), - -("Base","backtrace","backtrace() - - Get a backtrace object for the current program point. - -"), - -("Base","catch_backtrace","catch_backtrace() - - Get the backtrace of the current exception, for use within - \"catch\" blocks. - -"), - -("Base","assert","assert(cond) - - Throw an \"AssertionError\" if \"cond\" is false. Also available as - the macro \"@assert expr\". - -"), - -("","@assert cond [text]","@assert cond [text] - - Throw an \"AssertionError\" if \"cond\" is false. Preferred syntax - for writing assertions. - -"), - -("Base","ArgumentError","ArgumentError(msg) - - The parameters to a function call do not match a valid signature. - -"), - -("Base","AssertionError","AssertionError([msg]) - - The asserted condition did not evalutate to \"true\". - -"), - -("Base","BoundsError","BoundsError([a][, i]) - - An indexing operation into an array, \"a\", tried to access an out- - of-bounds element, \"i\". - -"), - -("Base","DimensionMismatch","DimensionMismatch([msg]) - - The objects called do not have matching dimensionality. - -"), - -("Base","DivideError","DivideError() - - Integer division was attempted with a denominator value of 0. - -"), - -("Base","DomainError","DomainError() - - The arguments to a function or constructor are outside the valid - domain. - -"), - -("Base","EOFError","EOFError() - - No more data was available to read from a file or stream. - -"), - -("Base","ErrorException","ErrorException(msg) - - Generic error type. The error message, in the *.msg* field, may - provide more specific details. - -"), - -("Base","InexactError","InexactError() - - Type conversion cannot be done exactly. - -"), - -("Base","InterruptException","InterruptException() - - The process was stopped by a terminal interrupt (CTRL+C). - -"), - -("Base","KeyError","KeyError(key) - - An indexing operation into an \"Associative\" (\"Dict\") or \"Set\" - like object tried to access or delete a non-existent element. - -"), - -("Base","LoadError","LoadError(file::AbstractString, line::Int, error) - - An error occurred while *including*, *requiring*, or *using* a - file. The error specifics should be available in the *.error* - field. - -"), - -("Base","MethodError","MethodError(f, args) - - A method with the required type signature does not exist in the - given generic function. - -"), - -("Base","NullException","NullException() - - An attempted access to a \"Nullable\" with no defined value. - -"), - -("Base","OutOfMemoryError","OutOfMemoryError() - - An operation allocated too much memory for either the system or the - garbage collector to handle properly. - -"), - -("Base","ReadOnlyMemoryError","ReadOnlyMemoryError() - - An operation tried to write to memory that is read-only. - -"), - -("Base","OverflowError","OverflowError() - - The result of an expression is too large for the specified type and - will cause a wraparound. - -"), - -("Base","ParseError","ParseError(msg) - - The expression passed to the *parse* function could not be - interpreted as a valid Julia expression. - -"), - -("Base","ProcessExitedException","ProcessExitedException() - - After a client Julia process has exited, further attempts to - reference the dead child will throw this exception. - -"), - -("Base","StackOverflowError","StackOverflowError() - - The function call grew beyond the size of the call stack. This - usually happens when a call recurses infinitely. - -"), - -("Base","SystemError","SystemError(prefix::AbstractString[, errnum::Int32]) - - A system call failed with an error code (in the \"errno\" global - variable). - -"), - -("Base","TypeError","TypeError(func::Symbol, context::AbstractString, expected::Type, got) - - A type assertion failure, or calling an intrinsic function with an - incorrect argument type. - -"), - -("Base","UndefRefError","UndefRefError() - - The item or field is not defined for the given object. - -"), - -("Base","UndefVarError","UndefVarError(var::Symbol) - - A symbol in the current scope is not defined. - -"), - -("Base","Timer","Timer(callback::Function, delay, repeat=0) - - Create a timer to call the given callback function. The callback is - passed one argument, the timer object itself. The callback will be - invoked after the specified initial delay, and then repeating with - the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is - only triggered once. Times are in seconds. A timer is stopped and - has its resources freed by calling \"close\" on it. - - Timer(delay, repeat=0) - - Create a timer that wakes up tasks waiting for it (by calling - \"wait\" on the timer object) at a specified interval. - -"), - -("Base","Timer","Timer(callback::Function, delay, repeat=0) - - Create a timer to call the given callback function. The callback is - passed one argument, the timer object itself. The callback will be - invoked after the specified initial delay, and then repeating with - the given \"repeat\" interval. If \"repeat\" is \"0\", the timer is - only triggered once. Times are in seconds. A timer is stopped and - has its resources freed by calling \"close\" on it. - - Timer(delay, repeat=0) - - Create a timer that wakes up tasks waiting for it (by calling - \"wait\" on the timer object) at a specified interval. - -"), - -("Base","module_name","module_name(m::Module) -> Symbol - - Get the name of a module as a symbol. - -"), - -("Base","module_parent","module_parent(m::Module) -> Module - - Get a module's enclosing module. \"Main\" is its own parent. - -"), - -("Base","current_module","current_module() -> Module - - Get the *dynamically* current module, which is the module code is - currently being read from. In general, this is not the same as the - module containing the call to this function. - -"), - -("Base","fullname","fullname(m::Module) - - Get the fully-qualified name of a module as a tuple of symbols. For - example, \"fullname(Base.Pkg)\" gives \"(:Base,:Pkg)\", and - \"fullname(Main)\" gives \"()\". - -"), - -("Base","names","names(x::Module[, all=false[, imported=false]]) - - Get an array of the names exported by a module, with optionally - more module globals according to the additional parameters. - -"), - -("Base","nfields","nfields(x::DataType) -> Int - - Get the number of fields of a data type. - -"), - -("Base","fieldnames","fieldnames(x::DataType) - - Get an array of the fields of a data type. - -"), - -("Base","isconst","isconst([m::Module], s::Symbol) -> Bool - - Determine whether a global is declared \"const\" in a given module. - The default module argument is \"current_module()\". - -"), - -("Base","isgeneric","isgeneric(f::Function) -> Bool - - Determine whether a function is generic. - -"), - -("Base","function_name","function_name(f::Function) -> Symbol - - Get the name of a generic function as a symbol, or \":anonymous\". - -"), - -("Base","function_module","function_module(f::Function, types) -> Module - - Determine the module containing a given definition of a generic - function. - -"), - -("Base","functionloc","functionloc(f::Function, types) - - Returns a tuple \"(filename,line)\" giving the location of a method - definition. - - functionloc(m::Method) - - Returns a tuple \"(filename,line)\" giving the location of a method - definition. - -"), - -("Base","functionloc","functionloc(f::Function, types) - - Returns a tuple \"(filename,line)\" giving the location of a method - definition. - - functionloc(m::Method) - - Returns a tuple \"(filename,line)\" giving the location of a method - definition. - -"), - -("Base","gc","gc() - - Perform garbage collection. This should not generally be used. - -"), - -("Base","gc_enable","gc_enable(on::Bool) - - Control whether garbage collection is enabled using a boolean - argument (true for enabled, false for disabled). Returns previous - GC state. Disabling garbage collection should be used only with - extreme caution, as it can cause memory use to grow without bound. - -"), - -("Base","macroexpand","macroexpand(x) - - Takes the expression x and returns an equivalent expression with - all macros removed (expanded). - -"), - -("Base","expand","expand(x) - - Takes the expression x and returns an equivalent expression in - lowered form - -"), - -("Base","code_lowered","code_lowered(f, types) - - Returns an array of lowered ASTs for the methods matching the given - generic function and type signature. - -"), - -("Base","@code_lowered","@code_lowered() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_lowered()\" on the resulting expression - -"), - -("Base","code_typed","code_typed(f, types; optimize=true) - - Returns an array of lowered and type-inferred ASTs for the methods - matching the given generic function and type signature. The keyword - argument \"optimize\" controls whether additional optimizations, - such as inlining, are also applied. - -"), - -("Base","@code_typed","@code_typed() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_typed()\" on the resulting expression - -"), - -("Base","code_warntype","code_warntype(f, types) - - Displays lowered and type-inferred ASTs for the methods matching - the given generic function and type signature. The ASTs are - annotated in such a way as to cause \"non-leaf\" types to be - emphasized (if color is available, displayed in red). This serves - as a warning of potential type instability. Not all non-leaf types - are particularly problematic for performance, so the results need - to be used judiciously. See *@code_warntype* for more information. - -"), - -("Base","@code_warntype","@code_warntype() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_warntype()\" on the resulting expression - -"), - -("Base","code_llvm","code_llvm(f, types) - - Prints the LLVM bitcodes generated for running the method matching - the given generic function and type signature to \"STDOUT\". - - All metadata and dbg.* calls are removed from the printed bitcode. - Use code_llvm_raw for the full IR. - -"), - -("Base","@code_llvm","@code_llvm() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_llvm()\" on the resulting expression - -"), - -("Base","code_native","code_native(f, types) - - Prints the native assembly instructions generated for running the - method matching the given generic function and type signature to - STDOUT. - -"), - -("Base","@code_native","@code_native() - - Evaluates the arguments to the function call, determines their - types, and calls \"code_native()\" on the resulting expression - -"), - -("Base","precompile","precompile(f, args::Tuple{Vararg{Any}}) - - Compile the given function \"f\" for the argument tuple (of types) - \"args\", but do not execute it. - -"), - -("Base","ccall","ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - - Call function in C-exported shared library, specified by - \"(function name, library)\" tuple, where each component is an - AbstractString or :Symbol. - - Note that the argument type tuple must be a literal tuple, and not - a tuple-valued variable or expression. Alternatively, ccall may - also be used to call a function pointer, such as one returned by - dlsym. - - Each \"ArgumentValue\" to the \"ccall\" will be converted to the - corresponding \"ArgumentType\", by automatic insertion of calls to - \"unsafe_convert(ArgumentType, cconvert(ArgumentType, - ArgumentValue))\". (see also the documentation for each of these - functions for further details). In most cases, this simply results - in a call to \"convert(ArgumentType, ArgumentValue)\" - -"), - -("Base","cglobal","cglobal((symbol, library)[, type=Void]) - - Obtain a pointer to a global variable in a C-exported shared - library, specified exactly as in \"ccall\". Returns a - \"Ptr{Type}\", defaulting to \"Ptr{Void}\" if no Type argument is - supplied. The values can be read or written by \"unsafe_load\" or - \"unsafe_store!\", respectively. - -"), - -("Base","cfunction","cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - - Generate C-callable function pointer from Julia function. Type - annotation of the return value in the callback function is a must - for situations where Julia cannot infer the return type - automatically. - - For example: - - function foo() - # body - - retval::Float64 - end - - bar = cfunction(foo, Float64, ()) - -"), - -("Base","unsafe_convert","unsafe_convert(T, x) - - Convert \"x\" to a value of type \"T\" - - In cases where \"convert\" would need to take a Julia object and - turn it into a \"Ptr\", this function should be used to define and - perform that conversion. - - Be careful to ensure that a julia reference to \"x\" exists as long - as the result of this function will be used. Accordingly, the - argument \"x\" to this function should never be an expression, only - a variable name or field reference. For example, \"x=a.b.c\" is - acceptable, but \"x=[a,b,c]\" is not. - - The \"unsafe\" prefix on this function indicates that using the - result of this function after the \"x\" argument to this function - is no longer accessible to the program may cause undefined - behavior, including program corruption or segfaults, at any later - time. - -"), - -("Base","cconvert","cconvert(T, x) - - Convert \"x\" to a value of type \"T\", typically by calling - \"convert(T,x)\" - - In cases where \"x\" cannot be safely converted to \"T\", unlike - \"convert\", \"cconvert\" may return an object of a type different - from \"T\", which however is suitable for \"unsafe_convert\" to - handle. - - Neither \"convert\" nor \"cconvert\" should take a Julia object and - turn it into a \"Ptr\". - -"), - -("Base","unsafe_load","unsafe_load(p::Ptr{T}, i::Integer) - - Load a value of type \"T\" from the address of the ith element - (1-indexed) starting at \"p\". This is equivalent to the C - expression \"p[i-1]\". - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointer \"p\" to ensure that it is valid. - Incorrect usage may segfault your program or return garbage - answers, in the same manner as C. - -"), - -("Base","unsafe_store!","unsafe_store!(p::Ptr{T}, x, i::Integer) - - Store a value of type \"T\" to the address of the ith element - (1-indexed) starting at \"p\". This is equivalent to the C - expression \"p[i-1] = x\". - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointer \"p\" to ensure that it is valid. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - -"), - -("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - - Copy \"N\" elements from a source pointer to a destination, with no - checking. The size of an element is determined by the type of the - pointers. - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointers \"dest\" and \"src\" to ensure that - they are valid. Incorrect usage may corrupt or segfault your - program, in the same manner as C. - - unsafe_copy!(dest::Array, do, src::Array, so, N) - - Copy \"N\" elements from a source array to a destination, starting - at offset \"so\" in the source and \"do\" in the destination - (1-indexed). - - The \"unsafe\" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - -"), - -("Base","unsafe_copy!","unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - - Copy \"N\" elements from a source pointer to a destination, with no - checking. The size of an element is determined by the type of the - pointers. - - The \"unsafe\" prefix on this function indicates that no validation - is performed on the pointers \"dest\" and \"src\" to ensure that - they are valid. Incorrect usage may corrupt or segfault your - program, in the same manner as C. - - unsafe_copy!(dest::Array, do, src::Array, so, N) - - Copy \"N\" elements from a source array to a destination, starting - at offset \"so\" in the source and \"do\" in the destination - (1-indexed). - - The \"unsafe\" prefix on this function indicates that no validation - is performed to ensure that N is inbounds on either array. - Incorrect usage may corrupt or segfault your program, in the same - manner as C. - -"), - -("Base","copy!","copy!(dest, src) - - Copy all elements from collection \"src\" to array \"dest\". - Returns \"dest\". - - copy!(dest, do, src, so, N) - - Copy \"N\" elements from collection \"src\" starting at offset - \"so\", to array \"dest\" starting at offset \"do\". Returns - \"dest\". - -"), - -("Base","copy!","copy!(dest, src) - - Copy all elements from collection \"src\" to array \"dest\". - Returns \"dest\". - - copy!(dest, do, src, so, N) - - Copy \"N\" elements from collection \"src\" starting at offset - \"so\", to array \"dest\" starting at offset \"do\". Returns - \"dest\". - -"), - -("Base","pointer","pointer(array[, index]) - - Get the native address of an array or string element. Be careful to - ensure that a julia reference to \"a\" exists as long as this - pointer will be used. This function is \"unsafe\" like - \"unsafe_convert\". - - Calling \"Ref(array[, index])\" is generally preferable to this - function. - -"), - -("Base","pointer_to_array","pointer_to_array(pointer, dims[, take_ownership::Bool]) - - Wrap a native pointer as a Julia Array object. The pointer element - type determines the array element type. \"own\" optionally - specifies whether Julia should take ownership of the memory, - calling \"free\" on the pointer when the array is no longer - referenced. - -"), - -("Base","pointer_from_objref","pointer_from_objref(object_instance) - - Get the memory address of a Julia object as a \"Ptr\". The - existence of the resulting \"Ptr\" will not protect the object from - garbage collection, so you must ensure that the object remains - referenced for the whole time that the \"Ptr\" will be used. - -"), - -("Base","unsafe_pointer_to_objref","unsafe_pointer_to_objref(p::Ptr) - - Convert a \"Ptr\" to an object reference. Assumes the pointer - refers to a valid heap-allocated Julia object. If this is not the - case, undefined behavior results, hence this function is considered - \"unsafe\" and should be used with care. - -"), - -("Base","disable_sigint","disable_sigint(f::Function) - - Disable Ctrl-C handler during execution of a function, for calling - external code that is not interrupt safe. Intended to be called - using \"do\" block syntax as follows: - - disable_sigint() do - # interrupt-unsafe code - ... - end - -"), - -("Base","reenable_sigint","reenable_sigint(f::Function) - - Re-enable Ctrl-C handler during execution of a function. - Temporarily reverses the effect of \"disable_sigint\". - -"), - -("Base","systemerror","systemerror(sysfunc, iftrue) - - Raises a \"SystemError\" for \"errno\" with the descriptive string - \"sysfunc\" if \"bool\" is true - -"), - -("Base","Ptr{T}","Ptr{T} - - A memory address referring to data of type \"T\". However, there is - no guarantee that the memory is actually valid, or that it actually - represents data of the specified type. - -"), - -("Base","Ref{T}","Ref{T} - - An object that safely references data of type \"T\". This type is - guaranteed to point to valid, Julia-allocated memory of the correct - type. The underlying data is protected from freeing by the garbage - collector as long as the \"Ref\" itself is referenced. - - When passed as a \"ccall\" argument (either as a \"Ptr\" or \"Ref\" - type), a \"Ref\" object will be converted to a native pointer to - the data it references. - - There is no invalid (NULL) \"Ref\". - -"), - -("Base","Cchar","Cchar - - Equivalent to the native \"char\" c-type - -"), - -("Base","Cuchar","Cuchar - - Equivalent to the native \"unsigned char\" c-type (UInt8) - -"), - -("Base","Cshort","Cshort - - Equivalent to the native \"signed short\" c-type (Int16) - -"), - -("Base","Cushort","Cushort - - Equivalent to the native \"unsigned short\" c-type (UInt16) - -"), - -("Base","Cint","Cint - - Equivalent to the native \"signed int\" c-type (Int32) - -"), - -("Base","Cuint","Cuint - - Equivalent to the native \"unsigned int\" c-type (UInt32) - -"), - -("Base","Clong","Clong - - Equivalent to the native \"signed long\" c-type - -"), - -("Base","Culong","Culong - - Equivalent to the native \"unsigned long\" c-type - -"), - -("Base","Clonglong","Clonglong - - Equivalent to the native \"signed long long\" c-type (Int64) - -"), - -("Base","Culonglong","Culonglong - - Equivalent to the native \"unsigned long long\" c-type (UInt64) - -"), - -("Base","Cintmax_t","Cintmax_t - - Equivalent to the native \"intmax_t\" c-type (Int64) - -"), - -("Base","Cuintmax_t","Cuintmax_t - - Equivalent to the native \"uintmax_t\" c-type (UInt64) - -"), - -("Base","Csize_t","Csize_t - - Equivalent to the native \"size_t\" c-type (UInt) - -"), - -("Base","Cssize_t","Cssize_t - - Equivalent to the native \"ssize_t\" c-type - -"), - -("Base","Cptrdiff_t","Cptrdiff_t - - Equivalent to the native \"ptrdiff_t\" c-type (Int) - -"), - -("Base","Coff_t","Coff_t - - Equivalent to the native \"off_t\" c-type - -"), - -("Base","Cwchar_t","Cwchar_t - - Equivalent to the native \"wchar_t\" c-type (Int32) - -"), - -("Base","Cfloat","Cfloat - - Equivalent to the native \"float\" c-type (Float32) - -"), - -("Base","Cdouble","Cdouble - - Equivalent to the native \"double\" c-type (Float64) - -"), - -("Base","start","start(iter) -> state - - Get initial iteration state for an iterable object - -"), - -("Base","done","done(iter, state) -> Bool - - Test whether we are done iterating - -"), - -("Base","next","next(iter, state) -> item, state - - For a given iterable object and iteration state, return the current - item and the next iteration state - -"), - -("Base","zip","zip(iters...) - - For a set of iterable objects, returns an iterable of tuples, where - the \"i\"th tuple contains the \"i\"th component of each input - iterable. - - Note that \"zip()\" is its own inverse: - \"collect(zip(zip(a...)...)) == collect(a)\". - -"), - -("Base","enumerate","enumerate(iter) - - An iterator that yields \"(i, x)\" where \"i\" is an index starting - at 1, and \"x\" is the \"i\"th value from the given iterator. It's - useful when you need not only the values \"x\" over which you are - iterating, but also the index \"i\" of the iterations. - - julia> a = [\"a\", \"b\", \"c\"]; - - julia> for (index, value) in enumerate(a) - println(\"\\\$index \\\$value\") - end - 1 a - 2 b - 3 c - -"), - -("Base","rest","rest(iter, state) - - An iterator that yields the same elements as \"iter\", but starting - at the given \"state\". - -"), - -("Base","countfrom","countfrom(start=1, step=1) - - An iterator that counts forever, starting at \"start\" and - incrementing by \"step\". - -"), - -("Base","take","take(iter, n) - - An iterator that generates at most the first \"n\" elements of - \"iter\". - -"), - -("Base","drop","drop(iter, n) - - An iterator that generates all but the first \"n\" elements of - \"iter\". - -"), - -("Base","cycle","cycle(iter) - - An iterator that cycles through \"iter\" forever. - -"), - -("Base","repeated","repeated(x[, n::Int]) - - An iterator that generates the value \"x\" forever. If \"n\" is - specified, generates \"x\" that many times (equivalent to - \"take(repeated(x), n)\"). - -"), - -("Base","isempty","isempty(collection) -> Bool - - Determine whether a collection is empty (has no elements). - - julia> isempty([]) - true - - julia> isempty([1 2 3]) - false - -"), - -("Base","empty!","empty!(collection) -> collection - - Remove all elements from a \"collection\". - -"), - -("Base","length","length(A) -> Integer - - Returns the number of elements in A - - length(collection) -> Integer - - For ordered, indexable collections, the maximum index \"i\" for - which \"getindex(collection, i)\" is valid. For unordered - collections, the number of elements. - - length(s) - - The number of characters in string \"s\". - -"), - -("Base","endof","endof(collection) -> Integer - - Returns the last index of the collection. - - julia> endof([1,2,4]) - 3 - -"), - -("Base","in","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)\". - -"), - -("Base","eltype","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 \"(key,value)\" tuple type. 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. - -"), - -("Base","indexin","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\". - -"), - -("Base","findin","findin(a, b) - - Returns the indices of elements in collection \"a\" that appear in - collection \"b\" - -"), - -("Base","unique","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\". - -"), - -("Base","reduce","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. - - 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\". - -"), - -("Base","reduce","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. - - 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\". - -"), - -("Base","foldl","foldl(op, v0, itr) - - Like \"reduce()\", but with guaranteed left associativity. \"v0\" - will be used exactly once. - - 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)\"). - -"), - -("Base","foldl","foldl(op, v0, itr) - - Like \"reduce()\", but with guaranteed left associativity. \"v0\" - will be used exactly once. - - 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)\"). - -"), - -("Base","foldr","foldr(op, v0, itr) - - Like \"reduce()\", but with guaranteed right associativity. \"v0\" - will be used exactly once. - - 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)\"). - -"), - -("Base","foldr","foldr(op, v0, itr) - - Like \"reduce()\", but with guaranteed right associativity. \"v0\" - will be used exactly once. - - 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)\"). - -"), - -("Base","maximum","maximum(itr) - - Returns the largest element in a collection. - - maximum(A, dims) - - Compute the maximum value of an array over the given dimensions. - -"), - -("Base","maximum","maximum(itr) - - Returns the largest element in a collection. - - maximum(A, dims) - - Compute the maximum value of an array over the given dimensions. - -"), - -("Base","maximum!","maximum!(r, A) - - Compute the maximum value of \"A\" over the singleton dimensions of - \"r\", and write results to \"r\". - -"), - -("Base","minimum","minimum(itr) - - Returns the smallest element in a collection. - - minimum(A, dims) - - Compute the minimum value of an array over the given dimensions. - -"), - -("Base","minimum","minimum(itr) - - Returns the smallest element in a collection. - - minimum(A, dims) - - Compute the minimum value of an array over the given dimensions. - -"), - -("Base","minimum!","minimum!(r, A) - - Compute the minimum value of \"A\" over the singleton dimensions of - \"r\", and write results to \"r\". - -"), - -("Base","extrema","extrema(itr) - - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. - -"), - -("Base","indmax","indmax(itr) -> Integer - - Returns the index of the maximum element in a collection. - -"), - -("Base","indmin","indmin(itr) -> Integer - - Returns the index of the minimum element in a collection. - -"), - -("Base","findmax","findmax(itr) -> (x, index) - - Returns the maximum element and its index. - - findmax(A, dims) -> (maxval, index) - - For an array input, returns the value and index of the maximum over - the given dimensions. - -"), - -("Base","findmax","findmax(itr) -> (x, index) - - Returns the maximum element and its index. - - findmax(A, dims) -> (maxval, index) - - For an array input, returns the value and index of the maximum over - the given dimensions. - -"), - -("Base","findmin","findmin(itr) -> (x, index) - - Returns the minimum element and its index. - - findmin(A, dims) -> (minval, index) - - For an array input, returns the value and index of the minimum over - the given dimensions. - -"), - -("Base","findmin","findmin(itr) -> (x, index) - - Returns the minimum element and its index. - - findmin(A, dims) -> (minval, index) - - For an array input, returns the value and index of the minimum over - the given dimensions. - -"), - -("Base","maxabs","maxabs(itr) - - Compute the maximum absolute value of a collection of values. - - maxabs(A, dims) - - Compute the maximum absolute values over given dimensions. - -"), - -("Base","maxabs","maxabs(itr) - - Compute the maximum absolute value of a collection of values. - - maxabs(A, dims) - - Compute the maximum absolute values over given dimensions. - -"), - -("Base","maxabs!","maxabs!(r, A) - - Compute the maximum absolute values over the singleton dimensions - of \"r\", and write values to \"r\". - -"), - -("Base","minabs","minabs(itr) - - Compute the minimum absolute value of a collection of values. - - minabs(A, dims) - - Compute the minimum absolute values over given dimensions. - -"), - -("Base","minabs","minabs(itr) - - Compute the minimum absolute value of a collection of values. - - minabs(A, dims) - - Compute the minimum absolute values over given dimensions. - -"), - -("Base","minabs!","minabs!(r, A) - - Compute the minimum absolute values over the singleton dimensions - of \"r\", and write values to \"r\". - -"), - -("Base","sum","sum(itr) - - Returns the sum of all elements in a collection. - - sum(A, dims) - - Sum elements of an array over the given dimensions. - - sum(f, itr) - - Sum the results of calling function \"f\" on each element of - \"itr\". - -"), - -("Base","sum","sum(itr) - - Returns the sum of all elements in a collection. - - sum(A, dims) - - Sum elements of an array over the given dimensions. - - sum(f, itr) - - Sum the results of calling function \"f\" on each element of - \"itr\". - -"), - -("Base","sum!","sum!(r, A) - - Sum elements of \"A\" over the singleton dimensions of \"r\", and - write results to \"r\". - -"), - -("Base","sum","sum(itr) - - Returns the sum of all elements in a collection. - - sum(A, dims) - - Sum elements of an array over the given dimensions. - - sum(f, itr) - - Sum the results of calling function \"f\" on each element of - \"itr\". - -"), - -("Base","sumabs","sumabs(itr) - - Sum absolute values of all elements in a collection. This is - equivalent to *sum(abs(itr))* but faster. - - sumabs(A, dims) - - Sum absolute values of elements of an array over the given - dimensions. - -"), - -("Base","sumabs","sumabs(itr) - - Sum absolute values of all elements in a collection. This is - equivalent to *sum(abs(itr))* but faster. - - sumabs(A, dims) - - Sum absolute values of elements of an array over the given - dimensions. - -"), - -("Base","sumabs!","sumabs!(r, A) - - Sum absolute values of elements of \"A\" over the singleton - dimensions of \"r\", and write results to \"r\". - -"), - -("Base","sumabs2","sumabs2(itr) - - Sum squared absolute values of all elements in a collection. This - is equivalent to *sum(abs2(itr))* but faster. - - sumabs2(A, dims) - - Sum squared absolute values of elements of an array over the given - dimensions. - -"), - -("Base","sumabs2","sumabs2(itr) - - Sum squared absolute values of all elements in a collection. This - is equivalent to *sum(abs2(itr))* but faster. - - sumabs2(A, dims) - - Sum squared absolute values of elements of an array over the given - dimensions. - -"), - -("Base","sumabs2!","sumabs2!(r, A) - - Sum squared absolute values of elements of \"A\" over the singleton - dimensions of \"r\", and write results to \"r\". - -"), - -("Base","prod","prod(itr) - - Returns the product of all elements of a collection. - - prod(A, dims) - - Multiply elements of an array over the given dimensions. - -"), - -("Base","prod","prod(itr) - - Returns the product of all elements of a collection. - - prod(A, dims) - - Multiply elements of an array over the given dimensions. - -"), - -("Base","prod!","prod!(r, A) - - Multiply elements of \"A\" over the singleton dimensions of \"r\", - and write results to \"r\". - -"), - -("Base","any","any(itr) -> Bool - - Test whether any elements of a boolean collection are true. - - any(A, dims) - - Test whether any values along the given dimensions of an array are - true. - - any(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for any elements of - \"itr\". - -"), - -("Base","any","any(itr) -> Bool - - Test whether any elements of a boolean collection are true. - - any(A, dims) - - Test whether any values along the given dimensions of an array are - true. - - any(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for any elements of - \"itr\". - -"), - -("Base","any!","any!(r, A) - - Test whether any values in \"A\" along the singleton dimensions of - \"r\" are true, and write results to \"r\". - -"), - -("Base","all","all(itr) -> Bool - - Test whether all elements of a boolean collection are true. - - all(A, dims) - - Test whether all values along the given dimensions of an array are - true. - - all(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for all elements of - \"itr\". - - julia> all(i->(4<=i<=6), [4,5,6]) - true - -"), - -("Base","all","all(itr) -> Bool - - Test whether all elements of a boolean collection are true. - - all(A, dims) - - Test whether all values along the given dimensions of an array are - true. - - all(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for all elements of - \"itr\". - - julia> all(i->(4<=i<=6), [4,5,6]) - true - -"), - -("Base","all!","all!(r, A) - - Test whether all values in \"A\" along the singleton dimensions of - \"r\" are true, and write results to \"r\". - -"), - -("Base","count","count(p, itr) -> Integer - - Count the number of elements in \"itr\" for which predicate \"p\" - returns true. - -"), - -("Base","any","any(itr) -> Bool - - Test whether any elements of a boolean collection are true. - - any(A, dims) - - Test whether any values along the given dimensions of an array are - true. - - any(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for any elements of - \"itr\". - -"), - -("Base","all","all(itr) -> Bool - - Test whether all elements of a boolean collection are true. - - all(A, dims) - - Test whether all values along the given dimensions of an array are - true. - - all(p, itr) -> Bool - - Determine whether predicate \"p\" returns true for all elements of - \"itr\". - - julia> all(i->(4<=i<=6), [4,5,6]) - true - -"), - -("Base","map","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 - -"), - -("Base","map!","map!(function, collection) - - In-place version of \"map()\". - - 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. - -"), - -("Base","map!","map!(function, collection) - - In-place version of \"map()\". - - 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. - -"), - -("Base","mapreduce","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. - - mapreduce(f, op, itr) - - Like \"mapreduce(f, op, v0, itr)\". In general, this cannot be used - with empty collections (see \"reduce(op, itr)\"). - -"), - -("Base","mapreduce","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. - - 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","mapfoldl(f, op, v0, itr) - - Like \"mapreduce()\", but with guaranteed left associativity. - \"v0\" will be used exactly once. - - 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","mapfoldl","mapfoldl(f, op, v0, itr) - - Like \"mapreduce()\", but with guaranteed left associativity. - \"v0\" will be used exactly once. - - 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","mapfoldr(f, op, v0, itr) - - Like \"mapreduce()\", but with guaranteed right associativity. - \"v0\" will be used exactly once. - - 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","mapfoldr","mapfoldr(f, op, v0, itr) - - Like \"mapreduce()\", but with guaranteed right associativity. - \"v0\" will be used exactly once. - - 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","first(coll) - - Get the first element of an iterable collection. Returns the start - point of a \"Range\" even if it is empty. - -"), - -("Base","last","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. - -"), - -("Base","step","step(r) - - Get the step size of a \"Range\" object. - -"), - -("Base","collect","collect(collection) - - Return an array of all items in a collection. For associative - collections, returns (key, value) tuples. - - collect(element_type, collection) - - Return an array of type \"Array{element_type,1}\" of all items in a - collection. - -"), - -("Base","collect","collect(collection) - - Return an array of all items in a collection. For associative - collections, returns (key, value) tuples. - - collect(element_type, collection) - - Return an array of type \"Array{element_type,1}\" of all items in a - collection. - -"), - -("Base","issubset","issubset(a, b) - - ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool - - Determine whether every element of \"a\" is also in \"b\", using - \"in()\". - - issubset(A, S) -> Bool - - ⊆(A, S) -> Bool - - True if A is a subset of or equal to S. - -"), - -("Base","filter","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). - -"), - -("Base","filter!","filter!(function, collection) - - Update \"collection\", removing elements for which \"function\" is - false. For associative collections, the function is passed two - arguments (key and value). - -"), - -("Base","getindex","getindex(type[, elements...]) - - Construct a 1-d array of the specified type. This is usually called - with the syntax \"Type[]\". Element values can be specified using - \"Type[a,b,c,...]\". - - getindex(A, inds...) - - Returns a subset of array \"A\" as specified by \"inds\", where - each \"ind\" may be an \"Int\", a \"Range\", or a \"Vector\". See - the manual section on *array indexing* for details. - - 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, ...)\". - -"), - -("Base","setindex!","setindex!(A, X, inds...) - - Store values from array \"X\" within some subset of \"A\" as - specified by \"inds\". - - 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, ...)\". - -"), - -("Base","Dict","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{ASCIIString,Int64} with 2 entries: - \"B\" => 2 - \"A\" => 1 - - Alternatively, a sequence of pair arguments may be passed. - - julia> Dict(\"A\"=>1, \"B\"=>2) - Dict{ASCIIString,Int64} with 2 entries: - \"B\" => 2 - \"A\" => 1 - -"), - -("Base","haskey","haskey(collection, key) -> Bool - - Determine whether a collection has a mapping for a given key. - -"), - -("Base","get","get(x) - - Attempt to access the value of the \"Nullable\" object, \"x\". - Returns the value if it is present; otherwise, throws a - \"NullException\". - - get(x, y) - - Attempt to access the value of the \"Nullable{T}\" object, \"x\". - Returns the value if it is present; otherwise, returns \"convert(T, - y)\". - - 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. - - 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 - -"), - -("Base","get","get(x) - - Attempt to access the value of the \"Nullable\" object, \"x\". - Returns the value if it is present; otherwise, throws a - \"NullException\". - - get(x, y) - - Attempt to access the value of the \"Nullable{T}\" object, \"x\". - Returns the value if it is present; otherwise, returns \"convert(T, - y)\". - - 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. - - 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 - - - time() - end - -"), - -("Base","get!","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\". - - 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 - -"), - -("Base","get!","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\". - - 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 - - - time() - end - -"), - -("Base","getkey","getkey(collection, key, default) - - Return the key matching argument \"key\" if one exists in - \"collection\", otherwise return \"default\". - -"), - -("Base","delete!","delete!(collection, key) - - Delete the mapping for the given key in a collection, and return - the collection. - -"), - -("Base","pop!","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. - - 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 - -"), - -("Base","keys","keys(collection) - - Return an iterator over all keys in a collection. - \"collect(keys(d))\" returns an array of keys. - -"), - -("Base","values","values(collection) - - Return an iterator over all values in a collection. - \"collect(values(d))\" returns an array of values. - -"), - -("Base","merge","merge(collection, others...) - - 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{ASCIIString,Float64} with 2 entries: - \"bar\" => 42.0 - \"foo\" => 0.0 - - julia> b = Dict(utf8(\"baz\") => 17, utf8(\"bar\") => 4711) - Dict{UTF8String,Int64} with 2 entries: - \"bar\" => 4711 - \"baz\" => 17 - - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - \"bar\" => 4711.0 - \"baz\" => 17.0 - \"foo\" => 0.0 - - julia> merge(b, a) - Dict{UTF8String,Float64} with 3 entries: - \"bar\" => 42.0 - \"baz\" => 17.0 - \"foo\" => 0.0 - -"), - -("Base","merge!","merge!(collection, others...) - - Update collection with pairs from the other collections - -"), - -("Base","sizehint!","sizehint!(s, n) - - Suggest that collection \"s\" reserve capacity for at least \"n\" - elements. This can improve performance. - -"), - -("Base","Set","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","IntSet([itr]) - - Construct a sorted set of the integers generated by the given - iterable object, or an empty set. Implemented as a bit string, and - therefore designed for dense integer sets. Only non-negative - integers can be stored. If the set will be sparse (for example - holding a single very large integer), use \"Set\" instead. - -"), - -("Base","union","union(s1, s2...) - - ∪(s1, s2) - - Construct the union of two or more sets. Maintains order with - arrays. - -"), - -("Base","union!","union!(s, iterable) - - Union each element of \"iterable\" into set \"s\" in-place. - -"), - -("Base","intersect","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. - -"), - -("Base","setdiff","setdiff(s1, s2) - - Construct the set of elements in \"s1\" but not \"s2\". 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. - -"), - -("Base","setdiff!","setdiff!(s, iterable) - - Remove each element of \"iterable\" from set \"s\" in-place. - -"), - -("Base","symdiff","symdiff(s1, s2...) - - Construct the symmetric difference of elements in the passed in - sets or arrays. Maintains order with arrays. - -"), - -("Base","symdiff!","symdiff!(s, n) - - The set \"s\" is destructively modified to toggle the inclusion of - integer \"n\". - - symdiff!(s, itr) - - For each element in \"itr\", destructively toggle its inclusion in - set \"s\". - - symdiff!(s1, s2) - - Construct the symmetric difference of sets \"s1\" and \"s2\", - storing the result in \"s1\". - -"), - -("Base","symdiff!","symdiff!(s, n) - - The set \"s\" is destructively modified to toggle the inclusion of - integer \"n\". - - symdiff!(s, itr) - - For each element in \"itr\", destructively toggle its inclusion in - set \"s\". - - symdiff!(s1, s2) - - Construct the symmetric difference of sets \"s1\" and \"s2\", - storing the result in \"s1\". - -"), - -("Base","symdiff!","symdiff!(s, n) - - The set \"s\" is destructively modified to toggle the inclusion of - integer \"n\". - - symdiff!(s, itr) - - For each element in \"itr\", destructively toggle its inclusion in - set \"s\". - - symdiff!(s1, s2) - - Construct the symmetric difference of sets \"s1\" and \"s2\", - storing the result in \"s1\". - -"), - -("Base","complement","complement(s) - - Returns the set-complement of \"IntSet\" \"s\". - -"), - -("Base","complement!","complement!(s) - - Mutates \"IntSet\" \"s\" into its set-complement. - -"), - -("Base","intersect!","intersect!(s1, s2) - - 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","issubset(a, b) - - ⊆(A, S) -> Bool ⊈(A, S) -> Bool ⊊(A, S) -> Bool - - Determine whether every element of \"a\" is also in \"b\", using - \"in()\". - - issubset(A, S) -> Bool - - ⊆(A, S) -> Bool - - True if A is a subset of or equal to S. - -"), - -("Base","push!","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])\". - -"), - -("Base","pop!","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. - - 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 - -"), - -("Base","unshift!","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 - -"), - -("Base","shift!","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 - -"), - -("Base","insert!","insert!(collection, index, item) - - Insert an \"item\" into \"collection\" at the given \"index\". - \"index\" is the index of \"item\" in the resulting \"collection\". - - julia> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 - -"), - -("Base","deleteat!","deleteat!(collection, index) - - Remove the item at the given \"index\" and return the modified - \"collection\". 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 - - deleteat!(collection, itr) - - Remove the items at the indices given by \"itr\", and return the - modified \"collection\". Subsequent items are shifted to fill the - resulting gap. \"itr\" must be sorted and unique. - - 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], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 - -"), - -("Base","deleteat!","deleteat!(collection, index) - - Remove the item at the given \"index\" and return the modified - \"collection\". 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 - - deleteat!(collection, itr) - - Remove the items at the indices given by \"itr\", and return the - modified \"collection\". Subsequent items are shifted to fill the - resulting gap. \"itr\" must be sorted and unique. - - 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], (2, 2)) - ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:631 - -"), - -("Base","splice!","splice!(collection, index[, replacement]) -> item - - Remove the item at the given index, and return the removed item. - Subsequent items are shifted down 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)\". - - splice!(collection, range[, replacement]) -> items - - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down 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 - -"), - -("Base","splice!","splice!(collection, index[, replacement]) -> item - - Remove the item at the given index, and return the removed item. - Subsequent items are shifted down 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)\". - - splice!(collection, range[, replacement]) -> items - - Remove items in the specified index range, and return a collection - containing the removed items. Subsequent items are shifted down 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 - -"), - -("Base","resize!","resize!(collection, n) -> collection - - Resize \"collection\" 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 - -"), - -("Base","append!","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)\". - -"), - -("Base","prepend!","prepend!(collection, items) -> collection - - Insert the elements of \"items\" to the beginning of - \"collection\". - - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 - -"), - -("Base.Collections","PriorityQueue","PriorityQueue(K, V[, ord]) - - Construct a new \"PriorityQueue\", with keys of type \"K\" and - values/priorites of type \"V\". If an order is not given, the - priority queue is min-ordered using the default comparison for - \"V\". - -"), - -("Base.Collections","enqueue!","enqueue!(pq, k, v) - - Insert the a key \"k\" into a priority queue \"pq\" with priority - \"v\". - -"), - -("Base.Collections","dequeue!","dequeue!(pq) - - Remove and return the lowest priority key from a priority queue. - -"), - -("Base.Collections","peek","peek(pq) - - Return the lowest priority key from a priority queue without - removing that key from the queue. - -"), - -("Base.Collections","heapify","heapify(v[, ord]) - - Return a new vector in binary heap order, optionally using the - given ordering. - -"), - -("Base.Collections","heapify!","heapify!(v[, ord]) - - In-place \"heapify()\". - -"), - -("Base.Collections","isheap","isheap(v[, ord]) - - Return true iff an array is heap-ordered according to the given - order. - -"), - -("Base.Collections","heappush!","heappush!(v, x[, ord]) - - Given a binary heap-ordered array, push a new element \"x\", - preserving the heap property. For efficiency, this function does - not check that the array is indeed heap-ordered. - -"), - -("Base.Collections","heappop!","heappop!(v[, ord]) - - Given a binary heap-ordered array, remove and return the lowest - ordered element. For efficiency, this function does not check that - the array is indeed heap-ordered. - -"), - -("Base","nothing","nothing - - The singleton instance of type \"Void\", used by convention when - there is no value to return (as in a C \"void\" function). Can be - converted to an empty \"Nullable\" value. - -"), - -("Base","OS_NAME","OS_NAME - - A symbol representing the name of the operating system. Possible - values are \":Linux\", \":Darwin\" (OS X), or \":Windows\". - -"), - -("Base","ARGS","ARGS - - An array of the command line arguments passed to Julia, as strings. - -"), - -("Base","C_NULL","C_NULL - - The C null pointer constant, sometimes used when calling external - code. - -"), - -("Base","CPU_CORES","CPU_CORES - - The number of CPU cores in the system. - -"), - -("Base","WORD_SIZE","WORD_SIZE - - Standard word size on the current machine, in bits. - -"), - -("Base","VERSION","VERSION - - An object describing which version of Julia is in use. - -"), - -("Base","LOAD_PATH","LOAD_PATH - - An array of paths (as strings) where the \"require\" function looks - for code. - -"), - -("Base","JULIA_HOME","JULIA_HOME - - A string containing the full path to the directory containing the - \"julia\" executable. - -"), - -("Base","ANY","ANY - - Equivalent to \"Any\" for dispatch purposes, but signals the - compiler to skip code generation specialization for that field - -"), - -("Dates","Period","Period - -"), - -("Dates","Year","Year - -"), - -("Dates","Month","Month - -"), - -("Dates","Week","Week - -"), - -("Dates","Day","Day - -"), - -("Dates","Hour","Hour - -"), - -("Dates","Minute","Minute - -"), - -("Dates","Second","Second - -"), - -("Dates","Millisecond","Millisecond - - \"Period\" types represent discrete, human representations of time. - -"), - -("Dates","Instant","Instant - - \"Instant\" types represent integer-based, machine representations - of time as continuous timelines starting from an epoch. - -"), - -("Dates","UTInstant{T}","UTInstant{T} - - The \"UTInstant\" represents a machine timeline based on *UT* time - (1 day = one revolution of the earth). The \"{T}\" is a \"Period\" - parameter that indicates the resolution or precision of the - instant. - -"), - -("Dates","TimeType","TimeType - - \"TimeType\" types wrap \"Instant\" machine instances to provide - human representations of the machine instant. - -"), - -("Dates","DateTime","DateTime - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - -"), - -("Dates","Date","Date - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - -"), - -("Dates","DateTime","DateTime() - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - - DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - - DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code - | Matches | Comment - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" - | 1996, 96 | Returns year of 1996, 0096 - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" - | 1, 01 | Matches 1 or 2-digit months - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" - | Jan | Matches abbreviated months according to the - \"locale\" keyword | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" - | January | Matches full month names according to the \"locale\" - keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"d\" | 1, 01 | Matches 1 or 2-digit days - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" - | 00 | Matches hours - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" - | 00 | Matches minutes - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" - | 00 | Matches seconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" - | .500 | Matches milliseconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" - | Mon, Tues | Matches abbreviated days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" - | Monday | Matches full name days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and - day | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","DateTime","DateTime() - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - - DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - - DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code - | Matches | Comment - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" - | 1996, 96 | Returns year of 1996, 0096 - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" - | 1, 01 | Matches 1 or 2-digit months - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" - | Jan | Matches abbreviated months according to the - \"locale\" keyword | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" - | January | Matches full month names according to the \"locale\" - keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"d\" | 1, 01 | Matches 1 or 2-digit days - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" - | 00 | Matches hours - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" - | 00 | Matches minutes - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" - | 00 | Matches seconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" - | .500 | Matches milliseconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" - | Mon, Tues | Matches abbreviated days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" - | Monday | Matches full name days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and - day | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","DateTime","DateTime() - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - - DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - - DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code - | Matches | Comment - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" - | 1996, 96 | Returns year of 1996, 0096 - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" - | 1, 01 | Matches 1 or 2-digit months - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" - | Jan | Matches abbreviated months according to the - \"locale\" keyword | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" - | January | Matches full month names according to the \"locale\" - keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"d\" | 1, 01 | Matches 1 or 2-digit days - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" - | 00 | Matches hours - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" - | 00 | Matches minutes - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" - | 00 | Matches seconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" - | .500 | Matches milliseconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" - | Mon, Tues | Matches abbreviated days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" - | Monday | Matches full name days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and - day | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","DateTime","DateTime() - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - - DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - - DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code - | Matches | Comment - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" - | 1996, 96 | Returns year of 1996, 0096 - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" - | 1, 01 | Matches 1 or 2-digit months - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" - | Jan | Matches abbreviated months according to the - \"locale\" keyword | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" - | January | Matches full month names according to the \"locale\" - keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"d\" | 1, 01 | Matches 1 or 2-digit days - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" - | 00 | Matches hours - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" - | 00 | Matches minutes - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" - | 00 | Matches seconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" - | .500 | Matches milliseconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" - | Mon, Tues | Matches abbreviated days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" - | Monday | Matches full name days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and - day | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","DateTime","DateTime() - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - - DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - - DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code - | Matches | Comment - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" - | 1996, 96 | Returns year of 1996, 0096 - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" - | 1, 01 | Matches 1 or 2-digit months - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" - | Jan | Matches abbreviated months according to the - \"locale\" keyword | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" - | January | Matches full month names according to the \"locale\" - keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"d\" | 1, 01 | Matches 1 or 2-digit days - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" - | 00 | Matches hours - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" - | 00 | Matches minutes - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" - | 00 | Matches seconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" - | .500 | Matches milliseconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" - | Mon, Tues | Matches abbreviated days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" - | Monday | Matches full name days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and - day | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","Dates","Dates.DateFormat(format::AbstractString) -> DateFormat - - Construct a date formatting object that can be passed repeatedly - for parsing similarly formatted date strings. \"format\" is a - format string in the form described above (e.g. \"\"yyyy-mm- - dd\"\"). - -"), - -("Dates","DateTime","DateTime() - - \"DateTime\" wraps a \"UTInstant{Millisecond}\" and interprets it - according to the proleptic Gregorian calendar. - - DateTime(y[, m, d, h, mi, s, ms]) -> DateTime - - Construct a DateTime type by parts. Arguments must be convertible - to \"Int64\". - - DateTime(periods::Period...) -> DateTime - - Constuct a DateTime type by \"Period\" type parts. Arguments may be - in any order. DateTime parts not provided will default to the value - of \"Dates.default(period)\". - - DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime - - Create a DateTime through the adjuster API. The starting point will - be constructed from the provided \"y, m, d...\" arguments, and will - be adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (in the case that \"f::Function\" is never - satisfied). - - DateTime(dt::Date) -> DateTime - - Converts a \"Date\" type to a \"DateTime\". The hour, minute, - second, and millisecond parts of the new \"DateTime\" are assumed - to be zero. - - DateTime(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime - - Construct a DateTime type by parsing the \"dt\" date string - following the pattern given in the \"format\" string. The following - codes can be used for constructing format strings: - - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | Code - | Matches | Comment - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"y\" - | 1996, 96 | Returns year of 1996, 0096 - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"m\" - | 1, 01 | Matches 1 or 2-digit months - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"u\" - | Jan | Matches abbreviated months according to the - \"locale\" keyword | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"U\" - | January | Matches full month names according to the \"locale\" - keyword | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"d\" | 1, 01 | Matches 1 or 2-digit days - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"H\" - | 00 | Matches hours - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"M\" - | 00 | Matches minutes - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"S\" - | 00 | Matches seconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"s\" - | .500 | Matches milliseconds - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"e\" - | Mon, Tues | Matches abbreviated days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | \"E\" - | Monday | Matches full name days of the week - | +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ | - \"yyyymmdd\" | 19960101 | Matches fixed-width year, month, and - day | - +––––––––-+–––––-+––––––––––––––––––––––––––––––––-+ - - All characters not listed above are treated as delimiters between - date and time slots. So a \"dt\" string of - \"1996-01-15T00:00:00.0\" would have a \"format\" string like - \"y-m-dTH:M:S.s\". - - DateTime(dt::AbstractString, df::DateFormat) -> DateTime - - Similar form as above for parsing a \"DateTime\", but passes a - \"DateFormat\" object instead of a raw formatting string. It is - more efficient if similarly formatted date strings will be parsed - repeatedly to first create a \"DateFormat\" object then use this - method for parsing. - -"), - -("Dates","Date","Date() - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - - Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - - Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - - Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - - Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","Date","Date() - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - - Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - - Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - - Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - - Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","Date","Date() - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - - Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - - Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - - Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - - Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","Date","Date() - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - - Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - - Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - - Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - - Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","Date","Date() - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - - Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - - Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - - Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - - Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","Date","Date() - - \"Date\" wraps a \"UTInstant{Day}\" and interprets it according to - the proleptic Gregorian calendar. - - Date(y[, m, d]) -> Date - - Construct a \"Date\" type by parts. Arguments must be convertible - to \"Int64\". - - Date(period::Period...) -> Date - - Constuct a Date type by \"Period\" type parts. Arguments may be in - any order. Date parts not provided will default to the value of - \"Dates.default(period)\". - - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - - Create a Date through the adjuster API. The starting point will be - constructed from the provided \"y, m\" arguments, and will be - adjusted until \"f::Function\" returns true. The step size in - adjusting can be provided manually through the \"step\" keyword. If - \"negate=true\", then the adjusting will stop when \"f::Function\" - returns false instead of true. \"limit\" provides a limit to the - max number of iterations the adjustment API will pursue before - throwing an error (given that \"f::Function\" is never satisfied). - - Date(dt::DateTime) -> Date - - Converts a \"DateTime\" type to a \"Date\". The hour, minute, - second, and millisecond parts of the \"DateTime\" are truncated, so - only the year, month and day parts are used in construction. - - Date(dt::AbstractString, format::AbstractString; locale=\"english\") -> Date - - Construct a Date type by parsing a \"dt\" date string following the - pattern given in the \"format\" string. Follows the same - conventions as \"DateTime\" above. - - Date(dt::AbstractString, df::DateFormat) -> Date - - Parse a date from a date string \"dt\" using a \"DateFormat\" - object \"df\". - -"), - -("Dates","now","now() -> DateTime - - Returns a DateTime corresponding to the user's system time - including the system timezone locale. - - now(::Type{UTC}) -> DateTime - - Returns a DateTime corresponding to the user's system time as - UTC/GMT. - -"), - -("Dates","now","now() -> DateTime - - Returns a DateTime corresponding to the user's system time - including the system timezone locale. - - now(::Type{UTC}) -> DateTime - - Returns a DateTime corresponding to the user's system time as - UTC/GMT. - -"), - -("Dates","eps","eps([type]) - - The distance between 1.0 and the next larger representable - floating-point value of \"type\". Only floating-point types are - sensible arguments. If \"type\" is omitted, then \"eps(Float64)\" - is returned. - - eps(x) - - The distance between \"x\" and the next larger representable - floating-point value of the same type as \"x\". - -"), - -("Dates","year","year(dt::TimeType) -> Int64 - - month(dt::TimeType) -> Int64 week(dt::TimeType) -> Int64 - day(dt::TimeType) -> Int64 hour(dt::TimeType) -> Int64 - minute(dt::TimeType) -> Int64 second(dt::TimeType) -> Int64 - millisecond(dt::TimeType) -> Int64 - - Return the field part of a Date or DateTime as an \"Int64\". - -"), - -("Dates","Year","Year(v) - - Year - - Year(dt::TimeType) -> Year - - Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week - Day(dt::TimeType) -> Day Hour(dt::TimeType) -> Hour - Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second - Millisecond(dt::TimeType) -> Millisecond - - Return the field part of a Date or DateTime as a \"Period\" type. - - Year(v) - - Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) - - Construct a \"Period\" type with the given \"v\" value. Input must - be losslessly convertible to an \"Int64\". - -"), - -("Dates","yearmonth","yearmonth(dt::TimeType) -> (Int64, Int64) - - Simultaneously return the year and month parts of a Date or - DateTime. - -"), - -("Dates","monthday","monthday(dt::TimeType) -> (Int64, Int64) - - Simultaneously return the month and day parts of a Date or - DateTime. - -"), - -("Dates","yearmonthday","yearmonthday(dt::TimeType) -> (Int64, Int64, Int64) - - Simultaneously return the year, month, and day parts of a Date or - DateTime. - -"), - -("Dates","dayname","dayname(dt::TimeType; locale=\"english\") -> AbstractString - - Return the full day name corresponding to the day of the week of - the Date or DateTime in the given \"locale\". - -"), - -("Dates","dayabbr","dayabbr(dt::TimeType; locale=\"english\") -> AbstractString - - Return the abbreviated name corresponding to the day of the week of - the Date or DateTime in the given \"locale\". - -"), - -("Dates","dayofweek","dayofweek(dt::TimeType) -> Int64 - - Returns the day of the week as an \"Int64\" with \"1 = Monday, 2 = - Tuesday, etc.\". - -"), - -("Dates","dayofweekofmonth","dayofweekofmonth(dt::TimeType) -> Int - - For the day of week of \"dt\", returns which number it is in - \"dt\"'s month. So if the day of the week of \"dt\" is Monday, then - \"1 = First Monday of the month, 2 = Second Monday of the month, - etc.\" In the range 1:5. - -"), - -("Dates","daysofweekinmonth","daysofweekinmonth(dt::TimeType) -> Int - - For the day of week of \"dt\", returns the total number of that day - of the week in \"dt\"'s month. Returns 4 or 5. Useful in temporal - expressions for specifying the last day of a week in a month by - including \"dayofweekofmonth(dt) == daysofweekinmonth(dt)\" in the - adjuster function. - -"), - -("Dates","monthname","monthname(dt::TimeType; locale=\"english\") -> AbstractString - - Return the full name of the month of the Date or DateTime in the - given \"locale\". - -"), - -("Dates","monthabbr","monthabbr(dt::TimeType; locale=\"english\") -> AbstractString - - Return the abbreviated month name of the Date or DateTime in the - given \"locale\". - -"), - -("Dates","daysinmonth","daysinmonth(dt::TimeType) -> Int - - Returns the number of days in the month of \"dt\". Value will be - 28, 29, 30, or 31. - -"), - -("Dates","isleapyear","isleapyear(dt::TimeType) -> Bool - - Returns true if the year of \"dt\" is a leap year. - -"), - -("Dates","dayofyear","dayofyear(dt::TimeType) -> Int - - Returns the day of the year for \"dt\" with January 1st being day - 1. - -"), - -("Dates","daysinyear","daysinyear(dt::TimeType) -> Int - - Returns 366 if the year of \"dt\" is a leap year, otherwise returns - 365. - -"), - -("Dates","quarterofyear","quarterofyear(dt::TimeType) -> Int - - Returns the quarter that \"dt\" resides in. Range of value is 1:4. - -"), - -("Dates","dayofquarter","dayofquarter(dt::TimeType) -> Int - - Returns the day of the current quarter of \"dt\". Range of value is - 1:92. - -"), - -("Dates","trunc","trunc([T], x[, digits[, base]]) - - \"trunc(x)\" returns the nearest integral value of the same type as - \"x\" whose absolute value is less than or equal to \"x\". - - \"trunc(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Dates","firstdayofweek","firstdayofweek(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the Monday of its week. - -"), - -("Dates","lastdayofweek","lastdayofweek(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the Sunday of its week. - -"), - -("Dates","firstdayofmonth","firstdayofmonth(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the first day of its month. - -"), - -("Dates","lastdayofmonth","lastdayofmonth(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the last day of its month. - -"), - -("Dates","firstdayofyear","firstdayofyear(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the first day of its year. - -"), - -("Dates","lastdayofyear","lastdayofyear(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the last day of its year. - -"), - -("Dates","firstdayofquarter","firstdayofquarter(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the first day of its quarter. - -"), - -("Dates","lastdayofquarter","lastdayofquarter(dt::TimeType) -> TimeType - - Adjusts \"dt\" to the last day of its quarter. - -"), - -("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts \"dt\" to the next day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the next \"dow\", allowing - for no adjustment to occur. - - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts \"dt\" by iterating at most \"limit\" iterations by - \"step\" increments until \"func\" returns true. \"func\" must take - a single \"TimeType\" argument and return a \"Bool\". \"same\" - allows \"dt\" to be considered in satisfying \"func\". \"negate\" - will make the adjustment process terminate when \"func\" returns - false instead of true. - -"), - -("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts \"dt\" to the previous day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the previous \"dow\", - allowing for no adjustment to occur. - - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts \"dt\" by iterating at most \"limit\" iterations by - \"step\" increments until \"func\" returns true. \"func\" must take - a single \"TimeType\" argument and return a \"Bool\". \"same\" - allows \"dt\" to be considered in satisfying \"func\". \"negate\" - will make the adjustment process terminate when \"func\" returns - false instead of true. - -"), - -("Dates","tofirst","tofirst(dt::TimeType, dow::Int;of=Month) -> TimeType - - Adjusts \"dt\" to the first \"dow\" of its month. Alternatively, - \"of=Year\" will adjust to the first \"dow\" of the year. - -"), - -("Dates","tolast","tolast(dt::TimeType, dow::Int;of=Month) -> TimeType - - Adjusts \"dt\" to the last \"dow\" of its month. Alternatively, - \"of=Year\" will adjust to the last \"dow\" of the year. - -"), - -("Dates","tonext","tonext(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts \"dt\" to the next day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the next \"dow\", allowing - for no adjustment to occur. - - tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts \"dt\" by iterating at most \"limit\" iterations by - \"step\" increments until \"func\" returns true. \"func\" must take - a single \"TimeType\" argument and return a \"Bool\". \"same\" - allows \"dt\" to be considered in satisfying \"func\". \"negate\" - will make the adjustment process terminate when \"func\" returns - false instead of true. - -"), - -("Dates","toprev","toprev(dt::TimeType, dow::Int;same::Bool=false) -> TimeType - - Adjusts \"dt\" to the previous day of week corresponding to \"dow\" - with \"1 = Monday, 2 = Tuesday, etc\". Setting \"same=true\" allows - the current \"dt\" to be considered as the previous \"dow\", - allowing for no adjustment to occur. - - toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) -> TimeType - - Adjusts \"dt\" by iterating at most \"limit\" iterations by - \"step\" increments until \"func\" returns true. \"func\" must take - a single \"TimeType\" argument and return a \"Bool\". \"same\" - allows \"dt\" to be considered in satisfying \"func\". \"negate\" - will make the adjustment process terminate when \"func\" returns - false instead of true. - -"), - -("Dates","recur{T<:TimeType}","recur{T<:TimeType}(func::Function, dr::StepRange{T};negate=false, limit=10000) -> Vector{T} - - \"func\" takes a single TimeType argument and returns a \"Bool\" - indicating whether the input should be \"included\" in the final - set. \"recur\" applies \"func\" over each element in the range of - \"dr\", including those elements for which \"func\" returns - \"true\" in the resulting Array, unless \"negate=true\", then only - elements where \"func\" returns \"false\" are included. - -"), - -("Dates","Year","Year(v) - - Year - - Year(dt::TimeType) -> Year - - Month(dt::TimeType) -> Month Week(dt::TimeType) -> Week - Day(dt::TimeType) -> Day Hour(dt::TimeType) -> Hour - Minute(dt::TimeType) -> Minute Second(dt::TimeType) -> Second - Millisecond(dt::TimeType) -> Millisecond - - Return the field part of a Date or DateTime as a \"Period\" type. - - Year(v) - - Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) - - Construct a \"Period\" type with the given \"v\" value. Input must - be losslessly convertible to an \"Int64\". - -"), - -("Dates","default","default(p::Period) -> Period - - Returns a sensible \"default\" value for the input Period by - returning \"one(p)\" for Year, Month, and Day, and \"zero(p)\" for - Hour, Minute, Second, and Millisecond. - -"), - -("Dates","today","today() -> Date - - Returns the date portion of \"now()\". - -"), - -("Dates","unix2datetime","unix2datetime(x) -> DateTime - - Takes the number of seconds since unix epoch - \"1970-01-01T00:00:00\" and converts to the corresponding DateTime. - -"), - -("Dates","datetime2unix","datetime2unix(dt::DateTime) -> Float64 - - Takes the given DateTime and returns the number of seconds since - the unix epoch as a \"Float64\". - -"), - -("Dates","julian2datetime","julian2datetime(julian_days) -> DateTime - - Takes the number of Julian calendar days since epoch - \"-4713-11-24T12:00:00\" and returns the corresponding DateTime. - -"), - -("Dates","datetime2julian","datetime2julian(dt::DateTime) -> Float64 - - Takes the given DateTime and returns the number of Julian calendar - days since the julian epoch as a \"Float64\". - -"), - -("Dates","rata2datetime","rata2datetime(days) -> DateTime - - Takes the number of Rata Die days since epoch - \"0000-12-31T00:00:00\" and returns the corresponding DateTime. - -"), - -("Dates","datetime2rata","datetime2rata(dt::TimeType) -> Int64 - - Returns the number of Rata Die days since epoch from the given Date - or DateTime. - -"), - -("Base","pwd","pwd() -> AbstractString - - Get the current working directory. - -"), - -("Base","cd","cd(dir::AbstractString) - - Set the current working directory. - - cd(f[, dir]) - - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. - -"), - -("Base","cd","cd(dir::AbstractString) - - Set the current working directory. - - cd(f[, dir]) - - Temporarily changes the current working directory (HOME if not - specified) and applies function f before returning. - -"), - -("Base","readdir","readdir([dir]) -> Vector{ByteString} - - Returns the files and directories in the directory *dir* (or the - current working directory if not given). - -"), - -("Base","mkdir","mkdir(path[, mode]) - - Make a new directory with name \"path\" and permissions \"mode\". - \"mode\" defaults to 0o777, modified by the current file creation - mask. - -"), - -("Base","mkpath","mkpath(path[, mode]) - - Create all directories in the given \"path\", with permissions - \"mode\". \"mode\" defaults to 0o777, modified by the current file - creation mask. - -"), - -("Base","symlink","symlink(target, link) - - Creates a symbolic link to \"target\" with the name \"link\". - - Note: This function raises an error under operating systems that - do not support soft symbolic links, such as Windows XP. - -"), - -("Base","readlink","readlink(path) -> AbstractString - - Returns the value of a symbolic link \"path\". - -"), - -("Base","chmod","chmod(path, mode) - - Change the permissions mode of \"path\" to \"mode\". Only integer - \"mode\"s (e.g. 0o777) are currently supported. - -"), - -("Base","stat","stat(file) - - Returns a structure whose fields contain information about the - file. The fields of the structure are: - - +–––––-+––––––––––––––––––––––––––––––––––––+ | size | The - size (in bytes) of the file - | +–––––-+––––––––––––––––––––––––––––––––––––+ | device | ID of - the device that contains the file | - +–––––-+––––––––––––––––––––––––––––––––––––+ | inode | The - inode number of the file - | +–––––-+––––––––––––––––––––––––––––––––––––+ | mode | The - protection mode of the file - | +–––––-+––––––––––––––––––––––––––––––––––––+ | nlink | The - number of hard links to the file - | +–––––-+––––––––––––––––––––––––––––––––––––+ | uid | The - user id of the owner of the file - | +–––––-+––––––––––––––––––––––––––––––––––––+ | gid | The - group id of the file owner - | +–––––-+––––––––––––––––––––––––––––––––––––+ | rdev | If - this file refers to a device, the ID of the device it refers to - | +–––––-+––––––––––––––––––––––––––––––––––––+ | blksize | The - file-system preferred block size for the file - | +–––––-+––––––––––––––––––––––––––––––––––––+ | blocks | The - number of such blocks allocated - | +–––––-+––––––––––––––––––––––––––––––––––––+ | mtime | Unix - timestamp of when the file was last modified | - +–––––-+––––––––––––––––––––––––––––––––––––+ | ctime | Unix - timestamp of when the file was created | - +–––––-+––––––––––––––––––––––––––––––––––––+ - -"), - -("Base","lstat","lstat(file) - - Like stat, but for symbolic links gets the info for the link itself - rather than the file it refers to. This function must be called on - a file path rather than a file object or a file descriptor. - -"), - -("Base","ctime","ctime(file) - - Equivalent to stat(file).ctime - -"), - -("Base","mtime","mtime(file) - - Equivalent to stat(file).mtime - -"), - -("Base","filemode","filemode(file) - - Equivalent to stat(file).mode - -"), - -("Base","filesize","filesize(path...) - - Equivalent to stat(file).size - -"), - -("Base","uperm","uperm(file) - - Gets the permissions of the owner of the file as a bitfield of - - +–––+–––––––––––-+ | 01 | Execute Permission | - +–––+–––––––––––-+ | 02 | Write Permission | - +–––+–––––––––––-+ | 04 | Read Permission | - +–––+–––––––––––-+ - - For allowed arguments, see \"stat\". - -"), - -("Base","gperm","gperm(file) - - Like uperm but gets the permissions of the group owning the file - -"), - -("Base","operm","operm(file) - - Like uperm but gets the permissions for people who neither own the - file nor are a member of the group owning the file - -"), - -("Base","cp","cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) - - Copy the file, link, or directory from *src* to *dest*. - \"remove_destination=true\" will first remove an existing *dst*. - - If *follow_symlinks=false*, and src is a symbolic link, dst will be - created as a symbolic link. If *follow_symlinks=true* and src is a - symbolic link, dst will be a copy of the file or directory *src* - refers to. - -"), - -("Base","download","download(url[, localfile]) - - Download a file from the given url, optionally renaming it to the - given local file name. Note that this function relies on the - availability of external tools such as \"curl\", \"wget\" or - \"fetch\" to download the file and is provided for convenience. For - production use or situations in which more options are need, please - use a package that provides the desired functionality instead. - -"), - -("Base","mv","mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) - - Move the file, link, or directory from *src* to *dest*. - \"remove_destination=true\" will first remove an existing *dst*. - -"), - -("Base","rm","rm(path::AbstractString; recursive=false) - - Delete the file, link, or empty directory at the given path. If - \"recursive=true\" is passed and the path is a directory, then all - contents are removed recursively. - -"), - -("Base","touch","touch(path::AbstractString) - - Update the last-modified timestamp on a file to the current time. - -"), - -("Base","tempname","tempname() - - Generate a unique temporary file path. - -"), - -("Base","tempdir","tempdir() - - Obtain the path of a temporary directory (possibly shared with - other processes). - -"), - -("Base","mktemp","mktemp([parent=tempdir()]) - - Returns \"(path, io)\", where \"path\" is the path of a new - temporary file in \"parent\" and \"io\" is an open file object for - this path. - -"), - -("Base","mktempdir","mktempdir([parent=tempdir()]) - - Create a temporary directory in the \"parent\" directory and return - its path. - -"), - -("Base","isblockdev","isblockdev(path) -> Bool - - Returns \"true\" if \"path\" is a block device, \"false\" - otherwise. - -"), - -("Base","ischardev","ischardev(path) -> Bool - - Returns \"true\" if \"path\" is a character device, \"false\" - otherwise. - -"), - -("Base","isdir","isdir(path) -> Bool - - Returns \"true\" if \"path\" is a directory, \"false\" otherwise. - -"), - -("Base","isexecutable","isexecutable(path) -> Bool - - Returns \"true\" if the current user has permission to execute - \"path\", \"false\" otherwise. - -"), - -("Base","isfifo","isfifo(path) -> Bool - - Returns \"true\" if \"path\" is a FIFO, \"false\" otherwise. - -"), - -("Base","isfile","isfile(path) -> Bool - - Returns \"true\" if \"path\" is a regular file, \"false\" - otherwise. - -"), - -("Base","islink","islink(path) -> Bool - - Returns \"true\" if \"path\" is a symbolic link, \"false\" - otherwise. - -"), - -("Base","ismount","ismount(path) -> Bool - - Returns \"true\" if \"path\" is a mount point, \"false\" otherwise. - -"), - -("Base","ispath","ispath(path) -> Bool - - Returns \"true\" if \"path\" is a valid filesystem path, \"false\" - otherwise. - -"), - -("Base","isreadable","isreadable(path) -> Bool - - Returns \"true\" if the current user has permission to read - \"path\", \"false\" otherwise. - -"), - -("Base","issetgid","issetgid(path) -> Bool - - Returns \"true\" if \"path\" has the setgid flag set, \"false\" - otherwise. - -"), - -("Base","issetuid","issetuid(path) -> Bool - - Returns \"true\" if \"path\" has the setuid flag set, \"false\" - otherwise. - -"), - -("Base","issocket","issocket(path) -> Bool - - Returns \"true\" if \"path\" is a socket, \"false\" otherwise. - -"), - -("Base","issticky","issticky(path) -> Bool - - Returns \"true\" if \"path\" has the sticky bit set, \"false\" - otherwise. - -"), - -("Base","iswritable","iswritable(path) -> Bool - - Returns \"true\" if the current user has permission to write to - \"path\", \"false\" otherwise. - -"), - -("Base","homedir","homedir() -> AbstractString - - Return the current user's home directory. - -"), - -("Base","dirname","dirname(path::AbstractString) -> AbstractString - - Get the directory part of a path. - -"), - -("Base","basename","basename(path::AbstractString) -> AbstractString - - Get the file name part of a path. - -"), - -("Base","@__FILE__","@__FILE__() -> AbstractString - - \"@__FILE__\" expands to a string with the absolute path and file - name of the script being run. Returns \"nothing\" if run from a - REPL or an empty string if evaluated by \"julia -e \". - -"), - -("Base","isabspath","isabspath(path::AbstractString) -> Bool - - Determines whether a path is absolute (begins at the root - directory). - -"), - -("Base","isdirpath","isdirpath(path::AbstractString) -> Bool - - Determines whether a path refers to a directory (for example, ends - with a path separator). - -"), - -("Base","joinpath","joinpath(parts...) -> AbstractString - - Join path components into a full path. If some argument is an - absolute path, then prior components are dropped. - -"), - -("Base","abspath","abspath(path::AbstractString) -> AbstractString - - Convert a path to an absolute path by adding the current directory - if necessary. - -"), - -("Base","normpath","normpath(path::AbstractString) -> AbstractString - - Normalize a path, removing \".\" and \"..\" entries. - -"), - -("Base","realpath","realpath(path::AbstractString) -> AbstractString - - Canonicalize a path by expanding symbolic links and removing \".\" - and \"..\" entries. - -"), - -("Base","relpath","relpath(path::AbstractString, startpath::AbstractString = \".\") -> AbstractString - - Return a relative filepath to path either from the current - directory or from an optional start directory. This is a path - computation: the filesystem is not accessed to confirm the - existence or nature of path or startpath. - -"), - -("Base","expanduser","expanduser(path::AbstractString) -> AbstractString - - On Unix systems, replace a tilde character at the start of a path - with the current user's home directory. - -"), - -("Base","splitdir","splitdir(path::AbstractString) -> (AbstractString, AbstractString) - - Split a path into a tuple of the directory name and file name. - -"), - -("Base","splitdrive","splitdrive(path::AbstractString) -> (AbstractString, AbstractString) - - On Windows, split a path into the drive letter part and the path - part. On Unix systems, the first component is always the empty - string. - -"), - -("Base","splitext","splitext(path::AbstractString) -> (AbstractString, AbstractString) - - If the last component of a path contains a dot, split the path into - everything before the dot and everything including and after the - dot. Otherwise, return a tuple of the argument unmodified and the - empty string. - -"), - - -("Base","STDOUT","STDOUT - - Global variable referring to the standard out stream. - -"), - -("Base","STDERR","STDERR - - Global variable referring to the standard error stream. - -"), - -("Base","STDIN","STDIN - - Global variable referring to the standard input stream. - -"), - -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) - - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. - - open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) - - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". - - open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - - open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: - - +–––+–––––––––––––––––-+ | r | read - | +–––+–––––––––––––––––-+ | r+ | read, write - | +–––+–––––––––––––––––-+ | w | write, create, truncate - | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate - | +–––+–––––––––––––––––-+ | a | write, create, append - | +–––+–––––––––––––––––-+ | a+ | read, write, create, append - | +–––+–––––––––––––––––-+ - - open(f::function, args...) - - Apply the function \"f\" to the result of \"open(args...)\" and - close the resulting file descriptor upon completion. - - **Example**: \"open(readall, \"file.txt\")\" - -"), - -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) - - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. - - open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) - - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". - - open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - - open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: - - +–––+–––––––––––––––––-+ | r | read - | +–––+–––––––––––––––––-+ | r+ | read, write - | +–––+–––––––––––––––––-+ | w | write, create, truncate - | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate - | +–––+–––––––––––––––––-+ | a | write, create, append - | +–––+–––––––––––––––––-+ | a+ | read, write, create, append - | +–––+–––––––––––––––––-+ - - open(f::function, args...) - - Apply the function \"f\" to the result of \"open(args...)\" and - close the resulting file descriptor upon completion. - - **Example**: \"open(readall, \"file.txt\")\" - -"), - -("Base","open","open(command, mode::AbstractString=\"r\", stdio=DevNull) - - Start running \"command\" asynchronously, and return a tuple - \"(stream,process)\". If \"mode\" is \"\"r\"\", then \"stream\" - reads from the process's standard output and \"stdio\" optionally - specifies the process's standard input stream. If \"mode\" is - \"\"w\"\", then \"stream\" writes to the process's standard input - and \"stdio\" optionally specifies the process's standard output - stream. - - open(f::Function, command, mode::AbstractString=\"r\", stdio=DevNull) - - Similar to \"open(command, mode, stdio)\", but calls \"f(stream)\" - on the resulting read or write stream, then closes the stream and - waits for the process to complete. Returns the value returned by - \"f\". - - open(file_name[, read, write, create, truncate, append]) -> IOStream - - Open a file in a mode specified by five boolean arguments. The - default is to open files for reading only. Returns a stream for - accessing the file. - - open(file_name[, mode]) -> IOStream - - Alternate syntax for open, where a string-based mode specifier is - used instead of the five booleans. The values of \"mode\" - correspond to those from \"fopen(3)\" or Perl \"open\", and are - equivalent to setting the following boolean groups: - - +–––+–––––––––––––––––-+ | r | read - | +–––+–––––––––––––––––-+ | r+ | read, write - | +–––+–––––––––––––––––-+ | w | write, create, truncate - | +–––+–––––––––––––––––-+ | w+ | read, write, create, truncate - | +–––+–––––––––––––––––-+ | a | write, create, append - | +–––+–––––––––––––––––-+ | a+ | read, write, create, append - | +–––+–––––––––––––––––-+ - - open(f::function, args...) - - Apply the function \"f\" to the result of \"open(args...)\" and - close the resulting file descriptor upon completion. - - **Example**: \"open(readall, \"file.txt\")\" - -"), - -("Base","IOBuffer","IOBuffer() -> IOBuffer - - Create an in-memory I/O stream. - - IOBuffer(size::Int) - - Create a fixed size IOBuffer. The buffer will not grow dynamically. - - IOBuffer(string) - - Create a read-only IOBuffer on the data underlying the given string - - IOBuffer([data][, readable, writable[, maxsize]]) - - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. - -"), - -("Base","IOBuffer","IOBuffer() -> IOBuffer - - Create an in-memory I/O stream. - - IOBuffer(size::Int) - - Create a fixed size IOBuffer. The buffer will not grow dynamically. - - IOBuffer(string) - - Create a read-only IOBuffer on the data underlying the given string - - IOBuffer([data][, readable, writable[, maxsize]]) - - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. - -"), - -("Base","IOBuffer","IOBuffer() -> IOBuffer - - Create an in-memory I/O stream. - - IOBuffer(size::Int) - - Create a fixed size IOBuffer. The buffer will not grow dynamically. - - IOBuffer(string) - - Create a read-only IOBuffer on the data underlying the given string - - IOBuffer([data][, readable, writable[, maxsize]]) - - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. - -"), - -("Base","IOBuffer","IOBuffer() -> IOBuffer - - Create an in-memory I/O stream. - - IOBuffer(size::Int) - - Create a fixed size IOBuffer. The buffer will not grow dynamically. - - IOBuffer(string) - - Create a read-only IOBuffer on the data underlying the given string - - IOBuffer([data][, readable, writable[, maxsize]]) - - Create an IOBuffer, which may optionally operate on a pre-existing - array. If the readable/writable arguments are given, they restrict - whether or not the buffer may be read from or written to - respectively. By default the buffer is readable but not writable. - The last argument optionally specifies a size beyond which the - buffer may not be grown. - -"), - -("Base","takebuf_array","takebuf_array(b::IOBuffer) - - Obtain the contents of an \"IOBuffer\" as an array, without - copying. Afterwards, the IOBuffer is reset to its initial state. - -"), - -("Base","takebuf_string","takebuf_string(b::IOBuffer) - - Obtain the contents of an \"IOBuffer\" as a string, without - copying. Afterwards, the IOBuffer is reset to its initial state. - -"), - -("Base","fdio","fdio([name::AbstractString], fd::Integer[, own::Bool]) -> IOStream - - Create an \"IOStream\" object from an integer file descriptor. If - \"own\" is true, closing this object will close the underlying - descriptor. By default, an \"IOStream\" is closed when it is - garbage collected. \"name\" allows you to associate the descriptor - with a named file. - -"), - -("Base","flush","flush(stream) - - Commit all currently buffered writes to the given stream. - -"), - -("Base","close","close(stream) - - Close an I/O stream. Performs a \"flush\" first. - -"), - -("Base","write","write(stream, x) - - Write the canonical binary representation of a value to the given - stream. - -"), - -("Base","read","read(stream, type) - - Read a value of the given type from a stream, in canonical binary - representation. - - read(stream, type, dims) - - Read a series of values of the given type from a stream, in - canonical binary representation. \"dims\" is either a tuple or a - series of integer arguments specifying the size of \"Array\" to - return. - -"), - -("Base","read","read(stream, type) - - Read a value of the given type from a stream, in canonical binary - representation. - - read(stream, type, dims) - - Read a series of values of the given type from a stream, in - canonical binary representation. \"dims\" is either a tuple or a - series of integer arguments specifying the size of \"Array\" to - return. - -"), - -("Base","read!","read!(stream, array::Array) - - Read binary data from a stream, filling in the argument \"array\". - -"), - -("Base","readbytes!","readbytes!(stream, b::Vector{UInt8}, nb=length(b)) - - Read at most \"nb\" bytes from the stream into \"b\", returning the - number of bytes read (increasing the size of \"b\" as needed). - -"), - -("Base","readbytes","readbytes(stream, nb=typemax(Int)) - - Read at most \"nb\" bytes from the stream, returning a - \"Vector{UInt8}\" of the bytes read. - -"), - -("Base","position","position(s) - - Get the current position of a stream. - -"), - -("Base","seek","seek(s, pos) - - Seek a stream to the given position. - -"), - -("Base","seekstart","seekstart(s) - - Seek a stream to its beginning. - -"), - -("Base","seekend","seekend(s) - - Seek a stream to its end. - -"), - -("Base","skip","skip(s, offset) - - Seek a stream relative to the current position. - -"), - -("Base","mark","mark(s) - - Add a mark at the current position of stream \"s\". Returns the - marked position. - - See also \"unmark()\", \"reset()\", \"ismarked()\" - -"), - -("Base","unmark","unmark(s) - - Remove a mark from stream \"s\". Returns \"true\" if the stream was - marked, \"false\" otherwise. - - See also \"mark()\", \"reset()\", \"ismarked()\" - -"), - -("Base","reset","reset(s) - - Reset a stream \"s\" to a previously marked position, and remove - the mark. Returns the previously marked position. Throws an error - if the stream is not marked. - - See also \"mark()\", \"unmark()\", \"ismarked()\" - -"), - -("Base","ismarked","ismarked(s) - - Returns true if stream \"s\" is marked. - - See also \"mark()\", \"unmark()\", \"reset()\" - -"), - -("Base","eof","eof(stream) -> Bool - - Tests whether an I/O stream is at end-of-file. If the stream is not - yet exhausted, this function will block to wait for more data if - necessary, and then return \"false\". Therefore it is always safe - to read one byte after seeing \"eof\" return \"false\". \"eof\" - will return \"false\" as long as buffered data is still available, - even if the remote end of a connection is closed. - -"), - -("Base","isreadonly","isreadonly(stream) -> Bool - - Determine whether a stream is read-only. - -"), - -("Base","isopen","isopen(stream) -> Bool - - Determine whether a stream is open (i.e. has not been closed yet). - If the connection has been closed remotely (in case of e.g. a - socket), \"isopen\" will return \"false\" even though buffered data - may still be available. Use \"eof\" to check if necessary. - -"), - -("Base","serialize","serialize(stream, value) - - Write an arbitrary value to a stream in an opaque format, such that - it can be read back by \"deserialize\". The read-back value will be - as identical as possible to the original. In general, this process - will not work if the reading and writing are done by different - versions of Julia, or an instance of Julia with a different system - image. - -"), - -("Base","deserialize","deserialize(stream) - - Read a value written by \"serialize\". - -"), - -("Base","print_escaped","print_escaped(io, str::AbstractString, esc::AbstractString) - - General escaping of traditional C and Unicode escape sequences, - plus any characters in esc are also escaped (with a backslash). - -"), - -("Base","print_unescaped","print_unescaped(io, s::AbstractString) - - General unescaping of traditional C and Unicode escape sequences. - Reverse of \"print_escaped()\". - -"), - -("Base","print_joined","print_joined(io, items, delim[, last]) - - Print elements of \"items\" to \"io\" with \"delim\" between them. - If \"last\" is specified, it is used as the final delimiter instead - of \"delim\". - -"), - -("Base","print_shortest","print_shortest(io, x) - - Print the shortest possible representation, with the minimum number - of consecutive non-zero digits, of number \"x\", ensuring that it - would parse to the exact same number. - -"), - -("Base","fd","fd(stream) - - Returns the file descriptor backing the stream or file. Note that - this function only applies to synchronous *File*'s and *IOStream*'s - not to any of the asynchronous streams. - -"), - -("Base","redirect_stdout","redirect_stdout() - - Create a pipe to which all C and Julia level STDOUT output will be - redirected. Returns a tuple (rd,wr) representing the pipe ends. - Data written to STDOUT may now be read from the rd end of the pipe. - The wr end is given for convenience in case the old STDOUT object - was cached by the user and needs to be replaced elsewhere. - - redirect_stdout(stream) - - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - -"), - -("Base","redirect_stdout","redirect_stdout() - - Create a pipe to which all C and Julia level STDOUT output will be - redirected. Returns a tuple (rd,wr) representing the pipe ends. - Data written to STDOUT may now be read from the rd end of the pipe. - The wr end is given for convenience in case the old STDOUT object - was cached by the user and needs to be replaced elsewhere. - - redirect_stdout(stream) - - Replace STDOUT by stream for all C and julia level output to - STDOUT. Note that *stream* must be a TTY, a Pipe or a TcpSocket. - -"), - -("Base","redirect_stderr","redirect_stderr([stream]) - - Like redirect_stdout, but for STDERR - -"), - -("Base","redirect_stdin","redirect_stdin([stream]) - - Like redirect_stdout, but for STDIN. Note that the order of the - return tuple is still (rd,wr), i.e. data to be read from STDIN, may - be written to wr. - -"), - -("Base","readchomp","readchomp(x) - - Read the entirety of x as a string but remove trailing newlines. - Equivalent to chomp(readall(x)). - -"), - -("Base","truncate","truncate(file, n) - - Resize the file or buffer given by the first argument to exactly - *n* bytes, filling previously unallocated space with '0' if the - file or buffer is grown - -"), - -("Base","skipchars","skipchars(stream, predicate; linecomment::Char) - - Advance the stream until before the first character for which - \"predicate\" returns false. For example \"skipchars(stream, - isspace)\" will skip all whitespace. If keyword argument - \"linecomment\" is specified, characters from that character - through the end of a line will also be skipped. - -"), - -("Base","countlines","countlines(io[, eol::Char]) - - Read io until the end of the stream/file and count the number of - non-empty lines. To specify a file pass the filename as the first - argument. EOL markers other than 'n' are supported by passing them - as the second argument. - -"), - -("Base","PipeBuffer","PipeBuffer() - - An IOBuffer that allows reading and performs writes by appending. - Seeking and truncating are not supported. See IOBuffer for the - available constructors. - - PipeBuffer(data::Vector{UInt8}[, maxsize]) - - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. - -"), - -("Base","PipeBuffer","PipeBuffer() - - An IOBuffer that allows reading and performs writes by appending. - Seeking and truncating are not supported. See IOBuffer for the - available constructors. - - PipeBuffer(data::Vector{UInt8}[, maxsize]) - - Create a PipeBuffer to operate on a data vector, optionally - specifying a size beyond which the underlying Array may not be - grown. - -"), - -("Base","readavailable","readavailable(stream) - - Read all available data on the stream, blocking the task only if no - data is available. The result is a \"Vector{UInt8,1}\". - -"), - -("Base","show","show(x) - - Write an informative text representation of a value to the current - output stream. New types should overload \"show(io, x)\" where the - first argument is a stream. The representation used by \"show\" - generally includes Julia-specific formatting and type information. - -"), - -("Base","showcompact","showcompact(x) - - Show a more compact representation of a value. This is used for - printing array elements. If a new type has a different compact - representation, it should overload \"showcompact(io, x)\" where the - first argument is a stream. - -"), - -("Base","showall","showall(x) - - Similar to \"show\", except shows all elements of arrays. - -"), - -("Base","summary","summary(x) - - Return a string giving a brief description of a value. By default - returns \"string(typeof(x))\". For arrays, returns strings like - \"2x2 Float64 Array\". - -"), - -("Base","print","print(x) - - Write (to the default output stream) a canonical (un-decorated) - text representation of a value if there is one, otherwise call - \"show\". The representation used by \"print\" includes minimal - formatting and tries to avoid Julia-specific details. - -"), - -("Base","println","println(x) - - Print (using \"print()\") \"x\" followed by a newline. - -"), - -("Base","print_with_color","print_with_color(color::Symbol[, io], strings...) - - Print strings in a color specified as a symbol, for example - \":red\" or \":blue\". - -"), - -("Base","info","info(msg) - - Display an informational message. - -"), - -("Base","warn","warn(msg) - - Display a warning. - -"), - -("Base","@printf","@printf([io::IOStream], \"%Fmt\", args...) - - Print arg(s) using C \"printf()\" style format specification - string. Optionally, an IOStream may be passed as the first argument - to redirect output. - -"), - -("Base","@sprintf","@sprintf(\"%Fmt\", args...) - - Return \"@printf\" formatted output as string. - -"), - -("Base","sprint","sprint(f::Function, args...) - - Call the given function with an I/O stream and the supplied extra - arguments. Everything written to this I/O stream is returned as a - string. - -"), - -("Base","showerror","showerror(io, e) - - Show a descriptive representation of an exception object. - -"), - -("Base","dump","dump(x) - - Show all user-visible structure of a value. - -"), - -("Base","xdump","xdump(x) - - Show all structure of a value, including all fields of objects. - -"), - -("Base","readall","readall(stream::IO) - - Read the entire contents of an I/O stream as a string. - - readall(filename::AbstractString) - - Open \"filename\", read the entire contents as a string, then close - the file. Equivalent to \"open(readall, filename)\". - -"), - -("Base","readall","readall(stream::IO) - - Read the entire contents of an I/O stream as a string. - - readall(filename::AbstractString) - - Open \"filename\", read the entire contents as a string, then close - the file. Equivalent to \"open(readall, filename)\". - -"), - -("Base","readline","readline(stream=STDIN) - - Read a single line of text, including a trailing newline character - (if one is reached before the end of the input), from the given - \"stream\" (defaults to \"STDIN\"), - -"), - -("Base","readuntil","readuntil(stream, delim) - - Read a string, up to and including the given delimiter byte. - -"), - -("Base","readlines","readlines(stream) - - Read all lines as an array. - -"), - -("Base","eachline","eachline(stream) - - Create an iterable object that will yield each line from a stream. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"n\". - - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". - - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"n\". - - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". - - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"n\". - - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". - - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"n\". - - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". - - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"n\". - - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". - - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","readdlm","readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - - Read a matrix from the source where each line (separated by - \"eol\") gives one row, with elements separated by the given - delimeter. The source can be a text file, stream or byte array. - Memory mapped files can be used by passing the byte array - representation of the mapped segment as source. - - If \"T\" is a numeric type, the result is an array of that type, - with any non-numeric elements as \"NaN\" for floating-point types, - or zero. Other useful values of \"T\" include \"ASCIIString\", - \"AbstractString\", and \"Any\". - - If \"header\" is \"true\", the first row of data will be read as - header and the tuple \"(data_cells, header_cells)\" is returned - instead of only \"data_cells\". - - Specifying \"skipstart\" will ignore the corresponding number of - initial lines from the input. - - If \"skipblanks\" is \"true\", blank lines in the input will be - ignored. - - If \"use_mmap\" is \"true\", the file specified by \"source\" is - memory mapped for potential speedups. Default is \"true\" except on - Windows. On Windows, you may want to specify \"true\" if the file - is large, and is only read once and not written to. - - If \"ignore_invalid_chars\" is \"true\", bytes in \"source\" with - invalid character encoding will be ignored. Otherwise an error is - thrown indicating the offending character position. - - If \"quotes\" is \"true\", column enclosed within double-quote (``) - characters are allowed to contain new lines and column delimiters. - Double-quote characters within a quoted field must be escaped with - another double-quote. - - Specifying \"dims\" as a tuple of the expected rows and columns - (including header, if any) may speed up reading of large files. - - If \"comments\" is \"true\", lines beginning with \"comment_char\" - and text following \"comment_char\" in any line are ignored. - - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some - elements cannot be parsed as numbers, a cell array of numbers and - strings is returned. - - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as \"n\". - - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". - - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. - The end of line delimiter is taken as \"n\". If all data is - numeric, the result will be a numeric array. If some elements - cannot be parsed as numbers, a cell array of numbers and strings is - returned. - -"), - -("Base","writedlm","writedlm(f, A, delim='t') - - Write \"A\" (a vector, matrix or an iterable collection of iterable - rows) as text to \"f\" (either a filename string or an \"IO\" - stream) using the given delimeter \"delim\" (which defaults to tab, - but can be any printable Julia object, typically a \"Char\" or - \"AbstractString\"). - - For example, two vectors \"x\" and \"y\" of the same length can be - written as two columns of tab-delimited text to \"f\" by either - \"writedlm(f, [x y])\" or by \"writedlm(f, zip(x, y))\". - -"), - -("Base","readcsv","readcsv(source, [T::Type]; options...) - - Equivalent to \"readdlm\" with \"delim\" set to comma. - -"), - -("Base","writecsv","writecsv(filename, A) - - Equivalent to \"writedlm\" with \"delim\" set to comma. - -"), - -("Base","Base64EncodePipe","Base64EncodePipe(ostream) - - Returns a new write-only I/O stream, which converts any bytes - written to it into base64-encoded ASCII bytes written to - \"ostream\". Calling \"close\" on the \"Base64Pipe\" stream is - necessary to complete the encoding (but does not close - \"ostream\"). - -"), - -("Base","Base64DecodePipe","Base64DecodePipe(istream) - - Returns a new read-only I/O stream, which decodes base64-encoded - data read from \"istream\". - -"), - -("Base","base64encode","base64encode(writefunc, args...) - - base64encode(args...) - - Given a \"write\"-like function \"writefunc\", which takes an I/O - stream as its first argument, \"base64(writefunc, args...)\" calls - \"writefunc\" to write \"args...\" to a base64-encoded string, and - returns the string. \"base64(args...)\" is equivalent to - \"base64(write, args...)\": it converts its arguments into bytes - using the standard \"write\" functions and returns the - base64-encoded string. - -"), - -("Base","base64decode","base64decode(string) - - Decodes the base64-encoded \"string\" and returns a - \"Vector{UInt8}\" of the decoded bytes. - -"), - -("Base","display","display(x) - - display(d::Display, x) display(mime, x) display(d::Display, mime, - x) - - Display \"x\" using the topmost applicable display in the display - stack, typically using the richest supported multimedia output for - \"x\", with plain-text \"STDOUT\" output as a fallback. The - \"display(d, x)\" variant attempts to display \"x\" on the given - display \"d\" only, throwing a \"MethodError\" if \"d\" cannot - display objects of this type. - - There are also two variants with a \"mime\" argument (a MIME type - string, such as \"\"image/png\"\"), which attempt to display \"x\" - using the requested MIME type *only*, throwing a \"MethodError\" if - this type is not supported by either the display(s) or by \"x\". - With these variants, one can also supply the \"raw\" data in the - requested MIME type by passing \"x::AbstractString\" (for MIME - types with text-based storage, such as text/html or - application/postscript) or \"x::Vector{UInt8}\" (for binary MIME - types). - -"), - -("Base","redisplay","redisplay(x) - - redisplay(d::Display, x) redisplay(mime, x) redisplay(d::Display, - mime, x) - - By default, the \"redisplay\" functions simply call \"display\". - However, some display backends may override \"redisplay\" to modify - an existing display of \"x\" (if any). Using \"redisplay\" is - also a hint to the backend that \"x\" may be redisplayed several - times, and the backend may choose to defer the display until (for - example) the next interactive prompt. - -"), - -("Base","displayable","displayable(mime) -> Bool - - displayable(d::Display, mime) -> Bool - - Returns a boolean value indicating whether the given \"mime\" type - (string) is displayable by any of the displays in the current - display stack, or specifically by the display \"d\" in the second - variant. - -"), - -("Base","writemime","writemime(stream, mime, x) - - The \"display\" functions ultimately call \"writemime\" in order to - write an object \"x\" as a given \"mime\" type to a given I/O - \"stream\" (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - \"T\", it is only necessary to define a new \"writemime\" method - for \"T\", via: \"writemime(stream, ::MIME\"mime\", x::T) = ...\", - where \"mime\" is a MIME-type string and the function body calls - \"write\" (or similar) to write that representation of \"x\" to - \"stream\". (Note that the \"MIME\"\"\" notation only supports - literal strings; to construct \"MIME\" types in a more flexible - manner use \"MIME{symbol(\"\")}\".) - - For example, if you define a \"MyImage\" type and know how to write - it to a PNG file, you could define a function \"writemime(stream, - ::MIME\"image/png\", x::MyImage) = ...`\" to allow your images to - be displayed on any PNG-capable \"Display\" (such as IJulia). As - usual, be sure to \"import Base.writemime\" in order to add new - methods to the built-in Julia function \"writemime\". - - Technically, the \"MIME\"mime\"\" macro defines a singleton type - for the given \"mime\" string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. - -"), - -("Base","mimewritable","mimewritable(mime, x) - - Returns a boolean value indicating whether or not the object \"x\" - can be written as the given \"mime\" type. (By default, this is - determined automatically by the existence of the corresponding - \"writemime\" function for \"typeof(x)\".) - -"), - -("Base","reprmime","reprmime(mime, x) - - Returns an \"AbstractString\" or \"Vector{UInt8}\" containing the - representation of \"x\" in the requested \"mime\" type, as written - by \"writemime\" (throwing a \"MethodError\" if no appropriate - \"writemime\" is available). An \"AbstractString\" is returned for - MIME types with textual representations (such as \"\"text/html\"\" - or \"\"application/postscript\"\"), whereas binary data is returned - as \"Vector{UInt8}\". (The function \"istext(mime)\" returns - whether or not Julia treats a given \"mime\" type as text.) - - As a special case, if \"x\" is an \"AbstractString\" (for textual - MIME types) or a \"Vector{UInt8}\" (for binary MIME types), the - \"reprmime\" function assumes that \"x\" is already in the - requested \"mime\" format and simply returns \"x\". - -"), - -("Base","stringmime","stringmime(mime, x) - - Returns an \"AbstractString\" containing the representation of - \"x\" in the requested \"mime\" type. This is similar to - \"reprmime\" except that binary data is base64-encoded as an ASCII - string. - -"), - -("Base","pushdisplay","pushdisplay(d::Display) - - Pushes a new display \"d\" on top of the global display-backend - stack. Calling \"display(x)\" or \"display(mime, x)\" will display - \"x\" on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a \"MethodError\"). - -"), - -("Base","popdisplay","popdisplay() - - popdisplay(d::Display) - - Pop the topmost backend off of the display-backend stack, or the - topmost copy of \"d\" in the second variant. - -"), - -("Base","TextDisplay","TextDisplay(stream) - - Returns a \"TextDisplay <: Display\", which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same as - the way an object is printed in the Julia REPL.) - -"), - -("Base","istext","istext(m::MIME) - - Determine whether a MIME type is text data. - -"), - -("Base","mmap_array","mmap_array(type, dims, stream[, offset]) - - Create an \"Array\" whose values are linked to a file, using - memory-mapping. This provides a convenient way of working with data - too large to fit in the computer's memory. - - The type determines how the bytes of the array are interpreted. - Note that the file must be stored in binary format, and no format - conversions are possible (this is a limitation of operating - systems, not Julia). - - \"dims\" is a tuple specifying the size of the array. - - The file is passed via the stream argument. When you initialize - the stream, use \"\"r\"\" for a \"read-only\" array, and \"\"w+\"\" - to create a new array used to write values to disk. - - Optionally, you can specify an offset (in bytes) if, for example, - you want to skip over a header in the file. The default value for - the offset is the current stream position. - - For example, the following code: - - # Create a file for mmapping - # (you could alternatively use mmap_array to do this step, too) - A = rand(1:20, 5, 30) - s = open(\"/tmp/mmap.bin\", \"w+\") - # We'll write the dimensions of the array as the first two Ints in the file - write(s, size(A,1)) - write(s, size(A,2)) - # Now write the data - write(s, A) - close(s) - - # Test by reading it back in - s = open(\"/tmp/mmap.bin\") # default is read-only - m = read(s, Int) - n = read(s, Int) - A2 = mmap_array(Int, (m,n), s) - - creates a \"m\"-by-\"n\" \"Matrix{Int}\", linked to the file - associated with stream \"s\". - - A more portable file would need to encode the word size–-32 bit or - 64 bit–-and endianness information in the header. In practice, - consider encoding binary data using standard formats like HDF5 - (which can be used with memory-mapping). - -"), - -("Base","mmap_bitarray","mmap_bitarray([type], dims, stream[, offset]) - - Create a \"BitArray\" whose values are linked to a file, using - memory-mapping; it has the same purpose, works in the same way, and - has the same arguments, as \"mmap_array()\", but the byte - representation is different. The \"type\" parameter is optional, - and must be \"Bool\" if given. - - **Example**: \"B = mmap_bitarray((25,30000), s)\" - - This would create a 25-by-30000 \"BitArray\", linked to the file - associated with stream \"s\". - -"), - -("Base","msync","msync(array) - - Forces synchronization between the in-memory version of a memory- - mapped \"Array\" or \"BitArray\" and the on-disk version. - -"), - -("Base","connect","connect([host], port) -> TcpSocket - - Connect to the host \"host\" on port \"port\" - - connect(path) -> Pipe - - Connect to the Named Pipe/Domain Socket at \"path\" - - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id \"pid\", specified - by \"config\" and return a pair of \"AsyncStream\" objects. - Messages from \"pid\" to current process will be read off - \"instrm\", while messages to be sent to \"pid\" will be written to - \"outstrm\". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP - socket connections in-between workers. - -"), - -("Base","connect","connect([host], port) -> TcpSocket - - Connect to the host \"host\" on port \"port\" - - connect(path) -> Pipe - - Connect to the Named Pipe/Domain Socket at \"path\" - - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id \"pid\", specified - by \"config\" and return a pair of \"AsyncStream\" objects. - Messages from \"pid\" to current process will be read off - \"instrm\", while messages to be sent to \"pid\" will be written to - \"outstrm\". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP - socket connections in-between workers. - -"), - -("Base","listen","listen([addr], port) -> TcpServer - - Listen on port on the address specified by \"addr\". By default - this listens on localhost only. To listen on all interfaces pass, - \"IPv4(0)\" or \"IPv6(0)\" as appropriate. - - listen(path) -> PipeServer - - Listens on/Creates a Named Pipe/Domain Socket - -"), - -("Base","listen","listen([addr], port) -> TcpServer - - Listen on port on the address specified by \"addr\". By default - this listens on localhost only. To listen on all interfaces pass, - \"IPv4(0)\" or \"IPv6(0)\" as appropriate. - - listen(path) -> PipeServer - - Listens on/Creates a Named Pipe/Domain Socket - -"), - -("Base","getaddrinfo","getaddrinfo(host) - - Gets the IP address of the \"host\" (may have to do a DNS lookup) - -"), - -("Base","parseip","parseip(addr) - - Parse a string specifying an IPv4 or IPv6 ip address. - -"), - -("Base","IPv4","IPv4(host::Integer) -> IPv4 - - Returns IPv4 object from ip address formatted as Integer - -"), - -("Base","IPv6","IPv6(host::Integer) -> IPv6 - - Returns IPv6 object from ip address formatted as Integer - -"), - -("Base","nb_available","nb_available(stream) - - Returns the number of bytes available for reading before a read - from this stream or buffer will block. - -"), - -("Base","accept","accept(server[, client]) - - Accepts a connection on the given server and returns a connection - to the client. An uninitialized client stream may be provided, in - which case it will be used instead of creating a new stream. - -"), - -("Base","listenany","listenany(port_hint) -> (UInt16, TcpServer) - - Create a TcpServer on any port, using hint as a starting point. - Returns a tuple of the actual port that the server was created on - and the server itself. - -"), - -("Base","watch_file","watch_file(cb=false, s; poll=false) - - Watch file or directory \"s\" and run callback \"cb\" when \"s\" is - modified. The \"poll\" parameter specifies whether to use file - system event monitoring or polling. The callback function \"cb\" - should accept 3 arguments: \"(filename, events, status)\" where - \"filename\" is the name of file that was modified, \"events\" is - an object with boolean fields \"changed\" and \"renamed\" when - using file system event monitoring, or \"readable\" and - \"writable\" when using polling, and \"status\" is always 0. Pass - \"false\" for \"cb\" to not use a callback function. - -"), - -("Base","poll_fd","poll_fd(fd, seconds::Real; readable=false, writable=false) - - Poll a file descriptor fd for changes in the read or write - availability and with a timeout given by the second argument. If - the timeout is not needed, use \"wait(fd)\" instead. The keyword - arguments determine which of read and/or write status should be - monitored and at least one of them needs to be set to true. The - returned value is an object with boolean fields \"readable\", - \"writable\", and \"timedout\", giving the result of the polling. - -"), - -("Base","poll_file","poll_file(s, interval_seconds::Real, seconds::Real) - - Monitor a file for changes by polling every *interval_seconds* - seconds for *seconds* seconds. A return value of true indicates the - file changed, a return value of false indicates a timeout. - -"), - -("Base","bind","bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) - - Bind \"socket\" to the given \"host:port\". Note that *0.0.0.0* - will listen on all devices. - -"), - -("Base","send","send(socket::UDPSocket, host::IPv4, port::Integer, msg) - - Send \"msg\" over \"socket to >>``< (address, data) - - Read a UDP packet from the specified socket, returning a tuple of - (address, data), where address will be either IPv4 or IPv6 as - appropriate. - -"), - -("Base","setopt","setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - - Set UDP socket options. \"multicast_loop\": loopback for multicast - packets (default: true). \"multicast_ttl\": TTL for multicast - packets. \"enable_broadcast\": flag must be set to true if socket - will be used for broadcast messages, or else the UDP system will - return an access error (default: false). \"ttl\": Time-to-live of - packets sent on the socket. - -"), - -("Base","ntoh","ntoh(x) - - Converts the endianness of a value from Network byte order (big- - endian) to that used by the Host. - -"), - -("Base","hton","hton(x) - - Converts the endianness of a value from that used by the Host to - Network byte order (big-endian). - -"), - -("Base","ltoh","ltoh(x) - - Converts the endianness of a value from Little-endian to that used - by the Host. - -"), - -("Base","htol","htol(x) - - Converts the endianness of a value from that used by the Host to - Little-endian. - -"), - -("Base","ENDIAN_BOM","ENDIAN_BOM - - The 32-bit byte-order-mark indicates the native byte order of the - host machine. Little-endian machines will contain the value - 0x04030201. Big-endian machines will contain the value 0x01020304. - -"), - -("Libc","malloc","malloc(size::Integer) -> Ptr{Void} - - Call \"malloc\" from the C standard library. - -"), - -("Libc","calloc","calloc(num::Integer, size::Integer) -> Ptr{Void} - - Call \"calloc\" from the C standard library. - -"), - -("Libc","realloc","realloc(addr::Ptr, size::Integer) -> Ptr{Void} - - Call \"realloc\" from the C standard library. - - See warning in the documentation for \"free\" regarding only using - this on memory originally obtained from \"malloc\". - -"), - -("Libc","free","free(addr::Ptr) - - Call \"free\" from the C standard library. Only use this on memory - obtained from \"malloc\", not on pointers retrieved from other C - libraries. \"Ptr\" objects obtained from C libraries should be - freed by the free functions defined in that library, to avoid - assertion failures if multiple \"libc\" libraries exist on the - system. - -"), - -("Libc","errno","errno([code]) - - Get the value of the C library's \"errno\". If an argument is - specified, it is used to set the value of \"errno\". - - The value of \"errno\" is only valid immediately after a \"ccall\" - to a C library routine that sets it. Specifically, you cannot call - \"errno\" at the next prompt in a REPL, because lots of code is - executed between prompts. - -"), - -("Libc","strerror","strerror(n) - - Convert a system call error code to a descriptive string - -"), - -("Libc","time","time() - - Get the system time in seconds since the epoch, with fairly high - (typically, microsecond) resolution. - -"), - -("Libc","strftime","strftime([format], time) - - Convert time, given as a number of seconds since the epoch or a - \"TmStruct\", to a formatted string using the given format. - Supported formats are the same as those in the standard C library. - -"), - -("Libc","strptime","strptime([format], timestr) - - Parse a formatted time string into a \"TmStruct\" giving the - seconds, minute, hour, date, etc. Supported formats are the same as - those in the standard C library. On some platforms, timezones will - not be parsed correctly. If the result of this function will be - passed to \"time\" to convert it to seconds since the epoch, the - \"isdst\" field should be filled in manually. Setting it to \"-1\" - will tell the C library to use the current system settings to - determine the timezone. - -"), - -("Libc","TmStruct","TmStruct([seconds]) - - Convert a number of seconds since the epoch to broken-down format, - with fields \"sec\", \"min\", \"hour\", \"mday\", \"month\", - \"year\", \"wday\", \"yday\", and \"isdst\". - -"), - -("Libc","flush_cstdio","flush_cstdio() - - Flushes the C \"stdout\" and \"stderr\" streams (which may have - been written to by external C code). - -"), - -("Libc","msync","msync(array) - - Forces synchronization between the in-memory version of a memory- - mapped \"Array\" or \"BitArray\" and the on-disk version. - -"), - -("Libc","MS_ASYNC","MS_ASYNC - - Enum constant for \"msync()\". See your platform man page for - details. (not available on Windows). - -"), - -("Libc","MS_SYNC","MS_SYNC - - Enum constant for \"msync()\". See your platform man page for - details. (not available on Windows). - -"), - -("Libc","MS_INVALIDATE","MS_INVALIDATE - - Enum constant for \"msync()\". See your platform man page for - details. (not available on Windows). - -"), - -("Libc","mmap","mmap(len, prot, flags, fd, offset) - - Low-level interface to the \"mmap\" system call. See the man page. - -"), - -("Libc","munmap","munmap(pointer, len) - - Low-level interface for unmapping memory (see the man page). With - \"mmap_array()\" you do not need to call this directly; the memory - is unmapped for you when the array goes out of scope. - -"), - -("Libdl","dlopen","dlopen(libfile::AbstractString[, flags::Integer]) - - Load a shared library, returning an opaque handle. - - The optional flags argument is a bitwise-or of zero or more of - \"RTLD_LOCAL\", \"RTLD_GLOBAL\", \"RTLD_LAZY\", \"RTLD_NOW\", - \"RTLD_NODELETE\", \"RTLD_NOLOAD\", \"RTLD_DEEPBIND\", and - \"RTLD_FIRST\". These are converted to the corresponding flags of - the POSIX (and/or GNU libc and/or MacOS) dlopen command, if - possible, or are ignored if the specified functionality is not - available on the current platform. The default is - \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL\". An important usage of - these flags, on POSIX platforms, is to specify - \"RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL\" in order for the library's - symbols to be available for usage in other shared libraries, in - situations where there are dependencies between shared libraries. - -"), - -("Libdl","dlopen_e","dlopen_e(libfile::AbstractString[, flags::Integer]) - - Similar to \"dlopen()\", except returns a \"NULL\" pointer instead - of raising errors. - -"), - -("Libdl","RTLD_DEEPBIND","RTLD_DEEPBIND - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_FIRST","RTLD_FIRST - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_GLOBAL","RTLD_GLOBAL - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_LAZY","RTLD_LAZY - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_LOCAL","RTLD_LOCAL - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_NODELETE","RTLD_NODELETE - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_NOLOAD","RTLD_NOLOAD - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","RTLD_NOW","RTLD_NOW - - Enum constant for \"dlopen()\". See your platform man page for - details, if applicable. - -"), - -("Libdl","dlsym","dlsym(handle, sym) - - Look up a symbol from a shared library handle, return callable - function pointer on success. - -"), - -("Libdl","dlsym_e","dlsym_e(handle, sym) - - Look up a symbol from a shared library handle, silently return NULL - pointer on lookup failure. - -"), - -("Libdl","dlclose","dlclose(handle) - - Close shared library referenced by handle. - -"), - -("Libdl","find_library","find_library(names, locations) - - Searches for the first library in \"names\" in the paths in the - \"locations\" list, \"DL_LOAD_PATH\", or system library paths (in - that order) which can successfully be dlopen'd. On success, the - return value will be one of the names (potentially prefixed by one - of the paths in locations). This string can be assigned to a - \"global const\" and used as the library name in future - \"ccall\"'s. On failure, it returns the empty string. - -"), - -("Libdl","DL_LOAD_PATH","DL_LOAD_PATH - - When calling \"dlopen\", the paths in this list will be searched - first, in order, before searching the system locations for a valid - library handle. - -"), - -("Base","*","*(A, B) - - Matrix multiplication - - *(x, y...) - - Multiplication operator. \"x*y*z*...\" calls this function with all - arguments, i.e. \">>*<<(x, y, z, ...)\". - - *(s, t) - - Concatenate strings. The \"*\" operator is an alias to this - function. - - julia> \"Hello \" * \"world\" - \"Hello world\" - -"), - -("Base","\\","\\(A, B) - - Matrix division using a polyalgorithm. For input matrices \"A\" and - \"B\", the result \"X\" is such that \"A*X == B\" when \"A\" is - square. The solver that is used depends upon the structure of - \"A\". A direct solver is used for upper- or lower triangular - \"A\". For Hermitian \"A\" (equivalent to symmetric \"A\" for non- - complex \"A\") the \"BunchKaufman\" factorization is used. - Otherwise an LU factorization is used. For rectangular \"A\" the - result is the minimum-norm least squares solution computed by a - pivoted QR factorization of \"A\" and a rank estimate of A based on - the R factor. - - When \"A\" is sparse, a similar polyalgorithm is used. For - indefinite matrices, the LDLt factorization does not use pivoting - during the numerical factorization and therefore the procedure can - fail even for invertible matrices. - -"), - -("Base","dot","dot(x, y) - - ⋅(x, y) - - Compute the dot product. For complex vectors, the first vector is - conjugated. - -"), - -("Base","vecdot","vecdot(x, y) - - For any iterable containers \"x\" and \"y\" (including arrays of - any dimension) of numbers (or any element type for which \"dot\" is - defined), compute the Euclidean dot product (the sum of - \"dot(x[i],y[i])\") as if they were vectors. - -"), - -("Base","cross","cross(x, y) - - ×(x, y) - - Compute the cross product of two 3-vectors. - -"), - -("Base","factorize","factorize(A) - - Compute a convenient factorization (including LU, Cholesky, Bunch- - Kaufman, LowerTriangular, UpperTriangular) of A, based upon the - type of the input matrix. The return value can then be reused for - efficient solving of multiple systems. For example: - \"A=factorize(A); x=Ab; y=AC\". - -"), - -("Base","full","full(S) - - Convert a sparse matrix \"S\" into a dense matrix. - - full(F) - - Reconstruct the matrix \"A\" from the factorization - \"F=factorize(A)\". - - full(QRCompactWYQ[, thin=true]) -> Matrix - - Converts an orthogonal or unitary matrix stored as a - \"QRCompactWYQ\" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. - - Optionally takes a \"thin\" Boolean argument, which if \"true\" - omits the columns that span the rows of \"R\" in the QR - factorization that are zero. The resulting matrix is the \"Q\" - in a thin QR factorization (sometimes called the reduced QR - factorization). If \"false\", returns a \"Q\" that spans all - rows of \"R\" in its corresponding QR factorization. - - Reconstruct the matrix \"A\" from the factorization - \"F=factorize(A)\". - -"), - -("Base","lu","lu(A) -> L, U, p - - Compute the LU factorization of \"A\", such that \"A[p,:] = L*U\". - -"), - -("Base","lufact","lufact(A[, pivot=Val{true}]) -> F - - Compute the LU factorization of \"A\". The return type of \"F\" - depends on the type of \"A\". In most cases, if \"A\" is a subtype - \"S\" of AbstractMatrix with an element type \"T`\" supporting - \"+\", \"-\", \"*\" and \"/\" the return type is \"LU{T,S{T}}\". If - pivoting is chosen (default) the element type should also support - \"abs\" and \"<\". When \"A\" is sparse and have element of type - \"Float32\", \"Float64\", \"Complex{Float32}\", or - \"Complex{Float64}\" the return type is \"UmfpackLU\". Some - examples are shown in the table below. - - +-------------------------+---------------------------+----------------------------------------------+ - | Type of input \"A\" | Type of output \"F\" | Relationship between \"F\" and \"A\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Matrix()\" | \"LU\" | \"F[:L]*F[:U] == A[F[:p], :]\" | - +-------------------------+---------------------------+----------------------------------------------+ - | \"Tridiagonal()\" | \"LU{T,Tridiagonal{T}}\" | N/A | - +-------------------------+---------------------------+----------------------------------------------+ - | \"SparseMatrixCSC()\" | \"UmfpackLU\" | \"F[:L]*F[:U] == F[:Rs] .* A[F[:p], F[:q]]\" | - +-------------------------+---------------------------+----------------------------------------------+ - - The individual components of the factorization \"F\" can be - accessed by indexing: - - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | Component | Description | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:L]\" | \"L\" (lower triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:U]\" | \"U\" (upper triangular) part of \"LU\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:p]\" | (right) permutation \"Vector\" | ✓ | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:P]\" | (right) permutation \"Matrix\" | ✓ | | | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:q]\" | left permutation \"Vector\" | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:Rs]\" | \"Vector\" of scaling factors | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - | \"F[:(:)]\" | \"(L,U,p,q,Rs)\" components | | | ✓ | - +-------------+-----------------------------------------+--------+--------------------------+---------------+ - - +--------------------+--------+--------------------------+---------------+ - | Supported function | \"LU\" | \"LU{T,Tridiagonal{T}}\" | \"UmfpackLU\" | - +--------------------+--------+--------------------------+---------------+ - | \"/\" | ✓ | | | - +--------------------+--------+--------------------------+---------------+ - | \"\\\\\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"cond\" | ✓ | | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"det\" | ✓ | ✓ | ✓ | - +--------------------+--------+--------------------------+---------------+ - | \"logdet\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | \"logabsdet\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - | \"size\" | ✓ | ✓ | | - +--------------------+--------+--------------------------+---------------+ - -"), - -("Base","lufact!","lufact!(A) -> LU - - \"lufact!\" is the same as \"lufact()\", but saves space by - overwriting the input A, instead of creating a copy. For sparse - \"A\" the \"nzval\" field is not overwritten but the index fields, - \"colptr\" and \"rowval\" are decremented in place, converting from - 1-based indices to 0-based indices. - -"), - -("Base","chol","chol(A[, LU]) -> F - - Compute the Cholesky factorization of a symmetric positive definite - matrix \"A\" and return the matrix \"F\". If \"LU\" is \"Val{:U}\" - (Upper), \"F\" is of type \"UpperTriangular\" and \"A = F'>>*< Cholesky - - Compute the Cholesky factorization of a dense symmetric positive - (semi)definite matrix \"A\" and return either a \"Cholesky\" if - \"pivot==Val{false}\" or \"CholeskyPivoted\" if - \"pivot==Val{true}\". \"LU\" may be \":L\" for using the lower part - or \":U\" for the upper part. The default is to use \":U\". The - triangular matrix can be obtained from the factorization \"F\" - with: \"F[:L]\" and \"F[:U]\". The following functions are - available for \"Cholesky\" objects: \"size\", \"\", \"inv\", - \"det\". For \"CholeskyPivoted\" there is also defined a \"rank\". - If \"pivot==Val{false}\" a \"PosDefException\" exception is thrown - in case the matrix is not positive definite. The argument \"tol\" - determines the tolerance for determining the rank. For negative - values, the tolerance is the machine precision. - - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the Cholesky factorization of a sparse positive definite - matrix \"A\". A fill-reducing permutation is used. \"F = - cholfact(A)\" is most frequently used to solve systems of equations - with \"Fb\", but also the methods \"diag\", \"det\", \"logdet\" are - defined for \"F\". You can also extract individual factors from - \"F\", using \"F[:L]\". However, since pivoting is on by default, - the factorization is internally represented as \"A == - P'>>*<>*<>*<>*< Cholesky - - Compute the Cholesky factorization of a dense symmetric positive - (semi)definite matrix \"A\" and return either a \"Cholesky\" if - \"pivot==Val{false}\" or \"CholeskyPivoted\" if - \"pivot==Val{true}\". \"LU\" may be \":L\" for using the lower part - or \":U\" for the upper part. The default is to use \":U\". The - triangular matrix can be obtained from the factorization \"F\" - with: \"F[:L]\" and \"F[:U]\". The following functions are - available for \"Cholesky\" objects: \"size\", \"\", \"inv\", - \"det\". For \"CholeskyPivoted\" there is also defined a \"rank\". - If \"pivot==Val{false}\" a \"PosDefException\" exception is thrown - in case the matrix is not positive definite. The argument \"tol\" - determines the tolerance for determining the rank. For negative - values, the tolerance is the machine precision. - - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the Cholesky factorization of a sparse positive definite - matrix \"A\". A fill-reducing permutation is used. \"F = - cholfact(A)\" is most frequently used to solve systems of equations - with \"Fb\", but also the methods \"diag\", \"det\", \"logdet\" are - defined for \"F\". You can also extract individual factors from - \"F\", using \"F[:L]\". However, since pivoting is on by default, - the factorization is internally represented as \"A == - P'>>*<>*<>*<>*< Cholesky - - \"cholfact!\" is the same as \"cholfact()\", but saves space by - overwriting the input \"A\", instead of creating a copy. - \"cholfact!\" can also reuse the symbolic factorization from a - different matrix \"F\" with the same structure when used as: - \"cholfact!(F::CholmodFactor, A)\". - -"), - -("Base","ldltfact","ldltfact(A) -> LDLtFactorization - - Compute a factorization of a positive definite matrix \"A\" such - that \"A=L*Diagonal(d)*L'\" where \"L\" is a unit lower triangular - matrix and \"d\" is a vector with non-negative elements. - - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix \"A\". A fill-reducing permutation is used. \"F = - ldltfact(A)\" is most frequently used to solve systems of equations - with \"Fb\", but also the methods \"diag\", \"det\", \"logdet\" are - defined for \"F\". You can also extract individual factors from - \"F\", using \"F[:L]\". However, since pivoting is on by default, - the factorization is internally represented as \"A == - P'>>*<>*<>*<>*< LDLtFactorization - - Compute a factorization of a positive definite matrix \"A\" such - that \"A=L*Diagonal(d)*L'\" where \"L\" is a unit lower triangular - matrix and \"d\" is a vector with non-negative elements. - - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - - Compute the LDLt factorization of a sparse symmetric or Hermitian - matrix \"A\". A fill-reducing permutation is used. \"F = - ldltfact(A)\" is most frequently used to solve systems of equations - with \"Fb\", but also the methods \"diag\", \"det\", \"logdet\" are - defined for \"F\". You can also extract individual factors from - \"F\", using \"F[:L]\". However, since pivoting is on by default, - the factorization is internally represented as \"A == - P'>>*<>*<>*<>*< Q, R, [p] - - Compute the (pivoted) QR factorization of \"A\" such that either - \"A = Q*R\" or \"A[:,p] = Q*R\". Also see \"qrfact\". The default - is to compute a thin factorization. Note that \"R\" is not extended - with zeros when the full \"Q\" is requested. - -"), - -("Base","qrfact","qrfact(A[, pivot=Val{false}]) -> F - - Computes the QR factorization of \"A\". The return type of \"F\" - depends on the element type of \"A\" and whether pivoting is - specified (with \"pivot==Val{true}\"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - - \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", - \"Complex64\" or \"Complex128\". - - The individual components of the factorization \"F\" can be - accessed by indexing: - - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:p]\" | pivot \"Vector\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - - The following functions are available for the \"QR\" objects: - \"size\", \"\". When \"A\" is rectangular, \"\" will return a least - squares solution and if the solution is not unique, the one with - smallest norm is returned. - - Multiplication with respect to either thin or full \"Q\" is - allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A - \"Q\" matrix can be converted into a regular matrix with \"full()\" - which has a named argument \"thin\". - - Note: \"qrfact\" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the \"Q\" and \"R\" matrices can be stored compactly rather - as two separate dense matrices.The data contained in \"QR\" or - \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, - which is a compact representation of the rotation matrix: - - Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) - - where tau_i is the scale factor and v_i is the projection vector - associated with the i^{th} Householder elementary reflector.The - data contained in \"QRCompactWY\" can be used to construct the - \"QRCompactWYQ\" type, which is a compact representation of the - rotation matrix - - Q = I + Y T Y^T - - where \"Y\" is m times r lower trapezoidal and \"T\" is r times r - upper triangular. The *compact WY* representation [Schreiber1989] - is not to be confused with the older, *WY* representation - [Bischof1987]. (The LAPACK documentation uses \"V\" in lieu of - \"Y\".) - - [Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 - - [Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 - - qrfact(A) -> SPQR.Factorization - - Compute the QR factorization of a sparse matrix \"A\". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with \"\". The function calls the C - library SPQR and a few additional functions from the library are - wrapped but not exported. - -"), - -("Base","qrfact","qrfact(A[, pivot=Val{false}]) -> F - - Computes the QR factorization of \"A\". The return type of \"F\" - depends on the element type of \"A\" and whether pivoting is - specified (with \"pivot==Val{true}\"). - - +------------------+-------------------+----------------+---------------------------------------+ - | Return type | \"eltype(A)\" | \"pivot\" | Relationship between \"F\" and \"A\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QR\" | not \"BlasFloat\" | either | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRCompactWY\" | \"BlasFloat\" | \"Val{false}\" | \"A==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - | \"QRPivoted\" | \"BlasFloat\" | \"Val{true}\" | \"A[:,F[:p]]==F[:Q]*F[:R]\" | - +------------------+-------------------+----------------+---------------------------------------+ - - \"BlasFloat\" refers to any of: \"Float32\", \"Float64\", - \"Complex64\" or \"Complex128\". - - The individual components of the factorization \"F\" can be - accessed by indexing: - - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | Component | Description | \"QR\" | \"QRCompactWY\" | \"QRPivoted\" | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:Q]\" | \"Q\" (orthogonal/unitary) part of \"QR\" | ✓ (\"QRPackedQ\") | ✓ (\"QRCompactWYQ\") | ✓ (\"QRPackedQ\") | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:R]\" | \"R\" (upper right triangular) part of \"QR\" | ✓ | ✓ | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:p]\" | pivot \"Vector\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - | \"F[:P]\" | (pivot) permutation \"Matrix\" | | | ✓ | - +-------------+-----------------------------------------------+--------------------+-----------------------+--------------------+ - - The following functions are available for the \"QR\" objects: - \"size\", \"\". When \"A\" is rectangular, \"\" will return a least - squares solution and if the solution is not unique, the one with - smallest norm is returned. - - Multiplication with respect to either thin or full \"Q\" is - allowed, i.e. both \"F[:Q]*F[:R]\" and \"F[:Q]*A\" are supported. A - \"Q\" matrix can be converted into a regular matrix with \"full()\" - which has a named argument \"thin\". - - Note: \"qrfact\" returns multiple types because LAPACK uses - several representations that minimize the memory storage - requirements of products of Householder elementary reflectors, so - that the \"Q\" and \"R\" matrices can be stored compactly rather - as two separate dense matrices.The data contained in \"QR\" or - \"QRPivoted\" can be used to construct the \"QRPackedQ\" type, - which is a compact representation of the rotation matrix: - - Q = \\prod_{i=1}^{\\min(m,n)} (I - \\tau_i v_i v_i^T) - - where tau_i is the scale factor and v_i is the projection vector - associated with the i^{th} Householder elementary reflector.The - data contained in \"QRCompactWY\" can be used to construct the - \"QRCompactWYQ\" type, which is a compact representation of the - rotation matrix - - Q = I + Y T Y^T - - where \"Y\" is m times r lower trapezoidal and \"T\" is r times r - upper triangular. The *compact WY* representation [Schreiber1989] - is not to be confused with the older, *WY* representation - [Bischof1987]. (The LAPACK documentation uses \"V\" in lieu of - \"Y\".) - - [Bischof1987] C Bischof and C Van Loan, The WY - representation for products of Householder matrices, - SIAM J Sci Stat Comput 8 (1987), s2-s13. - doi:10.1137/0908009 - - [Schreiber1989] R Schreiber and C Van Loan, A - storage-efficient WY representation for products of - Householder transformations, SIAM J Sci Stat Comput - 10 (1989), 53-57. doi:10.1137/0910005 - - qrfact(A) -> SPQR.Factorization - - Compute the QR factorization of a sparse matrix \"A\". A fill- - reducing permutation is used. The main application of this type is - to solve least squares problems with \"\". The function calls the C - library SPQR and a few additional functions from the library are - wrapped but not exported. - -"), - -("Base","qrfact!","qrfact!(A[, pivot=Val{false}]) - - \"qrfact!\" is the same as \"qrfact()\" when A is a subtype of - \"StridedMatrix\", but saves space by overwriting the input \"A\", - instead of creating a copy. - -"), - -("Base","full","full(S) - - Convert a sparse matrix \"S\" into a dense matrix. - - full(F) - - Reconstruct the matrix \"A\" from the factorization - \"F=factorize(A)\". - - full(QRCompactWYQ[, thin=true]) -> Matrix - - Converts an orthogonal or unitary matrix stored as a - \"QRCompactWYQ\" object, i.e. in the compact WY format - [Bischof1987], to a dense matrix. - - Optionally takes a \"thin\" Boolean argument, which if \"true\" - omits the columns that span the rows of \"R\" in the QR - factorization that are zero. The resulting matrix is the \"Q\" in a - thin QR factorization (sometimes called the reduced QR - factorization). If \"false\", returns a \"Q\" that spans all rows - of \"R\" in its corresponding QR factorization. - -"), - -("Base","bkfact","bkfact(A) -> BunchKaufman - - Compute the Bunch-Kaufman [Bunch1977] factorization of a real - symmetric or complex Hermitian matrix \"A\" and return a - \"BunchKaufman\" object. The following functions are available for - \"BunchKaufman\" objects: \"size\", \"\", \"inv\", \"issym\", - \"ishermitian\". - -"), - -("Base","bkfact!","bkfact!(A) -> BunchKaufman - - \"bkfact!\" is the same as \"bkfact()\", but saves space by - overwriting the input \"A\", instead of creating a copy. - -"), - -("Base","sqrtm","sqrtm(A) - - Compute the matrix square root of \"A\". If \"B = sqrtm(A)\", then - \"B*B == A\" within roundoff error. - - \"sqrtm\" uses a polyalgorithm, computing the matrix square root - using Schur factorizations (\"schurfact()\") unless it detects the - matrix to be Hermitian or real symmetric, in which case it computes - the matrix square root from an eigendecomposition (\"eigfact()\"). - In the latter situation for positive definite matrices, the matrix - square root has \"Real\" elements, otherwise it has \"Complex\" - elements. - -"), - -("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - - Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" - for details on the \"balance\" keyword argument. - - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) - - \"eig\" is a wrapper around \"eigfact()\", extracting all parts of - the factorization to a tuple; where possible, using \"eigfact()\" - is recommended. - - eig(A, B) -> D, V - - Computes generalized eigenvalues and vectors of \"A\" with respect - to \"B\". - - \"eig\" is a wrapper around \"eigfact()\", extracting all parts of - the factorization to a tuple; where possible, using \"eigfact()\" - is recommended. - -"), - -("Base","eig","eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - - Computes eigenvalues and eigenvectors of \"A\". See \"eigfact()\" - for details on the \"balance\" keyword argument. - - julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) - ([1.0,3.0,18.0], - 3x3 Array{Float64,2}: - 1.0 0.0 0.0 - 0.0 1.0 0.0 - 0.0 0.0 1.0) - - \"eig\" is a wrapper around \"eigfact()\", extracting all parts of - the factorization to a tuple; where possible, using \"eigfact()\" - is recommended. - - eig(A, B) -> D, V - - Computes generalized eigenvalues and vectors of \"A\" with respect - to \"B\". - - \"eig\" is a wrapper around \"eigfact()\", extracting all parts of - the factorization to a tuple; where possible, using \"eigfact()\" - is recommended. - -"), - -("Base","eigvals","eigvals(A,[irange,][vl,][vu]) - - Returns the eigenvalues of \"A\". If \"A\" is \"Symmetric\", - \"Hermitian\" or \"SymTridiagonal\", it is possible to calculate - only a subset of the eigenvalues by specifying either a - \"UnitRange\" \"irange\" covering indices of the sorted - eigenvalues, or a pair \"vl\" and \"vu\" for the lower and upper - boundaries of the eigenvalues. - - For general non-symmetric matrices it is possible to specify how - the matrix is balanced before the eigenvector calculation. The - option \"permute=true\" permutes the matrix to become closer to - upper triangular, and \"scale=true\" scales the matrix by its - diagonal elements to make rows and columns more equal in norm. The - default is \"true\" for both options. - -"), - -("Base","eigmax","eigmax(A) - - Returns the largest eigenvalue of \"A\". - -"), - -("Base","eigmin","eigmin(A) - - Returns the smallest eigenvalue of \"A\". - -"), - -("Base","eigvecs","eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix - - Returns a matrix \"M\" whose columns are the eigenvectors of \"A\". - (The \"k\"th eigenvector can be obtained from the slice \"M[:, - k]\".) The \"permute\" and \"scale\" keywords are the same as for - \"eigfact()\". - - For \"SymTridiagonal\" matrices, if the optional vector of - eigenvalues \"eigvals\" is specified, returns the specific - corresponding eigenvectors. - -"), - -("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - - Computes the eigenvalue decomposition of \"A\", returning an - \"Eigen\" factorization object \"F\" which contains the eigenvalues - in \"F[:values]\" and the eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the - slice \"F[:vectors][:, k]\".) - - The following functions are available for \"Eigen\" objects: - \"inv\", \"det\". - - If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it - is possible to calculate only a subset of the eigenvalues by - specifying either a \"UnitRange\" \"irange\" covering indices of - the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower - and upper boundaries of the eigenvalues. - - For general nonsymmetric matrices it is possible to specify how the - matrix is balanced before the eigenvector calculation. The option - \"permute=true\" permutes the matrix to become closer to upper - triangular, and \"scale=true\" scales the matrix by its diagonal - elements to make rows and columns more equal in norm. The default - is \"true\" for both options. - - eigfact(A, B) -> GeneralizedEigen - - Computes the generalized eigenvalue decomposition of \"A\" and - \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" - which contains the generalized eigenvalues in \"F[:values]\" and - the generalized eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th generalized eigenvector can be - obtained from the slice \"F[:vectors][:, k]\".) - -"), - -("Base","eigfact","eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - - Computes the eigenvalue decomposition of \"A\", returning an - \"Eigen\" factorization object \"F\" which contains the eigenvalues - in \"F[:values]\" and the eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the - slice \"F[:vectors][:, k]\".) - - The following functions are available for \"Eigen\" objects: - \"inv\", \"det\". - - If \"A\" is \"Symmetric\", \"Hermitian\" or \"SymTridiagonal\", it - is possible to calculate only a subset of the eigenvalues by - specifying either a \"UnitRange\" \"irange\" covering indices of - the sorted eigenvalues or a pair \"vl\" and \"vu\" for the lower - and upper boundaries of the eigenvalues. - - For general nonsymmetric matrices it is possible to specify how the - matrix is balanced before the eigenvector calculation. The option - \"permute=true\" permutes the matrix to become closer to upper - triangular, and \"scale=true\" scales the matrix by its diagonal - elements to make rows and columns more equal in norm. The default - is \"true\" for both options. - - eigfact(A, B) -> GeneralizedEigen - - Computes the generalized eigenvalue decomposition of \"A\" and - \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" - which contains the generalized eigenvalues in \"F[:values]\" and - the generalized eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k\"th generalized eigenvector can be - obtained from the slice \"F[:vectors][:, k]\".) - -"), - -("Base","eigfact!","eigfact!(A[, B]) - - Same as \"eigfact()\", but saves space by overwriting the input - \"A\" (and \"B\"), instead of creating a copy. - -"), - -("Base","hessfact","hessfact(A) - - Compute the Hessenberg decomposition of \"A\" and return a - \"Hessenberg\" object. If \"F\" is the factorization object, the - unitary matrix can be accessed with \"F[:Q]\" and the Hessenberg - matrix with \"F[:H]\". When \"Q\" is extracted, the resulting type - is the \"HessenbergQ\" object, and may be converted to a regular - matrix with \"full()\". - -"), - -("Base","hessfact!","hessfact!(A) - - \"hessfact!\" is the same as \"hessfact()\", but saves space by - overwriting the input A, instead of creating a copy. - -"), - -("Base","schurfact","schurfact(A) -> Schur - - Computes the Schur factorization of the matrix \"A\". The (quasi) - triangular Schur factor can be obtained from the \"Schur\" object - \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the - unitary/orthogonal Schur vectors can be obtained with - \"F[:vectors]\" or \"F[:Z]\" such that - \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" - can be obtained with \"F[:values]\". - - schurfact(A, B) -> GeneralizedSchur - - Computes the Generalized Schur (or QZ) factorization of the - matrices \"A\" and \"B\". The (quasi) triangular Schur factors can - be obtained from the \"Schur\" object \"F\" with \"F[:S]\" and - \"F[:T]\", the left unitary/orthogonal Schur vectors can be - obtained with \"F[:left]\" or \"F[:Q]\" and the right - unitary/orthogonal Schur vectors can be obtained with \"F[:right]\" - or \"F[:Z]\" such that \"A=F[:left]*F[:S]*F[:right]'\" and - \"B=F[:left]*F[:T]*F[:right]'\". The generalized eigenvalues of - \"A\" and \"B\" can be obtained with \"F[:alpha]./F[:beta]\". - -"), - -("Base","schurfact!","schurfact!(A) - - Computes the Schur factorization of \"A\", overwriting \"A\" in the - process. See \"schurfact()\" - -"), - -("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] - - See \"schurfact()\" - - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - - See \"schurfact()\" - -"), - -("Base","ordschur","ordschur(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" - according to the logical array \"select\" returning a Schur object - \"F\". The selected eigenvalues appear in the leading diagonal of - \"F[:Schur]\" and the the corresponding leading columns of - \"F[:vectors]\" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via \"select\". - - ordschur(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\". - - ordschur(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix \"(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" - and returns a GeneralizedSchur object \"GS\". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of - \"A\" and \"B\" can still be obtained with - \"GS[:alpha]./GS[:beta]\". - - ordschur(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object. See \"ordschur()\". - -"), - -("Base","ordschur!","ordschur!(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", - overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" - - ordschur!(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\", - overwriting \"S\" in the process. See \"ordschur()\" - - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices \"(S, T, Q, Z)\" in the process. See - \"ordschur()\". - - ordschur!(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - \"ordschur()\". - -"), - -("Base","ordschur","ordschur(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" - according to the logical array \"select\" returning a Schur object - \"F\". The selected eigenvalues appear in the leading diagonal of - \"F[:Schur]\" and the the corresponding leading columns of - \"F[:vectors]\" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via \"select\". - - ordschur(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\". - - ordschur(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix \"(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" - and returns a GeneralizedSchur object \"GS\". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of - \"A\" and \"B\" can still be obtained with - \"GS[:alpha]./GS[:beta]\". - - ordschur(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object. See \"ordschur()\". - -"), - -("Base","ordschur!","ordschur!(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", - overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" - - ordschur!(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\", - overwriting \"S\" in the process. See \"ordschur()\" - - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices \"(S, T, Q, Z)\" in the process. See - \"ordschur()\". - - ordschur!(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - \"ordschur()\". - -"), - -("Base","schurfact","schurfact(A) -> Schur - - Computes the Schur factorization of the matrix \"A\". The (quasi) - triangular Schur factor can be obtained from the \"Schur\" object - \"F\" with either \"F[:Schur]\" or \"F[:T]\" and the - unitary/orthogonal Schur vectors can be obtained with - \"F[:vectors]\" or \"F[:Z]\" such that - \"A=F[:vectors]*F[:Schur]*F[:vectors]'\". The eigenvalues of \"A\" - can be obtained with \"F[:values]\". - - schurfact(A, B) -> GeneralizedSchur - - Computes the Generalized Schur (or QZ) factorization of the - matrices \"A\" and \"B\". The (quasi) triangular Schur factors can - be obtained from the \"Schur\" object \"F\" with \"F[:S]\" and - \"F[:T]\", the left unitary/orthogonal Schur vectors can be - obtained with \"F[:left]\" or \"F[:Q]\" and the right - unitary/orthogonal Schur vectors can be obtained with \"F[:right]\" - or \"F[:Z]\" such that \"A=F[:left]*F[:S]*F[:right]'\" and - \"B=F[:left]*F[:T]*F[:right]'\". The generalized eigenvalues of - \"A\" and \"B\" can be obtained with \"F[:alpha]./F[:beta]\". - -"), - -("Base","schur","schur(A) -> Schur[:T], Schur[:Z], Schur[:values] - - See \"schurfact()\" - - schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - - See \"schurfact()\" - -"), - -("Base","ordschur","ordschur(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" - according to the logical array \"select\" returning a Schur object - \"F\". The selected eigenvalues appear in the leading diagonal of - \"F[:Schur]\" and the the corresponding leading columns of - \"F[:vectors]\" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via \"select\". - - ordschur(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\". - - ordschur(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix \"(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" - and returns a GeneralizedSchur object \"GS\". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of - \"A\" and \"B\" can still be obtained with - \"GS[:alpha]./GS[:beta]\". - - ordschur(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object. See \"ordschur()\". - -"), - -("Base","ordschur!","ordschur!(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", - overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" - - ordschur!(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\", - overwriting \"S\" in the process. See \"ordschur()\" - - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices \"(S, T, Q, Z)\" in the process. See - \"ordschur()\". - - ordschur!(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - \"ordschur()\". - -"), - -("Base","ordschur","ordschur(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\" - according to the logical array \"select\" returning a Schur object - \"F\". The selected eigenvalues appear in the leading diagonal of - \"F[:Schur]\" and the the corresponding leading columns of - \"F[:vectors]\" form an orthonormal basis of the corresponding - right invariant subspace. A complex conjugate pair of eigenvalues - must be either both included or excluded via \"select\". - - ordschur(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\". - - ordschur(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix \"(A, B) = - (Q*S*Z^{H}, Q*T*Z^{H})\" according to the logical array \"select\" - and returns a GeneralizedSchur object \"GS\". The selected - eigenvalues appear in the leading diagonal of both``(GS[:S], - GS[:T])`` and the left and right unitary/orthogonal Schur vectors - are also reordered such that \"(A, B) = GS[:Q]*(GS[:S], - GS[:T])*GS[:Z]^{H}\" still holds and the generalized eigenvalues of - \"A\" and \"B\" can still be obtained with - \"GS[:alpha]./GS[:beta]\". - - ordschur(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object. See \"ordschur()\". - -"), - -("Base","ordschur!","ordschur!(Q, T, select) -> Schur - - Reorders the Schur factorization of a real matrix \"A=Q*T*Q'\", - overwriting \"Q\" and \"T\" in the process. See \"ordschur()\" - - ordschur!(S, select) -> Schur - - Reorders the Schur factorization \"S\" of type \"Schur\", - overwriting \"S\" in the process. See \"ordschur()\" - - ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a matrix by - overwriting the matrices \"(S, T, Q, Z)\" in the process. See - \"ordschur()\". - - ordschur!(GS, select) -> GeneralizedSchur - - Reorders the Generalized Schur factorization of a Generalized Schur - object by overwriting the object with the new factorization. See - \"ordschur()\". - -"), - -("Base","svdfact","svdfact(A[, thin=true]) -> SVD - - Compute the Singular Value Decomposition (SVD) of \"A\" and return - an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained - from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" - and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The algorithm - produces \"Vt\" and hence \"Vt\" is more efficient to extract than - \"V\". The default is to produce a thin decomposition. - - svdfact(A, B) -> GeneralizedSVD - - Compute the generalized SVD of \"A\" and \"B\", returning a - \"GeneralizedSVD\" Factorization object \"F\", such that \"A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'\" and \"B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'\". - -"), - -("Base","svdfact!","svdfact!(A[, thin=true]) -> SVD - - \"svdfact!\" is the same as \"svdfact()\", but saves space by - overwriting the input A, instead of creating a copy. If \"thin\" is - \"true\", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - -"), - -("Base","svd","svd(A[, thin=true]) -> U, S, V - - Wrapper around \"svdfact\" extracting all parts the factorization - to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. Computes the SVD of A, returning \"U\", vector \"S\", - and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - - svd(A, B) -> U, V, Q, D1, D2, R0 - - Wrapper around \"svdfact\" extracting all parts the factorization - to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. The function returns the generalized SVD of \"A\" and - \"B\", returning \"U\", \"V\", \"Q\", \"D1\", \"D2\", and \"R0\" - such that \"A = U*D1*R0*Q'\" and \"B = V*D2*R0*Q'\". - -"), - -("Base","svdvals","svdvals(A) - - Returns the singular values of \"A\". - - svdvals(A, B) - - Return only the singular values from the generalized singular value - decomposition of \"A\" and \"B\". - -"), - -("Base","svdvals!","svdvals!(A) - - Returns the singular values of \"A\", while saving space by - overwriting the input. - -"), - -("Base","svdfact","svdfact(A[, thin=true]) -> SVD - - Compute the Singular Value Decomposition (SVD) of \"A\" and return - an \"SVD\" object. \"U\", \"S\", \"V\" and \"Vt\" can be obtained - from the factorization \"F\" with \"F[:U]\", \"F[:S]\", \"F[:V]\" - and \"F[:Vt]\", such that \"A = U*diagm(S)*Vt\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The algorithm - produces \"Vt\" and hence \"Vt\" is more efficient to extract than - \"V\". The default is to produce a thin decomposition. - - svdfact(A, B) -> GeneralizedSVD - - Compute the generalized SVD of \"A\" and \"B\", returning a - \"GeneralizedSVD\" Factorization object \"F\", such that \"A = - F[:U]*F[:D1]*F[:R0]*F[:Q]'\" and \"B = - F[:V]*F[:D2]*F[:R0]*F[:Q]'\". - -"), - -("Base","svd","svd(A[, thin=true]) -> U, S, V - - Wrapper around \"svdfact\" extracting all parts the factorization - to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. Computes the SVD of A, returning \"U\", vector \"S\", - and \"V\" such that \"A == U*diagm(S)*V'\". If \"thin\" is - \"true\", an economy mode decomposition is returned. The default is - to produce a thin decomposition. - - svd(A, B) -> U, V, Q, D1, D2, R0 - - Wrapper around \"svdfact\" extracting all parts the factorization - to a tuple. Direct use of \"svdfact\" is therefore generally more - efficient. The function returns the generalized SVD of \"A\" and - \"B\", returning \"U\", \"V\", \"Q\", \"D1\", \"D2\", and \"R0\" - such that \"A = U*D1*R0*Q'\" and \"B = V*D2*R0*Q'\". - -"), - -("Base","svdvals","svdvals(A) - - Returns the singular values of \"A\". - - svdvals(A, B) - - Return only the singular values from the generalized singular value - decomposition of \"A\" and \"B\". - -"), - -("Base","triu","triu(M) - - Upper triangle of a matrix. - - triu(M, k) - - Returns the upper triangle of \"M\" starting from the \"k\"th - superdiagonal. - -"), - -("Base","triu","triu(M) - - Upper triangle of a matrix. - - triu(M, k) - - Returns the upper triangle of \"M\" starting from the \"k\"th - superdiagonal. - -"), - -("Base","triu!","triu!(M) - - Upper triangle of a matrix, overwriting \"M\" in the process. - - triu!(M, k) - - Returns the upper triangle of \"M\" starting from the \"k\"th - superdiagonal, overwriting \"M\" in the process. - -"), - -("Base","triu!","triu!(M) - - Upper triangle of a matrix, overwriting \"M\" in the process. - - triu!(M, k) - - Returns the upper triangle of \"M\" starting from the \"k\"th - superdiagonal, overwriting \"M\" in the process. - -"), - -("Base","tril","tril(M) - - Lower triangle of a matrix. - - tril(M, k) - - Returns the lower triangle of \"M\" starting from the \"k\"th - subdiagonal. - -"), - -("Base","tril","tril(M) - - Lower triangle of a matrix. - - tril(M, k) - - Returns the lower triangle of \"M\" starting from the \"k\"th - subdiagonal. - -"), - -("Base","tril!","tril!(M) - - Lower triangle of a matrix, overwriting \"M\" in the process. - - tril!(M, k) - - Returns the lower triangle of \"M\" starting from the \"k\"th - subdiagonal, overwriting \"M\" in the process. - -"), - -("Base","tril!","tril!(M) - - Lower triangle of a matrix, overwriting \"M\" in the process. - - tril!(M, k) - - Returns the lower triangle of \"M\" starting from the \"k\"th - subdiagonal, overwriting \"M\" in the process. - -"), - -("Base","diagind","diagind(M[, k]) - - A \"Range\" giving the indices of the \"k\"th diagonal of the - matrix \"M\". - -"), - -("Base","diag","diag(M[, k]) - - The \"k\"th diagonal of a matrix, as a vector. Use \"diagm\" to - construct a diagonal matrix. - -"), - -("Base","diagm","diagm(v[, k]) - - Construct a diagonal matrix and place \"v\" on the \"k\"th - diagonal. - -"), - -("Base","scale","scale(b, A) - - scale(A, b) - - scale(b, A) - - Scale an array \"A\" by a scalar \"b\", returning a new array. - - If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" - scales each column \"i\" of \"A\" by \"b[i]\" (similar to - \"A*diagm(b)\"), while \"scale(b,A)\" scales each row \"i\" of - \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), returning a new - array. - - Note: for large \"A\", \"scale\" can be much faster than \"A .* b\" - or \"b .* A\", due to the use of BLAS. - -"), - -("Base","scale","scale(b, A) - - scale(A, b) - - scale(b, A) - - Scale an array \"A\" by a scalar \"b\", returning a new array. - - If \"A\" is a matrix and \"b\" is a vector, then \"scale(A,b)\" - scales each column \"i\" of \"A\" by \"b[i]\" (similar to - \"A*diagm(b)\"), while \"scale(b,A)\" scales each row \"i\" of - \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), returning a new - array. - - Note: for large \"A\", \"scale\" can be much faster than \"A .* b\" - or \"b .* A\", due to the use of BLAS. - -"), - -("Base","scale!","scale!(b, A) - - scale!(A, b) - - scale!(b, A) - - Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but - overwriting \"A\" in-place. - - If \"A\" is a matrix and \"b\" is a vector, then \"scale!(A,b)\" - scales each column \"i\" of \"A\" by \"b[i]\" (similar to - \"A*diagm(b)\"), while \"scale!(b,A)\" scales each row \"i\" of - \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), again operating in- - place on \"A\". - -"), - -("Base","scale!","scale!(b, A) - - scale!(A, b) - - scale!(b, A) - - Scale an array \"A\" by a scalar \"b\", similar to \"scale()\" but - overwriting \"A\" in-place. - - If \"A\" is a matrix and \"b\" is a vector, then \"scale!(A,b)\" - scales each column \"i\" of \"A\" by \"b[i]\" (similar to - \"A*diagm(b)\"), while \"scale!(b,A)\" scales each row \"i\" of - \"A\" by \"b[i]\" (similar to \"diagm(b)*A\"), again operating in- - place on \"A\". - -"), - -("Base","Tridiagonal","Tridiagonal(dl, d, du) - - Construct a tridiagonal matrix from the lower diagonal, diagonal, - and upper diagonal, respectively. The result is of type - \"Tridiagonal\" and provides efficient specialized linear solvers, - but may be converted into a regular matrix with \"full()\". - -"), - -("Base","Bidiagonal","Bidiagonal(dv, ev, isupper) - - Constructs an upper (\"isupper=true\") or lower (\"isupper=false\") - bidiagonal matrix using the given diagonal (\"dv\") and off- - diagonal (\"ev\") vectors. The result is of type \"Bidiagonal\" - and provides efficient specialized linear solvers, but may be - converted into a regular matrix with \"full()\". - -"), - -("Base","SymTridiagonal","SymTridiagonal(d, du) - - Construct a real symmetric tridiagonal matrix from the diagonal and - upper diagonal, respectively. The result is of type - \"SymTridiagonal\" and provides efficient specialized eigensolvers, - but may be converted into a regular matrix with \"full()\". - -"), - -("Base","rank","rank(M) - - Compute the rank of a matrix. - -"), - -("Base","norm","norm(A[, p]) - - Compute the \"p\"-norm of a vector or the operator norm of a matrix - \"A\", defaulting to the \"p=2\"-norm. - - For vectors, \"p\" can assume any numeric value (even though not - all values produce a mathematically valid vector norm). In - particular, \"norm(A, Inf)\" returns the largest value in - \"abs(A)\", whereas \"norm(A, -Inf)\" returns the smallest. - - For matrices, valid values of \"p\" are \"1\", \"2\", or \"Inf\". - (Note that for sparse matrices, \"p=2\" is currently not - implemented.) Use \"vecnorm()\" to compute the Frobenius norm. - -"), - -("Base","vecnorm","vecnorm(A[, p]) - - For any iterable container \"A\" (including arrays of any - dimension) of numbers (or any element type for which \"norm\" is - defined), compute the \"p\"-norm (defaulting to \"p=2\") as if - \"A\" were a vector of the corresponding length. - - For example, if \"A\" is a matrix and \"p=2\", then this is - equivalent to the Frobenius norm. - -"), - -("Base","cond","cond(M[, p]) - - Condition number of the matrix \"M\", computed using the operator - \"p\"-norm. Valid values for \"p\" are \"1\", \"2\" (default), or - \"Inf\". - -"), - -("Base","condskeel","condskeel(M[, x, p]) - - condskeel(M[, x, p]) - - \\kappa_S(M, p) & = \\left\\Vert \\left\\vert M \\right\\vert - \\left\\vert M^{-1} \\right\\vert \\right\\Vert_p \\\\ - \\kappa_S(M, x, p) & = \\left\\Vert \\left\\vert M \\right\\vert - \\left\\vert M^{-1} \\right\\vert \\left\\vert x \\right\\vert - \\right\\Vert_p - - Skeel condition number kappa_S of the matrix \"M\", optionally with - respect to the vector \"x\", as computed using the operator - \"p\"-norm. \"p\" is \"Inf\" by default, if not provided. Valid - values for \"p\" are \"1\", \"2\", or \"Inf\". - - This quantity is also known in the literature as the Bauer - condition number, relative condition number, or componentwise - relative condition number. - -"), - -("Base","trace","trace(M) - - Matrix trace - -"), - -("Base","det","det(M) - - Matrix determinant - -"), - -("Base","logabsdet","logabsdet(M) - - Log of absolute value of determinant of real matrix. Equivalent to - \"(log(abs(det(M))), sign(det(M)))\", but may provide increased - accuracy and/or speed. - -"), - -("Base","logabsdet","logabsdet(M) - - Log of absolute value of determinant of real matrix. Equivalent to - \"(log(abs(det(M))), sign(det(M)))\", but may provide increased - accuracy and/or speed. - -"), - -("Base","inv","inv(M) - - Matrix inverse - -"), - -("Base","pinv","pinv(M[, tol]) - - Computes the Moore-Penrose pseudoinverse. - - For matrices \"M\" with floating point elements, it is convenient - to compute the pseudoinverse by inverting only singular values - above a given threshold, \"tol\". - - The optimal choice of \"tol\" varies both with the value of \"M\" - and the intended application of the pseudoinverse. The default - value of \"tol\" is - \"eps(real(float(one(eltype(M)))))*maximum(size(A))\", which is - essentially machine epsilon for the real part of a matrix element - multiplied by the larger matrix dimension. For inverting dense ill- - conditioned matrices in a least-squares sense, \"tol = - sqrt(eps(real(float(one(eltype(M))))))\" is recommended. - - For more information, see [8859], [B96], [S84], [KY88]. - - [8859] Issue 8859, \"Fix least squares\", - https://github.com/JuliaLang/julia/pull/8859 - - [B96] Åke Björck, \"Numerical Methods for Least Squares - Problems\", SIAM Press, Philadelphia, 1996, \"Other Titles in - Applied Mathematics\", Vol. 51. doi:10.1137/1.9781611971484 - - [S84] G. W. Stewart, \"Rank Degeneracy\", SIAM Journal on - Scientific and Statistical Computing, 5(2), 1984, 403-413. - doi:10.1137/0905030 - - [KY88] Konstantinos Konstantinides and Kung Yao, - \"Statistical analysis of effective singular values in - matrix rank determination\", IEEE Transactions on Acoustics, - Speech and Signal Processing, 36(5), 1988, 757-763. - doi:10.1109/29.1585 - -"), - -("Base","nullspace","nullspace(M) - - Basis for nullspace of \"M\". - -"), - -("Base","repmat","repmat(A, n, m) - - Construct a matrix by repeating the given matrix \"n\" times in - dimension 1 and \"m\" times in dimension 2. - -"), - -("Base","repeat","repeat(A, inner = Int[], outer = Int[]) - - Construct an array by repeating the entries of \"A\". The i-th - element of \"inner\" specifies the number of times that the - individual entries of the i-th dimension of \"A\" should be - repeated. The i-th element of \"outer\" specifies the number of - times that a slice along the i-th dimension of \"A\" should be - repeated. - -"), - -("Base","kron","kron(A, B) - - Kronecker tensor product of two vectors or two matrices. - -"), - -("Base","blkdiag","blkdiag(A...) - - Concatenate matrices block-diagonally. Currently only implemented - for sparse matrices. - -"), - -("Base","linreg","linreg(x, y) -> [a; b] - - Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is - the closest line to the given points \"(x,y)\". In other words, - this function determines parameters \"[a, b]\" that minimize the - squared error between \"y\" and \"a+b*x\". - - **Example**: - - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, \"o\") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression - - linreg(x, y, w) - - Weighted least-squares linear regression. - -"), - -("Base","linreg","linreg(x, y) -> [a; b] - - Linear Regression. Returns \"a\" and \"b\" such that \"a+b*x\" is - the closest line to the given points \"(x,y)\". In other words, - this function determines parameters \"[a, b]\" that minimize the - squared error between \"y\" and \"a+b*x\". - - **Example**: - - using PyPlot; - x = float([1:12]) - y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] - a, b = linreg(x,y) # Linear regression - plot(x, y, \"o\") # Plot (x,y) points - plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression - - linreg(x, y, w) - - Weighted least-squares linear regression. - -"), - -("Base","expm","expm(A) - - Matrix exponential. - -"), - -("Base","lyap","lyap(A, C) - - Computes the solution \"X\" to the continuous Lyapunov equation - \"AX + XA' + C = 0\", where no eigenvalue of \"A\" has a zero real - part and no two eigenvalues are negative complex conjugates of each - other. - -"), - -("Base","sylvester","sylvester(A, B, C) - - Computes the solution \"X\" to the Sylvester equation \"AX + XB + C - = 0\", where \"A\", \"B\" and \"C\" have compatible dimensions and - \"A\" and \"-B\" have no eigenvalues with equal real part. - -"), - -("Base","issym","issym(A) -> Bool - - Test whether a matrix is symmetric. - -"), - -("Base","isposdef","isposdef(A) -> Bool - - Test whether a matrix is positive definite. - -"), - -("Base","isposdef!","isposdef!(A) -> Bool - - Test whether a matrix is positive definite, overwriting \"A\" in - the processes. - -"), - -("Base","istril","istril(A) -> Bool - - Test whether a matrix is lower triangular. - -"), - -("Base","istriu","istriu(A) -> Bool - - Test whether a matrix is upper triangular. - -"), - -("Base","isdiag","isdiag(A) -> Bool - - Test whether a matrix is diagonal. - -"), - -("Base","ishermitian","ishermitian(A) -> Bool - - Test whether a matrix is Hermitian. - -"), - -("Base","transpose","transpose(A) - - The transposition operator (\".'\"). - -"), - -("Base","transpose!","transpose!(dest, src) - - Transpose array \"src\" and store the result in the preallocated - array \"dest\", which should have a size corresponding to - \"(size(src,2),size(src,1))\". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. - -"), - -("Base","ctranspose","ctranspose(A) - - The conjugate transposition operator (\"'\"). - -"), - -("Base","ctranspose!","ctranspose!(dest, src) - - Conjugate transpose array \"src\" and store the result in the - preallocated array \"dest\", which should have a size corresponding - to \"(size(src,2),size(src,1))\". No in-place transposition is - supported and unexpected results will happen if *src* and *dest* - have overlapping memory regions. - -"), - -("Base","eigs","eigs(A[, B], ; nev=6, which=\"LM\", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0, ))) -> (d[, v], nconv, niter, nmult, resid) - - Computes eigenvalues \"d\" of \"A\" using Lanczos or Arnoldi - iterations for real symmetric or general nonsymmetric matrices - respectively. If \"B\" is provided, the generalized eigenproblem is - solved. - - The following keyword arguments are supported: * \"nev\": - Number of eigenvalues - - * \"ncv\": Number of Krylov vectors used in the computation; - should satisfy - - \"nev+1 <= ncv <= n\" for real symmetric problems and - \"nev+2 <= ncv <= n\" for other problems, where \"n\" is - the size of the input matrix \"A\". The default is \"ncv = - max(20,2*nev+1)\". Note that these restrictions limit the - input matrix \"A\" to be of dimension at least 2. - - * \"which\": type of eigenvalues to compute. See the note - below. - - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \"which\" | type of eigenvalues | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LM\" | eigenvalues of largest magnitude (default) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SM\" | eigenvalues of smallest magnitude | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LR\" | eigenvalues of largest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SR\" | eigenvalues of smallest real part | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":LI\" | eigenvalues of largest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":SI\" | eigenvalues of smallest imaginary part (nonsymmetric or complex \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - | \":BE\" | compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric \"A\" only) | - +-----------+-----------------------------------------------------------------------------------------------------------------------------+ - - * \"tol\": tolerance (tol \\le 0.0 defaults to - \"DLAMCH('EPS')\") - - * \"maxiter\": Maximum number of iterations (default = 300) - - * \"sigma\": Specifies the level shift used in inverse - iteration. If \"nothing\" (default), defaults to ordinary - (forward) iterations. Otherwise, find eigenvalues close to - \"sigma\" using shift and invert iterations. - - * \"ritzvec\": Returns the Ritz vectors \"v\" (eigenvectors) - if \"true\" - - * \"v0\": starting vector from which to start the iterations - - \"eigs\" returns the \"nev\" requested eigenvalues in \"d\", the - corresponding Ritz vectors \"v\" (only if \"ritzvec=true\"), the - number of converged eigenvalues \"nconv\", the number of iterations - \"niter\" and the number of matrix vector multiplications - \"nmult\", as well as the final residual vector \"resid\". - - Note: The \"sigma\" and \"which\" keywords interact: the - description of eigenvalues searched for by \"which\" do _not_ - necessarily refer to the eigenvalues of \"A\", but rather the - linear operator constructed by the specification of the iteration - mode implied by \"sigma\". - - +––––––––-+––––––––––––––––––+––––––––––––––––––+ | \"sigma\" - | iteration mode | \"which\" refers to - eigenvalues of | - +––––––––-+––––––––––––––––––+––––––––––––––––––+ | \"nothing\" - | ordinary (forward) | A - | +––––––––-+––––––––––––––––––+––––––––––––––––––+ | real or - complex | inverse with level shift \"sigma\" | (A - sigma I )^{-1} - | +––––––––-+––––––––––––––––––+––––––––––––––––––+ - -"), - -("Base","svds","svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) - - \"svds\" computes largest singular values \"s\" of \"A\" using - Lanczos or Arnoldi iterations. Uses \"eigs()\" underneath. - - Inputs are: * \"A\": Linear operator. It can either subtype of - \"AbstractArray\" (e.g., sparse matrix) or duck typed. For - duck typing \"A\" has to support \"size(A)\", \"eltype(A)\", - \"A * vector\" and \"A' * vector\". - - * \"nsv\": Number of singular values. - - * \"ritzvec\": Whether to return the left and right singular - vectors \"left_sv\" and \"right_sv\", default is \"true\". If - \"false\" the singular vectors are omitted from the output. - - * \"tol\": tolerance, see \"eigs()\". - - * \"maxiter\": Maximum number of iterations, see \"eigs()\". - - **Example**: - - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) - -"), - -("Base","peakflops","peakflops(n; parallel=false) - - \"peakflops\" computes the peak flop rate of the computer by using - double precision \"Base.LinAlg.BLAS.gemm!()\". By default, if no - arguments are specified, it multiplies a matrix of size \"n x n\", - where \"n = 2000\". If the underlying BLAS is using multiple - threads, higher flop rates are realized. The number of BLAS threads - can be set with \"blas_set_num_threads(n)\". - - If the keyword argument \"parallel\" is set to \"true\", - \"peakflops\" is run in parallel on all the worker processors. The - flop rate of the entire parallel computer is returned. When running - in parallel, only 1 BLAS thread is used. The argument \"n\" still - refers to the size of the problem that is solved on each processor. - -"), - -("Base.LinAlg.BLAS","dot","dot(n, X, incx, Y, incy) - - Dot product of two vectors consisting of \"n\" elements of array - \"X\" with stride \"incx\" and \"n\" elements of array \"Y\" with - stride \"incy\". - -"), - -("Base.LinAlg.BLAS","dotu","dotu(n, X, incx, Y, incy) - - Dot function for two complex vectors. - -"), - -("Base.LinAlg.BLAS","dotc","dotc(n, X, incx, U, incy) - - Dot function for two complex vectors conjugating the first vector. - -"), - -("Base.LinAlg.BLAS","blascopy!","blascopy!(n, X, incx, Y, incy) - - Copy \"n\" elements of array \"X\" with stride \"incx\" to array - \"Y\" with stride \"incy\". Returns \"Y\". - -"), - -("Base.LinAlg.BLAS","nrm2","nrm2(n, X, incx) - - 2-norm of a vector consisting of \"n\" elements of array \"X\" with - stride \"incx\". - -"), - -("Base.LinAlg.BLAS","asum","asum(n, X, incx) - - sum of the absolute values of the first \"n\" elements of array - \"X\" with stride \"incx\". - -"), - -("Base.LinAlg.BLAS","axpy!","axpy!(a, X, Y) - - Overwrite \"Y\" with \"a*X + Y\". Returns \"Y\". - -"), - -("Base.LinAlg.BLAS","scal!","scal!(n, a, X, incx) - - Overwrite \"X\" with \"a*X\". Returns \"X\". - -"), - -("Base.LinAlg.BLAS","scal","scal(n, a, X, incx) - - Returns \"a*X\". - -"), - -("Base.LinAlg.BLAS","ger!","ger!(alpha, x, y, A) - - Rank-1 update of the matrix \"A\" with vectors \"x\" and \"y\" as - \"alpha*x*y' + A\". - -"), - -("Base.LinAlg.BLAS","syr!","syr!(uplo, alpha, x, A) - - Rank-1 update of the symmetric matrix \"A\" with vector \"x\" as - \"alpha*x*x.' + A\". When \"uplo\" is 'U' the upper triangle of - \"A\" is updated ('L' for lower triangle). Returns \"A\". - -"), - -("Base.LinAlg.BLAS","syrk!","syrk!(uplo, trans, alpha, A, beta, C) - - Rank-k update of the symmetric matrix \"C\" as \"alpha*A*A.' + - beta*C\" or \"alpha*A.'>>*<>*<>*<>*<>*<>*<>*<<(x, y, z, ...)\". - - *(s, t) - - Concatenate strings. The \"*\" operator is an alias to this - function. - - julia> \"Hello \" * \"world\" - \"Hello world\" - -"), - -("Base","/","/(x, y) - - Right division operator: multiplication of \"x\" by the inverse of - \"y\" on the right. Gives floating-point results for integer - arguments. - -"), - -("Base","\\","\\(x, y) - - Left division operator: multiplication of \"y\" by the inverse of - \"x\" on the left. Gives floating-point results for integer - arguments. - -"), - -("Base","^","^(x, y) - - Exponentiation operator. - - ^(s, n) - - Repeat \"n\" times the string \"s\". The \"^\" operator is an alias - to this function. - - julia> \"Test \"^3 - \"Test Test Test \" - -"), - -("Base",".+",".+(x, y) - - Element-wise addition operator. - -"), - -("Base",".-",".-(x, y) - - Element-wise subtraction operator. - -"), - -("Base",".*",".*(x, y) - - Element-wise multiplication operator. - -"), - -("Base","./","./(x, y) - - Element-wise right division operator. - -"), - -("Base",".\\",".\\(x, y) - - Element-wise left division operator. - -"), - -("Base",".^",".^(x, y) - - Element-wise exponentiation operator. - -"), - -("Base","fma","fma(x, y, z) - - Computes \"x*y+z\" without rounding the intermediate result - \"x*y\". On some systems this is significantly more expensive than - \"x*y+z\". \"fma\" is used to improve accuracy in certain - algorithms. See \"muladd\". - -"), - -("Base","muladd","muladd(x, y, z) - - Combined multiply-add, computes \"x*y+z\" in an efficient manner. - This may on some systems be equivalent to \"x*y+z\", or to - \"fma(x,y,z)\". \"muladd\" is used to improve performance. See - \"fma\". - -"), - -("Base","div","div(x, y) - - ÷(x, y) - - The quotient from Euclidean division. Computes \"x/y\", truncated - to an integer. - -"), - -("Base","fld","fld(x, y) - - Largest integer less than or equal to \"x/y\". - -"), - -("Base","cld","cld(x, y) - - Smallest integer larger than or equal to \"x/y\". - -"), - -("Base","mod","mod(x, y) - - Modulus after division, returning in the range [0,``y``), if \"y\" - is positive, or (\"y\",0] if \"y\" is negative. - -"), - -("Base","mod2pi","mod2pi(x) - - Modulus after division by 2pi, returning in the range [0,2pi). - - This function computes a floating point representation of the - modulus after division by numerically exact 2pi, and is therefore - not exactly the same as mod(x,2pi), which would compute the modulus - of x relative to division by the floating-point number 2pi. - -"), - -("Base","rem","rem(x, y) - - %(x, y) - - Remainder from Euclidean division, returning a value of the same - sign as``x``, and smaller in magnitude than \"y\". This value is - always exact. - -"), - -("Base","divrem","divrem(x, y) - - The quotient and remainder from Euclidean division. Equivalent to - \"(x÷y, x%y)\". - -"), - -("Base","fldmod","fldmod(x, y) - - The floored quotient and modulus after division. Equivalent to - \"(fld(x,y), mod(x,y))\". - -"), - -("Base","mod1","mod1(x, m) - - Modulus after division, returning in the range (0,m] - -"), - -("Base","rem1","rem1(x, m) - - Remainder after division, returning in the range (0,m] - -"), - -("Base","//","//(num, den) - - Divide two integers or rational numbers, giving a \"Rational\" - result. - -"), - -("Base","rationalize","rationalize([Type=Int], x; tol=eps(x)) - - Approximate floating point number \"x\" as a Rational number with - components of the given integer type. The result will differ from - \"x\" by no more than \"tol\". - -"), - -("Base","num","num(x) - - Numerator of the rational representation of \"x\" - -"), - -("Base","den","den(x) - - Denominator of the rational representation of \"x\" - -"), - -("Base","<<","<<(x, n) - - Left bit shift operator. - -"), - -("Base",">>",">>(x, n) - - Right bit shift operator, preserving the sign of \"x\". - -"), - -("Base",">>>",">>>(x, n) - - Unsigned right bit shift operator. - -"), - -("Base",":",":(start[, step], stop) - - Range operator. \"a:b\" constructs a range from \"a\" to \"b\" with - a step size of 1, and \"a:s:b\" is similar but uses a step size of - \"s\". These syntaxes call the function \"colon\". The colon is - also used in indexing to select whole dimensions. - -"), - -("Base","colon","colon(start[, step], stop) - - Called by \":\" syntax for constructing ranges. - -"), - -("Base","range","range(start[, step], length) - - Construct a range by length, given a starting value and optional - step (defaults to 1). - -"), - -("Base","==","==(x, y) - - Generic equality operator, giving a single \"Bool\" result. Falls - back to \"===\". Should be implemented for all types with a notion - of equality, based on the abstract value that an instance - represents. For example, all numeric types are compared by numeric - value, ignoring type. Strings are compared as sequences of - characters, ignoring encoding. - - Follows IEEE semantics for floating-point numbers. - - Collections should generally implement \"==\" by calling \"==\" - recursively on all contents. - - New numeric types should implement this function for two arguments - of the new type, and handle comparison to other types via promotion - rules where possible. - -"), - -("Base","!=","!=(x, y) - - ≠(x, y) - - Not-equals comparison operator. Always gives the opposite answer as - \"==\". New types should generally not implement this, and rely on - the fallback definition \"!=(x,y) = !(x==y)\" instead. - -"), - -("Base","is","is(x, y) -> Bool - - ===(x, y) -> Bool ≡(x, y) -> Bool - - Determine whether \"x\" and \"y\" are identical, in the sense that - no program could distinguish them. Compares mutable objects by - address in memory, and compares immutable objects (such as numbers) - by contents at the bit level. This function is sometimes called - \"egal\". - -"), - -("Base","!==","!==(x, y) - - ≢(x, y) - - Equivalent to \"!is(x, y)\" - -"), - -("Base","<","<(x, y) - - Less-than comparison operator. New numeric types should implement - this function for two arguments of the new type. Because of the - behavior of floating-point NaN values, \"<\" implements a partial - order. Types with a canonical partial order should implement \"<\", - and types with a canonical total order should implement \"isless\". - -"), - -("Base","<=","<=(x, y) - - ≤(x, y) - - Less-than-or-equals comparison operator. - -"), - -("Base",">",">(x, y) - - Greater-than comparison operator. Generally, new types should - implement \"<\" instead of this function, and rely on the fallback - definition \">(x,y) = y=",">=(x, y) - - ≥(x, y) - - Greater-than-or-equals comparison operator. - -"), - -("Base",".==",".==(x, y) - - Element-wise equality comparison operator. - -"), - -("Base",".!=",".!=(x, y) - - .≠(x, y) - - Element-wise not-equals comparison operator. - -"), - -("Base",".<",".<(x, y) - - Element-wise less-than comparison operator. - -"), - -("Base",".<=",".<=(x, y) - - .≤(x, y) - - Element-wise less-than-or-equals comparison operator. - -"), - -("Base",".>",".>(x, y) - - Element-wise greater-than comparison operator. - -"), - -("Base",".>=",".>=(x, y) - - .≥(x, y) - - Element-wise greater-than-or-equals comparison operator. - -"), - -("Base","cmp","cmp(x, y) - - Return -1, 0, or 1 depending on whether \"x\" is less than, equal - to, or greater than \"y\", respectively. Uses the total order - implemented by \"isless\". For floating-point numbers, uses \"<\" - but throws an error for unordered arguments. - -"), - -("Base","~","~(x) - - Bitwise not - -"), - -("Base","&","&(x, y) - - Bitwise and - -"), - -("Base","|","|(x, y) - - Bitwise or - -"), - -("Base","\$","\$(x, y) - - Bitwise exclusive or - -"), - -("Base","!","!(x) - - Boolean not - -"), - -("","x && y","x && y - - Short-circuiting boolean and - -"), - -("","x || y","x || y - - Short-circuiting boolean or - -"), - -("Base","A_ldiv_Bc","A_ldiv_Bc(a, b) - - Matrix operator A B^H - -"), - -("Base","A_ldiv_Bt","A_ldiv_Bt(a, b) - - Matrix operator A B^T - -"), - -("Base","A_mul_B!","A_mul_B!(Y, A, B) -> Y - - Calculates the matrix-matrix or matrix-vector product *A B* and - stores the result in *Y*, overwriting the existing value of *Y*. - - julia> A=[1.0 2.0; 3.0 4.0]; B=[1.0 1.0; 1.0 1.0]; A_mul_B!(B, A, B); - - julia> B - 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 - -"), - -("Base","A_mul_Bc","A_mul_Bc(...) - - Matrix operator A B^H - -"), - -("Base","A_mul_Bt","A_mul_Bt(...) - - Matrix operator A B^T - -"), - -("Base","A_rdiv_Bc","A_rdiv_Bc(...) - - Matrix operator A / B^H - -"), - -("Base","A_rdiv_Bt","A_rdiv_Bt(a, b) - - Matrix operator A / B^T - -"), - -("Base","Ac_ldiv_B","Ac_ldiv_B(...) - - Matrix operator A^H B - -"), - -("Base","Ac_ldiv_Bc","Ac_ldiv_Bc(...) - - Matrix operator A^H B^H - -"), - -("Base","Ac_mul_B","Ac_mul_B(...) - - Matrix operator A^H B - -"), - -("Base","Ac_mul_Bc","Ac_mul_Bc(...) - - Matrix operator A^H B^H - -"), - -("Base","Ac_rdiv_B","Ac_rdiv_B(a, b) - - Matrix operator A^H / B - -"), - -("Base","Ac_rdiv_Bc","Ac_rdiv_Bc(a, b) - - Matrix operator A^H / B^H - -"), - -("Base","At_ldiv_B","At_ldiv_B(...) - - Matrix operator A^T B - -"), - -("Base","At_ldiv_Bt","At_ldiv_Bt(...) - - Matrix operator A^T B^T - -"), - -("Base","At_mul_B","At_mul_B(...) - - Matrix operator A^T B - -"), - -("Base","At_mul_Bt","At_mul_Bt(...) - - Matrix operator A^T B^T - -"), - -("Base","At_rdiv_B","At_rdiv_B(a, b) - - Matrix operator A^T / B - -"), - -("Base","At_rdiv_Bt","At_rdiv_Bt(a, b) - - Matrix operator A^T / B^T - -"), - -("Base","isapprox","isapprox(x::Number, y::Number; rtol::Real=cbrt(maxeps), atol::Real=sqrt(maxeps)) - - Inexact equality comparison - behaves slightly different depending - on types of input args: - - * For \"FloatingPoint\" numbers, \"isapprox\" returns \"true\" - if \"abs(x-y) <= atol + rtol*max(abs(x), abs(y))\". - - * For \"Integer\" and \"Rational\" numbers, \"isapprox\" - returns \"true\" if \"abs(x-y) <= atol\". The *rtol* argument - is ignored. If one of \"x\" and \"y\" is \"FloatingPoint\", - the other is promoted, and the method above is called - instead. - - * For \"Complex\" numbers, the distance in the complex plane - is compared, using the same criterion as above. - - For default tolerance arguments, \"maxeps = max(eps(abs(x)), - eps(abs(y)))\". - -"), - -("Base","sin","sin(x) - - Compute sine of \"x\", where \"x\" is in radians - -"), - -("Base","cos","cos(x) - - Compute cosine of \"x\", where \"x\" is in radians - -"), - -("Base","tan","tan(x) - - Compute tangent of \"x\", where \"x\" is in radians - -"), - -("Base","sind","sind(x) - - Compute sine of \"x\", where \"x\" is in degrees - -"), - -("Base","cosd","cosd(x) - - Compute cosine of \"x\", where \"x\" is in degrees - -"), - -("Base","tand","tand(x) - - Compute tangent of \"x\", where \"x\" is in degrees - -"), - -("Base","sinpi","sinpi(x) - - Compute sin(pi x) more accurately than \"sin(pi*x)\", especially - for large \"x\". - -"), - -("Base","cospi","cospi(x) - - Compute cos(pi x) more accurately than \"cos(pi*x)\", especially - for large \"x\". - -"), - -("Base","sinh","sinh(x) - - Compute hyperbolic sine of \"x\" - -"), - -("Base","cosh","cosh(x) - - Compute hyperbolic cosine of \"x\" - -"), - -("Base","tanh","tanh(x) - - Compute hyperbolic tangent of \"x\" - -"), - -("Base","asin","asin(x) - - Compute the inverse sine of \"x\", where the output is in radians - -"), - -("Base","acos","acos(x) - - Compute the inverse cosine of \"x\", where the output is in radians - -"), - -("Base","atan","atan(x) - - Compute the inverse tangent of \"x\", where the output is in - radians - -"), - -("Base","atan2","atan2(y, x) - - Compute the inverse tangent of \"y/x\", using the signs of both - \"x\" and \"y\" to determine the quadrant of the return value. - -"), - -("Base","asind","asind(x) - - Compute the inverse sine of \"x\", where the output is in degrees - -"), - -("Base","acosd","acosd(x) - - Compute the inverse cosine of \"x\", where the output is in degrees - -"), - -("Base","atand","atand(x) - - Compute the inverse tangent of \"x\", where the output is in - degrees - -"), - -("Base","sec","sec(x) - - Compute the secant of \"x\", where \"x\" is in radians - -"), - -("Base","csc","csc(x) - - Compute the cosecant of \"x\", where \"x\" is in radians - -"), - -("Base","cot","cot(x) - - Compute the cotangent of \"x\", where \"x\" is in radians - -"), - -("Base","secd","secd(x) - - Compute the secant of \"x\", where \"x\" is in degrees - -"), - -("Base","cscd","cscd(x) - - Compute the cosecant of \"x\", where \"x\" is in degrees - -"), - -("Base","cotd","cotd(x) - - Compute the cotangent of \"x\", where \"x\" is in degrees - -"), - -("Base","asec","asec(x) - - Compute the inverse secant of \"x\", where the output is in radians - -"), - -("Base","acsc","acsc(x) - - Compute the inverse cosecant of \"x\", where the output is in - radians - -"), - -("Base","acot","acot(x) - - Compute the inverse cotangent of \"x\", where the output is in - radians - -"), - -("Base","asecd","asecd(x) - - Compute the inverse secant of \"x\", where the output is in degrees - -"), - -("Base","acscd","acscd(x) - - Compute the inverse cosecant of \"x\", where the output is in - degrees - -"), - -("Base","acotd","acotd(x) - - Compute the inverse cotangent of \"x\", where the output is in - degrees - -"), - -("Base","sech","sech(x) - - Compute the hyperbolic secant of \"x\" - -"), - -("Base","csch","csch(x) - - Compute the hyperbolic cosecant of \"x\" - -"), - -("Base","coth","coth(x) - - Compute the hyperbolic cotangent of \"x\" - -"), - -("Base","asinh","asinh(x) - - Compute the inverse hyperbolic sine of \"x\" - -"), - -("Base","acosh","acosh(x) - - Compute the inverse hyperbolic cosine of \"x\" - -"), - -("Base","atanh","atanh(x) - - Compute the inverse hyperbolic tangent of \"x\" - -"), - -("Base","asech","asech(x) - - Compute the inverse hyperbolic secant of \"x\" - -"), - -("Base","acsch","acsch(x) - - Compute the inverse hyperbolic cosecant of \"x\" - -"), - -("Base","acoth","acoth(x) - - Compute the inverse hyperbolic cotangent of \"x\" - -"), - -("Base","sinc","sinc(x) - - Compute sin(pi x) / (pi x) if x neq 0, and 1 if x = 0. - -"), - -("Base","cosc","cosc(x) - - Compute cos(pi x) / x - sin(pi x) / (pi x^2) if x neq 0, and 0 if x - = 0. This is the derivative of \"sinc(x)\". - -"), - -("Base","deg2rad","deg2rad(x) - - Convert \"x\" from degrees to radians - -"), - -("Base","rad2deg","rad2deg(x) - - Convert \"x\" from radians to degrees - -"), - -("Base","hypot","hypot(x, y) - - Compute the sqrt{x^2+y^2} avoiding overflow and underflow - -"), - -("Base","log","log(x) - - Compute the natural logarithm of \"x\". Throws \"DomainError\" for - negative \"Real\" arguments. Use complex negative arguments to - obtain complex results. - - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. - - log(b, x) - - Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log","log(x) - - Compute the natural logarithm of \"x\". Throws \"DomainError\" for - negative \"Real\" arguments. Use complex negative arguments to - obtain complex results. - - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. - - log(b, x) - - Compute the base \"b\" logarithm of \"x\". Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log2","log2(x) - - Compute the logarithm of \"x\" to base 2. Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log10","log10(x) - - Compute the logarithm of \"x\" to base 10. Throws \"DomainError\" - for negative \"Real\" arguments. - -"), - -("Base","log1p","log1p(x) - - Accurate natural logarithm of \"1+x\". Throws \"DomainError\" for - \"Real\" arguments less than -1. - - There is an experimental variant in the \"Base.Math.JuliaLibm\" - module, which is typically faster and more accurate. - -"), - -("Base","frexp","frexp(val) - - Return \"(x,exp)\" such that \"x\" has a magnitude in the interval - \"[1/2, 1)\" or 0, and val = x times 2^{exp}. - -"), - -("Base","exp","exp(x) - - Compute e^x - -"), - -("Base","exp2","exp2(x) - - Compute 2^x - -"), - -("Base","exp10","exp10(x) - - Compute 10^x - -"), - -("Base","ldexp","ldexp(x, n) - - Compute x times 2^n - -"), - -("Base","modf","modf(x) - - Return a tuple (fpart,ipart) of the fractional and integral parts - of a number. Both parts have the same sign as the argument. - -"), - -("Base","expm1","expm1(x) - - Accurately compute e^x-1 - -"), - -("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) - - \"round(x)\" rounds \"x\" to an integer value according to the - default rounding mode (see \"get_rounding()\"), returning a value - of the same type as \"x\". By default (\"RoundNearest\"), this will - round to the nearest integer, with ties (fractional values of 0.5) - being rounded to the even integer. - - julia> round(1.7) - 2.0 - - julia> round(1.5) - 2.0 - - julia> round(2.5) - 2.0 - - The optional \"RoundingMode\" argument will change how the number - gets rounded. - - \"round(T, x, [r::RoundingMode])\" converts the result to type - \"T\", throwing an \"InexactError\" if the value is not - representable. - - \"round(x, digits)\" rounds to the specified number of digits after - the decimal place (or before if negative). \"round(x, digits, - base)\" rounds using a base other than 10. - - julia> round(pi, 2) - 3.14 - - julia> round(pi, 3, 2) - 3.125 - - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the \"Float64\" value represented by \"1.15\" is - actually *less* than 1.15, yet will be rounded to 1.2. - - julia> x = 1.15 - 1.15 - - julia> @sprintf \"%.20f\" x - \"1.14999999999999991118\" - - julia> x < 115//100 - true - - julia> round(x, 1) - 1.2 - - round(z, RoundingModeReal, RoundingModeImaginary) - - Returns the nearest integral value of the same type as the complex- - valued \"z\" to \"z\", breaking ties using the specified - \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding - the real components while the second is used for rounding the - imaginary components. - - julia> round(pi, 2) 3.14 - - julia> round(pi, 3, 2) 3.125 - - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the \"Float64\" value represented by \"1.15\" is - actually *less* than 1.15, yet will be rounded to 1.2. - - julia> x = 1.15 - 1.15 - - julia> @sprintf \"%.20f\" x - \"1.14999999999999991118\" - - julia> x < 115//100 - true - - julia> round(x, 1) - 1.2 - -"), - -("Base","RoundingMode","RoundingMode - - A type which controls rounding behavior. Currently supported - rounding modes are: - - * \"RoundNearest\" (default) - - * \"RoundNearestTiesAway\" - - * \"RoundNearestTiesUp\" - - * \"RoundToZero\" - - * \"RoundUp\" - - * \"RoundDown\" - -"), - -("Base","RoundNearest","RoundNearest - - The default rounding mode. Rounds to the nearest integer, with ties - (fractional values of 0.5) being rounded to the nearest even - integer. - -"), - -("Base","RoundNearestTiesAway","RoundNearestTiesAway - - Rounds to nearest integer, with ties rounded away from zero (C/C++ - \"round()\" behaviour). - -"), - -("Base","RoundNearestTiesUp","RoundNearestTiesUp - - Rounds to nearest integer, with ties rounded toward positive - infinity (Java/JavaScript \"round()\" behaviour). - -"), - -("Base","RoundToZero","RoundToZero - - \"round()\" using this rounding mode is an alias for \"trunc()\". - -"), - -("Base","RoundUp","RoundUp - - \"round()\" using this rounding mode is an alias for \"ceil()\". - -"), - -("Base","RoundDown","RoundDown - - \"round()\" using this rounding mode is an alias for \"floor()\". - -"), - -("Base","round","round([T], x[, digits[, base]][, r::RoundingMode]) - - \"round(x)\" rounds \"x\" to an integer value according to the - default rounding mode (see \"get_rounding()\"), returning a value - of the same type as \"x\". By default (\"RoundNearest\"), this will - round to the nearest integer, with ties (fractional values of 0.5) - being rounded to the even integer. - - julia> round(1.7) - 2.0 - - julia> round(1.5) - 2.0 - - julia> round(2.5) - 2.0 - - The optional \"RoundingMode\" argument will change how the number - gets rounded. - - \"round(T, x, [r::RoundingMode])\" converts the result to type - \"T\", throwing an \"InexactError\" if the value is not - representable. - - \"round(x, digits)\" rounds to the specified number of digits after - the decimal place (or before if negative). \"round(x, digits, - base)\" rounds using a base other than 10. - - julia> round(pi, 2) - 3.14 - - julia> round(pi, 3, 2) - 3.125 - - Note: Rounding to specified digits in bases other than 2 can be - inexact when operating on binary floating point numbers. For - example, the \"Float64\" value represented by \"1.15\" is - actually *less* than 1.15, yet will be rounded to 1.2. - - julia> x = 1.15 - 1.15 - - julia> @sprintf \"%.20f\" x - \"1.14999999999999991118\" - - julia> x < 115//100 - true - - julia> round(x, 1) - 1.2 - - round(z, RoundingModeReal, RoundingModeImaginary) - - Returns the nearest integral value of the same type as the complex- - valued \"z\" to \"z\", breaking ties using the specified - \"RoundingMode\"s. The first \"RoundingMode\" is used for rounding - the real components while the second is used for rounding the - imaginary components. - -"), - -("Base","ceil","ceil([T], x[, digits[, base]]) - - \"ceil(x)\" returns the nearest integral value of the same type as - \"x\" that is greater than or equal to \"x\". - - \"ceil(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","floor","floor([T], x[, digits[, base]]) - - \"floor(x)\" returns the nearest integral value of the same type as - \"x\" that is less than or equal to \"x\". - - \"floor(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","trunc","trunc([T], x[, digits[, base]]) - - \"trunc(x)\" returns the nearest integral value of the same type as - \"x\" whose absolute value is less than or equal to \"x\". - - \"trunc(T, x)\" converts the result to type \"T\", throwing an - \"InexactError\" if the value is not representable. - - \"digits\" and \"base\" work as for \"round()\". - -"), - -("Base","unsafe_trunc","unsafe_trunc(T, x) - - \"unsafe_trunc(T, x)\" returns the nearest integral value of type - \"T\" whose absolute value is less than or equal to \"x\". If the - value is not representable by \"T\", an arbitrary value will be - returned. - -"), - -("Base","signif","signif(x, digits[, base]) - - Rounds (in the sense of \"round\") \"x\" so that there are - \"digits\" significant digits, under a base \"base\" - representation, default 10. E.g., \"signif(123.456, 2)\" is - \"120.0\", and \"signif(357.913, 4, 2)\" is \"352.0\". - -"), - -("Base","min","min(x, y, ...) - - Return the minimum of the arguments. Operates elementwise over - arrays. - -"), - -("Base","max","max(x, y, ...) - - Return the maximum of the arguments. Operates elementwise over - arrays. - -"), - -("Base","minmax","minmax(x, y) - - Return \"(min(x,y), max(x,y))\". See also: \"extrema()\" that - returns \"(minimum(x), maximum(x))\" - -"), - -("Base","clamp","clamp(x, lo, hi) - - Return x if \"lo <= x <= hi\". If \"x < lo\", return \"lo\". If \"x - > hi\", return \"hi\". Arguments are promoted to a common type. - Operates elementwise over \"x\" if it is an array. - -"), - -("Base","bin","bin(n[, pad]) - - Convert an integer to a binary string, optionally specifying a - number of digits to pad to. - -"), - -("Base","hex","hex(n[, pad]) - - Convert an integer to a hexadecimal string, optionally specifying a - number of digits to pad to. - -"), - -("Base","dec","dec(n[, pad]) - - Convert an integer to a decimal string, optionally specifying a - number of digits to pad to. - -"), - -("Base","oct","oct(n[, pad]) - - Convert an integer to an octal string, optionally specifying a - number of digits to pad to. - -"), - -("Base","base","base(base, n[, pad]) - - Convert an integer to a string in the given base, optionally - specifying a number of digits to pad to. The base can be specified - as either an integer, or as a \"UInt8\" array of character values - to use as digit symbols. - -"), - -("Base","digits","digits(n[, base][, pad]) - - Returns an array of the digits of \"n\" in the given base, - optionally padded with zeros to a specified size. More significant - digits are at higher indexes, such that \"n == - sum([digits[k]*base^(k-1) for k=1:length(digits)])\". - -"), - -("Base","digits!","digits!(array, n[, base]) - - Fills an array of the digits of \"n\" in the given base. More - significant digits are at higher indexes. If the array length is - insufficient, the least significant digits are filled up to the - array length. If the array length is excessive, the excess portion - is filled with zeros. - -"), - -("Base","bits","bits(n) - - A string giving the literal bit representation of a number. - -"), - -("Base","parse","parse(str, start; greedy=true, raise=true) - - Parse the expression string and return an expression (which could - later be passed to eval for execution). Start is the index of the - first character to start parsing. If \"greedy\" is true (default), - \"parse\" will try to consume as much input as it can; otherwise, - it will stop as soon as it has parsed a valid expression. - Incomplete but otherwise syntactically valid expressions will - return \"Expr(:incomplete, \"(error message)\")\". If \"raise\" is - true (default), syntax errors other than incomplete expressions - will raise an error. If \"raise\" is false, \"parse\" will return - an expression that will raise an error upon evaluation. - - parse(str; raise=true) - - Parse the whole string greedily, returning a single expression. An - error is thrown if there are additional characters after the first - expression. If \"raise\" is true (default), syntax errors will - raise an error; otherwise, \"parse\" will return an expression that - will raise an error upon evaluation. - - parse(type, str[, base]) - - Parse a string as a number. If the type is an integer type, then a - base can be specified (the default is 10). If the type is a - floating point type, the string is parsed as a decimal floating - point number. If the string does not contain a valid number, an - error is raised. - -"), - -("Base","tryparse","tryparse(type, str[, base]) - - Like \"parse\", but returns a \"Nullable\" of the requested type. - The result will be null if the string does not contain a valid - number. - -"), - -("Base","big","big(x) - - Convert a number to a maximum precision representation (typically - \"BigInt\" or \"BigFloat\"). See \"BigFloat\" for information about - some pitfalls with floating-point numbers. - -"), - -("Base","signed","signed(x) - - Convert a number to a signed integer. If the argument is unsigned, - it is reinterpreted as signed without checking for overflow. - -"), - -("Base","unsigned","unsigned(x) -> Unsigned - - Convert a number to an unsigned integer. If the argument is signed, - it is reinterpreted as unsigned without checking for negative - values. - -"), - -("Base","float","float(x) - - Convert a number, array, or string to a \"FloatingPoint\" data - type. For numeric data, the smallest suitable \"FloatingPoint\" - type is used. Converts strings to \"Float64\". - -"), - -("Base","significand","significand(x) - - Extract the significand(s) (a.k.a. mantissa), in binary - representation, of a floating-point number or array. If \"x\" is a - non-zero finite number, than the result will be a number of the - same type on the interval [1,2). Otherwise \"x\" is returned. - - julia> significand(15.2)/15.2 - 0.125 - - julia> significand(15.2)*8 - 15.2 - -"), - -("Base","exponent","exponent(x) -> Int - - Get the exponent of a normalized floating-point number. - -"), - -("Base","complex","complex(r[, i]) - - Convert real numbers or arrays to complex. \"i\" defaults to zero. - -"), - -("Base","bswap","bswap(n) - - Byte-swap an integer - -"), - -("Base","num2hex","num2hex(f) - - Get a hexadecimal string of the binary representation of a floating - point number - -"), - -("Base","hex2num","hex2num(str) - - Convert a hexadecimal string to the floating point number it - represents - -"), - -("Base","hex2bytes","hex2bytes(s::ASCIIString) - - Convert an arbitrarily long hexadecimal string to its binary - representation. Returns an Array{UInt8, 1}, i.e. an array of bytes. - -"), - -("Base","bytes2hex","bytes2hex(bin_arr::Array{UInt8, 1}) - - Convert an array of bytes to its hexadecimal representation. All - characters are in lower-case. Returns an ASCIIString. - -"), - -("Base","one","one(x) - - Get the multiplicative identity element for the type of x (x can - also specify the type itself). For matrices, returns an identity - matrix of the appropriate size and type. - -"), - -("Base","zero","zero(x) - - Get the additive identity element for the type of x (x can also - specify the type itself). - -"), - -("Base","pi","pi -π - - The constant pi - -"), - -("Base","im","im - - The imaginary unit - -"), - -("Base","e","e -eu - - The constant e - -"), - -("Base","catalan","catalan - - Catalan's constant - -"), - -("Base","γ","γ -eulergamma - - Euler's constant - -"), - -("Base","φ","φ -golden - - The golden ratio - -"), - -("Base","Inf","Inf - - Positive infinity of type Float64 - -"), - -("Base","Inf32","Inf32 - - Positive infinity of type Float32 - -"), - -("Base","Inf16","Inf16 - - Positive infinity of type Float16 - -"), - -("Base","NaN","NaN - - A not-a-number value of type Float64 - -"), - -("Base","NaN32","NaN32 - - A not-a-number value of type Float32 - -"), - -("Base","NaN16","NaN16 - - A not-a-number value of type Float16 - -"), - -("Base","issubnormal","issubnormal(f) -> Bool - - Test whether a floating point number is subnormal - -"), - -("Base","isfinite","isfinite(f) -> Bool - - Test whether a number is finite - -"), - -("Base","isinf","isinf(f) -> Bool - - Test whether a number is infinite - -"), - -("Base","isnan","isnan(f) -> Bool - - Test whether a floating point number is not a number (NaN) - -"), - -("Base","inf","inf(f) - - Returns positive infinity of the floating point type \"f\" or of - the same floating point type as \"f\" - -"), - -("Base","nan","nan(f) - - Returns NaN (not-a-number) of the floating point type \"f\" or of - the same floating point type as \"f\" - -"), - -("Base","nextfloat","nextfloat(f) - - Get the next floating point number in lexicographic order - -"), - -("Base","prevfloat","prevfloat(f) -> FloatingPoint - - Get the previous floating point number in lexicographic order - -"), - -("Base","isinteger","isinteger(x) -> Bool - - Test whether \"x\" or all its elements are numerically equal to - some integer - -"), - -("Base","isreal","isreal(x) -> Bool - - Test whether \"x\" or all its elements are numerically equal to - some real number - -"), - -("Base","Float32","Float32(x[, mode::RoundingMode]) - - Create a Float32 from \"x\". If \"x\" is not exactly representable - then \"mode\" determines how \"x\" is rounded. - - julia> Float32(1/3, RoundDown) - 0.3333333f0 - - julia> Float32(1/3, RoundUp) - 0.33333334f0 - - See \"get_rounding\" for available rounding modes. - -"), - -("Base","Float64","Float64(x[, mode::RoundingMode]) - - Create a Float64 from \"x\". If \"x\" is not exactly representable - then \"mode\" determines how \"x\" is rounded. - - julia> Float64(pi, RoundDown) - 3.141592653589793 - - julia> Float64(pi, RoundUp) - 3.1415926535897936 - - See \"get_rounding\" for available rounding modes. - -"), - -("Base","BigInt","BigInt(x) - - Create an arbitrary precision integer. \"x\" may be an \"Int\" (or - anything that can be converted to an \"Int\"). The usual - mathematical operators are defined for this type, and results are - promoted to a \"BigInt\". - - Instances can be constructed from strings via \"parse()\", or using - the \"big\" string literal. - -"), - -("Base","BigFloat","BigFloat(x) - - Create an arbitrary precision floating point number. \"x\" may be - an \"Integer\", a \"Float64\" or a \"BigInt\". The usual - mathematical operators are defined for this type, and results are - promoted to a \"BigFloat\". - - Note that because decimal literals are converted to floating point - numbers when parsed, \"BigFloat(2.1)\" may not yield what you - expect. You may instead prefer to initialize constants from strings - via \"parse()\", or using the \"big\" string literal. - - julia> big\"2.1\" - 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision - -"), - -("Base","get_rounding","get_rounding(T) - - Get the current floating point rounding mode for type \"T\", - controlling the rounding of basic arithmetic functions (\"+()\", - \"-()\", \">>*<<()\", \"/()\" and \"sqrt()\") and type conversion. - - Valid modes are \"RoundNearest\", \"RoundToZero\", \"RoundUp\", - \"RoundDown\", and \"RoundFromZero\" (\"BigFloat\" only). - -"), - -("Base","set_rounding","set_rounding(T, mode) - - Set the rounding mode of floating point type \"T\", controlling the - rounding of basic arithmetic functions (\"+()\", \"-()\", - \">>*<<()\", \"/()\" and \"sqrt()\") and type conversion. - - Note that this may affect other types, for instance changing the - rounding mode of \"Float64\" will change the rounding mode of - \"Float32\". See \"get_rounding\" for available modes - -"), - -("Base","with_rounding","with_rounding(f::Function, T, mode) - - Change the rounding mode of floating point type \"T\" for the - duration of \"f\". It is logically equivalent to: - - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) - - See \"get_rounding\" for available rounding modes. - -"), - -("Base","count_ones","count_ones(x::Integer) -> Integer - - Number of ones in the binary representation of \"x\". - - julia> count_ones(7) - 3 - -"), - -("Base","count_zeros","count_zeros(x::Integer) -> Integer - - Number of zeros in the binary representation of \"x\". - - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 - -"), - -("Base","leading_zeros","leading_zeros(x::Integer) -> Integer - - Number of zeros leading the binary representation of \"x\". - - julia> leading_zeros(Int32(1)) - 31 - -"), - -("Base","leading_ones","leading_ones(x::Integer) -> Integer - - Number of ones leading the binary representation of \"x\". - - julia> leading_ones(UInt32(2 ^ 32 - 2)) - 31 - -"), - -("Base","trailing_zeros","trailing_zeros(x::Integer) -> Integer - - Number of zeros trailing the binary representation of \"x\". - - julia> trailing_zeros(2) - 1 - -"), - -("Base","trailing_ones","trailing_ones(x::Integer) -> Integer - - Number of ones trailing the binary representation of \"x\". - - julia> trailing_ones(3) - 2 - -"), - -("Base","isprime","isprime(x::Integer) -> Bool - - Returns \"true\" if \"x\" is prime, and \"false\" otherwise. - - julia> isprime(3) - true - - isprime(x::BigInt[, reps = 25]) -> Bool - - Probabilistic primality test. Returns \"true\" if \"x\" is prime; - and \"false\" if \"x\" is not prime with high probability. The - false positive rate is about \"0.25^reps\". \"reps = 25\" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). - - julia> isprime(big(3)) - true - -"), - -("Base","isprime","isprime(x::Integer) -> Bool - - Returns \"true\" if \"x\" is prime, and \"false\" otherwise. - - julia> isprime(3) - true - - isprime(x::BigInt[, reps = 25]) -> Bool - - Probabilistic primality test. Returns \"true\" if \"x\" is prime; - and \"false\" if \"x\" is not prime with high probability. The - false positive rate is about \"0.25^reps\". \"reps = 25\" is - considered safe for cryptographic applications (Knuth, - Seminumerical Algorithms). - - julia> isprime(big(3)) - true - -"), - -("Base","primes","primes(n) - - Returns a collection of the prime numbers <= \"n\". - -"), - -("Base","isodd","isodd(x::Integer) -> Bool - - Returns \"true\" if \"x\" is odd (that is, not divisible by 2), and - \"false\" otherwise. - - julia> isodd(9) - true - - julia> isodd(10) - false - -"), - -("Base","iseven","iseven(x::Integer) -> Bool - - Returns \"true\" is \"x\" is even (that is, divisible by 2), and - \"false\" otherwise. - - julia> iseven(9) - false - - julia> iseven(10) - true - -"), - -("Base","precision","precision(num::FloatingPoint) - - Get the precision of a floating point number, as defined by the - effective number of bits in the mantissa. - -"), - -("Base","get_bigfloat_precision","get_bigfloat_precision() - - Get the precision (in bits) currently used for BigFloat arithmetic. - -"), - -("Base","set_bigfloat_precision","set_bigfloat_precision(x::Int64) - - Set the precision (in bits) to be used to BigFloat arithmetic. - -"), - -("Base","with_bigfloat_precision","with_bigfloat_precision(f::Function, precision::Integer) - - Change the BigFloat arithmetic precision (in bits) for the duration - of \"f\". It is logically equivalent to: - - old = get_bigfloat_precision() - set_bigfloat_precision(precision) - f() - set_bigfloat_precision(old) - -"), - -("Base","srand","srand([rng][, seed]) - - Reseed the random number generator. If a \"seed\" is provided, the - RNG will give a reproducible sequence of numbers, otherwise Julia - will get entropy from the system. For \"MersenneTwister\", the - \"seed\" may be a non-negative integer, a vector of \"UInt32\" - integers or a filename, in which case the seed is read from a file. - \"RandomDevice\" does not support seeding. - -"), - -("Base","MersenneTwister","MersenneTwister([seed]) - - Create a \"MersenneTwister\" RNG object. Different RNG objects can - have their own seeds, which may be useful for generating different - streams of random numbers. - -"), - -("Base","RandomDevice","RandomDevice() - - Create a \"RandomDevice\" RNG object. Two such objects will always - generate different streams of random numbers. - -"), - -("Base","rand","rand([rng][, S][, dims...]) - - Pick a random element or array of random elements from the set of - values specified by \"S\"; \"S\" can be - - * an indexable collection (for example \"1:n\" or - \"['x','y','z']\"), or - - * a type: the set of values to pick from is then equivalent to - \"typemin(S):typemax(S)\" for integers (this is not applicable - to \"BigInt\"), and to [0,1) for floating point numbers; - - \"S\" defaults to \"Float64\". - -"), - -("Base","rand!","rand!([rng], A[, coll]) - - Populate the array A with random values. If the indexable - collection \"coll\" is specified, the values are picked randomly - from \"coll\". This is equivalent to \"copy!(A, rand(rng, coll, - size(A)))\" or \"copy!(A, rand(rng, eltype(A), size(A)))\" but - without allocating a new array. - -"), - -("Base","bitrand","bitrand([rng][, dims...]) - - Generate a \"BitArray\" of random boolean values. - -"), - -("Base","randn","randn([rng][, dims...]) - - Generate a normally-distributed random number with mean 0 and - standard deviation 1. Optionally generate an array of normally- - distributed random numbers. - -"), - -("Base","randn!","randn!([rng], A::Array{Float64, N}) - - Fill the array A with normally-distributed (mean 0, standard - deviation 1) random numbers. Also see the rand function. - -"), - -("Base","randexp","randexp([rng][, dims...]) - - Generate a random number according to the exponential distribution - with scale 1. Optionally generate an array of such random numbers. - -"), - -("Base","randexp!","randexp!([rng], A::Array{Float64, N}) - - Fill the array A with random numbers following the exponential - distribution (with scale 1). - -"), - -("Base","Task","Task(func) - - Create a \"Task\" (i.e. thread, or coroutine) to execute the given - function (which must be callable with no arguments). The task exits - when this function returns. - -"), - -("Base","yieldto","yieldto(task, arg = nothing) - - Switch to the given task. The first time a task is switched to, the - task's function is called with no arguments. On subsequent - switches, \"arg\" is returned from the task's last call to - \"yieldto\". This is a low-level call that only switches tasks, not - considering states or scheduling in any way. Its use is - discouraged. - -"), - -("Base","current_task","current_task() - - Get the currently running Task. - -"), - -("Base","istaskdone","istaskdone(task) -> Bool - - Tell whether a task has exited. - -"), - -("Base","istaskstarted","istaskstarted(task) -> Bool - - Tell whether a task has started executing. - -"), - -("Base","consume","consume(task, values...) - - Receive the next value passed to \"produce\" by the specified task. - Additional arguments may be passed, to be returned from the last - \"produce\" call in the producer. - -"), - -("Base","produce","produce(value) - - Send the given value to the last \"consume\" call, switching to the - consumer task. If the next \"consume\" call passes any values, they - are returned by \"produce\". - -"), - -("Base","yield","yield() - - Switch to the scheduler to allow another scheduled task to run. A - task that calls this function is still runnable, and will be - restarted immediately if there are no other runnable tasks. - -"), - -("Base","task_local_storage","task_local_storage(symbol) - - Look up the value of a symbol in the current task's task-local - storage. - - task_local_storage(symbol, value) - - Assign a value to a symbol in the current task's task-local - storage. - - task_local_storage(body, symbol, value) - - Call the function \"body\" with a modified task-local storage, in - which \"value\" is assigned to \"symbol\"; the previous value of - \"symbol\", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. - -"), - -("Base","task_local_storage","task_local_storage(symbol) - - Look up the value of a symbol in the current task's task-local - storage. - - task_local_storage(symbol, value) - - Assign a value to a symbol in the current task's task-local - storage. - - task_local_storage(body, symbol, value) - - Call the function \"body\" with a modified task-local storage, in - which \"value\" is assigned to \"symbol\"; the previous value of - \"symbol\", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. - -"), - -("Base","task_local_storage","task_local_storage(symbol) - - Look up the value of a symbol in the current task's task-local - storage. - - task_local_storage(symbol, value) - - Assign a value to a symbol in the current task's task-local - storage. - - task_local_storage(body, symbol, value) - - Call the function \"body\" with a modified task-local storage, in - which \"value\" is assigned to \"symbol\"; the previous value of - \"symbol\", or lack thereof, is restored afterwards. Useful for - emulating dynamic scoping. - -"), - -("Base","Condition","Condition() - - Create an edge-triggered event source that tasks can wait for. - Tasks that call \"wait\" on a \"Condition\" are suspended and - queued. Tasks are woken up when \"notify\" is later called on the - \"Condition\". Edge triggering means that only tasks waiting at the - time \"notify\" is called can be woken up. For level-triggered - notifications, you must keep extra state to keep track of whether a - notification has happened. The \"RemoteRef\" type does this, and so - can be used for level-triggered events. - -"), - -("Base","notify","notify(condition, val=nothing; all=true, error=false) - - Wake up tasks waiting for a condition, passing them \"val\". If - \"all\" is true (the default), all waiting tasks are woken, - otherwise only one is. If \"error\" is true, the passed value is - raised as an exception in the woken tasks. - -"), - -("Base","schedule","schedule(t::Task, [val]; error=false) - - Add a task to the scheduler's queue. This causes the task to run - constantly when the system is otherwise idle, unless the task - performs a blocking operation such as \"wait\". - - If a second argument is provided, it will be passed to the task - (via the return value of \"yieldto\") when it runs again. If - \"error\" is true, the value is raised as an exception in the woken - task. - -"), - -("Base","@schedule","@schedule() - - Wrap an expression in a Task and add it to the scheduler's queue. - -"), - -("Base","@task","@task() - - Wrap an expression in a Task without executing it, and return the - Task. This only creates a task, and does not run it. - -"), - -("Base","sleep","sleep(seconds) - - Block the current task for a specified number of seconds. The - minimum sleep time is 1 millisecond or input of \"0.001\". - -"), - -("Base","ReentrantLock","ReentrantLock() - - Creates a reentrant lock. The same task can acquire the lock as - many times as required. Each lock must be matched with an unlock. - -"), - -("Base","lock","lock(l::ReentrantLock) - - Associates \"l\" with the current task. If \"l\" is already locked - by a different task, waits for it to become available. The same - task can acquire the lock multiple times. Each \"lock\" must be - matched by an \"unlock\" - -"), - -("Base","unlock","unlock(l::ReentrantLock) - - Releases ownership of the lock by the current task. If the lock had - been acquired before, it just decrements an internal counter and - returns immediately. - -"), - -("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built \"LocalManager\" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. \"addprocs(4)\" will add 4 processes - on the local machine. - - addprocs() -> List of process identifiers - - Equivalent to \"addprocs(CPU_CORES)\" - - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - \"machines\" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string \"machine_spec\" or a - tuple - \"(machine_spec, count)\" - - \"machine_spec\" is a string of the form \"[user@]host[:port] - [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" - to the standard ssh port. If \"[bind_addr[:port]]\" is specified, - other workers will connect to this worker at the specified - \"bind_addr\" and \"port\". - - \"count\" is the number of workers to be launched on the specified - host. If specified as \":auto\" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: - - \"tunnel\" : if \"true\" then SSH tunneling will be used to connect - to the worker from the master process. - - \"sshflags\" : specifies additional ssh options, e.g. - \"sshflags=``-i /home/foo/bar.pem``\" . - - \"max_parallel\" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. - - \"dir\" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) - - \"exename\" : name of the julia executable. Defaults to - \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case - may be. - - \"exeflags\" : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable \"JULIA_WORKER_TIMEOUT\". The value of - \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster - manager implemented in package \"ClusterManagers\". - - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. - Relevant only when using TCP/IP as transport. - -"), - -("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built \"LocalManager\" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. \"addprocs(4)\" will add 4 processes - on the local machine. - - addprocs() -> List of process identifiers - - Equivalent to \"addprocs(CPU_CORES)\" - - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - \"machines\" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string \"machine_spec\" or a - tuple - \"(machine_spec, count)\" - - \"machine_spec\" is a string of the form \"[user@]host[:port] - [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" - to the standard ssh port. If \"[bind_addr[:port]]\" is specified, - other workers will connect to this worker at the specified - \"bind_addr\" and \"port\". - - \"count\" is the number of workers to be launched on the specified - host. If specified as \":auto\" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: - - \"tunnel\" : if \"true\" then SSH tunneling will be used to connect - to the worker from the master process. - - \"sshflags\" : specifies additional ssh options, e.g. - \"sshflags=``-i /home/foo/bar.pem``\" . - - \"max_parallel\" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. - - \"dir\" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) - - \"exename\" : name of the julia executable. Defaults to - \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case - may be. - - \"exeflags\" : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable \"JULIA_WORKER_TIMEOUT\". The value of - \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster - manager implemented in package \"ClusterManagers\". - - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. - Relevant only when using TCP/IP as transport. - -"), - -("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built \"LocalManager\" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. \"addprocs(4)\" will add 4 processes - on the local machine. - - addprocs() -> List of process identifiers - - Equivalent to \"addprocs(CPU_CORES)\" - - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - \"machines\" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string \"machine_spec\" or a - tuple - \"(machine_spec, count)\" - - \"machine_spec\" is a string of the form \"[user@]host[:port] - [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" - to the standard ssh port. If \"[bind_addr[:port]]\" is specified, - other workers will connect to this worker at the specified - \"bind_addr\" and \"port\". - - \"count\" is the number of workers to be launched on the specified - host. If specified as \":auto\" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: - - \"tunnel\" : if \"true\" then SSH tunneling will be used to connect - to the worker from the master process. - - \"sshflags\" : specifies additional ssh options, e.g. - \"sshflags=``-i /home/foo/bar.pem``\" . - - \"max_parallel\" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. - - \"dir\" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) - - \"exename\" : name of the julia executable. Defaults to - \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case - may be. - - \"exeflags\" : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable \"JULIA_WORKER_TIMEOUT\". The value of - \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster - manager implemented in package \"ClusterManagers\". - - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. - Relevant only when using TCP/IP as transport. - -"), - -("Base","addprocs","addprocs(n::Integer; exeflags=``) -> List of process identifiers - - Launches workers using the in-built \"LocalManager\" which only - launches workers on the local host. This can be used to take - advantage of multiple cores. \"addprocs(4)\" will add 4 processes - on the local machine. - - addprocs() -> List of process identifiers - - Equivalent to \"addprocs(CPU_CORES)\" - - addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers - - Add processes on remote machines via SSH. Requires julia to be - installed in the same location on each node, or to be available via - a shared file system. - - \"machines\" is a vector of machine specifications. Worker are - started for each specification. - - A machine specification is either a string \"machine_spec\" or a - tuple - \"(machine_spec, count)\" - - \"machine_spec\" is a string of the form \"[user@]host[:port] - [bind_addr[:port]]\". \"user\" defaults to current user, \"port\" - to the standard ssh port. If \"[bind_addr[:port]]\" is specified, - other workers will connect to this worker at the specified - \"bind_addr\" and \"port\". - - \"count\" is the number of workers to be launched on the specified - host. If specified as \":auto\" it will launch as many workers as - the number of cores on the specific host. - - Keyword arguments: - - \"tunnel\" : if \"true\" then SSH tunneling will be used to connect - to the worker from the master process. - - \"sshflags\" : specifies additional ssh options, e.g. - \"sshflags=``-i /home/foo/bar.pem``\" . - - \"max_parallel\" : specifies the maximum number of workers - connected to in parallel at a host. Defaults to 10. - - \"dir\" : specifies the working directory on the workers. Defaults - to the host's current directory (as found by *pwd()*) - - \"exename\" : name of the julia executable. Defaults to - \"\$JULIA_HOME/julia\" or \"\$JULIA_HOME/julia-debug\" as the case - may be. - - \"exeflags\" : additional flags passed to the worker processes. - - Environment variables : - - If the master process fails to establish a connection with a newly - launched worker within 60.0 seconds, the worker treats it a fatal - situation and terminates. This timeout can be controlled via - environment variable \"JULIA_WORKER_TIMEOUT\". The value of - \"JULIA_WORKER_TIMEOUT\" on the master process, specifies the - number of seconds a newly launched worker waits for connection - establishment. - - addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - - Launches worker processes via the specified cluster manager. - - For example Beowulf clusters are supported via a custom cluster - manager implemented in package \"ClusterManagers\". - - The number of seconds a newly launched worker waits for connection - establishment from the master can be specified via variable - \"JULIA_WORKER_TIMEOUT\" in the worker process's environment. - Relevant only when using TCP/IP as transport. - -"), - -("Base","nprocs","nprocs() - - Get the number of available processes. - -"), - -("Base","nworkers","nworkers() - - Get the number of available worker processes. This is one less than - nprocs(). Equal to nprocs() if nprocs() == 1. - -"), - -("Base","procs","procs() - - Returns a list of all process identifiers. - - procs(S::SharedArray) - - Get the vector of processes that have mapped the shared array - -"), - -("Base","workers","workers() - - Returns a list of all worker process identifiers. - -"), - -("Base","rmprocs","rmprocs(pids...) - - Removes the specified workers. - -"), - -("Base","interrupt","interrupt([pids...]) - - Interrupt the current executing task on the specified workers. This - is equivalent to pressing Ctrl-C on the local machine. If no - arguments are given, all workers are interrupted. - -"), - -("Base","myid","myid() - - Get the id of the current process. - -"), - -("Base","pmap","pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) - - Transform collections \"lsts\" by applying \"f\" to each element in - parallel. If \"nprocs() > 1\", the calling process will be - dedicated to assigning tasks. All other available processes will be - used as parallel workers, or on the processes specified by - \"pids\". - - If \"err_retry\" is true, it retries a failed application of \"f\" - on a different worker. If \"err_stop\" is true, it takes precedence - over the value of \"err_retry\" and \"pmap\" stops execution on the - first error. - -"), - -("Base","remotecall","remotecall(id, func, args...) - - Call a function asynchronously on the given arguments on the - specified process. Returns a \"RemoteRef\". - -"), - -("Base","wait","wait([x]) - - Block the current task until some event occurs, depending on the - type of the argument: - - * \"RemoteRef\": Wait for a value to become available for the - specified remote reference. - - * \"Condition\": Wait for \"notify\" on a condition. - - * \"Process\": Wait for a process or process chain to exit. - The \"exitcode\" field of a process can be used to determine - success or failure. - - * \"Task\": Wait for a \"Task\" to finish, returning its - result value. If the task fails with an exception, the - exception is propagated (re-thrown in the task that called - \"wait\"). - - * \"RawFD\": Wait for changes on a file descriptor (see - *poll_fd* for keyword arguments and return code) - - If no argument is passed, the task blocks for an undefined period. - If the task's state is set to \":waiting\", it can only be - restarted by an explicit call to \"schedule\" or \"yieldto\". If - the task's state is \":runnable\", it might be restarted - unpredictably. - - Often \"wait\" is called within a \"while\" loop to ensure a - waited-for condition is met before proceeding. - -"), - -("Base","fetch","fetch(RemoteRef) - - Wait for and get the value of a remote reference. - -"), - -("Base","remotecall_wait","remotecall_wait(id, func, args...) - - Perform \"wait(remotecall(...))\" in one message. - -"), - -("Base","remotecall_fetch","remotecall_fetch(id, func, args...) - - Perform \"fetch(remotecall(...))\" in one message. - -"), - -("Base","put!","put!(RemoteRef, value) - - Store a value to a remote reference. Implements \"shared queue of - length 1\" semantics: if a value is already present, blocks until - the value is removed with \"take!\". Returns its first argument. - -"), - -("Base","take!","take!(RemoteRef) - - Fetch the value of a remote reference, removing it so that the - reference is empty again. - -"), - -("Base","isready","isready(r::RemoteRef) - - Determine whether a \"RemoteRef\" has a value stored to it. Note - that this function can cause race conditions, since by the time you - receive its result it may no longer be true. It is recommended that - this function only be used on a \"RemoteRef\" that is assigned - once. - - If the argument \"RemoteRef\" is owned by a different node, this - call will block to wait for the answer. It is recommended to wait - for \"r\" in a separate task instead, or to use a local - \"RemoteRef\" as a proxy: - - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block - -"), - -("Base","RemoteRef","RemoteRef() - - Make an uninitialized remote reference on the local machine. - - RemoteRef(n) - - Make an uninitialized remote reference on process \"n\". - -"), - -("Base","RemoteRef","RemoteRef() - - Make an uninitialized remote reference on the local machine. - - RemoteRef(n) - - Make an uninitialized remote reference on process \"n\". - -"), - -("Base","timedwait","timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - - Waits till \"testcb\" returns \"true\" or for \"secs`\" seconds, - whichever is earlier. \"testcb\" is polled every \"pollint\" - seconds. - -"), - -("Base","@spawn","@spawn() - - Execute an expression on an automatically-chosen process, returning - a \"RemoteRef\" to the result. - -"), - -("Base","@spawnat","@spawnat() - - Accepts two arguments, \"p\" and an expression, and runs the - expression asynchronously on process \"p\", returning a - \"RemoteRef\" to the result. - -"), - -("Base","@fetch","@fetch() - - Equivalent to \"fetch(@spawn expr)\". - -"), - -("Base","@fetchfrom","@fetchfrom() - - Equivalent to \"fetch(@spawnat p expr)\". - -"), - -("Base","@async","@async() - - Schedule an expression to run on the local machine, also adding it - to the set of items that the nearest enclosing \"@sync\" waits for. - -"), - -("Base","@sync","@sync() - - Wait until all dynamically-enclosed uses of \"@async\", \"@spawn\", - \"@spawnat\" and \"@parallel\" are complete. - -"), - -("Base","@parallel","@parallel() - - A parallel for loop of the form - - @parallel [reducer] for var = range - body - end - - The specified range is partitioned and locally executed across all - workers. In case an optional reducer function is specified, - @parallel performs local reductions on each worker with a final - reduction on the calling process. - - Note that without a reducer function, @parallel executes - asynchronously, i.e. it spawns independent tasks on all available - workers and returns immediately without waiting for completion. To - wait for completion, prefix the call with \"@sync\", like - - @sync @parallel for var = range - body - end - -"), - -("Base","SharedArray","SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - - Construct a SharedArray of a bitstype \"T\" and size \"dims\" - across the processes specified by \"pids\" - all of which have to - be on the same host. - - If \"pids\" is left unspecified, the shared array will be mapped - across all processes on the current host, including the master. - But, \"localindexes\" and \"indexpids\" will only refer to worker - processes. This facilitates work distribution code to use workers - for actual computation with the master process acting as a driver. - - If an \"init\" function of the type \"initfn(S::SharedArray)\" is - specified, it is called on all the participating workers. - -"), - -("Base","procs","procs() - - Returns a list of all process identifiers. - - procs(S::SharedArray) - - Get the vector of processes that have mapped the shared array - -"), - -("Base","sdata","sdata(S::SharedArray) - - Returns the actual \"Array\" object backing \"S\" - -"), - -("Base","indexpids","indexpids(S::SharedArray) - - Returns the index of the current worker into the \"pids\" vector, - i.e., the list of workers mapping the SharedArray - -"), - -("Base","launch","launch(manager::FooManager, params::Dict, launched::Vector{WorkerConfig}, launch_ntfy::Condition) - - Implemented by cluster managers. For every Julia worker launched by - this function, it should append a \"WorkerConfig\" entry to - \"launched\" and notify \"launch_ntfy\". The function MUST exit - once all workers, requested by \"manager\" have been launched. - \"params\" is a dictionary of all keyword arguments \"addprocs\" - was called with. - -"), - -("Base","manage","manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) - - Implemented by cluster managers. It is called on the master - process, during a worker's lifetime, with appropriate \"op\" - values: - - * with \":register\"/\":deregister\" when a worker is added / - removed from the Julia worker pool. - - * with \":interrupt\" when \"interrupt(workers)\" is called. - The \"ClusterManager\" should signal the appropriate worker - with an interrupt signal. - - * with \":finalize\" for cleanup purposes. - -"), - -("Base","kill","kill(p::Process, signum=SIGTERM) - - Send a signal to a process. The default is to terminate the - process. - - kill(manager::FooManager, pid::Int, config::WorkerConfig) - - Implemented by cluster managers. It is called on the master - process, by \"rmprocs\". It should cause the remote worker - specified by \"pid\" to exit. - \"Base.kill(manager::ClusterManager.....)\" executes a remote - \"exit()\" on \"pid\" - -"), - -("Base","init_worker","init_worker(manager::FooManager) - - Called by cluster managers implementing custom transports. It - initializes a newly launched process as a worker. Command line - argument \"–worker\" has the effect of initializing a process as a - worker using TCP/IP sockets for transport. - -"), - -("Base","connect","connect([host], port) -> TcpSocket - - Connect to the host \"host\" on port \"port\" - - connect(path) -> Pipe - - Connect to the Named Pipe/Domain Socket at \"path\" - - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - - Implemented by cluster managers using custom transports. It should - establish a logical connection to worker with id \"pid\", specified - by \"config\" and return a pair of \"AsyncStream\" objects. - Messages from \"pid\" to current process will be read off - \"instrm\", while messages to be sent to \"pid\" will be written to - \"outstrm\". The custom transport implementation must ensure that - messages are delivered and received completely and in order. - \"Base.connect(manager::ClusterManager.....)\" sets up TCP/IP - socket connections in-between workers. - -"), - -("Base","Base","Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) - - Called by cluster managers using custom transports. It should be - called when the custom transport implementation receives the first - message from a remote worker. The custom transport must manage a - logical connection to the remote worker and provide two AsyncStream - objects, one for incoming messages and the other for messages - addressed to the remote worker. - -"), - -("Base.Pkg","dir","dir() -> AbstractString - - Returns the absolute path of the package directory. This defaults - to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION - .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell - syntax). If the \"JULIA_PKGDIR\" environment variable is set, then - that path is used in the returned value as - \"joinpath(ENV[\">>JULIA_<< - PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If - \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to - whatever the current working directory is. - - dir(names...) -> AbstractString - - Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, \"Pkg.dir(pkg)\" returns the path to - the package \"pkg\". - -"), - -("Base.Pkg","dir","dir() -> AbstractString - - Returns the absolute path of the package directory. This defaults - to \"joinpath(homedir(),\".julia\",\"v\$(VERSION.major).\$(VERSION - .minor)\")\" on all platforms (i.e. \"~/.julia/v0.4\" in UNIX shell - syntax). If the \"JULIA_PKGDIR\" environment variable is set, then - that path is used in the returned value as - \"joinpath(ENV[\">>JULIA_<< - PKGDIR\"],\"v\$(VERSION.major).\$(VERSION.minor)\")\". If - \"JULIA_PKGDIR\" is a relative path, it is interpreted relative to - whatever the current working directory is. - - dir(names...) -> AbstractString - - Equivalent to \"normpath(Pkg.dir(),names...)\" – i.e. it appends - path components to the package directory and normalizes the - resulting path. In particular, \"Pkg.dir(pkg)\" returns the path to - the package \"pkg\". - -"), - -("Base.Pkg","init","init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - - Initialize \"Pkg.dir()\" as a package directory. This will be done - automatically when the \"JULIA_PKGDIR\" is not set and - \"Pkg.dir()\" uses its default value. As part of this process, - clones a local METADATA git repository from the site and branch - specified by its arguments, which are typically not provided. - Explicit (non-default) arguments can be used to support a custom - METADATA setup. - -"), - -("Base.Pkg","resolve","resolve() - - Determines an optimal, consistent set of package versions to - install or upgrade to. The optimal set of package versions is based - on the contents of \"Pkg.dir(\"REQUIRE\")\" and the state of - installed packages in \"Pkg.dir()\", Packages that are no longer - required are moved into \"Pkg.dir(\".trash\")\". - -"), - -("Base.Pkg","edit","edit() - - Opens \"Pkg.dir(\"REQUIRE\")\" in the editor specified by the - \"VISUAL\" or \"EDITOR\" environment variables; when the editor - command returns, it runs \"Pkg.resolve()\" to determine and install - a new optimal set of installed package versions. - -"), - -("Base.Pkg","add","add(pkg, vers...) - - Add a requirement entry for \"pkg\" to \"Pkg.dir(\"REQUIRE\")\" and - call \"Pkg.resolve()\". If \"vers\" are given, they must be - \"VersionNumber\" objects and they specify acceptable version - intervals for \"pkg\". - -"), - -("Base.Pkg","rm","rm(pkg) - - Remove all requirement entries for \"pkg\" from - \"Pkg.dir(\"REQUIRE\")\" and call \"Pkg.resolve()\". - -"), - -("Base.Pkg","clone","clone(url[, pkg]) - - Clone a package directly from the git URL \"url\". The package does - not need to be a registered in \"Pkg.dir(\"METADATA\")\". The - package repo is cloned by the name \"pkg\" if provided; if not - provided, \"pkg\" is determined automatically from \"url\". - - clone(pkg) - - If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone - it from that URL on the default branch. The package does not need - to have any registered versions. - -"), - -("Base.Pkg","clone","clone(url[, pkg]) - - Clone a package directly from the git URL \"url\". The package does - not need to be a registered in \"Pkg.dir(\"METADATA\")\". The - package repo is cloned by the name \"pkg\" if provided; if not - provided, \"pkg\" is determined automatically from \"url\". - - clone(pkg) - - If \"pkg\" has a URL registered in \"Pkg.dir(\"METADATA\")\", clone - it from that URL on the default branch. The package does not need - to have any registered versions. - -"), - -("Base.Pkg","available","available() -> Vector{ASCIIString} - - Returns the names of available packages. - - available(pkg) -> Vector{VersionNumber} - - Returns the version numbers available for package \"pkg\". - -"), - -("Base.Pkg","available","available() -> Vector{ASCIIString} - - Returns the names of available packages. - - available(pkg) -> Vector{VersionNumber} - - Returns the version numbers available for package \"pkg\". - -"), - -("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} - - Returns a dictionary mapping installed package names to the - installed version number of each package. - - installed(pkg) -> Void | VersionNumber - - If \"pkg\" is installed, return the installed version number, - otherwise return \"nothing\". - -"), - -("Base.Pkg","installed","installed() -> Dict{ASCIIString,VersionNumber} - - Returns a dictionary mapping installed package names to the - installed version number of each package. - - installed(pkg) -> Void | VersionNumber - - If \"pkg\" is installed, return the installed version number, - otherwise return \"nothing\". - -"), - -("Base.Pkg","status","status() - - Prints out a summary of what packages are installed and what - version and state they're in. - -"), - -("Base.Pkg","update","update() - - Update package the metadata repo – kept in - \"Pkg.dir(\"METADATA\")\" – then update any fixed packages that can - safely be pulled from their origin; then call \"Pkg.resolve()\" to - determine a new optimal set of packages versions. - -"), - -("Base.Pkg","checkout","checkout(pkg[, branch=\"master\"]) - - Checkout the \"Pkg.dir(pkg)\" repo to the branch \"branch\". - Defaults to checking out the \"master\" branch. To go back to using - the newest compatible released version, use \"Pkg.free(pkg)\" - -"), - -("Base.Pkg","pin","pin(pkg) - - Pin \"pkg\" at the current version. To go back to using the newest - compatible released version, use \"Pkg.free(pkg)\" - - pin(pkg, version) - - Pin \"pkg\" at registered version \"version\". - -"), - -("Base.Pkg","pin","pin(pkg) - - Pin \"pkg\" at the current version. To go back to using the newest - compatible released version, use \"Pkg.free(pkg)\" - - pin(pkg, version) - - Pin \"pkg\" at registered version \"version\". - -"), - -("Base.Pkg","free","free(pkg) - - Free the package \"pkg\" to be managed by the package manager - again. It calls \"Pkg.resolve()\" to determine optimal package - versions after. This is an inverse for both \"Pkg.checkout\" and - \"Pkg.pin\". - - You can also supply an iterable collection of package names, e.g., - \"Pkg.free((\"Pkg1\", \"Pkg2\"))\" to free multiple packages at - once. - -"), - -("Base.Pkg","build","build() - - Run the build scripts for all installed packages in depth-first - recursive order. - - build(pkgs...) - - Run the build script in \"deps/build.jl\" for each package in - \"pkgs\" and all of their dependencies in depth-first recursive - order. This is called automatically by \"Pkg.resolve()\" on all - installed or updated packages. - -"), - -("Base.Pkg","build","build() - - Run the build scripts for all installed packages in depth-first - recursive order. - - build(pkgs...) - - Run the build script in \"deps/build.jl\" for each package in - \"pkgs\" and all of their dependencies in depth-first recursive - order. This is called automatically by \"Pkg.resolve()\" on all - installed or updated packages. - -"), - -("Base.Pkg","generate","generate(pkg, license) - - Generate a new package named \"pkg\" with one of these license - keys: \"\"MIT\"\", \"\"BSD\"\" or \"\"ASL\"\". If you want to make - a package with a different license, you can edit it afterwards. - Generate creates a git repo at \"Pkg.dir(pkg)\" for the package and - inside it \"LICENSE.md\", \"README.md\", the julia entrypoint - \"\$pkg/src/\$pkg.jl\", and a travis test file, \".travis.yml\". - -"), - -("Base.Pkg","register","register(pkg[, url]) - - Register \"pkg\" at the git URL \"url\", defaulting to the - configured origin URL of the git repo \"Pkg.dir(pkg)\". - -"), - -("Base.Pkg","tag","tag(pkg[, ver[, commit]]) - - Tag \"commit\" as version \"ver\" of package \"pkg\" and create a - version entry in \"METADATA\". If not provided, \"commit\" defaults - to the current commit of the \"pkg\" repo. If \"ver\" is one of the - symbols \":patch\", \":minor\", \":major\" the next patch, minor or - major version is used. If \"ver\" is not provided, it defaults to - \":patch\". - -"), - -("Base.Pkg","publish","publish() - - For each new package version tagged in \"METADATA\" not already - published, make sure that the tagged package commits have been - pushed to the repo at the registered URL for the package and if - they all have, open a pull request to \"METADATA\". - -"), - -("Base.Pkg","test","test() - - Run the tests for all installed packages ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its \"test/runtests.jl\" file - and test dependencies are specified in \"test/REQUIRE\". - - test(pkgs...) - - Run the tests for each package in \"pkgs\" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its \"test/runtests.jl\" file - and test dependencies are specified in \"test/REQUIRE\". - -"), - -("Base.Pkg","test","test() - - Run the tests for all installed packages ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its \"test/runtests.jl\" file - and test dependencies are specified in \"test/REQUIRE\". - - test(pkgs...) - - Run the tests for each package in \"pkgs\" ensuring that each - package's test dependencies are installed for the duration of the - test. A package is tested by running its \"test/runtests.jl\" file - and test dependencies are specified in \"test/REQUIRE\". - -"), - -("Base","@profile","@profile() - - \"@profile \" runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. - -"), - -("Base.Profile","clear","clear() - - Clear any existing backtraces from the internal buffer. - -"), - -("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) - - Prints profiling results to \"io\" (by default, \"STDOUT\"). If you - do not supply a \"data\" vector, the internal buffer of accumulated - backtraces will be used. \"format\" can be \":tree\" or \":flat\". - If \"C==true\", backtraces from C and Fortran code are shown. - \"combine==true\" merges instruction pointers that correspond to - the same line of code. \"cols\" controls the width of the display. - - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - - Prints profiling results to \"io\". This variant is used to examine - results exported by a previous call to \"retrieve()\". Supply the - vector \"data\" of backtraces and a dictionary \"lidict\" of line - information. - -"), - -("Base.Profile","print","print([io::IO = STDOUT], [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) - - Prints profiling results to \"io\" (by default, \"STDOUT\"). If you - do not supply a \"data\" vector, the internal buffer of accumulated - backtraces will be used. \"format\" can be \":tree\" or \":flat\". - If \"C==true\", backtraces from C and Fortran code are shown. - \"combine==true\" merges instruction pointers that correspond to - the same line of code. \"cols\" controls the width of the display. - - print([io::IO = STDOUT], data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) - - Prints profiling results to \"io\". This variant is used to examine - results exported by a previous call to \"retrieve()\". Supply the - vector \"data\" of backtraces and a dictionary \"lidict\" of line - information. - -"), - -("Base.Profile","init","init(; n::Integer, delay::Float64) - - Configure the \"delay\" between backtraces (measured in seconds), - and the number \"n\" of instruction pointers that may be stored. - Each instruction pointer corresponds to a single line of code; - backtraces generally consist of a long list of instruction - pointers. Default settings can be obtained by calling this function - with no arguments, and each can be set independently using keywords - or in the order \"(n, delay)\". - -"), - -("Base.Profile","fetch","fetch() -> data - - Returns a reference to the internal buffer of backtraces. Note that - subsequent operations, like \"clear()\", can affect \"data\" unless - you first make a copy. Note that the values in \"data\" have - meaning only on this machine in the current session, because it - depends on the exact memory addresses used in JIT-compiling. This - function is primarily for internal use; \"retrieve()\" may be a - better choice for most users. - -"), - -("Base.Profile","retrieve","retrieve() -> data, lidict - - \"Exports\" profiling results in a portable format, returning the - set of all backtraces (\"data\") and a dictionary that maps the - (session-specific) instruction pointers in \"data\" to \"LineInfo\" - values that store the file name, function name, and line number. - This function allows you to save profiling results for future - analysis. - -"), - -("Base.Profile","callers","callers(funcname[, data, lidict][, filename=][, linerange=]) -> Vector{Tuple{count, linfo}} - - Given a previous profiling run, determine who called a particular - function. Supplying the filename (and optionally, range of line - numbers over which the function is defined) allows you to - disambiguate an overloaded method. The returned value is a vector - containing a count of the number of calls and line information - about the caller. One can optionally supply backtrace data - obtained from \"retrieve()\"; otherwise, the current internal - profile buffer is used. - -"), - -("Base.Profile","clear_malloc_data","clear_malloc_data() - - Clears any stored memory allocation data when running julia with \" - –track-allocation\". Execute the command(s) you want to test (to - force JIT-compilation), then call \"clear_malloc_data()\". Then - execute your command(s) again, quit Julia, and examine the - resulting \">>*<<.mem\" files. - -"), - - -("Base","sort!","sort!(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the vector \"v\" in place. \"QuickSort\" is used by default - for numeric arrays while \"MergeSort\" is used for other arrays. - You can specify an algorithm to use via the \"alg\" keyword (see - Sorting Algorithms for available algorithms). The \"by\" keyword - lets you provide a function that will be applied to each element - before comparison; the \"lt\" keyword allows providing a custom - \"less than\" function; use \"rev=true\" to reverse the sorting - order. These options are independent and can be used together in - all possible combinations: if both \"by\" and \"lt\" are specified, - the \"lt\" function is applied to the result of the \"by\" - function; \"rev=true\" reverses whatever ordering specified via the - \"by\" and \"lt\" keywords. - -"), - -("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Variant of \"sort!\" that returns a sorted copy of \"v\" leaving - \"v\" itself unmodified. - - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort a multidimensional array \"A\" along the given dimension. - -"), - -("Base","sort","sort(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Variant of \"sort!\" that returns a sorted copy of \"v\" leaving - \"v\" itself unmodified. - - sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort a multidimensional array \"A\" along the given dimension. - -"), - -("Base","sortperm","sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) - - Return a permutation vector of indices of \"v\" that puts it in - sorted order. Specify \"alg\" to choose a particular sorting - algorithm (see Sorting Algorithms). \"MergeSort\" is used by - default, and since it is stable, the resulting permutation will be - the lexicographically first one that puts the input array into - sorted order – i.e. indices of equal elements appear in ascending - order. If you choose a non-stable sorting algorithm such as - \"QuickSort\", a different permutation that puts the array into - order may be returned. The order is specified using the same - keywords as \"sort!\". - - See also \"sortperm!()\" - -"), - -("Base","sortperm!","sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - - Like \"sortperm\", but accepts a preallocated index vector \"ix\". - If \"initialized\" is \"false\" (the default), ix is initialized to - contain the values \"1:length(v)\". - - See also \"sortperm()\" - -"), - -("Base","sortrows","sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the rows of matrix \"A\" lexicographically. - -"), - -("Base","sortcols","sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) - - Sort the columns of matrix \"A\" lexicographically. - -"), - -("Base","issorted","issorted(v, [by=,] [lt=,] [rev=false]) - - Test whether a vector is in sorted order. The \"by\", \"lt\" and - \"rev\" keywords modify what order is considered to be sorted just - as they do for \"sort\". - -"), - -("Base","searchsorted","searchsorted(a, x, [by=,] [lt=,] [rev=false]) - - Returns the range of indices of \"a\" which compare as equal to - \"x\" according to the order specified by the \"by\", \"lt\" and - \"rev\" keywords, assuming that \"a\" is already sorted in that - order. Returns an empty range located at the insertion point if - \"a\" does not contain values equal to \"x\". - -"), - -("Base","searchsortedfirst","searchsortedfirst(a, x, [by=,] [lt=,] [rev=false]) - - Returns the index of the first value in \"a\" greater than or equal - to \"x\", according to the specified order. Returns \"length(a)+1\" - if \"x\" is greater than all values in \"a\". - -"), - -("Base","searchsortedlast","searchsortedlast(a, x, [by=,] [lt=,] [rev=false]) - - Returns the index of the last value in \"a\" less than or equal to - \"x\", according to the specified order. Returns \"0\" if \"x\" is - less than all values in \"a\". - -"), - -("Base","select!","select!(v, k, [by=,] [lt=,] [rev=false]) - - Partially sort the vector \"v\" in place, according to the order - specified by \"by\", \"lt\" and \"rev\" so that the value at index - \"k\" (or range of adjacent values if \"k\" is a range) occurs at - the position where it would appear if the array were fully sorted - via a non-stable algorithm. If \"k\" is a single index, that value - is returned; if \"k\" is a range, an array of values at those - indices is returned. Note that \"select!\" does not fully sort the - input array. - -"), - -("Base","select","select(v, k, [by=,] [lt=,] [rev=false]) - - Variant of \"select!\" which copies \"v\" before partially sorting - it, thereby returning the same thing as \"select!\" but leaving - \"v\" unmodified. - -"), - -("Base","length","length(A) -> Integer - - Returns the number of elements in A - - length(collection) -> Integer - - For ordered, indexable collections, the maximum index \"i\" for - which \"getindex(collection, i)\" is valid. For unordered - collections, the number of elements. - - length(s) - - The number of characters in string \"s\". - -"), - -("Base","sizeof","sizeof(type) - - Size, in bytes, of the canonical binary representation of the given - type, if any. - - sizeof(s::AbstractString) - - The number of bytes in string \"s\". - -"), - -("Base","*","*(A, B) - - Matrix multiplication - - *(x, y...) - - Multiplication operator. \"x*y*z*...\" calls this function with all - arguments, i.e. \">>*<<(x, y, z, ...)\". - - *(s, t) - - Concatenate strings. The \"*\" operator is an alias to this - function. - - julia> \"Hello \" * \"world\" - \"Hello world\" - - - julia> \"Hello \" * \"world\" - \"Hello world\" - -"), - -("Base","^","^(x, y) - - Exponentiation operator. - - ^(s, n) - - Repeat \"n\" times the string \"s\". The \"^\" operator is an alias - to this function. - - julia> \"Test \"^3 - \"Test Test Test \" - -"), - -("Base","string","string(xs...) - - Create a string from any values using the \"print\" function. - -"), - -("Base","repr","repr(x) - - Create a string from any value using the \"showall\" function. - -"), - -("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) - - Create a string from the address of a C (0-terminated) string - encoded in ASCII or UTF-8. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - - bytestring(s) - - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. - -"), - -("Base","bytestring","bytestring(::Ptr{UInt8}[, length]) - - Create a string from the address of a C (0-terminated) string - encoded in ASCII or UTF-8. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - - bytestring(s) - - Convert a string to a contiguous byte array representation - appropriate for passing it to C functions. The string will be - encoded as either ASCII or UTF-8. - -"), - -("Base","ascii","ascii(::Array{UInt8, 1}) - - Create an ASCII string from a byte array. - - ascii(s) - - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). - - ascii(::Ptr{UInt8}[, length]) - - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - -"), - -("Base","ascii","ascii(::Array{UInt8, 1}) - - Create an ASCII string from a byte array. - - ascii(s) - - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). - - ascii(::Ptr{UInt8}[, length]) - - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - -"), - -("Base","ascii","ascii(::Array{UInt8, 1}) - - Create an ASCII string from a byte array. - - ascii(s) - - Convert a string to a contiguous ASCII string (all characters must - be valid ASCII characters). - - ascii(::Ptr{UInt8}[, length]) - - Create an ASCII string from the address of a C (0-terminated) - string encoded in ASCII. A copy is made; the ptr can be safely - freed. If \"length\" is specified, the string does not have to be - 0-terminated. - -"), - -("Base","utf8","utf8(::Array{UInt8, 1}) - - Create a UTF-8 string from a byte array. - - utf8(::Ptr{UInt8}[, length]) - - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - \"length\" is specified, the string does not have to be - 0-terminated. - - utf8(s) - - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). - -"), - -("Base","utf8","utf8(::Array{UInt8, 1}) - - Create a UTF-8 string from a byte array. - - utf8(::Ptr{UInt8}[, length]) - - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - \"length\" is specified, the string does not have to be - 0-terminated. - - utf8(s) - - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). - -"), - -("Base","utf8","utf8(::Array{UInt8, 1}) - - Create a UTF-8 string from a byte array. - - utf8(::Ptr{UInt8}[, length]) - - Create a UTF-8 string from the address of a C (0-terminated) string - encoded in UTF-8. A copy is made; the ptr can be safely freed. If - \"length\" is specified, the string does not have to be - 0-terminated. - - utf8(s) - - Convert a string to a contiguous UTF-8 string (all characters must - be valid UTF-8 characters). - -"), - -("Base","normalize_string","normalize_string(s, normalform::Symbol) - - Normalize the string \"s\" according to one of the four \"normal - forms\" of the Unicode standard: \"normalform\" can be \":NFC\", - \":NFD\", \":NFKC\", or \":NFKD\". Normal forms C (canonical - composition) and D (canonical decomposition) convert different - visually identical representations of the same abstract string into - a single canonical form, with form C being more compact. Normal - forms KC and KD additionally canonicalize \"compatibility - equivalents\": they convert characters that are abstractly similar - but visually distinct into a single canonical choice (e.g. they - expand ligatures into the individual characters), with form KC - being more compact. - - Alternatively, finer control and additional transformations may be - be obtained by calling *normalize_string(s; keywords...)*, where - any number of the following boolean keywords options (which all - default to \"false\" except for \"compose\") are specified: - - * \"compose=false\": do not perform canonical composition - - * \"decompose=true\": do canonical decomposition instead of - canonical composition (\"compose=true\" is ignored if present) - - * \"compat=true\": compatibility equivalents are canonicalized - - * \"casefold=true\": perform Unicode case folding, e.g. for - case- insensitive string comparison - - * \"newline2lf=true\", \"newline2ls=true\", or - \"newline2ps=true\": convert various newline sequences (LF, - CRLF, CR, NEL) into a linefeed (LF), line-separation (LS), - or paragraph-separation (PS) character, respectively - - * \"stripmark=true\": strip diacritical marks (e.g. accents) - - * \"stripignore=true\": strip Unicode's \"default ignorable\" - characters (e.g. the soft hyphen or the left-to-right marker) - - * \"stripcc=true\": strip control characters; horizontal tabs - and form feeds are converted to spaces; newlines are also - converted to spaces unless a newline-conversion flag was - specified - - * \"rejectna=true\": throw an error if unassigned code points - are found - - * \"stable=true\": enforce Unicode Versioning Stability - - For example, NFKC corresponds to the options \"compose=true, - compat=true, stable=true\". - -"), - -("Base","graphemes","graphemes(s) -> iterator over substrings of s - - Returns an iterator over substrings of \"s\" that correspond to the - extended graphemes in the string, as defined by Unicode UAX #29. - (Roughly, these are what users would perceive as single characters, - even though they may contain more than one codepoint; for example a - letter combined with an accent mark is a single grapheme.) - -"), - -("Base","isvalid","isvalid(value) -> Bool - - Returns true if the given value is valid for its type, which - currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" - - isvalid(T, value) -> Bool - - Returns true if the given value is valid for that type. Types - currently can be \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of - type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and - \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for - \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values - for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or - \"Vector{UInt32}\" - - isvalid(str, i) - - Tells whether index \"i\" is valid for the given string - -"), - -("Base","isvalid","isvalid(value) -> Bool - - Returns true if the given value is valid for its type, which - currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" - - isvalid(T, value) -> Bool - - Returns true if the given value is valid for that type. Types - currently can be \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of - type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and - \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for - \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values - for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or - \"Vector{UInt32}\" - - isvalid(str, i) - - Tells whether index \"i\" is valid for the given string - -"), - -("Base","is_assigned_char","is_assigned_char(c) -> Bool - - Returns true if the given char or integer is an assigned Unicode - code point. - -"), - -("Base","ismatch","ismatch(r::Regex, s::AbstractString) -> Bool - - Test whether a string contains a match of the given regular - expression. - -"), - -("Base","match","match(r::Regex, s::AbstractString[, idx::Integer[, addopts]]) - - Search for the first match of the regular expression \"r\" in \"s\" - and return a RegexMatch object containing the match, or nothing if - the match failed. The matching substring can be retrieved by - accessing \"m.match\" and the captured sequences can be retrieved - by accessing \"m.captures\" The optional \"idx\" argument specifies - an index at which to start the search. - -"), - -("Base","eachmatch","eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false]) - - Search for all matches of a the regular expression \"r\" in \"s\" - and return a iterator over the matches. If overlap is true, the - matching sequences are allowed to overlap indices in the original - string, otherwise they must be from distinct character ranges. - -"), - -("Base","matchall","matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} - - Return a vector of the matching substrings from eachmatch. - -"), - -("Base","lpad","lpad(string, n, p) - - Make a string at least \"n\" columns wide when printed, by padding - on the left with copies of \"p\". - -"), - -("Base","rpad","rpad(string, n, p) - - Make a string at least \"n\" columns wide when printed, by padding - on the right with copies of \"p\". - -"), - -("Base","search","search(string, chars[, start]) - - Search for the first occurrence of the given characters within the - given string. The second argument may be a single character, a - vector or a set of characters, a string, or a regular expression - (though regular expressions are only allowed on contiguous strings, - such as ASCII or UTF-8 strings). The third argument optionally - specifies a starting index. The return value is a range of indexes - where the matching sequence is found, such that \"s[search(s,x)] == - x\": - - \"search(string, \"substring\")\" = \"start:end\" such that - \"string[start:end] == \"substring\"\", or \"0:-1\" if unmatched. - - \"search(string, 'c')\" = \"index\" such that - \"string[index] == 'c'\", or \"0\" if unmatched. - -"), - -("Base","rsearch","rsearch(string, chars[, start]) - - Similar to \"search\", but returning the last occurrence of the - given characters within the given string, searching in reverse from - \"start\". - -"), - -("Base","searchindex","searchindex(string, substring[, start]) - - Similar to \"search\", but return only the start index at which the - substring is found, or 0 if it is not. - -"), - -("Base","rsearchindex","rsearchindex(string, substring[, start]) - - Similar to \"rsearch\", but return only the start index at which - the substring is found, or 0 if it is not. - -"), - -("Base","contains","contains(haystack, needle) - - Determine whether the second argument is a substring of the first. - -"), - -("Base","replace","replace(string, pat, r[, n]) - - Search for the given pattern \"pat\", and replace each occurrence - with \"r\". If \"n\" is provided, replace at most \"n\" - occurrences. As with search, the second argument may be a single - character, a vector or a set of characters, a string, or a regular - expression. If \"r\" is a function, each occurrence is replaced - with \"r(s)\" where \"s\" is the matched substring. - -"), - -("Base","split","split(string, [chars]; limit=0, keep=true) - - Return an array of substrings by splitting the given string on - occurrences of the given character delimiters, which may be - specified in any of the formats allowed by \"search\"'s second - argument (i.e. a single character, collection of characters, - string, or regular expression). If \"chars\" is omitted, it - defaults to the set of all space characters, and \"keep\" is taken - to be false. The two keyword arguments are optional: they are are a - maximum size for the result and a flag determining whether empty - fields should be kept in the result. - -"), - -("Base","rsplit","rsplit(string, [chars]; limit=0, keep=true) - - Similar to \"split\", but starting from the end of the string. - -"), - -("Base","strip","strip(string[, chars]) - - Return \"string\" with any leading and trailing whitespace removed. - If \"chars\" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. - -"), - -("Base","lstrip","lstrip(string[, chars]) - - Return \"string\" with any leading whitespace removed. If \"chars\" - (a character, or vector or set of characters) is provided, instead - remove characters contained in it. - -"), - -("Base","rstrip","rstrip(string[, chars]) - - Return \"string\" with any trailing whitespace removed. If - \"chars\" (a character, or vector or set of characters) is - provided, instead remove characters contained in it. - -"), - -("Base","startswith","startswith(string, prefix | chars) - - Returns \"true\" if \"string\" starts with \"prefix\". If the - second argument is a vector or set of characters, tests whether the - first character of \"string\" belongs to that set. - -"), - -("Base","endswith","endswith(string, suffix | chars) - - Returns \"true\" if \"string\" ends with \"suffix\". If the second - argument is a vector or set of characters, tests whether the last - character of \"string\" belongs to that set. - -"), - -("Base","uppercase","uppercase(string) - - Returns \"string\" with all characters converted to uppercase. - -"), - -("Base","lowercase","lowercase(string) - - Returns \"string\" with all characters converted to lowercase. - -"), - -("Base","ucfirst","ucfirst(string) - - Returns \"string\" with the first character converted to uppercase. - -"), - -("Base","lcfirst","lcfirst(string) - - Returns \"string\" with the first character converted to lowercase. - -"), - -("Base","join","join(strings, delim[, last]) - - Join an array of \"strings\" into a single string, inserting the - given delimiter between adjacent strings. If \"last\" is given, it - will be used instead of \"delim\" between the last two strings. For - example, \"join([\"apples\", \"bananas\", \"pineapples\"], \", \", - \" and \") == \"apples, bananas and pineapples\"\". - - \"strings\" can be any iterable over elements \"x\" which are - convertible to strings via \"print(io::IOBuffer, x)\". - -"), - -("Base","chop","chop(string) - - Remove the last character from a string - -"), - -("Base","chomp","chomp(string) - - Remove a trailing newline from a string - -"), - -("Base","ind2chr","ind2chr(string, i) - - Convert a byte index to a character index - -"), - -("Base","chr2ind","chr2ind(string, i) - - Convert a character index to a byte index - -"), - -("Base","isvalid","isvalid(value) -> Bool - - Returns true if the given value is valid for its type, which - currently can be one of \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" - - isvalid(T, value) -> Bool - - Returns true if the given value is valid for that type. Types - currently can be \"Char\", \"ASCIIString\", \"UTF8String\", - \"UTF16String\", or \"UTF32String\" Values for \"Char\" can be of - type \"Char\" or \"UInt32\" Values for \"ASCIIString\" and - \"UTF8String\" can be of that type, or \"Vector{UInt8}\" Values for - \"UTF16String\" can be \"UTF16String\" or \"Vector{UInt16}\" Values - for \"UTF32String\" can be \"UTF32String\", \"Vector{Char}\" or - \"Vector{UInt32}\" - - isvalid(str, i) - - Tells whether index \"i\" is valid for the given string - -"), - -("Base","nextind","nextind(str, i) - - Get the next valid string index after \"i\". Returns a value - greater than \"endof(str)\" at or after the end of the string. - -"), - -("Base","prevind","prevind(str, i) - - Get the previous valid string index before \"i\". Returns a value - less than \"1\" at the beginning of the string. - -"), - -("Base","randstring","randstring([rng], len=8) - - Create a random ASCII string of length \"len\", consisting of - upper- and lower-case letters and the digits 0-9. The optional - \"rng\" argument specifies a random number generator, see *Random - Numbers*. - -"), - -("Base","charwidth","charwidth(c) - - Gives the number of columns needed to print a character. - -"), - -("Base","strwidth","strwidth(s) - - Gives the number of columns needed to print a string. - -"), - -("Base","isalnum","isalnum(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is alphanumeric, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter or - Number, i.e. a character whose category code begins with 'L' or - 'N'. - -"), - -("Base","isalpha","isalpha(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is alphabetic, or whether this is true - for all elements of a string. A character is classified as - alphabetic if it belongs to the Unicode general category Letter, - i.e. a character whose category code begins with 'L'. - -"), - -("Base","isascii","isascii(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character belongs to the ASCII character set, or - whether this is true for all elements of a string. - -"), - -("Base","iscntrl","iscntrl(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a control character, or whether this - is true for all elements of a string. Control characters are the - non-printing characters of the Latin-1 subset of Unicode. - -"), - -("Base","isdigit","isdigit(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a numeric digit (0-9), or whether this - is true for all elements of a string. - -"), - -("Base","isgraph","isgraph(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is printable, and not a space, or whether - this is true for all elements of a string. Any character that - would cause a printer to use ink should be classified with - isgraph(c)==true. - -"), - -("Base","islower","islower(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a lowercase letter, or whether this is - true for all elements of a string. A character is classified as - lowercase if it belongs to Unicode category Ll, Letter: Lowercase. - -"), - -("Base","isnumber","isnumber(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is numeric, or whether this is true for - all elements of a string. A character is classified as numeric if - it belongs to the Unicode general category Number, i.e. a character - whose category code begins with 'N'. - -"), - -("Base","isprint","isprint(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is printable, including spaces, but not a - control character. For strings, tests whether this is true for all - elements of the string. - -"), - -("Base","ispunct","ispunct(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character belongs to the Unicode general category - Punctuation, i.e. a character whose category code begins with 'P'. - For strings, tests whether this is true for all elements of the - string. - -"), - -("Base","isspace","isspace(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is any whitespace character. Includes - ASCII characters 't', 'n', 'v', 'f', 'r', and ' ', Latin-1 - character U+0085, and characters in Unicode category Zs. For - strings, tests whether this is true for all elements of the - string. - -"), - -("Base","isupper","isupper(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is an uppercase letter, or whether this - is true for all elements of a string. A character is classified - as uppercase if it belongs to Unicode category Lu, Letter: - Uppercase, or Lt, Letter: Titlecase. - -"), - -("Base","isxdigit","isxdigit(c::Union{Char, AbstractString}) -> Bool - - Tests whether a character is a valid hexadecimal digit, or whether - this is true for all elements of a string. - -"), - -("Base","symbol","symbol(x...) -> Symbol - - Create a \"Symbol\" by concatenating the string representations of - the arguments together. - -"), - -("Base","escape_string","escape_string(str::AbstractString) -> AbstractString - - General escaping of traditional C and Unicode escape sequences. See - \"print_escaped()\" for more general escaping. - -"), - -("Base","unescape_string","unescape_string(s::AbstractString) -> AbstractString - - General unescaping of traditional C and Unicode escape sequences. - Reverse of \"escape_string()\". See also \"print_unescaped()\". - -"), - -("Base","utf16","utf16(s) - - Create a UTF-16 string from a byte array, array of \"UInt16\", or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) - - Note that the resulting \"UTF16String\" data is terminated by the - NUL codepoint (16-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf16(s)* conversion function. If you have a \"UInt16\" array - \"A\" that is already NUL-terminated valid UTF-16 data, then you - can instead use *UTF16String(A)`* to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. - - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If \"length\" is - specified, the string does not have to be NUL-terminated. - -"), - -("Base","utf16","utf16(s) - - Create a UTF-16 string from a byte array, array of \"UInt16\", or - any other string type. (Data must be valid UTF-16. Conversions of - byte arrays check for a byte-order marker in the first two bytes, - and do not include it in the resulting string.) - - Note that the resulting \"UTF16String\" data is terminated by the - NUL codepoint (16-bit zero), which is not treated as a character in - the string (so that it is mostly invisible in Julia); this allows - the string to be passed directly to external functions requiring - NUL-terminated data. This NUL is appended automatically by the - *utf16(s)* conversion function. If you have a \"UInt16\" array - \"A\" that is already NUL-terminated valid UTF-16 data, then you - can instead use *UTF16String(A)`* to construct the string without - making a copy of the data and treating the NUL as a terminator - rather than as part of the string. - - utf16(::Union{Ptr{UInt16}, Ptr{Int16}}[, length]) - - Create a string from the address of a NUL-terminated UTF-16 string. - A copy is made; the pointer can be safely freed. If \"length\" is - specified, the string does not have to be NUL-terminated. - -"), - -("Base","wstring","wstring(s) - - This is a synonym for either \"utf32(s)\" or \"utf16(s)\", - depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. - The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is - also provided. - -"), - -("Base","wstring","wstring(s) - - This is a synonym for either \"utf32(s)\" or \"utf16(s)\", - depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. - The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is - also provided. - -"), - -("Base","wstring","wstring(s) - - This is a synonym for either \"utf32(s)\" or \"utf16(s)\", - depending on whether \"Cwchar_t\" is 32 or 16 bits, respectively. - The synonym \"WString\" for \"UTF32String\" or \"UTF16String\" is - also provided. - -"), - -("Base","runtests","runtests([tests=[\"all\"][, numcores=iceil(CPU_CORES/2)]]) - - Run the Julia unit tests listed in \"tests\", which can be either a - string or an array of strings, using \"numcores\" processors. (not - exported) - -"), - -("Base.Test","@test","@test(ex) - - Test the expression \"ex\" and calls the current handler to handle - the result. - -"), - -("Base.Test","@test_throws","@test_throws(extype, ex) - - Test that the expression \"ex\" throws an exception of type - \"extype\" and calls the current handler to handle the result. - -"), - -("Base.Test","@test_approx_eq","@test_approx_eq(a, b) - - Test two floating point numbers \"a\" and \"b\" for equality taking - in account small numerical errors. - -"), - -("Base.Test","@test_approx_eq_eps","@test_approx_eq_eps(a, b, tol) - - Test two floating point numbers \"a\" and \"b\" for equality taking - in account a margin of tolerance given by \"tol\". - -"), - -("Base.Test","with_handler","with_handler(f, handler) - - Run the function \"f\" using the \"handler\" as the handler. - -"), - - -]