From b95f63f9689c0557c7b6b3875e8abe7facad3f56 Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Sat, 27 Jun 2015 17:33:17 -0400 Subject: [PATCH] first conversion from docs->rst --- doc/stdlib/arrays.rst | 2466 ++++++++++++++---- doc/stdlib/base.rst | 3093 +++++++++++++++++----- doc/stdlib/c.rst | 297 ++- doc/stdlib/collections.rst | 2487 +++++++++++++----- doc/stdlib/dates.rst | 885 +++++-- doc/stdlib/file.rst | 846 +++++- doc/stdlib/io-network.rst | 2126 +++++++++++---- doc/stdlib/libc.rst | 204 +- doc/stdlib/libdl.rst | 99 +- doc/stdlib/linalg.rst | 2723 +++++++++++++++----- doc/stdlib/math.rst | 4982 ++++++++++++++++++++++++++++-------- doc/stdlib/numbers.rst | 982 +++++-- doc/stdlib/parallel.rst | 912 +++++-- doc/stdlib/pkg.rst | 408 ++- doc/stdlib/profile.rst | 167 +- doc/stdlib/sort.rst | 209 +- doc/stdlib/strings.rst | 1130 ++++++-- doc/stdlib/test.rst | 87 +- 18 files changed, 19229 insertions(+), 4874 deletions(-) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 33614d302674f..13b137c3086d4 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -9,57 +9,83 @@ Basic functions .. function:: ndims(A) -> Integer - Returns the number of dimensions of A +:: + + ndims(A) -> Integer + +Returns the number of dimensions of A + + +:: + + 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.:: +:: + + size(A[, dim...]) - 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> 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) - Tests whether A or its elements are of type T +:: + + iseltype(A, T) + +Tests whether A or its elements are of type 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``. + + +:: + + 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: + + +:: + + 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,706 +104,2268 @@ 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. +:: + + 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(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 +:: + + conj!(A) + +Convert an array to its complex conjugate in-place + + +:: + + 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 +:: + + stride(A, k) + +Returns the distance in memory (in number of elements) between adjacent elements in dimension k + + +:: + + 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 +:: + + strides(A) + +Returns a tuple of the memory strides in each dimension + + +:: + + 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`` +:: + + ind2sub(a, index) -> subscripts + +Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` + + +:: + + ind2sub(a, index) -> subscripts + +Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` - **Example** ``i, j, ... = ind2sub(size(A), indmax(A))`` provides the indices of the maximum element .. 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 + ind2sub(a, index) -> subscripts - The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts +Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` -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. + ind2sub(a, index) -> subscripts -.. function:: getindex(type[, elements...]) +Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` - 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,...]``. -.. function:: cell(dims) +.. function:: sub2ind(dims, i, j, k...) -> index - Construct an uninitialized cell array (heterogeneous array). ``dims`` can be either a tuple or a series of integer arguments. -.. function:: zeros(type, dims) +:: - Create an array of all zeros of specified type. The type defaults to Float64 if not specified. + sub2ind(dims, i, j, k...) -> index -.. function:: zeros(A) +The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts - 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. + sub2ind(dims, i, j, k...) -> index -.. function:: ones(A) +The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts - Create an array of all ones with the same element type and shape as A. -.. function:: trues(dims) +Constructors +------------ - Create a ``BitArray`` with all values set to true +.. function:: Array(dims) -.. function:: falses(dims) +:: - Create a ``BitArray`` with all values set to false + Array(dims) -.. function:: fill(x, 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. - 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) + Array(dims) - 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. +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:: 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:: getindex(type[, elements...]) -.. 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. + getindex(collection, key...) -.. function:: reinterpret(type, A) +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, ...)``. - 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(n) +:: - n-by-n identity matrix + getindex(collection, key...) -.. function:: eye(m, n) +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, ...)``. - m-by-n identity matrix -.. function:: eye(A) +.. function:: cell(dims) - Constructs an identity matrix of the same dimensions and type as ``A``. +:: -.. function:: linspace(start, stop, n=100) + cell(dims) - Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. +Construct an uninitialized cell array (heterogeneous array). -.. function:: logspace(start, stop, n=50) - Construct a vector of ``n`` logarithmically spaced numbers from ``10^start`` to ``10^stop``. +:: -Mathematical operators and functions ------------------------------------- + cell(dims) -All mathematical operations and functions are supported for arrays +Construct an uninitialized cell array (heterogeneous array). -.. 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. +.. function:: zeros(type, dims) -.. 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)``. + zeros(A) -.. function:: bitbroadcast(f, As...) +Create an array of all zeros with the same element type and shape as A. - 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)``. + zeros(A) -.. function:: broadcast!_function(f) +Create an array of all zeros with the same element type and shape as A. - Like ``broadcast_function``, but for ``broadcast!``. -Indexing, Assignment, and Concatenation ---------------------------------------- +.. function:: zeros(A) -.. 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. + zeros(A) -.. function:: sub(A, inds...) +Create an array of all zeros with the same element type and shape as A. - 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. -.. 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 + zeros(A) -.. function:: parentindexes(A) +Create an array of all zeros with the same element type and shape as A. - From an array view ``A``, returns the corresponding indexes in the parent -.. function:: slicedim(A, d, i) +.. function:: ones(type, dims) - 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...) + ones(A) - Returns a view of array ``A`` with the given indices like :func:`sub`, but drops all dimensions indexed with scalars. +Create an array of all ones with the same element type and shape as A. -.. function:: setindex!(A, X, inds...) - Store values from array ``X`` within some subset of ``A`` as specified by ``inds``. +:: -.. function:: broadcast_getindex(A, inds...) + ones(A) - 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. +Create an array of all ones with the same element type and shape as A. -.. 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:: ones(A) -.. 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. + ones(A) -.. function:: vcat(A...) +Create an array of all ones with the same element type and shape as A. - Concatenate along dimension 1 -.. function:: hcat(A...) +:: - Concatenate along dimension 2 + ones(A) -.. function:: hvcat(rows::Tuple{Vararg{Int}}, values...) +Create an array of all ones with the same element type and shape as A. - 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:: trues(dims) -.. function:: flipdim(A, d) +:: - Reverse ``A`` in dimension ``d``. + trues(dims) -.. function:: circshift(A,shifts) +Create a ``BitArray`` with all values set to true - 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. + trues(dims) -.. function:: find(f,A) +Create a ``BitArray`` with all values set to true - Return a vector of the linear indexes of ``A`` where ``f`` returns true. -.. function:: findn(A) +.. function:: falses(dims) - 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) + falses(dims) - 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. +Create a ``BitArray`` with all values set to false -.. function:: findfirst(A) - Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). +:: -.. function:: findfirst(A,v) + falses(dims) - Return the index of the first element equal to ``v`` in ``A``. +Create a ``BitArray`` with all values set to false -.. function:: findfirst(predicate, A) - Return the index of the first element of ``A`` for which ``predicate`` returns true. +.. function:: fill(x, dims) -.. function:: findlast(A) +:: - Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + fill(x, dims) -.. function:: findlast(A, v) +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. - Return the index of the last element equal to ``v`` in ``A``. -.. function:: findlast(predicate, A) +:: - Return the index of the last element of ``A`` for which ``predicate`` returns true. + fill(x, dims) -.. function:: findnext(A, i) +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. - Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. -.. function:: findnext(predicate, A, i) +.. function:: fill!(A, x) - Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. +:: -.. function:: findnext(A, v, i) + fill!(A, x) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. +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:: findprev(A, i) - Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. +:: -.. function:: findprev(predicate, A, i) + fill!(A, x) - Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. +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:: findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. +.. function:: reshape(A, dims) -.. 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])``. + reshape(A, dims) -.. function:: ipermutedims(A, perm) +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. - Like :func:`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. + reshape(A, dims) -.. function:: squeeze(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. - 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 +.. function:: similar(array, element_type, dims) - Vectorize an array using column-major convention. +:: -.. function:: promote_shape(s1, s2) + similar(array, element_type, dims) - Check two array shapes for compatibility, allowing trailing singleton dimensions, - and return whichever shape has more dimensions. +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:: checkbounds(array, indexes...) - Throw an error if the specified indexes are not in bounds for the given array. +:: -.. function:: randsubseq(A, p) -> Vector + similar(array, element_type, dims) - 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``. +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:: randsubseq!(S, A, p) - Like ``randsubseq``, but the results are stored in ``S`` (which is - resized as needed). +.. function:: reinterpret(type, A) +:: -Array functions ---------------- + reinterpret(type, A) -.. function:: cumprod(A, [dim]) +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. - 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). -.. function:: cumprod!(B, A, [dim]) +:: - Cumulative product of ``A`` along a dimension, storing the result in ``B``. - The dimension defaults to 1. + reinterpret(type, A) -.. function:: cumsum(A, [dim]) +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. - 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). -.. function:: cumsum!(B, A, [dim]) +.. function:: eye(n) - Cumulative sum of ``A`` along a dimension, storing the result in ``B``. - The dimension defaults to 1. +:: -.. function:: cumsum_kbn(A, [dim]) + eye(A) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. - The dimension defaults to 1. +Constructs an identity matrix of the same dimensions and type as -.. function:: cummin(A, [dim]) - Cumulative minimum along a dimension. - The dimension defaults to 1. +:: -.. function:: cummax(A, [dim]) + eye(A) - Cumulative maximum along a dimension. - The dimension defaults to 1. +Constructs an identity matrix of the same dimensions and type as -.. function:: diff(A, [dim]) - Finite difference operator of matrix or vector. +.. function:: eye(m, n) -.. function:: gradient(F, [h]) +:: - Compute differences along vector ``F``, using ``h`` as the spacing between points. - The default spacing is one. + eye(A) -.. function:: rot180(A) +Constructs an identity matrix of the same dimensions and type as - Rotate matrix ``A`` 180 degrees. -.. 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``. + eye(A) -.. function:: rotl90(A) +Constructs an identity matrix of the same dimensions and type as - Rotate matrix ``A`` left 90 degrees. -.. function:: rotl90(A, k) +.. function:: eye(A) - 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) + eye(A) - Rotate matrix ``A`` right 90 degrees. +Constructs an identity matrix of the same dimensions and type as -.. 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]) + eye(A) - 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. +Constructs an identity matrix of the same dimensions and type as - 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]) +.. function:: linspace(start, stop, n=100) - 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) + linspace(start, stop, n=100) - 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``. +Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. -.. 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) + linspace(start, stop, n=100) - Given a ``dims`` tuple of integers ``(m, n, ...)``, call ``f`` on all combinations of - integers in the ranges ``1:m``, ``1:n``, etc. +Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. - .. doctest:: - julia> cartesianmap(println, (2,2)) - 11 - 21 - 12 - 22 +.. function:: logspace(start, stop, n=50) -Combinatorics -------------- +:: -.. function:: nthperm(v, k) + logspace(start, stop, n=50) - Compute the kth lexicographic permutation of a vector. +Construct a vector of ``n`` logarithmically spaced numbers from -.. function:: nthperm(p) - Return the ``k`` that generated permutation ``p``. - Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``. +:: -.. function:: nthperm!(v, k) + logspace(start, stop, n=50) - In-place version of :func:`nthperm`. +Construct a vector of ``n`` logarithmically spaced numbers from -.. function:: randperm([rng,] n) - Construct a random permutation of length ``n``. The optional ``rng`` argument - specifies a random number generator, see :ref:`Random Numbers `. +Mathematical operators and functions +------------------------------------ -.. function:: invperm(v) +All mathematical operations and functions are supported for arrays - Return the inverse permutation of v. +.. function:: broadcast(f, As...) -.. function:: isperm(v) -> Bool +:: - Returns true if v is a valid permutation. + broadcast(f, As...) -.. function:: permute!(v, p) +Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results - 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) + broadcast(f, As...) - Like permute!, but the inverse of the given permutation is applied. +Broadcasts the arrays ``As`` to a common size by expanding singleton dimensions, and returns an array of the results -.. 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 - `. +.. function:: broadcast!(f, dest, As...) -.. function:: shuffle([rng,] v) +:: - Return a randomly permuted copy of ``v``. The optional ``rng`` argument - specifies a random number generator, see :ref:`Random Numbers - `. + broadcast!(f, dest, As...) -.. function:: shuffle!([rng,] v) +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 - In-place version of :func:`shuffle`. -.. function:: reverse(v [, start=1 [, stop=length(v) ]] ) +:: - Return a copy of ``v`` reversed from start to stop. + broadcast!(f, dest, As...) -.. function:: reverseind(v, i) +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 - 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 +.. function:: bitbroadcast(f, As...) - In-place version of :func:`reverse`. +:: -.. function:: combinations(array, n) + bitbroadcast(f, As...) - 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. +Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. -.. 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(n) + bitbroadcast(f, As...) - 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))``. +Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. -.. 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))``. +.. function:: broadcast_function(f) -.. 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))``. + broadcast_function(f) -.. function:: partitions(array, m) +Returns a function ``broadcast_f`` such that useful in the form ``const broadcast_f = broadcast_function(f)``. - 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 + broadcast_function(f) - Converts a numeric array to a packed boolean array +Returns a function ``broadcast_f`` such that useful in the form ``const broadcast_f = broadcast_function(f)``. -.. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} - Converts a packed boolean array to an array of booleans +.. function:: broadcast!_function(f) + +:: -.. function:: flipbits!(B::BitArray{N}) -> BitArray{N} + broadcast!_function(f) - Performs a bitwise not operation on B. See :ref:`~ operator <~>`. +Like ``broadcast_function``, but for ``broadcast!``. -.. 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``. +:: -.. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + broadcast!_function(f) - Performs a left rotation operation on B. +Like ``broadcast_function``, but for ``broadcast!``. -.. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation. +Indexing, Assignment, and Concatenation +--------------------------------------- -.. function:: ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} +.. function:: getindex(A, inds...) - Performs a right rotation operation on ``src`` and put the result into ``dest``. +:: -.. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + getindex(collection, key...) - Performs a right rotation operation on B. +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:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation. +:: -.. _stdlib-sparse: + getindex(collection, key...) -Sparse Matrices ---------------- +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, ...)``. -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:: sub(A, inds...) - 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. +:: -.. function:: sparsevec(I, V, [m, combine]) + sub(A, inds...) - 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. +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:: 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. +:: -.. function:: issparse(S) + sub(A, inds...) - Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. +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:: sparse(A) - Convert an AbstractMatrix ``A`` into a sparse matrix. +.. function:: parent(A) -.. 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. + parent(A) -.. function:: full(S) +Returns the ``parent array`` of an array view type (e.g., SubArray), or the array itself if it is not a view - Convert a sparse matrix ``S`` into a dense matrix. -.. function:: nnz(A) +:: - Returns the number of stored (filled) elements in a sparse matrix. + parent(A) -.. function:: spzeros(m,n) +Returns the ``parent array`` of an array view type (e.g., SubArray), or the array itself if it is not a view - 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) +.. function:: parentindexes(A) - 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]) + parentindexes(A) - 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``. +From an array view ``A``, returns the corresponding indexes in the parent -.. 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. +:: -.. function:: sprand([rng,] m,n,p [,rfn]) + parentindexes(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 :ref:`Random Numbers `. +From an array view ``A``, returns the corresponding indexes in the parent -.. 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. +.. function:: slicedim(A, d, i) -.. 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``. + slicedim(A, d, i) -.. function:: etree(A[, post]) +Return all the data of ``A`` where the index for dimension ``d`` equals ``i``. Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``. - 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. + slicedim(A, d, i) -.. function:: nonzeros(A) +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 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) +.. function:: slice(A, inds...) - 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)``. +:: + + slice(A, inds...) + +Returns a view of array ``A`` with the given indices like + + +:: + + slice(A, inds...) + +Returns a view of array ``A`` with the given indices like + + +.. function:: setindex!(A, X, 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, ...)``. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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 + + +:: + + vcat(A...) + +Concatenate along dimension 1 + + +.. function:: hcat(A...) + +:: + + hcat(A...) + +Concatenate along dimension 2 + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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) + +:: + + find(f, A) + +Return a vector of the linear indexes of ``A`` where ``f`` returns true. + + +:: + + 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. + + +:: + + 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``). + + +:: + + 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. + + +:: + + 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) + +:: + + findfirst(predicate, A) + +Return the index of the first element of ``A`` for which + + +:: + + findfirst(predicate, A) + +Return the index of the first element of ``A`` for which + + +.. function:: findfirst(A,v) + +:: + + findfirst(predicate, A) + +Return the index of the first element of ``A`` for which + + +:: + + 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 + + +:: + + findfirst(predicate, A) + +Return the index of the first element of ``A`` for which + + +.. function:: findlast(A) + +:: + + findlast(predicate, A) + +Return the index of the last element of ``A`` for which + + +:: + + findlast(predicate, A) + +Return the index of the last element of ``A`` for which + + +.. function:: findlast(A, v) + +:: + + findlast(predicate, A) + +Return the index of the last element of ``A`` for which + + +:: + + 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 + + +:: + + findlast(predicate, A) + +Return the index of the last element of ``A`` for which + + +.. function:: findnext(A, i) + +:: + + findnext(A, v, i) + +Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + + +:: + + findnext(A, v, i) + +Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + + +.. function:: findnext(predicate, A, i) + +:: + + findnext(A, v, i) + +Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + + +:: + + 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`` + + +:: + + findnext(A, v, i) + +Find the next index >= ``i`` of an element of ``A`` equal to ``v`` + + +.. function:: findprev(A, i) + +:: + + findprev(A, v, i) + +Find the previous index <= ``i`` of an element of ``A`` equal to + + +:: + + findprev(A, v, i) + +Find the previous index <= ``i`` of an element of ``A`` equal to + + +.. function:: findprev(predicate, A, i) + +:: + + findprev(A, v, i) + +Find the previous index <= ``i`` of an element of ``A`` equal to + + +:: + + 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 + + +:: + + 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])``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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). + + +:: + + randsubseq!(S, A, p) + +Like ``randsubseq``, but the results are stored in ``S`` (which is resized as needed). + + +Array functions +--------------- + +.. 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). + + +:: + + 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]) + +:: + + 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]) + +:: + + 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(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]) + +:: + + cumsum!(B, A[, dim]) + +Cumulative sum of ``A`` along a dimension, storing the result in + + +:: + + cumsum!(B, A[, dim]) + +Cumulative sum of ``A`` along a dimension, storing the result in + + +.. 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. + + +:: + + 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]) + +:: + + 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]) + +:: + + 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. + + +:: + + diff(A[, dim]) + +Finite difference operator of matrix or vector. + + +.. function:: gradient(F, [h]) + +:: + + 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) + +:: + + 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:: 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``. + + +:: + + 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) + +:: + + 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:: 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``. + + +:: + + 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) + +:: + + 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:: 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``. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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) + +:: + + nthperm(p) + +Return the ``k`` that generated permutation ``p``. Note that + + +:: + + 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 + + +:: + + nthperm(p) + +Return the ``k`` that generated permutation ``p``. Note that + + +.. function:: nthperm!(v, k) + +:: + + nthperm!(v, k) + +In-place version of ``nthperm()``. + + +:: + + nthperm!(v, k) + +In-place version of ``nthperm()``. + + +.. function:: randperm([rng,] n) + +:: + + randperm([rng], n) + +Construct a random permutation of length ``n``. The optional 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. + + +:: + + invperm(v) + +Return the inverse permutation of v. + + +.. function:: isperm(v) -> Bool + +:: + + isperm(v) -> Bool + +Returns true if v is a valid permutation. + + +:: + + 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. + + +:: + + 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. + + +:: + + ipermute!(v, p) + +Like permute!, but the inverse of the given permutation is applied. + + +.. function:: randcycle([rng,] n) + +:: + + randcycle([rng], n) + +Construct a random cyclic permutation of length ``n``. The optional Numbers*. + + +:: + + randcycle([rng], n) + +Construct a random cyclic permutation of length ``n``. The optional Numbers*. + + +.. 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*. + + +:: + + 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) + +:: + + shuffle!([rng], v) + +In-place version of ``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. + + +:: + + 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.) + + +:: + + 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 + +:: + + reverse!(v[, start=1[, stop=length(v)]]) -> v + +In-place version of ``reverse()``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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) + +:: + + 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))``. + + +.. function:: 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))``. + + +:: + + 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) + +:: + + 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))``. + + +.. 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))``. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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*. + + +:: + + 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} + +:: + + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a left rotation operation on B. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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} + +:: + + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a right rotation operation on B. + + +:: + + 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. + + +:: + + 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. + + +:: + + ror(B::BitArray{1}, i::Integer) -> BitArray{1} + +Performs a right rotation operation. + + +.. _stdlib-sparse: + +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]) + +:: + + sparse(A) + +Convert an AbstractMatrix ``A`` into a sparse matrix. + + +:: + + sparse(A) + +Convert an AbstractMatrix ``A`` into a sparse matrix. + + +.. function:: sparsevec(I, V, [m, combine]) + +:: + + 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(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]) + +:: + + 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(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. + + +:: + + issparse(S) + +Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. + + +.. function:: sparse(A) + +:: + + sparse(A) + +Convert an AbstractMatrix ``A`` into a sparse matrix. + + +:: + + 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. + + +:: + + 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) + +:: + + 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(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. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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]) + +:: + + 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([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) + +:: + + sprandn(m, n, p) + +Create a random ``m`` by ``n`` sparse matrix with the specified 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) + +:: + + sprandbool(m, n, p) + +Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being + + +:: + + 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. + + +:: + + 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. + + +:: + + 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)``. + + +:: + + 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)``. + + +:: + + 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 + + +:: + + 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 -.. 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 diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index e7ead054d2064..80ce06948d5d5 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -22,79 +22,291 @@ Getting Around .. function:: exit([code]) - Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. +:: + + exit([code]) + +Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. + + +:: + + 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()``). + + +:: + + 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. +:: + + atexit(f) + +Register a zero-argument function to be called at exit. + + +:: + + 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. + + +:: + + 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. +:: + + isinteractive() -> Bool + +Determine whether Julia is running an interactive session. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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. +:: + + edit(function[, types]) + +Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. + + +:: + + 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 +:: + + @edit() + +Evaluates the arguments to the function call, determines their types, and calls the ``edit`` function on the resulting expression + + +:: + + @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. + + +:: + + 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. +:: + + 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(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 +:: + + @less() + +Evaluates the arguments to the function call, determines their types, and calls the ``less`` function on the resulting expression + + +:: + + @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 + + +:: + + 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 + + +:: + + 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. +:: + + 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(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``. - 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. +:: + + 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(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) - 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("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. + + +:: + + 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. +:: + + 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(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 +318,131 @@ Getting Around .. function:: which(f, types) - Returns the method of ``f`` (a ``Method`` object) that would be called for arguments of the given types. +:: + + 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. - If ``types`` is an abstract type, then the method that would be called by ``invoke`` - is returned. .. 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. + + +:: + + 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. + + +:: + + @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``. +:: + + 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. - 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``. +:: + + 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. - The optional second argument restricts the search to a particular module - or function. .. function:: @show - Show an expression and result, returning the result +:: + + @show() + +Show an expression and result, returning the result + + +:: + + @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. + + +:: + + 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``. +:: + + 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() + +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. - This function should only be used interactively. .. data:: ans @@ -164,908 +452,2569 @@ Getting Around All Objects ----------- -.. function:: is(x, y) -> Bool - ===(x,y) -> Bool - ≡(x,y) -> Bool +.. function:: is(x, y) -> Bool + +:: + + ===(x, y) + +See the ``is()`` operator + + +:: + + ===(x, y) + +See the ``is()`` operator + + +.. function:: isa(x, type) -> Bool + +:: + + isa(x, type) -> Bool + +Determine whether ``x`` is of the given ``type``. + + +:: + + 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 ``==``). + + +:: + + 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 + + +:: + + 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. + + +:: + + 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 + + +:: + + 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``. + + +:: + + lexless(x, y) + +Determine whether ``x`` is lexicographically less than ``y``. + + +.. function:: typeof(x) + +:: + + typeof(x) + +Get the concrete type of ``x``. + + +:: + + typeof(x) + +Get the concrete type of ``x``. + + +.. function:: tuple(xs...) + +:: + + tuple(xs...) + +Construct a tuple of the given objects. + + +:: + + 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. + + +:: + + 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)``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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) + +:: + + 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([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``. + + +:: + + 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). + + +:: + + 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)``). + + +:: + + 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))``. + + +:: + + 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. + + +:: + + identity(x) + +The identity function. Returns its argument. + + +Types +----- + +.. function:: super(T::DataType) + +:: + + super(T::DataType) + +Return the supertype of DataType T + + +:: + + super(T::DataType) + +Return the supertype of DataType T + + +.. function:: issubtype(type1, type2) + +:: + + <:(T1, T2) + +Subtype operator, equivalent to ``issubtype(T1,T2)``. + + +:: + + <:(T1, T2) + +Subtype operator, equivalent to ``issubtype(T1,T2)``. + + +.. function:: <:(T1, T2) + +:: + + <:(T1, T2) + +Subtype operator, equivalent to ``issubtype(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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + maxintfloat(type) + +The largest integer losslessly representable by the given floating- point type + + +.. function:: sizeof(type) + +:: + + sizeof(s::AbstractString) + +The number of bytes in string ``s``. + + +:: + + sizeof(s::AbstractString) + +The number of bytes in string ``s``. + + +.. function:: eps([type]) + +:: + + eps(::DateTime) -> Millisecond + +Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + + +:: + + eps(::DateTime) -> Millisecond + +Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + + +.. function:: eps(x) + +:: + + eps(::DateTime) -> Millisecond + +Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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: + + +:: + + 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. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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``). + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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} + + 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. + +.. function:: @enum EnumName EnumValue1[=x] EnumValue2[=y] + + Create an :obj:`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 + + .. doctest:: + + 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" + +.. 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``). + + +:: + + 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 + +:: + + method_exists(f, Tuple type) -> Bool + +Determine whether the given generic function has a method matching the given ``Tuple`` of argument types. + + +:: + + 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. + + +:: + + 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). + + +:: + + 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. + + +:: + + |>(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. + + +:: + + 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) + +:: + + 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. + + +:: + + @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. + + +:: + + 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. + + +:: + + 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. + + +:: + + gensym([tag]) + +Generates a symbol which will not conflict with other variable names. + + +.. function:: @gensym + +:: + + @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(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:: parse(str; raise=true) + +:: + + 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. + + +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``. + + +:: + + 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) + +:: + + 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(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) + +:: + + 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(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? + + +:: + + isnull(x) + +Is the ``Nullable`` object ``x`` null, i.e. missing a value? + + +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. + + +:: + + 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 + + +:: + + spawn(command) + +Run a command object asynchronously, returning the resulting + + +.. data:: 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)`` + +.. 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + process_exited(p::Process) + +Determine whether a process has exited. + + +.. function:: kill(p::Process, signum=SIGTERM) + +:: + + 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(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) + +:: + + open(f::function, args...) + +Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + +:: + + 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) + +:: + + open(f::function, args...) + +Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + +:: + + 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) + + Set the process title. No-op on some operating systems. (not exported) + +.. function:: Sys.get_process_title() + + Get the process title. On some systems, will always return empty string. (not exported) + +.. function:: readandwrite(command) + +:: + + readandwrite(command) + +Starts running a command asynchronously, and returns a tuple 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) + +:: + + 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) + +:: + + 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) + +:: + + 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(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. + + +:: + + 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, ...) + +:: + + 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(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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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. + + +:: + + getpid() -> Int32 + +Get julia's process ID. + + +.. function:: time() + +:: + + time(t::TmStruct) + +Converts a ``TmStruct`` struct to a number of seconds since the epoch. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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()``. + + +:: + + 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 + + +:: + + 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. + + +:: + + @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. + + +:: + + @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. + + +:: + + @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. + + +:: + + @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 + +:: + + @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. + + +:: + + EnvHash() -> EnvHash + +A singleton of this type provides a hash table interface to environment variables. + + +.. data:: ENV + + Reference to the singleton ``EnvHash``, providing a dictionary interface to system environment variables. + +.. 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. + + +:: + + @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 + +:: + + @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 + +:: + + @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 + +:: + + @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 + + +:: + + error(message::AbstractString) + +Raise an ``ErrorException`` with the given message + + +.. function:: throw(e) + +:: + + throw(e) + +Throw an object as an exception + + +:: + + 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 + + +:: + + 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. + + +:: + + 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 + + +:: + + 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``. + + +:: + + assert(cond) + +Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. + + +.. function:: @assert cond [text] + + Throw an ``AssertionError`` if ``cond`` is false. Preferred syntax for writing assertions. + +.. function:: ArgumentError(msg) + +:: + + ArgumentError(msg) + +The parameters to a function call do not match a valid signature. + + +:: + + 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``. + + +:: + + AssertionError([msg]) + +The asserted condition did not evalutate to ``true``. + + +.. function:: BoundsError([a],[i]) + +:: + + 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. + + +:: + + DimensionMismatch([msg]) + +The objects called do not have matching dimensionality. + + +.. function:: DivideError() + +:: + + DivideError() + +Integer division was attempted with a denominator value of 0. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + InexactError() + +Type conversion cannot be done exactly. + + +.. function:: InterruptException() + +:: + + InterruptException() + +The process was stopped by a terminal interrupt (CTRL+C). + + +:: + + 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. + + +:: + + 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. + + +:: + + 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) - 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``. +A method with the required type signature does not exist in the given generic function. -.. function:: isa(x, type) -> Bool - Determine whether ``x`` is of the given ``type``. +:: -.. function:: isequal(x, y) + MethodError(f, args) - 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 ``==``. +A method with the required type signature does not exist in the given generic function. - ``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. +.. function:: NullException() - 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) + NullException() - 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``. +An attempted access to a ``Nullable`` with no defined value. -.. 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) + NullException() - 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. +An attempted access to a ``Nullable`` with no defined value. -.. function:: lexless(x, y) - Determine whether ``x`` is lexicographically less than ``y``. +.. function:: OutOfMemoryError() -.. function:: typeof(x) +:: - Get the concrete type of ``x``. + OutOfMemoryError() -.. function:: tuple(xs...) +An operation allocated too much memory for either the system or the garbage collector to handle properly. - 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. + OutOfMemoryError() -.. function:: object_id(x) +An operation allocated too much memory for either the system or the garbage collector to handle properly. - Get a unique integer id for ``x``. ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``. -.. function:: hash(x[, h]) +.. function:: ReadOnlyMemoryError() - 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. + ReadOnlyMemoryError() -.. function:: finalizer(x, function) +An operation tried to write to memory that is read-only. - 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``. + ReadOnlyMemoryError() -.. function:: copy(x) +An operation tried to write to memory that is read-only. - 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) +.. function:: OverflowError() - 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. + OverflowError() - 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. +The result of an expression is too large for the specified type and will cause a wraparound. -.. 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()``. +:: -.. function:: convert(T, x) + OverflowError() - Convert ``x`` to a value of type ``T``. +The result of an expression is too large for the specified type and will cause a wraparound. - 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:: +.. function:: ParseError(msg) - julia> convert(Int, 3.0) - 3 +:: - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:196 + ParseError(msg) - If ``T`` is a :obj:`FloatingPoint` or :obj:`Rational` type, then it will return - the closest value to ``x`` representable by ``T``. +The expression passed to the *parse* function could not be interpreted as a valid Julia expression. - .. doctest:: - julia> x = 1/3 - 0.3333333333333333 +:: - julia> convert(Float32, x) - 0.33333334f0 + ParseError(msg) - julia> convert(Rational{Int32}, x) - 1//3 +The expression passed to the *parse* function could not be interpreted as a valid Julia expression. - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 -.. function:: promote(xs...) +.. function:: ProcessExitedException() - Convert all arguments to their common promotion type (if any), and return them all (as a tuple). +:: -.. function:: oftype(x, y) + ProcessExitedException() - Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``). +After a client Julia process has exited, further attempts to reference the dead child will throw this exception. -.. 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:: + ProcessExitedException() - julia> widen(Int32) - Int64 +After a client Julia process has exited, further attempts to reference the dead child will throw this exception. - .. doctest:: - julia> widen(1.5f0) - 1.5 +.. function:: StackOverflowError() -.. function:: identity(x) +:: - The identity function. Returns its argument. + StackOverflowError() -Types ------ +The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. -.. function:: super(T::DataType) - Return the supertype of DataType T +:: -.. function:: issubtype(type1, type2) + StackOverflowError() - True if and only if all values of ``type1`` are also of ``type2``. Can also be written using the ``<:`` infix operator as ``type1 <: type2``. +The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. -.. function:: <:(T1, T2) - Subtype operator, equivalent to ``issubtype(T1,T2)``. +.. function:: SystemError(prefix::AbstractString, [errnum::Int32]) -.. 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. + SystemError(prefix::AbstractString[, errnum::Int32]) -.. function:: typemin(type) +A system call failed with an error code (in the ``errno`` global variable). - The lowest value representable by the given (real) numeric type. -.. function:: typemax(type) +:: - The highest value representable by the given (real) numeric type. + SystemError(prefix::AbstractString[, errnum::Int32]) -.. function:: realmin(type) +A system call failed with an error code (in the ``errno`` global variable). - The smallest in absolute value non-subnormal value representable by the given floating-point type -.. function:: realmax(type) +.. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) - The highest finite value representable by the given floating-point type +:: -.. function:: maxintfloat(type) + TypeError(func::Symbol, context::AbstractString, expected::Type, got) - The largest integer losslessly representable by the given floating-point type +A type assertion failure, or calling an intrinsic function with an incorrect argument type. -.. function:: sizeof(type) - Size, in bytes, of the canonical binary representation of the given type, if any. +:: -.. function:: eps([type]) + TypeError(func::Symbol, context::AbstractString, expected::Type, got) - 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. +A type assertion failure, or calling an intrinsic function with an incorrect argument type. -.. function:: eps(x) - The distance between ``x`` and the next larger representable floating-point value of the same type as ``x``. +.. function:: UndefRefError() -.. 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. + UndefRefError() -.. function:: promote_rule(type1, type2) +The item or field is not defined for the given object. - 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)``. + UndefRefError() -.. function:: setfield!(value, name::Symbol, x) +The item or field is not defined for the given object. - 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) +.. function:: UndefVarError(var::Symbol) - 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:: + UndefVarError(var::Symbol) - 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) +A symbol in the current scope is not defined. -.. 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) + UndefVarError(var::Symbol) - 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. +A symbol in the current scope is not defined. -.. 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}``. +Events +------ - .. doctest:: +.. function:: Timer(callback::Function, delay, repeat=0) - julia> isbits(Complex{Float64}) - true +:: - julia> isbits(Complex) - false + Timer(delay, repeat=0) -.. function:: isleaftype(T) +Create a timer that wakes up tasks waiting for it (by calling - 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``. + Timer(delay, repeat=0) -.. function:: typeintersect(T, S) +Create a timer that wakes up tasks waiting for it (by calling - 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} +.. function:: Timer(delay, repeat=0) - 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. +:: -.. function:: @enum EnumName EnumValue1[=x] EnumValue2[=y] + Timer(delay, repeat=0) - Create an :obj:`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 +Create a timer that wakes up tasks waiting for it (by calling - .. doctest:: - 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) + Timer(delay, repeat=0) - julia> f(apple) - "I'm a FRUIT with value: 1" +Create a timer that wakes up tasks waiting for it (by calling -.. function:: instances(T::Type) - Return a collection of all instances of the given type, if applicable. - Mostly used for enumerated types (see ``@enum``). +Reflection +---------- -Generic Functions ------------------ +.. function:: module_name(m::Module) -> Symbol -.. function:: method_exists(f, Tuple type) -> Bool +:: - Determine whether the given generic function has a method matching the given :obj:`Tuple` of argument types. + module_name(m::Module) -> Symbol - .. doctest:: +Get the name of a module as a symbol. - 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. + module_name(m::Module) -> Symbol - .. doctest:: +Get the name of a module as a symbol. - julia> function f(x, y) - x + y - end; - julia> applicable(f, 1) - false +.. function:: module_parent(m::Module) -> Module - julia> applicable(f, 1, 2) - true +:: -.. function:: invoke(f, (types...), args...) + module_parent(m::Module) -> Module - 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). +Get a module's enclosing module. ``Main`` is its own parent. -.. function:: |>(x, f) - Applies a function to the preceding argument. This allows for easy function chaining. +:: - .. doctest:: + module_parent(m::Module) -> Module - julia> [1:5;] |> x->x.^2 |> sum |> inv - 0.01818181818181818 +Get a module's enclosing module. ``Main`` is its own parent. -.. 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. +.. function:: current_module() -> Module -Syntax ------- +:: -.. function:: eval([m::Module], expr::Expr) + current_module() -> 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. +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:: @eval - Evaluate an expression and return the value. +:: -.. function:: evalfile(path::AbstractString) + current_module() -> Module - Load the file using ``include``, evaluate all expressions, and return the value of the last one. +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:: 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. +.. function:: fullname(m::Module) -.. function:: gensym([tag]) +:: - Generates a symbol which will not conflict with other variable names. + fullname(m::Module) -.. function:: @gensym +Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and - 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. + fullname(m::Module) -.. function:: parse(str; raise=true) +Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and - 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. +.. function:: names(x::Module[, all=false[, imported=false]]) -Nullables ---------- +:: -.. function:: Nullable(x) + names(x::Module[, all=false[, imported=false]]) - 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``. +Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. -.. function:: get(x) - Attempt to access the value of the ``Nullable`` object, ``x``. Returns the - value if it is present; otherwise, throws a ``NullException``. +:: -.. function:: get(x, y) + names(x::Module[, all=false[, imported=false]]) - Attempt to access the value of the ``Nullable{T}`` object, ``x``. Returns - the value if it is present; otherwise, returns ``convert(T, y)``. +Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. -.. function:: isnull(x) - Is the ``Nullable`` object ``x`` null, i.e. missing a value? +.. function:: nfields(x::DataType) -> Int +:: -System ------- + nfields(x::DataType) -> Int -.. function:: run(command) +Get the number of fields of a data type. - 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. + nfields(x::DataType) -> Int -.. data:: DevNull +Get the number of fields of a data type. - 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)`` -.. function:: success(command) +.. function:: fieldnames(x::DataType) - 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) + fieldnames(x::DataType) - Determine whether a process is currently running. +Get an array of the fields of a data type. -.. function:: process_exited(p::Process) - Determine whether a process has exited. +:: -.. function:: kill(p::Process, signum=SIGTERM) + fieldnames(x::DataType) - Send a signal to a process. The default is to terminate the process. +Get an array of the fields of a data type. -.. 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. +.. function:: isconst([m::Module], s::Symbol) -> Bool -.. 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``. + isconst([m::Module], s::Symbol) -> Bool -.. function:: Sys.set_process_title(title::AbstractString) +Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``. - Set the process title. No-op on some operating systems. (not exported) -.. function:: Sys.get_process_title() +:: - Get the process title. On some systems, will always return empty string. (not exported) + isconst([m::Module], s::Symbol) -> Bool -.. function:: readandwrite(command) +Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``. - 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) +.. function:: isgeneric(f::Function) -> Bool - Mark a command object so that running it will not throw an error if the - result code is non-zero. +:: -.. function:: detach(command) + isgeneric(f::Function) -> Bool - 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. +Determine whether a function is generic. -.. 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. + isgeneric(f::Function) -> Bool -.. function:: withenv(f::Function, kv::Pair...) +Determine whether a function is generic. - 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(from, to, ...) +.. function:: function_name(f::Function) -> Symbol - 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`))`` + function_name(f::Function) -> Symbol -.. function:: pipe(command; stdin, stdout, stderr, append=false) +Get the name of a generic function as a symbol, or ``:anonymous``. - 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:: gethostname() -> AbstractString + function_name(f::Function) -> Symbol - Get the local machine's host name. +Get the name of a generic function as a symbol, or ``:anonymous``. -.. function:: getipaddr() -> AbstractString - Get the IP address of the local machine, as a string of the form "x.x.x.x". +.. function:: function_module(f::Function, types) -> Module -.. function:: getpid() -> Int32 +:: - Get julia's process ID. + function_module(f::Function, types) -> Module -.. function:: time() +Determine the module containing a given definition of a generic function. - Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. -.. function:: time_ns() +:: - Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. + function_module(f::Function, types) -> Module -.. function:: tic() +Determine the module containing a given definition of a generic function. - 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. -.. function:: toc() +.. function:: functionloc(f::Function, types) - Print and return the time elapsed since the last :func:`tic`. +:: -.. function:: toq() + functionloc(m::Method) - Return, but do not print, the time elapsed since the last :func:`tic`. +Returns a tuple ``(filename,line)`` giving the location of a method definition. -.. 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 + functionloc(m::Method) - 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 tuple ``(filename,line)`` giving the location of a method definition. -.. 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:: functionloc(m::Method) -.. 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. + functionloc(m::Method) -.. function:: @allocated +Returns a tuple ``(filename,line)`` giving the location of a method definition. - 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. + functionloc(m::Method) -.. data:: ENV +Returns a tuple ``(filename,line)`` giving the location of a method definition. - Reference to the singleton ``EnvHash``, providing a dictionary interface to system environment variables. -.. function:: @unix +Internals +--------- - 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:: gc() -.. 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. + gc() -.. function:: @linux +Perform garbage collection. This should not generally be used. - 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. + gc() +Perform garbage collection. This should not generally be used. -Errors ------- -.. function:: error(message::AbstractString) +.. function:: gc_enable(on::Bool) - Raise an ``ErrorException`` with the given message +:: -.. function:: throw(e) + gc_enable(on::Bool) - Throw an object as an exception +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:: rethrow([e]) - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - ``catch`` block). +:: -.. function:: backtrace() + gc_enable(on::Bool) - Get a backtrace object for the current program point. +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:: catch_backtrace() - Get the backtrace of the current exception, for use within ``catch`` - blocks. +.. function:: macroexpand(x) -.. function:: assert(cond) +:: - Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. + macroexpand(x) -.. function:: @assert cond [text] +Takes the expression x and returns an equivalent expression with all macros removed (expanded). - Throw an ``AssertionError`` if ``cond`` is false. Preferred syntax for writing assertions. -.. function:: ArgumentError(msg) +:: - The parameters to a function call do not match a valid signature. + macroexpand(x) -.. function:: AssertionError([msg]) +Takes the expression x and returns an equivalent expression with all macros removed (expanded). - The asserted condition did not evalutate to ``true``. -.. function:: BoundsError([a],[i]) +.. function:: expand(x) - An indexing operation into an array, ``a``, tried to access an out-of-bounds element, ``i``. +:: -.. function:: DimensionMismatch([msg]) + expand(x) - The objects called do not have matching dimensionality. +Takes the expression x and returns an equivalent expression in lowered form -.. function:: DivideError() - Integer division was attempted with a denominator value of 0. +:: -.. function:: DomainError() + expand(x) - The arguments to a function or constructor are outside the valid domain. +Takes the expression x and returns an equivalent expression in lowered form -.. function:: EOFError() - No more data was available to read from a file or stream. +.. function:: code_lowered(f, types) + +:: -.. function:: ErrorException(msg) + code_lowered(f, types) - Generic error type. The error message, in the `.msg` field, may provide more specific details. +Returns an array of lowered ASTs for the methods matching the given generic function and type signature. -.. function:: InexactError() - Type conversion cannot be done exactly. +:: -.. function:: InterruptException() + code_lowered(f, types) - The process was stopped by a terminal interrupt (CTRL+C). +Returns an array of lowered ASTs for the methods matching the given generic function and type signature. -.. function:: KeyError(key) - An indexing operation into an ``Associative`` (``Dict``) or ``Set`` like object tried to access or delete a non-existent element. +.. function:: @code_lowered -.. 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. + @code_lowered() -.. function:: MethodError(f, args) +Evaluates the arguments to the function call, determines their types, and calls ``code_lowered()`` on the resulting expression - 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. + @code_lowered() -.. function:: OutOfMemoryError() +Evaluates the arguments to the function call, determines their types, and calls ``code_lowered()`` on the resulting expression - An operation allocated too much memory for either the system or the garbage collector to handle properly. -.. function:: ReadOnlyMemoryError() +.. function:: code_typed(f, types; optimize=true) - An operation tried to write to memory that is read-only. +:: -.. function:: OverflowError() + code_typed(f, types; optimize=true) - The result of an expression is too large for the specified type and will cause a wraparound. +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:: ParseError(msg) - The expression passed to the `parse` function could not be interpreted as a valid Julia expression. +:: -.. function:: ProcessExitedException() + code_typed(f, types; optimize=true) - After a client Julia process has exited, further attempts to reference the dead child will throw this exception. +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:: StackOverflowError() - The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. +.. function:: @code_typed -.. function:: SystemError(prefix::AbstractString, [errnum::Int32]) +:: - A system call failed with an error code (in the ``errno`` global variable). + @code_typed() -.. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) +Evaluates the arguments to the function call, determines their types, and calls ``code_typed()`` on the resulting expression - 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. + @code_typed() -.. function:: UndefVarError(var::Symbol) +Evaluates the arguments to the function call, determines their types, and calls ``code_typed()`` on the resulting expression - A symbol in the current scope is not defined. -Events ------- +.. function:: code_warntype(f, types) -.. 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. + code_warntype(f, types) -.. function:: Timer(delay, repeat=0) +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. - 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 + code_warntype(f, types) - Get the name of a module as a symbol. +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:: module_parent(m::Module) -> Module - Get a module's enclosing module. ``Main`` is its own parent. +.. function:: @code_warntype -.. 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. + @code_warntype() -.. function:: fullname(m::Module) +Evaluates the arguments to the function call, determines their types, and calls ``code_warntype()`` on the resulting expression - 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. + @code_warntype() -.. function:: nfields(x::DataType) -> Int +Evaluates the arguments to the function call, determines their types, and calls ``code_warntype()`` on the resulting expression - Get the number of fields of a data type. -.. function:: fieldnames(x::DataType) +.. function:: code_llvm(f, types) - Get an array of the fields of a data type. +:: -.. function:: isconst([m::Module], s::Symbol) -> Bool + code_llvm(f, types) - Determine whether a global is declared ``const`` in a given module. - The default module argument is ``current_module()``. +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:: isgeneric(f::Function) -> Bool - Determine whether a function is generic. +:: -.. function:: function_name(f::Function) -> Symbol + code_llvm(f, types) - Get the name of a generic function as a symbol, or ``:anonymous``. +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:: function_module(f::Function, types) -> Module - Determine the module containing a given definition of a generic function. +.. function:: @code_llvm -.. function:: functionloc(f::Function, types) +:: - Returns a tuple ``(filename,line)`` giving the location of a method definition. + @code_llvm() -.. function:: functionloc(m::Method) +Evaluates the arguments to the function call, determines their types, and calls ``code_llvm()`` on the resulting expression - Returns a tuple ``(filename,line)`` giving the location of a method definition. -Internals ---------- +:: -.. function:: gc() + @code_llvm() - Perform garbage collection. This should not generally be used. +Evaluates the arguments to the function call, determines their types, and calls ``code_llvm()`` on the resulting expression -.. 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:: code_native(f, types) -.. function:: macroexpand(x) +:: - Takes the expression x and returns an equivalent expression with all macros removed (expanded). + code_native(f, types) -.. function:: expand(x) +Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. - 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. + code_native(f, types) -.. function:: @code_lowered +Prints the native assembly instructions generated for running the method matching the given generic function and type signature to STDOUT. - Evaluates the arguments to the function call, determines their types, and calls :func:`code_lowered` on the resulting expression -.. function:: code_typed(f, types; optimize=true) +.. function:: @code_native - 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 + @code_native() - Evaluates the arguments to the function call, determines their types, and calls :func:`code_typed` on the resulting expression +Evaluates the arguments to the function call, determines their types, and calls ``code_native()`` 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. +:: -.. function:: @code_warntype + @code_native() - Evaluates the arguments to the function call, determines their types, and calls :func:`code_warntype` on the resulting expression +Evaluates the arguments to the function call, determines their types, and calls ``code_native()`` 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`. +.. function:: precompile(f,args::Tuple{Vararg{Any}}) - All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. +:: -.. function:: @code_llvm + precompile(f, args::Tuple{Vararg{Any}}) - Evaluates the arguments to the function call, determines their types, and calls :func:`code_llvm` on the resulting expression +Compile the given function ``f`` for the argument tuple (of types) -.. 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 + precompile(f, args::Tuple{Vararg{Any}}) - Evaluates the arguments to the function call, determines their types, and calls :func:`code_native` on the resulting expression +Compile the given function ``f`` for the argument tuple (of types) -.. function:: precompile(f,args::Tuple{Vararg{Any}}) - 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 2d24a41c6bb43..7589ca5d43447 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -6,154 +6,291 @@ .. 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. + 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)`` + + +:: + + 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)`` - 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. +:: + + 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((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. +:: + + 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: - For example:: - function foo() - # body +:: - retval::Float64 - end + 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: - bar = cfunction(foo, Float64, ()) .. function:: unsafe_convert(T,x) - Convert "x" to a value of type "T" +:: + + 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. + - 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. + 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. - 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)`` +:: + + 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``. - 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]``. +:: + + 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(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. - 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``. +:: + + 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!(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. - 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. +:: + + 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!(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. - 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. .. 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). +:: + + 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!(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. - 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 + + +:: + + 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 + + +:: + + 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``. +:: + + 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(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. - 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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(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(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 .. 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``. + + +:: + + 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 + + +:: + + 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..8bf7aa4900545 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -26,61 +26,179 @@ 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 +:: + + start(iter) -> state + +Get initial iteration state for an iterable object + + +:: + + start(iter) -> state + +Get initial iteration state for an iterable object + .. function:: done(iter, state) -> Bool - Test whether we are done iterating +:: + + done(iter, state) -> Bool + +Test whether we are done iterating + + +:: + + 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 +:: + + next(iter, state) -> item, state + +For a given iterable object and iteration state, return the current item and the next iteration 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. +:: + + 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(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: - Note that :func:`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. +:: + + enumerate(iter) - .. doctest:: +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(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``. +:: + + rest(iter, state) + +An iterator that yields the same elements as ``iter``, but starting at the given ``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) - An iterator that counts forever, starting at ``start`` and incrementing by ``step``. +:: + + countfrom(start=1, step=1) + +An iterator that counts forever, starting at ``start`` and incrementing by ``step``. + + +:: + + 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 + + +:: + + 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 + + +:: + + drop(iter, n) + +An iterator that generates all but the first ``n`` elements of + .. function:: cycle(iter) - An iterator that cycles through ``iter`` forever. +:: + + cycle(iter) + +An iterator that cycles through ``iter`` forever. + + +:: + + 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 + + +:: + + 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 +222,67 @@ General Collections .. function:: isempty(collection) -> Bool - Determine whether a collection is empty (has no elements). +:: + + isempty(collection) -> Bool + +Determine whether a collection is empty (has no elements). + - .. doctest:: +:: - julia> isempty([]) - true + isempty(collection) -> Bool + +Determine whether a collection is empty (has no elements). - julia> isempty([1 2 3]) - false .. function:: empty!(collection) -> collection - Remove all elements from a ``collection``. +:: + + empty!(collection) -> collection + +Remove all elements from a ``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``. + + +:: + + length(s) + +The number of characters in string ``s``. + .. function:: endof(collection) -> Integer - Returns the last index of the collection. +:: + + endof(collection) -> Integer + +Returns the last index of the collection. + + +:: + + endof(collection) -> Integer - .. doctest:: +Returns the last index of the collection. - julia> endof([1,2,4]) - 3 Fully implemented by: @@ -148,938 +301,1869 @@ 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)``. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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`` +:: + + findin(a, b) + +Returns the indices of elements in collection ``a`` that appear in collection ``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``. + + +:: + + 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. +:: + + 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``. + + +:: - 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)``. + reduce(op, 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. +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``. - 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. .. 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``. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. +:: + + maximum(A, dims) + +Compute the maximum value of an array over the given dimensions. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. +:: + + minimum(A, dims) + +Compute the minimum value of an array over the given dimensions. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + indmin(itr) -> Integer + +Returns the index of the minimum element in a collection. + + +.. function:: findmax(itr) -> (x, index) + +:: + + 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:: 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. + + +:: + + 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) + +:: + + 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:: 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. + + +:: + + findmin(A, dims) -> (minval, index) + +For an array input, returns the value and index of the minimum over the given dimensions. + + +.. function:: maxabs(itr) + +:: + + maxabs(A, dims) + +Compute the maximum absolute values over given dimensions. + + +:: + + 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. + + +:: + + 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``. + + +:: + + maxabs!(r, A) + +Compute the maximum absolute values over the singleton dimensions of ``r``, and write values to ``r``. + + +.. function:: minabs(itr) + +:: + + minabs(A, dims) + +Compute the minimum absolute values over given dimensions. + + +:: + + 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. + + +:: + + 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``. + + +:: + + minabs!(r, A) + +Compute the minimum absolute values over the singleton dimensions of ``r``, and write values to ``r``. + + +.. function:: sum(itr) + +:: + + sum(f, itr) + +Sum the results of calling function ``f`` on each element of + + +:: + + sum(f, itr) + +Sum the results of calling function ``f`` on each element of + + +.. function:: sum(A, dims) + +:: + + sum(f, itr) + +Sum the results of calling function ``f`` on each element of + + +:: + + 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``. + + +:: + + 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 + + +:: + + sum(f, itr) + +Sum the results of calling function ``f`` on each element of + + +.. function:: sumabs(itr) + +:: + + 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(A, dims) + +:: + + 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) + +:: + + 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) + +:: + + 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(A, dims) + +:: + + 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) + +:: + + 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) + +:: + + prod(A, dims) + +Multiply elements of an array over the given dimensions. + + +:: + + 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. + + +:: + + 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``. + + +:: + + prod!(r, A) + +Multiply elements of ``A`` over the singleton dimensions of ``r``, and write results to ``r``. + + +.. function:: any(itr) -> Bool + +:: + + any(p, itr) -> Bool + +Determine whether predicate ``p`` returns true for any elements of + + +:: + + any(p, itr) -> Bool + +Determine whether predicate ``p`` returns true for any elements of + + +.. function:: any(A, dims) + +:: + + any(p, itr) -> Bool + +Determine whether predicate ``p`` returns true for any elements of + + +:: + + 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 + + +:: + + any!(r, A) + +Test whether any values in ``A`` along the singleton dimensions of + + +.. function:: all(itr) -> Bool + +:: + + all(p, itr) -> Bool + +Determine whether predicate ``p`` returns true for all elements of + + +:: + + all(p, itr) -> Bool + +Determine whether predicate ``p`` returns true for all elements of + + +.. function:: all(A, dims) + +:: + + all(p, itr) -> Bool + +Determine whether predicate ``p`` returns true for all elements of + + +:: + + 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 + + +:: + + 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. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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. + + +:: + + map(f, c...) -> collection + +Transform collection ``c`` by applying ``f`` to each element. For multiple collection arguments, apply ``f`` elementwise. + + +.. function:: map!(function, 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. + + +:: + + 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. + + +:: + + 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) + +:: + + 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:: 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)``). + + +:: + + 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) + +:: + + mapfoldl(f, op, itr) + +Like ``mapfoldl(f, op, v0, itr)``, but using the first element of 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:: 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)``). + + +:: + + 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) + +:: + + mapfoldr(f, op, itr) + +Like ``mapfoldr(f, op, v0, itr)``, but using the first element of 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:: 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)``). + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + step(r) + +Get the step size of a ``Range`` object. + + +.. function:: collect(collection) + +:: + + collect(element_type, collection) + +Return an array of type ``Array{element_type,1}`` of all items in a 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. + + +:: + + collect(element_type, collection) + +Return an array of type ``Array{element_type,1}`` of all items in a collection. + + +.. function:: issubset(a, b) + +:: + + issubset(A, S) -> Bool + +True if A is a subset of or equal to S. + + +:: + + 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). + + +:: + + 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). + + +:: + + 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...) + +:: + + 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...) + +:: + + 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: + +- :obj:`Array` +- :obj:`BitArray` +- :obj:`AbstractArray` +- :obj:`SubArray` +- :obj:`ObjectIdDict` +- :obj:`Dict` +- :obj:`WeakKeyDict` +- :obj:`AbstractString` + +Partially implemented by: + +- :obj:`Range` +- :obj:`UnitRange` +- :obj:`Tuple` + +Associative Collections +----------------------- + +:obj:`Dict` is the standard associative collection. Its implementation uses :func:`hash` as the hashing function for the key, and :func:`isequal` to determine equality. Define these two functions for custom types to override how they are stored in a hash table. + +:obj:`ObjectIdDict` is a special hash table where the keys are always object identities. + +:obj:`WeakKeyDict` is a hash table implementation where the keys are weak references to objects, and thus may be garbage collected even when referenced in a hash table. + +:obj:`Dict`\ s can be created by passing pair objects constructed with :func:`=>` to a :obj:`Dict` constructor: ``Dict("A"=>1, "B"=>2)``. This call will attempt to infer type information from the keys and values (i.e. this example creates a ``Dict{ASCIIString, Int64}``). +To explicitly specify types use the syntax ``Dict{KeyType,ValueType}(...)``. +For example, ``Dict{ASCIIString,Int32}("A"=>1, "B"=>2)``. + +As with :obj:`Array`\ s, :obj:`Dict`\ s may be created with comprehensions. For example, +``[i => f(i) for i = 1:10]``. + +Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if it exists) or throws an error, and ``D[x] = y`` stores the key-value pair ``x => y`` in ``D`` (replacing any existing value for the key ``x``). Multiple arguments to ``D[...]`` are converted to tuples; for example, the syntax ``D[x,y]`` is equivalent to ``D[(x,y)]``, i.e. it refers to the value keyed by the tuple ``(x,y)``. + +.. 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. + + +:: + + 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. + + +:: + + haskey(collection, key) -> Bool + +Determine whether a collection has a mapping for a given key. + + +.. function:: get(collection, key, default) + +:: + + 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(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: + + +:: + + 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) + +:: + + 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: + + +.. 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: + + +:: + + 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 + +.. function:: getkey(collection, key, default) + +:: + + getkey(collection, key, default) + +Return the key matching argument ``key`` if one exists in + + +:: + + 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. + + +:: + + delete!(collection, key) + +Delete the mapping for the given key in a collection, and return the collection. + + +.. function:: pop!(collection, key[, default]) + +:: + + pop!(collection) -> item + +Remove the last item in ``collection`` and return it. + + +:: + + 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. + + +:: + + keys(collection) + +Return an iterator over all keys in a collection. + + +.. function:: values(collection) -.. function:: minimum!(r, A) +:: - Compute the minimum value of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + values(collection) -.. function:: extrema(itr) +Return an iterator over all values in a collection. - 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. + values(collection) -.. function:: indmin(itr) -> Integer +Return an iterator over all values in a collection. - Returns the index of the minimum element in a collection. -.. function:: findmax(itr) -> (x, index) +.. function:: merge(collection, others...) - Returns the maximum element and its index. +:: -.. function:: findmax(A, dims) -> (maxval, index) + merge(collection, others...) - For an array input, returns the value and index of the maximum over - the given dimensions. +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:: findmin(itr) -> (x, index) - Returns the minimum element and its index. +:: -.. function:: findmin(A, dims) -> (minval, index) + merge(collection, others...) - For an array input, returns the value and index of the minimum over - the given dimensions. +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:: maxabs(itr) - Compute the maximum absolute value of a collection of values. +.. function:: merge!(collection, others...) -.. function:: maxabs(A, dims) +:: - Compute the maximum absolute values over given dimensions. + merge!(collection, others...) -.. function:: maxabs!(r, A) +Update collection with pairs from the other collections - 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. + merge!(collection, others...) -.. function:: minabs(A, dims) +Update collection with pairs from the other collections - Compute the minimum absolute values over given dimensions. -.. function:: minabs!(r, A) +.. function:: sizehint!(s, n) - Compute the minimum absolute values over the singleton dimensions of ``r``, - and write values to ``r``. +:: -.. function:: sum(itr) + sizehint!(s, n) - Returns the sum of all elements in a collection. +Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. -.. function:: sum(A, dims) - Sum elements of an array over the given dimensions. +:: -.. function:: sum!(r, A) + sizehint!(s, n) - Sum elements of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. +Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. -.. function:: sum(f, itr) - Sum the results of calling function ``f`` on each element of ``itr``. +Fully implemented by: -.. function:: sumabs(itr) +- :obj:`ObjectIdDict` +- :obj:`Dict` +- :obj:`WeakKeyDict` - Sum absolute values of all elements in a collection. This is - equivalent to `sum(abs(itr))` but faster. +Partially implemented by: -.. function:: sumabs(A, dims) +- :obj:`IntSet` +- :obj:`Set` +- :obj:`EnvHash` +- :obj:`Array` +- :obj:`BitArray` - Sum absolute values of elements of an array over the given - dimensions. +Set-Like Collections +-------------------- -.. function:: sumabs!(r, A) +.. function:: Set([itr]) - Sum absolute values of elements of ``A`` over the singleton - dimensions of ``r``, and write results to ``r``. +:: -.. function:: sumabs2(itr) + Set([itr]) - Sum squared absolute values of all elements in a collection. This - is equivalent to `sum(abs2(itr))` but faster. +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:: sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. +:: -.. function:: sumabs2!(r, A) + Set([itr]) - Sum squared absolute values of elements of ``A`` over the singleton - dimensions of ``r``, and write results to ``r``. +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:: prod(itr) - Returns the product of all elements of a collection. +.. function:: IntSet([itr]) -.. function:: prod(A, dims) +:: - Multiply elements of an array over the given dimensions. + IntSet([itr]) -.. function:: prod!(r, A) +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. - 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. + IntSet([itr]) -.. function:: any(A, dims) +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. - Test whether any values along the given dimensions of an array are true. -.. function:: any!(r, A) +.. function:: union(s1,s2...) - Test whether any values in ``A`` along the singleton dimensions of ``r`` are true, - and write results to ``r``. +:: -.. function:: all(itr) -> Bool + union(s1, s2...) - Test whether all elements of a boolean collection are true. +Construct the union of two or more sets. Maintains order with arrays. -.. function:: all(A, dims) - Test whether all values along the given dimensions of an array are true. +:: -.. function:: all!(r, A) + union(s1, s2...) - Test whether all values in ``A`` along the singleton dimensions of ``r`` are true, - and write results to ``r``. +Construct the union of two or more sets. Maintains order with arrays. -.. function:: count(p, itr) -> Integer - Count the number of elements in ``itr`` for which predicate ``p`` returns true. +.. function:: union!(s, iterable) -.. function:: any(p, itr) -> Bool +:: - Determine whether predicate ``p`` returns true for any elements of ``itr``. + union!(s, iterable) -.. function:: all(p, itr) -> Bool +Union each element of ``iterable`` into set ``s`` in-place. - Determine whether predicate ``p`` returns true for all elements of ``itr``. - .. doctest:: +:: - julia> all(i->(4<=i<=6), [4,5,6]) - true + union!(s, iterable) -.. function:: map(f, c...) -> collection +Union each element of ``iterable`` into set ``s`` in-place. - Transform collection ``c`` by applying ``f`` to each element. - For multiple collection arguments, apply ``f`` elementwise. - .. doctest:: +.. function:: intersect(s1,s2...) - 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 + intersect(s1, s2...) -.. function:: map!(function, collection) +Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. - In-place version of :func:`map`. -.. 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. + intersect(s1, s2...) -.. function:: mapreduce(f, op, v0, itr) +Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. - 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`. +.. function:: setdiff(s1,s2) - .. doctest:: +:: - julia> mapreduce(x->x^2, +, [1:3;]) # == 1 + 4 + 9 - 14 + setdiff(s1, s2) - 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. +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:: 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) + setdiff(s1, s2) - Like :func:`mapreduce`, but with guaranteed left associativity. ``v0`` - will be used exactly once. +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:: 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:: setdiff!(s, iterable) -.. function:: mapfoldr(f, op, v0, itr) +:: - Like :func:`mapreduce`, but with guaranteed right associativity. ``v0`` - will be used exactly once. + setdiff!(s, iterable) -.. function:: mapfoldr(f, op, itr) +Remove each element of ``iterable`` from set ``s`` in-place. - 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 :obj:`Range` - even if it is empty. + setdiff!(s, iterable) -.. function:: last(coll) +Remove each element of ``iterable`` from set ``s`` in-place. - 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. -.. function:: step(r) +.. function:: symdiff(s1,s2...) - Get the step size of a :obj:`Range` object. +:: -.. function:: collect(collection) + symdiff(s1, s2...) - Return an array of all items in a collection. For associative collections, returns (key, value) tuples. +Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. -.. function:: 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 + symdiff(s1, s2...) - Determine whether every element of ``a`` is also in ``b``, using :func:`in`. +Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. -.. 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). +.. function:: symdiff!(s, n) -.. 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). + symdiff!(s1, s2) +Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. -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, ...)``. + symdiff!(s1, s2) -.. function:: setindex!(collection, value, key...) +Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - 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: +.. function:: symdiff!(s, itr) -- :obj:`Array` -- :obj:`BitArray` -- :obj:`AbstractArray` -- :obj:`SubArray` -- :obj:`ObjectIdDict` -- :obj:`Dict` -- :obj:`WeakKeyDict` -- :obj:`AbstractString` +:: -Partially implemented by: + symdiff!(s1, s2) -- :obj:`Range` -- :obj:`UnitRange` -- :obj:`Tuple` +Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. -Associative Collections ------------------------ -:obj:`Dict` is the standard associative collection. Its implementation uses :func:`hash` as the hashing function for the key, and :func:`isequal` to determine equality. Define these two functions for custom types to override how they are stored in a hash table. +:: -:obj:`ObjectIdDict` is a special hash table where the keys are always object identities. + symdiff!(s1, s2) -:obj:`WeakKeyDict` is a hash table implementation where the keys are weak references to objects, and thus may be garbage collected even when referenced in a hash table. +Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. -:obj:`Dict`\ s can be created by passing pair objects constructed with :func:`=>` to a :obj:`Dict` constructor: ``Dict("A"=>1, "B"=>2)``. This call will attempt to infer type information from the keys and values (i.e. this example creates a ``Dict{ASCIIString, Int64}``). -To explicitly specify types use the syntax ``Dict{KeyType,ValueType}(...)``. -For example, ``Dict{ASCIIString,Int32}("A"=>1, "B"=>2)``. -As with :obj:`Array`\ s, :obj:`Dict`\ s may be created with comprehensions. For example, -``[i => f(i) for i = 1:10]``. +.. function:: symdiff!(s1, s2) -Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if it exists) or throws an error, and ``D[x] = y`` stores the key-value pair ``x => y`` in ``D`` (replacing any existing value for the key ``x``). Multiple arguments to ``D[...]`` are converted to tuples; for example, the syntax ``D[x,y]`` is equivalent to ``D[(x,y)]``, i.e. it refers to the value keyed by the tuple ``(x,y)``. +:: -.. function:: Dict([itr]) + symdiff!(s1, s2) - ``Dict{K,V}()`` constructs a hash table with keys of type ``K`` and values of type ``V``. +Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - 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 + symdiff!(s1, s2) - Alternatively, a sequence of pair arguments may be passed. +Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. - .. doctest:: - julia> Dict("A"=>1, "B"=>2) - Dict{ASCIIString,Int64} with 2 entries: - "B" => 2 - "A" => 1 +.. function:: complement(s) -.. function:: haskey(collection, key) -> Bool +:: - Determine whether a collection has a mapping for a given key. + complement(s) -.. function:: get(collection, key, default) +Returns the set-complement of ``IntSet`` ``s``. - Return the value stored for the given key, or the given default value if no mapping for the key is present. -.. 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. + complement(s) - This is intended to be called using ``do`` block syntax:: +Returns the set-complement of ``IntSet`` ``s``. - get(dict, key) do - # default value calculated here - time() - end -.. function:: get!(collection, key, default) +.. function:: complement!(s) - Return the value stored for the given key, or if no mapping for the key is present, store ``key => default``, and return ``default``. +:: -.. function:: get!(f::Function, collection, key) + complement!(s) - Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``, and return ``f()``. +Mutates ``IntSet`` ``s`` into its set-complement. - 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) + complement!(s) - Return the key matching argument ``key`` if one exists in ``collection``, otherwise return ``default``. +Mutates ``IntSet`` ``s`` into its set-complement. -.. function:: delete!(collection, key) - Delete the mapping for the given key in a collection, and return the collection. +.. function:: intersect!(s1, s2) -.. 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. + intersect!(s1, s2) -.. function:: keys(collection) +Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of - 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. + intersect!(s1, s2) -.. function:: merge(collection, others...) +Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of - 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:: +.. function:: issubset(A, S) -> Bool - 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 + issubset(A, S) -> Bool - julia> merge(a, b) - Dict{UTF8String,Float64} with 3 entries: - "bar" => 4711.0 - "baz" => 17.0 - "foo" => 0.0 +True if A is a subset of or equal to S. - 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 + issubset(A, S) -> Bool -.. function:: sizehint!(s, n) +True if A is a subset of or equal to S. - Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. Fully implemented by: -- :obj:`ObjectIdDict` -- :obj:`Dict` -- :obj:`WeakKeyDict` +- :obj:`IntSet` +- :obj:`Set` Partially implemented by: -- :obj:`IntSet` -- :obj:`Set` -- :obj:`EnvHash` - :obj:`Array` -- :obj:`BitArray` -Set-Like Collections --------------------- +Dequeues +-------- -.. function:: Set([itr]) +.. function:: push!(collection, items...) -> collection - 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. +:: -.. function:: IntSet([itr]) + push!(collection, items...) -> collection - 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. +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:: union(s1,s2...) - ∪(s1,s2) - Construct the union of two or more sets. Maintains order with arrays. +:: -.. function:: union!(s, iterable) + push!(collection, items...) -> collection - Union each element of ``iterable`` into set ``s`` in-place. +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:: 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. +.. function:: pop!(collection) -> item -.. 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. + pop!(collection) -> item -.. function:: setdiff!(s, iterable) +Remove the last item in ``collection`` and return it. - 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. + pop!(collection) -> item -.. function:: symdiff!(s, n) +Remove the last item in ``collection`` and return it. - The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. -.. function:: symdiff!(s, itr) +.. function:: unshift!(collection, items...) -> collection - For each element in ``itr``, destructively toggle its inclusion in set ``s``. +:: -.. function:: symdiff!(s1, s2) + unshift!(collection, items...) -> collection - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. +Insert one or more ``items`` at the beginning of ``collection``. -.. function:: complement(s) - Returns the set-complement of :obj:`IntSet` ``s``. +:: -.. function:: complement!(s) + unshift!(collection, items...) -> collection - Mutates :obj:`IntSet` ``s`` into its set-complement. +Insert one or more ``items`` at the beginning of ``collection``. -.. 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``. +.. function:: shift!(collection) -> item -.. function:: issubset(A, S) -> Bool - ⊆(A,S) -> Bool +:: - True if A is a subset of or equal to S. + shift!(collection) -> item -Fully implemented by: +Remove the first ``item`` from ``collection``. -- :obj:`IntSet` -- :obj:`Set` -Partially implemented by: +:: -- :obj:`Array` + shift!(collection) -> item -Dequeues --------- +Remove the first ``item`` from ``collection``. -.. function:: push!(collection, items...) -> collection - Insert one or more ``items`` at the end of ``collection``. +.. function:: insert!(collection, index, item) - .. doctest:: +:: - julia> push!([1, 2, 3], 4, 5, 6) - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 + insert!(collection, index, item) - 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])``. +Insert an ``item`` into ``collection`` at the given ``index``. -.. function:: pop!(collection) -> item - Remove the last item in ``collection`` and return it. +:: - .. doctest:: + insert!(collection, index, item) - julia> A=[1, 2, 3, 4, 5, 6] - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 +Insert an ``item`` into ``collection`` at the given ``index``. - julia> pop!(A) - 6 - julia> A - 5-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 +.. function:: deleteat!(collection, index) -.. function:: unshift!(collection, items...) -> collection +:: - Insert one or more ``items`` at the beginning of ``collection``. + deleteat!(collection, itr) - .. doctest:: +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> 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``. + deleteat!(collection, itr) - .. doctest:: +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> A = [1, 2, 3, 4, 5, 6] - 6-element Array{Int64,1}: - 1 - 2 - 3 - 4 - 5 - 6 - julia> shift!(A) - 1 +.. function:: deleteat!(collection, itr) - julia> A - 5-element Array{Int64,1}: - 2 - 3 - 4 - 5 - 6 +:: -.. function:: insert!(collection, index, item) + deleteat!(collection, itr) - Insert an ``item`` into ``collection`` at the given ``index``. - ``index`` is the index of ``item`` in the resulting ``collection``. +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> insert!([6, 5, 4, 2, 1], 4, 3) - 6-element Array{Int64,1}: - 6 - 5 - 4 - 3 - 2 - 1 +:: -.. function:: deleteat!(collection, index) + 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. - .. doctest:: - julia> deleteat!([6, 5, 4, 3, 2, 1], 2) - 5-element Array{Int64,1}: - 6 - 4 - 3 - 2 - 1 +.. function:: splice!(collection, index, [replacement]) -> item -.. 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. + splice!(collection, range[, replacement]) -> items - .. doctest:: +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> 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 + splice!(collection, range[, replacement]) -> items -.. function:: splice!(collection, index, [replacement]) -> item +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 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)``. .. 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)``. + splice!(collection, range[, replacement]) -> items - .. doctest:: +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!(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. +:: + + resize!(collection, n) -> collection - .. doctest:: +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 - .. code-block:: julia +:: + + 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], 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``. +:: + + 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)``. - .. doctest:: - julia> append!([1],[2,3]) - 3-element Array{Int64,1}: - 1 - 2 - 3 +:: - .. doctest:: + append!(collection, collection2) -> collection. - 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 :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)``. .. function:: prepend!(collection, items) -> collection - Insert the elements of ``items`` to the beginning of ``collection``. +:: + + prepend!(collection, items) -> collection + +Insert the elements of ``items`` to the beginning of + + +:: - .. doctest:: + prepend!(collection, items) -> collection + +Insert the elements of ``items`` to the beginning of - julia> prepend!([3],[1,2]) - 3-element Array{Int64,1}: - 1 - 2 - 3 Fully implemented by: @@ -1098,21 +2182,67 @@ 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 + + +:: + + 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 + + +:: + + 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. +:: + + dequeue!(pq) + +Remove and return the lowest priority key from a priority queue. + + +:: + + 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. +:: + + peek(pq) + +Return the lowest priority key from a priority queue without removing that key from the queue. + + +:: + + 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 +2276,81 @@ 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. + + +:: + + 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()``. + + +:: + + heapify!(v[, ord]) + +In-place ``heapify()``. + .. function:: isheap(v, [ord]) - Return true iff an array is heap-ordered according to the given order. +:: + + isheap(v[, ord]) + +Return true iff an array is heap-ordered according to the given order. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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..b366ed0c2e40c 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -49,53 +49,83 @@ 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 +133,696 @@ 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. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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``. +:: + + Date(dt::AbstractString, df::DateFormat) -> Date + +Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + + +:: + + 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. + + +:: + + 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. + + +:: + + now(::Type{UTC}) -> DateTime + +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. +:: + + eps(::DateTime) -> Millisecond + +Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. + + +:: + + 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 - Return the field part of a Date or DateTime as an ``Int64``. +:: + + year(dt::TimeType) -> Int64 + +Return the field part of a Date or DateTime as an ``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``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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.``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. +:: + + monthname(dt::TimeType; locale="english") -> AbstractString + +Return the full name of the month of the Date or DateTime in the given ``locale``. + + +:: + + 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``. +:: + + monthabbr(dt::TimeType; locale="english") -> AbstractString + +Return the abbreviated month name of the Date or DateTime in the given ``locale``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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]]) + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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, + + +:: + + 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, + + +:: + + 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. + + +:: + + 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. + + +:: + + 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,59 +836,150 @@ 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``. + + +:: + + 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. + + +:: + + 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()``. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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 - ``-4713-11-24T12:00:00`` and returns the corresponding DateTime. +:: + + julian2datetime(julian_days) -> DateTime + +Takes the number of Julian calendar days since epoch + + +:: + + 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``. +:: + + 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 + + +:: + + 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. + + +:: + + 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..7fb8e7a630626 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -7,285 +7,913 @@ .. function:: pwd() -> AbstractString - Get the current working directory. +:: + + pwd() -> AbstractString + +Get the current working directory. + + +:: + + 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. + + +:: + + 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. +:: + + cd(f[, dir]) + +Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. + + +:: + + 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). + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. +:: + + symlink(target, link) + +Creates a symbolic link to ``target`` with the name ``link``. Note: This function raises an error under operating systems that - .. 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 - Returns the value of a symbolic link ``path``. +:: + + readlink(path) -> AbstractString + +Returns the value of a symbolic link ``path``. + + +:: + + 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 + + +:: + + 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: - - ========= ====================================================================== - 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: + + +:: + + 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. +:: + + 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(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 +:: + + ctime(file) + +Equivalent to stat(file).ctime + + +:: + + ctime(file) + +Equivalent to stat(file).ctime + .. function:: mtime(file) - Equivalent to stat(file).mtime +:: + + mtime(file) + +Equivalent to stat(file).mtime + + +:: + + mtime(file) + +Equivalent to stat(file).mtime + .. function:: filemode(file) - Equivalent to stat(file).mode +:: + + filemode(file) + +Equivalent to stat(file).mode + + +:: + + filemode(file) + +Equivalent to stat(file).mode + .. function:: filesize(path...) - Equivalent to stat(file).size +:: + + filesize(path...) + +Equivalent to stat(file).size + + +:: + + filesize(path...) + +Equivalent to stat(file).size + .. function:: uperm(file) - Gets the permissions of the owner of the file as a bitfield of +:: + + uperm(file) + +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 - ==== ===================== +:: + + uperm(file) + +Gets the permissions of the owner of the file as a bitfield of 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 +:: + + gperm(file) + +Like uperm but gets the permissions of the group owning the 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 + + +:: + + 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`. +:: + + 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(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. - 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. + + +:: + + 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*. - \"remove_destination=true\" will first remove an existing `dst`. +:: + + mv(src::AbstractString, dst::AbstractString; remove_destination::Bool=false) + +Move the file, link, or directory from *src* to *dest*. + + +:: + + 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 ``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. + + +:: + + 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. +:: + + touch(path::AbstractString) + +Update the last-modified timestamp on a file to the current time. + + +:: + + touch(path::AbstractString) + +Update the last-modified timestamp on a file to the current time. + .. function:: tempname() - Generate a unique temporary file path. +:: + + tempname() + +Generate a unique temporary file path. + + +:: + + tempname() + +Generate a unique temporary file path. + .. function:: tempdir() - Obtain the path of a temporary directory (possibly shared with other processes). +:: + + tempdir() + +Obtain the path of a temporary directory (possibly shared with other processes). + + +:: + + 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. + + +:: + + 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. +:: + + mktempdir([parent=tempdir()]) + +Create a temporary directory in the ``parent`` directory and return its path. + + +:: + + 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. +:: + + isblockdev(path) -> Bool + +Returns ``true`` if ``path`` is a block device, ``false`` otherwise. + + +:: + + 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. +:: + + ischardev(path) -> Bool + +Returns ``true`` if ``path`` is a character device, ``false`` otherwise. + + +:: + + 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. +:: + + isdir(path) -> Bool + +Returns ``true`` if ``path`` is a directory, ``false`` otherwise. + + +:: + + 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 + + +:: + + 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. +:: + + isfifo(path) -> Bool + +Returns ``true`` if ``path`` is a FIFO, ``false`` otherwise. + + +:: + + 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. +:: + + isfile(path) -> Bool + +Returns ``true`` if ``path`` is a regular file, ``false`` otherwise. + + +:: + + 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. +:: + + islink(path) -> Bool + +Returns ``true`` if ``path`` is a symbolic link, ``false`` otherwise. + + +:: + + 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. +:: + + ismount(path) -> Bool + +Returns ``true`` if ``path`` is a mount point, ``false`` otherwise. + + +:: + + 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. +:: + + ispath(path) -> Bool + +Returns ``true`` if ``path`` is a valid filesystem path, ``false`` otherwise. + + +:: + + 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 + + +:: + + 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. +:: + + issetgid(path) -> Bool + +Returns ``true`` if ``path`` has the setgid flag set, ``false`` otherwise. + + +:: + + 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. +:: + + issetuid(path) -> Bool + +Returns ``true`` if ``path`` has the setuid flag set, ``false`` otherwise. + + +:: + + 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. +:: + + issocket(path) -> Bool + +Returns ``true`` if ``path`` is a socket, ``false`` otherwise. + + +:: + + 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. +:: + + issticky(path) -> Bool + +Returns ``true`` if ``path`` has the sticky bit set, ``false`` otherwise. + + +:: + + 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 + + +:: + + iswritable(path) -> Bool + +Returns ``true`` if the current user has permission to write to + .. function:: homedir() -> AbstractString - Return the current user's home directory. +:: + + homedir() -> AbstractString + +Return the current user's home directory. + + +:: + + homedir() -> AbstractString + +Return the current user's home directory. + .. function:: dirname(path::AbstractString) -> AbstractString - Get the directory part of a path. +:: + + dirname(path::AbstractString) -> AbstractString + +Get the directory part of a path. + + +:: + + dirname(path::AbstractString) -> AbstractString + +Get the directory part of a path. + .. function:: basename(path::AbstractString) -> AbstractString - Get the file name part of a path. +:: + + basename(path::AbstractString) -> AbstractString + +Get the file name part of a path. + + +:: + + 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 ``. + + +:: + + @__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). +:: + + isabspath(path::AbstractString) -> Bool + +Determines whether a path is absolute (begins at the root directory). + + +:: + + 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). +:: + + isdirpath(path::AbstractString) -> Bool + +Determines whether a path refers to a directory (for example, ends with a path separator). + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. +:: + + splitdir(path::AbstractString) -> (AbstractString, AbstractString) + +Split a path into a tuple of the directory name and file name. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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..1738521ef2e0b 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -21,745 +21,1963 @@ 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. + + +:: + + 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: +:: + + open(f::function, args...) - ==== ================================= - r read - r+ read, write - w write, create, truncate - w+ read, write, create, truncate - a write, create, append - a+ read, write, create, append - ==== ================================= +Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + +:: + + 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. +:: + + open(f::function, args...) + +Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. +:: + + 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(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. +:: + + 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(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. + + +:: + + 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. +:: + + flush(stream) + +Commit all currently buffered writes to the given stream. + + +:: + + 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) + close(stream) - Write the canonical binary representation of a value to the given stream. +Close an I/O stream. Performs a ``flush`` first. -.. function:: read(stream, type) - Read a value of the given type from a stream, in canonical binary representation. +:: -.. function:: read(stream, type, dims) + close(stream) - 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. +Close an I/O stream. Performs a ``flush`` first. -.. function:: read!(stream, array::Array) - Read binary data from a stream, filling in the argument ``array``. +.. function:: write(stream, x) -.. 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). + write(stream, x) -.. function:: readbytes(stream, nb=typemax(Int)) +Write the canonical binary representation of a value to the given stream. - 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. + write(stream, x) -.. function:: seek(s, pos) +Write the canonical binary representation of a value to the given stream. - Seek a stream to the given position. -.. function:: seekstart(s) +.. function:: read(stream, type) - Seek a stream to its beginning. +:: -.. function:: seekend(s) + read(stream, type, dims) - Seek a stream to its end. +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:: skip(s, offset) - Seek a stream relative to the current position. +:: -.. function:: mark(s) + read(stream, type, dims) - Add a mark at the current position of stream ``s``. Returns the marked position. +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. - See also :func:`unmark`, :func:`reset`, :func:`ismarked` -.. function:: unmark(s) +.. function:: read(stream, type, dims) - Remove a mark from stream ``s``. - Returns ``true`` if the stream was marked, ``false`` otherwise. +:: - See also :func:`mark`, :func:`reset`, :func:`ismarked` + read(stream, type, dims) -.. function:: reset(s) +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. - 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` +:: -.. function:: ismarked(s) + read(stream, type, dims) - Returns true if stream ``s`` is marked. +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. - See also :func:`mark`, :func:`unmark`, :func:`reset` -.. function:: eof(stream) -> Bool +.. function:: read!(stream, array::Array) - 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 + read!(stream, array::Array) - Determine whether a stream is read-only. +Read binary data from a stream, filling in the argument ``array``. -.. 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) + read!(stream, array::Array) - 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. +Read binary data from a stream, filling in the argument ``array``. -.. function:: deserialize(stream) - Read a value written by ``serialize``. +.. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b)) -.. 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). + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) -.. function:: print_unescaped(io, s::AbstractString) +Read at most ``nb`` bytes from the stream into ``b``, returning the number of bytes read (increasing the size of ``b`` as needed). - General unescaping of traditional C and Unicode escape sequences. Reverse of :func:`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``. + readbytes!(stream, b::Vector{UInt8}, nb=length(b)) -.. function:: print_shortest(io, x) +Read at most ``nb`` bytes from the stream into ``b``, returning the number of bytes read (increasing the size of ``b`` as needed). - 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) +.. function:: readbytes(stream, nb=typemax(Int)) - 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() + readbytes(stream, nb=typemax(Int)) - 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. +Read at most ``nb`` bytes from the stream, returning a -.. 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]) + readbytes(stream, nb=typemax(Int)) - Like redirect_stdout, but for STDERR +Read at most ``nb`` bytes from the stream, returning a -.. 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:: position(s) -.. function:: readchomp(x) +:: - Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). + position(s) -.. function:: truncate(file,n) +Get the current position of a stream. - 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. + position(s) -.. function:: countlines(io,[eol::Char]) +Get the current position of a stream. - 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:: seek(s, pos) - An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. +:: -.. function:: PipeBuffer(data::Vector{UInt8},[maxsize]) + seek(s, pos) - Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. +Seek a stream to the given position. -.. 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}``. +:: + seek(s, pos) -Text I/O --------- +Seek a stream to the given position. -.. 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:: seekstart(s) -.. 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. + seekstart(s) -.. function:: showall(x) +Seek a stream to its beginning. - 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". + seekstart(s) -.. function:: print(x) +Seek a stream to its beginning. - 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) +.. function:: seekend(s) - Print (using :func:`print`) ``x`` followed by a newline. +:: -.. function:: print_with_color(color::Symbol, [io], strings...) + seekend(s) - Print strings in a color specified as a symbol, for example ``:red`` or ``:blue``. +Seek a stream to its end. -.. function:: info(msg) - Display an informational message. +:: -.. function:: warn(msg) + seekend(s) - Display a warning. +Seek a stream to its end. -.. 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:: skip(s, offset) -.. function:: @sprintf("%Fmt", args...) +:: - Return ``@printf`` formatted output as string. + skip(s, offset) -.. function:: sprint(f::Function, args...) +Seek a stream relative to the current position. - 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. + skip(s, offset) -.. function:: dump(x) +Seek a stream relative to the current position. - Show all user-visible structure of a value. -.. function:: xdump(x) +.. function:: mark(s) - Show all structure of a value, including all fields of objects. +:: -.. function:: readall(stream::IO) + mark(s) - Read the entire contents of an I/O stream as a string. +Add a mark at the current position of stream ``s``. Returns the marked position. See also ``unmark()``, ``reset()``, ``ismarked()`` -.. 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) + mark(s) - 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``), +Add a mark at the current position of stream ``s``. Returns the marked position. See also ``unmark()``, ``reset()``, ``ismarked()`` -.. function:: readuntil(stream, delim) - Read a string, up to and including the given delimiter byte. +.. function:: unmark(s) -.. function:: readlines(stream) +:: - Read all lines as an array. + unmark(s) -.. function:: eachline(stream) +Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. See also ``mark()``, ``reset()``, ``ismarked()`` - 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. + unmark(s) - 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``. +Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. See also ``mark()``, ``reset()``, ``ismarked()`` - 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. +.. function:: reset(s) - 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. + reset(s) - 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. +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()`` - 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. + reset(s) -.. function:: readdlm(source, delim::Char, eol::Char; options...) +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()`` - 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:: ismarked(s) - The end of line delimiter is taken as ``\n``. +:: -.. function:: readdlm(source, delim::Char; options...) + ismarked(s) - 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. +Returns true if stream ``s`` is marked. See also ``mark()``, ``unmark()``, ``reset()`` -.. 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``. +:: -.. function:: readdlm(source; options...) + ismarked(s) - 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. +Returns true if stream ``s`` is marked. See also ``mark()``, ``unmark()``, ``reset()`` -.. 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``). +.. function:: eof(stream) -> Bool - 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...) + eof(stream) -> Bool - Equivalent to ``readdlm`` with ``delim`` set to comma. +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:: writecsv(filename, A) - Equivalent to ``writedlm`` with ``delim`` set to comma. +:: -.. function:: Base64EncodePipe(ostream) + eof(stream) -> Bool - 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``). +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:: Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded data - read from ``istream``. +.. function:: isreadonly(stream) -> Bool -.. 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. + isreadonly(stream) -> Bool -.. function:: base64decode(string) +Determine whether a stream is read-only. - Decodes the base64-encoded ``string`` and returns a ``Vector{UInt8}`` - of the decoded bytes. -Multimedia I/O --------------- +:: -Just as text output is performed by ``print`` and user-defined types -can indicate their textual representation by overloading ``show``, -Julia provides a standardized mechanism for rich multimedia output -(such as images, formatted text, or even audio and video), consisting -of three parts: + isreadonly(stream) -> Bool -* A function ``display(x)`` to request the richest available multimedia - display of a Julia object ``x`` (with a plain-text fallback). -* Overloading ``writemime`` allows one to indicate arbitrary multimedia - representations (keyed by standard MIME types) of user-defined types. -* Multimedia-capable display backends may be registered by subclassing - a generic ``Display`` type and pushing them onto a stack of display - backends via ``pushdisplay``. +Determine whether a stream is read-only. -The base Julia runtime provides only plain-text display, but richer -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). +.. function:: isopen(stream) -> Bool -.. 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. + isopen(stream) -> Bool -.. function:: displayable(mime) -> Bool - displayable(d::Display, mime) -> 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. - 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. + isopen(stream) -> Bool -.. function:: mimewritable(mime, x) +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. - 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) +.. function:: serialize(stream, value) - 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``. + serialize(stream, value) -.. function:: stringmime(mime, x) +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 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 -this capability with Julia, so that calling ``display(x)`` on types -with PNG representations will automatically display the image using -the module's window. +:: -In order to define a new display backend, one should first create a -subtype ``D`` of the abstract class ``Display``. Then, for each MIME -type (``mime`` string) that can be displayed on ``D``, one should -define a function ``display(d::D, ::MIME"mime", x) = ...`` that -displays ``x`` as that MIME type, usually by calling ``reprmime(mime, -x)``. A ``MethodError`` should be thrown if ``x`` cannot be displayed -as that MIME type; this is automatic if one calls ``reprmime``. -Finally, one should define a function ``display(d::D, x)`` that -queries ``mimewritable(mime, x)`` for the ``mime`` types supported by -``D`` and displays the "best" one; a ``MethodError`` should be thrown -if no supported MIME types are found for ``x``. Similarly, some -subtypes may wish to override ``redisplay(d::D, ...)``. (Again, one -should ``import Base.display`` to add new methods to ``display``.) -The return values of these functions are up to the implementation -(since in some cases it may be useful to return a display "handle" of -some type). The display functions for ``D`` can then be called -directly, but they can also be invoked automatically from -``display(x)`` simply by pushing a new display onto the display-backend -stack with: + serialize(stream, value) -.. function:: pushdisplay(d::Display) +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. - 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) +.. function:: deserialize(stream) - Pop the topmost backend off of the display-backend stack, or the - topmost copy of ``d`` in the second variant. +:: -.. function:: TextDisplay(stream) + deserialize(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.) +Read a value written by ``serialize``. -.. function:: istext(m::MIME) - Determine whether a MIME type is text data. +:: -Memory-mapped I/O ------------------ + deserialize(stream) -.. function:: mmap_array(type, dims, stream, [offset]) +Read a value written by ``serialize``. - 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). +.. function:: print_escaped(io, str::AbstractString, esc::AbstractString) - ``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. + print_escaped(io, str::AbstractString, esc::AbstractString) - 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. +General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). - 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) + print_escaped(io, str::AbstractString, esc::AbstractString) - creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. +General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). - 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]) +.. function:: print_unescaped(io, s::AbstractString) - 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)`` + print_unescaped(io, s::AbstractString) - This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. +General unescaping of traditional C and Unicode escape sequences. Reverse of ``print_escaped()``. -.. function:: msync(array) - Forces synchronization between the in-memory version of a memory-mapped ``Array`` or ``BitArray`` and the on-disk version. +:: -Network I/O ------------ + print_unescaped(io, s::AbstractString) -.. function:: connect([host],port) -> TcpSocket +General unescaping of traditional C and Unicode escape sequences. Reverse of ``print_escaped()``. - Connect to the host ``host`` on port ``port`` -.. function:: connect(path) -> Pipe +.. function:: print_joined(io, items, delim, [last]) - Connect to the Named Pipe/Domain Socket at ``path`` +:: -.. function:: listen([addr,]port) -> TcpServer + print_joined(io, items, delim[, last]) - 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. +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:: listen(path) -> PipeServer - Listens on/Creates a Named Pipe/Domain Socket +:: -.. function:: getaddrinfo(host) + print_joined(io, items, delim[, last]) - Gets the IP address of the ``host`` (may have to do a DNS lookup) +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:: parseip(addr) - Parse a string specifying an IPv4 or IPv6 ip address. +.. function:: print_shortest(io, x) -.. function:: IPv4(host::Integer) -> IPv4 +:: - Returns IPv4 object from ip address formatted as Integer + print_shortest(io, x) -.. function:: IPv6(host::Integer) -> IPv6 +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. - 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. + print_shortest(io, x) -.. function:: accept(server[,client]) +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. - 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:: fd(stream) - 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) + fd(stream) - 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. +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:: 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. +:: -.. function:: poll_file(s, interval_seconds::Real, seconds::Real) + fd(stream) - 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. +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:: 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:: redirect_stdout() -.. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) +:: - Send ``msg`` over ``socket to ``host:port``. + redirect_stdout(stream) -.. function:: recv(socket::UDPSocket) +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. - 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. + redirect_stdout(stream) -.. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) +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. - 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) +.. function:: redirect_stdout(stream) - Converts the endianness of a value from Network byte order (big-endian) to - that used by the Host. +:: -.. function:: hton(x) + redirect_stdout(stream) - Converts the endianness of a value from that used by the Host to Network - byte order (big-endian). +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:: ltoh(x) - Converts the endianness of a value from Little-endian to that used by the - Host. +:: -.. function:: htol(x) + 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 + + +:: + + 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. + + +:: + + 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)). + + +:: + + readchomp(x) + +Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). + + +.. function:: truncate(file,n) + +:: + + truncate(file, n) + +Resize the file or buffer given by the first argument to exactly 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) + +:: + + 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(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]) + +:: + + 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() + +:: + + 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(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. + + +:: + + 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}``. + + +:: + + 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) + +:: + + 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) + +:: + + 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. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + println(x) + +Print (using ``print()``) ``x`` followed by a newline. + + +.. 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 + + +:: + + 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. + + +:: + + info(msg) + +Display an informational message. + + +.. function:: warn(msg) + +:: + + warn(msg) + +Display a warning. + + +:: + + 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. + + +:: + + @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. + + +:: + + @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. + + +:: + + 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. + + +:: + + showerror(io, e) + +Show a descriptive representation of an exception object. + + +.. function:: dump(x) + +:: + + dump(x) + +Show all user-visible structure of a value. + + +:: + + 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. + + +:: + + xdump(x) + +Show all structure of a value, including all fields of objects. + + +.. function:: readall(stream::IO) + +:: + + 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:: readall(filename::AbstractString) + +:: + + 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) + +:: + + readline(stream=STDIN) + +Read a single line of text, including a trailing newline character + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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='#') + +:: + + 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(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...) + +:: + + 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(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...) + +:: + + 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(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...) + +:: + + 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(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...) + +:: + + 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(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. + + +:: + + 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') + +:: + + 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(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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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 + + +:: + + base64decode(string) + +Decodes the base64-encoded ``string`` and returns a + + +Multimedia I/O +-------------- + +Just as text output is performed by ``print`` and user-defined types +can indicate their textual representation by overloading ``show``, +Julia provides a standardized mechanism for rich multimedia output +(such as images, formatted text, or even audio and video), consisting +of three parts: + +* A function ``display(x)`` to request the richest available multimedia + display of a Julia object ``x`` (with a plain-text fallback). +* Overloading ``writemime`` allows one to indicate arbitrary multimedia + representations (keyed by standard MIME types) of user-defined types. +* Multimedia-capable display backends may be registered by subclassing + a generic ``Display`` type and pushing them onto a stack of display + backends via ``pushdisplay``. + +The base Julia runtime provides only plain-text display, but richer +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(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(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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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) + +:: + + 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(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``. + + +:: + + 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. + + +:: + + 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 +this capability with Julia, so that calling ``display(x)`` on types +with PNG representations will automatically display the image using +the module's window. + +In order to define a new display backend, one should first create a +subtype ``D`` of the abstract class ``Display``. Then, for each MIME +type (``mime`` string) that can be displayed on ``D``, one should +define a function ``display(d::D, ::MIME"mime", x) = ...`` that +displays ``x`` as that MIME type, usually by calling ``reprmime(mime, +x)``. A ``MethodError`` should be thrown if ``x`` cannot be displayed +as that MIME type; this is automatic if one calls ``reprmime``. +Finally, one should define a function ``display(d::D, x)`` that +queries ``mimewritable(mime, x)`` for the ``mime`` types supported by +``D`` and displays the "best" one; a ``MethodError`` should be thrown +if no supported MIME types are found for ``x``. Similarly, some +subtypes may wish to override ``redisplay(d::D, ...)``. (Again, one +should ``import Base.display`` to add new methods to ``display``.) +The return values of these functions are up to the implementation +(since in some cases it may be useful to return a display "handle" of +some type). The display functions for ``D`` can then be called +directly, but they can also be invoked automatically from +``display(x)`` simply by pushing a new display onto the display-backend +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``). + + +:: + + 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. + + +:: + + 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.) + + +:: + + 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. + + +:: + + istext(m::MIME) + +Determine whether a MIME type is text data. + + +Memory-mapped I/O +----------------- + +.. 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 + + +:: + + 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]) + +:: + + 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([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) + +:: + + 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. + + +:: + + 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(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(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(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(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(path) -> PipeServer + +Listens on/Creates a Named Pipe/Domain Socket + + +:: + + 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 + + +:: + + 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) + + +:: + + 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. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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. + + +:: + + 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]) + +:: + + 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) + +:: + + 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(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(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``, + + +:: + + 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. + + +:: + + 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. + + +:: + + 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(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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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). + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 12d8a6f33d562..0114480043966 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -6,64 +6,195 @@ .. function:: malloc(size::Integer) -> Ptr{Void} - Call ``malloc`` from the C standard library. +:: + + malloc(size::Integer) -> Ptr{Void} + +Call ``malloc`` from the C standard library. + + +:: + + 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. +:: + + calloc(num::Integer, size::Integer) -> Ptr{Void} + +Call ``calloc`` from the C standard library. + + +:: + + 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. +:: + + 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``. - 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. + + +:: + + 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``. +:: + + 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. + + +:: + + 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. - 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 +:: + + strerror(n) + +Convert a system call error code to a descriptive string + + +:: + + 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. +:: + + time(t::TmStruct) + +Converts a ``TmStruct`` struct to a number of seconds since the epoch. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``, + + +:: + + 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). + + +:: + + 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. +:: + + 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. + + +:: + + 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. - 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 +210,33 @@ .. function:: mmap(len, prot, flags, fd, offset) - Low-level interface to the ``mmap`` system call. See the man page. +:: + + mmap(len, prot, flags, fd, offset) + +Low-level interface to the ``mmap`` system call. See the man page. + + +:: + + 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. + + +:: + + 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..318ec6ec952b0 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -6,23 +6,35 @@ .. 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. + + +:: + + 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. + + +:: + + dlopen_e(libfile::AbstractString[, flags::Integer]) + +Similar to ``dlopen()``, except returns a ``NULL`` pointer instead of raising errors. + .. data:: RTLD_DEEPBIND @@ -58,22 +70,67 @@ .. function:: dlsym(handle, sym) - Look up a symbol from a shared library handle, return callable function pointer on success. +:: + + dlsym(handle, sym) + +Look up a symbol from a shared library handle, return callable function pointer on success. + + +:: + + 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. +:: + + dlsym_e(handle, sym) + +Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. + + +:: + + 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. +:: + + dlclose(handle) + +Close shared library referenced by 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 + + +:: + + 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..78ce60b2e982e 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -14,9 +14,20 @@ 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. + + +:: + + *(s, t) + +Concatenate strings. The ``*`` operator is an alias to this function. + .. function:: \\(A, B) :noindex: @@ -26,1016 +37,2410 @@ 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) - Compute the dot product. For complex vectors, the first vector is conjugated. +:: + + dot(x, y) + +Compute the dot product. For complex vectors, the first vector is conjugated. + + +:: + + 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 + + +:: + + 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) - Compute the cross product of two 3-vectors. +:: + + cross(x, y) + +Compute the cross product of two 3-vectors. + + +:: + + 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: + + +:: + + 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. + + +:: + + 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``. +:: + + lu(A) -> L, U, p + +Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. + + +:: + + 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: + + +:: + + 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. + + +:: + + 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}``. +:: -.. function:: cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + chol(A[, LU]) -> F - 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. +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 [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + chol(A[, LU]) -> F - ``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)``. +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:: 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. +.. function:: cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky -.. 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. + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor -.. function:: qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] +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 (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 [,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}``). + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - ================ ================= ============== ===================================== - 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]`` - ================ ================= ============== ===================================== +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. - ``BlasFloat`` refers to any of: ``Float32``, ``Float64``, ``Complex64`` or ``Complex128``. - The individual components of the factorization ``F`` can be accessed by indexing: +.. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - =========== ============================================= ================== ===================== ================== - 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. + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - 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``. +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. - .. 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: + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - .. math:: +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. - 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. +.. function:: cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - The data contained in ``QRCompactWY`` can be used to construct the ``QRCompactWYQ`` type, which is a compact representation of the rotation matrix +:: - .. math:: + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - Q = I + Y T Y^T +overwriting the input ``A``, instead of creating a copy. different matrix ``F`` with the same structure when used as: - 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 +:: -.. function:: qrfact(A) -> SPQR.Factorization + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - 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. +overwriting the input ``A``, instead of creating a copy. different matrix ``F`` with the same structure when used as: -.. 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. +.. function:: ldltfact(A) -> LDLtFactorization -.. 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. + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - 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. +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:: 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``. +:: -.. [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 `_. + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor -.. function:: bkfact!(A) -> BunchKaufman +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. - ``bkfact!`` is the same as :func:`bkfact`, but saves space by overwriting the input ``A``, instead of creating a copy. -.. function:: sqrtm(A) +.. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - 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. + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor -.. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V +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. - 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) + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the - factorization to a tuple; where possible, using :func:`eigfact` is - recommended. +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:: eig(A, B) -> D, V - Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. +.. function:: qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] - ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the - factorization to a tuple; where possible, using :func:`eigfact` is - recommended. +:: -.. function:: eigvals(A,[irange,][vl,][vu]) + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] - 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. +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. - 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``. + qr(A[, pivot=Val{false}][;thin=true]) -> Q, R, [p] -.. function:: eigmin(A) +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. - Returns the smallest eigenvalue of ``A``. -.. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix +.. function:: qrfact(A [,pivot=Val{false}]) -> F - 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. + qrfact(A) -> SPQR.Factorization -.. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen +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. - 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. + qrfact(A) -> SPQR.Factorization - 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. +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:: 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:: qrfact(A) -> SPQR.Factorization -.. function:: eigfact!(A, [B]) +:: - Same as :func:`eigfact`, but saves space by overwriting the input ``A`` (and - ``B``), instead of creating a copy. + qrfact(A) -> SPQR.Factorization -.. function:: hessfact(A) +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 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`. -.. function:: hessfact!(A) +:: - ``hessfact!`` is the same as :func:`hessfact`, but saves space by overwriting the input A, instead of creating a copy. + qrfact(A) -> SPQR.Factorization -.. function:: schurfact(A) -> Schur +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. - 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]``. -.. function:: schurfact!(A) +.. function:: qrfact!(A [,pivot=Val{false}]) - Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See :func:`schurfact` +:: -.. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + qrfact!(A[, pivot=Val{false}]) - See :func:`schurfact` +instead of creating a copy. -.. 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``. +:: -.. function:: ordschur!(Q, T, select) -> Schur + qrfact!(A[, pivot=Val{false}]) - Reorders the Schur factorization of a real matrix ``A=Q*T*Q'``, overwriting ``Q`` and ``T`` in the process. See :func:`ordschur` +instead of creating a copy. -.. function:: ordschur(S, select) -> Schur - Reorders the Schur factorization ``S`` of type ``Schur``. +.. function:: full(QRCompactWYQ[, thin=true]) -> Matrix -.. function:: ordschur!(S, select) -> Schur +:: - Reorders the Schur factorization ``S`` of type ``Schur``, overwriting ``S`` in the process. See :func:`ordschur` + full(QRCompactWYQ[, thin=true]) -> Matrix -.. function:: schurfact(A, B) -> GeneralizedSchur +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. - 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 :func:`schurfact` + full(QRCompactWYQ[, thin=true]) -> Matrix -.. function:: ordschur(S, T, Q, Z, select) -> GeneralizedSchur +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. - 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]``. -.. function:: ordschur!(S, T, Q, Z, select) -> GeneralizedSchur +.. function:: bkfact(A) -> BunchKaufman - Reorders the Generalized Schur factorization of a matrix by overwriting the matrices ``(S, T, Q, Z)`` in the process. See :func:`ordschur`. +:: -.. function:: ordschur(GS, select) -> GeneralizedSchur + bkfact(A) -> BunchKaufman - Reorders the Generalized Schur factorization of a Generalized Schur object. See :func:`ordschur`. +Compute the Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix ``A`` and return a -.. 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`. +:: -.. function:: svdfact(A, [thin=true]) -> SVD + bkfact(A) -> BunchKaufman - 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 Bunch-Kaufman [Bunch1977] factorization of a real symmetric or complex Hermitian matrix ``A`` and return a -.. 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. +.. [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:: svd(A, [thin=true]) -> U, S, V +.. function:: bkfact!(A) -> BunchKaufman - 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. +:: -.. function:: svdvals(A) + bkfact!(A) -> BunchKaufman - Returns the singular values of ``A``. +overwriting the input ``A``, instead of creating a copy. -.. function:: svdvals!(A) - Returns the singular values of ``A``, while saving space by overwriting the input. +:: -.. function:: svdfact(A, B) -> GeneralizedSVD + bkfact!(A) -> BunchKaufman - 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]'``. +overwriting the input ``A``, instead of creating a copy. -.. 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'``. +.. function:: sqrtm(A) -.. function:: svdvals(A, B) +:: - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + sqrtm(A) -.. function:: triu(M) +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. - Upper triangle of a matrix. -.. function:: triu(M, k) +:: - Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal. + sqrtm(A) -.. function:: triu!(M) +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. - Upper triangle of a matrix, overwriting ``M`` in the process. -.. function:: triu!(M, k) +.. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V - Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. +:: -.. function:: tril(M) + eig(A, B) -> D, V - Lower triangle of a matrix. +Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. -.. function:: tril(M, k) - Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal. +:: -.. function:: tril!(M) + eig(A, B) -> D, V - Lower triangle of a matrix, overwriting ``M`` in the process. +Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. -.. function:: tril!(M, k) - Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal, overwriting ``M`` in the process. +.. function:: eig(A, B) -> D, V -.. function:: diagind(M[, k]) +:: - A ``Range`` giving the indices of the ``k``\ th diagonal of the matrix ``M``. + eig(A, B) -> D, V -.. function:: diag(M[, k]) +Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. - 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. + eig(A, B) -> D, V -.. function:: scale(A, b) -.. function:: scale(b, A) +Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. the factorization to a tuple; where possible, using ``eigfact()`` is recommended. - 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. +.. function:: eigvals(A,[irange,][vl,][vu]) - 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) + eigvals(A,[irange,][vl,][vu]) - Scale an array ``A`` by a scalar ``b``, similar to :func:`scale` but - overwriting ``A`` in-place. +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. - 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 :func:`full`. + eigvals(A,[irange,][vl,][vu]) -.. function:: Bidiagonal(dv, ev, isupper) +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. - 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`. -.. function:: SymTridiagonal(d, du) +.. function:: eigmax(A) - 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`. +:: -.. function:: rank(M) + eigmax(A) - Compute the rank of a matrix. +Returns the largest eigenvalue of ``A``. -.. 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. + eigmax(A) - 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. +Returns the largest eigenvalue of ``A``. -.. 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. +.. function:: eigmin(A) - For example, if ``A`` is a matrix and ``p=2``, then this is equivalent - to the Frobenius norm. +:: -.. function:: cond(M, [p]) + eigmin(A) - Condition number of the matrix ``M``, computed using the operator ``p``-norm. Valid values for ``p`` are ``1``, ``2`` (default), or ``Inf``. +Returns the smallest eigenvalue of ``A``. -.. 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``. + eigmin(A) - This quantity is also known in the literature as the Bauer condition number, relative condition number, or componentwise relative condition number. +Returns the smallest eigenvalue of ``A``. -.. function:: trace(M) - Matrix trace +.. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix -.. function:: det(M) +:: - Matrix determinant + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix -.. function:: logdet(M) +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. - Log of matrix determinant. Equivalent to ``log(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. + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix -.. function:: inv(M) +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. - Matrix inverse -.. function:: pinv(M[, tol]) +.. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen - 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 `_ +:: -.. function:: nullspace(M) + eigfact(A, B) -> GeneralizedEigen - Basis for nullspace of ``M``. +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:: 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[]) + eigfact(A, B) -> GeneralizedEigen - 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. +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:: kron(A, B) - Kronecker tensor product of two vectors or two matrices. +.. function:: eigfact(A, B) -> GeneralizedEigen -.. function:: blkdiag(A...) +:: - Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. + eigfact(A, B) -> GeneralizedEigen -.. function:: linreg(x, y) -> [a; b] +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]``.) - 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 + eigfact(A, B) -> GeneralizedEigen -.. function:: linreg(x, y, w) +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]``.) - Weighted least-squares linear regression. -.. function:: expm(A) +.. function:: eigfact!(A, [B]) - Matrix exponential. +:: -.. function:: lyap(A, C) + eigfact!(A[, B]) - 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. +Same as ``eigfact()``, but saves space by overwriting the input -.. 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. +:: -.. function:: issym(A) -> Bool + eigfact!(A[, B]) - Test whether a matrix is symmetric. +Same as ``eigfact()``, but saves space by overwriting the input -.. function:: isposdef(A) -> Bool - Test whether a matrix is positive definite. +.. function:: hessfact(A) -.. function:: isposdef!(A) -> Bool +:: - Test whether a matrix is positive definite, overwriting ``A`` in the processes. + hessfact(A) -.. function:: istril(A) -> Bool +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()``. - Test whether a matrix is lower triangular. -.. function:: istriu(A) -> Bool +:: - Test whether a matrix is upper triangular. + hessfact(A) -.. function:: isdiag(A) -> Bool +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()``. - Test whether a matrix is diagonal. -.. function:: ishermitian(A) -> Bool +.. function:: hessfact!(A) - Test whether a matrix is Hermitian. +:: -.. function:: transpose(A) + hessfact!(A) - The transposition operator (``.'``). +overwriting the input A, instead of creating a copy. -.. 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. +:: -.. function:: ctranspose(A) + hessfact!(A) - The conjugate transposition operator (``'``). +overwriting the input A, instead of creating a copy. -.. 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:: schurfact(A) -> Schur + +:: -.. 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) + schurfact(A, B) -> GeneralizedSchur - 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}` - =============== ================================== ================================== +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:: 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`. + schurfact(A, B) -> GeneralizedSchur - **Example**:: +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 - X = sprand(10, 5, 0.2) - svds(X, nsv = 2) -.. function:: peakflops(n; parallel=false) +.. function:: schurfact!(A) - ``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. + schurfact!(A) -BLAS Functions --------------- +Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See ``schurfact()`` -.. module:: Base.LinAlg.BLAS -:mod:`Base.LinAlg.BLAS` provides wrappers for some of the BLAS functions for -linear algebra. Those BLAS functions that overwrite one of the input -arrays have names ending in ``'!'``. +:: -Usually a function has 4 methods defined, one each for ``Float64``, -``Float32``, ``Complex128`` and ``Complex64`` arrays. + schurfact!(A) -.. currentmodule:: Base.LinAlg.BLAS +Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See ``schurfact()`` -.. 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``. +.. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] -.. function:: dotu(n, X, incx, Y, incy) +:: - Dot function for two complex vectors. + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] -.. function:: dotc(n, X, incx, U, incy) +See ``schurfact()`` - 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``. + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] -.. function:: nrm2(n, X, incx) +See ``schurfact()`` - 2-norm of a vector consisting of ``n`` elements of array ``X`` with - stride ``incx``. -.. function:: asum(n, X, incx) +.. function:: ordschur(Q, T, select) -> Schur - sum of the absolute values of the first ``n`` elements of array ``X`` with - stride ``incx``. +:: -.. function:: axpy!(a, X, Y) + ordschur(GS, select) -> GeneralizedSchur - Overwrite ``Y`` with ``a*X + Y``. Returns ``Y``. +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. function:: scal!(n, a, X, incx) - Overwrite ``X`` with ``a*X``. Returns ``X``. +:: -.. function:: scal(n, a, X, incx) + ordschur(GS, select) -> GeneralizedSchur - Returns ``a*X``. +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. function:: ger!(alpha, x, y, A) - Rank-1 update of the matrix ``A`` with vectors ``x`` and - ``y`` as ``alpha*x*y' + A``. +.. function:: ordschur!(Q, T, select) -> Schur -.. 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``. + ordschur!(GS, select) -> GeneralizedSchur -.. function:: syrk!(uplo, trans, alpha, A, beta, C) +Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - 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'). + ordschur!(GS, select) -> GeneralizedSchur -.. function:: her!(uplo, alpha, x, A) +Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See - 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) +.. function:: ordschur(S, select) -> Schur - 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) + ordschur(GS, select) -> GeneralizedSchur - 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'). +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. 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``. +:: -.. function:: gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + ordschur(GS, select) -> GeneralizedSchur - 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. +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. -.. 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/. +.. function:: ordschur!(S, select) -> Schur - Returns the updated ``y``. +:: -.. function:: sbmv(uplo, k, alpha, A, x) + ordschur!(GS, select) -> GeneralizedSchur - 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``. +Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See -.. 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``. +:: -.. function:: gemm!(tA, tB, alpha, A, B, beta, C) + ordschur!(GS, select) -> GeneralizedSchur - Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. Returns the - updated ``C``. +Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See -.. function:: gemm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. +.. function:: schurfact(A, B) -> GeneralizedSchur -.. function:: gemm(tA, tB, A, B) +:: - Returns ``A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + schurfact(A, B) -> GeneralizedSchur -.. function:: gemv!(tA, alpha, A, x, beta, y) +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 - 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, alpha, A, x) +:: - Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` - (transpose ``A``). + schurfact(A, B) -> GeneralizedSchur -.. function:: gemv(tA, A, x) +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 - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). -.. function:: symm!(side, ul, alpha, A, B, beta, C) +.. function:: schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - 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(side, ul, alpha, A, B) + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - 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. +See ``schurfact()`` -.. 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. +:: -.. function:: symm(tA, tB, alpha, A, B) + schur(A, B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. +See ``schurfact()`` -.. 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:: ordschur(S, T, Q, Z, select) -> GeneralizedSchur -.. function:: symv(ul, alpha, A, x) +:: - Returns ``alpha*A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + ordschur(GS, select) -> GeneralizedSchur -.. function:: symv(ul, A, x) +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - 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``. + ordschur(GS, select) -> GeneralizedSchur -.. function:: trmm(side, ul, tA, dA, alpha, A, B) +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. - 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) +.. function:: ordschur!(S, T, Q, Z, select) -> GeneralizedSchur - 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) + ordschur!(GS, select) -> GeneralizedSchur - 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). +Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See -.. 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``. +:: -.. function:: trmv(side, ul, tA, dA, alpha, A, b) + ordschur!(GS, select) -> GeneralizedSchur - 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). +Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See -.. 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``. +.. function:: ordschur(GS, select) -> GeneralizedSchur -.. 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). + ordschur(GS, select) -> GeneralizedSchur -.. function:: blas_set_num_threads(n) +Reorders the Generalized Schur factorization of a Generalized Schur object. See ``ordschur()``. + + +:: + + 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 + + +:: + + 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 + +:: + + 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(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!(A[, thin=true]) -> SVD + +overwriting the input A, instead of creating a copy. If ``thin`` 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 + +:: + + 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(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) + +:: + + svdvals(A, B) + +Return only the singular values from the generalized singular value decomposition of ``A`` and ``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. + + +:: + + 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]'`. + + +:: + + 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'``. + + +:: + + 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``. + + +:: + + svdvals(A, B) + +Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + + +.. function:: triu(M) + +:: + + 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, k) + +:: + + 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) + +:: + + 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:: triu!(M, k) + +:: + + 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) + +:: + + 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, k) + +:: + + 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) + +:: + + 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:: tril!(M, k) + +:: + + 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]) + +:: + + 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]) + +:: + + 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]) + +:: + + 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) + +:: + + 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(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. + + +:: + + 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) + +:: + + 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!(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``. + + +:: + + 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()``. + + +:: + + 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()``. + + +:: + + 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()``. + + +:: + + 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. + + +:: + + rank(M) + +Compute the rank of a matrix. + + +.. 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. + + +:: + + 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]) + +:: + + 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(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]) + +:: + + cond(M[, p]) + +Condition number of the matrix ``M``, computed using the operator + + +:: + + cond(M[, p]) + +Condition number of the matrix ``M``, computed using the operator + + +.. 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. + + +:: + + 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 + + +:: + + trace(M) + +Matrix trace + + +.. function:: det(M) + +:: + + det(M) + +Matrix determinant + + +:: + + 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. + + +:: + + logdet(M) + +Log of matrix determinant. Equivalent to ``log(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. + +.. function:: inv(M) + +:: + + inv(M) + +Matrix inverse + + +:: + + 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]. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + blkdiag(A...) + +Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. + + +.. function:: linreg(x, y) -> [a; b] + +:: + + linreg(x, y, w) + +Weighted least-squares 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. + + +:: + + linreg(x, y, w) + +Weighted least-squares linear regression. + + +.. function:: expm(A) + +:: + + expm(A) + +Matrix exponential. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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. + + +:: + + issym(A) -> Bool + +Test whether a matrix is symmetric. + + +.. function:: isposdef(A) -> Bool + +:: + + isposdef(A) -> Bool + +Test whether a matrix is positive definite. + + +:: + + 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. + + +:: + + 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. + + +:: + + istril(A) -> Bool + +Test whether a matrix is lower triangular. + + +.. function:: istriu(A) -> Bool + +:: + + istriu(A) -> Bool + +Test whether a matrix is upper triangular. + + +:: + + istriu(A) -> Bool + +Test whether a matrix is upper triangular. + + +.. function:: isdiag(A) -> Bool + +:: + + isdiag(A) -> Bool + +Test whether a matrix is diagonal. + + +:: + + isdiag(A) -> Bool + +Test whether a matrix is diagonal. + + +.. function:: ishermitian(A) -> Bool + +:: + + ishermitian(A) -> Bool + +Test whether a matrix is Hermitian. + + +:: + + ishermitian(A) -> Bool + +Test whether a matrix is Hermitian. + + +.. function:: transpose(A) + +:: + + transpose(A) + +The transposition operator (``.'``). + + +:: + + transpose(A) + +The transposition operator (``.'``). + + +.. 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. + + +:: + + 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 (``'``). + + +:: + + ctranspose(A) + +The conjugate transposition operator (``'``). + + +.. 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. + + +:: + + 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) + +:: + + 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(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: + + +:: + + 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. + + +:: + + 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 +-------------- + +.. module:: Base.LinAlg.BLAS + +:mod:`Base.LinAlg.BLAS` provides wrappers for some of the BLAS functions for +linear algebra. Those BLAS functions that overwrite one of the input +arrays have names ending in ``'!'``. + +Usually a function has 4 methods defined, one each for ``Float64``, +``Float32``, ``Complex128`` and ``Complex64`` arrays. + +.. currentmodule:: Base.LinAlg.BLAS + +.. 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``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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'). + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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) + +:: + + sbmv(uplo, k, A, x) + +Returns ``A*x`` where ``A`` is a symmetric band matrix of order + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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) + +:: + + gemm(tA, tB, A, B) + +Returns ``A*B`` or the other three variants according to ``tA`` + + +:: + + 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`` + + +:: + + 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 + + +:: + + 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) + +:: + + gemv(tA, A, x) + +Returns ``A*x`` or ``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``). + + +:: + + 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 + + +:: + + 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) + +:: + + symm(tA, tB, alpha, A, B) + +Returns ``alpha*A*B`` or the other three variants according to + + +:: + + symm(tA, tB, alpha, A, B) + +Returns ``alpha*A*B`` or the other three variants according to + + +.. function:: symm(side, ul, A, B) + +:: + + symm(tA, tB, alpha, A, B) + +Returns ``alpha*A*B`` or the other three variants according to + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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) + +:: + + symv(ul, A, x) + +Returns ``A*x``. ``A`` is assumed to be symmetric. Only the + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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). + + +:: + + 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``. + + +:: + + 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). + + +:: + + 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``. + + +:: + + 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). + + +:: + + 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``. + + +:: + + 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). + + +:: + + 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. + + +:: + + 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 4dea80104eb4f..f602a22eb3d9a 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -11,30 +11,87 @@ Mathematical Operators .. function:: -(x) - Unary minus operator. +:: + + -(x, y) + +Subtraction 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, ...)``. + + +:: + + +(x, y...) + +Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. ``+(x, y, z, ...)``. + .. _-: .. function:: -(x, y) - Subtraction operator. +:: + + -(x, y) + +Subtraction operator. + + +:: + + -(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. + + +:: + + *(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. + + +:: + + /(x, y) + +Right division operator: multiplication of ``x`` by the inverse of arguments. + .. _\\: .. function:: \\(x, y) @@ -45,1617 +102,4528 @@ Mathematical Operators .. _^: .. function:: ^(x, y) - Exponentiation operator. +:: -.. _.+: -.. function:: .+(x, y) + ^(s, n) - Element-wise addition operator. +Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. -.. _.-: -.. function:: .-(x, y) - Element-wise subtraction operator. +:: -.. _.*: -.. function:: .*(x, y) + ^(s, n) - Element-wise multiplication operator. +Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. -.. _./: -.. function:: ./(x, y) - Element-wise right division operator. +.. _.+: +.. function:: .+(x, y) -.. _.\\: -.. function:: .\\(x, y) +:: - Element-wise left division operator. + .+(x, y) -.. _.^: -.. function:: .^(x, y) +Element-wise addition 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``. + .+(x, y) -.. function:: muladd(x, y, z) +Element-wise addition operator. - 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) +.. _.-: +.. function:: .-(x, y) - The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. +:: -.. function:: fld(x, y) + .-(x, y) - Largest integer less than or equal to ``x/y``. +Element-wise subtraction operator. -.. function:: cld(x, y) - Smallest integer larger than or equal to ``x/y``. +:: -.. function:: mod(x, y) + .-(x, y) - Modulus after division, returning in the range [0,``y``), if ``y`` is - positive, or (``y``,0] if ``y`` is negative. +Element-wise subtraction operator. -.. function:: mod2pi(x) - Modulus after division by 2pi, returning in the range [0,2pi). +.. _.*: +.. function:: .*(x, y) - 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) + .*(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. +Element-wise multiplication operator. -.. function:: divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to ``(x÷y, x%y)``. +:: -.. function:: fldmod(x, y) + .*(x, y) - The floored quotient and modulus after division. Equivalent to ``(fld(x,y), mod(x,y))``. +Element-wise multiplication operator. -.. function:: mod1(x,m) - Modulus after division, returning in the range (0,m] +.. _./: +.. function:: ./(x, y) -.. function:: rem1(x,m) +:: - Remainder after division, returning in the range (0,m] + ./(x, y) -.. _//: -.. function:: //(num, den) +Element-wise right division operator. - 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``. + ./(x, y) -.. function:: num(x) +Element-wise right division operator. - Numerator of the rational representation of ``x`` -.. function:: den(x) +.. _.\\: +.. function:: .\\(x, y) - Denominator of the rational representation of ``x`` + Element-wise left division operator. -.. _<<: -.. function:: <<(x, n) +.. _.^: +.. function:: .^(x, y) - Left bit shift operator. +:: -.. _>>: -.. function:: >>(x, n) + .^(x, y) - Right bit shift operator, preserving the sign of ``x``. +Element-wise exponentiation operator. -.. _>>>: -.. function:: >>>(x, n) - Unsigned right bit shift operator. +:: -.. _\:: -.. function:: \:(start, [step], stop) + .^(x, y) - 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. +Element-wise exponentiation operator. -.. function:: colon(start, [step], stop) - Called by ``:`` syntax for constructing ranges. +.. function:: fma(x, y, z) -.. function:: range(start, [step], length) +:: - Construct a range by length, given a starting value and optional step (defaults to 1). + fma(x, y, z) -.. _==: -.. function:: ==(x, y) +Computes ``x*y+z`` without rounding the intermediate result algorithms. See ``muladd``. - 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. + fma(x, y, z) - 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. +Computes ``x*y+z`` without rounding the intermediate result algorithms. See ``muladd``. -.. _!=: -.. 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. +.. function:: muladd(x, y, z) -.. _===: -.. function:: ===(x, y) - ≡(x,y) +:: - See the :func:`is` operator + muladd(x, y, z) -.. _!==: -.. function:: !==(x, y) - ≢(x,y) +Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``, or to - 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``. + muladd(x, y, z) -.. _<=: -.. function:: <=(x, y) - ≤(x,y) +Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``, or to - Less-than-or-equals comparison operator. -.. _>: -.. function:: >(x, y) +.. function:: div(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) + div(x, y) - Greater-than-or-equals comparison operator. +The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. -.. _.==: -.. function:: .==(x, y) - Element-wise equality comparison operator. +:: -.. _.!=: -.. function:: .!=(x, y) - .≠(x,y) + div(x, y) - Element-wise not-equals comparison operator. +The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. -.. _.<: -.. function:: .<(x, y) - Element-wise less-than comparison operator. +.. function:: fld(x, y) -.. _.<=: -.. function:: .<=(x, y) - .≤(x,y) +:: - Element-wise less-than-or-equals comparison operator. + fld(x, y) -.. _.>: -.. function:: .>(x, y) +Largest integer less than or equal to ``x/y``. - Element-wise greater-than comparison operator. -.. _.>=: -.. function:: .>=(x, y) - .≥(x,y) +:: - Element-wise greater-than-or-equals comparison operator. + fld(x, y) -.. function:: cmp(x,y) +Largest integer less than or equal to ``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) +.. function:: cld(x, y) - Bitwise not +:: -.. _&: -.. function:: &(x, y) + cld(x, y) - Bitwise and +Smallest integer larger than or equal to ``x/y``. -.. _|: -.. function:: |(x, y) - Bitwise or +:: -.. _$: -.. function:: $(x, y) + cld(x, y) - Bitwise exclusive or +Smallest integer larger than or equal to ``x/y``. -.. _!: -.. function:: !(x) - Boolean not +.. function:: mod(x, y) -.. _&&: -.. function:: x && y +:: - Short-circuiting boolean and + mod(x, y) -.. _||: -.. function:: x || y +Modulus after division, returning in the range [0,``y``), if ``y`` is positive, or (``y``,0] if ``y`` is negative. - Short-circuiting boolean or -.. function:: A_ldiv_Bc(a,b) +:: - Matrix operator A \\ B\ :sup:`H` + mod(x, y) -.. function:: A_ldiv_Bt(a,b) +Modulus after division, returning in the range [0,``y``), if ``y`` is positive, or (``y``,0] if ``y`` is negative. - Matrix operator A \\ B\ :sup:`T` -.. function:: A_mul_B!(Y, A, B) -> Y +.. function:: mod2pi(x) +:: - Calculates the matrix-matrix or matrix-vector product *A B* and stores the - result in *Y*, overwriting the existing value of *Y*. + mod2pi(x) - .. doctest:: +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. - 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 +:: -.. function:: A_mul_Bc(...) + mod2pi(x) - Matrix operator A B\ :sup:`H` +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:: A_mul_Bt(...) - Matrix operator A B\ :sup:`T` +.. function:: rem(x, y) -.. function:: A_rdiv_Bc(...) +:: - Matrix operator A / B\ :sup:`H` + rem(x, y) -.. function:: A_rdiv_Bt(a,b) +Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than ``y``. This value is always exact. - Matrix operator A / B\ :sup:`T` -.. function:: Ac_ldiv_B(...) +:: - Matrix operator A\ :sup:`H` \\ B + rem(x, y) -.. function:: Ac_ldiv_Bc(...) +Remainder from Euclidean division, returning a value of the same sign as``x``, and smaller in magnitude than ``y``. This value is always exact. - Matrix operator A\ :sup:`H` \\ B\ :sup:`H` -.. function:: Ac_mul_B(...) +.. function:: divrem(x, y) - Matrix operator A\ :sup:`H` B +:: -.. function:: Ac_mul_Bc(...) + divrem(x, y) - Matrix operator A\ :sup:`H` B\ :sup:`H` +The quotient and remainder from Euclidean division. Equivalent to -.. function:: Ac_rdiv_B(a,b) - Matrix operator A\ :sup:`H` / B +:: -.. function:: Ac_rdiv_Bc(a,b) + divrem(x, y) - Matrix operator A\ :sup:`H` / B\ :sup:`H` +The quotient and remainder from Euclidean division. Equivalent to -.. function:: At_ldiv_B(...) - Matrix operator A\ :sup:`T` \\ B +.. function:: fldmod(x, y) -.. function:: At_ldiv_Bt(...) +:: - Matrix operator A\ :sup:`T` \\ B\ :sup:`T` + fldmod(x, y) -.. function:: At_mul_B(...) +The floored quotient and modulus after division. Equivalent to - Matrix operator A\ :sup:`T` B -.. function:: At_mul_Bt(...) +:: - Matrix operator A\ :sup:`T` B\ :sup:`T` + fldmod(x, y) -.. function:: At_rdiv_B(a,b) +The floored quotient and modulus after division. Equivalent to - Matrix operator A\ :sup:`T` / B -.. function:: At_rdiv_Bt(a,b) +.. function:: mod1(x,m) - Matrix operator A\ :sup:`T` / B\ :sup:`T` +:: + mod1(x, m) -Mathematical Functions ----------------------- +Modulus after division, returning in the range (0,m] -.. 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))``. + mod1(x, m) - * 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. +Modulus after division, returning in the range (0,m] - * 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:: rem1(x,m) -.. function:: sin(x) +:: - Compute sine of ``x``, where ``x`` is in radians + rem1(x, m) -.. function:: cos(x) +Remainder after division, returning in the range (0,m] - Compute cosine of ``x``, where ``x`` is in radians -.. function:: tan(x) +:: - Compute tangent of ``x``, where ``x`` is in radians + rem1(x, m) -.. function:: sind(x) +Remainder after division, returning in the range (0,m] - Compute sine of ``x``, where ``x`` is in degrees -.. function:: cosd(x) +.. _//: +.. function:: //(num, den) - Compute cosine of ``x``, where ``x`` is in degrees +:: -.. function:: tand(x) + //(num, den) - Compute tangent of ``x``, where ``x`` is in degrees +Divide two integers or rational numbers, giving a ``Rational`` result. -.. function:: sinpi(x) - Compute :math:`\sin(\pi x)` more accurately than ``sin(pi*x)``, especially for large ``x``. +:: -.. function:: cospi(x) + //(num, den) - Compute :math:`\cos(\pi x)` more accurately than ``cos(pi*x)``, especially for large ``x``. +Divide two integers or rational numbers, giving a ``Rational`` result. -.. function:: sinh(x) - Compute hyperbolic sine of ``x`` +.. function:: rationalize([Type=Int,] x; tol=eps(x)) -.. function:: cosh(x) +:: - Compute hyperbolic cosine of ``x`` + rationalize([Type=Int], x; tol=eps(x)) -.. function:: tanh(x) +Approximate floating point number ``x`` as a Rational number with components of the given integer type. The result will differ from - Compute hyperbolic tangent of ``x`` -.. function:: asin(x) +:: - Compute the inverse sine of ``x``, where the output is in radians + rationalize([Type=Int], x; tol=eps(x)) -.. function:: acos(x) +Approximate floating point number ``x`` as a Rational number with components of the given integer type. The result will differ from - Compute the inverse cosine of ``x``, where the output is in radians -.. function:: atan(x) +.. function:: num(x) - Compute the inverse tangent of ``x``, where the output is in radians +:: -.. function:: atan2(y, x) + num(x) - Compute the inverse tangent of ``y/x``, using the signs of both ``x`` and ``y`` to determine the quadrant of the return value. +Numerator of the rational representation of ``x`` -.. function:: asind(x) - Compute the inverse sine of ``x``, where the output is in degrees +:: -.. function:: acosd(x) + num(x) - Compute the inverse cosine of ``x``, where the output is in degrees +Numerator of the rational representation of ``x`` -.. function:: atand(x) - Compute the inverse tangent of ``x``, where the output is in degrees +.. function:: den(x) -.. function:: sec(x) +:: - Compute the secant of ``x``, where ``x`` is in radians + den(x) -.. function:: csc(x) +Denominator of the rational representation of ``x`` - Compute the cosecant of ``x``, where ``x`` is in radians -.. function:: cot(x) +:: - Compute the cotangent of ``x``, where ``x`` is in radians + den(x) -.. function:: secd(x) +Denominator of the rational representation of ``x`` - Compute the secant of ``x``, where ``x`` is in degrees -.. function:: cscd(x) +.. _<<: +.. function:: <<(x, n) - Compute the cosecant of ``x``, where ``x`` is in degrees +:: -.. function:: cotd(x) + <<(x, n) - Compute the cotangent of ``x``, where ``x`` is in degrees +Left bit shift operator. -.. function:: asec(x) - Compute the inverse secant of ``x``, where the output is in radians +:: -.. function:: acsc(x) + <<(x, n) - Compute the inverse cosecant of ``x``, where the output is in radians +Left bit shift operator. -.. function:: acot(x) - Compute the inverse cotangent of ``x``, where the output is in radians +.. _>>: +.. function:: >>(x, n) -.. function:: asecd(x) +:: - Compute the inverse secant of ``x``, where the output is in degrees + >>(x, n) -.. function:: acscd(x) +Right bit shift operator, preserving the sign of ``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 + >>(x, n) -.. function:: sech(x) +Right bit shift operator, preserving the sign of ``x``. - Compute the hyperbolic secant of ``x`` -.. function:: csch(x) +.. _>>>: +.. function:: >>>(x, n) - Compute the hyperbolic cosecant of ``x`` +:: -.. function:: coth(x) + >>>(x, n) - Compute the hyperbolic cotangent of ``x`` +Unsigned right bit shift operator. -.. function:: asinh(x) - Compute the inverse hyperbolic sine of ``x`` +:: -.. function:: acosh(x) + >>>(x, n) - Compute the inverse hyperbolic cosine of ``x`` +Unsigned right bit shift operator. -.. function:: atanh(x) - Compute the inverse hyperbolic tangent of ``x`` +.. _\:: +.. function:: \:(start, [step], stop) -.. function:: asech(x) + 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. - Compute the inverse hyperbolic secant of ``x`` +.. function:: colon(start, [step], stop) -.. function:: acsch(x) +:: - Compute the inverse hyperbolic cosecant of ``x`` + colon(start[, step], stop) -.. function:: acoth(x) +Called by ``:`` syntax for constructing ranges. - 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`. + colon(start[, step], stop) -.. function:: cosc(x) +Called by ``:`` syntax for constructing ranges. - 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)``. -.. function:: deg2rad(x) +.. function:: range(start, [step], length) - Convert ``x`` from degrees to radians +:: -.. function:: rad2deg(x) + range(start[, step], length) - Convert ``x`` from radians to degrees +Construct a range by length, given a starting value and optional step (defaults to 1). -.. function:: hypot(x, y) - Compute the :math:`\sqrt{x^2+y^2}` avoiding overflow and underflow +:: -.. function:: log(x) + range(start[, step], length) - Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative - ``Real`` arguments. Use complex negative arguments to obtain complex - results. +Construct a range by length, given a starting value and optional step (defaults to 1). - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. -.. function:: log(b,x) +.. _==: +.. function:: ==(x, y) - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. +:: -.. function:: log2(x) + ==(x, y) - Compute the logarithm of ``x`` to base 2. Throws ``DomainError`` for negative ``Real`` arguments. +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:: log10(x) - Compute the logarithm of ``x`` to base 10. Throws ``DomainError`` for negative ``Real`` arguments. +:: -.. function:: log1p(x) + ==(x, y) - Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for ``Real`` arguments less than -1. +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. - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. -.. function:: frexp(val) +.. _!=: +.. function:: !=(x, y) - Return ``(x,exp)`` such that ``x`` has a magnitude in the interval ``[1/2, 1)`` or 0, - and val = :math:`x \times 2^{exp}`. +:: -.. function:: exp(x) + !=(x, y) - Compute :math:`e^x` +Not-equals comparison operator. Always gives the opposite answer as the fallback definition ``!=(x,y) = !(x==y)`` instead. -.. function:: exp2(x) - Compute :math:`2^x` +:: -.. function:: exp10(x) + !=(x, y) - Compute :math:`10^x` +Not-equals comparison operator. Always gives the opposite answer as the fallback definition ``!=(x,y) = !(x==y)`` instead. -.. function:: ldexp(x, n) - Compute :math:`x \times 2^n` +.. _===: +.. function:: ===(x, y) -.. 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. + ===(x, y) -.. function:: expm1(x) +See the ``is()`` operator - Accurately compute :math:`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. + ===(x, y) - .. doctest:: +See the ``is()`` operator - julia> round(1.7) - 2.0 - julia> round(1.5) - 2.0 +.. _!==: +.. function:: !==(x, y) - julia> round(2.5) - 2.0 +:: - The optional :obj:`RoundingMode` argument will change how the number gets rounded. + !==(x, y) - ``round(T, x, [r::RoundingMode])`` converts the result to type ``T``, throwing an - :exc:`InexactError` if the value is not representable. +Equivalent to ``!is(x, y)`` - ``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. + +:: + + !==(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``. + + +:: + + <(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. + + +:: + + <=(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(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. + + +:: + + >=(x, y) + +Greater-than-or-equals comparison operator. + + +.. _.==: +.. function:: .==(x, y) + +:: + + .==(x, y) + +Element-wise equality comparison operator. + + +:: + + .==(x, y) + +Element-wise equality comparison operator. + + +.. _.!=: +.. function:: .!=(x, y) + +:: + + .!=(x, y) + +Element-wise not-equals comparison operator. + + +:: + + .!=(x, y) + +Element-wise not-equals comparison operator. + + +.. _.<: +.. function:: .<(x, y) + +:: + + .<(x, y) + +Element-wise less-than comparison operator. + + +:: + + .<(x, y) + +Element-wise less-than comparison operator. + + +.. _.<=: +.. function:: .<=(x, y) + +:: + + .<=(x, y) + +Element-wise less-than-or-equals comparison operator. + + +:: + + .<=(x, y) + +Element-wise less-than-or-equals comparison operator. + + +.. _.>: +.. function:: .>(x, y) + +:: + + .>(x, y) + +Element-wise greater-than comparison operator. + + +:: + + .>(x, y) + +Element-wise greater-than comparison operator. + + +.. _.>=: +.. function:: .>=(x, y) + +:: + + .>=(x, y) + +Element-wise greater-than-or-equals comparison operator. + + +:: + + .>=(x, y) + +Element-wise greater-than-or-equals comparison operator. + + +.. 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. + + +:: + + 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 + + +:: + + ~(x) + +Bitwise not + + +.. _&: +.. function:: &(x, y) + +:: + + &(x, y) + +Bitwise and + + +:: + + &(x, y) + +Bitwise and + + +.. _|: +.. function:: |(x, y) + +:: + + |(x, y) + +Bitwise or + + +:: + + |(x, y) + +Bitwise or + + +.. _$: +.. function:: $(x, y) + +:: + + \$(x, y) + +Bitwise exclusive or + + +:: + + \$(x, y) + +Bitwise exclusive or + + +.. _!: +.. function:: !(x) + +:: + + !(x) + +Boolean not + + +:: + + !(x) + +Boolean not + + +.. _&&: +.. function:: x && y + + Short-circuiting boolean and + +.. _||: +.. function:: x || y + + Short-circuiting boolean or + +.. function:: A_ldiv_Bc(a,b) + +:: + + A_ldiv_Bc(a, b) + +Matrix operator A \ B^H + + +:: + + A_ldiv_Bc(a, b) + +Matrix operator A \ B^H + + +.. function:: A_ldiv_Bt(a,b) + +:: + + A_ldiv_Bt(a, b) + +Matrix operator A \ B^T + + +:: + + 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*. + + +:: + + 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 + + +:: + + A_mul_Bc(...) + +Matrix operator A B^H + + +.. function:: A_mul_Bt(...) + +:: + + A_mul_Bt(...) + +Matrix operator A B^T + + +:: + + A_mul_Bt(...) + +Matrix operator A B^T + + +.. function:: A_rdiv_Bc(...) + +:: + + A_rdiv_Bc(...) + +Matrix operator A / B^H + + +:: + + A_rdiv_Bc(...) + +Matrix operator A / B^H + + +.. function:: A_rdiv_Bt(a,b) + +:: + + A_rdiv_Bt(a, b) + +Matrix operator A / B^T + + +:: + + A_rdiv_Bt(a, b) + +Matrix operator A / B^T + + +.. function:: Ac_ldiv_B(...) + +:: + + Ac_ldiv_B(...) + +Matrix operator A^H \ B + + +:: + + Ac_ldiv_B(...) + +Matrix operator A^H \ B + + +.. function:: Ac_ldiv_Bc(...) + +:: + + Ac_ldiv_Bc(...) + +Matrix operator A^H \ B^H + + +:: + + Ac_ldiv_Bc(...) + +Matrix operator A^H \ B^H + + +.. function:: Ac_mul_B(...) + +:: + + Ac_mul_B(...) + +Matrix operator A^H B + + +:: + + Ac_mul_B(...) + +Matrix operator A^H B + + +.. function:: Ac_mul_Bc(...) + +:: + + Ac_mul_Bc(...) + +Matrix operator A^H B^H + + +:: + + Ac_mul_Bc(...) + +Matrix operator A^H B^H + + +.. function:: Ac_rdiv_B(a,b) + +:: + + Ac_rdiv_B(a, b) + +Matrix operator A^H / B + + +:: + + Ac_rdiv_B(a, b) + +Matrix operator A^H / B + + +.. function:: Ac_rdiv_Bc(a,b) + +:: + + Ac_rdiv_Bc(a, b) + +Matrix operator A^H / B^H + + +:: + + Ac_rdiv_Bc(a, b) + +Matrix operator A^H / B^H + + +.. function:: At_ldiv_B(...) + +:: + + At_ldiv_B(...) + +Matrix operator A^T \ B + + +:: + + At_ldiv_B(...) + +Matrix operator A^T \ B + + +.. function:: At_ldiv_Bt(...) + +:: + + At_ldiv_Bt(...) + +Matrix operator A^T \ B^T + + +:: + + At_ldiv_Bt(...) + +Matrix operator A^T \ B^T + + +.. function:: At_mul_B(...) + +:: + + At_mul_B(...) + +Matrix operator A^T B + + +:: + + At_mul_B(...) + +Matrix operator A^T B + + +.. function:: At_mul_Bt(...) + +:: + + At_mul_Bt(...) + +Matrix operator A^T B^T + + +:: + + At_mul_Bt(...) + +Matrix operator A^T B^T + + +.. function:: At_rdiv_B(a,b) + +:: + + At_rdiv_B(a, b) + +Matrix operator A^T / B + + +:: + + At_rdiv_B(a, b) + +Matrix operator A^T / B + + +.. function:: At_rdiv_Bt(a,b) + +:: + + At_rdiv_Bt(a, b) + +Matrix operator A^T / B^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)) + +:: + + 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(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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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`` + + +:: + + sinh(x) + +Compute hyperbolic sine of ``x`` + + +.. function:: cosh(x) + +:: + + cosh(x) + +Compute hyperbolic cosine of ``x`` + + +:: + + cosh(x) + +Compute hyperbolic cosine of ``x`` + + +.. function:: tanh(x) + +:: + + tanh(x) + +Compute hyperbolic tangent of ``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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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`` + + +:: + + sech(x) + +Compute the hyperbolic secant of ``x`` + + +.. function:: csch(x) + +:: + + csch(x) + +Compute the hyperbolic cosecant of ``x`` + + +:: + + csch(x) + +Compute the hyperbolic cosecant of ``x`` + + +.. function:: coth(x) + +:: + + coth(x) + +Compute the hyperbolic cotangent of ``x`` + + +:: + + coth(x) + +Compute the hyperbolic cotangent of ``x`` + + +.. function:: asinh(x) + +:: + + asinh(x) + +Compute the inverse hyperbolic sine of ``x`` + + +:: + + asinh(x) + +Compute the inverse hyperbolic sine of ``x`` + + +.. function:: acosh(x) + +:: + + acosh(x) + +Compute the inverse hyperbolic cosine of ``x`` + + +:: + + acosh(x) + +Compute the inverse hyperbolic cosine of ``x`` + + +.. function:: atanh(x) + +:: + + atanh(x) + +Compute the inverse hyperbolic tangent of ``x`` + + +:: + + atanh(x) + +Compute the inverse hyperbolic tangent of ``x`` + + +.. function:: asech(x) + +:: + + asech(x) + +Compute the inverse hyperbolic secant of ``x`` + + +:: + + asech(x) + +Compute the inverse hyperbolic secant of ``x`` + + +.. function:: acsch(x) + +:: + + acsch(x) + +Compute the inverse hyperbolic cosecant of ``x`` + + +:: + + acsch(x) + +Compute the inverse hyperbolic cosecant of ``x`` + + +.. function:: acoth(x) + +:: + + acoth(x) + +Compute the inverse hyperbolic cotangent of ``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. + + +:: + + 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)``. + + +:: + + 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 + + +:: + + deg2rad(x) + +Convert ``x`` from degrees to radians + + +.. function:: rad2deg(x) + +:: + + rad2deg(x) + +Convert ``x`` from radians to degrees + + +:: + + 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 + + +:: + + hypot(x, y) + +Compute the \sqrt{x^2+y^2} avoiding overflow and underflow + + +.. function:: log(x) + +:: + + log(b, x) + +Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + frexp(val) + +Return ``(x,exp)`` such that ``x`` has a magnitude in the interval + + +.. function:: exp(x) + +:: + + exp(x) + +Compute e^x + + +:: + + exp(x) + +Compute e^x + + +.. function:: exp2(x) + +:: + + exp2(x) + +Compute 2^x + + +:: + + exp2(x) + +Compute 2^x + + +.. function:: exp10(x) + +:: + + exp10(x) + +Compute 10^x + + +:: + + exp10(x) + +Compute 10^x + + +.. function:: ldexp(x, n) + +:: + + ldexp(x, n) + +Compute x \times 2^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. + + +:: + + 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 + + +:: + + expm1(x) + +Accurately compute e^x-1 + + +.. function:: round([T,] x, [digits, [base]], [r::RoundingMode]) + +:: + + 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(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 + + 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. .. doctest:: - julia> round(pi, 2) - 3.14 + julia> x = 1.15 + 1.15 + + julia> @sprintf "%.20f" x + "1.14999999999999991118" + + julia> x < 115//100 + true + + julia> round(x, 1) + 1.2 + +.. data:: RoundingMode + + A type which controls rounding behavior. Currently supported rounding modes are: + + - :obj:`RoundNearest` (default) + - :obj:`RoundNearestTiesAway` + - :obj:`RoundNearestTiesUp` + - :obj:`RoundToZero` + - :obj:`RoundUp` + - :obj:`RoundDown` + +.. data:: RoundNearest + + The default rounding mode. Rounds to the nearest integer, with ties + (fractional values of 0.5) being rounded to the nearest even integer. + +.. data:: RoundNearestTiesAway + + Rounds to nearest integer, with ties rounded away from zero (C/C++ + :func:`round` behaviour). + +.. data:: RoundNearestTiesUp + + Rounds to nearest integer, with ties rounded toward positive infinity + (Java/JavaScript :func:`round` behaviour). + +.. data:: RoundToZero + + :func:`round` using this rounding mode is an alias for :func:`trunc`. + +.. data:: RoundUp + + :func:`round` using this rounding mode is an alias for :func:`ceil`. + +.. data:: RoundDown + + :func:`round` using this rounding mode is an alias for :func:`floor`. + +.. 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. + + +:: + + 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([T], x[, digits[, base]]) + + +:: + + ceil([T], x[, digits[, base]]) + + +.. function:: floor([T,] x, [digits, [base]]) + +:: + + floor([T], x[, digits[, base]]) + + +:: + + floor([T], x[, digits[, base]]) + + +.. function:: trunc([T,] x, [digits, [base]]) + +:: + + 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. + + +:: + + unsafe_trunc(T, x) + +value is not representable by ``T``, an arbitrary value will be returned. + + +.. 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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))`` + + +:: + + 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. + + +:: + + 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`` + + +:: + + abs(x) + +Absolute value of ``x`` + + +.. function:: abs2(x) + +:: + + abs2(x) + +Squared absolute value of ``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`` + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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)``. + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 - + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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. + + +:: + + 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`` + + +:: + + 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`` + + +:: + + 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 + + +:: + + 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`` + + +:: + + 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`` + + +:: + + angle(z) + +Compute the phase angle in radians of a complex number ``z`` + + +.. function:: cis(z) + +:: + + cis(z) + +Return \exp(iz). + + +:: + + cis(z) + +Return \exp(iz). + + +.. function:: binomial(n,k) + +:: + + binomial(n, k) + +Number of ways to choose ``k`` out of ``n`` items + + +:: + + binomial(n, k) + +Number of ways to choose ``k`` out of ``n`` items + + +.. function:: factorial(n) + +:: + + factorial(n, k) + +Compute ``factorial(n)/factorial(k)`` + + +:: + + factorial(n, k) + +Compute ``factorial(n)/factorial(k)`` + + +.. function:: factorial(n,k) + +:: + + factorial(n, k) + +Compute ``factorial(n)/factorial(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. + + +:: + + 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) + +:: + + gcd(x, y) + +Greatest common (positive) divisor (or zero if x and y are both zero). + + +:: + + 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. + + +:: + + lcm(x, y) + +Least common (non-negative) multiple. + + +.. 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`` + + +:: + + 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 + + +:: + + 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 + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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) + +:: + + 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([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) + +:: + + prevprod([k_1, k_2, ...], n) + +Previous integer not greater than ``n`` that can be written as + + +:: + + prevprod([k_1, k_2, ...], n) + +Previous integer not greater than ``n`` that can be written as + + +.. function:: invmod(x,m) + +:: + + invmod(x, m) + +Take the inverse of ``x`` modulo ``m``: ``y`` such that xy = 1 + + +:: + + 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 + + +:: + + powermod(x, p, m) + +Compute x^p \pmod m + + +.. function:: gamma(x) + +:: + + gamma(x) + +Compute the gamma function of ``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)``. + + +:: + + 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`` + + +:: + + 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)``) + + +:: + + 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``. + + +:: + + 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)``) + + +:: + + 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`` + + +:: + + polygamma(m, x) + +Compute the polygamma function of order ``m`` of argument ``x`` + + +.. function:: airy(k,x) + +:: + + airy(k, x) + +kth derivative of the Airy function \operatorname{Ai}(x). + + +:: + + airy(k, x) + +kth derivative of the Airy function \operatorname{Ai}(x). + + +.. function:: airyai(x) + +:: + + airyai(x) + +Airy function \operatorname{Ai}(x). + + +:: + + airyai(x) + +Airy function \operatorname{Ai}(x). + + +.. function:: airyprime(x) + +:: + + airyprime(x) + +Airy function derivative \operatorname{Ai}'(x). + + +:: + + airyprime(x) + +Airy function derivative \operatorname{Ai}'(x). + + +.. function:: airyaiprime(x) + +:: + + airyaiprime(x) + +Airy function derivative \operatorname{Ai}'(x). + + +:: + + airyaiprime(x) + +Airy function derivative \operatorname{Ai}'(x). + + +.. function:: airybi(x) + +:: + + airybi(x) + +Airy function \operatorname{Bi}(x). + + +:: + + airybi(x) + +Airy function \operatorname{Bi}(x). + + +.. function:: airybiprime(x) + +:: + + airybiprime(x) + +Airy function derivative \operatorname{Bi}'(x). + + +:: + + airybiprime(x) + +Airy function derivative \operatorname{Bi}'(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``. + + +:: + + 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). + + +:: + + 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). + + +:: + + 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). + + +:: + + 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) |}. + + +:: + + 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). + + +:: + + 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). + + +:: + + 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). + + +:: + + 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) |}. + + +:: + + 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). + + +:: + + 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}. + + +:: + + 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). + + +:: + + 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}. + + +:: + + 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 + + +:: + + 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). + + +:: + + 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) |}. + + +:: + + 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). + + +:: + + 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. + + +:: + + 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) = + + +:: + + 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 + + +:: + + lbeta(x, y) + +Natural logarithm of the absolute value of the beta function + + +.. function:: eta(x) + +:: + + eta(x) + +Dirichlet eta function \eta(s) = + + +:: + + eta(x) + +Dirichlet eta function \eta(s) = + + +.. 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``.) + + +:: + + 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``.) + + +:: + + 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``. + + +:: + + 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. + + +:: + + widemul(x, y) + +Multiply ``x`` and ``y``, giving the result as a larger type. + + +.. function:: @evalpoly(z, c...) - julia> round(pi, 3, 2) - 3.125 +:: - .. note:: + @evalpoly(z, c...) - 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. +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(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]) + +:: + + 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``. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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 + + +:: + + 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. + + +:: + + varm(v, m) + +Compute the sample variance of a vector ``v`` with known mean computation. + + +.. function:: middle(x) + +:: + + 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:: middle(x, y) + +:: + + 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:: middle(range) + +:: + + 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:: middle(array) + +:: + + 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) + +:: + + 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. + + +:: + + median!(v) + +Like ``median``, but may overwrite the input vector. + + +.. function:: hist(v[, n]) -> 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. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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. + + +:: + + cor(v1[, v2][, vardim=1, mean=nothing]) - .. doctest:: +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. - julia> x = 1.15 - 1.15 - julia> @sprintf "%.20f" x - "1.14999999999999991118" +Signal Processing +----------------- - julia> x < 115//100 - true +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. - julia> round(x, 1) - 1.2 +.. function:: fft(A [, dims]) -.. data:: RoundingMode +:: - A type which controls rounding behavior. Currently supported rounding modes are: + fft(A[, dims]) - - :obj:`RoundNearest` (default) - - :obj:`RoundNearestTiesAway` - - :obj:`RoundNearestTiesUp` - - :obj:`RoundToZero` - - :obj:`RoundUp` - - :obj:`RoundDown` +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. -.. data:: RoundNearest - The default rounding mode. Rounds to the nearest integer, with ties - (fractional values of 0.5) being rounded to the nearest even integer. +:: -.. data:: RoundNearestTiesAway + fft(A[, dims]) - Rounds to nearest integer, with ties rounded away from zero (C/C++ - :func:`round` behaviour). +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. -.. data:: RoundNearestTiesUp - Rounds to nearest integer, with ties rounded toward positive infinity - (Java/JavaScript :func:`round` behaviour). +.. function:: fft!(A [, dims]) -.. data:: RoundToZero +:: - :func:`round` using this rounding mode is an alias for :func:`trunc`. + fft!(A[, dims]) -.. data:: RoundUp +Same as ``fft()``, but operates in-place on ``A``, which must be an array of complex floating-point numbers. - :func:`round` using this rounding mode is an alias for :func:`ceil`. -.. data:: RoundDown +:: - :func:`round` using this rounding mode is an alias for :func:`floor`. + fft!(A[, dims]) -.. function:: round(z, RoundingModeReal, RoundingModeImaginary) +Same as ``fft()``, but operates in-place on ``A``, which must be an array of complex floating-point numbers. - 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. -.. function:: ceil([T,] x, [digits, [base]]) +.. function:: ifft(A [, dims]) - ``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. + ifft(A[, dims]) - ``digits`` and ``base`` work as for :func:`round`. +Multidimensional inverse FFT. A one-dimensional inverse FFT computes A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``. -.. 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. + ifft(A[, dims]) - ``digits`` and ``base`` work as for :func:`round`. +Multidimensional inverse FFT. A one-dimensional inverse FFT computes A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``. -.. 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``. +.. function:: ifft!(A [, dims]) - ``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`. + ifft!(A[, dims]) -.. function:: unsafe_trunc(T, x) +Same as ``ifft()``, but operates in-place on ``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. -.. 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``. + ifft!(A[, dims]) -.. function:: min(x, y, ...) +Same as ``ifft()``, but operates in-place on ``A``. - Return the minimum of the arguments. Operates elementwise over arrays. -.. function:: max(x, y, ...) +.. function:: bfft(A [, dims]) - Return the maximum of the arguments. Operates elementwise over arrays. +:: -.. function:: minmax(x, y) + bfft(A[, dims]) - Return ``(min(x,y), max(x,y))``. - See also: :func:`extrema` that returns ``(minimum(x), maximum(x))`` +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:: 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) + bfft(A[, dims]) - Absolute value of ``x`` +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:: abs2(x) - Squared absolute value of ``x`` +.. function:: bfft!(A [, dims]) -.. function:: copysign(x, y) +:: - Return ``x`` such that it has the same sign as ``y`` + bfft!(A[, dims]) -.. function:: sign(x) +Same as ``bfft()``, but operates in-place on ``A``. - 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``. + bfft!(A[, dims]) -.. function:: flipsign(x, y) +Same as ``bfft()``, but operates in-place on ``A``. - Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``. -.. function:: sqrt(x) +.. function:: plan_fft(A [, dims [, flags [, timelimit]]]) - Return :math:`\sqrt{x}`. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. The prefix operator ``√`` is equivalent to ``sqrt``. +:: -.. function:: isqrt(n) + plan_fft(A[, dims[, flags[, timelimit]]]) - Integer square root: the largest integer ``m`` such that ``m*m <= n``. +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:: cbrt(x) - Return :math:`x^{1/3}`. The prefix operator ``∛`` is equivalent to ``cbrt``. +:: -.. function:: erf(x) + plan_fft(A[, dims[, flags[, timelimit]]]) - Compute the error function of ``x``, defined by - :math:`\frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt` - for arbitrary complex ``x``. +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:: erfc(x) - Compute the complementary error function of ``x``, - defined by :math:`1 - \operatorname{erf}(x)`. +.. function:: plan_ifft(A [, dims [, flags [, timelimit]]]) -.. 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)`. + plan_ifft(A[, dims[, flags[, timelimit]]]) -.. function:: erfi(x) +Same as ``plan_fft()``, but produces a plan that performs inverse transforms ``ifft()``. - Compute the imaginary error function of ``x``, - defined by :math:`-i \operatorname{erf}(ix)`. -.. 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)`. + plan_ifft(A[, dims[, flags[, timelimit]]]) -.. function:: erfinv(x) +Same as ``plan_fft()``, but produces a plan that performs inverse transforms ``ifft()``. - Compute the inverse error function of a real ``x``, - defined by :math:`\operatorname{erf}(\operatorname{erfinv}(x)) = x`. -.. function:: erfcinv(x) +.. function:: plan_bfft(A [, dims [, flags [, timelimit]]]) - Compute the inverse error complementary function of a real ``x``, - defined by :math:`\operatorname{erfc}(\operatorname{erfcinv}(x)) = x`. +:: -.. function:: real(z) + plan_bfft(A[, dims[, flags[, timelimit]]]) - Return the real part of the complex number ``z`` +Same as ``plan_fft()``, but produces a plan that performs an unnormalized backwards transform ``bfft()``. -.. function:: imag(z) - Return the imaginary part of the complex number ``z`` +:: -.. function:: reim(z) + plan_bfft(A[, dims[, flags[, timelimit]]]) - Return both the real and imaginary parts of the complex number ``z`` +Same as ``plan_fft()``, but produces a plan that performs an unnormalized backwards transform ``bfft()``. -.. function:: conj(z) - Compute the complex conjugate of a complex number ``z`` +.. function:: plan_fft!(A [, dims [, flags [, timelimit]]]) -.. function:: angle(z) +:: - Compute the phase angle in radians of a complex number ``z`` + plan_fft!(A[, dims[, flags[, timelimit]]]) -.. function:: cis(z) +Same as ``plan_fft()``, but operates in-place on ``A``. - Return :math:`\exp(iz)`. -.. function:: binomial(n,k) +:: - Number of ways to choose ``k`` out of ``n`` items + plan_fft!(A[, dims[, flags[, timelimit]]]) -.. function:: factorial(n) +Same as ``plan_fft()``, but operates in-place on ``A``. - 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) `. -.. function:: factorial(n,k) +.. function:: plan_ifft!(A [, dims [, flags [, timelimit]]]) - Compute ``factorial(n)/factorial(k)`` +:: -.. function:: factor(n) -> Dict + plan_ifft!(A[, dims[, flags[, timelimit]]]) - 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. +Same as ``plan_ifft()``, but operates in-place on ``A``. - .. doctest:: - julia> factor(100) # == 2*2*5*5 - Dict{Int64,Int64} with 2 entries: - 2 => 2 - 5 => 2 +:: -.. function:: gcd(x,y) + plan_ifft!(A[, dims[, flags[, timelimit]]]) - Greatest common (positive) divisor (or zero if x and y are both zero). +Same as ``plan_ifft()``, but operates in-place on ``A``. -.. function:: lcm(x,y) - Least common (non-negative) multiple. +.. function:: plan_bfft!(A [, dims [, flags [, timelimit]]]) -.. 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)`. + plan_bfft!(A[, dims[, flags[, timelimit]]]) - .. doctest:: +Same as ``plan_bfft()``, but operates in-place on ``A``. - julia> gcdx(12, 42) - (6,-3,1) - .. doctest:: +:: - julia> gcdx(240, 46) - (2,-9,47) + plan_bfft!(A[, dims[, flags[, timelimit]]]) - .. note:: +Same as ``plan_bfft()``, but operates in-place on ``A``. - 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. -.. function:: ispow2(n) -> Bool +.. function:: rfft(A [, dims]) - Test whether ``n`` is a power of two +:: -.. function:: nextpow2(n) + rfft(A[, dims]) - The smallest power of two not less than ``n``. Returns 0 for ``n==0``, and returns - ``-nextpow2(-n)`` for negative arguments. +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:: 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) + rfft(A[, dims]) - 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. +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:: 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:: irfft(A, d [, dims]) -.. 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. + irfft(A, d[, dims]) -.. function:: prevprod([k_1,k_2,...], 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)``. floor(size(A,dims[1])/2)+1``. (This parameter cannot be inferred from `size(A)`` due to the possibility of rounding by the - 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. -.. function:: invmod(x,m) +:: - Take the inverse of ``x`` modulo ``m``: ``y`` such that :math:`xy = 1 \pmod m` + irfft(A, d[, dims]) -.. function:: powermod(x, p, m) +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 - Compute :math:`x^p \pmod m` -.. function:: gamma(x) +.. function:: brfft(A, d [, dims]) - Compute the gamma function of ``x`` +:: -.. function:: lgamma(x) + brfft(A, d[, dims]) - 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)``. +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:: lfact(x) - Compute the logarithmic factorial of ``x`` +:: -.. function:: digamma(x) + brfft(A, d[, dims]) - Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(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. -.. function:: invdigamma(x) - Compute the inverse digamma function of ``x``. +.. function:: plan_rfft(A [, dims [, flags [, timelimit]]]) -.. function:: trigamma(x) +:: - Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``) + plan_rfft(A[, dims[, flags[, timelimit]]]) -.. function:: polygamma(m, 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 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 :math:`\operatorname{Ai}(x)`. + plan_rfft(A[, dims[, flags[, timelimit]]]) -.. function:: airyai(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()``. - Airy function :math:`\operatorname{Ai}(x)`. -.. function:: airyprime(x) +.. function:: plan_brfft(A, d [, dims [, flags [, timelimit]]]) - Airy function derivative :math:`\operatorname{Ai}'(x)`. +:: -.. function:: airyaiprime(x) + plan_brfft(A, d[, dims[, flags[, timelimit]]]) - Airy function derivative :math:`\operatorname{Ai}'(x)`. +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:: airybi(x) - Airy function :math:`\operatorname{Bi}(x)`. +:: -.. function:: airybiprime(x) + plan_brfft(A, d[, dims[, flags[, timelimit]]]) - Airy function derivative :math:`\operatorname{Bi}'(x)`. +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:: 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``. +.. function:: plan_irfft(A, d [, dims [, flags [, timelimit]]]) -.. function:: besselj0(x) +:: - Bessel function of the first kind of order 0, :math:`J_0(x)`. + plan_irfft(A, d[, dims[, flags[, timelimit]]]) -.. function:: besselj1(x) +Pre-plan an optimized inverse real-input FFT, similar to respectively. The first three arguments have the same meaning as for ``irfft()``. - Bessel function of the first kind of order 1, :math:`J_1(x)`. -.. function:: besselj(nu, x) +:: - Bessel function of the first kind of order ``nu``, :math:`J_\nu(x)`. + plan_irfft(A, d[, dims[, flags[, timelimit]]]) -.. function:: besseljx(nu, x) +Pre-plan an optimized inverse real-input FFT, similar to respectively. The first three arguments have the same meaning as for ``irfft()``. - Scaled Bessel function of the first kind of order ``nu``, :math:`J_\nu(x) e^{- | \operatorname{Im}(x) |}`. -.. function:: bessely0(x) +.. function:: dct(A [, dims]) - Bessel function of the second kind of order 0, :math:`Y_0(x)`. +:: -.. function:: bessely1(x) + dct(A[, dims]) - Bessel function of the second kind of order 1, :math:`Y_1(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. -.. function:: bessely(nu, x) - Bessel function of the second kind of order ``nu``, :math:`Y_\nu(x)`. +:: -.. function:: besselyx(nu, x) + dct(A[, dims]) - Scaled Bessel function of the second kind of order ``nu``, :math:`Y_\nu(x) e^{- | \operatorname{Im}(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. -.. function:: hankelh1(nu, x) - Bessel function of the third kind of order ``nu``, :math:`H^{(1)}_\nu(x)`. +.. function:: dct!(A [, dims]) -.. function:: hankelh1x(nu, x) +:: - Scaled Bessel function of the third kind of order ``nu``, :math:`H^{(1)}_\nu(x) e^{-x i}`. + dct!(A[, dims]) -.. function:: hankelh2(nu, x) +Same as ``dct!()``, except that it operates in-place on ``A``, which must be an array of real or complex floating-point values. - Bessel function of the third kind of order ``nu``, :math:`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}`. + dct!(A[, dims]) -.. function:: besselh(nu, k, x) +Same as ``dct!()``, except that it operates in-place on ``A``, which must be an array of real or complex floating-point values. - 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) +.. function:: idct(A [, dims]) - Modified Bessel function of the first kind of order ``nu``, :math:`I_\nu(x)`. +:: -.. function:: besselix(nu, x) + idct(A[, dims]) - Scaled modified Bessel function of the first kind of order ``nu``, :math:`I_\nu(x) e^{- | \operatorname{Re}(x) |}`. +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:: besselk(nu, x) - Modified Bessel function of the second kind of order ``nu``, :math:`K_\nu(x)`. +:: -.. function:: besselkx(nu, x) + idct(A[, dims]) - Scaled modified Bessel function of the second kind of order ``nu``, :math:`K_\nu(x) e^x`. +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:: beta(x, y) - Euler integral of the first kind :math:`\operatorname{B}(x,y) = \Gamma(x)\Gamma(y)/\Gamma(x+y)`. +.. function:: idct!(A [, dims]) -.. function:: lbeta(x, y) +:: - Natural logarithm of the absolute value of the beta function :math:`\log(|\operatorname{B}(x,y)|)`. + idct!(A[, dims]) -.. function:: eta(x) +Same as ``idct!()``, but operates in-place on ``A``. - Dirichlet eta function :math:`\eta(s) = \sum^\infty_{n=1}(-)^{n-1}/n^{s}`. -.. function:: zeta(s) +:: - Riemann zeta function :math:`\zeta(s)`. + idct!(A[, dims]) -.. function:: zeta(s, z) +Same as ``idct!()``, but operates in-place on ``A``. - Hurwitz zeta function :math:`\zeta(s, z)`. (This is equivalent to - the Riemann zeta function :math:`\zeta(s)` for the case of ``z=1``.) -.. function:: ndigits(n, b) +.. function:: plan_dct(A [, dims [, flags [, timelimit]]]) - Compute the number of digits in number ``n`` written in base ``b``. +:: -.. function:: widemul(x, y) + plan_dct(A[, dims[, flags[, timelimit]]]) - Multiply ``x`` and ``y``, giving the result as a larger type. +Pre-plan an optimized discrete cosine transform (DCT), similar to The first two arguments have the same meaning as for ``dct()``. -.. 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. +:: -Statistics ----------- + plan_dct(A[, dims[, flags[, timelimit]]]) -.. function:: mean(v[, region]) +Pre-plan an optimized discrete cosine transform (DCT), similar to The first two arguments have the same meaning as for ``dct()``. - 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) +.. function:: plan_dct!(A [, dims [, flags [, timelimit]]]) - Compute the mean of ``v`` over the singleton dimensions of ``r``, and write results to ``r``. +:: -.. function:: std(v[, region]) + plan_dct!(A[, dims[, flags[, timelimit]]]) - 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. +Same as ``plan_dct()``, but operates in-place on ``A``. -.. 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]) + plan_dct!(A[, dims[, flags[, timelimit]]]) - 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. +Same as ``plan_dct()``, but operates in-place on ``A``. -.. 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:: plan_idct(A [, dims [, flags [, timelimit]]]) + +:: -.. function:: middle(x) + plan_idct(A[, dims[, flags[, timelimit]]]) - Compute the middle of a scalar value, which is equivalent to ``x`` itself, - but of the type of ``middle(x, x)`` for consistency. +Pre-plan an optimized inverse discrete cosine transform (DCT), similar to ``plan_fft()`` except producing a function that computes -.. 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``). +:: -.. function:: middle(range) + plan_idct(A[, dims[, flags[, timelimit]]]) - 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. +Pre-plan an optimized inverse discrete cosine transform (DCT), similar to ``plan_fft()`` except producing a function that computes -.. function:: middle(array) - Compute the middle of an array, which consists in finding its extrema and - then computing their mean. +.. function:: plan_idct!(A [, dims [, flags [, timelimit]]]) -.. 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. + plan_idct!(A[, dims[, flags[, timelimit]]]) -.. function:: median!(v) +Same as ``plan_idct()``, but operates in-place on ``A``. - 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. + plan_idct!(A[, dims[, flags[, timelimit]]]) -.. function:: hist(v, e) -> e, counts +Same as ``plan_idct()``, but operates in-place on ``A``. - 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 +.. function:: fftshift(x) - 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) + fftshift(x, dim) - 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. +Swap the first and second halves of the given dimension of array -.. 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) + fftshift(x, dim) - 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. +Swap the first and second halves of the given dimension of array -.. 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:: fftshift(x,dim) -.. 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. + fftshift(x, dim) -.. function:: quantile(v, p) +Swap the first and second halves of the given dimension of array - 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. + fftshift(x, dim) -.. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) +Swap the first and second halves of the given dimension of array - 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: +.. function:: ifftshift(x, [dim]) - - ``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``. + ifftshift(x[, dim]) - - ``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. +Undoes the effect of ``fftshift``. - 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``. +:: + ifftshift(x[, dim]) -.. function:: cor(v1[, v2][, vardim=1, mean=nothing]) +Undoes the effect of ``fftshift``. - 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. +.. function:: filt(b, a, x, [si]) +:: -Signal Processing ------------------ + filt(b, a, x[, si]) -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. +Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an optional initial filter state vector ``si`` (defaults to zeros). -.. 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 + filt(b, a, x[, si]) - .. math:: +Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an optional initial filter state vector ``si`` (defaults to zeros). - \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``. +.. function:: filt!(out, b, a, x, [si]) - 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]) + filt!(out, b, a, x[, si]) - Same as :func:`fft`, but operates in-place on ``A``, - which must be an array of complex floating-point numbers. +Same as ``filt()`` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. -.. function:: ifft(A [, dims]) - Multidimensional inverse FFT. +:: - A one-dimensional inverse FFT computes + filt!(out, b, a, x[, si]) - .. math:: +Same as ``filt()`` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. - \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:: deconv(b,a) -.. function:: ifft!(A [, dims]) +:: - Same as :func:`ifft`, but operates in-place on ``A``. + deconv(b, a) -.. function:: bfft(A [, dims]) +Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. - 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] + deconv(b, a) -.. function:: bfft!(A [, dims]) +Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. - Same as :func:`bfft`, but operates in-place on ``A``. -.. function:: plan_fft(A [, dims [, flags [, timelimit]]]) +.. function:: conv(u,v) - 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. +:: -.. function:: plan_ifft(A [, dims [, flags [, timelimit]]]) + conv(u, v) - Same as :func:`plan_fft`, but produces a plan that performs inverse transforms - :func:`ifft`. +Convolution of two vectors. Uses FFT algorithm. -.. function:: plan_bfft(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_fft`, but produces a plan that performs an unnormalized - backwards transform :func:`bfft`. +:: -.. function:: plan_fft!(A [, dims [, flags [, timelimit]]]) + conv(u, v) - Same as :func:`plan_fft`, but operates in-place on ``A``. +Convolution of two vectors. Uses FFT algorithm. -.. function:: plan_ifft!(A [, dims [, flags [, timelimit]]]) - Same as :func:`plan_ifft`, but operates in-place on ``A``. +.. function:: conv2(u,v,A) -.. function:: plan_bfft!(A [, dims [, flags [, timelimit]]]) +:: - Same as :func:`plan_bfft`, but operates in-place on ``A``. + conv2(B, A) -.. function:: rfft(A [, dims]) +2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm - 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. +:: -.. function:: irfft(A, d [, dims]) + conv2(B, A) - 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)``. +2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm - ``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]) +.. function:: conv2(B,A) - 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. +:: -.. function:: plan_rfft(A [, dims [, flags [, timelimit]]]) + conv2(B, A) - 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`. +2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm -.. 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`. +:: -.. function:: plan_irfft(A, d [, dims [, flags [, timelimit]]]) + conv2(B, A) - 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`. +2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm -.. 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. +.. function:: xcorr(u,v) -.. 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. + xcorr(u, v) -.. function:: idct(A [, dims]) +Compute the cross-correlation of two vectors. - 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. -.. function:: idct!(A [, dims]) +:: - Same as :func:`idct!`, but operates in-place on ``A``. + xcorr(u, v) -.. function:: plan_dct(A [, dims [, flags [, timelimit]]]) +Compute the cross-correlation of two vectors. - 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`. -.. function:: plan_dct!(A [, dims [, flags [, timelimit]]]) +The following functions are defined within the ``Base.FFTW`` module. - Same as :func:`plan_dct`, but operates in-place on ``A``. +.. currentmodule:: Base.FFTW -.. function:: plan_idct(A [, dims [, flags [, timelimit]]]) +.. function:: r2r(A, kind [, dims]) - 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`. +:: -.. function:: plan_idct!(A [, dims [, flags [, timelimit]]]) + r2r(A, kind[, dims]) - Same as :func:`plan_idct`, but operates in-place on ``A``. +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:: fftshift(x) - Swap the first and second halves of each dimension of ``x``. +:: -.. function:: fftshift(x,dim) + r2r(A, kind[, dims]) - Swap the first and second halves of the given dimension of array ``x``. +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:: ifftshift(x, [dim]) - Undoes the effect of ``fftshift``. +.. function:: r2r!(A, kind [, dims]) -.. 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). + r2r!(A, kind[, dims]) -.. function:: filt!(out, b, a, x, [si]) +Same as ``r2r()``, but operates in-place on ``A``, which must be an array of real or complex floating-point numbers. - Same as :func:`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. + r2r!(A, kind[, dims]) -.. function:: conv(u,v) +Same as ``r2r()``, but operates in-place on ``A``, which must be an array of real or complex floating-point numbers. - Convolution of two vectors. Uses FFT algorithm. -.. function:: conv2(u,v,A) +.. function:: plan_r2r(A, kind [, dims [, flags [, timelimit]]]) - 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 +:: -.. function:: conv2(B,A) + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm +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:: xcorr(u,v) - Compute the cross-correlation of two vectors. +:: -The following functions are defined within the ``Base.FFTW`` module. + plan_r2r(A, kind[, dims[, flags[, timelimit]]]) -.. currentmodule:: Base.FFTW +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:: 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. +.. function:: plan_r2r!(A, kind [, dims [, flags [, timelimit]]]) -.. 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. + plan_r2r!(A, kind[, dims[, flags[, timelimit]]]) -.. function:: plan_r2r(A, kind [, dims [, flags [, timelimit]]]) +Similar to ``Base.plan_fft()``, but corresponds to ``r2r!()``. - 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. -.. 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]]]) -.. currentmodule:: Base +Similar to ``Base.plan_fft()``, but corresponds to ``r2r!()``. + +.. currentmodule:: Base Numerical Integration --------------------- @@ -1665,61 +4633,17 @@ 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.) + + +:: + + 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..d8164ecced4d0 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -14,108 +14,354 @@ Data Formats .. function:: bin(n, [pad]) - Convert an integer to a binary string, optionally specifying a number of digits to pad to. +:: + + bin(n[, pad]) + +Convert an integer to a binary string, optionally specifying a number of digits to pad to. + + +:: + + 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. +:: + + hex(n[, pad]) + +Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. + + +:: + + 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. +:: + + dec(n[, pad]) + +Convert an integer to a decimal string, optionally specifying a number of digits to pad to. + + +:: + + 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. +:: + + oct(n[, pad]) + +Convert an integer to an octal string, optionally specifying a number of digits to pad to. + + +:: + + 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. +:: + + 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, 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)])``. + + +:: + + 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. + + +:: + + 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. +:: + + bits(n) + +A string giving the literal bit representation of a number. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. +:: + + signed(x) + +Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. + + +:: + + 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. +:: + + 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(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``. +:: + + 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(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:: + significand(x) - 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. + + +:: + + 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)*8 - 15.2 .. function:: exponent(x) -> Int - Get the exponent of a normalized floating-point number. +:: + + exponent(x) -> Int + +Get the exponent of a normalized floating-point number. + + +:: + + 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. +:: + + complex(r[, i]) + +Convert real numbers or arrays to complex. ``i`` defaults to zero. + + +:: + + complex(r[, i]) + +Convert real numbers or arrays to complex. ``i`` defaults to zero. + .. function:: bswap(n) - Byte-swap an integer +:: + + bswap(n) + +Byte-swap an integer + + +:: + + bswap(n) + +Byte-swap an integer + .. function:: num2hex(f) - Get a hexadecimal string of the binary representation of a floating point number +:: + + num2hex(f) + +Get a hexadecimal string of the binary representation of a floating point number + + +:: + + 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 +:: + + hex2num(str) + +Convert a hexadecimal string to the floating point number it represents + + +:: + + 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. +:: + + 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(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. +:: + + 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(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 @@ -123,11 +369,35 @@ 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. +:: + + 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(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). +:: + + zero(x) + +Get the additive identity element for the type of x (x can also specify the type itself). + + +:: + + zero(x) + +Get the additive identity element for the type of x (x can also specify the type itself). + .. data:: pi π @@ -183,238 +453,454 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool - Test whether a floating point number is subnormal +:: + + issubnormal(f) -> Bool + +Test whether a floating point number is subnormal + + +:: + + issubnormal(f) -> Bool + +Test whether a floating point number is subnormal + .. function:: isfinite(f) -> Bool - Test whether a number is finite +:: + + isfinite(f) -> Bool + +Test whether a number is finite + + +:: + + isfinite(f) -> Bool + +Test whether a number is finite + .. function:: isinf(f) -> Bool - Test whether a number is infinite +:: + + isinf(f) -> Bool + +Test whether a number is infinite + + +:: + + isinf(f) -> Bool + +Test whether a number is infinite + .. function:: isnan(f) -> Bool - Test whether a floating point number is not a number (NaN) +:: + + isnan(f) -> Bool + +Test whether a floating point number is not a number (NaN) + + +:: + + 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`` +:: + + inf(f) + +Returns positive infinity of the floating point type ``f`` or of the same floating point type as ``f`` + + +:: + + 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`` +:: + + nan(f) + +Returns NaN (not-a-number) of the floating point type ``f`` or of the same floating point type as ``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) - Get the next floating point number in lexicographic order +:: + + nextfloat(f) + +Get the next floating point number in lexicographic order + + +:: + + nextfloat(f) + +Get the next floating point number in lexicographic order + .. function:: prevfloat(f) -> FloatingPoint - Get the previous floating point number in lexicographic order +:: + + prevfloat(f) -> FloatingPoint + +Get the previous floating point number in lexicographic order + + +:: + + 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 +:: + + isinteger(x) -> Bool + +Test whether ``x`` or all its elements are numerically equal to some integer + + +:: + + 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 +:: + + isreal(x) -> Bool + +Test whether ``x`` or all its elements are numerically equal to some real number + + +:: + + 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:: + Float32(x[, mode::RoundingMode]) - julia> Float32(1/3, RoundDown) - 0.3333333f0 +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. - 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. +:: + + Float64(x[, mode::RoundingMode]) - .. doctest:: +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. - julia> Float64(pi, RoundDown) - 3.141592653589793 - julia> Float64(pi, RoundUp) - 3.1415926535897936 +:: + + 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. - 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``. +:: + + 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(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. - Instances can be constructed from strings via :func:`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``. +:: + + BigFloat(x) - 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. +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. - .. 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. +:: + + 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(T) + +Get the current floating point rounding mode for type ``T``, controlling the rounding of basic arithmetic functions (``+()``, Valid modes are ``RoundNearest``, ``RoundToZero``, ``RoundUp``, - 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 (:func:`+`, :func:`-`, :func:`*`, - :func:`/` and :func:`sqrt`) and type conversion. +:: + + 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(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 - 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:: +:: + + 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. + - old = get_rounding(T) - set_rounding(T, mode) - f() - set_rounding(T, old) +:: + + 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. - See ``get_rounding`` for available rounding modes. Integers ~~~~~~~~ .. function:: count_ones(x::Integer) -> Integer - Number of ones in the binary representation of ``x``. +:: + + count_ones(x::Integer) -> Integer - .. doctest:: +Number of ones in the binary representation of ``x``. + + +:: + + count_ones(x::Integer) -> Integer + +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``. +:: + + count_zeros(x::Integer) -> Integer + +Number of zeros in the binary representation of ``x``. - .. doctest:: - julia> count_zeros(Int32(2 ^ 16 - 1)) - 16 +:: + + 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``. +:: + + leading_zeros(x::Integer) -> Integer + +Number of zeros leading the binary representation of ``x``. + + +:: - .. doctest:: + leading_zeros(x::Integer) -> Integer + +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``. +:: + + leading_ones(x::Integer) -> Integer + +Number of ones leading the binary representation of ``x``. + + +:: + + leading_ones(x::Integer) -> Integer - .. doctest:: +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``. +:: - .. doctest:: + trailing_zeros(x::Integer) -> Integer + +Number of zeros trailing the binary representation of ``x``. + + +:: + + trailing_zeros(x::Integer) -> Integer + +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``. +:: + + trailing_ones(x::Integer) -> Integer + +Number of ones trailing the binary representation of ``x``. - .. doctest:: - julia> trailing_ones(3) - 2 +:: + + trailing_ones(x::Integer) -> Integer + +Number of ones trailing the binary representation of ``x``. + .. function:: isprime(x::Integer) -> Bool - Returns ``true`` if ``x`` is prime, and ``false`` otherwise. +:: + + 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:: +:: + + 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(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). +:: + + 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(x::BigInt[, reps = 25]) -> Bool - .. doctest:: +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``. +:: + + primes(n) + +Returns a collection of the prime numbers <= ``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. +:: + + isodd(x::Integer) -> Bool + +Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and + - .. doctest:: +:: - julia> isodd(9) - true + isodd(x::Integer) -> Bool + +Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and - julia> isodd(10) - false .. function:: iseven(x::Integer) -> Bool - Returns ``true`` is ``x`` is even (that is, divisible by 2), and ``false`` otherwise. +:: + + iseven(x::Integer) -> Bool + +Returns ``true`` is ``x`` is even (that is, divisible by 2), and - .. doctest:: - julia> iseven(9) - false +:: + + iseven(x::Integer) -> Bool + +Returns ``true`` is ``x`` is even (that is, divisible by 2), and - julia> iseven(10) - true BigFloats --------- @@ -422,24 +908,67 @@ 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. +:: + + precision(num::FloatingPoint) + +Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. + + +:: + + 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. +:: + + get_bigfloat_precision() + +Get the precision (in bits) currently used for BigFloat arithmetic. + + +:: + + 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. +:: + + set_bigfloat_precision(x::Int64) + +Set the precision (in bits) to be used to BigFloat arithmetic. + + +:: + + 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:: +:: + + 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(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) .. _random-numbers: @@ -462,48 +991,161 @@ 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. + + +:: + + 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. +:: + + 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([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. +:: + + RandomDevice() + +Create a ``RandomDevice`` RNG object. Two such objects will always generate different streams of random numbers. + + +:: + + 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 +:: + + 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; +:: + + rand([rng][, S][, dims...]) + +Pick a random element or array of random elements from the set of values specified by ``S``; ``S`` can be - ``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. +:: + + 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!([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. +:: + + bitrand([rng][, dims...]) + +Generate a ``BitArray`` of random boolean values. + + +:: + + 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. + + +:: + + 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. +:: + + 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!([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. +:: + + randexp([rng][, dims...]) + +Generate a random number according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. + + +:: + + 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). +:: + + randexp!([rng], A::Array{Float64, N}) + +Fill the array A with random numbers following the exponential distribution (with scale 1). + + +:: + + 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..c28cd4d46e6c8 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -9,110 +9,322 @@ 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. +:: + + 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(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. + + +:: + + 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. +:: + + current_task() + +Get the currently running Task. + + +:: + + current_task() + +Get the currently running Task. + .. function:: istaskdone(task) -> Bool - Tell whether a task has exited. +:: + + istaskdone(task) -> Bool + +Tell whether a task has exited. + + +:: + + istaskdone(task) -> Bool + +Tell whether a task has exited. + .. function:: istaskstarted(task) -> Bool - Tell whether a task has started executing. +:: + + istaskstarted(task) -> Bool + +Tell whether a task has started executing. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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. +:: + + 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() + +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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. +:: + + 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(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. - 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. +:: + + @schedule() + +Wrap an expression in a Task and add it to the scheduler's queue. + + +:: + + @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. + + +:: + + @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``. + + +:: + + 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. + + +:: + + 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`` + + +:: + + 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. + + +:: + + 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 @@ -120,256 +332,550 @@ 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. +:: -.. function:: addprocs() -> List of process identifiers + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - Equivalent to ``addprocs(CPU_CORES)`` +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. +:: + + 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. - ``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)`` +.. function:: addprocs() -> List of process identifiers + +:: + + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - ``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``. +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. - ``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: + 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. 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 - ``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. + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - ``dir`` : specifies the working directory on the workers. Defaults to the host's current directory (as found by `pwd()`) +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. - ``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 : + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - 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. +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``. + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers - 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. +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(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. +:: + + nprocs() + +Get the number of available processes. + + +:: + + 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. +:: + + nworkers() + +Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. + + +:: + + 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 + + +:: + + procs(S::SharedArray) + +Get the vector of processes that have mapped the shared array + .. function:: workers() - Returns a list of all worker process identifiers. +:: + + workers() + +Returns a list of all worker process identifiers. + + +:: + + workers() + +Returns a list of all worker process identifiers. + .. function:: rmprocs(pids...) - Removes the specified workers. +:: + + rmprocs(pids...) + +Removes the specified workers. + + +:: + + 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. + + +:: + + 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. +:: + + myid() + +Get the id of the current process. + + +:: + + 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. + + +:: + + 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``. +:: + + remotecall(id, func, args...) + +Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. + + +:: + + 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. + wait([x]) - * ``Condition``: Wait for ``notify`` on a condition. +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. - * ``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) + wait([x]) - 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. +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. - 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. +:: + + fetch(RemoteRef) + +Wait for and get the value of a remote reference. + + +:: + + fetch(RemoteRef) + +Wait for and get the value of a remote reference. + .. function:: remotecall_wait(id, func, args...) - Perform ``wait(remotecall(...))`` in one message. +:: + + remotecall_wait(id, func, args...) + +Perform ``wait(remotecall(...))`` in one message. + + +:: + + remotecall_wait(id, func, args...) + +Perform ``wait(remotecall(...))`` in one message. + .. function:: remotecall_fetch(id, func, args...) - Perform ``fetch(remotecall(...))`` in one message. +:: + + remotecall_fetch(id, func, args...) + +Perform ``fetch(remotecall(...))`` in one message. + + +:: + + 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. + + +:: + + 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. +:: + + take!(RemoteRef) + +Fetch the value of a remote reference, removing it so that the reference is empty again. + + +:: + + 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. +:: + + isready(r::RemoteRef) - 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:: +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(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 - rr = RemoteRef() - @async put!(rr, remotecall_fetch(p, long_computation)) - isready(rr) # will not block .. function:: RemoteRef() - Make an uninitialized remote reference on the local machine. +:: + + RemoteRef(n) + +Make an uninitialized remote reference on process ``n``. + + +:: + + RemoteRef(n) + +Make an uninitialized remote reference on process ``n``. + .. function:: RemoteRef(n) - Make an uninitialized remote reference on process ``n``. +:: + + RemoteRef(n) + +Make an uninitialized remote reference on process ``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. + + +:: + + 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. + + +:: + + @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 + + +:: + + @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)``. +:: + + @fetch() + +Equivalent to ``fetch(@spawn expr)``. + + +:: + + @fetch() + +Equivalent to ``fetch(@spawn expr)``. + .. function:: @fetchfrom - Equivalent to ``fetch(@spawnat p expr)``. +:: + + @fetchfrom() + +Equivalent to ``fetch(@spawnat p expr)``. + + +:: + + @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. + + +:: + + @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``, - ``@spawnat`` and ``@parallel`` are complete. +:: + + @sync() + +Wait until all dynamically-enclosed uses of ``@async``, ``@spawn``, + + +:: + + @sync() + +Wait until all dynamically-enclosed uses of ``@async``, ``@spawn``, + .. function:: @parallel - A parallel for loop of the form :: +:: + + @parallel() - @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 :: +:: + + @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 - @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. +:: + + SharedArray(T::Type, dims::NTuple; init=false, pids=Int[]) - 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. +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. - 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 +:: + + procs(S::SharedArray) + +Get the vector of processes that have mapped the shared array + + +:: + + 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`` +:: + + sdata(S::SharedArray) + +Returns the actual ``Array`` object backing ``S`` + + +:: + + 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 + + +:: + + 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,40 +886,82 @@ 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. + + +:: + + 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: +:: + + 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(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. .. 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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..883763300a298 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -9,139 +9,433 @@ 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``. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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``)``. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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 + + +:: + + 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. + + +:: + + 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. + + +:: + + 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``. + + +:: + + 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``. +:: + + available(pkg) -> Vector{VersionNumber} + +Returns the version numbers available for package ``pkg``. + + +:: + + 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``. + + +:: + + 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``. +:: + + installed(pkg) -> Void | VersionNumber + +If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. + + +:: + + 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. +:: + + status() + +Prints out a summary of what packages are installed and what version and state they're in. + + +:: + + 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. + + +:: + + 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)`` + + +:: + + 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``. + + +:: + + pin(pkg, version) + +Pin ``pkg`` at registered version ``version``. + .. function:: pin(pkg, version) - Pin ``pkg`` at registered version ``version``. +:: + + pin(pkg, version) + +Pin ``pkg`` at registered version ``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``. +:: + + 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(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. - You can also supply an iterable collection of package names, e.g., - ``Pkg.free(("Pkg1", "Pkg2"))`` to free multiple packages at 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. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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)``. +:: + + 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[, 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 + + +:: + + 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``. +:: + + 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``. + + +:: + + 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``. + + +:: + + 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``. +:: + + 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``. + + +:: + + 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..e548f655f9324 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -10,79 +10,148 @@ .. function:: @profile - ``@profile `` runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. +:: -.. currentmodule:: Base.Profile + @profile() + +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 any existing backtraces from the internal buffer. +:: + + clear() + +Clear any existing backtraces from the internal buffer. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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)``. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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..e342f3aa26776 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -119,50 +119,114 @@ 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 + + +:: + + 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. + + +:: + + 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. +:: + + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort a multidimensional array ``A`` along the given dimension. + + +:: + + 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!``. +:: + + 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(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!()`` - See also :func:`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)``. +:: + + 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!(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()`` - See also :func:`sortperm` .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) - Sort the rows of matrix ``A`` lexicographically. +:: + + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the rows of matrix ``A`` lexicographically. + + +:: + + 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. +:: + + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the columns of matrix ``A`` lexicographically. + + +:: + + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + +Sort the columns of matrix ``A`` lexicographically. Order-Related Functions @@ -170,41 +234,98 @@ 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``. + + +:: + + 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 + + +:: + + 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``. + + +:: + + 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``. + + +:: + + 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. + + +:: + + 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 + + +:: + + 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..13715b7401abb 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,408 +6,1188 @@ .. function:: length(s) - The number of characters in string ``s``. +:: + + length(s) + +The number of characters in string ``s``. + + +:: + + length(s) + +The number of characters in string ``s``. + .. function:: sizeof(s::AbstractString) - The number of bytes in string ``s``. +:: + + sizeof(s::AbstractString) + +The number of bytes in string ``s``. + + +:: + + sizeof(s::AbstractString) + +The number of bytes in string ``s``. + .. function:: *(s, t) - Concatenate strings. The ``*`` operator is an alias to this function. +:: + + *(s, t) + +Concatenate strings. The ``*`` operator is an alias to this function. + + +:: + + *(s, t) + +Concatenate strings. The ``*`` operator is an alias to this function. - .. doctest:: julia> "Hello " * "world" "Hello world" .. function:: ^(s, n) - Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. +:: + + ^(s, n) + +Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. + + +:: - .. doctest:: + ^(s, n) + +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. +:: + + string(xs...) + +Create a string from any values using the ``print`` 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. +:: + + repr(x) + +Create a string from any value using the ``showall`` function. + + +:: + + 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. + + +:: + + 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. +:: + + 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(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. + + +:: + + 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. + + +:: + + 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. +:: + + 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(::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). + + +:: + + 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). + + +:: + + 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). +:: + + utf8(s) + +Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + + +:: + + 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``. + + +:: + + 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.) + + +:: + + 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 + + +:: + + 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 + + +:: + + 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. +:: + + is_assigned_char(c) -> Bool + +Returns true if the given char or integer is an assigned Unicode code point. + + +:: + + 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. +:: + + ismatch(r::Regex, s::AbstractString) -> Bool + +Test whether a string contains a match of the given regular expression. + + +:: + + 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. +:: + + 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(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. +:: + + 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(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. +:: + + matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} + +Return a vector of the matching substrings from eachmatch. + + +:: + + 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``. +:: + + lpad(string, n, p) + +Make a string at least ``n`` columns wide when printed, by padding on the left with copies of ``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) - Make a string at least ``n`` columns wide when printed, by padding on the right with copies of ``p``. +:: + + rpad(string, n, p) + +Make a string at least ``n`` columns wide when printed, by padding on the right with copies of ``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, 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(string, "substring")`` = ``start:end`` such that ``string[start:end] == "substring"``, or ``0:-1`` 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``: - ``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``. +:: + + 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(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. +:: + + 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(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. +:: + + 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(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. +:: + + contains(haystack, needle) + +Determine whether the second argument is a substring of the first. + + +:: + + 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. +:: + + 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(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. +:: + + 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(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. +:: + + rsplit(string, [chars]; limit=0, keep=true) + +Similar to ``split``, but starting from the end of the string. + + +:: + + 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. +:: + + 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(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. + + +:: + + 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. + + +:: + + 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. +:: + + 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(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. +:: + + 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(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. +:: + + uppercase(string) + +Returns ``string`` with all characters converted to uppercase. + + +:: + + uppercase(string) + +Returns ``string`` with all characters converted to uppercase. + .. function:: lowercase(string) - Returns ``string`` with all characters converted to lowercase. +:: + + lowercase(string) + +Returns ``string`` with all characters converted to lowercase. + + +:: + + lowercase(string) + +Returns ``string`` with all characters converted to lowercase. + .. function:: ucfirst(string) - Returns ``string`` with the first character converted to uppercase. +:: + + ucfirst(string) + +Returns ``string`` with the first character converted to uppercase. + + +:: + + ucfirst(string) + +Returns ``string`` with the first character converted to uppercase. + .. function:: lcfirst(string) - Returns ``string`` with the first character converted to lowercase. +:: + + lcfirst(string) + +Returns ``string`` with the first character converted to lowercase. + + +:: + + 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"``. +:: + + 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(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)``. - ``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 +:: + + chop(string) + +Remove the last character from a string + + +:: + + chop(string) + +Remove the last character from a string + .. function:: chomp(string) - Remove a trailing newline from a string +:: + + chomp(string) + +Remove a trailing newline from a string + + +:: + + chomp(string) + +Remove a trailing newline from a string + .. function:: ind2chr(string, i) - Convert a byte index to a character index +:: + + ind2chr(string, i) + +Convert a byte index to a character index + + +:: + + ind2chr(string, i) + +Convert a byte index to a character index + .. function:: chr2ind(string, i) - Convert a character index to a byte index +:: + + chr2ind(string, i) + +Convert a character index to a byte index + + +:: + + 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 +:: + + isvalid(str, i) + +Tells whether index ``i`` is valid for the given string + + +:: + + 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. + + +:: + + 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. + + +:: + + 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*. + + +:: + + 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. +:: + + charwidth(c) + +Gives the number of columns needed to print a character. + + +:: + + 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. +:: + + strwidth(s) + +Gives the number of columns needed to print a string. + + +:: + + 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 + + +:: + + 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'. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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'. + + +:: + + 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. +:: + + 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(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. +:: + + 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(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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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. +:: + + symbol(x...) -> Symbol + +Create a ``Symbol`` by concatenating the string representations of the arguments together. + + +:: + + 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 + + +:: + + 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()``. + + +:: + + 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. + + +:: + + 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. +:: + + 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(::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. + + +:: + + 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. + + +:: + + 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. + + +:: + + 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..7acfe43177c06 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -14,12 +14,21 @@ 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) + + +:: + + 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 +.. module:: Base.Test Test Framework -------------- @@ -133,26 +142,84 @@ Macros .. function:: @test(ex) - Test the expression ``ex`` and calls the current handler to handle the result. +:: + + @test(ex) + +Test the expression ``ex`` and calls the current handler to handle the result. + + +:: + + @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 + + +:: + + @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. + + +:: + + @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``. + + +:: + + @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) - Run the function ``f`` using the ``handler`` as the handler. +:: + + with_handler(f, handler) + +Run the function ``f`` using the ``handler`` as the handler. + + +:: + + with_handler(f, handler) + +Run the function ``f`` using the ``handler`` as the handler. +