From 4adfd31862270dd597977bd26ce33092943da3cb Mon Sep 17 00:00:00 2001 From: Mike Innes Date: Wed, 19 Aug 2015 15:55:35 +0100 Subject: [PATCH] regenerate the manual --- doc/devdocs/cartesian.rst | 104 +- doc/stdlib/arrays.rst | 1403 +++++++++++++++++---------- doc/stdlib/base.rst | 1335 ++++++++++++++++++++------ doc/stdlib/c.rst | 223 +++-- doc/stdlib/collections.rst | 1020 ++++++++++++++------ doc/stdlib/dates.rst | 763 ++++++++------- doc/stdlib/file.rst | 356 +++++-- doc/stdlib/io-network.rst | 1185 ++++++++++++----------- doc/stdlib/libc.rst | 71 +- doc/stdlib/libdl.rst | 45 +- doc/stdlib/linalg.rst | 1225 ++++++++++++++++-------- doc/stdlib/math.rst | 1832 ++++++++++++++++++++++++++++-------- doc/stdlib/numbers.rst | 361 ++++++- doc/stdlib/parallel.rst | 531 +++++++---- doc/stdlib/pkg.rst | 281 +++--- doc/stdlib/profile.rst | 59 +- doc/stdlib/sort.rst | 121 ++- doc/stdlib/strings.rst | 584 ++++++++---- doc/stdlib/test.rst | 36 +- 19 files changed, 7924 insertions(+), 3611 deletions(-) diff --git a/doc/devdocs/cartesian.rst b/doc/devdocs/cartesian.rst index 98fad0492420cf..fedeba619271bc 100644 --- a/doc/devdocs/cartesian.rst +++ b/doc/devdocs/cartesian.rst @@ -138,72 +138,82 @@ Macro reference .. function:: @nloops N itersym rangeexpr bodyexpr - :: - @nloops N itersym rangeexpr preexpr bodyexpr - @nloops N itersym rangeexpr preexpr postexpr bodyexpr - - Generate ``N`` nested loops, using ``itersym`` as the prefix for - the iteration variables. ``rangeexpr`` may be an - anonymous-function expression, or a simple symbol ``var`` in which - case the range is ``1:size(var,d)`` for dimension ``d``. - - Optionally, you can provide "pre" and "post" expressions. These - get executed first and last, respectively, in the body of each - loop. For example, - :: - - @nloops 2 i A d->j_d=min(i_d,5) begin - s += @nref 2 A j - end - - would generate - :: - - for i_2 = 1:size(A, 2) - j_2 = min(i_2, 5) - for i_1 = 1:size(A, 1) - j_1 = min(i_1, 5) - s += A[j_1,j_2] - end - end - - If you want just a post-expression, supply - ``nothing`` for the pre-expression. Using parenthesis and - semicolons, you can supply multi-statement expressions. + .. Docstring generated from Julia source + .. code-block:: julia + @nloops N itersym rangeexpr bodyexpr + @nloops N itersym rangeexpr preexpr bodyexpr + @nloops N itersym rangeexpr preexpr postexpr bodyexpr + + Generate ``N`` nested loops, using ``itersym`` as the prefix for the iteration variables. ``rangeexpr`` may be an anonymous-function expression, or a simple symbol ``var`` in which case the range is ``1:size(var,d)`` for dimension ``d``\ . + + Optionally, you can provide "pre" and "post" expressions. These get executed first and last, respectively, in the body of each loop. For example, : + + .. code-block:: julia + @nloops 2 i A d->j_d=min(i_d,5) begin + s += @nref 2 A j + end + + would generate : + + .. code-block:: julia + for i_2 = 1:size(A, 2) + j_2 = min(i_2, 5) + for i_1 = 1:size(A, 1) + j_1 = min(i_1, 5) + s += A[j_1,j_2] + end + end + + If you want just a post-expression, supply ``nothing`` for the pre-expression. Using parenthesis and semicolons, you can supply multi-statement expressions. .. function:: @nref N A indexexpr - Generate expressions like ``A[i_1,i_2,...]``. ``indexexpr`` can - either be an iteration-symbol prefix, or an anonymous-function - expression. + .. Docstring generated from Julia source + .. code-block:: julia + @nref N A indexexpr + + Generate expressions like ``A[i_1,i_2,...]``\ . ``indexexpr`` can either be an iteration-symbol prefix, or an anonymous-function expression. .. function:: @nexprs N expr - Generate ``N`` expressions. ``expr`` should be an - anonymous-function expression. + .. Docstring generated from Julia source + .. code-block:: julia + @nexprs N expr + + Generate ``N`` expressions. ``expr`` should be an anonymous-function expression. .. function:: @ntuple N expr - Generates an ``N``-tuple. ``@ntuple 2 i`` would generate ``(i_1, i_2)``, and ``@ntuple 2 k->k+1`` would generate ``(2,3)``. + .. Docstring generated from Julia source + .. code-block:: julia + @ntuple N expr + + Generates an ``N``\ -tuple. ``@ntuple 2 i`` would generate ``(i_1, i_2)``\ , and ``@ntuple 2 k->k+1`` would generate ``(2,3)``\ . .. function:: @nall N expr - ``@nall 3 d->(i_d > 1)`` would generate the expression - ``(i_1 > 1 && i_2 > 1 && i_3 > 1)``. This can be convenient for - bounds-checking. + .. Docstring generated from Julia source + .. code-block:: julia + @nall N expr + + ``@nall 3 d->(i_d > 1)`` would generate the expression ``(i_1 > 1 && i_2 > 1 && i_3 > 1)``\ . This can be convenient for bounds-checking. .. function:: @nif N conditionexpr expr - :: - @nif N conditionexpr expr elseexpr + .. Docstring generated from Julia source + .. code-block:: julia + @nif N conditionexpr expr + @nif N conditionexpr expr elseexpr - Generates a sequence of ``if ... elseif ... else ... end`` statements. For example:: + Generates a sequence of ``if ... elseif ... else ... end`` statements. For example: - @nif 3 d->(i_d >= size(A,d)) d->(error("Dimension ", d, " too big")) d->println("All OK") + .. code-block:: julia + @nif 3 d->(i_d >= size(A,d)) d->(error("Dimension ", d, " too big")) d->println("All OK") - would generate:: + would generate: - if i_1 > size(A, 1) + .. code-block:: julia + if i_1 > size(A, 1) error("Dimension ", 1, " too big") elseif i_2 > size(A, 2) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 42970fe8155ae1..0bce057528c550 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -11,67 +11,89 @@ Basic functions .. function:: ndims(A) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + 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.:: + .. Docstring generated from Julia source + .. code-block:: julia + size(A, [dim...]) + + Returns a tuple containing the dimensions of A. Optionally you can specify the dimension(s) you want the length of, and get the length of that dimension, or a tuple of the lengths of dimensions you asked for.: - julia> A = rand(2,3,4); + .. code-block:: julia + julia> A = rand(2,3,4); - julia> size(A, 2) - 3 + julia> size(A, 2) + 3 - julia> size(A,3,2) - (4,3) + julia> size(A,3,2) + (4,3) .. function:: iseltype(A,T) + .. Docstring generated from Julia source + .. code-block:: julia + iseltype(A,T) + Tests whether A or its elements are of type T .. function:: length(A) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + length(A) -> Integer + Returns the number of elements in A - :: - length(collection) -> Integer + .. code-block:: julia + 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) + .. code-block:: julia + length(s) - The number of characters in string ``s``. + The number of characters in string ``s``\ . .. function:: eachindex(A...) - Creates an iterable object for visiting each index of an AbstractArray ``A`` in an efficient manner. For array types that have opted into fast linear indexing (like ``Array``), this is simply the range ``1:length(A)``. For other array types, this returns a specialized Cartesian range to efficiently index into the array with indices specified for every dimension. For other iterables, including strings and dictionaries, this returns an iterator object supporting arbitrary index types (e.g. unevenly spaced or non-integer indices). - - Example for a sparse 2-d array:: - - julia> A = sprand(2, 3, 0.5) - 2x3 sparse matrix with 4 Float64 entries: - [1, 1] = 0.598888 - [1, 2] = 0.0230247 - [1, 3] = 0.486499 - [2, 3] = 0.809041 - - julia> for iter in eachindex(A) - @show iter.I_1, iter.I_2 - @show A[iter] - end - (iter.I_1,iter.I_2) = (1,1) - A[iter] = 0.5988881393454597 - (iter.I_1,iter.I_2) = (2,1) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,2) - A[iter] = 0.02302469881746183 - (iter.I_1,iter.I_2) = (2,2) - A[iter] = 0.0 - (iter.I_1,iter.I_2) = (1,3) - A[iter] = 0.4864987874354343 - (iter.I_1,iter.I_2) = (2,3) - A[iter] = 0.8090413606455655 + .. Docstring generated from Julia source + .. code-block:: julia + 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: + + .. code-block:: julia + julia> A = sprand(2, 3, 0.5) + 2x3 sparse matrix with 4 Float64 entries: + [1, 1] = 0.598888 + [1, 2] = 0.0230247 + [1, 3] = 0.486499 + [2, 3] = 0.809041 + + julia> for iter in eachindex(A) + @show iter.I_1, iter.I_2 + @show A[iter] + end + (iter.I_1,iter.I_2) = (1,1) + A[iter] = 0.5988881393454597 + (iter.I_1,iter.I_2) = (2,1) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,2) + A[iter] = 0.02302469881746183 + (iter.I_1,iter.I_2) = (2,2) + A[iter] = 0.0 + (iter.I_1,iter.I_2) = (1,3) + A[iter] = 0.4864987874354343 + (iter.I_1,iter.I_2) = (2,3) + A[iter] = 0.8090413606455655 If you supply more than one ``AbstractArray`` argument, ``eachindex`` will create an iterable object that is fast for all arguments (a @@ -82,42 +104,71 @@ largest range along each dimension. .. function:: Base.linearindexing(A) - ``linearindexing`` defines how an AbstractArray most efficiently accesses its elements. If ``Base.linearindexing(A)`` returns ``Base.LinearFast()``, this means that linear indexing with only one index is an efficient operation. If it instead returns ``Base.LinearSlow()`` (by default), this means that the array intrinsically accesses its elements with indices specified for every dimension. Since converting a linear index to multiple indexing subscripts is typically very expensive, this provides a traits-based mechanism to enable efficient generic code for all array types. + .. Docstring generated from Julia source + .. code-block:: julia + Base.linearindexing(A) + + ``linearindexing`` defines how an AbstractArray most efficiently accesses its elements. If ``Base.linearindexing(A)`` returns ``Base.LinearFast()``\ , this means that linear indexing with only one index is an efficient operation. If it instead returns ``Base.LinearSlow()`` (by default), this means that the array intrinsically accesses its elements with indices specified for every dimension. Since converting a linear index to multiple indexing subscripts is typically very expensive, this provides a traits-based mechanism to enable efficient generic code for all array types. - An abstract array subtype ``MyArray`` that wishes to opt into fast linear indexing behaviors should define ``linearindexing`` in the type-domain:: + An abstract array subtype ``MyArray`` that wishes to opt into fast linear indexing behaviors should define ``linearindexing`` in the type-domain: + .. code-block:: julia Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast() .. function:: countnz(A) - Counts the number of nonzero values in array A (dense or sparse). Note that this is not a constant-time operation. For sparse matrices, one should usually use ``nnz``, which returns the number of stored values. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + conj!(A) + Convert an array to its complex conjugate in-place .. function:: stride(A, k) + .. Docstring generated from Julia source + .. code-block:: julia + stride(A, k) + Returns the distance in memory (in number of elements) between adjacent elements in dimension k .. function:: strides(A) + .. Docstring generated from Julia source + .. code-block:: julia + strides(A) + Returns a tuple of the memory strides in each dimension .. function:: ind2sub(dims, index) -> subscripts + .. Docstring generated from Julia source + :: + + ind2sub(dims, index) -> subscripts + Returns a tuple of subscripts into an array with dimensions ``dims``, corresponding to the linear index ``index`` **Example** ``i, j, ... = ind2sub(size(A), indmax(A))`` provides the indices of the maximum element :: + ind2sub(a, index) -> subscripts Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` .. function:: ind2sub(a, index) -> subscripts + .. Docstring generated from Julia source :: + ind2sub(dims, index) -> subscripts Returns a tuple of subscripts into an array with dimensions ``dims``, corresponding to the linear index ``index`` @@ -125,33 +176,47 @@ largest range along each dimension. **Example** ``i, j, ... = ind2sub(size(A), indmax(A))`` provides the indices of the maximum element :: + ind2sub(a, index) -> subscripts Returns a tuple of subscripts into array ``a`` corresponding to the linear index ``index`` .. function:: sub2ind(dims, i, j, k...) -> index - The inverse of ``ind2sub``, returns the linear index corresponding to the provided subscripts + .. Docstring generated from Julia source + .. code-block:: julia + sub2ind(dims, i, j, k...) -> index + + The inverse of ``ind2sub``\ , returns the linear index corresponding to the provided subscripts Constructors ------------ .. function:: Array(dims) - ``Array{T}(dims)`` constructs an uninitialized dense array with element type ``T``. - ``dims`` may be a tuple or a series of integer arguments. - The syntax ``Array(T, dims)`` is also available, but deprecated. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: getindex(type[, elements...]) + .. Docstring generated from Julia source + :: + + getindex(type[, elements...]) + Construct a 1-d array of the specified type. This is usually called with the syntax ``Type[]``. Element values can be specified using ``Type[a,b,c,...]``. :: + getindex(A, inds...) Returns a subset of array ``A`` as specified by ``inds``, where each ``ind`` may be an ``Int``, a ``Range``, or a ``Vector``. See the manual section on :ref:`array indexing ` for details. :: + getindex(collection, key...) Retrieve the value(s) stored at the given key or index within a collection. @@ -160,139 +225,191 @@ Constructors .. function:: cell(dims) + .. Docstring generated from Julia source + .. code-block:: julia + cell(dims) + Construct an uninitialized cell array (heterogeneous array). ``dims`` can be either a tuple or a series of integer arguments. .. function:: zeros(type, dims) + .. Docstring generated from Julia source + .. code-block:: julia + zeros(type, dims) + Create an array of all zeros of specified type. The type defaults to Float64 if not specified. - :: - zeros(A) + .. code-block:: julia + zeros(A) Create an array of all zeros with the same element type and shape as A. .. function:: zeros(A) - :: - zeros(type, dims) + .. Docstring generated from Julia source + .. code-block:: julia + zeros(type, dims) Create an array of all zeros of specified type. The type defaults to Float64 if not specified. - :: - zeros(A) + .. code-block:: julia + zeros(A) Create an array of all zeros with the same element type and shape as A. .. function:: ones(type, dims) + .. Docstring generated from Julia source + .. code-block:: julia + ones(type, dims) + Create an array of all ones of specified type. The type defaults to Float64 if not specified. - :: - ones(A) + .. code-block:: julia + ones(A) Create an array of all ones with the same element type and shape as A. .. function:: ones(A) - :: - ones(type, dims) + .. Docstring generated from Julia source + .. code-block:: julia + ones(type, dims) Create an array of all ones of specified type. The type defaults to Float64 if not specified. - :: - ones(A) + .. code-block:: julia + ones(A) Create an array of all ones with the same element type and shape as A. .. function:: trues(dims) + .. Docstring generated from Julia source + .. code-block:: julia + trues(dims) + Create a ``BitArray`` with all values set to true .. function:: falses(dims) + .. Docstring generated from Julia source + .. code-block:: julia + falses(dims) + Create a ``BitArray`` with all values set to false .. function:: fill(x, dims) - Create an array filled with the value ``x``. - For example, ``fill(1.0, (10,10))`` returns a 10x10 array of floats, with each - element initialized to 1.0. + .. Docstring generated from Julia source + .. code-block:: julia + fill(x, dims) - If ``x`` is an object reference, all elements will refer to the same object. - ``fill(Foo(), dims)`` will return an array filled with the result of evaluating ``Foo()`` once. + Create an array filled with the value ``x``\ . For example, ``fill(1.0, (10,10))`` returns a 10x10 array of floats, with each element initialized to 1.0. + + If ``x`` is an object reference, all elements will refer to the same object. ``fill(Foo(), dims)`` will return an array filled with the result of evaluating ``Foo()`` once. .. function:: fill!(A, x) - Fill array ``A`` with the value ``x``. If ``x`` is an object reference, all elements will refer to the same object. - ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating ``Foo()`` once. + .. Docstring generated from Julia source + .. code-block:: julia + fill!(A, x) + + Fill array ``A`` with the value ``x``\ . If ``x`` is an object reference, all elements will refer to the same object. ``fill!(A, Foo())`` will return ``A`` filled with the result of evaluating ``Foo()`` once. .. function:: reshape(A, dims) + .. Docstring generated from Julia source + .. code-block:: julia + reshape(A, dims) + Create an array with the same data as the given array, but with different dimensions. An implementation for a particular type of array may choose whether the data is copied or shared. .. function:: similar(array, element_type, dims) + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: reinterpret(type, A) - Change the type-interpretation of a block of memory. For example, ``reinterpret(Float32, UInt32(7))`` interprets the 4 bytes corresponding to ``UInt32(7)`` as a ``Float32``. For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. + .. Docstring generated from Julia source + .. code-block:: julia + reinterpret(type, A) + + Change the type-interpretation of a block of memory. For example, ``reinterpret(Float32, UInt32(7))`` interprets the 4 bytes corresponding to ``UInt32(7)`` as a ``Float32``\ . For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. .. function:: eye(n) + .. Docstring generated from Julia source + .. code-block:: julia + eye(n) + n-by-n identity matrix - :: - eye(m, n) + .. code-block:: julia + eye(m, n) m-by-n identity matrix - :: - eye(A) + .. code-block:: julia + eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. + Constructs an identity matrix of the same dimensions and type as ``A``\ . .. function:: eye(m, n) - :: - eye(n) + .. Docstring generated from Julia source + .. code-block:: julia + eye(n) n-by-n identity matrix - :: - eye(m, n) + .. code-block:: julia + eye(m, n) m-by-n identity matrix - :: - eye(A) + .. code-block:: julia + eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. + Constructs an identity matrix of the same dimensions and type as ``A``\ . .. function:: eye(A) - :: - eye(n) + .. Docstring generated from Julia source + .. code-block:: julia + eye(n) n-by-n identity matrix - :: - eye(m, n) + .. code-block:: julia + eye(m, n) m-by-n identity matrix - :: - eye(A) + .. code-block:: julia + eye(A) - Constructs an identity matrix of the same dimensions and type as ``A``. + Constructs an identity matrix of the same dimensions and type as ``A``\ . .. function:: linspace(start, stop, n=100) - Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``. + .. Docstring generated from Julia source + .. code-block:: julia + linspace(start, stop, n=100) + + Construct a range of ``n`` linearly spaced elements from ``start`` to ``stop``\ . .. function:: logspace(start, stop, n=50) - Construct a vector of ``n`` logarithmically spaced numbers from ``10^start`` to ``10^stop``. + .. Docstring generated from Julia source + .. code-block:: julia + logspace(start, stop, n=50) + + Construct a vector of ``n`` logarithmically spaced numbers from ``10^start`` to ``10^stop``\ . Mathematical operators and functions ------------------------------------ @@ -301,43 +418,64 @@ All mathematical operations and functions are supported for arrays .. function:: broadcast(f, As...) + .. Docstring generated from Julia source + .. code-block:: julia + 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:: 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)``. + .. Docstring generated from Julia source + .. code-block:: julia + 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)``\ . .. function:: bitbroadcast(f, As...) - Like ``broadcast``, but allocates a ``BitArray`` to store the result, rather then an ``Array``. + .. Docstring generated from Julia source + .. code-block:: julia + bitbroadcast(f, As...) + + Like ``broadcast``\ , but allocates a ``BitArray`` to store the result, rather then an ``Array``\ . .. function:: broadcast_function(f) - Returns a function ``broadcast_f`` such that ``broadcast_function(f)(As...) === broadcast(f, As...)``. Most useful in the form ``const broadcast_f = broadcast_function(f)``. + .. Docstring generated from Julia source + .. code-block:: julia + broadcast_function(f) + + Returns a function ``broadcast_f`` such that ``broadcast_function(f)(As...) === broadcast(f, As...)``\ . Most useful in the form ``const broadcast_f = broadcast_function(f)``\ . .. function:: broadcast!_function(f) - Like ``broadcast_function``, but for ``broadcast!``. + .. Docstring generated from Julia source + .. code-block:: julia + broadcast!_function(f) + + Like ``broadcast_function``\ , but for ``broadcast!``\ . Indexing, Assignment, and Concatenation --------------------------------------- .. function:: getindex(A, inds...) + .. Docstring generated from Julia source :: + getindex(type[, elements...]) Construct a 1-d array of the specified type. This is usually called with the syntax ``Type[]``. Element values can be specified using ``Type[a,b,c,...]``. :: + getindex(A, inds...) Returns a subset of array ``A`` as specified by ``inds``, where each ``ind`` may be an ``Int``, a ``Range``, or a ``Vector``. See the manual section on :ref:`array indexing ` for details. :: + getindex(collection, key...) Retrieve the value(s) stored at the given key or index within a collection. @@ -346,355 +484,466 @@ Indexing, Assignment, and Concatenation .. function:: sub(A, inds...) + .. Docstring generated from Julia source + :: + + sub(A, inds...) + Like :func:`getindex`, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling :func:`getindex` or :func:`setindex!` on the returned :obj:`SubArray` computes the indices to the parent array on the fly without checking bounds. .. function:: parent(A) + .. Docstring generated from Julia source + .. code-block:: julia + parent(A) + Returns the "parent array" of an array view type (e.g., SubArray), or the array itself if it is not a view .. function:: parentindexes(A) - From an array view ``A``, returns the corresponding indexes in the parent + .. Docstring generated from Julia source + .. code-block:: julia + parentindexes(A) + + From an array view ``A``\ , returns the corresponding indexes in the parent .. function:: slicedim(A, d, i) - Return all the data of ``A`` where the index for dimension ``d`` equals ``i``. Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``. + .. Docstring generated from Julia source + .. code-block:: julia + slicedim(A, d, i) + + Return all the data of ``A`` where the index for dimension ``d`` equals ``i``\ . Equivalent to ``A[:,:,...,i,:,:,...]`` where ``i`` is in position ``d``\ . .. function:: slice(A, inds...) + .. Docstring generated from Julia source + :: + + slice(A, inds...) + Returns a view of array ``A`` with the given indices like :func:`sub`, but drops all dimensions indexed with scalars. .. function:: setindex!(A, X, inds...) - Store values from array ``X`` within some subset of ``A`` as specified by ``inds``. + .. Docstring generated from Julia source + .. code-block:: julia + setindex!(A, X, inds...) - :: - setindex!(collection, value, key...) + Store values from array ``X`` within some subset of ``A`` as specified by ``inds``\ . + + .. code-block:: julia + setindex!(collection, value, key...) - Store the given value at the given key or index within a collection. - The syntax ``a[i,j,...] = x`` is converted by the compiler to - ``setindex!(a, x, i, j, ...)``. + Store the given value at the given key or index within a collection. The syntax ``a[i,j,...] = x`` is converted by the compiler to ``setindex!(a, x, i, j, ...)``\ . .. function:: broadcast_getindex(A, inds...) - Broadcasts the ``inds`` arrays to a common size like ``broadcast``, and returns an array of the results ``A[ks...]``, where ``ks`` goes over the positions in the broadcast. + .. Docstring generated from Julia source + .. code-block:: julia + broadcast_getindex(A, inds...) + + Broadcasts the ``inds`` arrays to a common size like ``broadcast``\ , and returns an array of the results ``A[ks...]``\ , where ``ks`` goes over the positions in the broadcast. .. function:: broadcast_setindex!(A, X, inds...) - Broadcasts the ``X`` and ``inds`` arrays to a common size and stores the value from each position in ``X`` at the indices given by the same positions in ``inds``. + .. Docstring generated from Julia source + .. code-block:: julia + broadcast_setindex!(A, X, inds...) + + Broadcasts the ``X`` and ``inds`` arrays to a common size and stores the value from each position in ``X`` at the indices given by the same positions in ``inds``\ . .. function:: cat(dims, A...) - Concatenate the input arrays along the specified dimensions in the iterable ``dims``. For dimensions not in ``dims``, all input arrays should have the same size, which will also be the size of the output array along that dimension. For dimensions in ``dims``, the size of the output array is the sum of the sizes of the input arrays along that dimension. If ``dims`` is a single number, the different arrays are tightly stacked along that dimension. If ``dims`` is an iterable containing several dimensions, this allows to construct block diagonal matrices and their higher-dimensional analogues by simultaneously increasing several dimensions for every new input array and putting zero blocks elsewhere. For example, ``cat([1,2], matrices...)`` builds a block diagonal matrix, i.e. a block matrix with ``matrices[1]``, ``matrices[2]``, ... as diagonal blocks and matching zero blocks away from the diagonal. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: vcat(A...) + .. Docstring generated from Julia source + .. code-block:: julia + vcat(A...) + Concatenate along dimension 1 .. function:: hcat(A...) + .. Docstring generated from Julia source + .. code-block:: julia + hcat(A...) + Concatenate along dimension 2 .. function:: hvcat(rows::Tuple{Vararg{Int}}, values...) - Horizontal and vertical concatenation in one call. This function is called for - block matrix syntax. The first argument specifies the number of arguments to - concatenate in each block row. - For example, ``[a b;c d e]`` calls ``hvcat((2,3),a,b,c,d,e)``. + .. Docstring generated from Julia source + .. code-block:: julia + hvcat(rows::Tuple{Vararg{Int}}, values...) + + Horizontal and vertical concatenation in one call. This function is called for block matrix syntax. The first argument specifies the number of arguments to concatenate in each block row. For example, ``[a b;c d e]`` calls ``hvcat((2,3),a,b,c,d,e)``\ . - If the first argument is a single integer ``n``, then all block rows are assumed to have ``n`` block columns. + If the first argument is a single integer ``n``\ , then all block rows are assumed to have ``n`` block columns. .. function:: flipdim(A, d) - Reverse ``A`` in dimension ``d``. + .. Docstring generated from Julia source + .. code-block:: julia + flipdim(A, d) + + Reverse ``A`` in dimension ``d``\ . .. function:: circshift(A,shifts) + .. Docstring generated from Julia source + .. code-block:: julia + circshift(A,shifts) + Circularly shift the data in an array. The second argument is a vector giving the amount to shift in each dimension. .. function:: find(A) - Return a vector of the linear indexes of the non-zeros in ``A`` - (determined by ``A[i]!=0``). A common use of this is to convert a - boolean array to an array of indexes of the ``true`` - elements. + .. Docstring generated from Julia source + .. code-block:: julia + find(A) - :: - find(f,A) + Return a vector of the linear indexes of the non-zeros in ``A`` (determined by ``A[i]!=0``\ ). A common use of this is to convert a boolean array to an array of indexes of the ``true`` elements. + + .. code-block:: julia + find(f,A) - Return a vector of the linear indexes of ``A`` where ``f`` returns true. + Return a vector of the linear indexes of ``A`` where ``f`` returns true. .. function:: find(f,A) - :: - find(A) + .. Docstring generated from Julia source + .. code-block:: julia + find(A) - Return a vector of the linear indexes of the non-zeros in ``A`` - (determined by ``A[i]!=0``). A common use of this is to convert a - boolean array to an array of indexes of the ``true`` - elements. + Return a vector of the linear indexes of the non-zeros in ``A`` (determined by ``A[i]!=0``\ ). A common use of this is to convert a boolean array to an array of indexes of the ``true`` elements. - :: - find(f,A) + .. code-block:: julia + find(f,A) - Return a vector of the linear indexes of ``A`` where ``f`` returns true. + Return a vector of the linear indexes of ``A`` where ``f`` returns true. .. function:: findn(A) - Return a vector of indexes for each dimension giving the locations of the non-zeros in ``A`` (determined by ``A[i]!=0``). + .. Docstring generated from Julia source + .. code-block:: julia + findn(A) + + Return a vector of indexes for each dimension giving the locations of the non-zeros in ``A`` (determined by ``A[i]!=0``\ ). .. function:: findnz(A) - Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and - column indexes of the non-zero values in matrix ``A``, and ``V`` is - a vector of the non-zero values. + .. Docstring generated from Julia source + .. code-block:: julia + findnz(A) + + Return a tuple ``(I, J, V)`` where ``I`` and ``J`` are the row and column indexes of the non-zero values in matrix ``A``\ , and ``V`` is a vector of the non-zero values. .. function:: findfirst(A) - Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + .. Docstring generated from Julia source + .. code-block:: julia + findfirst(A) - :: - findfirst(A,v) + Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``\ ). - Return the index of the first element equal to ``v`` in ``A``. + .. code-block:: julia + findfirst(A,v) - :: - findfirst(predicate, A) + Return the index of the first element equal to ``v`` in ``A``\ . + + .. code-block:: julia + findfirst(predicate, A) Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findfirst(A,v) - :: - findfirst(A) + .. Docstring generated from Julia source + .. code-block:: julia + findfirst(A) - Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``\ ). - :: - findfirst(A,v) + .. code-block:: julia + findfirst(A,v) - Return the index of the first element equal to ``v`` in ``A``. + Return the index of the first element equal to ``v`` in ``A``\ . - :: - findfirst(predicate, A) + .. code-block:: julia + findfirst(predicate, A) Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findfirst(predicate, A) - :: - findfirst(A) + .. Docstring generated from Julia source + .. code-block:: julia + findfirst(A) - Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``\ ). - :: - findfirst(A,v) + .. code-block:: julia + findfirst(A,v) - Return the index of the first element equal to ``v`` in ``A``. + Return the index of the first element equal to ``v`` in ``A``\ . - :: - findfirst(predicate, A) + .. code-block:: julia + findfirst(predicate, A) Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findlast(A) - Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + .. Docstring generated from Julia source + .. code-block:: julia + findlast(A) - :: - findlast(A, v) + Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``\ ). - Return the index of the last element equal to ``v`` in ``A``. + .. code-block:: julia + findlast(A, v) - :: - findlast(predicate, A) + Return the index of the last element equal to ``v`` in ``A``\ . + + .. code-block:: julia + findlast(predicate, A) Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findlast(A, v) - :: - findlast(A) + .. Docstring generated from Julia source + .. code-block:: julia + findlast(A) - Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``\ ). - :: - findlast(A, v) + .. code-block:: julia + findlast(A, v) - Return the index of the last element equal to ``v`` in ``A``. + Return the index of the last element equal to ``v`` in ``A``\ . - :: - findlast(predicate, A) + .. code-block:: julia + findlast(predicate, A) Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findlast(predicate, A) - :: - findlast(A) + .. Docstring generated from Julia source + .. code-block:: julia + findlast(A) - Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``\ ). - :: - findlast(A, v) + .. code-block:: julia + findlast(A, v) - Return the index of the last element equal to ``v`` in ``A``. + Return the index of the last element equal to ``v`` in ``A``\ . - :: - findlast(predicate, A) + .. code-block:: julia + findlast(predicate, A) Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findnext(A, i) - Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + .. Docstring generated from Julia source + .. code-block:: julia + findnext(A, i) - :: - findnext(predicate, A, i) + Find the next index >= ``i`` of a non-zero element of ``A``\ , or ``0`` if not found. + + .. code-block:: julia + findnext(predicate, A, i) Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. - :: - findnext(A, v, i) + .. code-block:: julia + findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``\ ), or ``0`` if not found. .. function:: findnext(predicate, A, i) - :: - findnext(A, i) + .. Docstring generated from Julia source + .. code-block:: julia + findnext(A, i) - Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + Find the next index >= ``i`` of a non-zero element of ``A``\ , or ``0`` if not found. - :: - findnext(predicate, A, i) + .. code-block:: julia + findnext(predicate, A, i) Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. - :: - findnext(A, v, i) + .. code-block:: julia + findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``\ ), or ``0`` if not found. .. function:: findnext(A, v, i) - :: - findnext(A, i) + .. Docstring generated from Julia source + .. code-block:: julia + findnext(A, i) - Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + Find the next index >= ``i`` of a non-zero element of ``A``\ , or ``0`` if not found. - :: - findnext(predicate, A, i) + .. code-block:: julia + findnext(predicate, A, i) Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. - :: - findnext(A, v, i) + .. code-block:: julia + findnext(A, v, i) - Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``\ ), or ``0`` if not found. .. function:: findprev(A, i) - Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + .. Docstring generated from Julia source + .. code-block:: julia + findprev(A, i) - :: - findprev(predicate, A, i) + Find the previous index <= ``i`` of a non-zero element of ``A``\ , or 0 if not found. + + .. code-block:: julia + findprev(predicate, A, i) Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. - :: - findprev(A, v, i) + .. code-block:: julia + findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``\ ), or ``0`` if not found. .. function:: findprev(predicate, A, i) - :: - findprev(A, i) + .. Docstring generated from Julia source + .. code-block:: julia + findprev(A, i) - Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + Find the previous index <= ``i`` of a non-zero element of ``A``\ , or 0 if not found. - :: - findprev(predicate, A, i) + .. code-block:: julia + findprev(predicate, A, i) Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. - :: - findprev(A, v, i) + .. code-block:: julia + findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``\ ), or ``0`` if not found. .. function:: findprev(A, v, i) - :: - findprev(A, i) + .. Docstring generated from Julia source + .. code-block:: julia + findprev(A, i) - Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + Find the previous index <= ``i`` of a non-zero element of ``A``\ , or 0 if not found. - :: - findprev(predicate, A, i) + .. code-block:: julia + findprev(predicate, A, i) Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. - :: - findprev(A, v, i) + .. code-block:: julia + findprev(A, v, i) - Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), - or ``0`` if not found. + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``\ ), or ``0`` if not found. .. function:: permutedims(A, perm) - Permute the dimensions of array ``A``. ``perm`` is a vector specifying a permutation of length ``ndims(A)``. This is a generalization of transpose for multi-dimensional arrays. Transpose is equivalent to ``permutedims(A, [2,1])``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + ipermutedims(A, perm) + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: squeeze(A, dims) - Remove the dimensions specified by ``dims`` from array ``A``. Elements of - ``dims`` must be unique and within the range ``1:ndims(A)``. + .. Docstring generated from Julia source + .. code-block:: julia + squeeze(A, dims) + + Remove the dimensions specified by ``dims`` from array ``A``\ . Elements of ``dims`` must be unique and within the range ``1:ndims(A)``\ . .. function:: vec(Array) -> Vector + .. Docstring generated from Julia source + .. code-block:: julia + vec(Array) -> Vector + Vectorize an array using column-major convention. .. function:: promote_shape(s1, s2) - Check two array shapes for compatibility, allowing trailing singleton dimensions, - and return whichever shape has more dimensions. + .. Docstring generated from Julia source + .. code-block:: julia + 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...) + .. Docstring generated from Julia source + .. code-block:: julia + checkbounds(array, indexes...) + Throw an error if the specified indexes are not in bounds for the given array. .. function:: randsubseq(A, p) -> Vector - Return a vector consisting of a random subsequence of the given array ``A``, - where each element of ``A`` is included (in order) with independent - probability ``p``. (Complexity is linear in ``p*length(A)``, so this - function is efficient even if ``p`` is small and ``A`` is large.) Technically, - this process is known as "Bernoulli sampling" of ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + randsubseq(A, p) -> Vector + + Return a vector consisting of a random subsequence of the given array ``A``\ , where each element of ``A`` is included (in order) with independent probability ``p``\ . (Complexity is linear in ``p*length(A)``\ , so this function is efficient even if ``p`` is small and ``A`` is large.) Technically, this process is known as "Bernoulli sampling" of ``A``\ . .. function:: randsubseq!(S, A, p) - Like ``randsubseq``, but the results are stored in ``S`` (which is - resized as needed). + .. Docstring generated from Julia source + .. code-block:: julia + randsubseq!(S, A, p) + + Like ``randsubseq``\ , but the results are stored in ``S`` (which is resized as needed). Array functions --------------- .. function:: cumprod(A, [dim]) + .. Docstring generated from Julia source + :: + + cumprod(A, [dim]) + Cumulative product along a dimension ``dim`` (defaults to 1). See also :func:`cumprod!` to use a preallocated output array, both for performance and to control the precision of the @@ -702,11 +951,19 @@ Array functions .. function:: cumprod!(B, A, [dim]) - Cumulative product of ``A`` along a dimension, storing the result in ``B``. - The dimension defaults to 1. + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. Docstring generated from Julia source + :: + + cumsum(A, [dim]) + Cumulative sum along a dimension ``dim`` (defaults to 1). See also :func:`cumsum!` to use a preallocated output array, both for performance and to control the precision of the @@ -714,134 +971,171 @@ Array functions .. function:: cumsum!(B, A, [dim]) - Cumulative sum of ``A`` along a dimension, storing the result in ``B``. - The dimension defaults to 1. + .. Docstring generated from Julia source + .. code-block:: julia + cumsum!(B, A, [dim]) + + Cumulative sum of ``A`` along a dimension, storing the result in ``B``\ . The dimension defaults to 1. .. function:: cumsum_kbn(A, [dim]) - Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier - compensated summation algorithm for additional accuracy. - The dimension defaults to 1. + .. Docstring generated from Julia source + .. code-block:: julia + cumsum_kbn(A, [dim]) + + Cumulative sum along a dimension, using the Kahan-Babuska-Neumaier compensated summation algorithm for additional accuracy. The dimension defaults to 1. .. function:: cummin(A, [dim]) - Cumulative minimum along a dimension. - The dimension defaults to 1. + .. Docstring generated from Julia source + .. code-block:: julia + cummin(A, [dim]) + + Cumulative minimum along a dimension. The dimension defaults to 1. .. function:: cummax(A, [dim]) - Cumulative maximum along a dimension. - The dimension defaults to 1. + .. Docstring generated from Julia source + .. code-block:: julia + cummax(A, [dim]) + + Cumulative maximum along a dimension. The dimension defaults to 1. .. function:: diff(A, [dim]) + .. Docstring generated from Julia source + .. code-block:: julia + diff(A, [dim]) + Finite difference operator of matrix or vector. .. function:: gradient(F, [h]) - Compute differences along vector ``F``, using ``h`` as the spacing between points. - The default spacing is one. + .. Docstring generated from Julia source + .. code-block:: julia + gradient(F, [h]) + + Compute differences along vector ``F``\ , using ``h`` as the spacing between points. The default spacing is one. .. function:: rot180(A) + .. Docstring generated from Julia source + .. code-block:: julia + rot180(A) + Rotate matrix ``A`` 180 degrees. - :: - rot180(A, k) + .. code-block:: julia + rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. - If ``k`` is even, this is equivalent to a ``copy``. + Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``\ . .. function:: rot180(A, k) - :: - rot180(A) + .. Docstring generated from Julia source + .. code-block:: julia + rot180(A) Rotate matrix ``A`` 180 degrees. - :: - rot180(A, k) + .. code-block:: julia + rot180(A, k) - Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. - If ``k`` is even, this is equivalent to a ``copy``. + Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``\ . .. function:: rotl90(A) + .. Docstring generated from Julia source + .. code-block:: julia + rotl90(A) + Rotate matrix ``A`` left 90 degrees. - :: - rotl90(A, k) + .. code-block:: julia + rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` - is zero or a multiple of four, this is equivalent to a ``copy``. + Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``\ . .. function:: rotl90(A, k) - :: - rotl90(A) + .. Docstring generated from Julia source + .. code-block:: julia + rotl90(A) Rotate matrix ``A`` left 90 degrees. - :: - rotl90(A, k) + .. code-block:: julia + rotl90(A, k) - Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` - is zero or a multiple of four, this is equivalent to a ``copy``. + Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``\ . .. function:: rotr90(A) + .. Docstring generated from Julia source + .. code-block:: julia + rotr90(A) + Rotate matrix ``A`` right 90 degrees. - :: - rotr90(A, k) + .. code-block:: julia + rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` - is zero or a multiple of four, this is equivalent to a ``copy``. + Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``\ . .. function:: rotr90(A, k) - :: - rotr90(A) + .. Docstring generated from Julia source + .. code-block:: julia + rotr90(A) Rotate matrix ``A`` right 90 degrees. - :: - rotr90(A, k) + .. code-block:: julia + rotr90(A, k) - Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` - is zero or a multiple of four, this is equivalent to a ``copy``. + Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``\ . .. function:: reducedim(f, A, dims[, initial]) - Reduce 2-argument function ``f`` along dimensions of ``A``. ``dims`` is a - vector specifying the dimensions to reduce, and ``initial`` is the initial - value to use in the reductions. For ``+``, ``*``, ``max`` and ``min`` the ``initial`` - argument is optional. + .. Docstring generated from Julia source + .. code-block:: julia + reducedim(f, A, dims[, initial]) + + Reduce 2-argument function ``f`` along dimensions of ``A``\ . ``dims`` is a vector specifying the dimensions to reduce, and ``initial`` is the initial value to use in the reductions. For ``+``\ , ``*``\ , ``max`` and ``min`` the ``initial`` argument is optional. - The associativity of the reduction is implementation-dependent; if you - need a particular associativity, e.g. left-to-right, you should write - your own loop. See documentation for ``reduce``. + The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for ``reduce``\ . .. function:: mapreducedim(f, op, A, dims[, initial]) - Evaluates to the same as ``reducedim(op, map(f, A), dims, f(initial))``, but - is generally faster because the intermediate array is avoided. + .. Docstring generated from Julia source + .. code-block:: julia + mapreducedim(f, op, A, dims[, initial]) + + Evaluates to the same as ``reducedim(op, map(f, A), dims, f(initial))``\ , but is generally faster because the intermediate array is avoided. .. function:: mapslices(f, A, dims) - Transform the given dimensions of array ``A`` using function ``f``. ``f`` - is called on each slice of ``A`` of the form ``A[...,:,...,:,...]``. - ``dims`` is an integer vector specifying where the colons go in this - expression. The results are concatenated along the remaining dimensions. - For example, if ``dims`` is ``[1,2]`` and A is 4-dimensional, ``f`` is - called on ``A[:,:,i,j]`` for all ``i`` and ``j``. + .. Docstring generated from Julia source + .. code-block:: julia + mapslices(f, A, dims) + + Transform the given dimensions of array ``A`` using function ``f``\ . ``f`` is called on each slice of ``A`` of the form ``A[...,:,...,:,...]``\ . ``dims`` is an integer vector specifying where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if ``dims`` is ``[1,2]`` and A is 4-dimensional, ``f`` is called on ``A[:,:,i,j]`` for all ``i`` and ``j``\ . .. function:: sum_kbn(A) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + 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. @@ -858,324 +1152,341 @@ Combinatorics .. function:: nthperm(v, k) + .. Docstring generated from Julia source + .. code-block:: julia + nthperm(v, k) + Compute the kth lexicographic permutation of a vector. - :: - nthperm(p) + .. code-block:: julia + nthperm(p) - Return the ``k`` that generated permutation ``p``. - Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``. + Return the ``k`` that generated permutation ``p``\ . Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``\ . .. function:: nthperm(p) - :: - nthperm(v, k) + .. Docstring generated from Julia source + .. code-block:: julia + nthperm(v, k) Compute the kth lexicographic permutation of a vector. - :: - nthperm(p) + .. code-block:: julia + nthperm(p) - Return the ``k`` that generated permutation ``p``. - Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``. + Return the ``k`` that generated permutation ``p``\ . Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``\ . .. function:: nthperm!(v, k) + .. Docstring generated from Julia source + :: + + nthperm!(v, k) + In-place version of :func:`nthperm`. .. function:: randperm([rng,] n) + .. Docstring generated from Julia source + :: + + randperm([rng,] n) + Construct a random permutation of length ``n``. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers `. .. function:: invperm(v) + .. Docstring generated from Julia source + .. code-block:: julia + invperm(v) + Return the inverse permutation of v. .. function:: isperm(v) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isperm(v) -> Bool + Returns true if v is a valid permutation. .. function:: permute!(v, p) - Permute vector ``v`` in-place, according to permutation ``p``. No - checking is done to verify that ``p`` is a permutation. + .. Docstring generated from Julia source + .. code-block:: julia + permute!(v, p) - To return a new permutation, use ``v[p]``. Note that this is - generally faster than ``permute!(v,p)`` for large vectors. + Permute vector ``v`` in-place, according to permutation ``p``\ . No checking is done to verify that ``p`` is a permutation. + + To return a new permutation, use ``v[p]``\ . Note that this is generally faster than ``permute!(v,p)`` for large vectors. .. function:: ipermute!(v, p) + .. Docstring generated from Julia source + .. code-block:: julia + ipermute!(v, p) + Like permute!, but the inverse of the given permutation is applied. .. function:: randcycle([rng,] n) + .. Docstring generated from Julia source + :: + + 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:: shuffle([rng,] v) + .. Docstring generated from Julia source + :: + + shuffle([rng,] v) + Return a randomly permuted copy of ``v``. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers `. .. function:: shuffle!([rng,] v) + .. Docstring generated from Julia source + :: + + shuffle!([rng,] v) + In-place version of :func:`shuffle`. .. function:: reverse(v [, start=1 [, stop=length(v) ]] ) + .. Docstring generated from Julia source + .. code-block:: julia + reverse(v [, start=1 [, stop=length(v) ]] ) + Return a copy of ``v`` reversed from start to stop. .. function:: reverseind(v, i) - Given an index ``i`` in ``reverse(v)``, return the corresponding - index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``. - (This can be nontrivial in the case where ``v`` is a Unicode string.) + .. Docstring generated from Julia source + .. code-block:: julia + reverseind(v, i) + + Given an index ``i`` in ``reverse(v)``\ , return the corresponding index in ``v`` so that ``v[reverseind(v,i)] == reverse(v)[i]``\ . (This can be nontrivial in the case where ``v`` is a Unicode string.) .. function:: reverse!(v [, start=1 [, stop=length(v) ]]) -> v + .. Docstring generated from Julia source + :: + + reverse!(v [, start=1 [, stop=length(v) ]]) -> v + In-place version of :func:`reverse`. .. function:: combinations(array, n) - Generate all combinations of ``n`` elements from an indexable - object. Because the number of combinations can be very large, this - function returns an iterator object. Use - ``collect(combinations(array,n))`` to get an array of all combinations. + .. Docstring generated from Julia source + .. code-block:: julia + combinations(array, n) + + Generate all combinations of ``n`` elements from an indexable object. Because the number of combinations can be very large, this function returns an iterator object. Use ``collect(combinations(array,n))`` to get an array of all combinations. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + permutations(array) + + Generate all permutations of an indexable object. Because the number of permutations can be very large, this function returns an iterator object. Use ``collect(permutations(array))`` to get an array of all permutations. .. function:: partitions(n) - Generate all integer arrays that sum to ``n``. Because the number of - partitions can be very large, this function returns an iterator - object. Use ``collect(partitions(n))`` to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n))``. + .. Docstring generated from Julia source + .. code-block:: julia + partitions(n) - :: - partitions(n, m) + Generate all integer arrays that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n))``\ . - Generate all 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))``. + .. code-block:: julia + partitions(n, m) - :: - partitions(array) + Generate all arrays of ``m`` integers that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n,m))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n,m))``\ . - Generate all set partitions of the elements of an array, - 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))``. + .. code-block:: julia + partitions(array) - :: - partitions(array, m) + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(array))``\ . + + .. code-block:: julia + partitions(array, m) - Generate all set partitions of the elements of an array into exactly m - subsets, represented as arrays of arrays. Because the number of - partitions can be very large, this function returns an iterator object. - Use ``collect(partitions(array,m))`` to get an array of all partitions. - The number of partitions into m subsets is equal to the Stirling number - of the second kind and can be efficiently computed using - ``length(partitions(array,m))``. + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``\ . .. function:: partitions(n, m) - :: - partitions(n) + .. Docstring generated from Julia source + .. code-block:: julia + partitions(n) - Generate all integer arrays that sum to ``n``. Because the number of - partitions can be very large, this function returns an iterator - object. Use ``collect(partitions(n))`` to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n))``. + Generate all integer arrays that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n))``\ . - :: - partitions(n, m) + .. code-block:: julia + partitions(n, m) - Generate all arrays of ``m`` integers that sum to ``n``. Because - the number of partitions can be very large, this function returns an - iterator object. Use ``collect(partitions(n,m))`` to get an array of - all partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n,m))``. + Generate all arrays of ``m`` integers that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n,m))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n,m))``\ . - :: - partitions(array) + .. code-block:: julia + partitions(array) - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - ``collect(partitions(array))`` to get an array of all partitions. - The number of partitions to generate can be efficiently - computed using ``length(partitions(array))``. + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(array))``\ . - :: - partitions(array, m) + .. code-block:: julia + partitions(array, m) - Generate all set partitions of the elements of an array into exactly m - subsets, represented as arrays of arrays. Because the number of - partitions can be very large, this function returns an iterator object. - Use ``collect(partitions(array,m))`` to get an array of all partitions. - The number of partitions into m subsets is equal to the Stirling number - of the second kind and can be efficiently computed using - ``length(partitions(array,m))``. + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``\ . .. function:: partitions(array) - :: - partitions(n) + .. Docstring generated from Julia source + .. code-block:: julia + partitions(n) - Generate all integer arrays that sum to ``n``. Because the number of - partitions can be very large, this function returns an iterator - object. Use ``collect(partitions(n))`` to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n))``. + Generate all integer arrays that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n))``\ . - :: - partitions(n, m) + .. code-block:: julia + partitions(n, m) - Generate all arrays of ``m`` integers that sum to ``n``. Because - the number of partitions can be very large, this function returns an - iterator object. Use ``collect(partitions(n,m))`` to get an array of - all partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n,m))``. + Generate all arrays of ``m`` integers that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n,m))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n,m))``\ . - :: - partitions(array) + .. code-block:: julia + partitions(array) - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - ``collect(partitions(array))`` to get an array of all partitions. - The number of partitions to generate can be efficiently - computed using ``length(partitions(array))``. + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(array))``\ . - :: - partitions(array, m) + .. code-block:: julia + partitions(array, m) - Generate all set partitions of the elements of an array into exactly m - subsets, represented as arrays of arrays. Because the number of - partitions can be very large, this function returns an iterator object. - Use ``collect(partitions(array,m))`` to get an array of all partitions. - The number of partitions into m subsets is equal to the Stirling number - of the second kind and can be efficiently computed using - ``length(partitions(array,m))``. + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``\ . .. function:: partitions(array, m) - :: - partitions(n) + .. Docstring generated from Julia source + .. code-block:: julia + partitions(n) - Generate all integer arrays that sum to ``n``. Because the number of - partitions can be very large, this function returns an iterator - object. Use ``collect(partitions(n))`` to get an array of all - partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n))``. + Generate all integer arrays that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n))``\ . - :: - partitions(n, m) + .. code-block:: julia + partitions(n, m) - Generate all arrays of ``m`` integers that sum to ``n``. Because - the number of partitions can be very large, this function returns an - iterator object. Use ``collect(partitions(n,m))`` to get an array of - all partitions. The number of partitions to generate can be efficiently - computed using ``length(partitions(n,m))``. + Generate all arrays of ``m`` integers that sum to ``n``\ . Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n,m))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n,m))``\ . - :: - partitions(array) + .. code-block:: julia + partitions(array) - Generate all set partitions of the elements of an array, - represented as arrays of arrays. Because the number of partitions - can be very large, this function returns an iterator object. Use - ``collect(partitions(array))`` to get an array of all partitions. - The number of partitions to generate can be efficiently - computed using ``length(partitions(array))``. + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(array))``\ . - :: - partitions(array, m) + .. code-block:: julia + partitions(array, m) - Generate all set partitions of the elements of an array into exactly m - subsets, represented as arrays of arrays. Because the number of - partitions can be very large, this function returns an iterator object. - Use ``collect(partitions(array,m))`` to get an array of all partitions. - The number of partitions into m subsets is equal to the Stirling number - of the second kind and can be efficiently computed using - ``length(partitions(array,m))``. + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(array,m))`` to get an array of all partitions. The number of partitions into m subsets is equal to the Stirling number of the second kind and can be efficiently computed using ``length(partitions(array,m))``\ . BitArrays --------- .. function:: bitpack(A::AbstractArray{T,N}) -> BitArray + .. Docstring generated from Julia source + .. code-block:: julia + bitpack(A::AbstractArray{T,N}) -> BitArray + Converts a numeric array to a packed boolean array .. function:: bitunpack(B::BitArray{N}) -> Array{Bool,N} + .. Docstring generated from Julia source + .. code-block:: julia + bitunpack(B::BitArray{N}) -> Array{Bool,N} + Converts a packed boolean array to an array of booleans .. function:: flipbits!(B::BitArray{N}) -> BitArray{N} + .. Docstring generated from Julia source + :: + + flipbits!(B::BitArray{N}) -> BitArray{N} + Performs a bitwise not operation on B. See :ref:`~ operator <~>`. .. function:: rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on ``src`` and put the result into ``dest``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 ``src`` and put the result into ``dest``\ . + + .. code-block:: julia + 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!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + .. Docstring generated from Julia source + .. code-block:: julia + rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a left rotation operation on ``src`` and put the result into ``dest``. + Performs a left rotation operation on ``src`` and put the result into ``dest``\ . - :: - rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + .. code-block:: julia + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a left rotation operation on B. .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} + .. Docstring generated from Julia source + .. code-block:: julia + rol(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a left rotation operation. .. function:: ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on ``src`` and put the result into ``dest``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 ``src`` and put the result into ``dest``\ . + + .. code-block:: julia + 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!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + .. Docstring generated from Julia source + .. code-block:: julia + ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} - Performs a right rotation operation on ``src`` and put the result into ``dest``. + Performs a right rotation operation on ``src`` and put the result into ``dest``\ . - :: - ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + .. code-block:: julia + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} Performs a right rotation operation on B. .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} + .. Docstring generated from Julia source + .. code-block:: julia + ror(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a right rotation operation. .. _stdlib-sparse: @@ -1187,87 +1498,109 @@ Sparse matrices support much of the same set of operations as dense matrices. Th .. function:: sparse(I,J,V,[m,n,combine]) - Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``. The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. + .. Docstring generated from Julia source + .. code-block:: julia + sparse(I,J,V,[m,n,combine]) - :: - sparse(A) + Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``\ . The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. + + .. code-block:: julia + sparse(A) Convert an AbstractMatrix ``A`` into a sparse matrix. .. function:: sparsevec(I, V, [m, combine]) - Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + .. Docstring generated from Julia source + .. code-block:: julia + sparsevec(I, V, [m, combine]) - :: - sparsevec(D::Dict, [m]) + 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. + + .. code-block:: julia + sparsevec(D::Dict, [m]) Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. - :: - sparsevec(A) + .. code-block:: julia + sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``\ . In julia, sparse vectors are really just sparse matrices with one column. .. function:: sparsevec(D::Dict, [m]) - :: - sparsevec(I, V, [m, combine]) + .. Docstring generated from Julia source + .. code-block:: julia + sparsevec(I, V, [m, combine]) - Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``\ . Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. - :: - sparsevec(D::Dict, [m]) + .. code-block:: julia + sparsevec(D::Dict, [m]) Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. - :: - sparsevec(A) + .. code-block:: julia + sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``\ . In julia, sparse vectors are really just sparse matrices with one column. .. function:: issparse(S) + .. Docstring generated from Julia source + .. code-block:: julia + issparse(S) + Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. .. function:: sparse(A) - :: - sparse(I,J,V,[m,n,combine]) + .. Docstring generated from Julia source + .. code-block:: julia + sparse(I,J,V,[m,n,combine]) - Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``. The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. + Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``\ . The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. - :: - sparse(A) + .. code-block:: julia + sparse(A) Convert an AbstractMatrix ``A`` into a sparse matrix. .. function:: sparsevec(A) - :: - sparsevec(I, V, [m, combine]) + .. Docstring generated from Julia source + .. code-block:: julia + sparsevec(I, V, [m, combine]) - Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``\ . Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. - :: - sparsevec(D::Dict, [m]) + .. code-block:: julia + sparsevec(D::Dict, [m]) Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. - :: - sparsevec(A) + .. code-block:: julia + sparsevec(A) - Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``\ . In julia, sparse vectors are really just sparse matrices with one column. .. function:: full(S) + .. Docstring generated from Julia source + :: + + full(S) + Convert a sparse matrix ``S`` into a dense matrix. :: + full(F) Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. :: + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` @@ -1281,65 +1614,119 @@ Sparse matrices support much of the same set of operations as dense matrices. Th .. function:: nnz(A) + .. Docstring generated from Julia source + .. code-block:: julia + nnz(A) + Returns the number of stored (filled) elements in a sparse matrix. .. function:: spzeros(m,n) - Create a sparse matrix of size ``m x n``. This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. + .. Docstring generated from Julia source + .. code-block:: julia + spzeros(m,n) + + Create a sparse matrix of size ``m x n``\ . This sparse matrix will not contain any nonzero values. No storage will be allocated for nonzero values during construction. .. function:: spones(S) - Create a sparse matrix with the same structure as that of ``S``, but with every nonzero element having the value ``1.0``. + .. Docstring generated from Julia source + .. code-block:: julia + spones(S) + + Create a sparse matrix with the same structure as that of ``S``\ , but with every nonzero element having the value ``1.0``\ . .. function:: speye(type,m[,n]) - Create a sparse identity matrix of specified type of size ``m x m``. In case ``n`` is supplied, create a sparse identity matrix of size ``m x n``. + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. Docstring generated from Julia source + :: + + sprand([rng,] m,n,p [,rfn]) + Create a random ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by ``p`` (and hence the mean density of nonzeros is also exactly ``p``). Nonzero values are sampled from the distribution specified by ``rfn``. The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers `. .. function:: sprandn(m,n,p) + .. Docstring generated from Julia source + .. code-block:: julia + 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:: sprandbool(m,n,p) - Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being ``true``. + .. Docstring generated from Julia source + .. code-block:: julia + sprandbool(m,n,p) + + Create a random ``m`` by ``n`` sparse boolean matrix with the specified (independent) probability ``p`` of any entry being ``true``\ . .. function:: etree(A[, post]) + .. Docstring generated from Julia source + .. code-block:: julia + etree(A[, post]) + Compute the elimination tree of a symmetric sparse matrix ``A`` from ``triu(A)`` and, optionally, its post-ordering permutation. .. function:: symperm(A, p) - Return the symmetric permutation of A, which is ``A[p,p]``. A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. + .. Docstring generated from Julia source + .. code-block:: julia + symperm(A, p) + + Return the symmetric permutation of A, which is ``A[p,p]``\ . A should be symmetric and sparse, where only the upper triangular part of the matrix is stored. This algorithm ignores the lower triangular part of the matrix. Only the upper triangular part of the result is returned as well. .. function:: nonzeros(A) - Return a vector of the structural nonzero values in sparse matrix ``A``. This includes zeros that are explicitly stored in the sparse matrix. The returned vector points directly to the internal nonzero storage of ``A``, and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``. + .. Docstring generated from Julia source + .. code-block:: julia + nonzeros(A) + + Return a vector of the structural nonzero values in sparse matrix ``A``\ . This includes zeros that are explicitly stored in the sparse matrix. The returned vector points directly to the internal nonzero storage of ``A``\ , and any modifications to the returned vector will mutate ``A`` as well. See ``rowvals(A)`` and ``nzrange(A, col)``\ . .. function:: rowvals(A) - Return a vector of the row indices of ``A``, and any modifications to the returned vector will mutate ``A`` as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See ``nonzeros(A)`` and ``nzrange(A, col)``. + .. Docstring generated from Julia source + .. code-block:: julia + rowvals(A) + + Return a vector of the row indices of ``A``\ , and any modifications to the returned vector will mutate ``A`` as well. Given the internal storage format of sparse matrices, providing access to how the row indices are stored internally can be useful in conjuction with iterating over structural nonzero values. See ``nonzeros(A)`` and ``nzrange(A, col)``\ . .. function:: nzrange(A, col) - Return the range of indices to the structural nonzero values of a sparse matrix column. In conjunction with ``nonzeros(A)`` and ``rowvals(A)``, this allows for convenient iterating over a sparse matrix :: - - A = sparse(I,J,V) - rows = rowvals(A) - vals = nonzeros(A) - m, n = size(A) - for i = 1:n - for j in nzrange(A, i) - row = rows[j] - val = vals[j] - # perform sparse wizardry... - end - end + .. Docstring generated from Julia source + .. code-block:: julia + 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 : + + .. code-block:: julia + 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 86dcdf4b697157..ee1d7ae7cfbf28 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -22,210 +22,285 @@ Getting Around .. function:: exit([code]) + .. Docstring generated from Julia source + .. code-block:: julia + exit([code]) + Quit (or control-D at the prompt). The default exit code is zero, indicating that the processes completed successfully. .. function:: quit() + .. Docstring generated from Julia source + :: + + quit() + Quit the program indicating that the processes completed successfully. This function calls ``exit(0)`` (see :func:`exit`). .. function:: atexit(f) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + whos([Module,] [pattern::Regex]) + + Print information about exported global variables in a module, optionally restricted to those matching ``pattern``\ . .. function:: edit(file::AbstractString, [line]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. code-block:: julia + 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(file::AbstractString, [line]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. code-block:: julia + edit(function, [types]) Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. .. function:: @edit + .. Docstring generated from Julia source + .. code-block:: julia + @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]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. code-block:: julia + less(function, [types]) Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. .. function:: less(function, [types]) - :: - less(file::AbstractString, [line]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + @less + Evaluates the arguments to the function call, determines their types, and calls the ``less`` function on the resulting expression .. function:: clipboard(x) + .. Docstring generated from Julia source + .. code-block:: julia + clipboard(x) + Send a printed form of ``x`` to the operating system clipboard ("copy"). - :: - clipboard() -> AbstractString + .. code-block:: julia + clipboard() -> AbstractString Return a string with the contents of the operating system clipboard ("paste"). .. function:: clipboard() -> AbstractString - :: - clipboard(x) + .. Docstring generated from Julia source + .. code-block:: julia + clipboard(x) Send a printed form of ``x`` to the operating system clipboard ("copy"). - :: - clipboard() -> AbstractString + .. code-block:: julia + clipboard() -> AbstractString Return a string with the contents of the operating system clipboard ("paste"). .. function:: require(module::Symbol) - This function is part of the implementation of ``using`` / ``import``, if a module is not already defined in ``Main``. It can also be called directly to force reloading a module, regardless of whether it has been loaded before (for exmple, when interactively developing libraries). + .. Docstring generated from Julia source + .. code-block:: julia + require(module::Symbol) + + This function is part of the implementation of ``using`` / ``import``\ , if a module is not already defined in ``Main``\ . It can also be called directly to force reloading a module, regardless of whether it has been loaded before (for exmple, when interactively developing libraries). - Loads a source files, 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. + Loads a source files, in the context of the ``Main`` module, on every active node, searching standard locations for files. ``require`` is considered a top-level operation, so it sets the current ``include`` path but does not use it to search for files (see help for ``include``\ ). This function is typically used to load library code, and is implicitly called by ``using`` to load packages. - When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``, then tries paths in the global array ``LOAD_PATH``. + When searching for files, ``require`` first looks in the current working directory, then looks for package code under ``Pkg.dir()``\ , then tries paths in the global array ``LOAD_PATH``\ . .. function:: compilecache(module::Symbol) + .. Docstring generated from Julia source + :: + + Base.compilecache(module::Symbol) + Creates a precompiled cache file for module (see help for ``require``) and all of its dependencies. This can be used to reduce package load times. Cache files are stored in ``LOAD_CACHE_PATH[1]``, which defaults to ``~/.julia/lib/VERSION``. See :ref:`Module initialization and precompilation ` for important notes. .. function:: __precompile__(isprecompilable::Bool=true) - Specify whether the file calling this function is precompilable. If - ``isprecompilable`` is ``true``, then ``__precompile__`` throws an exception - *unless* the file is being precompiled, and in a module file it causes - the module to be automatically precompiled when it is imported. - Typically, ``__precompile__()`` should occur before the ``module`` - declaration in the file, or better yet ``VERSION >= v"0.4" && - __precompile__()`` in order to be backward-compatible with Julia 0.3. + .. Docstring generated from Julia source + .. code-block:: julia + __precompile__(isprecompilable::Bool=true) + + Specify whether the file calling this function is precompilable. If ``isprecompilable`` is ``true``\ , then ``__precompile__`` throws an exception when the file is loaded by ``using``\ /``import``\ /``require`` *unless* the file is being precompiled, and in a module file it causes the module to be automatically precompiled when it is imported. Typically, ``__precompile__()`` should occur before the ``module`` declaration in the file, or better yet ``VERSION >= v"0.4" && __precompile__()`` in order to be backward-compatible with Julia 0.3. - If a module or file is *not* safely precompilable, it should call - ``__precompile__(false)`` in order to throw an error if Julia attempts - to precompile it. + If a module or file is *not* safely precompilable, it should call ``__precompile__(false)`` in order to throw an error if Julia attempts to precompile it. .. function:: include(path::AbstractString) + .. Docstring generated from Julia source + .. code-block:: julia + 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, [filename]) - 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. + .. Docstring generated from Julia source + .. code-block:: julia + include_string(code::AbstractString, [filename]) + + 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:: include_dependency(path::AbstractString) - In a module, declare that the file specified by ``path`` (relative or - absolute) is a dependency for precompilation; that is, the - module will need to be recompiled if this file changes. + .. Docstring generated from Julia source + .. code-block:: julia + include_dependency(path::AbstractString) + + In a module, declare that the file specified by ``path`` (relative or absolute) is a dependency for precompilation; that is, the module will need to be recompiled if this file changes. - This is only needed if your module depends on a file that is not - used via ``include``. It has no effect outside of compilation. + This is only needed if your module depends on a file that is not used via ``include``\ . It has no effect outside of compilation. .. function:: which(f, types) + .. Docstring generated from Julia source + .. code-block:: julia + which(f, types) + Returns the method of ``f`` (a ``Method`` object) that would be called for arguments of the given types. - If ``types`` is an abstract type, then the method that would be called by ``invoke`` - is returned. + If ``types`` is an abstract type, then the method that would be called by ``invoke`` is returned. - :: - which(symbol) + .. code-block:: julia + which(symbol) - Return the module in which the binding for the variable referenced - by ``symbol`` was created. + Return the module in which the binding for the variable referenced by ``symbol`` was created. .. function:: which(symbol) - :: - which(f, types) + .. Docstring generated from Julia source + .. code-block:: julia + which(f, types) Returns the method of ``f`` (a ``Method`` object) that would be called for arguments of the given types. - If ``types`` is an abstract type, then the method that would be called by ``invoke`` - is returned. + If ``types`` is an abstract type, then the method that would be called by ``invoke`` is returned. - :: - which(symbol) + .. code-block:: julia + which(symbol) - Return the module in which the binding for the variable referenced - by ``symbol`` was created. + Return the module in which the binding for the variable referenced by ``symbol`` was created. .. function:: @which - Applied to a function call, it evaluates the arguments to the - specified function call, and returns the ``Method`` object for the - method that would be called for those arguments. Applied to a - variable, it returns the module in which the variable was bound. It - calls out to the ``which`` function. + .. Docstring generated from Julia source + .. code-block:: julia + @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``. + .. Docstring generated from Julia source + .. code-block:: julia + methods(f, [types]) + + Returns the method table for ``f``\ . If ``types`` is specified, returns an array of methods whose types match. .. function:: methodswith(typ[, module or function][, showparents]) - Return an array of methods with an argument of type ``typ``. If optional - ``showparents`` is ``true``, also return arguments with a parent type - of ``typ``, excluding type ``Any``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + @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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + workspace() + + Replace the top-level module (``Main``\ ) with a new one, providing a clean workspace. The previous ``Main`` module is made available as ``LastMain``\ . A previously-loaded package can be accessed using a statement such as ``using LastMain.Package``\ . This function should only be used interactively. @@ -239,149 +314,329 @@ All Objects .. function:: is(x, y) -> Bool - :: - ===(x,y) -> Bool - ≡(x,y) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + is(x, y) -> Bool + ===(x,y) -> Bool + ≡(x,y) -> Bool - Determine whether ``x`` and ``y`` are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called ``egal``. + Determine whether ``x`` and ``y`` are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called ``egal``\ . .. function:: isa(x, type) -> Bool - Determine whether ``x`` is of the given ``type``. + .. Docstring generated from Julia source + .. code-block:: julia + isa(x, type) -> Bool + + Determine whether ``x`` is of the given ``type``\ . .. function:: isequal(x, y) - Similar to ``==``, except treats all floating-point ``NaN`` values as equal to each other, - and treats ``-0.0`` as unequal to ``0.0``. - The default implementation of ``isequal`` calls ``==``, so if you have a type that doesn't have these floating-point subtleties then you probably only need to define ``==``. + .. Docstring generated from Julia source + .. code-block:: julia + isequal(x, y) - ``isequal`` is the comparison function used by hash tables (``Dict``). - ``isequal(x,y)`` must imply that ``hash(x) == hash(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 ``==``\ . - 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. + ``isequal`` is the comparison function used by hash tables (``Dict``\ ). ``isequal(x,y)`` must imply that ``hash(x) == hash(y)``\ . - 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 ``==``). + This typically means that if you define your own ``==`` function then you must define a corresponding ``hash`` (and vice versa). Collections typically implement ``isequal`` by calling ``isequal`` recursively on all contents. + + Scalar types generally do not need to implement ``isequal`` separate from ``==``\ , unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on ``isnan``\ , ``signbit``\ , and ``==``\ ). .. function:: isless(x, y) - Test whether ``x`` is less than ``y``, according to a canonical total order. - Values that are normally unordered, such as ``NaN``, are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``. Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as ``NaN``. + .. Docstring generated from Julia source + .. code-block:: julia + isless(x, y) + + Test whether ``x`` is less than ``y``\ , according to a canonical total order. Values that are normally unordered, such as ``NaN``\ , are ordered in an arbitrary but consistent fashion. This is the default comparison used by ``sort``\ . Non-numeric types with a canonical total order should implement this function. Numeric types only need to implement it if they have special values such as ``NaN``\ . .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + ifelse(condition::Bool, x, y) + + Return ``x`` if ``condition`` is true, otherwise return ``y``\ . This differs from ``?`` or ``if`` in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using ``ifelse`` instead of an ``if`` statement can eliminate the branch in generated code and provide higher performance in tight loops. .. function:: lexcmp(x, y) - Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``, respectively. - This function should be defined for lexicographically comparable types, and ``lexless`` will call ``lexcmp`` by default. + .. Docstring generated from Julia source + .. code-block:: julia + lexcmp(x, y) + + Compare ``x`` and ``y`` lexicographically and return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater than ``y``\ , respectively. This function should be defined for lexicographically comparable types, and ``lexless`` will call ``lexcmp`` by default. .. function:: lexless(x, y) - Determine whether ``x`` is lexicographically less than ``y``. + .. Docstring generated from Julia source + .. code-block:: julia + lexless(x, y) + + Determine whether ``x`` is lexicographically less than ``y``\ . .. function:: typeof(x) - Get the concrete type of ``x``. + .. Docstring generated from Julia source + .. code-block:: julia + typeof(x) + + Get the concrete type of ``x``\ . .. function:: tuple(xs...) + .. Docstring generated from Julia source + .. code-block:: julia + tuple(xs...) + Construct a tuple of the given objects. .. function:: ntuple(f::Function, n) - Create a tuple of length ``n``, computing each element as ``f(i)``, where ``i`` is the index of the element. + .. Docstring generated from Julia source + .. code-block:: julia + ntuple(f::Function, n) + + Create a tuple of length ``n``\ , computing each element as ``f(i)``\ , where ``i`` is the index of the element. .. function:: object_id(x) - Get a unique integer id for ``x``. ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``. + .. Docstring generated from Julia source + .. code-block:: julia + object_id(x) + + Get a unique integer id for ``x``\ . ``object_id(x)==object_id(y)`` if and only if ``is(x,y)``\ . .. function:: hash(x[, h]) - Compute an integer hash code such that ``isequal(x,y)`` implies ``hash(x)==hash(y)``. - The optional second argument ``h`` is a hash code to be mixed with the result. + .. Docstring generated from Julia source + .. code-block:: julia + hash(x[, h]) - New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``) to guarantee the property mentioned above. + Compute an integer hash code such that ``isequal(x,y)`` implies ``hash(x)==hash(y)``\ . The optional second argument ``h`` is a hash code to be mixed with the result. + + New types should implement the 2-argument form, typically by calling the 2-argument ``hash`` method recursively in order to mix hashes of the contents with each other (and with ``h``\ ). Typically, any type that implements ``hash`` should also implement its own ``==`` (hence ``isequal``\ ) to guarantee the property mentioned above. .. function:: finalizer(x, function) - Register a function ``f(x)`` to be called when there are no program-accessible references to ``x``. The behavior of this function is unpredictable if ``x`` is of a bits type. + .. Docstring generated from Julia source + .. code-block:: julia + finalizer(x, function) + + Register a function ``f(x)`` to be called when there are no program-accessible references to ``x``\ . The behavior of this function is unpredictable if ``x`` is of a bits type. .. function:: finalize(x) - Immediately run finalizers registered for object ``x``. + .. Docstring generated from Julia source + .. code-block:: julia + finalize(x) + + Immediately run finalizers registered for object ``x``\ . .. function:: copy(x) - Create a shallow copy of ``x``: the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. + .. Docstring generated from Julia source + .. code-block:: julia + copy(x) + + Create a shallow copy of ``x``\ : the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. .. function:: deepcopy(x) - Create a deep copy of ``x``: everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling ``deepcopy`` on an object should generally have the same effect as serializing and then deserializing it. + .. Docstring generated from Julia source + .. code-block:: julia + deepcopy(x) + + Create a deep copy of ``x``\ : everything is copied recursively, resulting in a fully independent object. For example, deep-copying an array produces a new array whose elements are deep copies of the original elements. Calling ``deepcopy`` on an object should generally have the same effect as serializing and then deserializing it. As a special case, functions can only be actually deep-copied if they are anonymous, otherwise they are just copied. The difference is only relevant in the case of closures, i.e. functions which may contain hidden internal references. - While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` (which shouldn't otherwise be used), where ``T`` is the type to be specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``, and the ``dict`` variable should be updated as appropriate before returning. + While it isn't normally necessary, user-defined types can override the default ``deepcopy`` behavior by defining a specialized version of the function ``deepcopy_internal(x::T, dict::ObjectIdDict)`` (which shouldn't otherwise be used), where ``T`` is the type to be specialized for, and ``dict`` keeps track of objects copied so far within the recursion. Within the definition, ``deepcopy_internal`` should be used in place of ``deepcopy``\ , and the ``dict`` variable should be updated as appropriate before returning. .. function:: isdefined([object,] index | symbol) - Tests whether an assignable location is defined. The arguments can be an - array and index, a composite object and field name (as a symbol), or a - module and a symbol. - With a single symbol argument, tests whether a global variable with that - name is defined in ``current_module()``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) - Convert ``x`` to a value of type ``T``. + .. Docstring generated from Julia source + .. code-block:: julia + :: - 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``. + convert(T, x) - .. doctest:: + Convert ``x`` to a value of type ``T``. - julia> convert(Int, 3.0) - 3 + 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``. - julia> convert(Int, 3.5) - ERROR: InexactError() - in convert at int.jl:205 + .. doctest:: - If ``T`` is a :obj:`AbstractFloat` or :obj:`Rational` type, then it will return - the closest value to ``x`` representable by ``T``. + julia> convert(Int, 3.0) + 3 - .. doctest:: + julia> convert(Int, 3.5) + ERROR: InexactError() + in convert at int.jl:205 + + If ``T`` is a :obj:`AbstractFloat` or :obj:`Rational` type, then it will return + the closest value to ``x`` representable by ``T``. + + .. doctest:: + + julia> x = 1/3 + 0.3333333333333333 + + julia> convert(Float32, x) + 0.33333334f0 + + julia> convert(Rational{Int32}, x) + 1//3 + + julia> convert(Rational{Int64}, x) + 6004799503160661//18014398509481984 + + Converts a ``UTF32String`` to ``UTF16String`` + + Returns: + -------- + + + * ``::UTF16String`` + + Throws: + ------- + + + * ``UnicodeError`` + + Converts a ``UTF16String`` to ``UTF32String`` + + Returns: + -------- + + + * ``::UTF32String`` + + Throws: + ------- + + + * ``UnicodeError`` + + Converts a ``UTF8String`` to a ``UTF32String`` + + Returns: + -------- + + + * ``::UTF32String`` + + Throws: + ------- - julia> x = 1/3 - 0.3333333333333333 - julia> convert(Float32, x) - 0.33333334f0 + * ``UnicodeError`` - julia> convert(Rational{Int32}, x) - 1//3 + Converts a ``UTF32String`` to a ``UTF8String`` - julia> convert(Rational{Int64}, x) - 6004799503160661//18014398509481984 + Returns: + -------- + + + * ``UTF8String`` + + Throws: + ------- + + + * ``UnicodeError`` + + Converts an ``AbstractString`` to a ``UTF32String`` + + Returns: + -------- + + + * ``UTF32String`` + + Throws: + ------- + + + * ``UnicodeError`` + + Converts a ``UTF16String`` to a ``UTF8String`` + + Returns: + -------- + + + * ``UTF8String`` + + Throws: + ------- + + + * ``UnicodeError`` + + Converts an ``AbstractString`` to a ``UTF16String`` + + Returns: + -------- + + + * ``UTF16String`` + + Throws: + ------- + + + * ``UnicodeError`` + + Converts a UTF-8 encoded vector of ``UInt8`` to a ``UTF8String`` + + Returns: + -------- + + + * ``UTF8String`` + + Throws: + ------- + + + * ``UnicodeError`` .. function:: promote(xs...) + .. Docstring generated from Julia source + .. code-block:: julia + promote(xs...) + Convert all arguments to their common promotion type (if any), and return them all (as a tuple). .. function:: oftype(x, y) - Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``). + .. Docstring generated from Julia source + .. code-block:: julia + oftype(x, y) + + Convert ``y`` to the type of ``x`` (``convert(typeof(x), y)``\ ). .. function:: widen(type | x) + .. Docstring generated from Julia source + :: + + 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))``. @@ -398,6 +653,10 @@ All Objects .. function:: identity(x) + .. Docstring generated from Julia source + .. code-block:: julia + identity(x) + The identity function. Returns its argument. Types @@ -405,91 +664,146 @@ Types .. function:: super(T::DataType) + .. Docstring generated from Julia source + .. code-block:: julia + super(T::DataType) + Return the supertype of DataType T .. function:: issubtype(type1, type2) - True if and only if all values of ``type1`` are also of ``type2``. Can also be written using the ``<:`` infix operator as ``type1 <: type2``. + .. Docstring generated from Julia source + .. code-block:: julia + issubtype(type1, type2) + + True if and only if all values of ``type1`` are also of ``type2``\ . Can also be written using the ``<:`` infix operator as ``type1 <: type2``\ . .. function:: <:(T1, T2) - :: - issubtype(type1, type2) + .. Docstring generated from Julia source + .. code-block:: julia + issubtype(type1, type2) - True if and only if all values of ``type1`` are also of ``type2``. Can also be written using the ``<:`` infix operator as ``type1 <: type2``. + True if and only if all values of ``type1`` are also of ``type2``\ . Can also be written using the ``<:`` infix operator as ``type1 <: type2``\ . .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + typemin(type) + The lowest value representable by the given (real) numeric type. .. function:: typemax(type) + .. Docstring generated from Julia source + .. code-block:: julia + typemax(type) + The highest value representable by the given (real) numeric type. .. function:: realmin(type) + .. Docstring generated from Julia source + .. code-block:: julia + realmin(type) + The smallest in absolute value non-subnormal value representable by the given floating-point type .. function:: realmax(type) + .. Docstring generated from Julia source + .. code-block:: julia + realmax(type) + The highest finite value representable by the given floating-point type .. function:: maxintfloat(type) + .. Docstring generated from Julia source + .. code-block:: julia + maxintfloat(type) + The largest integer losslessly representable by the given floating-point type .. function:: sizeof(type) + .. Docstring generated from Julia source + .. code-block:: julia + sizeof(type) + Size, in bytes, of the canonical binary representation of the given type, if any. - :: - sizeof(s::AbstractString) + .. code-block:: julia + sizeof(s::AbstractString) - The number of bytes in string ``s``. + The number of bytes in string ``s``\ . .. function:: eps([type]) - :: - eps(::DateTime) -> Millisecond - eps(::Date) -> Day + .. Docstring generated from Julia source + .. code-block:: julia + eps(::DateTime) -> Millisecond + eps(::Date) -> Day Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. .. function:: eps(x) - :: - eps(::DateTime) -> Millisecond - eps(::Date) -> Day + .. Docstring generated from Julia source + .. code-block:: julia + eps(::DateTime) -> Millisecond + eps(::Date) -> Day Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. .. function:: promote_type(type1, type2) + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: promote_rule(type1, type2) - Specifies what type should be used by ``promote`` when given values of types - ``type1`` and ``type2``. This function should not be called directly, but - should have definitions added to it for new types as appropriate. + .. Docstring generated from Julia source + .. code-block:: julia + promote_rule(type1, type2) + + Specifies what type should be used by ``promote`` when given values of types ``type1`` and ``type2``\ . This function should not be called directly, but should have definitions added to it for new types as appropriate. .. function:: getfield(value, name::Symbol) - Extract a named field from a value of composite type. The syntax ``a.b`` calls - ``getfield(a, :b)``, and the syntax ``a.(b)`` calls ``getfield(a, b)``. + .. Docstring generated from Julia source + .. code-block:: julia + 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)``\ . .. function:: setfield!(value, name::Symbol, x) - Assign ``x`` to a named field in ``value`` of composite type. - The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``, and the syntax ``a.(b) = c`` - calls ``setfield!(a, b, c)``. + .. Docstring generated from Julia source + .. code-block:: julia + setfield!(value, name::Symbol, x) + + Assign ``x`` to a named field in ``value`` of composite type. The syntax ``a.b = c`` calls ``setfield!(a, :b, c)``\ , and the syntax ``a.(b) = c`` calls ``setfield!(a, b, c)``\ . .. function:: fieldoffsets(type) + .. Docstring generated from Julia source + :: + + 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: @@ -514,15 +828,29 @@ Types .. function:: fieldtype(type, name::Symbol | index::Int) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + isimmutable(v) + True if value ``v`` is immutable. See :ref:`man-immutable-composite-types` for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of ``DataType`` is mutable. .. function:: isbits(T) + .. Docstring generated from Julia source + :: + + isbits(T) + True if ``T`` is a "plain data" type, meaning it is immutable and contains no references to other values. Typical examples are numeric types such as ``UInt8``, ``Float64``, and ``Complex{Float64}``. .. doctest:: @@ -535,28 +863,43 @@ Types .. function:: isleaftype(T) - Determine whether ``T`` is a concrete type that can have instances, meaning - its only subtypes are itself and ``None`` (but ``T`` itself is not - ``None``). + .. Docstring generated from Julia source + .. code-block:: julia + isleaftype(T) + + Determine whether ``T`` is a concrete type that can have instances, meaning its only subtypes are itself and ``None`` (but ``T`` itself is not ``None``\ ). .. function:: typejoin(T, S) - Compute a type that contains both ``T`` and ``S``. + .. Docstring generated from Julia source + .. code-block:: julia + typejoin(T, S) + + Compute a type that contains both ``T`` and ``S``\ . .. function:: typeintersect(T, S) - Compute a type that contains the intersection of ``T`` and ``S``. Usually this will be the smallest such type or one close to it. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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] + .. Docstring generated from Julia source + :: + + @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:: @@ -571,14 +914,22 @@ Types .. function:: instances(T::Type) - Return a collection of all instances of the given type, if applicable. - Mostly used for enumerated types (see ``@enum``). + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + :: + + method_exists(f, Tuple type) -> Bool + Determine whether the given generic function has a method matching the given :obj:`Tuple` of argument types. .. doctest:: @@ -588,6 +939,11 @@ Generic Functions .. function:: applicable(f, args...) -> Bool + .. Docstring generated from Julia source + :: + + applicable(f, args...) -> Bool + Determine whether the given generic function has a method applicable to the given arguments. .. doctest:: @@ -604,10 +960,19 @@ Generic Functions .. function:: invoke(f, (types...), args...) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + |>(x, f) + Applies a function to the preceding argument. This allows for easy function chaining. .. doctest:: @@ -617,99 +982,137 @@ Generic Functions .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + call(x, args...) + + If ``x`` is not a ``Function``\ , then ``x(args...)`` is equivalent to ``call(x, args...)``\ . This means that function-like behavior can be added to any type by defining new ``call`` methods. Syntax ------ .. function:: eval([m::Module], expr::Expr) - Evaluate an expression in the given module and return the result. - Every module (except those defined with ``baremodule``) has its own 1-argument definition - of ``eval``, which evaluates expressions in that module. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + @eval + Evaluate an expression and return the value. .. function:: evalfile(path::AbstractString) - Load the file using ``include``, evaluate all expressions, and return the value of the last one. + .. Docstring generated from Julia source + .. code-block:: julia + evalfile(path::AbstractString) + + Load the file using ``include``\ , evaluate all expressions, and return the value of the last one. .. function:: esc(e::ANY) + .. Docstring generated from Julia source + :: + + 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:: gensym([tag]) + .. Docstring generated from Julia source + .. code-block:: julia + gensym([tag]) + Generates a symbol which will not conflict with other variable names. .. function:: @gensym - Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym("x"); y = gensym("y")``. + .. Docstring generated from Julia source + .. code-block:: julia + @gensym + + Generates a gensym symbol for a variable. For example, ``@gensym x y`` is transformed into ``x = gensym("x"); y = gensym("y")``\ . .. function:: parse(str, start; greedy=true, raise=true) - Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + .. Docstring generated from Julia source + .. code-block:: julia + parse(str, start; greedy=true, raise=true) - :: - parse(str; raise=true) + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``\ . If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. - Parse the 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. + .. code-block:: julia + parse(str; raise=true) - :: - parse(type, str, [base]) + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. + + .. code-block:: julia + parse(type, str, [base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. - If the string does not contain a valid number, an error is raised. + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. .. function:: parse(str; raise=true) - :: - parse(str, start; greedy=true, raise=true) + .. Docstring generated from Julia source + .. code-block:: julia + parse(str, start; greedy=true, raise=true) - Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``\ . If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. - :: - parse(str; raise=true) + .. code-block:: julia + parse(str; raise=true) - Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. - :: - parse(type, str, [base]) + .. code-block:: julia + parse(type, str, [base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. - If the string does not contain a valid number, an error is raised. + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. Nullables --------- .. function:: Nullable(x) - Wrap value ``x`` in an object of type ``Nullable``, which indicates whether a value is present. - ``Nullable(x)`` yields a non-empty wrapper, and ``Nullable{T}()`` yields an empty instance - of a wrapper that might contain a value of type ``T``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + get(x) + Attempt to access the value of the ``Nullable`` object, ``x``. Returns the value if it is present; otherwise, throws a ``NullException``. :: + get(x, y) Attempt to access the value of the ``Nullable{T}`` object, ``x``. Returns the value if it is present; otherwise, returns ``convert(T, y)``. :: + get(collection, key, default) Return the value stored for the given key, or the given default value if no mapping for the key is present. :: + get(f::Function, collection, key) Return the value stored for the given key, or if no mapping for the key is present, return ``f()``. Use :func:`get!` to also store the default value in the dictionary. @@ -721,24 +1124,29 @@ Nullables .. function:: get(x, y) + .. Docstring generated from Julia source :: + get(x) Attempt to access the value of the ``Nullable`` object, ``x``. Returns the value if it is present; otherwise, throws a ``NullException``. :: + get(x, y) Attempt to access the value of the ``Nullable{T}`` object, ``x``. Returns the value if it is present; otherwise, returns ``convert(T, y)``. :: + get(collection, key, default) Return the value stored for the given key, or the given default value if no mapping for the key is present. :: + get(f::Function, collection, key) Return the value stored for the given key, or if no mapping for the key is present, return ``f()``. Use :func:`get!` to also store the default value in the dictionary. @@ -750,6 +1158,10 @@ Nullables .. function:: isnull(x) + .. Docstring generated from Julia source + .. code-block:: julia + isnull(x) + Is the ``Nullable`` object ``x`` null, i.e. missing a value? System @@ -757,10 +1169,18 @@ System .. function:: run(command) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + spawn(command) + Run a command object asynchronously, returning the resulting ``Process`` object. .. data:: DevNull @@ -770,28 +1190,48 @@ System .. function:: success(command) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + process_running(p::Process) + Determine whether a process is currently running. .. function:: process_exited(p::Process) + .. Docstring generated from Julia source + .. code-block:: julia + process_exited(p::Process) + Determine whether a process has exited. .. function:: kill(p::Process, signum=SIGTERM) + .. Docstring generated from Julia source + .. code-block:: julia + kill(p::Process, signum=SIGTERM) + Send a signal to a process. The default is to terminate the process. - :: - kill(manager::FooManager, pid::Int, config::WorkerConfig) + .. code-block:: julia + kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified - by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` + Implemented by cluster managers. It is called on the master process, by ``rmprocs``\ . It should cause the remote worker specified by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` .. function:: open(command, mode::AbstractString="r", stdio=DevNull) + .. Docstring generated from Julia source + :: + + 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 @@ -801,6 +1241,7 @@ System stream. :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` @@ -809,11 +1250,13 @@ System by ``f``. :: + open(file_name, [read, write, create, truncate, append]) -> IOStream Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. :: + open(file_name, [mode]) -> IOStream Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: @@ -828,6 +1271,7 @@ System ==== ================================= :: + open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. @@ -836,7 +1280,9 @@ System .. function:: open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + .. Docstring generated from Julia source :: + open(command, mode::AbstractString="r", stdio=DevNull) Start running ``command`` asynchronously, and return a tuple @@ -848,6 +1294,7 @@ System stream. :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` @@ -856,11 +1303,13 @@ System by ``f``. :: + open(file_name, [read, write, create, truncate, append]) -> IOStream Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. :: + open(file_name, [mode]) -> IOStream Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: @@ -875,6 +1324,7 @@ System ==== ================================= :: + open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. @@ -883,45 +1333,69 @@ System .. function:: Sys.set_process_title(title::AbstractString) + .. Docstring generated from Julia source + .. code-block:: julia + Sys.set_process_title(title::AbstractString) + Set the process title. No-op on some operating systems. (not exported) .. function:: Sys.get_process_title() + .. Docstring generated from Julia source + .. code-block:: julia + Sys.get_process_title() + Get the process title. On some systems, will always return empty string. (not exported) .. function:: readandwrite(command) + .. Docstring generated from Julia source + .. code-block:: julia + readandwrite(command) + Starts running a command asynchronously, and returns a tuple (stdout,stdin,process) of the output stream and input stream of the process, and the process object itself. .. function:: ignorestatus(command) - Mark a command object so that running it will not throw an error if the - result code is non-zero. + .. Docstring generated from Julia source + .. code-block:: julia + ignorestatus(command) + + Mark a command object so that running it will not throw an error if the result code is non-zero. .. function:: detach(command) - Mark a command object so that it will be run in a new process group, - allowing it to outlive the julia process, and not have Ctrl-C interrupts - passed to it. + .. Docstring generated from Julia source + .. code-block:: julia + detach(command) + + Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it. .. function:: setenv(command, env; dir=working_dir) - Set environment variables to use when running the given - command. ``env`` is either a dictionary mapping strings to strings, - an array of strings of the form ``"var=val"``, or zero or more - ``"var"=>val`` pair arguments. In order to modify (rather than - replace) the existing environment, create ``env`` by ``copy(ENV)`` - and then setting ``env["var"]=val`` as desired, or use ``withenv``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + The ``dir`` keyword argument can be used to specify a working directory for the command. .. function:: withenv(f::Function, kv::Pair...) - Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``) by zero or more ``"var"=>val`` arguments ``kv``. ``withenv`` is generally used via the ``withenv(kv...) do ... end`` syntax. A value of ``nothing`` can be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. + .. Docstring generated from Julia source + .. code-block:: julia + withenv(f::Function, kv::Pair...) + + Execute ``f()`` in an environment that is temporarily modified (not replaced as in ``setenv``\ ) by zero or more ``"var"=>val`` arguments ``kv``\ . ``withenv`` is generally used via the ``withenv(kv...) do ... end`` syntax. A value of ``nothing`` can be used to temporarily unset an environment variable (if it is set). When ``withenv`` returns, the original environment has been restored. .. function:: pipe(from, to, ...) + .. Docstring generated from Julia source + :: + + pipe(from, to, ...) + Create a pipeline from a data source to a destination. The source and destination can be commands, I/O streams, strings, or results of other ``pipe`` calls. At least one argument must be a command. Strings refer to filenames. @@ -935,6 +1409,7 @@ System * ``run(pipe("out.txt", `grep xyz`))`` :: + pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given ``command``. Keyword arguments specify which of @@ -951,7 +1426,9 @@ System .. function:: pipe(command; stdin, stdout, stderr, append=false) + .. Docstring generated from Julia source :: + pipe(from, to, ...) Create a pipeline from a data source to a destination. The source and destination can @@ -967,6 +1444,7 @@ System * ``run(pipe("out.txt", `grep xyz`))`` :: + pipe(command; stdin, stdout, stderr, append=false) Redirect I/O to or from the given ``command``. Keyword arguments specify which of @@ -983,61 +1461,117 @@ System .. function:: gethostname() -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + gethostname() -> AbstractString + Get the local machine's host name. .. function:: getipaddr() -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + getipaddr() -> AbstractString + Get the IP address of the local machine, as a string of the form "x.x.x.x". .. function:: getpid() -> Int32 + .. Docstring generated from Julia source + .. code-block:: julia + getpid() -> Int32 + Get julia's process ID. .. function:: time() + .. Docstring generated from Julia source + .. code-block:: julia + time() + Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. .. function:: time_ns() + .. Docstring generated from Julia source + .. code-block:: julia + time_ns() + Get the time in nanoseconds. The time corresponding to 0 is undefined, and wraps every 5.8 years. .. function:: tic() + .. Docstring generated from Julia source + :: + + tic() + Set a timer to be read by the next call to :func:`toc` or :func:`toq`. The macro call ``@time expr`` can also be used to time evaluation. .. function:: toc() + .. Docstring generated from Julia source + :: + + toc() + Print and return the time elapsed since the last :func:`tic`. .. function:: toq() + .. Docstring generated from Julia source + :: + + toq() + Return, but do not print, the time elapsed since the last :func:`tic`. .. function:: @time + .. Docstring generated from Julia source + .. code-block:: julia + @time + A macro to execute an expression, printing the time it took to execute, the number of allocations, and the total number of bytes its execution caused to be allocated, before returning the value of the expression. .. function:: @timev - This is a verbose version of the ``@time`` macro, it first prints the same information as ``@time``, then any non-zero memory allocation counters, and then returns the value of the expression. + .. Docstring generated from Julia source + .. code-block:: julia + @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 + .. Docstring generated from Julia source + .. code-block:: julia + @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 + .. Docstring generated from Julia source + .. code-block:: julia + @elapsed + A macro to evaluate an expression, discarding the resulting value, instead returning the number of seconds it took to execute as a floating-point number. .. function:: @allocated - A macro to evaluate an expression, discarding the resulting value, instead returning the total number of bytes allocated during evaluation of the expression. - Note: the expression is evaluated inside a local function, instead of the current context, in order to eliminate the effects of compilation, - however, there still may be some allocations due to JIT compilation. This also makes the results inconsistent with the ``@time`` macros, - which do not try to adjust for the effects of compilation. + .. Docstring generated from Julia source + .. code-block:: julia + @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 + .. Docstring generated from Julia source + .. code-block:: julia + EnvHash() -> EnvHash + A singleton of this type provides a hash table interface to environment variables. .. data:: ENV @@ -1046,152 +1580,285 @@ System .. function:: @unix - Given ``@unix? a : b``, do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation - for Handling Platform Variations in the Calling C and Fortran Code section of the manual. + .. Docstring generated from Julia source + .. code-block:: julia + @unix + + Given ``@unix? a : b``\ , do ``a`` on Unix systems (including Linux and OS X) and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. .. function:: @osx - Given ``@osx? a : b``, do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations - in the Calling C and Fortran Code section of the manual. + .. Docstring generated from Julia source + .. code-block:: julia + @osx + + Given ``@osx? a : b``\ , do ``a`` on OS X and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. .. function:: @linux - Given ``@linux? a : b``, do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations - in the Calling C and Fortran Code section of the manual. + .. Docstring generated from Julia source + .. code-block:: julia + @linux + + Given ``@linux? a : b``\ , do ``a`` on Linux and ``b`` elsewhere. See documentation for Handling Platform Variations in the Calling C and Fortran Code section of the manual. .. function:: @windows - Given ``@windows? a : b``, do ``a`` on Windows and ``b`` elsewhere. See documentation for Handling Platform Variations - in the Calling C and Fortran Code section of the manual. + .. Docstring generated from Julia source + .. code-block:: julia + @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) + .. Docstring generated from Julia source + .. code-block:: julia + error(message::AbstractString) + Raise an ``ErrorException`` with the given message .. function:: throw(e) + .. Docstring generated from Julia source + .. code-block:: julia + throw(e) + Throw an object as an exception .. function:: rethrow([e]) - Throw an object without changing the current exception backtrace. - The default argument is the current exception (if called within a - ``catch`` block). + .. Docstring generated from Julia source + .. code-block:: julia + 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() + .. Docstring generated from Julia source + .. code-block:: julia + backtrace() + Get a backtrace object for the current program point. .. function:: catch_backtrace() - Get the backtrace of the current exception, for use within ``catch`` - blocks. + .. Docstring generated from Julia source + .. code-block:: julia + catch_backtrace() + + Get the backtrace of the current exception, for use within ``catch`` blocks. .. function:: assert(cond) - Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``. + .. Docstring generated from Julia source + .. code-block:: julia + assert(cond) + + Throw an ``AssertionError`` if ``cond`` is false. Also available as the macro ``@assert expr``\ . .. function:: @assert cond [text] + .. Docstring generated from Julia source + .. code-block:: julia + @assert cond [text] + Throw an ``AssertionError`` if ``cond`` is false. Preferred syntax for writing assertions. .. function:: ArgumentError(msg) + .. Docstring generated from Julia source + .. code-block:: julia + ArgumentError(msg) + The parameters to a function call do not match a valid signature. .. function:: AssertionError([msg]) - The asserted condition did not evalutate to ``true``. + .. Docstring generated from Julia source + .. code-block:: julia + AssertionError([msg]) + + The asserted condition did not evalutate to ``true``\ . .. function:: BoundsError([a],[i]) - An indexing operation into an array, ``a``, tried to access an out-of-bounds element, ``i``. + .. Docstring generated from Julia source + .. code-block:: julia + BoundsError([a],[i]) + + An indexing operation into an array, ``a``\ , tried to access an out-of-bounds element, ``i``\ . .. function:: DimensionMismatch([msg]) + .. Docstring generated from Julia source + .. code-block:: julia + DimensionMismatch([msg]) + The objects called do not have matching dimensionality. .. function:: DivideError() + .. Docstring generated from Julia source + .. code-block:: julia + DivideError() + Integer division was attempted with a denominator value of 0. .. function:: DomainError() + .. Docstring generated from Julia source + .. code-block:: julia + DomainError() + The arguments to a function or constructor are outside the valid domain. .. function:: EOFError() + .. Docstring generated from Julia source + .. code-block:: julia + EOFError() + No more data was available to read from a file or stream. .. function:: ErrorException(msg) + .. Docstring generated from Julia source + .. code-block:: julia + ErrorException(msg) + Generic error type. The error message, in the ``.msg`` field, may provide more specific details. .. function:: InexactError() + .. Docstring generated from Julia source + .. code-block:: julia + InexactError() + Type conversion cannot be done exactly. .. function:: InterruptException() + .. Docstring generated from Julia source + .. code-block:: julia + InterruptException() + The process was stopped by a terminal interrupt (CTRL+C). .. function:: KeyError(key) - An indexing operation into an ``Associative`` (``Dict``) or ``Set`` like object tried to access or delete a non-existent element. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + LoadError(file::AbstractString, line::Int, error) + An error occurred while ``include``\ ing, ``require``\ ing, or ``using`` a file. The error specifics should be available in the ``.error`` field. .. function:: MethodError(f, args) + .. Docstring generated from Julia source + .. code-block:: julia + MethodError(f, args) + A method with the required type signature does not exist in the given generic function. .. function:: NullException() + .. Docstring generated from Julia source + .. code-block:: julia + NullException() + An attempted access to a ``Nullable`` with no defined value. .. function:: OutOfMemoryError() + .. Docstring generated from Julia source + .. code-block:: julia + OutOfMemoryError() + An operation allocated too much memory for either the system or the garbage collector to handle properly. .. function:: ReadOnlyMemoryError() + .. Docstring generated from Julia source + .. code-block:: julia + ReadOnlyMemoryError() + An operation tried to write to memory that is read-only. .. function:: OverflowError() + .. Docstring generated from Julia source + .. code-block:: julia + OverflowError() + The result of an expression is too large for the specified type and will cause a wraparound. .. function:: ParseError(msg) + .. Docstring generated from Julia source + .. code-block:: julia + ParseError(msg) + The expression passed to the ``parse`` function could not be interpreted as a valid Julia expression. .. function:: ProcessExitedException() + .. Docstring generated from Julia source + .. code-block:: julia + ProcessExitedException() + After a client Julia process has exited, further attempts to reference the dead child will throw this exception. .. function:: StackOverflowError() + .. Docstring generated from Julia source + .. code-block:: julia + StackOverflowError() + The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely. .. function:: SystemError(prefix::AbstractString, [errnum::Int32]) + .. Docstring generated from Julia source + .. code-block:: julia + SystemError(prefix::AbstractString, [errnum::Int32]) + A system call failed with an error code (in the ``errno`` global variable). .. function:: TypeError(func::Symbol, context::AbstractString, expected::Type, got) + .. Docstring generated from Julia source + .. code-block:: julia + TypeError(func::Symbol, context::AbstractString, expected::Type, got) + A type assertion failure, or calling an intrinsic function with an incorrect argument type. .. function:: UndefRefError() + .. Docstring generated from Julia source + .. code-block:: julia + UndefRefError() + The item or field is not defined for the given object. .. function:: UndefVarError(var::Symbol) + .. Docstring generated from Julia source + .. code-block:: julia + UndefVarError(var::Symbol) + A symbol in the current scope is not defined. Events @@ -1199,113 +1866,144 @@ Events .. function:: Timer(callback::Function, delay, repeat=0) - Create a timer to call the given callback function. - The callback is passed one argument, the timer object itself. - The callback will be invoked after the specified initial delay, - and then repeating with the given ``repeat`` interval. - If ``repeat`` is ``0``, the timer is only triggered once. - Times are in seconds. - A timer is stopped and has its resources freed by calling ``close`` on it. + .. Docstring generated from Julia source + .. code-block:: julia + Timer(callback::Function, delay, repeat=0) - :: - Timer(delay, repeat=0) + Create a timer to call the given callback function. The callback is passed one argument, the timer object itself. The callback will be invoked after the specified initial delay, and then repeating with the given ``repeat`` interval. If ``repeat`` is ``0``\ , the timer is only triggered once. Times are in seconds. A timer is stopped and has its resources freed by calling ``close`` on it. + + .. code-block:: julia + Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling ``wait`` on - the timer object) at a specified interval. - Waiting tasks are woken with an error when the timer is closed (by ``close``). - Use ``isopen`` to check whether a timer is still active. + Create a timer that wakes up tasks waiting for it (by calling ``wait`` on the timer object) at a specified interval. Waiting tasks are woken with an error when the timer is closed (by ``close``\ ). Use ``isopen`` to check whether a timer is still active. .. function:: Timer(delay, repeat=0) - :: - Timer(callback::Function, delay, repeat=0) + .. Docstring generated from Julia source + .. code-block:: julia + Timer(callback::Function, delay, repeat=0) - Create a timer to call the given callback function. - The callback is passed one argument, the timer object itself. - The callback will be invoked after the specified initial delay, - and then repeating with the given ``repeat`` interval. - If ``repeat`` is ``0``, the timer is only triggered once. - Times are in seconds. - A timer is stopped and has its resources freed by calling ``close`` on it. + Create a timer to call the given callback function. The callback is passed one argument, the timer object itself. The callback will be invoked after the specified initial delay, and then repeating with the given ``repeat`` interval. If ``repeat`` is ``0``\ , the timer is only triggered once. Times are in seconds. A timer is stopped and has its resources freed by calling ``close`` on it. - :: - Timer(delay, repeat=0) + .. code-block:: julia + Timer(delay, repeat=0) - Create a timer that wakes up tasks waiting for it (by calling ``wait`` on - the timer object) at a specified interval. - Waiting tasks are woken with an error when the timer is closed (by ``close``). - Use ``isopen`` to check whether a timer is still active. + Create a timer that wakes up tasks waiting for it (by calling ``wait`` on the timer object) at a specified interval. Waiting tasks are woken with an error when the timer is closed (by ``close``\ ). Use ``isopen`` to check whether a timer is still active. Reflection ---------- .. function:: module_name(m::Module) -> Symbol + .. Docstring generated from Julia source + .. code-block:: julia + module_name(m::Module) -> Symbol + Get the name of a module as a symbol. .. function:: module_parent(m::Module) -> Module + .. Docstring generated from Julia source + .. code-block:: julia + module_parent(m::Module) -> Module + Get a module's enclosing module. ``Main`` is its own parent. .. function:: current_module() -> Module - Get the *dynamically* current module, which is the module code is currently being - read from. In general, this is not the same as the module containing the call to - this function. + .. Docstring generated from Julia source + .. code-block:: julia + current_module() -> Module + + Get the *dynamically* current module, which is the module code is currently being read from. In general, this is not the same as the module containing the call to this function. .. function:: fullname(m::Module) - Get the fully-qualified name of a module as a tuple of symbols. For example, - ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``, and ``fullname(Main)`` gives ``()``. + .. Docstring generated from Julia source + .. code-block:: julia + fullname(m::Module) + + Get the fully-qualified name of a module as a tuple of symbols. For example, ``fullname(Base.Pkg)`` gives ``(:Base,:Pkg)``\ , and ``fullname(Main)`` gives ``()``\ . .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + names(x::Module[, all=false[, imported=false]]) + + Get an array of the names exported by a module, with optionally more module globals according to the additional parameters. .. function:: nfields(x::DataType) -> Int + .. Docstring generated from Julia source + .. code-block:: julia + nfields(x::DataType) -> Int + Get the number of fields of a data type. .. function:: fieldnames(x::DataType) + .. Docstring generated from Julia source + .. code-block:: julia + fieldnames(x::DataType) + Get an array of the fields of a data type. .. function:: isconst([m::Module], s::Symbol) -> Bool - Determine whether a global is declared ``const`` in a given module. - The default module argument is ``current_module()``. + .. Docstring generated from Julia source + .. code-block:: julia + isconst([m::Module], s::Symbol) -> Bool + + Determine whether a global is declared ``const`` in a given module. The default module argument is ``current_module()``\ . .. function:: isgeneric(f::Function) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isgeneric(f::Function) -> Bool + Determine whether a function is generic. .. function:: function_name(f::Function) -> Symbol - Get the name of a generic function as a symbol, or ``:anonymous``. + .. Docstring generated from Julia source + .. code-block:: julia + function_name(f::Function) -> Symbol + + Get the name of a generic function as a symbol, or ``:anonymous``\ . .. function:: function_module(f::Function, types) -> Module + .. Docstring generated from Julia source + .. code-block:: julia + function_module(f::Function, types) -> Module + Determine the module containing a given definition of a generic function. .. function:: functionloc(f::Function, types) + .. Docstring generated from Julia source + .. code-block:: julia + functionloc(f::Function, types) + Returns a tuple ``(filename,line)`` giving the location of a method definition. - :: - functionloc(m::Method) + .. code-block:: julia + functionloc(m::Method) Returns a tuple ``(filename,line)`` giving the location of a method definition. .. function:: functionloc(m::Method) - :: - functionloc(f::Function, types) + .. Docstring generated from Julia source + .. code-block:: julia + functionloc(f::Function, types) Returns a tuple ``(filename,line)`` giving the location of a method definition. - :: - functionloc(m::Method) + .. code-block:: julia + functionloc(m::Method) Returns a tuple ``(filename,line)`` giving the location of a method definition. @@ -1314,67 +2012,130 @@ Internals .. function:: gc() + .. Docstring generated from Julia source + .. code-block:: julia + gc() + Perform garbage collection. This should not generally be used. .. function:: gc_enable(on::Bool) - Control whether garbage collection is enabled using a boolean argument (true for - enabled, false for disabled). - Returns previous GC state. - Disabling garbage collection should be used only with extreme caution, - as it can cause memory use to grow without bound. + .. Docstring generated from Julia source + .. code-block:: julia + gc_enable(on::Bool) + + Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Returns previous GC state. Disabling garbage collection should be used only with extreme caution, as it can cause memory use to grow without bound. .. function:: macroexpand(x) + .. Docstring generated from Julia source + .. code-block:: julia + macroexpand(x) + Takes the expression x and returns an equivalent expression with all macros removed (expanded). .. function:: expand(x) + .. Docstring generated from Julia source + .. code-block:: julia + expand(x) + Takes the expression x and returns an equivalent expression in lowered form .. function:: code_lowered(f, types) + .. Docstring generated from Julia source + .. code-block:: julia + code_lowered(f, types) + Returns an array of lowered ASTs for the methods matching the given generic function and type signature. .. function:: @code_lowered + .. Docstring generated from Julia source + :: + + @code_lowered + 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) + .. Docstring generated from Julia source + .. code-block:: julia + code_typed(f, types; optimize=true) + Returns an array of lowered and type-inferred ASTs for the methods matching the given generic function and type signature. The keyword argument ``optimize`` controls whether additional optimizations, such as inlining, are also applied. .. function:: @code_typed + .. Docstring generated from Julia source + :: + + @code_typed + Evaluates the arguments to the function call, determines their types, and calls :func:`code_typed` on the resulting expression .. function:: code_warntype(f, types) + .. Docstring generated from Julia source + :: + + 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 + .. Docstring generated from Julia source + :: + + @code_warntype + Evaluates the arguments to the function call, determines their types, and calls :func:`code_warntype` on the resulting expression .. function:: code_llvm(f, types) + .. Docstring generated from Julia source + :: + + code_llvm(f, types) + Prints the LLVM bitcodes generated for running the method matching the given generic function and type signature to :const:`STDOUT`. All metadata and dbg.* calls are removed from the printed bitcode. Use code_llvm_raw for the full IR. .. function:: @code_llvm + .. Docstring generated from Julia source + :: + + @code_llvm + Evaluates the arguments to the function call, determines their types, and calls :func:`code_llvm` on the resulting expression .. function:: code_native(f, types) + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + :: + + @code_native + Evaluates the arguments to the function call, determines their types, and calls :func:`code_native` on the resulting expression .. function:: precompile(f,args::Tuple{Vararg{Any}}) - Compile the given function ``f`` for the argument tuple (of types) ``args``, but do not execute it. + .. Docstring generated from Julia source + .. code-block:: julia + 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 81fbf0084b7cc4..d63ef99dd645cc 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -6,190 +6,211 @@ .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...) - Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. - Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. + Call function in C-exported shared library, specified by ``(function name, library)`` tuple, where each component is an AbstractString or :Symbol. - 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)`` + Note that the argument type tuple must be a literal tuple, and not a tuple-valued variable or expression. Alternatively, ccall may also be used to call a function pointer, such as one returned by dlsym. + + Each ``ArgumentValue`` to the ``ccall`` will be converted to the corresponding ``ArgumentType``\ , by automatic insertion of calls to ``unsafe_convert(ArgumentType, cconvert(ArgumentType, ArgumentValue))``\ . (see also the documentation for each of these functions for further details). In most cases, this simply results in a call to ``convert(ArgumentType, ArgumentValue)`` .. function:: cglobal((symbol, library) [, type=Void]) - Obtain a pointer to a global variable in a C-exported shared library, specified exactly as in ``ccall``. Returns a ``Ptr{Type}``, defaulting to ``Ptr{Void}`` if no Type argument is supplied. The values can be read or written by ``unsafe_load`` or ``unsafe_store!``, respectively. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + cfunction(function::Function, ReturnType::Type, (ArgumentTypes...)) - For example:: + Generate C-callable function pointer from Julia function. Type annotation of the return value in the callback function is a must for situations where Julia cannot infer the return type automatically. - function foo() - # body + For example: - retval::Float64 - end + .. code-block:: julia + function foo() + # body - bar = cfunction(foo, Float64, ()) + retval::Float64 + end + + bar = cfunction(foo, Float64, ()) .. function:: unsafe_convert(T,x) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + In cases where ``convert`` would need to take a Julia object and turn it into a ``Ptr``\ , this function should be used to define and perform that conversion. - Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. - Accordingly, the argument ``x`` to this function should never be an expression, - only a variable name or field reference. - For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. + Be careful to ensure that a julia reference to ``x`` exists as long as the result of this function will be used. Accordingly, the argument ``x`` to this function should never be an expression, only a variable name or field reference. For example, ``x=a.b.c`` is acceptable, but ``x=[a,b,c]`` is not. - The ``unsafe`` prefix on this function indicates that using the result of this function - after the ``x`` argument to this function is no longer accessible to the program may cause - undefined behavior, including program corruption or segfaults, at any later time. + The ``unsafe`` prefix on this function indicates that using the result of this function after the ``x`` argument to this function is no longer accessible to the program may cause undefined behavior, including program corruption or segfaults, at any later time. .. function:: cconvert(T,x) + .. Docstring generated from Julia source + .. code-block:: julia + cconvert(T,x) + Convert "x" to a value of type "T", typically by calling ``convert(T,x)`` - In cases where "x" cannot be safely converted to "T", unlike ``convert``, - ``cconvert`` may return an object of a type different from "T", - which however is suitable for ``unsafe_convert`` to handle. + In cases where "x" cannot be safely converted to "T", unlike ``convert``\ , ``cconvert`` may return an object of a type different from "T", which however is suitable for ``unsafe_convert`` to handle. - Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``. + Neither ``convert`` nor ``cconvert`` should take a Julia object and turn it into a ``Ptr``\ . .. function:: unsafe_load(p::Ptr{T},i::Integer) - Load a value of type ``T`` from the address of the ith element (1-indexed) - starting at ``p``. This is equivalent to the C expression ``p[i-1]``. + .. Docstring generated from Julia source + .. code-block:: julia + unsafe_load(p::Ptr{T},i::Integer) + + Load a value of type ``T`` from the address of the ith element (1-indexed) starting at ``p``\ . This is equivalent to the C expression ``p[i-1]``\ . - The ``unsafe`` prefix on this function indicates that no validation is - performed on the pointer ``p`` to ensure that it is valid. Incorrect usage - may segfault your program or return garbage answers, in the same manner as - C. + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + unsafe_store!(p::Ptr{T},x,i::Integer) - The ``unsafe`` prefix on this function indicates that no validation is performed - on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt - or segfault your program, in the same manner as C. + Store a value of type ``T`` to the address of the ith element (1-indexed) starting at ``p``\ . This is equivalent to the C expression ``p[i-1] = x``\ . + + The ``unsafe`` prefix on this function indicates that no validation is performed on the pointer ``p`` to ensure that it is valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. .. function:: unsafe_copy!(dest::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. + .. Docstring generated from Julia source + .. code-block:: julia + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy ``N`` elements from a source pointer to a destination, with no checking. The size of an element is determined by the type of the pointers. - The ``unsafe`` prefix on this function indicates that no validation is performed - on the pointers ``dest`` and ``src`` to ensure that they are valid. - Incorrect usage may corrupt or segfault your program, in the same manner as C. + The ``unsafe`` prefix on this function indicates that no validation is performed on the pointers ``dest`` and ``src`` to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. - :: - unsafe_copy!(dest::Array, do, src::Array, so, N) + .. code-block:: julia + unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` - in the source and ``do`` in the destination (1-indexed). + Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination (1-indexed). - The ``unsafe`` prefix on this function indicates that no validation is performed - to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault - your program, in the same manner as C. + The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) - :: - unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + .. Docstring generated from Julia source + .. code-block:: julia + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) - Copy ``N`` elements from a source pointer to a destination, with no checking. The - size of an element is determined by the type of the pointers. + Copy ``N`` elements from a source pointer to a destination, with no checking. The size of an element is determined by the type of the pointers. - The ``unsafe`` prefix on this function indicates that no validation is performed - on the pointers ``dest`` and ``src`` to ensure that they are valid. - Incorrect usage may corrupt or segfault your program, in the same manner as C. + The ``unsafe`` prefix on this function indicates that no validation is performed on the pointers ``dest`` and ``src`` to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. - :: - unsafe_copy!(dest::Array, do, src::Array, so, N) + .. code-block:: julia + unsafe_copy!(dest::Array, do, src::Array, so, N) - Copy ``N`` elements from a source array to a destination, starting at offset ``so`` - in the source and ``do`` in the destination (1-indexed). + Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination (1-indexed). - The ``unsafe`` prefix on this function indicates that no validation is performed - to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault - your program, in the same manner as C. + The ``unsafe`` prefix on this function indicates that no validation is performed to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault your program, in the same manner as C. .. function:: copy!(dest, src) - Copy all elements from collection ``src`` to array ``dest``. Returns ``dest``. + .. Docstring generated from Julia source + .. code-block:: julia + copy!(dest, src) - :: - copy!(dest, do, src, so, N) + Copy all elements from collection ``src`` to array ``dest``\ . Returns ``dest``\ . - Copy ``N`` elements from collection ``src`` starting at offset ``so``, to - array ``dest`` starting at offset ``do``. Returns ``dest``. + .. code-block:: julia + copy!(dest, do, src, so, N) + + Copy ``N`` elements from collection ``src`` starting at offset ``so``\ , to array ``dest`` starting at offset ``do``\ . Returns ``dest``\ . .. function:: copy!(dest, do, src, so, N) - :: - copy!(dest, src) + .. Docstring generated from Julia source + .. code-block:: julia + copy!(dest, src) - Copy all elements from collection ``src`` to array ``dest``. Returns ``dest``. + Copy all elements from collection ``src`` to array ``dest``\ . Returns ``dest``\ . - :: - copy!(dest, do, src, so, N) + .. code-block:: julia + copy!(dest, do, src, so, N) - Copy ``N`` elements from collection ``src`` starting at offset ``so``, to - array ``dest`` starting at offset ``do``. Returns ``dest``. + Copy ``N`` elements from collection ``src`` starting at offset ``so``\ , to array ``dest`` starting at offset ``do``\ . Returns ``dest``\ . .. function:: pointer(array [, index]) - Get the native address of an array or string element. Be careful to - ensure that a julia reference to ``a`` exists as long as this - pointer will be used. This function is "unsafe" like ``unsafe_convert``. + .. Docstring generated from Julia source + .. code-block:: julia + pointer(array [, index]) + + Get the native address of an array or string element. Be careful to ensure that a julia reference to ``a`` exists as long as this pointer will be used. This function is "unsafe" like ``unsafe_convert``\ . Calling ``Ref(array[, index])`` is generally preferable to this function. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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:: + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + systemerror(sysfunc, iftrue) + Raises a ``SystemError`` for ``errno`` with the descriptive string ``sysfunc`` if ``bool`` is true .. data:: Ptr{T} diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index fee94eaa593afc..206639f0e42395 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -31,24 +31,46 @@ type. .. function:: start(iter) -> state + .. Docstring generated from Julia source + .. code-block:: julia + start(iter) -> state + Get initial iteration state for an iterable object .. function:: done(iter, state) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + done(iter, state) -> Bool + Test whether we are done iterating .. function:: next(iter, state) -> item, state + .. Docstring generated from Julia source + .. code-block:: julia + 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...) + .. Docstring generated from Julia source + :: + + zip(iters...) + For a set of iterable objects, returns an iterable of tuples, where the ``i``\ th tuple contains the ``i``\ th component of each input iterable. Note that :func:`zip` is its own inverse: ``collect(zip(zip(a...)...)) == collect(a)``. .. function:: enumerate(iter) + .. Docstring generated from Julia source + :: + + enumerate(iter) + An iterator that yields ``(i, x)`` where ``i`` is an index starting at 1, and ``x`` is the ``i``\ th value from the given iterator. It's useful when you need not only the values ``x`` over which you are iterating, but also the index ``i`` of the iterations. .. doctest:: @@ -64,28 +86,51 @@ type. .. function:: rest(iter, state) - An iterator that yields the same elements as ``iter``, but starting at the given ``state``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + take(iter, n) + + An iterator that generates at most the first ``n`` elements of ``iter``\ . .. function:: drop(iter, n) - An iterator that generates all but the first ``n`` elements of ``iter``. + .. Docstring generated from Julia source + .. code-block:: julia + drop(iter, n) + + An iterator that generates all but the first ``n`` elements of ``iter``\ . .. function:: cycle(iter) + .. Docstring generated from Julia source + .. code-block:: julia + 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)``). + .. Docstring generated from Julia source + .. code-block:: julia + 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)``\ ). Fully implemented by: @@ -109,6 +154,11 @@ General Collections .. function:: isempty(collection) -> Bool + .. Docstring generated from Julia source + :: + + isempty(collection) -> Bool + Determine whether a collection is empty (has no elements). .. doctest:: @@ -121,27 +171,37 @@ General Collections .. function:: empty!(collection) -> collection - Remove all elements from a ``collection``. + .. Docstring generated from Julia source + .. code-block:: julia + empty!(collection) -> collection + + Remove all elements from a ``collection``\ . .. function:: length(collection) -> Integer - :: - length(A) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + length(A) -> Integer Returns the number of elements in A - :: - length(collection) -> Integer + .. code-block:: julia + 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) + .. code-block:: julia + length(s) - The number of characters in string ``s``. + The number of characters in string ``s``\ . .. function:: endof(collection) -> Integer + .. Docstring generated from Julia source + :: + + endof(collection) -> Integer + Returns the last index of the collection. .. doctest:: @@ -167,7 +227,10 @@ Iterable Collections .. function:: in(item, collection) -> Bool + .. Docstring generated from Julia source :: + + in(item, collection) -> Bool ∈(item,collection) -> Bool ∋(collection,item) -> Bool ∉(item,collection) -> Bool @@ -183,100 +246,86 @@ Iterable Collections .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + reduce(op, v0, itr) - Reductions for certain commonly-used operators have special - implementations which should be used instead: ``maximum(itr)``, - ``minimum(itr)``, ``sum(itr)``, ``prod(itr)``, ``any(itr)``, - ``all(itr)``. + 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. - 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. + 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)``\ . - 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. + The associativity of the reduction is implementation dependent. This means that you can't use non-associative operations like ``-`` because it is undefined whether ``reduce(-,[1,2,3])`` should be evaluated as ``(1-2)-3`` or ``1-(2-3)``\ . Use ``foldl`` or ``foldr`` instead for guaranteed left or right associativity. - :: - reduce(op, itr) + Some operations accumulate error, and parallelism will also be easier if the reduction can be executed in groups. Future versions of Julia might change the algorithm. Note that the elements are not reordered if you use an ordered collection. + + .. code-block:: julia + reduce(op, itr) - Like ``reduce(op, v0, itr)``. This cannot be used with empty - collections, except for some special cases (e.g. when ``op`` is one - of ``+``, ``*``, ``max``, ``min``, ``&``, ``|``) when Julia can - determine the neutral element of ``op``. + Like ``reduce(op, v0, itr)``\ . This cannot be used with empty collections, except for some special cases (e.g. when ``op`` is one of ``+``\ , ``*``\ , ``max``\ , ``min``\ , ``&``\ , ``|``\ ) when Julia can determine the neutral element of ``op``\ . .. function:: reduce(op, itr) - :: - reduce(op, v0, itr) + .. Docstring generated from Julia source + .. code-block:: julia + reduce(op, v0, itr) - Reduce the given collection ``ìtr`` with the given binary operator - ``op``. ``v0`` must be a neutral element for ``op`` that will be - returned for empty collections. It is unspecified whether ``v0`` is - used for non-empty collections. + Reduce the given collection ``ìtr`` with the given binary operator ``op``\ . ``v0`` must be a neutral element for ``op`` that will be returned for empty collections. It is unspecified whether ``v0`` is used for non-empty collections. - Reductions for certain commonly-used operators have special - implementations which should be used instead: ``maximum(itr)``, - ``minimum(itr)``, ``sum(itr)``, ``prod(itr)``, ``any(itr)``, - ``all(itr)``. + Reductions for certain commonly-used operators have special implementations which should be used instead: ``maximum(itr)``\ , ``minimum(itr)``\ , ``sum(itr)``\ , ``prod(itr)``\ , ``any(itr)``\ , ``all(itr)``\ . - The associativity of the reduction is implementation dependent. - This means that you can't use non-associative operations like ``-`` - because it is undefined whether ``reduce(-,[1,2,3])`` should be - evaluated as ``(1-2)-3`` or ``1-(2-3)``. Use ``foldl`` or ``foldr`` - instead for guaranteed left or right associativity. + The associativity of the reduction is implementation dependent. This means that you can't use non-associative operations like ``-`` because it is undefined whether ``reduce(-,[1,2,3])`` should be evaluated as ``(1-2)-3`` or ``1-(2-3)``\ . Use ``foldl`` or ``foldr`` instead for guaranteed left or right associativity. - Some operations accumulate error, and parallelism will also be - easier if the reduction can be executed in groups. Future versions - of Julia might change the algorithm. Note that the elements are not - reordered if you use an ordered collection. + Some operations accumulate error, and parallelism will also be easier if the reduction can be executed in groups. Future versions of Julia might change the algorithm. Note that the elements are not reordered if you use an ordered collection. - :: - reduce(op, itr) + .. code-block:: julia + reduce(op, itr) - Like ``reduce(op, v0, itr)``. This cannot be used with empty - collections, except for some special cases (e.g. when ``op`` is one - of ``+``, ``*``, ``max``, ``min``, ``&``, ``|``) when Julia can - determine the neutral element of ``op``. + Like ``reduce(op, v0, itr)``\ . This cannot be used with empty collections, except for some special cases (e.g. when ``op`` is one of ``+``\ , ``*``\ , ``max``\ , ``min``\ , ``&``\ , ``|``\ ) when Julia can determine the neutral element of ``op``\ . .. function:: foldl(op, v0, itr) + .. Docstring generated from Julia source + :: + + 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`` @@ -285,13 +334,16 @@ Iterable Collections .. function:: foldl(op, itr) + .. Docstring generated from Julia source :: + 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`` @@ -300,10 +352,16 @@ Iterable Collections .. function:: foldr(op, v0, itr) + .. Docstring generated from Julia source + :: + + 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`` @@ -312,13 +370,16 @@ Iterable Collections .. function:: foldr(op, itr) + .. Docstring generated from Julia source :: + 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`` @@ -327,352 +388,441 @@ Iterable Collections .. function:: maximum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + maximum(itr) + Returns the largest element in a collection. - :: - maximum(A, dims) + .. code-block:: julia + maximum(A, dims) Compute the maximum value of an array over the given dimensions. .. function:: maximum(A, dims) - :: - maximum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + maximum(itr) Returns the largest element in a collection. - :: - maximum(A, dims) + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + maximum!(r, A) + + Compute the maximum value of ``A`` over the singleton dimensions of ``r``\ , and write results to ``r``\ . .. function:: minimum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + minimum(itr) + Returns the smallest element in a collection. - :: - minimum(A, dims) + .. code-block:: julia + minimum(A, dims) Compute the minimum value of an array over the given dimensions. .. function:: minimum(A, dims) - :: - minimum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + minimum(itr) Returns the smallest element in a collection. - :: - minimum(A, dims) + .. code-block:: julia + minimum(A, dims) Compute the minimum value of an array over the given dimensions. .. function:: minimum!(r, A) - Compute the minimum value of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + minimum!(r, A) + + Compute the minimum value of ``A`` over the singleton dimensions of ``r``\ , and write results to ``r``\ . .. function:: extrema(itr) - Compute both the minimum and maximum element in a single pass, and - return them as a 2-tuple. + .. Docstring generated from Julia source + .. code-block:: julia + extrema(itr) + + Compute both the minimum and maximum element in a single pass, and return them as a 2-tuple. .. function:: indmax(itr) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + indmax(itr) -> Integer + Returns the index of the maximum element in a collection. .. function:: indmin(itr) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + indmin(itr) -> Integer + Returns the index of the minimum element in a collection. .. function:: findmax(itr) -> (x, index) + .. Docstring generated from Julia source + .. code-block:: julia + findmax(itr) -> (x, index) + Returns the maximum element and its index. - :: - findmax(A, dims) -> (maxval, index) + .. code-block:: julia + findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over - the given dimensions. + For an array input, returns the value and index of the maximum over the given dimensions. .. function:: findmax(A, dims) -> (maxval, index) - :: - findmax(itr) -> (x, index) + .. Docstring generated from Julia source + .. code-block:: julia + findmax(itr) -> (x, index) Returns the maximum element and its index. - :: - findmax(A, dims) -> (maxval, index) + .. code-block:: julia + findmax(A, dims) -> (maxval, index) - For an array input, returns the value and index of the maximum over - the given dimensions. + For an array input, returns the value and index of the maximum over the given dimensions. .. function:: findmin(itr) -> (x, index) + .. Docstring generated from Julia source + .. code-block:: julia + findmin(itr) -> (x, index) + Returns the minimum element and its index. - :: - findmin(A, dims) -> (minval, index) + .. code-block:: julia + findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over - the given dimensions. + For an array input, returns the value and index of the minimum over the given dimensions. .. function:: findmin(A, dims) -> (minval, index) - :: - findmin(itr) -> (x, index) + .. Docstring generated from Julia source + .. code-block:: julia + findmin(itr) -> (x, index) Returns the minimum element and its index. - :: - findmin(A, dims) -> (minval, index) + .. code-block:: julia + findmin(A, dims) -> (minval, index) - For an array input, returns the value and index of the minimum over - the given dimensions. + For an array input, returns the value and index of the minimum over the given dimensions. .. function:: maxabs(itr) + .. Docstring generated from Julia source + .. code-block:: julia + maxabs(itr) + Compute the maximum absolute value of a collection of values. - :: - maxabs(A, dims) + .. code-block:: julia + maxabs(A, dims) Compute the maximum absolute values over given dimensions. .. function:: maxabs(A, dims) - :: - maxabs(itr) + .. Docstring generated from Julia source + .. code-block:: julia + maxabs(itr) Compute the maximum absolute value of a collection of values. - :: - maxabs(A, dims) + .. code-block:: julia + maxabs(A, dims) Compute the maximum absolute values over given dimensions. .. function:: maxabs!(r, A) - Compute the maximum absolute values over the singleton dimensions of ``r``, - and write values to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + maxabs!(r, A) + + Compute the maximum absolute values over the singleton dimensions of ``r``\ , and write values to ``r``\ . .. function:: minabs(itr) + .. Docstring generated from Julia source + .. code-block:: julia + minabs(itr) + Compute the minimum absolute value of a collection of values. - :: - minabs(A, dims) + .. code-block:: julia + minabs(A, dims) Compute the minimum absolute values over given dimensions. .. function:: minabs(A, dims) - :: - minabs(itr) + .. Docstring generated from Julia source + .. code-block:: julia + minabs(itr) Compute the minimum absolute value of a collection of values. - :: - minabs(A, dims) + .. code-block:: julia + minabs(A, dims) Compute the minimum absolute values over given dimensions. .. function:: minabs!(r, A) - Compute the minimum absolute values over the singleton dimensions of ``r``, - and write values to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + minabs!(r, A) + + Compute the minimum absolute values over the singleton dimensions of ``r``\ , and write values to ``r``\ . .. function:: sum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + sum(itr) + Returns the sum of all elements in a collection. - :: - sum(A, dims) + .. code-block:: julia + sum(A, dims) Sum elements of an array over the given dimensions. - :: - sum(f, itr) + .. code-block:: julia + sum(f, itr) - Sum the results of calling function ``f`` on each element of ``itr``. + Sum the results of calling function ``f`` on each element of ``itr``\ . .. function:: sum(A, dims) - :: - sum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + sum(itr) Returns the sum of all elements in a collection. - :: - sum(A, dims) + .. code-block:: julia + sum(A, dims) Sum elements of an array over the given dimensions. - :: - sum(f, itr) + .. code-block:: julia + sum(f, itr) - Sum the results of calling function ``f`` on each element of ``itr``. + Sum the results of calling function ``f`` on each element of ``itr``\ . .. function:: sum!(r, A) - Sum elements of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + sum!(r, A) + + Sum elements of ``A`` over the singleton dimensions of ``r``\ , and write results to ``r``\ . .. function:: sum(f, itr) - :: - sum(itr) + .. Docstring generated from Julia source + .. code-block:: julia + sum(itr) Returns the sum of all elements in a collection. - :: - sum(A, dims) + .. code-block:: julia + sum(A, dims) Sum elements of an array over the given dimensions. - :: - sum(f, itr) + .. code-block:: julia + sum(f, itr) - Sum the results of calling function ``f`` on each element of ``itr``. + Sum the results of calling function ``f`` on each element of ``itr``\ . .. function:: sumabs(itr) - Sum absolute values of all elements in a collection. This is - equivalent to ``sum(abs(itr))`` but faster. + .. Docstring generated from Julia source + .. code-block:: julia + sumabs(itr) - :: - sumabs(A, dims) + Sum absolute values of all elements in a collection. This is equivalent to ``sum(abs(itr))`` but faster. - Sum absolute values of elements of an array over the given - dimensions. + .. code-block:: julia + sumabs(A, dims) + + Sum absolute values of elements of an array over the given dimensions. .. function:: sumabs(A, dims) - :: - sumabs(itr) + .. Docstring generated from Julia source + .. code-block:: julia + sumabs(itr) - Sum absolute values of all elements in a collection. This is - equivalent to ``sum(abs(itr))`` but faster. + Sum absolute values of all elements in a collection. This is equivalent to ``sum(abs(itr))`` but faster. - :: - sumabs(A, dims) + .. code-block:: julia + sumabs(A, dims) - Sum absolute values of elements of an array over the given - dimensions. + Sum absolute values of elements of an array over the given dimensions. .. function:: sumabs!(r, A) - Sum absolute values of elements of ``A`` over the singleton - dimensions of ``r``, and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + sumabs!(r, A) + + Sum absolute values of elements of ``A`` over the singleton dimensions of ``r``\ , and write results to ``r``\ . .. function:: sumabs2(itr) - Sum squared absolute values of all elements in a collection. This - is equivalent to ``sum(abs2(itr))`` but faster. + .. Docstring generated from Julia source + .. code-block:: julia + sumabs2(itr) - :: - sumabs2(A, dims) + Sum squared absolute values of all elements in a collection. This is equivalent to ``sum(abs2(itr))`` but faster. + + .. code-block:: julia + sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. + Sum squared absolute values of elements of an array over the given dimensions. .. function:: sumabs2(A, dims) - :: - sumabs2(itr) + .. Docstring generated from Julia source + .. code-block:: julia + sumabs2(itr) - Sum squared absolute values of all elements in a collection. This - is equivalent to ``sum(abs2(itr))`` but faster. + Sum squared absolute values of all elements in a collection. This is equivalent to ``sum(abs2(itr))`` but faster. - :: - sumabs2(A, dims) + .. code-block:: julia + sumabs2(A, dims) - Sum squared absolute values of elements of an array over the given - dimensions. + Sum squared absolute values of elements of an array over the given dimensions. .. function:: sumabs2!(r, A) - Sum squared absolute values of elements of ``A`` over the singleton - dimensions of ``r``, and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + prod(itr) + Returns the product of all elements of a collection. - :: - prod(A, dims) + .. code-block:: julia + prod(A, dims) Multiply elements of an array over the given dimensions. .. function:: prod(A, dims) - :: - prod(itr) + .. Docstring generated from Julia source + .. code-block:: julia + prod(itr) Returns the product of all elements of a collection. - :: - prod(A, dims) + .. code-block:: julia + prod(A, dims) Multiply elements of an array over the given dimensions. .. function:: prod!(r, A) - Multiply elements of ``A`` over the singleton dimensions of ``r``, - and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + prod!(r, A) + + Multiply elements of ``A`` over the singleton dimensions of ``r``\ , and write results to ``r``\ . .. function:: any(itr) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + any(itr) -> Bool + Test whether any elements of a boolean collection are true. - :: - any(A, dims) + .. code-block:: julia + any(A, dims) Test whether any values along the given dimensions of an array are true. - :: - any(p, itr) -> Bool + .. code-block:: julia + any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of ``itr``. + Determine whether predicate ``p`` returns true for any elements of ``itr``\ . .. function:: any(A, dims) - :: - any(itr) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + any(itr) -> Bool Test whether any elements of a boolean collection are true. - :: - any(A, dims) + .. code-block:: julia + any(A, dims) Test whether any values along the given dimensions of an array are true. - :: - any(p, itr) -> Bool + .. code-block:: julia + any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of ``itr``. + Determine whether predicate ``p`` returns true for any elements of ``itr``\ . .. function:: any!(r, A) - Test whether any values in ``A`` along the singleton dimensions of ``r`` are true, - and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + any!(r, A) + + Test whether any values in ``A`` along the singleton dimensions of ``r`` are true, and write results to ``r``\ . .. function:: all(itr) -> Bool + .. Docstring generated from Julia source + :: + + all(itr) -> Bool + Test whether all elements of a boolean collection are true. :: + all(A, dims) Test whether all values along the given dimensions of an array are true. :: + all(p, itr) -> Bool Determine whether predicate ``p`` returns true for all elements of ``itr``. @@ -684,17 +834,21 @@ Iterable Collections .. function:: all(A, dims) + .. Docstring generated from Julia source :: + all(itr) -> Bool Test whether all elements of a boolean collection are true. :: + all(A, dims) Test whether all values along the given dimensions of an array are true. :: + all(p, itr) -> Bool Determine whether predicate ``p`` returns true for all elements of ``itr``. @@ -706,43 +860,55 @@ Iterable Collections .. function:: all!(r, A) - Test whether all values in ``A`` along the singleton dimensions of ``r`` are true, - and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + all!(r, A) + + Test whether all values in ``A`` along the singleton dimensions of ``r`` are true, and write results to ``r``\ . .. function:: count(p, itr) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + count(p, itr) -> Integer + Count the number of elements in ``itr`` for which predicate ``p`` returns true. .. function:: any(p, itr) -> Bool - :: - any(itr) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + any(itr) -> Bool Test whether any elements of a boolean collection are true. - :: - any(A, dims) + .. code-block:: julia + any(A, dims) Test whether any values along the given dimensions of an array are true. - :: - any(p, itr) -> Bool + .. code-block:: julia + any(p, itr) -> Bool - Determine whether predicate ``p`` returns true for any elements of ``itr``. + Determine whether predicate ``p`` returns true for any elements of ``itr``\ . .. function:: all(p, itr) -> Bool + .. Docstring generated from Julia source :: + all(itr) -> Bool Test whether all elements of a boolean collection are true. :: + all(A, dims) Test whether all values along the given dimensions of an array are true. :: + all(p, itr) -> Bool Determine whether predicate ``p`` returns true for all elements of ``itr``. @@ -754,6 +920,11 @@ Iterable Collections .. function:: map(f, c...) -> collection + .. Docstring generated from Julia source + :: + + map(f, c...) -> collection + Transform collection ``c`` by applying ``f`` to each element. For multiple collection arguments, apply ``f`` elementwise. @@ -773,9 +944,15 @@ Iterable Collections .. function:: map!(function, collection) + .. Docstring generated from Julia source + :: + + map!(function, collection) + In-place version of :func:`map`. :: + map!(function, destination, collection...) Like :func:`map`, but stores the result in ``destination`` rather than a @@ -784,12 +961,15 @@ Iterable Collections .. function:: map!(function, destination, collection...) + .. Docstring generated from Julia source :: + map!(function, collection) In-place version of :func:`map`. :: + map!(function, destination, collection...) Like :func:`map`, but stores the result in ``destination`` rather than a @@ -798,6 +978,11 @@ Iterable Collections .. function:: mapreduce(f, op, v0, itr) + .. Docstring generated from Julia source + :: + + mapreduce(f, op, v0, itr) + Apply function ``f`` to each element in ``itr``, and then reduce the result using the binary function ``op``. ``v0`` must be a neutral element for ``op`` that will be returned for empty @@ -821,6 +1006,7 @@ Iterable Collections left or right associativity and invocation of ``f`` for every value. :: + mapreduce(f, op, itr) Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used @@ -828,7 +1014,9 @@ Iterable Collections .. function:: mapreduce(f, op, itr) + .. Docstring generated from Julia source :: + mapreduce(f, op, v0, itr) Apply function ``f`` to each element in ``itr``, and then reduce @@ -854,6 +1042,7 @@ Iterable Collections left or right associativity and invocation of ``f`` for every value. :: + mapreduce(f, op, itr) Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used @@ -861,10 +1050,16 @@ Iterable Collections .. function:: mapfoldl(f, op, v0, itr) + .. Docstring generated from Julia source + :: + + mapfoldl(f, op, v0, itr) + Like :func:`mapreduce`, but with guaranteed left associativity. ``v0`` will be used exactly once. :: + mapfoldl(f, op, itr) Like ``mapfoldl(f, op, v0, itr)``, but using the first element of @@ -873,13 +1068,16 @@ Iterable Collections .. function:: mapfoldl(f, op, itr) + .. Docstring generated from Julia source :: + mapfoldl(f, op, v0, itr) Like :func:`mapreduce`, but with guaranteed left associativity. ``v0`` will be used exactly once. :: + mapfoldl(f, op, itr) Like ``mapfoldl(f, op, v0, itr)``, but using the first element of @@ -888,10 +1086,16 @@ Iterable Collections .. function:: mapfoldr(f, op, v0, itr) + .. Docstring generated from Julia source + :: + + mapfoldr(f, op, v0, itr) + Like :func:`mapreduce`, but with guaranteed right associativity. ``v0`` will be used exactly once. :: + mapfoldr(f, op, itr) Like ``mapfoldr(f, op, v0, itr)``, but using the first element of @@ -900,13 +1104,16 @@ Iterable Collections .. function:: mapfoldr(f, op, itr) + .. Docstring generated from Julia source :: + mapfoldr(f, op, v0, itr) Like :func:`mapreduce`, but with guaranteed right associativity. ``v0`` will be used exactly once. :: + mapfoldr(f, op, itr) Like ``mapfoldr(f, op, v0, itr)``, but using the first element of @@ -915,43 +1122,66 @@ Iterable Collections .. function:: first(coll) + .. Docstring generated from Julia source + :: + + first(coll) + Get the first element of an iterable collection. Returns the start point of a :obj:`Range` even if it is empty. .. function:: last(coll) + .. Docstring generated from Julia source + :: + + last(coll) + Get the last element of an ordered collection, if it can be computed in O(1) time. This is accomplished by calling :func:`endof` to get the last index. Returns the end point of a :obj:`Range` even if it is empty. .. function:: step(r) + .. Docstring generated from Julia source + :: + + step(r) + Get the step size of a :obj:`Range` object. .. function:: collect(collection) + .. Docstring generated from Julia source + .. code-block:: julia + collect(collection) + Return an array of all items in a collection. For associative collections, returns (key, value) tuples. - :: - collect(element_type, collection) + .. code-block:: julia + 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(collection) + .. Docstring generated from Julia source + .. code-block:: julia + collect(collection) Return an array of all items in a collection. For associative collections, returns (key, value) tuples. - :: - collect(element_type, collection) + .. code-block:: julia + collect(element_type, collection) Return an array of type ``Array{element_type,1}`` of all items in a collection. .. function:: issubset(a, b) + .. Docstring generated from Julia source :: + + issubset(a, b) ⊆(A,S) -> Bool ⊈(A,S) -> Bool ⊊(A,S) -> Bool @@ -959,6 +1189,7 @@ Iterable Collections Determine whether every element of ``a`` is also in ``b``, using :func:`in`. :: + issubset(A, S) -> Bool ⊆(A,S) -> Bool @@ -966,30 +1197,40 @@ Iterable Collections .. 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). + .. Docstring generated from Julia source + .. code-block:: julia + 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:: filter!(function, collection) - Update ``collection``, removing elements for which ``function`` is false. - For associative collections, the function is passed two arguments (key and value). + .. Docstring generated from Julia source + .. code-block:: julia + 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...) + .. Docstring generated from Julia source :: + getindex(type[, elements...]) Construct a 1-d array of the specified type. This is usually called with the syntax ``Type[]``. Element values can be specified using ``Type[a,b,c,...]``. :: + getindex(A, inds...) Returns a subset of array ``A`` as specified by ``inds``, where each ``ind`` may be an ``Int``, a ``Range``, or a ``Vector``. See the manual section on :ref:`array indexing ` for details. :: + getindex(collection, key...) Retrieve the value(s) stored at the given key or index within a collection. @@ -998,17 +1239,16 @@ Indexable Collections .. function:: setindex!(collection, value, key...) - :: - setindex!(A, X, inds...) + .. Docstring generated from Julia source + .. code-block:: julia + setindex!(A, X, inds...) - Store values from array ``X`` within some subset of ``A`` as specified by ``inds``. + Store values from array ``X`` within some subset of ``A`` as specified by ``inds``\ . - :: - setindex!(collection, value, key...) + .. code-block:: julia + setindex!(collection, value, key...) - Store the given value at the given key or index within a collection. - The syntax ``a[i,j,...] = x`` is converted by the compiler to - ``setindex!(a, x, i, j, ...)``. + Store the given value at the given key or index within a collection. The syntax ``a[i,j,...] = x`` is converted by the compiler to ``setindex!(a, x, i, j, ...)``\ . Fully implemented by: @@ -1047,6 +1287,11 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: Dict([itr]) + .. Docstring generated from Julia source + :: + + Dict([itr]) + ``Dict{K,V}()`` constructs a hash table with keys of type ``K`` and values of type ``V``. Given a single iterable argument, constructs a :obj:`Dict` whose key-value pairs @@ -1070,28 +1315,37 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: haskey(collection, key) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + haskey(collection, key) -> Bool + Determine whether a collection has a mapping for a given key. .. function:: get(collection, key, default) + .. Docstring generated from Julia source :: + get(x) Attempt to access the value of the ``Nullable`` object, ``x``. Returns the value if it is present; otherwise, throws a ``NullException``. :: + get(x, y) Attempt to access the value of the ``Nullable{T}`` object, ``x``. Returns the value if it is present; otherwise, returns ``convert(T, y)``. :: + get(collection, key, default) Return the value stored for the given key, or the given default value if no mapping for the key is present. :: + get(f::Function, collection, key) Return the value stored for the given key, or if no mapping for the key is present, return ``f()``. Use :func:`get!` to also store the default value in the dictionary. @@ -1103,24 +1357,29 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: get(f::Function, collection, key) + .. Docstring generated from Julia source :: + get(x) Attempt to access the value of the ``Nullable`` object, ``x``. Returns the value if it is present; otherwise, throws a ``NullException``. :: + get(x, y) Attempt to access the value of the ``Nullable{T}`` object, ``x``. Returns the value if it is present; otherwise, returns ``convert(T, y)``. :: + get(collection, key, default) Return the value stored for the given key, or the given default value if no mapping for the key is present. :: + get(f::Function, collection, key) Return the value stored for the given key, or if no mapping for the key is present, return ``f()``. Use :func:`get!` to also store the default value in the dictionary. @@ -1135,51 +1394,72 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: get!(collection, key, default) - Return the value stored for the given key, or if no mapping for the key is present, store ``key => default``, and return ``default``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 => default``\ , and return ``default``\ . - Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``, and return ``f()``. + .. code-block:: julia + get!(f::Function, collection, key) - This is intended to be called using ``do`` block syntax:: + Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``\ , and return ``f()``\ . - get!(dict, key) do - # default value calculated here + This is intended to be called using ``do`` block syntax: + + .. code-block:: julia + get!(dict, key) do + # default value calculated here .. function:: get!(f::Function, collection, key) - :: - get!(collection, key, default) + .. Docstring generated from Julia source + .. code-block:: julia + get!(collection, key, default) - Return the value stored for the given key, or if no mapping for the key is present, store ``key => default``, and return ``default``. + Return the value stored for the given key, or if no mapping for the key is present, store ``key => default``\ , and return ``default``\ . - :: - get!(f::Function, collection, key) + .. code-block:: julia + get!(f::Function, collection, key) - Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``, and return ``f()``. + Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``\ , and return ``f()``\ . - This is intended to be called using ``do`` block syntax:: + This is intended to be called using ``do`` block syntax: - get!(dict, key) do - # default value calculated here + .. code-block:: julia + get!(dict, key) do + # default value calculated here time() end .. function:: getkey(collection, key, default) - Return the key matching argument ``key`` if one exists in ``collection``, otherwise return ``default``. + .. Docstring generated from Julia source + .. code-block:: julia + getkey(collection, key, default) + + Return the key matching argument ``key`` if one exists in ``collection``\ , otherwise return ``default``\ . .. function:: delete!(collection, key) + .. Docstring generated from Julia source + .. code-block:: julia + delete!(collection, key) + Delete the mapping for the given key in a collection, and return the collection. .. function:: pop!(collection, key[, default]) + .. Docstring generated from Julia source + :: + + pop!(collection, key[, default]) + Delete and return the mapping for ``key`` if it exists in ``collection``, otherwise return ``default``, or throw an error if default is not specified. :: + pop!(collection) -> item Remove the last item in ``collection`` and return it. @@ -1208,14 +1488,27 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: keys(collection) + .. Docstring generated from Julia source + .. code-block:: julia + keys(collection) + Return an iterator over all keys in a collection. ``collect(keys(d))`` returns an array of keys. .. function:: values(collection) + .. Docstring generated from Julia source + .. code-block:: julia + values(collection) + Return an iterator over all values in a collection. ``collect(values(d))`` returns an array of values. .. function:: merge(collection, others...) + .. Docstring generated from Julia source + :: + + merge(collection, others...) + Construct a merged collection from the given collections. If necessary, the types of the resulting collection will be promoted to accommodate the types of the merged collections. If the same key is present in another collection, the value for that key will be the value it has in the last collection listed. .. doctest:: @@ -1244,10 +1537,18 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: merge!(collection, others...) + .. Docstring generated from Julia source + .. code-block:: julia + merge!(collection, others...) + Update collection with pairs from the other collections .. function:: sizehint!(s, n) + .. Docstring generated from Julia source + .. code-block:: julia + sizehint!(s, n) + Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. Fully implemented by: @@ -1269,109 +1570,158 @@ Set-Like Collections .. function:: Set([itr]) + .. Docstring generated from Julia source + :: + + Set([itr]) + Construct a :obj:`Set` of the values generated by the given iterable object, or an empty set. Should be used instead of :obj:`IntSet` for sparse integer sets, or for sets of arbitrary objects. .. function:: IntSet([itr]) + .. Docstring generated from Julia source + :: + + IntSet([itr]) + Construct a sorted set of the integers generated by the given iterable object, or an empty set. Implemented as a bit string, and therefore designed for dense integer sets. Only non-negative integers can be stored. If the set will be sparse (for example holding a single very large integer), use :obj:`Set` instead. .. function:: union(s1,s2...) - :: - ∪(s1,s2) + .. Docstring generated from Julia source + .. code-block:: julia + union(s1,s2...) + ∪(s1,s2) Construct the union of two or more sets. Maintains order with arrays. .. function:: union!(s, iterable) + .. Docstring generated from Julia source + .. code-block:: julia + union!(s, iterable) + Union each element of ``iterable`` into set ``s`` in-place. .. function:: intersect(s1,s2...) - :: - ∩(s1,s2) + .. Docstring generated from Julia source + .. code-block:: julia + 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:: 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: setdiff!(s, iterable) + .. Docstring generated from Julia source + .. code-block:: julia + setdiff!(s, iterable) + Remove each element of ``iterable`` from set ``s`` in-place. .. function:: symdiff(s1,s2...) + .. Docstring generated from Julia source + .. code-block:: julia + symdiff(s1,s2...) + Construct the symmetric difference of elements in the passed in sets or arrays. Maintains order with arrays. .. function:: symdiff!(s, n) - The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + .. Docstring generated from Julia source + .. code-block:: julia + symdiff!(s, n) - :: - symdiff!(s, itr) + The set ``s`` is destructively modified to toggle the inclusion of integer ``n``\ . - For each element in ``itr``, destructively toggle its inclusion in set ``s``. + .. code-block:: julia + symdiff!(s, itr) - :: - symdiff!(s1, s2) + For each element in ``itr``\ , destructively toggle its inclusion in set ``s``\ . + + .. code-block:: julia + symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + Construct the symmetric difference of sets ``s1`` and ``s2``\ , storing the result in ``s1``\ . .. function:: symdiff!(s, itr) - :: - symdiff!(s, n) + .. Docstring generated from Julia source + .. code-block:: julia + symdiff!(s, n) - The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + The set ``s`` is destructively modified to toggle the inclusion of integer ``n``\ . - :: - symdiff!(s, itr) + .. code-block:: julia + symdiff!(s, itr) - For each element in ``itr``, destructively toggle its inclusion in set ``s``. + For each element in ``itr``\ , destructively toggle its inclusion in set ``s``\ . - :: - symdiff!(s1, s2) + .. code-block:: julia + symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + Construct the symmetric difference of sets ``s1`` and ``s2``\ , storing the result in ``s1``\ . .. function:: symdiff!(s1, s2) - :: - symdiff!(s, n) + .. Docstring generated from Julia source + .. code-block:: julia + symdiff!(s, n) - The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + The set ``s`` is destructively modified to toggle the inclusion of integer ``n``\ . - :: - symdiff!(s, itr) + .. code-block:: julia + symdiff!(s, itr) - For each element in ``itr``, destructively toggle its inclusion in set ``s``. + For each element in ``itr``\ , destructively toggle its inclusion in set ``s``\ . - :: - symdiff!(s1, s2) + .. code-block:: julia + symdiff!(s1, s2) - Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + Construct the symmetric difference of sets ``s1`` and ``s2``\ , storing the result in ``s1``\ . .. function:: complement(s) + .. Docstring generated from Julia source + :: + + complement(s) + Returns the set-complement of :obj:`IntSet` ``s``. .. function:: complement!(s) + .. Docstring generated from Julia source + :: + + complement!(s) + Mutates :obj:`IntSet` ``s`` into its set-complement. .. function:: intersect!(s1, s2) - Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of ``s2``. + .. Docstring generated from Julia source + .. code-block:: julia + 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:: issubset(A, S) -> Bool + .. Docstring generated from Julia source :: + issubset(a, b) ⊆(A,S) -> Bool ⊈(A,S) -> Bool @@ -1380,6 +1730,7 @@ Set-Like Collections Determine whether every element of ``a`` is also in ``b``, using :func:`in`. :: + issubset(A, S) -> Bool ⊆(A,S) -> Bool @@ -1399,6 +1750,11 @@ Dequeues .. function:: push!(collection, items...) -> collection + .. Docstring generated from Julia source + :: + + push!(collection, items...) -> collection + Insert one or more ``items`` at the end of ``collection``. .. doctest:: @@ -1419,12 +1775,15 @@ Dequeues .. function:: pop!(collection) -> item + .. Docstring generated from Julia source :: + pop!(collection, key[, default]) Delete and return the mapping for ``key`` if it exists in ``collection``, otherwise return ``default``, or throw an error if default is not specified. :: + pop!(collection) -> item Remove the last item in ``collection`` and return it. @@ -1453,6 +1812,11 @@ Dequeues .. function:: unshift!(collection, items...) -> collection + .. Docstring generated from Julia source + :: + + unshift!(collection, items...) -> collection + Insert one or more ``items`` at the beginning of ``collection``. .. doctest:: @@ -1468,6 +1832,11 @@ Dequeues .. function:: shift!(collection) -> item + .. Docstring generated from Julia source + :: + + shift!(collection) -> item + Remove the first ``item`` from ``collection``. .. doctest:: @@ -1494,6 +1863,11 @@ Dequeues .. function:: insert!(collection, index, item) + .. Docstring generated from Julia source + :: + + insert!(collection, index, item) + Insert an ``item`` into ``collection`` at the given ``index``. ``index`` is the index of ``item`` in the resulting ``collection``. @@ -1510,6 +1884,11 @@ Dequeues .. function:: deleteat!(collection, index) + .. Docstring generated from Julia source + :: + + deleteat!(collection, index) + Remove the item at the given ``index`` and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. @@ -1524,6 +1903,7 @@ Dequeues 1 :: + deleteat!(collection, itr) Remove the items at the indices given by ``itr``, and return the modified ``collection``. @@ -1545,7 +1925,9 @@ Dequeues .. function:: deleteat!(collection, itr) + .. Docstring generated from Julia source :: + deleteat!(collection, index) Remove the item at the given ``index`` and return the modified ``collection``. @@ -1562,6 +1944,7 @@ Dequeues 1 :: + deleteat!(collection, itr) Remove the items at the indices given by ``itr``, and return the modified ``collection``. @@ -1583,6 +1966,11 @@ Dequeues .. function:: splice!(collection, index, [replacement]) -> item + .. Docstring generated from Julia source + :: + + splice!(collection, index, [replacement]) -> item + Remove the item at the given index, and return the removed item. Subsequent items are shifted down to fill the resulting gap. If specified, replacement values from an ordered collection will be spliced in place of the removed item. @@ -1628,6 +2016,7 @@ Dequeues ``splice!(collection, n:n-1, replacement)``. :: + splice!(collection, range, [replacement]) -> items Remove items in the specified index range, and return a collection containing the @@ -1656,7 +2045,9 @@ Dequeues .. function:: splice!(collection, range, [replacement]) -> items + .. Docstring generated from Julia source :: + splice!(collection, index, [replacement]) -> item Remove the item at the given index, and return the removed item. Subsequent items @@ -1704,6 +2095,7 @@ Dequeues ``splice!(collection, n:n-1, replacement)``. :: + splice!(collection, range, [replacement]) -> items Remove items in the specified index range, and return a collection containing the @@ -1732,6 +2124,11 @@ Dequeues .. function:: resize!(collection, n) -> collection + .. Docstring generated from Julia source + :: + + 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 @@ -1760,6 +2157,11 @@ Dequeues .. function:: append!(collection, collection2) -> collection. + .. Docstring generated from Julia source + :: + + append!(collection, collection2) -> collection. + Add the elements of ``collection2`` to the end of ``collection``. .. doctest:: @@ -1788,6 +2190,11 @@ Dequeues .. function:: prepend!(collection, items) -> collection + .. Docstring generated from Julia source + :: + + prepend!(collection, items) -> collection + Insert the elements of ``items`` to the beginning of ``collection``. .. doctest:: @@ -1815,20 +2222,37 @@ changed efficiently. .. function:: PriorityQueue(K, V, [ord]) + .. Docstring generated from Julia source + :: + + 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``. .. function:: enqueue!(pq, k, v) - Insert the a key ``k`` into a priority queue ``pq`` with priority ``v``. + .. Docstring generated from Julia source + .. code-block:: julia + enqueue!(pq, k, v) + + Insert the a key ``k`` into a priority queue ``pq`` with priority ``v``\ . .. function:: dequeue!(pq) + .. Docstring generated from Julia source + .. code-block:: julia + dequeue!(pq) + Remove and return the lowest priority key from a priority queue. .. function:: peek(pq) + .. Docstring generated from Julia source + .. code-block:: julia + 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 @@ -1863,26 +2287,42 @@ 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. + .. Docstring generated from Julia source + .. code-block:: julia + heapify(v, [ord]) + + Return a new vector in binary heap order, optionally using the given ordering. .. function:: heapify!(v, [ord]) + .. Docstring generated from Julia source + :: + + heapify!(v, [ord]) + In-place :func:`heapify`. .. function:: isheap(v, [ord]) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 ba6553e0236f5e..c3ac7897e42839 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -49,16 +49,23 @@ alternatively, you could call ``using Dates`` to bring all exported functions in .. function:: DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + .. Docstring generated from Julia source + :: + + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. :: + DateTime(periods::Period...) -> DateTime Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime Create a DateTime through the adjuster API. The starting point will be constructed from the @@ -69,12 +76,14 @@ alternatively, you could call ``using Dates`` to bring all exported functions in is never satisfied). :: + DateTime(dt::Date) -> DateTime Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime Construct a DateTime type by parsing the ``dt`` date string following the pattern given in @@ -102,25 +111,30 @@ alternatively, you could call ``using Dates`` to bring all exported functions in like "y-m-dTH:M:S.s". :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: DateTime(periods::Period...) -> DateTime + .. Docstring generated from Julia source :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. :: + DateTime(periods::Period...) -> DateTime Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime Create a DateTime through the adjuster API. The starting point will be constructed from the @@ -131,12 +145,14 @@ alternatively, you could call ``using Dates`` to bring all exported functions in is never satisfied). :: + DateTime(dt::Date) -> DateTime Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime Construct a DateTime type by parsing the ``dt`` date string following the pattern given in @@ -164,25 +180,30 @@ alternatively, you could call ``using Dates`` to bring all exported functions in like "y-m-dTH:M:S.s". :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + .. Docstring generated from Julia source :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. :: + DateTime(periods::Period...) -> DateTime Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime Create a DateTime through the adjuster API. The starting point will be constructed from the @@ -193,12 +214,14 @@ alternatively, you could call ``using Dates`` to bring all exported functions in is never satisfied). :: + DateTime(dt::Date) -> DateTime Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime Construct a DateTime type by parsing the ``dt`` date string following the pattern given in @@ -226,25 +249,30 @@ alternatively, you could call ``using Dates`` to bring all exported functions in like "y-m-dTH:M:S.s". :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: DateTime(dt::Date) -> DateTime + .. Docstring generated from Julia source :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. :: + DateTime(periods::Period...) -> DateTime Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime Create a DateTime through the adjuster API. The starting point will be constructed from the @@ -255,12 +283,14 @@ alternatively, you could call ``using Dates`` to bring all exported functions in is never satisfied). :: + DateTime(dt::Date) -> DateTime Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime Construct a DateTime type by parsing the ``dt`` date string following the pattern given in @@ -288,25 +318,30 @@ alternatively, you could call ``using Dates`` to bring all exported functions in like "y-m-dTH:M:S.s". :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + .. Docstring generated from Julia source :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. :: + DateTime(periods::Period...) -> DateTime Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime Create a DateTime through the adjuster API. The starting point will be constructed from the @@ -317,12 +352,14 @@ alternatively, you could call ``using Dates`` to bring all exported functions in is never satisfied). :: + DateTime(dt::Date) -> DateTime Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime Construct a DateTime type by parsing the ``dt`` date string following the pattern given in @@ -350,29 +387,38 @@ alternatively, you could call ``using Dates`` to bring all exported functions in like "y-m-dTH:M:S.s". :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: Dates.DateFormat(format::AbstractString) -> DateFormat - Construct a date formatting object that can be passed repeatedly for parsing similarly formatted date strings. ``format`` is a format string in the form described above (e.g. ``"yyyy-mm-dd"``). + .. Docstring generated from Julia source + .. code-block:: julia + Dates.DateFormat(format::AbstractString) -> DateFormat + + Construct a date formatting object that can be passed repeatedly for parsing similarly formatted date strings. ``format`` is a format string in the form described above (e.g. ``"yyyy-mm-dd"``\ ). .. function:: DateTime(dt::AbstractString, df::DateFormat) -> DateTime + .. Docstring generated from Julia source :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. :: + DateTime(periods::Period...) -> DateTime Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime Create a DateTime through the adjuster API. The starting point will be constructed from the @@ -383,12 +429,14 @@ alternatively, you could call ``using Dates`` to bring all exported functions in is never satisfied). :: + DateTime(dt::Date) -> DateTime Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime Construct a DateTime type by parsing the ``dt`` date string following the pattern given in @@ -416,282 +464,241 @@ alternatively, you could call ``using Dates`` to bring all exported functions in like "y-m-dTH:M:S.s". :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + .. Docstring generated from Julia source + .. code-block:: julia + Date(y, [m, d]) -> Date - :: - Date(period::Period...) -> Date + Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``\ . - 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)``. + .. code-block:: julia + Date(period::Period...) -> Date - :: - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> 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)``\ . - 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). + .. code-block:: julia + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - :: - Date(dt::DateTime) -> 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). - 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. + .. code-block:: julia + Date(dt::DateTime) -> Date - :: - Date(dt::AbstractString, format::AbstractString; locale="english") -> 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. - 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. + .. code-block:: julia + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - :: - Date(dt::AbstractString, df::DateFormat) -> Date + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. + + .. code-block:: julia + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``\ . .. function:: Date(period::Period...) -> Date - :: - Date(y, [m, d]) -> Date + .. Docstring generated from Julia source + .. code-block:: julia + Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``\ . - :: - Date(period::Period...) -> Date + .. code-block:: julia + Date(period::Period...) -> Date - Constuct a Date type by ``Period`` type parts. Arguments may be in any order. - Date parts not provided will default to the value of ``Dates.default(period)``. + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. Date parts not provided will default to the value of ``Dates.default(period)``\ . - :: - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + .. code-block:: julia + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be constructed from the - provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` - is never satisfied). + Create a Date through the adjuster API. The starting point will be constructed from the provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``\ , then the adjusting will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` is never satisfied). - :: - Date(dt::DateTime) -> Date + .. code-block:: julia + Date(dt::DateTime) -> Date - Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond - parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + Converts a ``DateTime`` type to a ``Date``\ . The hour, minute, second, and millisecond parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. - :: - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + .. code-block:: julia + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a ``dt`` date string following the pattern given in - the ``format`` string. Follows the same conventions as ``DateTime`` above. + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. - :: - Date(dt::AbstractString, df::DateFormat) -> Date + .. code-block:: julia + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``\ . .. function:: Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - :: - Date(y, [m, d]) -> Date + .. Docstring generated from Julia source + .. code-block:: julia + Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``\ . - :: - Date(period::Period...) -> Date + .. code-block:: julia + Date(period::Period...) -> Date - Constuct a Date type by ``Period`` type parts. Arguments may be in any order. - Date parts not provided will default to the value of ``Dates.default(period)``. + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. Date parts not provided will default to the value of ``Dates.default(period)``\ . - :: - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + .. code-block:: julia + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be constructed from the - provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` - is never satisfied). + Create a Date through the adjuster API. The starting point will be constructed from the provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``\ , then the adjusting will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` is never satisfied). - :: - Date(dt::DateTime) -> Date + .. code-block:: julia + Date(dt::DateTime) -> Date - Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond - parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + Converts a ``DateTime`` type to a ``Date``\ . The hour, minute, second, and millisecond parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. - :: - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + .. code-block:: julia + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a ``dt`` date string following the pattern given in - the ``format`` string. Follows the same conventions as ``DateTime`` above. + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. - :: - Date(dt::AbstractString, df::DateFormat) -> Date + .. code-block:: julia + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``\ . .. function:: Date(dt::DateTime) -> Date - :: - Date(y, [m, d]) -> Date + .. Docstring generated from Julia source + .. code-block:: julia + Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``\ . - :: - Date(period::Period...) -> Date + .. code-block:: julia + Date(period::Period...) -> Date - Constuct a Date type by ``Period`` type parts. Arguments may be in any order. - Date parts not provided will default to the value of ``Dates.default(period)``. + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. Date parts not provided will default to the value of ``Dates.default(period)``\ . - :: - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + .. code-block:: julia + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be constructed from the - provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` - is never satisfied). + Create a Date through the adjuster API. The starting point will be constructed from the provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``\ , then the adjusting will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` is never satisfied). - :: - Date(dt::DateTime) -> Date + .. code-block:: julia + Date(dt::DateTime) -> Date - Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond - parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + Converts a ``DateTime`` type to a ``Date``\ . The hour, minute, second, and millisecond parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. - :: - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + .. code-block:: julia + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a ``dt`` date string following the pattern given in - the ``format`` string. Follows the same conventions as ``DateTime`` above. + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. - :: - Date(dt::AbstractString, df::DateFormat) -> Date + .. code-block:: julia + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``\ . .. function:: Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - :: - Date(y, [m, d]) -> Date + .. Docstring generated from Julia source + .. code-block:: julia + Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``\ . - :: - Date(period::Period...) -> Date + .. code-block:: julia + Date(period::Period...) -> Date - Constuct a Date type by ``Period`` type parts. Arguments may be in any order. - Date parts not provided will default to the value of ``Dates.default(period)``. + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. Date parts not provided will default to the value of ``Dates.default(period)``\ . - :: - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + .. code-block:: julia + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be constructed from the - provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` - is never satisfied). + Create a Date through the adjuster API. The starting point will be constructed from the provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``\ , then the adjusting will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` is never satisfied). - :: - Date(dt::DateTime) -> Date + .. code-block:: julia + Date(dt::DateTime) -> Date - Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond - parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + Converts a ``DateTime`` type to a ``Date``\ . The hour, minute, second, and millisecond parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. - :: - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + .. code-block:: julia + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a ``dt`` date string following the pattern given in - the ``format`` string. Follows the same conventions as ``DateTime`` above. + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. - :: - Date(dt::AbstractString, df::DateFormat) -> Date + .. code-block:: julia + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``\ . .. function:: Date(dt::AbstractString, df::DateFormat) -> Date - :: - Date(y, [m, d]) -> Date + .. Docstring generated from Julia source + .. code-block:: julia + Date(y, [m, d]) -> Date - Construct a ``Date`` type by parts. Arguments must be convertible to - ``Int64``. + Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``\ . - :: - Date(period::Period...) -> Date + .. code-block:: julia + Date(period::Period...) -> Date - Constuct a Date type by ``Period`` type parts. Arguments may be in any order. - Date parts not provided will default to the value of ``Dates.default(period)``. + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. Date parts not provided will default to the value of ``Dates.default(period)``\ . - :: - Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + .. code-block:: julia + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date - Create a Date through the adjuster API. The starting point will be constructed from the - provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in - adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting - will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to - the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` - is never satisfied). + Create a Date through the adjuster API. The starting point will be constructed from the provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``\ , then the adjusting will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` is never satisfied). - :: - Date(dt::DateTime) -> Date + .. code-block:: julia + Date(dt::DateTime) -> Date - Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond - parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + Converts a ``DateTime`` type to a ``Date``\ . The hour, minute, second, and millisecond parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. - :: - Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + .. code-block:: julia + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date - Construct a Date type by parsing a ``dt`` date string following the pattern given in - the ``format`` string. Follows the same conventions as ``DateTime`` above. + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. - :: - Date(dt::AbstractString, df::DateFormat) -> Date + .. code-block:: julia + Date(dt::AbstractString, df::DateFormat) -> Date - Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``\ . .. function:: now() -> DateTime - Returns a DateTime corresponding to the user's system - time including the system timezone locale. + .. Docstring generated from Julia source + .. code-block:: julia + now() -> DateTime - :: - now(::Type{UTC}) -> DateTime + Returns a DateTime corresponding to the user's system time including the system timezone locale. - Returns a DateTime corresponding to the user's system - time as UTC/GMT. + .. code-block:: julia + now(::Type{UTC}) -> DateTime + + Returns a DateTime corresponding to the user's system time as UTC/GMT. .. function:: now(::Type{UTC}) -> DateTime - :: - now() -> DateTime + .. Docstring generated from Julia source + .. code-block:: julia + now() -> DateTime - Returns a DateTime corresponding to the user's system - time including the system timezone locale. + Returns a DateTime corresponding to the user's system time including the system timezone locale. - :: - now(::Type{UTC}) -> DateTime + .. code-block:: julia + now(::Type{UTC}) -> DateTime - Returns a DateTime corresponding to the user's system - time as UTC/GMT. + Returns a DateTime corresponding to the user's system time as UTC/GMT. .. function:: eps(::DateTime) -> Millisecond - :: - eps(::Date) -> Day + .. Docstring generated from Julia source + .. code-block:: julia + eps(::DateTime) -> Millisecond + eps(::Date) -> Day Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. @@ -700,308 +707,432 @@ 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 + .. Docstring generated from Julia source + .. code-block:: julia + year(dt::TimeType) -> Int64 + month(dt::TimeType) -> Int64 + week(dt::TimeType) -> Int64 + day(dt::TimeType) -> Int64 + hour(dt::TimeType) -> Int64 + minute(dt::TimeType) -> Int64 + second(dt::TimeType) -> Int64 + millisecond(dt::TimeType) -> Int64 - Return the field part of a Date or DateTime as an ``Int64``. + Return the field part of a Date or DateTime as an ``Int64``\ . .. 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 + .. Docstring generated from Julia source + .. code-block:: julia + Year(dt::TimeType) -> Year + Month(dt::TimeType) -> Month + Week(dt::TimeType) -> Week + Day(dt::TimeType) -> Day + Hour(dt::TimeType) -> Hour + Minute(dt::TimeType) -> Minute + Second(dt::TimeType) -> Second + Millisecond(dt::TimeType) -> Millisecond Return the field part of a Date or DateTime as a ``Period`` type. - :: - Year(v) - Month(v) - Week(v) - Day(v) - Hour(v) - Minute(v) - Second(v) - Millisecond(v) - - Construct a ``Period`` type with the given ``v`` value. - Input must be losslessly convertible to an ``Int64``. + .. code-block:: julia + 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``\ . .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) - Simultaneously return the year and month parts of a Date or DateTime. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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.``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + :: + + 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``. .. function:: firstdayofweek(dt::TimeType) -> TimeType - Adjusts ``dt`` to the Monday of its week. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + tonext(dt::TimeType,dow::Int;same::Bool=false) -> TimeType - :: - tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType + Adjusts ``dt`` to the next day of week corresponding to ``dow`` with ``1 = Monday, 2 = Tuesday, etc``\ . Setting ``same=true`` allows the current ``dt`` to be considered as the next ``dow``\ , allowing for no adjustment to occur. - Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until - ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. - ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment - process terminate when ``func`` returns false instead of true. + .. code-block:: julia + tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``\ . ``same`` allows ``dt`` to be considered in satisfying ``func``\ . ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. .. function:: toprev(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. + .. Docstring generated from Julia source + .. code-block:: julia + toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType - :: - toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType + Adjusts ``dt`` to the previous day of week corresponding to ``dow`` with ``1 = Monday, 2 = Tuesday, etc``\ . Setting ``same=true`` allows the current ``dt`` to be considered as the previous ``dow``\ , allowing for no adjustment to occur. - Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until - ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. - ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment - process terminate when ``func`` returns false instead of true. + .. code-block:: julia + 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType - :: - tonext(dt::TimeType,dow::Int;same::Bool=false) -> TimeType + .. Docstring generated from Julia source + .. code-block:: julia + tonext(dt::TimeType,dow::Int;same::Bool=false) -> TimeType - Adjusts ``dt`` to the next day of week corresponding to ``dow`` with - ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current - ``dt`` to be considered as the next ``dow``, allowing for no adjustment to occur. + Adjusts ``dt`` to the next day of week corresponding to ``dow`` with ``1 = Monday, 2 = Tuesday, etc``\ . Setting ``same=true`` allows the current ``dt`` to be considered as the next ``dow``\ , allowing for no adjustment to occur. - :: - tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType + .. code-block:: julia + tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until - ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. - ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment - process terminate when ``func`` returns false instead of true. + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``\ . ``same`` allows ``dt`` to be considered in satisfying ``func``\ . ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. .. function:: toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType - :: - toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType + .. Docstring generated from Julia source + .. code-block:: julia + toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType - Adjusts ``dt`` to the previous day of week corresponding to ``dow`` with - ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current - ``dt`` to be considered as the previous ``dow``, allowing for no adjustment to occur. + Adjusts ``dt`` to the previous day of week corresponding to ``dow`` with ``1 = Monday, 2 = Tuesday, etc``\ . Setting ``same=true`` allows the current ``dt`` to be considered as the previous ``dow``\ , allowing for no adjustment to occur. - :: - toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType + .. code-block:: julia + toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType - Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until - ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. - ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment - process terminate when ``func`` returns false instead of true. + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``\ . ``same`` allows ``dt`` to be considered in satisfying ``func``\ . ``negate`` will make the adjustment process terminate when ``func`` returns false instead of true. .. function:: recur{T<:TimeType}(func::Function,dr::StepRange{T};negate=false,limit=10000) -> Vector{T} - ``func`` takes a single TimeType argument and returns a ``Bool`` indicating whether the input - should be "included" in the final set. ``recur`` applies ``func`` over each element in the - range of ``dr``, including those elements for which ``func`` returns ``true`` in the resulting - Array, unless ``negate=true``, then only elements where ``func`` returns ``false`` are included. + .. Docstring generated from Julia source + .. code-block:: julia + recur{T<:TimeType}(func::Function,dr::StepRange{T};negate=false,limit=10000) -> Vector{T} + + ``func`` takes a single TimeType argument and returns a ``Bool`` indicating whether the input should be "included" in the final set. ``recur`` applies ``func`` over each element in the range of ``dr``\ , including those elements for which ``func`` returns ``true`` in the resulting Array, unless ``negate=true``\ , then only elements where ``func`` returns ``false`` are included. Periods ~~~~~~~ .. function:: Year(v) - :: - 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 + .. Docstring generated from Julia source + .. code-block:: julia + Year(dt::TimeType) -> Year + Month(dt::TimeType) -> Month + Week(dt::TimeType) -> Week + Day(dt::TimeType) -> Day + Hour(dt::TimeType) -> Hour + Minute(dt::TimeType) -> Minute + Second(dt::TimeType) -> Second + Millisecond(dt::TimeType) -> Millisecond Return the field part of a Date or DateTime as a ``Period`` type. - :: - Year(v) - Month(v) - Week(v) - Day(v) - Hour(v) - Minute(v) - Second(v) - Millisecond(v) - - Construct a ``Period`` type with the given ``v`` value. - Input must be losslessly convertible to an ``Int64``. + .. code-block:: julia + 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``\ . .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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()``. + .. Docstring generated from Julia source + .. code-block:: julia + today() -> Date + + Returns the date portion of ``now()``\ . .. function:: unix2datetime(x) -> DateTime + .. Docstring generated from Julia source + :: + + unix2datetime(x) -> DateTime + Takes the number of seconds since unix epoch ``1970-01-01T00:00:00`` and converts to the corresponding DateTime. .. function:: datetime2unix(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of seconds since - the unix epoch as a ``Float64``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + :: + + julian2datetime(julian_days) -> DateTime + Takes the number of Julian calendar days since epoch ``-4713-11-24T12:00:00`` and returns the corresponding DateTime. .. function:: datetime2julian(dt::DateTime) -> Float64 - Takes the given DateTime and returns the number of Julian calendar days - since the julian epoch as a ``Float64``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + :: + + rata2datetime(days) -> DateTime + Takes the number of Rata Die days since epoch ``0000-12-31T00:00:00`` and returns the corresponding DateTime. .. function:: datetime2rata(dt::TimeType) -> Int64 - Returns the number of Rata Die days since epoch from the - given Date or DateTime. + .. Docstring generated from Julia source + .. code-block:: julia + 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 75c3e16bcf18d7..dce625636e2257 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -7,63 +7,97 @@ .. function:: pwd() -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + pwd() -> AbstractString + Get the current working directory. .. function:: cd(dir::AbstractString) + .. Docstring generated from Julia source + .. code-block:: julia + cd(dir::AbstractString) + Set the current working directory. - :: - cd(f, [dir]) + .. code-block:: julia + cd(f, [dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. .. function:: cd(f, [dir]) - :: - cd(dir::AbstractString) + .. Docstring generated from Julia source + .. code-block:: julia + cd(dir::AbstractString) Set the current working directory. - :: - cd(f, [dir]) + .. code-block:: julia + cd(f, [dir]) Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. .. function:: readdir([dir]) -> Vector{ByteString} + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + mkdir(path, [mode]) + + Make a new directory with name ``path`` and permissions ``mode``\ . ``mode`` defaults to 0o777, modified by the current file creation mask. .. function:: mkpath(path, [mode]) - Create all directories in the given ``path``, with permissions ``mode``. - ``mode`` defaults to 0o777, modified by the current file creation mask. + .. Docstring generated from Julia source + .. code-block:: julia + mkpath(path, [mode]) + + Create all directories in the given ``path``\ , with permissions ``mode``\ . ``mode`` defaults to 0o777, modified by the current file creation mask. .. function:: symlink(target, link) - Creates a symbolic link to ``target`` with the name ``link``. + .. Docstring generated from Julia source + .. code-block:: julia + symlink(target, link) + + Creates a symbolic link to ``target`` with the name ``link``\ . - .. note:: + **note** - This function raises an error under operating systems that do not support - soft symbolic links, such as Windows XP. + This function raises an error under operating systems that do not support soft symbolic links, such as Windows XP. .. function:: readlink(path) -> AbstractString - Returns the value of a symbolic link ``path``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + chmod(path, mode) + + Change the permissions mode of ``path`` to ``mode``\ . Only integer ``mode``\ s (e.g. 0o777) are currently supported. .. function:: stat(file) + .. Docstring generated from Julia source + :: + + stat(file) + Returns a structure whose fields contain information about the file. The fields of the structure are: ========= ====================================================================== @@ -83,26 +117,51 @@ .. function:: lstat(file) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + ctime(file) + Equivalent to stat(file).ctime .. function:: mtime(file) + .. Docstring generated from Julia source + .. code-block:: julia + mtime(file) + Equivalent to stat(file).mtime .. function:: filemode(file) + .. Docstring generated from Julia source + .. code-block:: julia + filemode(file) + Equivalent to stat(file).mode .. function:: filesize(path...) + .. Docstring generated from Julia source + .. code-block:: julia + filesize(path...) + Equivalent to stat(file).size .. function:: uperm(file) + .. Docstring generated from Julia source + :: + + uperm(file) + Gets the permissions of the owner of the file as a bitfield of ==== ===================== @@ -115,230 +174,367 @@ .. function:: gperm(file) + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false) + + Copy the file, link, or directory from *src* to *dest*. ``remove_destination=true`` will first remove an existing ``dst``\ . - If ``follow_symlinks=false``, and ``src`` is a symbolic link, ``dst`` will be created as a symbolic link. - If ``follow_symlinks=true`` and ``src`` is a symbolic link, ``dst`` will be a copy of the file or directory - ``src`` refers to. + 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 needed, please use a package that provides the - desired functionality instead. + .. Docstring generated from Julia source + .. code-block:: julia + 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 needed, 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``. + .. Docstring generated from Julia source + .. code-block:: julia + mv(src::AbstractString,dst::AbstractString; remove_destination::Bool=false) + + Move the file, link, or directory from *src* to *dest*. ``remove_destination=true`` will first remove an existing ``dst``\ . .. function:: rm(path::AbstractString; recursive=false) - Delete the file, link, or empty directory at the given path. If ``recursive=true`` is - passed and the path is a directory, then all contents are removed recursively. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: touch(path::AbstractString) + .. Docstring generated from Julia source + .. code-block:: julia + touch(path::AbstractString) + Update the last-modified timestamp on a file to the current time. .. function:: tempname() + .. Docstring generated from Julia source + .. code-block:: julia + tempname() + Generate a unique temporary file path. .. function:: tempdir() + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + mktemp([parent=tempdir()]) - :: - mktemp(f::function, [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. + + .. code-block:: julia + mktemp(f::function, [parent=tempdir()]) - Apply the function ``f`` to the result of ``mktemp(parent)`` and remove the - temporary file upon completion. + Apply the function ``f`` to the result of ``mktemp(parent)`` and remove the temporary file upon completion. .. function:: mktemp(f::function, [parent=tempdir()]) - :: - mktemp([parent=tempdir()]) + .. Docstring generated from Julia source + .. code-block:: julia + mktemp([parent=tempdir()]) - Returns ``(path, io)``, where ``path`` is the path of a new temporary file - in ``parent`` and ``io`` is an open file object for this path. + Returns ``(path, io)``\ , where ``path`` is the path of a new temporary file in ``parent`` and ``io`` is an open file object for this path. - :: - mktemp(f::function, [parent=tempdir()]) + .. code-block:: julia + mktemp(f::function, [parent=tempdir()]) - Apply the function ``f`` to the result of ``mktemp(parent)`` and remove the - temporary file upon completion. + Apply the function ``f`` to the result of ``mktemp(parent)`` and remove the temporary file upon completion. .. function:: mktempdir([parent=tempdir()]) + .. Docstring generated from Julia source + .. code-block:: julia + mktempdir([parent=tempdir()]) + Create a temporary directory in the ``parent`` directory and return its path. - :: - mktempdir(f::function, [parent=tempdir()]) + .. code-block:: julia + mktempdir(f::function, [parent=tempdir()]) - Apply the function ``f`` to the result of ``mktempdir(parent)`` and remove the - temporary directory upon completion. + Apply the function ``f`` to the result of ``mktempdir(parent)`` and remove the temporary directory upon completion. .. function:: mktempdir(f::function, [parent=tempdir()]) - :: - mktempdir([parent=tempdir()]) + .. Docstring generated from Julia source + .. code-block:: julia + mktempdir([parent=tempdir()]) Create a temporary directory in the ``parent`` directory and return its path. - :: - mktempdir(f::function, [parent=tempdir()]) + .. code-block:: julia + mktempdir(f::function, [parent=tempdir()]) - Apply the function ``f`` to the result of ``mktempdir(parent)`` and remove the - temporary directory upon completion. + Apply the function ``f`` to the result of ``mktempdir(parent)`` and remove the temporary directory upon completion. .. function:: isblockdev(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isblockdev(path) -> Bool + Returns ``true`` if ``path`` is a block device, ``false`` otherwise. .. function:: ischardev(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + ischardev(path) -> Bool + Returns ``true`` if ``path`` is a character device, ``false`` otherwise. .. function:: isdir(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + isexecutable(path) -> Bool + + Returns ``true`` if the current user has permission to execute ``path``\ , ``false`` otherwise. .. function:: isfifo(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isfifo(path) -> Bool + Returns ``true`` if ``path`` is a FIFO, ``false`` otherwise. .. function:: isfile(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isfile(path) -> Bool + Returns ``true`` if ``path`` is a regular file, ``false`` otherwise. .. function:: islink(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + islink(path) -> Bool + Returns ``true`` if ``path`` is a symbolic link, ``false`` otherwise. .. function:: ismount(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + ismount(path) -> Bool + Returns ``true`` if ``path`` is a mount point, ``false`` otherwise. .. function:: ispath(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + isreadable(path) -> Bool + + Returns ``true`` if the current user has permission to read ``path``\ , ``false`` otherwise. .. function:: issetgid(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + issetgid(path) -> Bool + Returns ``true`` if ``path`` has the setgid flag set, ``false`` otherwise. .. function:: issetuid(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + issetuid(path) -> Bool + Returns ``true`` if ``path`` has the setuid flag set, ``false`` otherwise. .. function:: issocket(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + issocket(path) -> Bool + Returns ``true`` if ``path`` is a socket, ``false`` otherwise. .. function:: issticky(path) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + iswritable(path) -> Bool + + Returns ``true`` if the current user has permission to write to ``path``\ , ``false`` otherwise. .. function:: homedir() -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + homedir() -> AbstractString + Return the current user's home directory. .. function:: dirname(path::AbstractString) -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + dirname(path::AbstractString) -> AbstractString + Get the directory part of a path. .. function:: basename(path::AbstractString) -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + 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 ``. + .. Docstring generated from Julia source + .. code-block:: julia + @__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 ``\ . .. function:: isabspath(path::AbstractString) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isabspath(path::AbstractString) -> Bool + Determines whether a path is absolute (begins at the root directory). .. function:: isdirpath(path::AbstractString) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + abspath(path::AbstractString) -> AbstractString + + Convert a path to an absolute path by adding the current directory if necessary. .. function:: normpath(path::AbstractString) -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + normpath(path::AbstractString) -> AbstractString + Normalize a path, removing "." and ".." entries. .. function:: realpath(path::AbstractString) -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 750c7f7800497b..2bcb3a137ef073 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -21,7 +21,9 @@ General I/O .. function:: open(file_name, [read, write, create, truncate, append]) -> IOStream + .. Docstring generated from Julia source :: + open(command, mode::AbstractString="r", stdio=DevNull) Start running ``command`` asynchronously, and return a tuple @@ -33,6 +35,7 @@ General I/O stream. :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` @@ -41,11 +44,13 @@ General I/O by ``f``. :: + open(file_name, [read, write, create, truncate, append]) -> IOStream Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. :: + open(file_name, [mode]) -> IOStream Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: @@ -60,6 +65,7 @@ General I/O ==== ================================= :: + open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. @@ -68,7 +74,9 @@ General I/O .. function:: open(file_name, [mode]) -> IOStream + .. Docstring generated from Julia source :: + open(command, mode::AbstractString="r", stdio=DevNull) Start running ``command`` asynchronously, and return a tuple @@ -80,6 +88,7 @@ General I/O stream. :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` @@ -88,11 +97,13 @@ General I/O by ``f``. :: + open(file_name, [read, write, create, truncate, append]) -> IOStream Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. :: + open(file_name, [mode]) -> IOStream Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: @@ -107,6 +118,7 @@ General I/O ==== ================================= :: + open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. @@ -115,7 +127,9 @@ General I/O .. function:: open(f::function, args...) + .. Docstring generated from Julia source :: + open(command, mode::AbstractString="r", stdio=DevNull) Start running ``command`` asynchronously, and return a tuple @@ -127,6 +141,7 @@ General I/O stream. :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` @@ -135,11 +150,13 @@ General I/O by ``f``. :: + open(file_name, [read, write, create, truncate, append]) -> IOStream Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. :: + open(file_name, [mode]) -> IOStream Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: @@ -154,6 +171,7 @@ General I/O ==== ================================= :: + open(f::function, args...) Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. @@ -162,118 +180,139 @@ General I/O .. function:: IOBuffer() -> IOBuffer + .. Docstring generated from Julia source + .. code-block:: julia + IOBuffer() -> IOBuffer + Create an in-memory I/O stream. - :: - IOBuffer(size::Int) + .. code-block:: julia + IOBuffer(size::Int) Create a fixed size IOBuffer. The buffer will not grow dynamically. - :: - IOBuffer(string) + .. code-block:: julia + IOBuffer(string) Create a read-only IOBuffer on the data underlying the given string - :: - IOBuffer([data,],[readable,writable,[maxsize]]) + .. code-block:: julia + IOBuffer([data,],[readable,writable,[maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, - they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable - but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. .. function:: IOBuffer(size::Int) - :: - IOBuffer() -> IOBuffer + .. Docstring generated from Julia source + .. code-block:: julia + IOBuffer() -> IOBuffer Create an in-memory I/O stream. - :: - IOBuffer(size::Int) + .. code-block:: julia + IOBuffer(size::Int) Create a fixed size IOBuffer. The buffer will not grow dynamically. - :: - IOBuffer(string) + .. code-block:: julia + IOBuffer(string) Create a read-only IOBuffer on the data underlying the given string - :: - IOBuffer([data,],[readable,writable,[maxsize]]) + .. code-block:: julia + IOBuffer([data,],[readable,writable,[maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, - they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable - but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. .. function:: IOBuffer(string) - :: - IOBuffer() -> IOBuffer + .. Docstring generated from Julia source + .. code-block:: julia + IOBuffer() -> IOBuffer Create an in-memory I/O stream. - :: - IOBuffer(size::Int) + .. code-block:: julia + IOBuffer(size::Int) Create a fixed size IOBuffer. The buffer will not grow dynamically. - :: - IOBuffer(string) + .. code-block:: julia + IOBuffer(string) Create a read-only IOBuffer on the data underlying the given string - :: - IOBuffer([data,],[readable,writable,[maxsize]]) + .. code-block:: julia + IOBuffer([data,],[readable,writable,[maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, - they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable - but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. .. function:: IOBuffer([data,],[readable,writable,[maxsize]]) - :: - IOBuffer() -> IOBuffer + .. Docstring generated from Julia source + .. code-block:: julia + IOBuffer() -> IOBuffer Create an in-memory I/O stream. - :: - IOBuffer(size::Int) + .. code-block:: julia + IOBuffer(size::Int) Create a fixed size IOBuffer. The buffer will not grow dynamically. - :: - IOBuffer(string) + .. code-block:: julia + IOBuffer(string) Create a read-only IOBuffer on the data underlying the given string - :: - IOBuffer([data,],[readable,writable,[maxsize]]) + .. code-block:: julia + IOBuffer([data,],[readable,writable,[maxsize]]) - Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, - they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable - but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. .. function:: takebuf_array(b::IOBuffer) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: flush(stream) + .. Docstring generated from Julia source + .. code-block:: julia + flush(stream) + Commit all currently buffered writes to the given stream. .. function:: close(stream) + .. Docstring generated from Julia source + :: + + close(stream) + Close an I/O stream. Performs a ``flush`` first. :: + close(Channel) Closes a channel. An exception is thrown by: @@ -284,79 +323,124 @@ General I/O .. function:: write(stream, x) + .. Docstring generated from Julia source + .. code-block:: julia + write(stream, x) + Write the canonical binary representation of a value to the given stream. .. function:: read(stream, type) + .. Docstring generated from Julia source + .. code-block:: julia + read(stream, type) + Read a value of the given type from a stream, in canonical binary representation. - :: - read(stream, type, dims) + .. code-block:: julia + read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. .. function:: read(stream, type, dims) - :: - read(stream, type) + .. Docstring generated from Julia source + .. code-block:: julia + read(stream, type) Read a value of the given type from a stream, in canonical binary representation. - :: - read(stream, type, dims) + .. code-block:: julia + read(stream, type, dims) Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. .. function:: read!(stream, array::Array) - Read binary data from a stream, filling in the argument ``array``. + .. Docstring generated from Julia source + .. code-block:: julia + read!(stream, array::Array) + + Read binary data from a stream, filling in the argument ``array``\ . .. function:: readbytes!(stream, b::Vector{UInt8}, nb=length(b); all=true) - Read at most ``nb`` bytes from the stream into ``b``, returning the - number of bytes read (increasing the size of ``b`` as needed). + .. Docstring generated from Julia source + .. code-block:: julia + readbytes!(stream, b::Vector{UInt8}, nb=length(b); all=true) + + Read at most ``nb`` bytes from the stream into ``b``\ , returning the number of bytes read (increasing the size of ``b`` as needed). See ``readbytes`` for a description of the ``all`` option. .. function:: readbytes(stream, nb=typemax(Int); all=true) + .. Docstring generated from Julia source + .. code-block:: julia + readbytes(stream, nb=typemax(Int); all=true) + Read at most ``nb`` bytes from the stream, returning a ``Vector{UInt8}`` of the bytes read. - If ``all`` is true (the default), this function will block repeatedly - trying to read all requested bytes, until an error or end-of-file - occurs. - If ``all`` is false, at most one ``read`` call is performed, and the - amount of data returned is device-dependent. - Note that not all stream types support the ``all`` option. + If ``all`` is true (the default), this function will block repeatedly trying to read all requested bytes, until an error or end-of-file occurs. If ``all`` is false, at most one ``read`` call is performed, and the amount of data returned is device-dependent. Note that not all stream types support the ``all`` option. .. function:: position(s) + .. Docstring generated from Julia source + .. code-block:: julia + position(s) + Get the current position of a stream. .. function:: seek(s, pos) + .. Docstring generated from Julia source + .. code-block:: julia + seek(s, pos) + Seek a stream to the given position. .. function:: seekstart(s) + .. Docstring generated from Julia source + .. code-block:: julia + seekstart(s) + Seek a stream to its beginning. .. function:: seekend(s) + .. Docstring generated from Julia source + .. code-block:: julia + seekend(s) + Seek a stream to its end. .. function:: skip(s, offset) + .. Docstring generated from Julia source + .. code-block:: julia + skip(s, offset) + Seek a stream relative to the current position. .. function:: mark(s) + .. Docstring generated from Julia source + :: + + mark(s) + Add a mark at the current position of stream ``s``. Returns the marked position. See also :func:`unmark`, :func:`reset`, :func:`ismarked` .. function:: unmark(s) + .. Docstring generated from Julia source + :: + + unmark(s) + Remove a mark from stream ``s``. Returns ``true`` if the stream was marked, ``false`` otherwise. @@ -364,6 +448,11 @@ General I/O .. function:: reset(s) + .. Docstring generated from Julia source + :: + + reset(s) + Reset a stream ``s`` to a previously marked position, and remove the mark. Returns the previously marked position. Throws an error if the stream is not marked. @@ -372,599 +461,578 @@ General I/O .. function:: ismarked(s) + .. Docstring generated from Julia source + :: + + ismarked(s) + Returns true if stream ``s`` is marked. See also :func:`mark`, :func:`unmark`, :func:`reset` .. function:: eof(stream) -> Bool - Tests whether an I/O stream is at end-of-file. If the stream is not yet - exhausted, this function will block to wait for more data if necessary, and - then return ``false``. Therefore it is always safe to read one byte after - seeing ``eof`` return ``false``. ``eof`` will return ``false`` as long - as buffered data is still available, even if the remote end of a - connection is closed. + .. Docstring generated from Julia source + .. code-block:: julia + eof(stream) -> Bool + + Tests whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return ``false``\ . Therefore it is always safe to read one byte after seeing ``eof`` return ``false``\ . ``eof`` will return ``false`` as long as buffered data is still available, even if the remote end of a connection is closed. .. function:: isreadonly(stream) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isreadonly(stream) -> Bool + Determine whether a stream is read-only. .. function:: isopen(object) -> Bool - Determine whether an object - such as a stream, timer, or mmap -- is not yet closed. - Once an object is closed, it will never produce a new event. - However, a closed stream may still have data to read in its buffer, - use ``eof`` to check for the ability to read data. - Use ``poll_fd`` to be notified when a stream might be writable or readable. + .. Docstring generated from Julia source + .. code-block:: julia + isopen(object) -> Bool + + Determine whether an object - such as a stream, timer, or mmap – is not yet closed. Once an object is closed, it will never produce a new event. However, a closed stream may still have data to read in its buffer, use ``eof`` to check for the ability to read data. Use ``poll_fd`` to be notified when a stream might be writable or readable. .. function:: serialize(stream, value) - Write an arbitrary value to a stream in an opaque format, such that it can - be read back by ``deserialize``. The read-back value will be as identical as - possible to the original. In general, this process will not work if the - reading and writing are done by different versions of Julia, or - an instance of Julia with a different system image. + .. Docstring generated from Julia source + .. code-block:: julia + serialize(stream, value) + + Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``\ . The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. .. function:: deserialize(stream) - Read a value written by ``serialize``. + .. Docstring generated from Julia source + .. code-block:: julia + deserialize(stream) + + Read a value written by ``serialize``\ . .. function:: print_escaped(io, str::AbstractString, esc::AbstractString) + .. Docstring generated from Julia source + .. code-block:: julia + print_escaped(io, str::AbstractString, esc::AbstractString) + General escaping of traditional C and Unicode escape sequences, plus any characters in esc are also escaped (with a backslash). .. function:: print_unescaped(io, s::AbstractString) + .. Docstring generated from Julia source + :: + + print_unescaped(io, s::AbstractString) + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + print_joined(io, items, delim, [last]) + + Print elements of ``items`` to ``io`` with ``delim`` between them. If ``last`` is specified, it is used as the final delimiter instead of ``delim``\ . .. function:: print_shortest(io, x) - Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number ``x``, ensuring that it would parse to the exact same number. + .. Docstring generated from Julia source + .. code-block:: julia + print_shortest(io, x) + + Print the shortest possible representation, with the minimum number of consecutive non-zero digits, of number ``x``\ , ensuring that it would parse to the exact same number. .. function:: fd(stream) - Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous ``File``'s and ``IOStream``'s - not to any of the asynchronous streams. + .. Docstring generated from Julia source + .. code-block:: julia + fd(stream) + + Returns the file descriptor backing the stream or file. Note that this function only applies to synchronous ``File``\ 's and ``IOStream``\ 's not to any of the asynchronous streams. .. function:: redirect_stdout() - Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) - representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The - wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be - replaced elsewhere. + .. Docstring generated from Julia source + .. code-block:: julia + redirect_stdout() - :: - redirect_stdout(stream) + Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be replaced elsewhere. + + .. code-block:: julia + redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that ``stream`` must be a TTY, a Pipe or a - TcpSocket. + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that ``stream`` must be a TTY, a Pipe or a TcpSocket. .. function:: redirect_stdout(stream) - :: - redirect_stdout() + .. Docstring generated from Julia source + .. code-block:: julia + redirect_stdout() - Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) - representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The - wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be - replaced elsewhere. + Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be replaced elsewhere. - :: - redirect_stdout(stream) + .. code-block:: julia + redirect_stdout(stream) - Replace STDOUT by stream for all C and julia level output to STDOUT. Note that ``stream`` must be a TTY, a Pipe or a - TcpSocket. + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that ``stream`` must be a TTY, a Pipe or a TcpSocket. .. function:: redirect_stderr([stream]) + .. Docstring generated from Julia source + .. code-block:: julia + redirect_stderr([stream]) + Like redirect_stdout, but for STDERR .. function:: redirect_stdin([stream]) - Like redirect_stdout, but for STDIN. Note that the order of the return tuple is still (rd,wr), i.e. data to be read - from STDIN, may be written to wr. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + readchomp(x) + Read the entirety of x as a string but remove trailing newlines. Equivalent to chomp(readall(x)). .. function:: truncate(file,n) - Resize the file or buffer given by the first argument to exactly ``n`` bytes, filling previously unallocated space with '\\0' - if the file or buffer is grown + .. Docstring generated from Julia source + .. code-block:: julia + truncate(file,n) + + Resize the file or buffer given by the first argument to exactly ``n`` bytes, filling previously unallocated space with '\\0' if the file or buffer is grown .. function:: skipchars(stream, predicate; linecomment::Char) + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: countlines(io,[eol::Char]) - Read ``io`` until the end of the stream/file and count the number of 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. + .. Docstring generated from Julia source + .. code-block:: julia + countlines(io,[eol::Char]) + + Read ``io`` until the end of the stream/file and count the number of 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() + .. Docstring generated from Julia source + .. code-block:: julia + PipeBuffer() + An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. - :: - PipeBuffer(data::Vector{UInt8},[maxsize]) + .. code-block:: julia + 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() + .. Docstring generated from Julia source + .. code-block:: julia + PipeBuffer() An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. - :: - PipeBuffer(data::Vector{UInt8},[maxsize]) + .. code-block:: julia + PipeBuffer(data::Vector{UInt8},[maxsize]) Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. .. function:: readavailable(stream) - Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``. + .. Docstring generated from Julia source + .. code-block:: julia + readavailable(stream) + + Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``\ . Text I/O -------- .. function:: show(x) - Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. - The representation used by ``show`` generally includes Julia-specific formatting and type information. + .. Docstring generated from Julia source + .. code-block:: julia + show(x) + + Write an informative text representation of a value to the current output stream. New types should overload ``show(io, x)`` where the first argument is a stream. The representation used by ``show`` generally includes Julia-specific formatting and type information. .. function:: showcompact(x) - Show a more compact representation of a value. This is used for printing - array elements. If a new type has a different compact representation, it - should overload ``showcompact(io, x)`` where the first argument is a stream. + .. Docstring generated from Julia source + .. code-block:: julia + showcompact(x) + + Show a more compact representation of a value. This is used for printing array elements. If a new type has a different compact representation, it should overload ``showcompact(io, x)`` where the first argument is a stream. .. function:: showall(x) - Similar to ``show``, except shows all elements of arrays. + .. Docstring generated from Julia source + .. code-block:: julia + showall(x) + + Similar to ``show``\ , except shows all elements of arrays. .. function:: summary(x) - Return a string giving a brief description of a value. By default returns - ``string(typeof(x))``. For arrays, returns strings like "2x2 Float64 Array". + .. Docstring generated from Julia source + .. code-block:: julia + 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". .. function:: print(x) - Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call ``show``. - The representation used by ``print`` includes minimal formatting and tries to avoid Julia-specific details. + .. Docstring generated from Julia source + .. code-block:: julia + print(x) + + Write (to the default output stream) a canonical (un-decorated) text representation of a value if there is one, otherwise call ``show``\ . The representation used by ``print`` includes minimal formatting and tries to avoid Julia-specific details. .. function:: println(x) + .. Docstring generated from Julia source + :: + + println(x) + Print (using :func:`print`) ``x`` followed by a newline. .. function:: print_with_color(color::Symbol, [io], strings...) - Print strings in a color specified as a symbol, for example ``:red`` or ``:blue``. + .. Docstring generated from Julia source + .. code-block:: julia + print_with_color(color::Symbol, [io], strings...) + + Print strings in a color specified as a symbol, for example ``:red`` or ``:blue``\ . .. function:: info(msg) + .. Docstring generated from Julia source + .. code-block:: julia + info(msg) + Display an informational message. .. function:: warn(msg) + .. Docstring generated from Julia source + .. code-block:: julia + warn(msg) + Display a warning. .. function:: @printf([io::IOStream], "%Fmt", args...) + .. Docstring generated from Julia source + .. code-block:: julia + @printf([io::IOStream], "%Fmt", args...) + Print arg(s) using C ``printf()`` style format specification string. Optionally, an IOStream may be passed as the first argument to redirect output. .. function:: @sprintf("%Fmt", args...) - Return ``@printf`` formatted output as string. - julia> s = @sprintf "this is a %s %15.1f" "test" 34.567; + .. Docstring generated from Julia source + .. code-block:: julia + @sprintf("%Fmt", args...) + + Return ``@printf`` formatted output as string. julia> s = @sprintf "this is a %s %15.1f" "test" 34.567; - julia> println(s) - this is a test 34.6 + julia> println(s) this is a test 34.6 .. function:: sprint(f::Function, args...) - Call the given function with an I/O stream and the supplied extra arguments. - Everything written to this I/O stream is returned as a string. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + showerror(io, e) + Show a descriptive representation of an exception object. .. function:: dump(x) + .. Docstring generated from Julia source + .. code-block:: julia + dump(x) + Show all user-visible structure of a value. .. function:: xdump(x) + .. Docstring generated from Julia source + .. code-block:: julia + xdump(x) + Show all structure of a value, including all fields of objects. .. function:: readall(stream::IO) + .. Docstring generated from Julia source + .. code-block:: julia + readall(stream::IO) + Read the entire contents of an I/O stream as a string. - :: - readall(filename::AbstractString) + .. code-block:: julia + readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. - Equivalent to ``open(readall, filename)``. + Open ``filename``\ , read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``\ . .. function:: readall(filename::AbstractString) - :: - readall(stream::IO) + .. Docstring generated from Julia source + .. code-block:: julia + readall(stream::IO) Read the entire contents of an I/O stream as a string. - :: - readall(filename::AbstractString) + .. code-block:: julia + readall(filename::AbstractString) - Open ``filename``, read the entire contents as a string, then close the file. - Equivalent to ``open(readall, filename)``. + Open ``filename``\ , read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``\ . .. function:: readline(stream=STDIN) - Read a single line of text, including a trailing newline character (if one is reached before the end of the input), from the given ``stream`` (defaults to ``STDIN``), + .. Docstring generated from Julia source + .. code-block:: julia + readline(stream=STDIN) + + Read a single line of text, including a trailing newline character (if one is reached before the end of the input), from the given ``stream`` (defaults to ``STDIN``\ ), .. function:: readuntil(stream, delim) + .. Docstring generated from Julia source + .. code-block:: julia + readuntil(stream, delim) + Read a string, up to and including the given delimiter byte. .. function:: readlines(stream) + .. Docstring generated from Julia source + .. code-block:: julia + readlines(stream) + Read all lines as an array. .. function:: eachline(stream) + .. Docstring generated from Julia source + .. code-block:: julia + eachline(stream) + Create an iterable object that will yield each line from a stream. .. function:: readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. - - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. - - Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. + .. Docstring generated from Julia source + .. code-block:: julia + 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='#') - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. + Read a matrix from the source where each line (separated by ``eol``\ ) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``\ , ``AbstractString``\ , and ``Any``\ . - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + If ``header`` is ``true``\ , the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``\ . - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. - - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. - - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. - - :: - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as ``\n``. - - :: - readdlm(source, delim::Char; options...) + Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - 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. + If ``skipblanks`` is ``true``\ , blank lines in the input will be ignored. - :: - readdlm(source, T::Type; options...) + 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. - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + 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. - :: - 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. + If ``quotes`` is ``true``\ , column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying``\ dims``as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If``\ comments``is``\ true``, lines beginning with``\ comment_char``and text following``\ comment_char``in any line are ignored. :: readdlm(source, delim::Char, eol::Char; options...) If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, delim::Char, T::Type; options...) The end of line delimiter is taken as``\ n``. :: readdlm(source, delim::Char; options...) The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, T::Type; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. :: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: readdlm(source, delim::Char, eol::Char; options...) - :: - 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='#') + .. Docstring generated from Julia source + .. code-block:: julia + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + Read a matrix from the source where each line (separated by ``eol``\ ) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``\ , ``AbstractString``\ , and ``Any``\ . - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + If ``header`` is ``true``\ , the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``\ . Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. - - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. - - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. - - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. - - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. - - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. - - :: - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as ``\n``. - - :: - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, T::Type; options...) + If ``skipblanks`` is ``true``\ , blank lines in the input will be ignored. - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + 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. - :: - readdlm(source; options...) + 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. - 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. + If ``quotes`` is ``true``\ , column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying``\ dims``as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If``\ comments``is``\ true``, lines beginning with``\ comment_char``and text following``\ comment_char``in any line are ignored. :: readdlm(source, delim::Char, eol::Char; options...) If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, delim::Char, T::Type; options...) The end of line delimiter is taken as``\ n``. :: readdlm(source, delim::Char; options...) The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, T::Type; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. :: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: readdlm(source, delim::Char, T::Type; options...) - :: - 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='#') + .. Docstring generated from Julia source + .. code-block:: julia + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + Read a matrix from the source where each line (separated by ``eol``\ ) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``\ , ``AbstractString``\ , and ``Any``\ . - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + If ``header`` is ``true``\ , the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``\ . Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. - - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. - - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. - - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. - - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. - - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. - - :: - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as ``\n``. - - :: - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, T::Type; options...) + If ``skipblanks`` is ``true``\ , blank lines in the input will be ignored. - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + 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. - :: - readdlm(source; options...) + 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. - 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. + If ``quotes`` is ``true``\ , column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying``\ dims``as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If``\ comments``is``\ true``, lines beginning with``\ comment_char``and text following``\ comment_char``in any line are ignored. :: readdlm(source, delim::Char, eol::Char; options...) If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, delim::Char, T::Type; options...) The end of line delimiter is taken as``\ n``. :: readdlm(source, delim::Char; options...) The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, T::Type; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. :: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: readdlm(source, delim::Char; options...) - :: - 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='#') + .. Docstring generated from Julia source + .. code-block:: julia + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + Read a matrix from the source where each line (separated by ``eol``\ ) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``\ , ``AbstractString``\ , and ``Any``\ . - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + If ``header`` is ``true``\ , the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``\ . Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. - - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. - - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + If ``skipblanks`` is ``true``\ , blank lines in the input will be ignored. - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + If ``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. - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + If ``ignore_invalid_chars`` is ``true``\ , bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. - - :: - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as ``\n``. - - :: - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. - - :: - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + If ``quotes`` is ``true``\ , column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying``\ dims``as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If``\ comments``is``\ true``, lines beginning with``\ comment_char``and text following``\ comment_char``in any line are ignored. :: readdlm(source, delim::Char, eol::Char; options...) If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, delim::Char, T::Type; options...) The end of line delimiter is taken as``\ n``. :: readdlm(source, delim::Char; options...) The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, T::Type; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. :: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: readdlm(source, T::Type; options...) - :: - 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='#') + .. Docstring generated from Julia source + .. code-block:: julia + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + Read a matrix from the source where each line (separated by ``eol``\ ) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``\ , ``AbstractString``\ , and ``Any``\ . - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + If ``header`` is ``true``\ , the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``\ . Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. - - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. - - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + If ``skipblanks`` is ``true``\ , blank lines in the input will be ignored. - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + If ``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. - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + If ``ignore_invalid_chars`` is ``true``\ , bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. - - :: - readdlm(source, delim::Char, eol::Char; options...) - - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as ``\n``. - - :: - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. - - :: - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + If ``quotes`` is ``true``\ , column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying``\ dims``as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If``\ comments``is``\ true``, lines beginning with``\ comment_char``and text following``\ comment_char``in any line are ignored. :: readdlm(source, delim::Char, eol::Char; options...) If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, delim::Char, T::Type; options...) The end of line delimiter is taken as``\ n``. :: readdlm(source, delim::Char; options...) The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, T::Type; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. :: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: readdlm(source; options...) - :: - 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='#') + .. Docstring generated from Julia source + .. code-block:: julia + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') - Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + Read a matrix from the source where each line (separated by ``eol``\ ) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. - If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``\ , ``AbstractString``\ , and ``Any``\ . - If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + If ``header`` is ``true``\ , the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``\ . Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. - If ``skipblanks`` is ``true``, blank lines in the input will be ignored. - - If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + If ``skipblanks`` is ``true``\ , blank lines in the input will be ignored. - If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + If ``use_mmap`` is ``true``\ , the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. - If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. - - Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. - - If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. - - :: - readdlm(source, delim::Char, eol::Char; options...) + If ``ignore_invalid_chars`` is ``true``\ , bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. - If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, delim::Char, T::Type; options...) - - The end of line delimiter is taken as ``\n``. - - :: - readdlm(source, delim::Char; options...) - - The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. - - :: - readdlm(source, T::Type; options...) - - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. - - :: - readdlm(source; options...) - - The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + If ``quotes`` is ``true``\ , column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. Specifying``\ dims``as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. If``\ comments``is``\ true``, lines beginning with``\ comment_char``and text following``\ comment_char``in any line are ignored. :: readdlm(source, delim::Char, eol::Char; options...) If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, delim::Char, T::Type; options...) The end of line delimiter is taken as``\ n``. :: readdlm(source, delim::Char; options...) The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. :: readdlm(source, T::Type; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. :: readdlm(source; options...) The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as``\ n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: 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``). + .. Docstring generated from Julia source + .. code-block:: julia + writedlm(f, A, delim='\\t') - 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))``. + Write ``A`` (a vector, matrix or an iterable collection of iterable rows) as text to ``f`` (either a filename string or an ``IO`` stream) using the given delimeter ``delim`` (which defaults to tab, but can be any printable Julia object, typically a ``Char`` or ``AbstractString``\ ). + + For example, two vectors ``x`` and ``y`` of the same length can be written as two columns of tab-delimited text to ``f`` by either ``writedlm(f, [x y])`` or by ``writedlm(f, zip(x, y))``\ . .. function:: readcsv(source, [T::Type]; options...) + .. Docstring generated from Julia source + .. code-block:: julia + readcsv(source, [T::Type]; options...) + Equivalent to ``readdlm`` with ``delim`` set to comma. .. function:: writecsv(filename, A) + .. Docstring generated from Julia source + .. code-block:: julia + writecsv(filename, A) + Equivalent to ``writedlm`` with ``delim`` set to comma. .. function:: Base64EncodePipe(ostream) - Returns a new write-only I/O stream, which converts any bytes written - to it into base64-encoded ASCII bytes written to ``ostream``. Calling - ``close`` on the ``Base64Pipe`` stream is necessary to complete the - encoding (but does not close ``ostream``). + .. Docstring generated from Julia source + .. code-block:: julia + Base64EncodePipe(ostream) + + Returns a new write-only I/O stream, which converts any bytes written to it into base64-encoded ASCII bytes written to ``ostream``\ . Calling ``close`` on the ``Base64Pipe`` stream is necessary to complete the encoding (but does not close ``ostream``\ ). .. function:: Base64DecodePipe(istream) - Returns a new read-only I/O stream, which decodes base64-encoded data - read from ``istream``. + .. Docstring generated from Julia source + .. code-block:: julia + Base64DecodePipe(istream) + + Returns a new read-only I/O stream, which decodes base64-encoded data read from ``istream``\ . .. function:: base64encode(writefunc, args...) - :: - base64encode(args...) + .. Docstring generated from Julia source + .. code-block:: julia + base64encode(writefunc, args...) + base64encode(args...) - Given a ``write``-like function ``writefunc``, which takes an I/O - stream as its first argument, ``base64(writefunc, args...)`` - calls ``writefunc`` to write ``args...`` to a base64-encoded string, - and returns the string. ``base64(args...)`` is equivalent to - ``base64(write, args...)``: it converts its arguments into bytes - using the standard ``write`` functions and returns the base64-encoded - string. + Given a ``write``\ -like function ``writefunc``\ , which takes an I/O stream as its first argument, ``base64(writefunc, args...)`` calls ``writefunc`` to write ``args...`` to a base64-encoded string, and returns the string. ``base64(args...)`` is equivalent to ``base64(write, args...)``\ : it converts its arguments into bytes using the standard ``write`` functions and returns the base64-encoded string. .. function:: base64decode(string) - Decodes the base64-encoded ``string`` and returns a ``Vector{UInt8}`` - of the decoded bytes. + .. Docstring generated from Julia source + .. code-block:: julia + base64decode(string) + + Decodes the base64-encoded ``string`` and returns a ``Vector{UInt8}`` of the decoded bytes. Multimedia I/O -------------- @@ -989,103 +1057,74 @@ 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). + .. Docstring generated from Julia source + .. code-block:: julia + 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:: redisplay(x) - :: - redisplay(d::Display, x) - redisplay(mime, x) - redisplay(d::Display, mime, x) + .. Docstring generated from Julia source + .. code-block:: julia + redisplay(x) + redisplay(d::Display, x) + redisplay(mime, x) + redisplay(d::Display, mime, x) - By default, the ``redisplay`` functions simply call ``display``. However, - some display backends may override ``redisplay`` to modify an existing - display of ``x`` (if any). Using ``redisplay`` is also a hint to the - backend that ``x`` may be redisplayed several times, and the backend - may choose to defer the display until (for example) the next interactive - prompt. + By default, the ``redisplay`` functions simply call ``display``\ . However, some display backends may override ``redisplay`` to modify an existing display of ``x`` (if any). Using ``redisplay`` is also a hint to the backend that ``x`` may be redisplayed several times, and the backend may choose to defer the display until (for example) the next interactive prompt. .. function:: displayable(mime) -> Bool - :: - displayable(d::Display, mime) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + displayable(mime) -> Bool + displayable(d::Display, mime) -> Bool - Returns a boolean value indicating whether the given ``mime`` type (string) - is displayable by any of the displays in the current display stack, or - specifically by the display ``d`` in the second variant. + Returns a boolean value indicating whether the given ``mime`` type (string) is displayable by any of the displays in the current display stack, or specifically by the display ``d`` in the second variant. .. function:: writemime(stream, mime, x) - The ``display`` functions ultimately call ``writemime`` in order to - write an object ``x`` as a given ``mime`` type to a given I/O - ``stream`` (usually a memory buffer), if possible. In order to - provide a rich multimedia representation of a user-defined type - ``T``, it is only necessary to define a new ``writemime`` method for - ``T``, via: ``writemime(stream, ::MIME"mime", x::T) = ...``, where - ``mime`` is a MIME-type string and the function body calls - ``write`` (or similar) to write that representation of ``x`` to - ``stream``. (Note that the ``MIME""`` notation only supports literal - strings; to construct ``MIME`` types in a more flexible manner use - ``MIME{symbol("")}``.) - - For example, if you define a ``MyImage`` type and know how to write - it to a PNG file, you could define a function ``writemime(stream, - ::MIME"image/png", x::MyImage) = ...`` to allow your images to - be displayed on any PNG-capable ``Display`` (such as IJulia). - As usual, be sure to ``import Base.writemime`` in order to add - new methods to the built-in Julia function ``writemime``. - - Technically, the ``MIME"mime"`` macro defines a singleton type for - the given ``mime`` string, which allows us to exploit Julia's - dispatch mechanisms in determining how to display objects of any - given type. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: mimewritable(mime, x) - Returns a boolean value indicating whether or not the object ``x`` - can be written as the given ``mime`` type. (By default, this - is determined automatically by the existence of the corresponding - ``writemime`` function for ``typeof(x)``.) + .. Docstring generated from Julia source + .. code-block:: julia + mimewritable(mime, x) + + Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding ``writemime`` function for ``typeof(x)``\ .) .. function:: reprmime(mime, x) - Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the - representation of ``x`` in the requested ``mime`` type, as written - by ``writemime`` (throwing a ``MethodError`` if no appropriate - ``writemime`` is available). An ``AbstractString`` is returned for MIME - types with textual representations (such as ``"text/html"`` or - ``"application/postscript"``), whereas binary data is returned as - ``Vector{UInt8}``. (The function ``istext(mime)`` returns whether - or not Julia treats a given ``mime`` type as text.) + .. Docstring generated from Julia source + .. code-block:: julia + reprmime(mime, x) + + Returns an ``AbstractString`` or ``Vector{UInt8}`` containing the representation of ``x`` in the requested ``mime`` type, as written by ``writemime`` (throwing a ``MethodError`` if no appropriate ``writemime`` is available). An ``AbstractString`` is returned for MIME types with textual representations (such as ``"text/html"`` or ``"application/postscript"``\ ), whereas binary data is returned as ``Vector{UInt8}``\ . (The function ``istext(mime)`` returns whether or not Julia treats a given ``mime`` type as text.) - As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) - or a ``Vector{UInt8}`` (for binary MIME types), the ``reprmime`` function - assumes that ``x`` is already in the requested ``mime`` format and - simply returns ``x``. + As a special case, if ``x`` is an ``AbstractString`` (for textual MIME types) or a ``Vector{UInt8}`` (for binary MIME types), the ``reprmime`` function assumes that ``x`` is already in the requested ``mime`` format and simply returns ``x``\ . .. function:: stringmime(mime, x) - Returns an ``AbstractString`` containing the representation of ``x`` in the - requested ``mime`` type. This is similar to ``reprmime`` except - that binary data is base64-encoded as an ASCII string. + .. Docstring generated from Julia source + .. code-block:: julia + stringmime(mime, x) + + Returns an ``AbstractString`` containing the representation of ``x`` in the requested ``mime`` type. This is similar to ``reprmime`` except that binary data is base64-encoded as an ASCII string. As mentioned above, one can also define new display backends. For example, a module that can display PNG images in a window can register @@ -1115,27 +1154,36 @@ stack with: .. function:: pushdisplay(d::Display) - Pushes a new display ``d`` on top of the global display-backend - stack. Calling ``display(x)`` or ``display(mime, x)`` will display - ``x`` on the topmost compatible backend in the stack (i.e., the - topmost backend that does not throw a ``MethodError``). + .. Docstring generated from Julia source + .. code-block:: julia + pushdisplay(d::Display) + + Pushes a new display ``d`` on top of the global display-backend stack. Calling ``display(x)`` or ``display(mime, x)`` will display ``x`` on the topmost compatible backend in the stack (i.e., the topmost backend that does not throw a ``MethodError``\ ). .. function:: popdisplay() - popdisplay(d::Display) + .. Docstring generated from Julia source + .. code-block:: julia + popdisplay() - Pop the topmost backend off of the display-backend stack, or the - topmost copy of ``d`` in the second variant. + popdisplay(d::Display) + + Pop the topmost backend off of the display-backend stack, or the topmost copy of ``d`` in the second variant. .. function:: TextDisplay(stream) - Returns a ``TextDisplay <: Display``, which can display any object - as the text/plain MIME type (only), writing the text representation - to the given I/O stream. (The text representation is the same - as the way an object is printed in the Julia REPL.) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + istext(m::MIME) + Determine whether a MIME type is text data. Memory-mapped I/O @@ -1143,11 +1191,18 @@ Memory-mapped I/O .. function:: Mmap.Anonymous(name, readonly, create) - Create an ``IO``-like object for creating zeroed-out mmapped-memory that is not tied to a file for use in ``Mmap.mmap``. Used by ``SharedArray`` for creating shared memory arrays. + .. Docstring generated from Julia source + .. code-block:: julia + Mmap.Anonymous(name, readonly, create) + + Create an ``IO``\ -like object for creating zeroed-out mmapped-memory that is not tied to a file for use in ``Mmap.mmap``\ . Used by ``SharedArray`` for creating shared memory arrays. .. function:: Mmap.mmap(io::Union{IOStream,AbstractString,Mmap.AnonymousMmap}[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true) + .. Docstring generated from Julia source :: + + Mmap.mmap(io::Union{IOStream,AbstractString,Mmap.AnonymousMmap}[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true) Mmap.mmap(type::Type{Array{T,N}}, dims) 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. @@ -1190,6 +1245,7 @@ Memory-mapped I/O A more portable file would need to encode the word size---32 bit or 64 bit---and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). :: + Mmap.mmap(io, BitArray, [dims, offset]) Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as :func:`mmap`, but the byte representation is different. @@ -1200,7 +1256,9 @@ Memory-mapped I/O .. function:: Mmap.mmap(io, BitArray, [dims, offset]) + .. Docstring generated from Julia source :: + Mmap.mmap(io::Union{IOStream,AbstractString,Mmap.AnonymousMmap}[, type::Type{Array{T,N}}, dims, offset]; grow::Bool=true, shared::Bool=true) Mmap.mmap(type::Type{Array{T,N}}, dims) @@ -1244,6 +1302,7 @@ Memory-mapped I/O A more portable file would need to encode the word size---32 bit or 64 bit---and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). :: + Mmap.mmap(io, BitArray, [dims, offset]) Create a ``BitArray`` whose values are linked to a file, using memory-mapping; it has the same purpose, works in the same way, and has the same arguments, as :func:`mmap`, but the byte representation is different. @@ -1254,6 +1313,10 @@ Memory-mapped I/O .. function:: Mmap.sync!(array) + .. Docstring generated from Julia source + .. code-block:: julia + Mmap.sync!(array) + Forces synchronization between the in-memory version of a memory-mapped ``Array`` or ``BitArray`` and the on-disk version. Network I/O @@ -1261,165 +1324,229 @@ Network I/O .. function:: connect([host],port) -> TcpSocket + .. Docstring generated from Julia source + .. code-block:: julia + connect([host],port) -> TcpSocket + Connect to the host ``host`` on port ``port`` - :: - connect(path) -> Pipe + .. code-block:: julia + connect(path) -> Pipe Connect to the Named Pipe/Domain Socket at ``path`` - :: - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + .. code-block:: julia + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, - specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read - off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation - must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` - sets up TCP/IP socket connections in-between workers. + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``\ , specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off ``instrm``\ , while messages to be sent to ``pid`` will be written to ``outstrm``\ . The custom transport implementation must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` sets up TCP/IP socket connections in-between workers. .. function:: connect(path) -> Pipe - :: - connect([host],port) -> TcpSocket + .. Docstring generated from Julia source + .. code-block:: julia + connect([host],port) -> TcpSocket Connect to the host ``host`` on port ``port`` - :: - connect(path) -> Pipe + .. code-block:: julia + connect(path) -> Pipe Connect to the Named Pipe/Domain Socket at ``path`` - :: - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + .. code-block:: julia + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, - specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read - off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation - must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` - sets up TCP/IP socket connections in-between workers. + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``\ , specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off ``instrm``\ , while messages to be sent to ``pid`` will be written to ``outstrm``\ . The custom transport implementation must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` sets up TCP/IP socket connections in-between workers. .. function:: listen([addr,]port) -> TcpServer - Listen on port on the address specified by ``addr``. By default this listens on localhost only. - To listen on all interfaces pass ``IPv4(0)`` or ``IPv6(0)`` as appropriate. + .. Docstring generated from Julia source + .. code-block:: julia + listen([addr,]port) -> TcpServer - :: - listen(path) -> PipeServer + Listen on port on the address specified by ``addr``\ . By default this listens on localhost only. To listen on all interfaces pass ``IPv4(0)`` or ``IPv6(0)`` as appropriate. + + .. code-block:: julia + listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket .. function:: listen(path) -> PipeServer - :: - listen([addr,]port) -> TcpServer + .. Docstring generated from Julia source + .. code-block:: julia + listen([addr,]port) -> TcpServer - Listen on port on the address specified by ``addr``. By default this listens on localhost only. - To listen on all interfaces pass ``IPv4(0)`` or ``IPv6(0)`` as appropriate. + Listen on port on the address specified by ``addr``\ . By default this listens on localhost only. To listen on all interfaces pass ``IPv4(0)`` or ``IPv6(0)`` as appropriate. - :: - listen(path) -> PipeServer + .. code-block:: julia + listen(path) -> PipeServer Listens on/Creates a Named Pipe/Domain Socket .. function:: getaddrinfo(host) + .. Docstring generated from Julia source + .. code-block:: julia + getaddrinfo(host) + Gets the IP address of the ``host`` (may have to do a DNS lookup) .. function:: parseip(addr) + .. Docstring generated from Julia source + .. code-block:: julia + parseip(addr) + Parse a string specifying an IPv4 or IPv6 ip address. .. function:: IPv4(host::Integer) -> IPv4 + .. Docstring generated from Julia source + .. code-block:: julia + IPv4(host::Integer) -> IPv4 + Returns IPv4 object from ip address formatted as Integer .. function:: IPv6(host::Integer) -> IPv6 + .. Docstring generated from Julia source + .. code-block:: julia + IPv6(host::Integer) -> IPv6 + Returns IPv6 object from ip address formatted as Integer .. function:: nb_available(stream) + .. Docstring generated from Julia source + .. code-block:: julia + nb_available(stream) + Returns the number of bytes available for reading before a read from this stream or buffer will block. .. function:: accept(server[,client]) - Accepts a connection on the given server and returns a connection to the client. An uninitialized client - stream may be provided, in which case it will be used instead of creating a new stream. + .. Docstring generated from Julia source + .. code-block:: julia + accept(server[,client]) + + Accepts a connection on the given server and returns a connection to the client. An uninitialized client stream may be provided, in which case it will be used instead of creating a new stream. .. function:: listenany(port_hint) -> (UInt16,TcpServer) - Create a TcpServer on any port, using hint as a starting point. Returns a tuple of the actual port that the server - was created on and the server itself. + .. Docstring generated from Julia source + .. code-block:: julia + 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:: poll_fd(fd, timeout_s::Real; readable=false, writable=false) + .. Docstring generated from Julia source + .. code-block:: julia + poll_fd(fd, timeout_s::Real; readable=false, writable=false) + Monitor a file descriptor ``fd`` for changes in the read or write availability, and with a timeout given by ``timeout_s`` seconds. The keyword arguments determine which of read and/or write status should be monitored; at least one of them must be set to true. - The returned value is an object with boolean fields ``readable``, ``writable``, and - ``timedout``, giving the result of the polling. + The returned value is an object with boolean fields ``readable``\ , ``writable``\ , and ``timedout``\ , giving the result of the polling. .. function:: poll_file(path, interval_s::Real, timeout_s::Real) -> (previous::StatStruct, current::StatStruct) - Monitor a file for changes by polling every ``interval_s`` seconds until a change occurs or ``timeout_s`` seconds have elapsed. - The ``interval_s`` should be a long period; the default is 5.007 seconds. + .. Docstring generated from Julia source + .. code-block:: julia + poll_file(path, interval_s::Real, timeout_s::Real) -> (previous::StatStruct, current::StatStruct) + + Monitor a file for changes by polling every ``interval_s`` seconds until a change occurs or ``timeout_s`` seconds have elapsed. The ``interval_s`` should be a long period; the default is 5.007 seconds. Returns a pair of ``StatStruct`` objects ``(previous, current)`` when a change is detected. - To determine when a file was modified, compare ``mtime(prev) != mtime(current)`` to detect notification of changes. - However, using ``watch_file`` for this operation is preferred, since it is more reliable and efficient, - although in some situations it may not be available. + To determine when a file was modified, compare ``mtime(prev) != mtime(current)`` to detect notification of changes. However, using ``watch_file`` for this operation is preferred, since it is more reliable and efficient, although in some situations it may not be available. .. function:: watch_file(path, timeout_s::Real) + .. Docstring generated from Julia source + .. code-block:: julia + watch_file(path, timeout_s::Real) + Watch file or directory ``s`` for changes until a change occurs or ``timeout_s`` seconds have elapsed. - The returned value is an object with boolean fields ``changed``, ``renamed``, - and ``timedout``, giving the result of watching the file. + The returned value is an object with boolean fields ``changed``\ , ``renamed``\ , and ``timedout``\ , giving the result of watching the file. - This behavior of this function varies slightly across platforms. - See https://nodejs.org/api/fs.html#fs_caveats for more detailed information. + This behavior of this function varies slightly across platforms. See for more detailed information. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + bind(socket::Union{UDPSocket, TCPSocket}, host::IPv4, port::Integer) + + Bind ``socket`` to the given ``host:port``\ . Note that ``0.0.0.0`` will listen on all devices. .. function:: send(socket::UDPSocket, host::IPv4, port::Integer, msg) - Send ``msg`` over ``socket`` to ``host:port``. + .. Docstring generated from Julia source + .. code-block:: julia + send(socket::UDPSocket, host::IPv4, port::Integer, msg) + + Send ``msg`` over ``socket`` to ``host:port``\ . .. function:: recv(socket::UDPSocket) + .. Docstring generated from Julia source + .. code-block:: julia + recv(socket::UDPSocket) + Read a UDP packet from the specified socket, and return the bytes received. This call blocks. .. function:: recvfrom(socket::UDPSocket) -> (address, data) - Read a UDP packet from the specified socket, returning a tuple of (address, data), where address will be either IPv4 or IPv6 as appropriate. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) - Set UDP socket options. ``multicast_loop``: loopback for multicast packets (default: true). ``multicast_ttl``: TTL for multicast packets. ``enable_broadcast``: flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). ``ttl``: Time-to-live of packets sent on the socket. + .. Docstring generated from Julia source + .. code-block:: julia + setopt(sock::UDPSocket; multicast_loop = nothing, multicast_ttl=nothing, enable_broadcast=nothing, ttl=nothing) + + Set UDP socket options. ``multicast_loop``\ : loopback for multicast packets (default: true). ``multicast_ttl``\ : TTL for multicast packets. ``enable_broadcast``\ : flag must be set to true if socket will be used for broadcast messages, or else the UDP system will return an access error (default: false). ``ttl``\ : Time-to-live of packets sent on the socket. .. function:: ntoh(x) - Converts the endianness of a value from Network byte order (big-endian) to - that used by the Host. + .. Docstring generated from Julia source + .. code-block:: julia + ntoh(x) + + Converts the endianness of a value from Network byte order (big-endian) to that used by the Host. .. function:: hton(x) - Converts the endianness of a value from that used by the Host to Network - byte order (big-endian). + .. Docstring generated from Julia source + .. code-block:: julia + hton(x) + + Converts the endianness of a value from that used by the Host to Network byte order (big-endian). .. function:: ltoh(x) - Converts the endianness of a value from Little-endian to that used by the - Host. + .. Docstring generated from Julia source + .. code-block:: julia + ltoh(x) + + Converts the endianness of a value from Little-endian to that used by the Host. .. function:: htol(x) - Converts the endianness of a value from that used by the Host to - Little-endian. + .. Docstring generated from Julia source + .. code-block:: julia + htol(x) + + Converts the endianness of a value from that used by the Host to Little-endian. .. data:: ENDIAN_BOM diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index 11f28895c713d3..1aa620e546b345 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -6,36 +6,54 @@ .. function:: malloc(size::Integer) -> Ptr{Void} + .. Docstring generated from Julia source + .. code-block:: julia + malloc(size::Integer) -> Ptr{Void} + Call ``malloc`` from the C standard library. .. function:: calloc(num::Integer, size::Integer) -> Ptr{Void} + .. Docstring generated from Julia source + .. code-block:: julia + calloc(num::Integer, size::Integer) -> Ptr{Void} + Call ``calloc`` from the C standard library. .. function:: realloc(addr::Ptr, size::Integer) -> Ptr{Void} + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + errno([code]) - 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. + Get the value of the C library's ``errno``\ . If an argument is specified, it is used to set the value of ``errno``\ . + + The value of ``errno`` is only valid immediately after a ``ccall`` to a C library routine that sets it. Specifically, you cannot call ``errno`` at the next prompt in a REPL, because lots of code is executed between prompts. .. function:: strerror(n=errno()) + .. Docstring generated from Julia source + .. code-block:: julia + strerror(n=errno()) + Convert a system call error code to a descriptive string .. function:: GetLastError() @@ -48,30 +66,51 @@ .. function:: time(t::TmStruct) - :: - time() + .. Docstring generated from Julia source + .. code-block:: julia + time() Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: strptime([format], timestr) + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: flush_cstdio() - Flushes the C ``stdout`` and ``stderr`` streams (which may have been - written to by external C code). + .. Docstring generated from Julia source + .. code-block:: julia + flush_cstdio() + + Flushes the C ``stdout`` and ``stderr`` streams (which may have been written to by external C code). .. function:: msync(ptr, len, [flags]) + .. Docstring generated from Julia source + :: + + msync(ptr, len, [flags]) + Forces synchronization of the :func:`mmap`\ ped memory region from ``ptr`` to ``ptr+len``. Flags defaults to ``MS_SYNC``, but can be a combination of ``MS_ASYNC``, ``MS_SYNC``, or ``MS_INVALIDATE``. See your platform man page for specifics. The flags argument is not valid on Windows. You may not need to call ``msync``, because synchronization is performed at intervals automatically by the operating system. However, you can call this directly if, for example, you are concerned about losing the result of a long-running calculation. diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index 2f72a539a89c7e..074219d2345011 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -6,25 +6,21 @@ .. function:: dlopen(libfile::AbstractString [, flags::Integer]) + .. Docstring generated from Julia source + .. code-block:: julia + 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 flags are platform specific. On MacOS the default ``dlopen`` flags are - ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL`` while on other platforms the - defaults are ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL``. An important usage - of these flags is to specify non default behavior for when the dynamic library loader - binds library references to exported symbols and if the bound references are put into - process local or global scope. For instance ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL`` - allows the library's symbols to be available for usage in other shared libraries, addressing - situations where there are dependencies between shared libraries. + The optional flags argument is a bitwise-or of zero or more of ``RTLD_LOCAL``\ , ``RTLD_GLOBAL``\ , ``RTLD_LAZY``\ , ``RTLD_NOW``\ , ``RTLD_NODELETE``\ , ``RTLD_NOLOAD``\ , ``RTLD_DEEPBIND``\ , and ``RTLD_FIRST``\ . These are converted to the corresponding flags of the POSIX (and/or GNU libc and/or MacOS) dlopen command, if possible, or are ignored if the specified functionality is not available on the current platform. The default flags are platform specific. On MacOS the default ``dlopen`` flags are ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL`` while on other platforms the defaults are ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_LOCAL``\ . An important usage of these flags is to specify non default behavior for when the dynamic library loader binds library references to exported symbols and if the bound references are put into process local or global scope. For instance ``RTLD_LAZY|RTLD_DEEPBIND|RTLD_GLOBAL`` allows the library's symbols to be available for usage in other shared libraries, addressing situations where there are dependencies between shared libraries. .. function:: dlopen_e(libfile::AbstractString [, flags::Integer]) + .. Docstring generated from Julia source + :: + + dlopen_e(libfile::AbstractString [, flags::Integer]) + Similar to :func:`dlopen`, except returns a ``NULL`` pointer instead of raising errors. .. data:: RTLD_DEEPBIND @@ -61,22 +57,35 @@ .. function:: dlsym(handle, sym) + .. Docstring generated from Julia source + .. code-block:: julia + dlsym(handle, sym) + Look up a symbol from a shared library handle, return callable function pointer on success. .. function:: dlsym_e(handle, sym) + .. Docstring generated from Julia source + .. code-block:: julia + dlsym_e(handle, sym) + Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. .. function:: dlclose(handle) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. data:: DL_LOAD_PATH diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 3f82f00dd28579..643fc2ddbb7d34 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -15,17 +15,23 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: *(A, B) + .. Docstring generated from Julia source + :: + + *(A, B) :noindex: Matrix multiplication :: + *(x, y...) Multiplication operator. ``x*y*z*...`` calls this function with all arguments, i.e. ``*(x, y, z, ...)``. :: + *(s, t) Concatenate strings. The ``*`` operator is an alias to this function. @@ -41,42 +47,55 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: dot(x, y) - :: - ⋅(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + dot(x, y) + ⋅(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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: cross(x, y) - :: - ×(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + cross(x, y) + ×(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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: full(F) + .. Docstring generated from Julia source :: + full(S) Convert a sparse matrix ``S`` into a dense matrix. :: + full(F) Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. :: + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` @@ -90,10 +109,19 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: lu(A) -> L, U, p - Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. + .. Docstring generated from Julia source + .. code-block:: julia + lu(A) -> L, U, p + + Compute the LU factorization of ``A``\ , such that ``A[p,:] = L*U``\ . .. function:: lufact(A [,pivot=Val{true}]) -> F + .. Docstring generated from Julia source + :: + + 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. ======================= ========================= ======================================== @@ -132,144 +160,113 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: lufact!(A) -> LU + .. Docstring generated from Julia source + :: + + 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. .. 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}``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 - 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. + .. Docstring generated from Julia source + .. code-block:: julia + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - :: - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + 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 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``). + .. code-block:: julia + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - 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). + 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``\ ). - The function calls the C library CHOLMOD and many other functions - from the library are wrapped but not exported. + Setting optional ``shift`` keyword argument computes the factorization of ``A+shift*I`` instead of ``A``\ . If the ``perm`` argument is nonempty, it should be a permutation of ``1:size(A,1)`` giving the ordering to use (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - :: - cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + .. Docstring generated from Julia source + .. code-block:: julia + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky - Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix ``A`` and return either a ``Cholesky`` if ``pivot==Val{false}`` or ``CholeskyPivoted`` if ``pivot==Val{true}``. ``LU`` may be ``:L`` for using the lower part or ``:U`` for the upper part. The default is to use ``:U``. The triangular matrix can be obtained from the factorization ``F`` with: ``F[:L]`` and ``F[:U]``. The following functions are available for ``Cholesky`` objects: ``size``, ``\``, ``inv``, ``det``. For ``CholeskyPivoted`` there is also defined a ``rank``. If ``pivot==Val{false}`` a ``PosDefException`` exception is thrown in case the matrix is not positive definite. The argument ``tol`` determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. + Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix ``A`` and return either a ``Cholesky`` if ``pivot==Val{false}`` or ``CholeskyPivoted`` if ``pivot==Val{true}``\ . ``LU`` may be ``:L`` for using the lower part or ``:U`` for the upper part. The default is to use ``:U``\ . The triangular matrix can be obtained from the factorization ``F`` with: ``F[:L]`` and ``F[:U]``\ . The following functions are available for ``Cholesky`` objects: ``size``\ , ``\``\ , ``inv``\ , ``det``\ . For ``CholeskyPivoted`` there is also defined a ``rank``\ . If ``pivot==Val{false}`` a ``PosDefException`` exception is thrown in case the matrix is not positive definite. The argument ``tol`` determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. - :: - cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + .. code-block:: julia + 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``). + 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). + 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. + 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 + .. Docstring generated from Julia source + :: + + cholfact!(A [,LU=:U [,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + ``cholfact!`` is the same as :func:`cholfact`, but saves space by overwriting the input ``A``, instead of creating a copy. ``cholfact!`` can also reuse the symbolic factorization from a different matrix ``F`` with the same structure when used as: ``cholfact!(F::CholmodFactor, A)``. .. function:: ldltfact(A) -> LDLtFactorization + .. Docstring generated from Julia source + .. code-block:: julia + ldltfact(A) -> LDLtFactorization + Compute a factorization of a positive definite matrix ``A`` such that ``A=L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector with non-negative elements. - :: - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + .. code-block:: julia + 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``. + 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). + 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. + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor - :: - ldltfact(A) -> LDLtFactorization + .. Docstring generated from Julia source + .. code-block:: julia + ldltfact(A) -> LDLtFactorization Compute a factorization of a positive definite matrix ``A`` such that ``A=L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector with non-negative elements. - :: - ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + .. code-block:: julia + 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``. + 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). + 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. + The function calls the C library CHOLMOD and many other functions from the library are wrapped but not exported. .. function:: qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] - Compute the (pivoted) QR factorization of ``A`` such that either ``A = Q*R`` or ``A[:,p] = Q*R``. Also see ``qrfact``. The default is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. + .. Docstring generated from Julia source + .. code-block:: julia + qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] + + Compute the (pivoted) QR factorization of ``A`` such that either ``A = Q*R`` or ``A[:,p] = Q*R``\ . Also see ``qrfact``\ . The default is to compute a thin factorization. Note that ``R`` is not extended with zeros when the full ``Q`` is requested. .. function:: qrfact(A [,pivot=Val{false}]) -> F + .. Docstring generated from Julia source + :: + + 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}``). ================ ================= ============== ===================================== @@ -326,13 +323,16 @@ Linear algebra functions in Julia are largely implemented by calling functions f `doi:10.1137/0910005 `_ :: + qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix ``A``. A fill-reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. .. function:: qrfact(A) -> SPQR.Factorization + .. Docstring generated from Julia source :: + 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}``). @@ -391,27 +391,37 @@ Linear algebra functions in Julia are largely implemented by calling functions f `doi:10.1137/0910005 `_ :: + qrfact(A) -> SPQR.Factorization Compute the QR factorization of a sparse matrix ``A``. A fill-reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. .. function:: qrfact!(A [,pivot=Val{false}]) + .. Docstring generated from Julia source + :: + + 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:: full(QRCompactWYQ[, thin=true]) -> Matrix + .. Docstring generated from Julia source :: + full(S) Convert a sparse matrix ``S`` into a dense matrix. :: + full(F) Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. :: + full(QRCompactWYQ[, thin=true]) -> Matrix Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` @@ -425,16 +435,31 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: bkfact(A) -> BunchKaufman + .. Docstring generated from Julia source + :: + + 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 `_. .. function:: bkfact!(A) -> BunchKaufman + .. Docstring generated from Julia source + :: + + bkfact!(A) -> BunchKaufman + ``bkfact!`` is the same as :func:`bkfact`, but saves space by overwriting the input ``A``, instead of creating a copy. .. function:: eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + .. Docstring generated from Julia source + :: + + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + Computes eigenvalues and eigenvectors of ``A``. See :func:`eigfact` for details on the ``balance`` keyword argument. @@ -452,6 +477,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f recommended. :: + eig(A, B) -> D, V Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. @@ -462,7 +488,9 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: eig(A, B) -> D, V + .. Docstring generated from Julia source :: + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V Computes eigenvalues and eigenvectors of ``A``. See :func:`eigfact` for @@ -482,6 +510,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f recommended. :: + eig(A, B) -> D, V Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. @@ -492,6 +521,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: eigvals(A,[irange,][vl,][vu]) + .. Docstring generated from Julia source + :: + + eigvals(A,[irange,][vl,][vu]) + Returns the eigenvalues of ``A``. If ``A`` is :class:`Symmetric`, :class:`Hermitian` or :class:`SymTridiagonal`, it is possible to calculate only a subset of the eigenvalues by specifying either a :class:`UnitRange` @@ -506,14 +540,27 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: eigmax(A) - Returns the largest eigenvalue of ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + eigmax(A) + + Returns the largest eigenvalue of ``A``\ . .. function:: eigmin(A) - Returns the smallest eigenvalue of ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + eigmin(A) + + Returns the smallest eigenvalue of ``A``\ . .. function:: eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + .. Docstring generated from Julia source + :: + + eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix + Returns a matrix ``M`` whose columns are the eigenvectors of ``A``. (The ``k``\ th eigenvector can be obtained from the slice ``M[:, k]``.) The ``permute`` and ``scale`` keywords are the same as for :func:`eigfact`. @@ -523,6 +570,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + .. Docstring generated from Julia source + :: + + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + Computes the eigenvalue decomposition of ``A``, returning an ``Eigen`` factorization object ``F`` which contains the eigenvalues in ``F[:values]`` and the eigenvectors in the columns of the matrix ``F[:vectors]``. @@ -544,6 +596,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f equal in norm. The default is ``true`` for both options. :: + eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of ``A`` and ``B``, @@ -555,7 +608,9 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: eigfact(A, B) -> GeneralizedEigen + .. Docstring generated from Julia source :: + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen Computes the eigenvalue decomposition of ``A``, returning an ``Eigen`` @@ -579,6 +634,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f equal in norm. The default is ``true`` for both options. :: + eigfact(A, B) -> GeneralizedEigen Computes the generalized eigenvalue decomposition of ``A`` and ``B``, @@ -590,436 +646,573 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: eigfact!(A, [B]) + .. Docstring generated from Julia source + :: + + eigfact!(A, [B]) + Same as :func:`eigfact`, but saves space by overwriting the input ``A`` (and ``B``), instead of creating a copy. .. function:: hessfact(A) + .. Docstring generated from Julia source + :: + + hessfact(A) + Compute the Hessenberg decomposition of ``A`` and return a ``Hessenberg`` object. If ``F`` is the factorization object, the unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``. When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with :func:`full`. .. function:: hessfact!(A) + .. Docstring generated from Julia source + :: + + hessfact!(A) + ``hessfact!`` is the same as :func:`hessfact`, but saves space by overwriting the input A, instead of creating a copy. .. function:: schurfact(A) -> Schur - Computes the Schur factorization of the matrix ``A``. The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``. The eigenvalues of ``A`` can be obtained with ``F[:values]``. + .. Docstring generated from Julia source + .. code-block:: julia + schurfact(A) -> Schur - :: - schurfact(A, B) -> GeneralizedSchur + Computes the Schur factorization of the matrix ``A``\ . The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``\ . The eigenvalues of ``A`` can be obtained with ``F[:values]``\ . - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``, the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``. The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``. + .. code-block:: julia + schurfact(A, B) -> GeneralizedSchur + + Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``\ . The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``\ , the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``\ . The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``\ . .. function:: schurfact!(A) + .. Docstring generated from Julia source + :: + + schurfact!(A) + Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See :func:`schurfact` .. function:: schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + .. Docstring generated from Julia source + :: + + schur(A) -> Schur[:T], Schur[:Z], Schur[:values] + See :func:`schurfact` :: + schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See :func:`schurfact` .. function:: ordschur(Q, T, select) -> Schur + .. Docstring generated from Julia source + :: + + ordschur(Q, T, select) -> Schur + Reorders the Schur factorization of a real matrix ``A=Q*T*Q'`` according to the logical array ``select`` returning a Schur object ``F``. The selected eigenvalues appear in the leading diagonal of ``F[:Schur]`` and the the corresponding leading columns of ``F[:vectors]`` form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via ``select``. :: + ordschur(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``. :: + ordschur(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix ``(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})`` according to the logical array ``select`` and returns a GeneralizedSchur object ``GS``. The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that ``(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}`` still holds and the generalized eigenvalues of ``A`` and ``B`` can still be obtained with ``GS[:alpha]./GS[:beta]``. :: + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See :func:`ordschur`. .. function:: ordschur!(Q, T, select) -> Schur + .. Docstring generated from Julia source + :: + + ordschur!(Q, T, select) -> Schur + Reorders the Schur factorization of a real matrix ``A=Q*T*Q'``, overwriting ``Q`` and ``T`` in the process. See :func:`ordschur` :: + ordschur!(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``, overwriting ``S`` in the process. See :func:`ordschur` :: + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix by overwriting the matrices ``(S, T, Q, Z)`` in the process. See :func:`ordschur`. :: + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See :func:`ordschur`. .. function:: ordschur(S, select) -> Schur + .. Docstring generated from Julia source :: + ordschur(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'`` according to the logical array ``select`` returning a Schur object ``F``. The selected eigenvalues appear in the leading diagonal of ``F[:Schur]`` and the the corresponding leading columns of ``F[:vectors]`` form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via ``select``. :: + ordschur(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``. :: + ordschur(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix ``(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})`` according to the logical array ``select`` and returns a GeneralizedSchur object ``GS``. The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that ``(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}`` still holds and the generalized eigenvalues of ``A`` and ``B`` can still be obtained with ``GS[:alpha]./GS[:beta]``. :: + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See :func:`ordschur`. .. function:: ordschur!(S, select) -> Schur + .. Docstring generated from Julia source :: + ordschur!(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'``, overwriting ``Q`` and ``T`` in the process. See :func:`ordschur` :: + ordschur!(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``, overwriting ``S`` in the process. See :func:`ordschur` :: + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix by overwriting the matrices ``(S, T, Q, Z)`` in the process. See :func:`ordschur`. :: + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See :func:`ordschur`. .. function:: schurfact(A, B) -> GeneralizedSchur - :: - schurfact(A) -> Schur + .. Docstring generated from Julia source + .. code-block:: julia + schurfact(A) -> Schur - Computes the Schur factorization of the matrix ``A``. The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``. The eigenvalues of ``A`` can be obtained with ``F[:values]``. + Computes the Schur factorization of the matrix ``A``\ . The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``\ . The eigenvalues of ``A`` can be obtained with ``F[:values]``\ . - :: - schurfact(A, B) -> GeneralizedSchur + .. code-block:: julia + schurfact(A, B) -> GeneralizedSchur - Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``, the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``. The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``. + Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``\ . The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``\ , the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``\ . The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``\ . .. function:: schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + .. Docstring generated from Julia source :: + schur(A) -> Schur[:T], Schur[:Z], Schur[:values] See :func:`schurfact` :: + schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] See :func:`schurfact` .. function:: ordschur(S, T, Q, Z, select) -> GeneralizedSchur + .. Docstring generated from Julia source :: + ordschur(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'`` according to the logical array ``select`` returning a Schur object ``F``. The selected eigenvalues appear in the leading diagonal of ``F[:Schur]`` and the the corresponding leading columns of ``F[:vectors]`` form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via ``select``. :: + ordschur(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``. :: + ordschur(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix ``(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})`` according to the logical array ``select`` and returns a GeneralizedSchur object ``GS``. The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that ``(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}`` still holds and the generalized eigenvalues of ``A`` and ``B`` can still be obtained with ``GS[:alpha]./GS[:beta]``. :: + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See :func:`ordschur`. .. function:: ordschur!(S, T, Q, Z, select) -> GeneralizedSchur + .. Docstring generated from Julia source :: + ordschur!(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'``, overwriting ``Q`` and ``T`` in the process. See :func:`ordschur` :: + ordschur!(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``, overwriting ``S`` in the process. See :func:`ordschur` :: + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix by overwriting the matrices ``(S, T, Q, Z)`` in the process. See :func:`ordschur`. :: + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See :func:`ordschur`. .. function:: ordschur(GS, select) -> GeneralizedSchur + .. Docstring generated from Julia source :: + ordschur(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'`` according to the logical array ``select`` returning a Schur object ``F``. The selected eigenvalues appear in the leading diagonal of ``F[:Schur]`` and the the corresponding leading columns of ``F[:vectors]`` form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via ``select``. :: + ordschur(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``. :: + ordschur(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix ``(A, B) = (Q*S*Z^{H}, Q*T*Z^{H})`` according to the logical array ``select`` and returns a GeneralizedSchur object ``GS``. The selected eigenvalues appear in the leading diagonal of both``(GS[:S], GS[:T])`` and the left and right unitary/orthogonal Schur vectors are also reordered such that ``(A, B) = GS[:Q]*(GS[:S], GS[:T])*GS[:Z]^{H}`` still holds and the generalized eigenvalues of ``A`` and ``B`` can still be obtained with ``GS[:alpha]./GS[:beta]``. :: + ordschur(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object. See :func:`ordschur`. .. function:: ordschur!(GS, select) -> GeneralizedSchur + .. Docstring generated from Julia source :: + ordschur!(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'``, overwriting ``Q`` and ``T`` in the process. See :func:`ordschur` :: + ordschur!(S, select) -> Schur Reorders the Schur factorization ``S`` of type ``Schur``, overwriting ``S`` in the process. See :func:`ordschur` :: + ordschur!(S, T, Q, Z, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a matrix by overwriting the matrices ``(S, T, Q, Z)`` in the process. See :func:`ordschur`. :: + ordschur!(GS, select) -> GeneralizedSchur Reorders the Generalized Schur factorization of a Generalized Schur object by overwriting the object with the new factorization. See :func:`ordschur`. .. function:: svdfact(A, [thin=true]) -> SVD - Compute the Singular Value Decomposition (SVD) of ``A`` and return an ``SVD`` object. ``U``, ``S``, ``V`` and ``Vt`` can be obtained from the factorization ``F`` with ``F[:U]``, ``F[:S]``, ``F[:V]`` and ``F[:Vt]``, such that ``A = U*diagm(S)*Vt``. If ``thin`` is ``true``, an economy mode decomposition is returned. The algorithm produces ``Vt`` and hence ``Vt`` is more efficient to extract than ``V``. The default is to produce a thin decomposition. + .. Docstring generated from Julia source + .. code-block:: julia + svdfact(A, [thin=true]) -> SVD - :: - svdfact(A, B) -> GeneralizedSVD + Compute the Singular Value Decomposition (SVD) of ``A`` and return an ``SVD`` object. ``U``\ , ``S``\ , ``V`` and ``Vt`` can be obtained from the factorization ``F`` with ``F[:U]``\ , ``F[:S]``\ , ``F[:V]`` and ``F[:Vt]``\ , such that ``A = U*diagm(S)*Vt``\ . If ``thin`` is ``true``\ , an economy mode decomposition is returned. The algorithm produces ``Vt`` and hence ``Vt`` is more efficient to extract than ``V``\ . The default is to produce a thin decomposition. + + .. code-block:: julia + svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a ``GeneralizedSVD`` Factorization object ``F``, such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``. + Compute the generalized SVD of ``A`` and ``B``\ , returning a ``GeneralizedSVD`` Factorization object ``F``\ , such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``\ . .. function:: svdfact!(A, [thin=true]) -> SVD + .. Docstring generated from Julia source + :: + + 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. .. function:: svd(A, [thin=true]) -> U, S, V - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. Computes the SVD of A, returning ``U``, vector ``S``, and ``V`` such that ``A == U*diagm(S)*V'``. If ``thin`` is ``true``, an economy mode decomposition is returned. The default is to produce a thin decomposition. + .. Docstring generated from Julia source + .. code-block:: julia + 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. 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. + + .. code-block:: julia + svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``, returning ``U``, ``V``, ``Q``, ``D1``, ``D2``, and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``\ , returning ``U``\ , ``V``\ , ``Q``\ , ``D1``\ , ``D2``\ , and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``\ . .. function:: svdvals(A) - Returns the singular values of ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + svdvals(A) - :: - svdvals(A, B) + Returns the singular values of ``A``\ . + + .. code-block:: julia + svdvals(A, B) - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``\ . .. function:: svdvals!(A) - Returns the singular values of ``A``, while saving space by overwriting the input. + .. Docstring generated from Julia source + .. code-block:: julia + svdvals!(A) + + Returns the singular values of ``A``\ , while saving space by overwriting the input. .. function:: svdfact(A, B) -> GeneralizedSVD - :: - svdfact(A, [thin=true]) -> SVD + .. Docstring generated from Julia source + .. code-block:: julia + svdfact(A, [thin=true]) -> SVD - Compute the Singular Value Decomposition (SVD) of ``A`` and return an ``SVD`` object. ``U``, ``S``, ``V`` and ``Vt`` can be obtained from the factorization ``F`` with ``F[:U]``, ``F[:S]``, ``F[:V]`` and ``F[:Vt]``, such that ``A = U*diagm(S)*Vt``. If ``thin`` is ``true``, an economy mode decomposition is returned. The algorithm produces ``Vt`` and hence ``Vt`` is more efficient to extract than ``V``. The default is to produce a thin decomposition. + Compute the Singular Value Decomposition (SVD) of ``A`` and return an ``SVD`` object. ``U``\ , ``S``\ , ``V`` and ``Vt`` can be obtained from the factorization ``F`` with ``F[:U]``\ , ``F[:S]``\ , ``F[:V]`` and ``F[:Vt]``\ , such that ``A = U*diagm(S)*Vt``\ . If ``thin`` is ``true``\ , an economy mode decomposition is returned. The algorithm produces ``Vt`` and hence ``Vt`` is more efficient to extract than ``V``\ . The default is to produce a thin decomposition. - :: - svdfact(A, B) -> GeneralizedSVD + .. code-block:: julia + svdfact(A, B) -> GeneralizedSVD - Compute the generalized SVD of ``A`` and ``B``, returning a ``GeneralizedSVD`` Factorization object ``F``, such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``. + Compute the generalized SVD of ``A`` and ``B``\ , returning a ``GeneralizedSVD`` Factorization object ``F``\ , such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``\ . .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 - :: - svd(A, [thin=true]) -> U, S, V + .. Docstring generated from Julia source + .. code-block:: julia + svd(A, [thin=true]) -> U, S, V - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. Computes the SVD of A, returning ``U``, vector ``S``, and ``V`` such that ``A == U*diagm(S)*V'``. If ``thin`` is ``true``, an economy mode decomposition is returned. The default is to produce a thin decomposition. + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. Computes the SVD of A, returning ``U``\ , vector ``S``\ , and ``V`` such that ``A == U*diagm(S)*V'``\ . If ``thin`` is ``true``\ , an economy mode decomposition is returned. The default is to produce a thin decomposition. - :: - svd(A, B) -> U, V, Q, D1, D2, R0 + .. code-block:: julia + svd(A, B) -> U, V, Q, D1, D2, R0 - Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``, returning ``U``, ``V``, ``Q``, ``D1``, ``D2``, and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``\ , returning ``U``\ , ``V``\ , ``Q``\ , ``D1``\ , ``D2``\ , and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``\ . .. function:: svdvals(A, B) - :: - svdvals(A) + .. Docstring generated from Julia source + .. code-block:: julia + svdvals(A) - Returns the singular values of ``A``. + Returns the singular values of ``A``\ . - :: - svdvals(A, B) + .. code-block:: julia + svdvals(A, B) - Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``\ . .. function:: triu(M) + .. Docstring generated from Julia source + .. code-block:: julia + triu(M) + Upper triangle of a matrix. - :: - triu(M, k) + .. code-block:: julia + triu(M, k) Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal. .. function:: triu(M, k) - :: - triu(M) + .. Docstring generated from Julia source + .. code-block:: julia + triu(M) Upper triangle of a matrix. - :: - triu(M, k) + .. code-block:: julia + triu(M, k) Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal. .. function:: triu!(M) + .. Docstring generated from Julia source + .. code-block:: julia + triu!(M) + Upper triangle of a matrix, overwriting ``M`` in the process. - :: - triu!(M, k) + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + triu!(M) Upper triangle of a matrix, overwriting ``M`` in the process. - :: - triu!(M, k) + .. code-block:: julia + triu!(M, k) Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. .. function:: tril(M) + .. Docstring generated from Julia source + .. code-block:: julia + tril(M) + Lower triangle of a matrix. - :: - tril(M, k) + .. code-block:: julia + tril(M, k) Returns the lower triangle of ``M`` starting from the ``k``\ th superdiagonal. .. function:: tril(M, k) - :: - tril(M) + .. Docstring generated from Julia source + .. code-block:: julia + tril(M) Lower triangle of a matrix. - :: - tril(M, k) + .. code-block:: julia + tril(M, k) Returns the lower triangle of ``M`` starting from the ``k``\ th superdiagonal. .. function:: tril!(M) + .. Docstring generated from Julia source + .. code-block:: julia + tril!(M) + Lower triangle of a matrix, overwriting ``M`` in the process. - :: - tril!(M, k) + .. code-block:: julia + tril!(M, k) Returns the lower triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. .. function:: tril!(M, k) - :: - tril!(M) + .. Docstring generated from Julia source + .. code-block:: julia + tril!(M) Lower triangle of a matrix, overwriting ``M`` in the process. - :: - tril!(M, k) + .. code-block:: julia + tril!(M, k) Returns the lower triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. .. function:: diagind(M[, k]) - A ``Range`` giving the indices of the ``k``\ th diagonal of the matrix ``M``. + .. Docstring generated from Julia source + .. code-block:: julia + diagind(M[, k]) + + A ``Range`` giving the indices of the ``k``\ th diagonal of the matrix ``M``\ . .. function:: diag(M[, k]) + .. Docstring generated from Julia source + .. code-block:: julia + diag(M[, k]) + The ``k``\ th diagonal of a matrix, as a vector. Use ``diagm`` to construct a diagonal matrix. .. function:: diagm(v[, k]) + .. Docstring generated from Julia source + .. code-block:: julia + diagm(v[, k]) + Construct a diagonal matrix and place ``v`` on the ``k``\ th diagonal. .. function:: scale(A, b) - :: - scale(b, A) + .. Docstring generated from Julia source + .. code-block:: julia + scale(A, b) - Scale an array ``A`` by a scalar ``b``, returning a new array. + scale(b, A) - If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` - scales each column ``i`` of ``A`` by ``b[i]`` (similar to - ``A*diagm(b)``), while ``scale(b,A)`` scales each row ``i`` of - ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), returning a new array. + Scale an array ``A`` by a scalar ``b``\ , returning a new array. + + If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to ``A*diagm(b)``\ ), while ``scale(b,A)`` scales each row ``i`` of ``A`` by ``b[i]`` (similar to ``diagm(b)*A``\ ), returning a new array. - Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or - ``b .* A``, due to the use of BLAS. + Note: for large ``A``\ , ``scale`` can be much faster than ``A .* b`` or ``b .* A``\ , due to the use of BLAS. .. function:: scale(b, A) - :: - scale(A, b) + .. Docstring generated from Julia source + .. code-block:: julia + scale(A, b) - :: - scale(b, A) + scale(b, A) - Scale an array ``A`` by a scalar ``b``, returning a new array. + Scale an array ``A`` by a scalar ``b``\ , returning a new array. - If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` - scales each column ``i`` of ``A`` by ``b[i]`` (similar to - ``A*diagm(b)``), while ``scale(b,A)`` scales each row ``i`` of - ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), returning a new array. + If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` scales each column ``i`` of ``A`` by ``b[i]`` (similar to ``A*diagm(b)``\ ), while ``scale(b,A)`` scales each row ``i`` of ``A`` by ``b[i]`` (similar to ``diagm(b)*A``\ ), returning a new array. - Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or - ``b .* A``, due to the use of BLAS. + Note: for large ``A``\ , ``scale`` can be much faster than ``A .* b`` or ``b .* A``\ , due to the use of BLAS. .. function:: scale!(A, b) + .. Docstring generated from Julia source :: + + scale!(A, b) + + :: + scale!(b, A) Scale an array ``A`` by a scalar ``b``, similar to :func:`scale` but @@ -1033,10 +1226,13 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: scale!(b, A) + .. Docstring generated from Julia source :: + scale!(A, b) :: + scale!(b, A) Scale an array ``A`` by a scalar ``b``, similar to :func:`scale` but @@ -1050,45 +1246,78 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: Tridiagonal(dl, d, du) + .. Docstring generated from Julia source + :: + + 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`. .. function:: Bidiagonal(dv, ev, isupper) + .. Docstring generated from Julia source + :: + + Bidiagonal(dv, ev, isupper) + Constructs an upper (``isupper=true``) or lower (``isupper=false``) bidiagonal matrix using the given diagonal (``dv``) and off-diagonal (``ev``) vectors. The result is of type ``Bidiagonal`` and provides efficient specialized linear solvers, but may be converted into a regular matrix with :func:`full`. .. function:: SymTridiagonal(d, du) + .. Docstring generated from Julia source + :: + + SymTridiagonal(d, du) + Construct a real symmetric tridiagonal matrix from the diagonal and upper diagonal, respectively. The result is of type ``SymTridiagonal`` and provides efficient specialized eigensolvers, but may be converted into a regular matrix with :func:`full`. .. function:: rank(M) + .. Docstring generated from Julia source + .. code-block:: julia + rank(M) + Compute the rank of a matrix. .. function:: norm(A, [p]) + .. Docstring generated from Julia source + :: + + norm(A, [p]) + Compute the ``p``-norm of a vector or the operator norm of a matrix ``A``, defaulting to the ``p=2``-norm. For vectors, ``p`` can assume any numeric value (even though not all values produce a mathematically valid vector norm). In particular, ``norm(A, Inf)`` returns the largest value in ``abs(A)``, whereas ``norm(A, -Inf)`` returns the smallest. - For matrices, valid values of ``p`` are ``1``, ``2``, or ``Inf``. (Note that for sparse matrices, ``p=2`` is currently not implemented.) Use :func:`vecnorm` to compute the Frobenius norm. + For matrices, the matrix norm induced by the vector ``p``-norm is used, where 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + vecnorm(A, [p]) + + For any iterable container ``A`` (including arrays of any dimension) of numbers (or any element type for which ``norm`` is defined), compute the ``p``\ -norm (defaulting to ``p=2``\ ) as if ``A`` were a vector of the corresponding length. - For example, if ``A`` is a matrix and ``p=2``, then this is equivalent - to the Frobenius norm. + For example, if ``A`` is a matrix and ``p=2``\ , then this is equivalent to the Frobenius norm. .. function:: cond(M, [p]) - Condition number of the matrix ``M``, computed using the operator ``p``-norm. Valid values for ``p`` are ``1``, ``2`` (default), or ``Inf``. + .. Docstring generated from Julia source + .. code-block:: julia + cond(M, [p]) + + Condition number of the matrix ``M``\ , computed using the operator ``p``\ -norm. Valid values for ``p`` are ``1``\ , ``2`` (default), or ``Inf``\ . .. function:: condskeel(M, [x, p]) + .. Docstring generated from Julia source + :: + + 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 @@ -1099,26 +1328,51 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: trace(M) + .. Docstring generated from Julia source + .. code-block:: julia + trace(M) + Matrix trace .. function:: det(M) + .. Docstring generated from Julia source + .. code-block:: julia + det(M) + Matrix determinant .. function:: logdet(M) - Log of matrix determinant. Equivalent to ``log(det(M))``, but may provide increased accuracy and/or speed. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + inv(M) + Matrix inverse .. function:: pinv(M[, tol]) + .. Docstring generated from Julia source + :: + + pinv(M[, tol]) + Computes the Moore-Penrose pseudoinverse. For matrices ``M`` with floating point elements, it is convenient to compute @@ -1150,26 +1404,51 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: nullspace(M) - Basis for nullspace of ``M``. + .. Docstring generated from Julia source + .. code-block:: julia + nullspace(M) + + Basis for nullspace of ``M``\ . .. function:: repmat(A, n, m) + .. Docstring generated from Julia source + .. code-block:: julia + repmat(A, n, m) + Construct a matrix by repeating the given matrix ``n`` times in dimension 1 and ``m`` times in dimension 2. .. function:: repeat(A, inner = Int[], outer = Int[]) - Construct an array by repeating the entries of ``A``. The i-th element of ``inner`` specifies the number of times that the individual entries of the i-th dimension of ``A`` should be repeated. The i-th element of ``outer`` specifies the number of times that a slice along the i-th dimension of ``A`` should be repeated. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + kron(A, B) + Kronecker tensor product of two vectors or two matrices. .. function:: blkdiag(A...) + .. Docstring generated from Julia source + .. code-block:: julia + blkdiag(A...) + Concatenate matrices block-diagonally. Currently only implemented for sparse matrices. .. function:: linreg(x, y) -> [a; b] + .. Docstring generated from Julia source + :: + + linreg(x, y) -> [a; b] + Linear Regression. Returns ``a`` and ``b`` such that ``a+b*x`` is the closest line to the given points ``(x,y)``. In other words, this function determines parameters ``[a, b]`` that minimize the squared error between ``y`` and ``a+b*x``. **Example**:: @@ -1182,13 +1461,16 @@ Linear algebra functions in Julia are largely implemented by calling functions f plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression :: + linreg(x, y, w) Weighted least-squares linear regression. .. function:: linreg(x, y, w) + .. Docstring generated from Julia source :: + linreg(x, y) -> [a; b] Linear Regression. Returns ``a`` and ``b`` such that ``a+b*x`` is the closest line to the given points ``(x,y)``. In other words, this function determines parameters ``[a, b]`` that minimize the squared error between ``y`` and ``a+b*x``. @@ -1203,12 +1485,18 @@ Linear algebra functions in Julia are largely implemented by calling functions f plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression :: + linreg(x, y, w) Weighted least-squares linear regression. .. function:: expm(A) + .. Docstring generated from Julia source + :: + + expm(A) + Compute the matrix exponential of ``A``, defined by .. math:: @@ -1223,6 +1511,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: logm(A) + .. Docstring generated from Julia source + :: + + logm(A) + If ``A`` has no negative real eigenvalue, compute the principal matrix logarithm of ``A``, i.e. the unique matrix :math:`X` such that :math:`e^X = A` and :math:`-\pi < Im(\lambda) < \pi` for all the eigenvalues :math:`\lambda` of :math:`X`. If ``A`` has nonpositive eigenvalues, a warning is printed and whenever possible a nonprincipal matrix function is returned. If ``A`` is symmetric or Hermitian, its eigendecomposition (:func:`eigfact`) is used, if ``A`` is triangular an improved version of the inverse scaling and squaring method is employed (see [AH12]_ and [AHR13]_). For general matrices, the complex Schur form (:func:`schur`) is computed and the triangular algorithm is used on the triangular factor. @@ -1239,6 +1532,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: sqrtm(A) + .. Docstring generated from Julia source + :: + + sqrtm(A) + If ``A`` has no negative real eigenvalues, compute the principal matrix square root of ``A``, that is the unique matrix :math:`X` with eigenvalues having positive real part such that :math:`X^2 = A`. Otherwise, a nonprincipal square root is returned. If ``A`` is symmetric or Hermitian, its eigendecomposition (:func:`eigfact`) is used to compute the square root. Otherwise, the square root is determined by means of the Björck-Hammarling method, which computes the complex Schur form (:func:`schur`) and then the complex square root of the triangular factor. @@ -1249,58 +1547,115 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: lyap(A, C) - Computes the solution ``X`` to the continuous Lyapunov equation ``AX + XA' + C = 0``, where no eigenvalue of ``A`` has a zero real part and no two eigenvalues are negative complex conjugates of each other. + .. Docstring generated from Julia source + .. code-block:: julia + lyap(A, C) + + Computes the solution ``X`` to the continuous Lyapunov equation ``AX + XA' + C = 0``\ , where no eigenvalue of ``A`` has a zero real part and no two eigenvalues are negative complex conjugates of each other. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + issym(A) -> Bool + Test whether a matrix is symmetric. .. function:: isposdef(A) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isposdef(A) -> Bool + Test whether a matrix is positive definite. .. function:: isposdef!(A) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isposdef!(A) -> Bool + Test whether a matrix is positive definite, overwriting ``A`` in the processes. .. function:: istril(A) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + istril(A) -> Bool + Test whether a matrix is lower triangular. .. function:: istriu(A) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + istriu(A) -> Bool + Test whether a matrix is upper triangular. .. function:: isdiag(A) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isdiag(A) -> Bool + Test whether a matrix is diagonal. .. function:: ishermitian(A) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + ishermitian(A) -> Bool + Test whether a matrix is Hermitian. .. function:: transpose(A) - The transposition operator (``.'``). + .. Docstring generated from Julia source + .. code-block:: julia + transpose(A) + + The transposition operator (``.'``\ ). .. function:: transpose!(dest,src) - Transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if ``src`` and ``dest`` have overlapping memory regions. + .. Docstring generated from Julia source + .. code-block:: julia + 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) - The conjugate transposition operator (``'``). + .. Docstring generated from Julia source + .. code-block:: julia + ctranspose(A) + + The conjugate transposition operator (``'``\ ). .. function:: ctranspose!(dest,src) - Conjugate transpose array ``src`` and store the result in the preallocated array ``dest``, which should have a size corresponding to ``(size(src,2),size(src,1))``. No in-place transposition is supported and unexpected results will happen if ``src`` and ``dest`` have overlapping memory regions. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + 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. @@ -1346,6 +1701,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid) + .. Docstring generated from Julia source + :: + + 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. @@ -1363,6 +1723,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: peakflops(n; parallel=false) + .. Docstring generated from Julia source + :: + + peakflops(n; parallel=false) + ``peakflops`` computes the peak flop rate of the computer by using double precision :func:`Base.LinAlg.BLAS.gemm!`. By default, if no arguments are specified, it multiplies a matrix of size ``n x n``, where ``n = 2000``. If the underlying BLAS is using multiple threads, higher flop rates are realized. The number of BLAS threads can be set with ``blas_set_num_threads(n)``. If the keyword argument ``parallel`` is set to ``true``, ``peakflops`` is run in parallel on all the worker processors. The flop rate of the entire parallel computer is returned. When running in parallel, only 1 BLAS thread is used. The argument ``n`` still refers to the size of the problem that is solved on each processor. @@ -1383,364 +1748,418 @@ Usually a function has 4 methods defined, one each for ``Float64``, .. function:: dot(n, X, incx, Y, incy) - Dot product of two vectors consisting of ``n`` elements of array - ``X`` with stride ``incx`` and ``n`` elements of array ``Y`` with - stride ``incy``. + .. Docstring generated from Julia source + .. code-block:: julia + 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:: dotu(n, X, incx, Y, incy) + .. Docstring generated from Julia source + .. code-block:: julia + dotu(n, X, incx, Y, incy) + Dot function for two complex vectors. .. function:: dotc(n, X, incx, U, incy) + .. Docstring generated from Julia source + .. code-block:: julia + dotc(n, X, incx, U, incy) + Dot function for two complex vectors conjugating the first vector. .. function:: blascopy!(n, X, incx, Y, incy) - Copy ``n`` elements of array ``X`` with stride ``incx`` to array - ``Y`` with stride ``incy``. Returns ``Y``. + .. Docstring generated from Julia source + .. code-block:: julia + blascopy!(n, X, incx, Y, incy) + + Copy ``n`` elements of array ``X`` with stride ``incx`` to array ``Y`` with stride ``incy``\ . Returns ``Y``\ . .. function:: nrm2(n, X, incx) - 2-norm of a vector consisting of ``n`` elements of array ``X`` with - stride ``incx``. + .. Docstring generated from Julia source + .. code-block:: julia + nrm2(n, X, incx) + + 2-norm of a vector consisting of ``n`` elements of array ``X`` with stride ``incx``\ . .. function:: asum(n, X, incx) - sum of the absolute values of the first ``n`` elements of array ``X`` with - stride ``incx``. + .. Docstring generated from Julia source + .. code-block:: julia + asum(n, X, incx) + + sum of the absolute values of the first ``n`` elements of array ``X`` with stride ``incx``\ . .. function:: axpy!(a, X, Y) - Overwrite ``Y`` with ``a*X + Y``. Returns ``Y``. + .. Docstring generated from Julia source + .. code-block:: julia + axpy!(a, X, Y) + + Overwrite ``Y`` with ``a*X + Y``\ . Returns ``Y``\ . .. function:: scal!(n, a, X, incx) - Overwrite ``X`` with ``a*X``. Returns ``X``. + .. Docstring generated from Julia source + .. code-block:: julia + scal!(n, a, X, incx) + + Overwrite ``X`` with ``a*X``\ . Returns ``X``\ . .. function:: scal(n, a, X, incx) - Returns ``a*X``. + .. Docstring generated from Julia source + .. code-block:: julia + scal(n, a, X, incx) + + Returns ``a*X``\ . .. function:: ger!(alpha, x, y, A) - Rank-1 update of the matrix ``A`` with vectors ``x`` and - ``y`` as ``alpha*x*y' + A``. + .. Docstring generated from Julia source + .. code-block:: julia + ger!(alpha, x, y, A) + + Rank-1 update of the matrix ``A`` with vectors ``x`` and ``y`` as ``alpha*x*y' + A``\ . .. function:: syr!(uplo, alpha, x, A) - Rank-1 update of the symmetric matrix ``A`` with vector - ``x`` as ``alpha*x*x.' + A``. When ``uplo`` is 'U' the - upper triangle of ``A`` is updated ('L' for lower triangle). - Returns ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: syrk!(uplo, trans, alpha, A, beta, C) - Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + - beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` - is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is - updated ('L' for lower triangle). Returns ``C``. + .. Docstring generated from Julia source + .. code-block:: julia + syrk!(uplo, trans, alpha, A, beta, C) + + Rank-k update of the symmetric matrix ``C`` as ``alpha*A*A.' + beta*C`` or ``alpha*A.'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``\ . .. function:: syrk(uplo, trans, alpha, A) - Returns either the upper triangle or the lower triangle, according - to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``, - according to ``trans`` ('N' or 'T'). + .. Docstring generated from Julia source + .. code-block:: julia + syrk(uplo, trans, alpha, A) + + Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of ``alpha*A*A.'`` or ``alpha*A.'*A``\ , according to ``trans`` ('N' or 'T'). .. function:: her!(uplo, alpha, x, A) - Methods for complex arrays only. Rank-1 update of the Hermitian - matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``. When - ``uplo`` is 'U' the upper triangle of ``A`` is updated - ('L' for lower triangle). Returns ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + her!(uplo, alpha, x, A) + + Methods for complex arrays only. Rank-1 update of the Hermitian matrix ``A`` with vector ``x`` as ``alpha*x*x' + A``\ . When ``uplo`` is 'U' the upper triangle of ``A`` is updated ('L' for lower triangle). Returns ``A``\ . .. function:: herk!(uplo, trans, alpha, A, beta, C) - Methods for complex arrays only. Rank-k update of the Hermitian - matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` - according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' - the upper triangle of ``C`` is updated ('L' for lower triangle). - Returns ``C``. + .. Docstring generated from Julia source + .. code-block:: julia + herk!(uplo, trans, alpha, A, beta, C) + + Methods for complex arrays only. Rank-k update of the Hermitian matrix ``C`` as ``alpha*A*A' + beta*C`` or ``alpha*A'*A + beta*C`` according to whether ``trans`` is 'N' or 'T'. When ``uplo`` is 'U' the upper triangle of ``C`` is updated ('L' for lower triangle). Returns ``C``\ . .. function:: herk(uplo, trans, alpha, A) - Methods for complex arrays only. Returns either the upper triangle - or the lower triangle, according to ``uplo`` ('U' or 'L'), of - ``alpha*A*A'`` or ``alpha*A'*A``, according to ``trans`` ('N' or 'T'). + .. Docstring generated from Julia source + .. code-block:: julia + herk(uplo, trans, alpha, A) + + Methods for complex arrays only. Returns either the upper triangle or the lower triangle, according to ``uplo`` ('U' or 'L'), of ``alpha*A*A'`` or ``alpha*A'*A``\ , according to ``trans`` ('N' or 'T'). .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) - 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. + .. Docstring generated from Julia source + .. code-block:: julia + gbmv(trans, m, kl, ku, alpha, A, x, beta, y) + + Returns ``alpha*A*x`` or ``alpha*A'*x`` according to ``trans`` ('N' or 'T'). The matrix ``A`` is a general band matrix of dimension ``m`` by ``size(A,2)`` with ``kl`` sub-diagonals and ``ku`` super-diagonals. .. 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/. + .. Docstring generated from Julia source + .. code-block:: julia + 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 . - Returns the updated ``y``. + Returns the updated ``y``\ . .. function:: sbmv(uplo, k, alpha, A, x) - Returns ``alpha*A*x`` where ``A`` is a symmetric band matrix of - order ``size(A,2)`` with ``k`` super-diagonals stored in the - argument ``A``. + .. Docstring generated from Julia source + .. code-block:: julia + sbmv(uplo, k, alpha, A, x) - :: - sbmv(uplo, k, A, x) + Returns ``alpha*A*x`` where ``A`` is a symmetric band matrix of order ``size(A,2)`` with ``k`` super-diagonals stored in the argument ``A``\ . + + .. code-block:: julia + sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of - order ``size(A,2)`` with ``k`` super-diagonals stored in the - argument ``A``. + Returns ``A*x`` where ``A`` is a symmetric band matrix of order ``size(A,2)`` with ``k`` super-diagonals stored in the argument ``A``\ . .. function:: sbmv(uplo, k, A, x) - :: - sbmv(uplo, k, alpha, A, x) + .. Docstring generated from Julia source + .. code-block:: julia + sbmv(uplo, k, alpha, A, x) - Returns ``alpha*A*x`` where ``A`` is a symmetric band matrix of - order ``size(A,2)`` with ``k`` super-diagonals stored in the - argument ``A``. + Returns ``alpha*A*x`` where ``A`` is a symmetric band matrix of order ``size(A,2)`` with ``k`` super-diagonals stored in the argument ``A``\ . - :: - sbmv(uplo, k, A, x) + .. code-block:: julia + sbmv(uplo, k, A, x) - Returns ``A*x`` where ``A`` is a symmetric band matrix of - order ``size(A,2)`` with ``k`` super-diagonals stored in the - argument ``A``. + Returns ``A*x`` where ``A`` is a symmetric band matrix of order ``size(A,2)`` with ``k`` super-diagonals stored in the argument ``A``\ . .. function:: gemm!(tA, tB, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. Returns the - updated ``C``. + .. Docstring generated from Julia source + .. code-block:: julia + gemm!(tA, tB, alpha, A, B, beta, C) + + Update ``C`` as ``alpha*A*B + beta*C`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . Returns the updated ``C``\ . .. function:: gemm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + .. Docstring generated from Julia source + .. code-block:: julia + gemm(tA, tB, alpha, A, B) - :: - gemm(tA, tB, A, B) + Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . + + .. code-block:: julia + gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + Returns ``A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . .. function:: gemm(tA, tB, A, B) - :: - gemm(tA, tB, alpha, A, B) + .. Docstring generated from Julia source + .. code-block:: julia + gemm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . - :: - gemm(tA, tB, A, B) + .. code-block:: julia + gemm(tA, tB, A, B) - Returns ``A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + Returns ``A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . .. function:: gemv!(tA, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y`` or - ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``). - Returns the updated ``y``. + .. Docstring generated from Julia source + .. code-block:: julia + gemv!(tA, alpha, A, x, beta, y) + + Update the vector ``y`` as ``alpha*A*x + beta*y`` or ``alpha*A'x + beta*y`` according to ``tA`` (transpose ``A``\ ). Returns the updated ``y``\ . .. function:: gemv(tA, alpha, A, x) - Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` - (transpose ``A``). + .. Docstring generated from Julia source + .. code-block:: julia + gemv(tA, alpha, A, x) - :: - gemv(tA, A, x) + Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` (transpose ``A``\ ). + + .. code-block:: julia + gemv(tA, A, x) - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). + Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``\ ). .. function:: gemv(tA, A, x) - :: - gemv(tA, alpha, A, x) + .. Docstring generated from Julia source + .. code-block:: julia + gemv(tA, alpha, A, x) - Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` - (transpose ``A``). + Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` (transpose ``A``\ ). - :: - gemv(tA, A, x) + .. code-block:: julia + gemv(tA, A, x) - Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). + Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``\ ). .. function:: symm!(side, ul, alpha, A, B, beta, C) - Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` - according to ``side``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. Returns the updated ``C``. + .. Docstring generated from Julia source + .. code-block:: julia + symm!(side, ul, alpha, A, B, beta, C) + + Update ``C`` as ``alpha*A*B + beta*C`` or ``alpha*B*A + beta*C`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. Returns the updated ``C``\ . .. function:: symm(side, ul, alpha, A, B) - Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``. - ``A`` is assumed to be symmetric. Only the ``ul`` triangle of - ``A`` is used. + .. Docstring generated from Julia source + .. code-block:: julia + symm(side, ul, alpha, A, B) - :: - symm(side, ul, A, B) + Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed - to be symmetric. Only the ``ul`` triangle of ``A`` is used. + .. code-block:: julia + symm(side, ul, A, B) - :: - symm(tA, tB, alpha, A, B) + Returns ``A*B`` or ``B*A`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + .. code-block:: julia + symm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . .. function:: symm(side, ul, A, B) - :: - symm(side, ul, alpha, A, B) + .. Docstring generated from Julia source + .. code-block:: julia + symm(side, ul, alpha, A, B) - Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``. - ``A`` is assumed to be symmetric. Only the ``ul`` triangle of - ``A`` is used. + Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - :: - symm(side, ul, A, B) + .. code-block:: julia + symm(side, ul, A, B) - Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed - to be symmetric. Only the ``ul`` triangle of ``A`` is used. + Returns ``A*B`` or ``B*A`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - :: - symm(tA, tB, alpha, A, B) + .. code-block:: julia + symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . .. function:: symm(tA, tB, alpha, A, B) - :: - symm(side, ul, alpha, A, B) + .. Docstring generated from Julia source + .. code-block:: julia + symm(side, ul, alpha, A, B) - Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``. - ``A`` is assumed to be symmetric. Only the ``ul`` triangle of - ``A`` is used. + Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - :: - symm(side, ul, A, B) + .. code-block:: julia + symm(side, ul, A, B) - Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed - to be symmetric. Only the ``ul`` triangle of ``A`` is used. + Returns ``A*B`` or ``B*A`` according to ``side``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - :: - symm(tA, tB, alpha, A, B) + .. code-block:: julia + symm(tA, tB, alpha, A, B) - Returns ``alpha*A*B`` or the other three variants - according to ``tA`` (transpose ``A``) and ``tB``. + Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``\ ) and ``tB``\ . .. function:: symv!(ul, alpha, A, x, beta, y) - Update the vector ``y`` as ``alpha*A*x + beta*y``. ``A`` is assumed - to be symmetric. Only the ``ul`` triangle of ``A`` is used. - Returns the updated ``y``. + .. Docstring generated from Julia source + .. code-block:: julia + symv!(ul, alpha, A, x, beta, y) + + Update the vector ``y`` as ``alpha*A*x + beta*y``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. Returns the updated ``y``\ . .. function:: symv(ul, alpha, A, x) - Returns ``alpha*A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + .. Docstring generated from Julia source + .. code-block:: julia + symv(ul, alpha, A, x) - :: - symv(ul, A, x) + Returns ``alpha*A*x``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. + + .. code-block:: julia + symv(ul, A, x) - Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + Returns ``A*x``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. .. function:: symv(ul, A, x) - :: - symv(ul, alpha, A, x) + .. Docstring generated from Julia source + .. code-block:: julia + symv(ul, alpha, A, x) - Returns ``alpha*A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + Returns ``alpha*A*x``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. - :: - symv(ul, A, x) + .. code-block:: julia + symv(ul, A, x) - Returns ``A*x``. ``A`` is assumed to be symmetric. Only the - ``ul`` triangle of ``A`` is used. + Returns ``A*x``\ . ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. .. function:: trmm!(side, ul, tA, dA, alpha, A, B) - Update ``B`` as ``alpha*A*B`` or one of the other three variants - determined by ``side`` (A on left or right) and ``tA`` (transpose ``A``). - Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if - ``A`` is unit-triangular (the diagonal is assumed to be all ones). - Returns the updated ``B``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: trmm(side, ul, tA, dA, alpha, A, B) - Returns ``alpha*A*B`` or one of the other three variants - determined by ``side`` (A on left or right) and ``tA`` (transpose ``A``). - Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if - ``A`` is unit-triangular (the diagonal is assumed to be all ones). + .. Docstring generated from Julia source + .. code-block:: julia + trmm(side, ul, tA, dA, alpha, A, B) + + Returns ``alpha*A*B`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose ``A``\ ). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular (the diagonal is assumed to be all ones). .. function:: trsm!(side, ul, tA, dA, alpha, A, B) - Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of - the other three variants determined by ``side`` (A on left or - right of ``X``) and ``tA`` (transpose ``A``). Only the ``ul`` triangle - of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular - (the diagonal is assumed to be all ones). Returns the updated ``B``. + .. Docstring generated from Julia source + .. code-block:: julia + trsm!(side, ul, tA, dA, alpha, A, B) + + Overwrite ``B`` with the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``\ ) and ``tA`` (transpose ``A``\ ). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular (the diagonal is assumed to be all ones). Returns the updated ``B``\ . .. function:: trsm(side, ul, tA, dA, alpha, A, B) - Returns the solution to ``A*X = alpha*B`` or one of - the other three variants determined by ``side`` (A on left or - right of ``X``) and ``tA`` (transpose ``A``). Only the ``ul`` triangle - of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular - (the diagonal is assumed to be all ones). + .. Docstring generated from Julia source + .. code-block:: julia + trsm(side, ul, tA, dA, alpha, A, B) + + Returns the solution to ``A*X = alpha*B`` or one of the other three variants determined by ``side`` (A on left or right of ``X``\ ) and ``tA`` (transpose ``A``\ ). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular (the diagonal is assumed to be all ones). .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) - 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). + .. Docstring generated from Julia source + .. code-block:: julia + trmv(side, ul, tA, dA, alpha, A, b) + + Returns ``alpha*A*b`` or one of the other three variants determined by ``side`` (A on left or right) and ``tA`` (transpose ``A``\ ). Only the ``ul`` triangle of ``A`` is used. ``dA`` indicates if ``A`` is unit-triangular (the diagonal is assumed to be all ones). .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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:: 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). + .. Docstring generated from Julia source + .. code-block:: julia + 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). .. function:: blas_set_num_threads(n) + .. Docstring generated from Julia source + .. code-block:: julia + blas_set_num_threads(n) + Set the number of threads the BLAS library should use. .. data:: I diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index e577792faa97c6..052f1eea07a349 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -11,48 +11,60 @@ Mathematical Operators .. function:: -(x) + .. Docstring generated from Julia source + .. code-block:: julia + -(x) + Unary minus operator. - :: - -(x, y) + .. code-block:: julia + -(x, y) Subtraction operator. .. _+: .. function:: +(x, y...) - Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. - ``+(x, y, z, ...)``. + .. Docstring generated from Julia source + .. code-block:: julia + +(x, y...) + + Addition operator. ``x+y+z+...`` calls this function with all arguments, i.e. ``+(x, y, z, ...)``\ . .. _-: .. function:: -(x, y) - :: - -(x) + .. Docstring generated from Julia source + .. code-block:: julia + -(x) Unary minus operator. - :: - -(x, y) + .. code-block:: julia + -(x, y) Subtraction operator. .. _*: .. function:: *(x, y...) + .. Docstring generated from Julia source :: + *(A, B) :noindex: Matrix multiplication :: + *(x, y...) Multiplication operator. ``x*y*z*...`` calls this function with all arguments, i.e. ``*(x, y, z, ...)``. :: + *(s, t) Concatenate strings. The ``*`` operator is an alias to this function. @@ -62,8 +74,11 @@ Mathematical Operators .. _/: .. function:: /(x, y) - Right division operator: multiplication of ``x`` by the inverse of ``y`` on the right. - Gives floating-point results for integer arguments. + .. Docstring generated from Julia source + .. code-block:: julia + /(x, y) + + Right division operator: multiplication of ``x`` by the inverse of ``y`` on the right. Gives floating-point results for integer arguments. .. _\\: .. function:: \\(x, y) @@ -74,9 +89,15 @@ Mathematical Operators .. _^: .. function:: ^(x, y) + .. Docstring generated from Julia source + :: + + ^(x, y) + Exponentiation operator. :: + ^(s, n) Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. @@ -89,21 +110,37 @@ Mathematical Operators .. _.+: .. function:: .+(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .+(x, y) + Element-wise addition operator. .. _.-: .. function:: .-(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .-(x, y) + Element-wise subtraction operator. .. _.*: .. function:: .*(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .*(x, y) + Element-wise multiplication operator. .. _./: .. function:: ./(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + ./(x, y) + Element-wise right division operator. .. _.\\: @@ -114,106 +151,170 @@ Mathematical Operators .. _.^: .. function:: .^(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .^(x, y) + Element-wise exponentiation operator. .. function:: fma(x, y, z) - Computes ``x*y+z`` without rounding the intermediate result - ``x*y``. On some systems this is significantly more expensive than - ``x*y+z``. ``fma`` is used to improve accuracy in certain - algorithms. See ``muladd``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: muladd(x, y, z) - Combined multiply-add, computes ``x*y+z`` in an efficient manner. - This may on some systems be equivalent to ``x*y+z``, or to - ``fma(x,y,z)``. ``muladd`` is used to improve performance. See - ``fma``. + .. Docstring generated from Julia source + .. code-block:: julia + muladd(x, y, z) + + Combined multiply-add, computes ``x*y+z`` in an efficient manner. This may on some systems be equivalent to ``x*y+z``\ , or to ``fma(x,y,z)``\ . ``muladd`` is used to improve performance. See ``fma``\ . .. function:: div(x, y) - :: - ÷(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + div(x, y) + ÷(x, y) - The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. + The quotient from Euclidean division. Computes ``x/y``\ , truncated to an integer. .. function:: fld(x, y) - Largest integer less than or equal to ``x/y``. + .. Docstring generated from Julia source + .. code-block:: julia + fld(x, y) + + Largest integer less than or equal to ``x/y``\ . .. function:: cld(x, y) - Smallest integer larger than or equal to ``x/y``. + .. Docstring generated from Julia source + .. code-block:: julia + cld(x, y) + + Smallest integer larger than or equal to ``x/y``\ . .. function:: mod(x, y) - Modulus after division, returning in the range [0,``y``), if ``y`` is - positive, or (``y``,0] if ``y`` is negative. + .. Docstring generated from Julia source + .. code-block:: julia + mod(x, y) + + Modulus after division, returning in the range [0,``y``\ ), if ``y`` is positive, or (``y``\ ,0] if ``y`` is negative. .. function:: mod2pi(x) + .. Docstring generated from Julia source + .. code-block:: julia + mod2pi(x) + Modulus after division by 2pi, returning in the range [0,2pi). - This function computes a floating point representation of the modulus after - division by numerically exact 2pi, and is therefore not exactly the same as - mod(x,2pi), which would compute the modulus of x relative to division by the - floating-point number 2pi. + 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) + .. Docstring generated from Julia source + .. code-block:: julia + rem(x, y) + %(x, y) - Remainder from Euclidean division, returning a value of the same sign - as``x``, and smaller in magnitude than ``y``. This value is always exact. + Remainder from Euclidean division, returning a value of the same sign as``x``\ , and smaller in magnitude than ``y``\ . This value is always exact. .. function:: divrem(x, y) - The quotient and remainder from Euclidean division. Equivalent to ``(x÷y, x%y)``. + .. Docstring generated from Julia source + .. code-block:: julia + divrem(x, y) + + The quotient and remainder from Euclidean division. Equivalent to ``(x÷y, x%y)``\ . .. function:: fldmod(x, y) - The floored quotient and modulus after division. Equivalent to ``(fld(x,y), mod(x,y))``. + .. Docstring generated from Julia source + .. code-block:: julia + fldmod(x, y) + + The floored quotient and modulus after division. Equivalent to ``(fld(x,y), mod(x,y))``\ . .. function:: mod1(x,m) + .. Docstring generated from Julia source + .. code-block:: julia + mod1(x,m) + Modulus after division, returning in the range (0,m] .. function:: rem1(x,m) + .. Docstring generated from Julia source + .. code-block:: julia + rem1(x,m) + Remainder after division, returning in the range (0,m] .. _//: .. function:: //(num, den) + .. Docstring generated from Julia source + .. code-block:: julia + //(num, den) + Divide two integers or rational numbers, giving a ``Rational`` result. .. function:: rationalize([Type=Int,] x; tol=eps(x)) - Approximate floating point number ``x`` as a Rational number with components of the given - integer type. The result will differ from ``x`` by no more than ``tol``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: num(x) + .. Docstring generated from Julia source + .. code-block:: julia + num(x) + Numerator of the rational representation of ``x`` .. function:: den(x) + .. Docstring generated from Julia source + .. code-block:: julia + den(x) + Denominator of the rational representation of ``x`` .. _<<: .. function:: <<(x, n) + .. Docstring generated from Julia source + .. code-block:: julia + <<(x, n) + Left bit shift operator. .. _>>: .. function:: >>(x, n) - Right bit shift operator, preserving the sign of ``x``. + .. Docstring generated from Julia source + .. code-block:: julia + >>(x, n) + + Right bit shift operator, preserving the sign of ``x``\ . .. _>>>: .. function:: >>>(x, n) + .. Docstring generated from Julia source + .. code-block:: julia + >>>(x, n) + Unsigned right bit shift operator. .. _\:: @@ -226,155 +327,212 @@ Mathematical Operators .. function:: colon(start, [step], stop) + .. Docstring generated from Julia source + .. code-block:: julia + colon(start, [step], stop) + Called by ``:`` syntax for constructing ranges. .. function:: range(start, [step], length) + .. Docstring generated from Julia source + .. code-block:: julia + range(start, [step], length) + Construct a range by length, given a starting value and optional step (defaults to 1). .. _==: .. function:: ==(x, y) - Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``. - Should be implemented for all types with a notion of equality, based - on the abstract value that an instance represents. For example, all numeric types are compared - by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring - encoding. + .. Docstring generated from Julia source + .. code-block:: julia + ==(x, y) + + Generic equality operator, giving a single ``Bool`` result. Falls back to ``===``\ . Should be implemented for all types with a notion of equality, based on the abstract value that an instance represents. For example, all numeric types are compared by numeric value, ignoring type. Strings are compared as sequences of characters, ignoring encoding. Follows IEEE semantics for floating-point numbers. Collections should generally implement ``==`` by calling ``==`` recursively on all contents. - New numeric types should implement this function for two arguments of the new type, and handle - comparison to other types via promotion rules where possible. + New numeric types should implement this function for two arguments of the new type, and handle comparison to other types via promotion rules where possible. .. _!=: .. function:: !=(x, y) - :: - ≠(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + !=(x, y) + ≠(x,y) - Not-equals comparison operator. Always gives the opposite answer as ``==``. - New types should generally not implement this, and rely on the fallback - definition ``!=(x,y) = !(x==y)`` instead. + Not-equals comparison operator. Always gives the opposite answer as ``==``\ . New types should generally not implement this, and rely on the fallback definition ``!=(x,y) = !(x==y)`` instead. .. _===: .. function:: ===(x, y) - :: - is(x, y) -> Bool - ===(x,y) -> Bool - ≡(x,y) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + is(x, y) -> Bool + ===(x,y) -> Bool + ≡(x,y) -> Bool - Determine whether ``x`` and ``y`` are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called ``egal``. + Determine whether ``x`` and ``y`` are identical, in the sense that no program could distinguish them. Compares mutable objects by address in memory, and compares immutable objects (such as numbers) by contents at the bit level. This function is sometimes called ``egal``\ . .. _!==: .. function:: !==(x, y) - :: - ≢(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + !==(x, y) + ≢(x,y) Equivalent to ``!is(x, y)`` .. _<: .. function:: <(x, y) - Less-than comparison operator. New numeric types should implement this function - for two arguments of the new type. - Because of the behavior of floating-point NaN values, ``<`` implements a - partial order. Types with a canonical partial order should implement ``<``, and - types with a canonical total order should implement ``isless``. + .. Docstring generated from Julia source + .. code-block:: julia + <(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) + .. Docstring generated from Julia source + .. code-block:: julia + <=(x, y) + ≤(x,y) Less-than-or-equals comparison operator. .. _>: .. function:: >(x, y) - Greater-than comparison operator. Generally, new types should implement ``<`` - instead of this function, and rely on the fallback definition ``>(x,y) = y(x, y) + + Greater-than comparison operator. Generally, new types should implement ``<`` instead of this function, and rely on the fallback definition ``>(x,y) = y=: .. function:: >=(x, y) - :: - ≥(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + >=(x, y) + ≥(x,y) Greater-than-or-equals comparison operator. .. _.==: .. function:: .==(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .==(x, y) + Element-wise equality comparison operator. .. _.!=: .. function:: .!=(x, y) - :: - .≠(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + .!=(x, y) + .≠(x,y) Element-wise not-equals comparison operator. .. _.<: .. function:: .<(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .<(x, y) + Element-wise less-than comparison operator. .. _.<=: .. function:: .<=(x, y) - :: - .≤(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + .<=(x, y) + .≤(x,y) Element-wise less-than-or-equals comparison operator. .. _.>: .. function:: .>(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + .>(x, y) + Element-wise greater-than comparison operator. .. _.>=: .. function:: .>=(x, y) - :: - .≥(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + .>=(x, y) + .≥(x,y) Element-wise greater-than-or-equals comparison operator. .. function:: cmp(x,y) - Return -1, 0, or 1 depending on whether ``x`` is less than, equal to, or greater - than ``y``, respectively. Uses the total order implemented by ``isless``. For - floating-point numbers, uses ``<`` but throws an error for unordered arguments. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + ~(x) + Bitwise not .. _&: .. function:: &(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + &(x, y) + Bitwise and .. _|: .. function:: |(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + |(x, y) + Bitwise or .. _$: .. function:: $(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + \$(x, y) + Bitwise exclusive or .. _!: .. function:: !(x) + .. Docstring generated from Julia source + .. code-block:: julia + !(x) + Boolean not .. _&&: @@ -389,14 +547,30 @@ Mathematical Operators .. function:: A_ldiv_Bc(a,b) + .. Docstring generated from Julia source + :: + + A_ldiv_Bc(a,b) + Matrix operator A \\ B\ :sup:`H` .. function:: A_ldiv_Bt(a,b) + .. Docstring generated from Julia source + :: + + A_ldiv_Bt(a,b) + Matrix operator A \\ B\ :sup:`T` .. function:: A_mul_B!(Y, A, B) -> Y + .. Docstring generated from Julia source + :: + + 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*. @@ -411,66 +585,146 @@ Mathematical Operators .. function:: A_mul_Bc(...) + .. Docstring generated from Julia source + :: + + A_mul_Bc(...) + Matrix operator A B\ :sup:`H` .. function:: A_mul_Bt(...) + .. Docstring generated from Julia source + :: + + A_mul_Bt(...) + Matrix operator A B\ :sup:`T` .. function:: A_rdiv_Bc(...) + .. Docstring generated from Julia source + :: + + A_rdiv_Bc(...) + Matrix operator A / B\ :sup:`H` .. function:: A_rdiv_Bt(a,b) + .. Docstring generated from Julia source + :: + + A_rdiv_Bt(a,b) + Matrix operator A / B\ :sup:`T` .. function:: Ac_ldiv_B(...) + .. Docstring generated from Julia source + :: + + Ac_ldiv_B(...) + Matrix operator A\ :sup:`H` \\ B .. function:: Ac_ldiv_Bc(...) + .. Docstring generated from Julia source + :: + + Ac_ldiv_Bc(...) + Matrix operator A\ :sup:`H` \\ B\ :sup:`H` .. function:: Ac_mul_B(...) + .. Docstring generated from Julia source + :: + + Ac_mul_B(...) + Matrix operator A\ :sup:`H` B .. function:: Ac_mul_Bc(...) + .. Docstring generated from Julia source + :: + + Ac_mul_Bc(...) + Matrix operator A\ :sup:`H` B\ :sup:`H` .. function:: Ac_rdiv_B(a,b) + .. Docstring generated from Julia source + :: + + Ac_rdiv_B(a,b) + Matrix operator A\ :sup:`H` / B .. function:: Ac_rdiv_Bc(a,b) + .. Docstring generated from Julia source + :: + + Ac_rdiv_Bc(a,b) + Matrix operator A\ :sup:`H` / B\ :sup:`H` .. function:: At_ldiv_B(...) + .. Docstring generated from Julia source + :: + + At_ldiv_B(...) + Matrix operator A\ :sup:`T` \\ B .. function:: At_ldiv_Bt(...) + .. Docstring generated from Julia source + :: + + At_ldiv_Bt(...) + Matrix operator A\ :sup:`T` \\ B\ :sup:`T` .. function:: At_mul_B(...) + .. Docstring generated from Julia source + :: + + At_mul_B(...) + Matrix operator A\ :sup:`T` B .. function:: At_mul_Bt(...) + .. Docstring generated from Julia source + :: + + At_mul_Bt(...) + Matrix operator A\ :sup:`T` B\ :sup:`T` .. function:: At_rdiv_B(a,b) + .. Docstring generated from Julia source + :: + + At_rdiv_B(a,b) + Matrix operator A\ :sup:`T` / B .. function:: At_rdiv_Bt(a,b) + .. Docstring generated from Julia source + :: + + At_rdiv_Bt(a,b) + Matrix operator A\ :sup:`T` / B\ :sup:`T` Mathematical Functions @@ -478,272 +732,502 @@ Mathematical Functions .. function:: isapprox(x, y; rtol::Real=sqrt(eps), atol::Real=0) - Inexact equality comparison: ``true`` if ``norm(x-y) <= atol + rtol*max(norm(x), norm(y))``. The default ``atol`` is zero and the default ``rtol`` depends on the types of ``x`` and ``y``. + .. Docstring generated from Julia source + .. code-block:: julia + isapprox(x, y; rtol::Real=sqrt(eps), atol::Real=0) - For real or complex floating-point values, ``rtol`` defaults to ``sqrt(eps(typeof(real(x-y))))``. This corresponds to requiring equality of about half of the significand digits. For other types, ``rtol`` defaults to zero. + Inexact equality comparison: ``true`` if ``norm(x-y) <= atol + rtol*max(norm(x), norm(y))``\ . The default ``atol`` is zero and the default ``rtol`` depends on the types of ``x`` and ``y``\ . - ``x`` and ``y`` may also be arrays of numbers, in which case ``norm`` - defaults to ``vecnorm`` but may be changed by passing a - ``norm::Function`` keyword argument. (For numbers, ``norm`` is the - same thing as ``abs``.) + For real or complex floating-point values, ``rtol`` defaults to ``sqrt(eps(typeof(real(x-y))))``\ . This corresponds to requiring equality of about half of the significand digits. For other types, ``rtol`` defaults to zero. - The binary operator ``≈`` is equivalent to ``isapprox`` with the default arguments, and ``x ≉ y`` is equivalent to ``!isapprox(x,y)``. + ``x`` and ``y`` may also be arrays of numbers, in which case ``norm`` defaults to ``vecnorm`` but may be changed by passing a ``norm::Function`` keyword argument. (For numbers, ``norm`` is the same thing as ``abs``\ .) + + The binary operator ``≈`` is equivalent to ``isapprox`` with the default arguments, and ``x ≉ y`` is equivalent to ``!isapprox(x,y)``\ . .. function:: sin(x) - Compute sine of ``x``, where ``x`` is in radians + .. Docstring generated from Julia source + .. code-block:: julia + sin(x) + + Compute sine of ``x``\ , where ``x`` is in radians .. function:: cos(x) - Compute cosine of ``x``, where ``x`` is in radians + .. Docstring generated from Julia source + .. code-block:: julia + cos(x) + + Compute cosine of ``x``\ , where ``x`` is in radians .. function:: tan(x) - Compute tangent of ``x``, where ``x`` is in radians + .. Docstring generated from Julia source + .. code-block:: julia + tan(x) + + Compute tangent of ``x``\ , where ``x`` is in radians .. function:: sind(x) - Compute sine of ``x``, where ``x`` is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + sind(x) + + Compute sine of ``x``\ , where ``x`` is in degrees .. function:: cosd(x) - Compute cosine of ``x``, where ``x`` is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + cosd(x) + + Compute cosine of ``x``\ , where ``x`` is in degrees .. function:: tand(x) - Compute tangent of ``x``, where ``x`` is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + tand(x) + + Compute tangent of ``x``\ , where ``x`` is in degrees .. function:: sinpi(x) + .. Docstring generated from Julia source + :: + + sinpi(x) + Compute :math:`\sin(\pi x)` more accurately than ``sin(pi*x)``, especially for large ``x``. .. function:: cospi(x) + .. Docstring generated from Julia source + :: + + cospi(x) + Compute :math:`\cos(\pi x)` more accurately than ``cos(pi*x)``, especially for large ``x``. .. function:: sinh(x) + .. Docstring generated from Julia source + .. code-block:: julia + sinh(x) + Compute hyperbolic sine of ``x`` .. function:: cosh(x) + .. Docstring generated from Julia source + .. code-block:: julia + cosh(x) + Compute hyperbolic cosine of ``x`` .. function:: tanh(x) + .. Docstring generated from Julia source + .. code-block:: julia + tanh(x) + Compute hyperbolic tangent of ``x`` .. function:: asin(x) - Compute the inverse sine of ``x``, where the output is in radians + .. Docstring generated from Julia source + .. code-block:: julia + asin(x) + + Compute the inverse sine of ``x``\ , where the output is in radians .. function:: acos(x) - Compute the inverse cosine of ``x``, where the output is in radians + .. Docstring generated from Julia source + .. code-block:: julia + acos(x) + + Compute the inverse cosine of ``x``\ , where the output is in radians .. function:: atan(x) - Compute the inverse tangent of ``x``, where the output is in radians + .. Docstring generated from Julia source + .. code-block:: julia + atan(x) + + Compute the inverse tangent of ``x``\ , where the output is in radians .. function:: atan2(y, x) - Compute the inverse tangent of ``y/x``, using the signs of both ``x`` and ``y`` to determine the quadrant of the return value. + .. Docstring generated from Julia source + .. code-block:: julia + atan2(y, x) + + Compute the inverse tangent of ``y/x``\ , using the signs of both ``x`` and ``y`` to determine the quadrant of the return value. .. function:: asind(x) - Compute the inverse sine of ``x``, where the output is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + asind(x) + + Compute the inverse sine of ``x``\ , where the output is in degrees .. function:: acosd(x) - Compute the inverse cosine of ``x``, where the output is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + acosd(x) + + Compute the inverse cosine of ``x``\ , where the output is in degrees .. function:: atand(x) - Compute the inverse tangent of ``x``, where the output is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + atand(x) + + Compute the inverse tangent of ``x``\ , where the output is in degrees .. function:: sec(x) - Compute the secant of ``x``, where ``x`` is in radians + .. Docstring generated from Julia source + .. code-block:: julia + sec(x) + + Compute the secant of ``x``\ , where ``x`` is in radians .. function:: csc(x) - Compute the cosecant of ``x``, where ``x`` is in radians + .. Docstring generated from Julia source + .. code-block:: julia + csc(x) + + Compute the cosecant of ``x``\ , where ``x`` is in radians .. function:: cot(x) - Compute the cotangent of ``x``, where ``x`` is in radians + .. Docstring generated from Julia source + .. code-block:: julia + cot(x) + + Compute the cotangent of ``x``\ , where ``x`` is in radians .. function:: secd(x) - Compute the secant of ``x``, where ``x`` is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + secd(x) + + Compute the secant of ``x``\ , where ``x`` is in degrees .. function:: cscd(x) - Compute the cosecant of ``x``, where ``x`` is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + cscd(x) + + Compute the cosecant of ``x``\ , where ``x`` is in degrees .. function:: cotd(x) - Compute the cotangent of ``x``, where ``x`` is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + cotd(x) + + Compute the cotangent of ``x``\ , where ``x`` is in degrees .. function:: asec(x) - Compute the inverse secant of ``x``, where the output is in radians + .. Docstring generated from Julia source + .. code-block:: julia + asec(x) + + Compute the inverse secant of ``x``\ , where the output is in radians .. function:: acsc(x) - Compute the inverse cosecant of ``x``, where the output is in radians + .. Docstring generated from Julia source + .. code-block:: julia + acsc(x) + + Compute the inverse cosecant of ``x``\ , where the output is in radians .. function:: acot(x) - Compute the inverse cotangent of ``x``, where the output is in radians + .. Docstring generated from Julia source + .. code-block:: julia + acot(x) + + Compute the inverse cotangent of ``x``\ , where the output is in radians .. function:: asecd(x) - Compute the inverse secant of ``x``, where the output is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + asecd(x) + + Compute the inverse secant of ``x``\ , where the output is in degrees .. function:: acscd(x) - Compute the inverse cosecant of ``x``, where the output is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + acscd(x) + + Compute the inverse cosecant of ``x``\ , where the output is in degrees .. function:: acotd(x) - Compute the inverse cotangent of ``x``, where the output is in degrees + .. Docstring generated from Julia source + .. code-block:: julia + acotd(x) + + Compute the inverse cotangent of ``x``\ , where the output is in degrees .. function:: sech(x) + .. Docstring generated from Julia source + .. code-block:: julia + sech(x) + Compute the hyperbolic secant of ``x`` .. function:: csch(x) + .. Docstring generated from Julia source + .. code-block:: julia + csch(x) + Compute the hyperbolic cosecant of ``x`` .. function:: coth(x) + .. Docstring generated from Julia source + .. code-block:: julia + coth(x) + Compute the hyperbolic cotangent of ``x`` .. function:: asinh(x) + .. Docstring generated from Julia source + .. code-block:: julia + asinh(x) + Compute the inverse hyperbolic sine of ``x`` .. function:: acosh(x) + .. Docstring generated from Julia source + .. code-block:: julia + acosh(x) + Compute the inverse hyperbolic cosine of ``x`` .. function:: atanh(x) + .. Docstring generated from Julia source + .. code-block:: julia + atanh(x) + Compute the inverse hyperbolic tangent of ``x`` .. function:: asech(x) + .. Docstring generated from Julia source + .. code-block:: julia + asech(x) + Compute the inverse hyperbolic secant of ``x`` .. function:: acsch(x) + .. Docstring generated from Julia source + .. code-block:: julia + acsch(x) + Compute the inverse hyperbolic cosecant of ``x`` .. function:: acoth(x) + .. Docstring generated from Julia source + .. code-block:: julia + acoth(x) + Compute the inverse hyperbolic cotangent of ``x`` .. function:: sinc(x) + .. Docstring generated from Julia source + :: + + sinc(x) + Compute :math:`\sin(\pi x) / (\pi x)` if :math:`x \neq 0`, and :math:`1` if :math:`x = 0`. .. function:: cosc(x) + .. Docstring generated from Julia source + :: + + cosc(x) + Compute :math:`\cos(\pi x) / x - \sin(\pi x) / (\pi x^2)` if :math:`x \neq 0`, and :math:`0` if :math:`x = 0`. This is the derivative of ``sinc(x)``. .. function:: deg2rad(x) + .. Docstring generated from Julia source + .. code-block:: julia + deg2rad(x) + Convert ``x`` from degrees to radians .. function:: rad2deg(x) + .. Docstring generated from Julia source + .. code-block:: julia + rad2deg(x) + Convert ``x`` from radians to degrees .. function:: hypot(x, y) + .. Docstring generated from Julia source + :: + + hypot(x, y) + Compute the :math:`\sqrt{x^2+y^2}` avoiding overflow and underflow .. function:: log(x) - Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative - ``Real`` arguments. Use complex negative arguments to obtain complex - results. + .. Docstring generated from Julia source + .. code-block:: julia + log(x) - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. + Compute the natural logarithm of ``x``\ . Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments to obtain complex results. - :: - log(b,x) + There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. + .. code-block:: julia + log(b,x) + + Compute the base ``b`` logarithm of ``x``\ . Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log(b,x) - :: - log(x) + .. Docstring generated from Julia source + .. code-block:: julia + log(x) - Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative - ``Real`` arguments. Use complex negative arguments to obtain complex - results. + Compute the natural logarithm of ``x``\ . Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments to obtain complex results. - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. + There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. - :: - log(b,x) + .. code-block:: julia + log(b,x) - Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. + Compute the base ``b`` logarithm of ``x``\ . Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log2(x) + .. Docstring generated from Julia source + .. code-block:: julia + log2(x) + Compute the logarithm of ``x`` to base 2. Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log10(x) + .. Docstring generated from Julia source + .. code-block:: julia + log10(x) + Compute the logarithm of ``x`` to base 10. Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log1p(x) - Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for ``Real`` arguments less than -1. + .. Docstring generated from Julia source + .. code-block:: julia + log1p(x) + + Accurate natural logarithm of ``1+x``\ . Throws ``DomainError`` for ``Real`` arguments less than -1. - There is an experimental variant in the ``Base.Math.JuliaLibm`` module, - which is typically faster and more accurate. + There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. .. function:: frexp(val) + .. Docstring generated from Julia source + :: + + frexp(val) + Return ``(x,exp)`` such that ``x`` has a magnitude in the interval ``[1/2, 1)`` or 0, and val = :math:`x \times 2^{exp}`. .. function:: exp(x) + .. Docstring generated from Julia source + :: + + exp(x) + Compute :math:`e^x` .. function:: exp2(x) + .. Docstring generated from Julia source + :: + + exp2(x) + Compute :math:`2^x` .. function:: exp10(x) + .. Docstring generated from Julia source + :: + + exp10(x) + Compute :math:`10^x` .. function:: ldexp(x, n) + .. Docstring generated from Julia source + :: + + ldexp(x, n) + Compute :math:`x \times 2^n` .. function:: modf(x) - Return a tuple (fpart,ipart) of the fractional and integral parts of a - number. Both parts have the same sign as the argument. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + expm1(x) + Accurately compute :math:`e^x-1` .. function:: round([T,] x, [digits, [base]], [r::RoundingMode]) + .. Docstring generated from Julia source + :: + + 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 @@ -773,6 +1257,7 @@ Mathematical Functions .. doctest:: :: + round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex-valued @@ -847,7 +1332,9 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) + .. Docstring generated from Julia source :: + round([T,] x, [digits, [base]], [r::RoundingMode]) ``round(x)`` rounds ``x`` to an integer value according to the default @@ -879,6 +1366,7 @@ Mathematical Functions .. doctest:: :: + round(z, RoundingModeReal, RoundingModeImaginary) Returns the nearest integral value of the same type as the complex-valued @@ -888,6 +1376,11 @@ Mathematical Functions .. function:: ceil([T,] x, [digits, [base]]) + .. Docstring generated from Julia source + :: + + ceil([T,] x, [digits, [base]]) + ``ceil(x)`` returns the nearest integral value of the same type as ``x`` that is greater than or equal to ``x``. @@ -898,6 +1391,11 @@ Mathematical Functions .. function:: floor([T,] x, [digits, [base]]) + .. Docstring generated from Julia source + :: + + 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``. @@ -908,7 +1406,9 @@ Mathematical Functions .. function:: trunc([T,] x, [digits, [base]]) + .. Docstring generated from Julia source :: + trunc(dt::TimeType, ::Type{Period}) -> TimeType Truncates the value of ``dt`` according to the provided ``Period`` type. @@ -916,80 +1416,156 @@ Mathematical Functions .. function:: unsafe_trunc(T, x) - ``unsafe_trunc(T, x)`` returns the nearest integral value of type ``T`` whose absolute - value is less than or equal to ``x``. If the value is not representable by - ``T``, an arbitrary value will be returned. + .. Docstring generated from Julia source + .. code-block:: julia + unsafe_trunc(T, x) + + ``unsafe_trunc(T, x)`` returns the nearest integral value of type ``T`` whose absolute value is less than or equal to ``x``\ . If the value is not representable by ``T``\ , an arbitrary value will be returned. .. function:: signif(x, digits, [base]) - Rounds (in the sense of ``round``) ``x`` so that there are ``digits`` significant digits, under a base ``base`` representation, default 10. E.g., ``signif(123.456, 2)`` is ``120.0``, and ``signif(357.913, 4, 2)`` is ``352.0``. + .. Docstring generated from Julia source + .. code-block:: julia + signif(x, digits, [base]) + + Rounds (in the sense of ``round``\ ) ``x`` so that there are ``digits`` significant digits, under a base ``base`` representation, default 10. E.g., ``signif(123.456, 2)`` is ``120.0``\ , and ``signif(357.913, 4, 2)`` is ``352.0``\ . .. function:: min(x, y, ...) + .. Docstring generated from Julia source + .. code-block:: julia + min(x, y, ...) + Return the minimum of the arguments. Operates elementwise over arrays. .. function:: max(x, y, ...) + .. Docstring generated from Julia source + .. code-block:: julia + max(x, y, ...) + Return the maximum of the arguments. Operates elementwise over arrays. .. function:: minmax(x, y) + .. Docstring generated from Julia source + :: + + minmax(x, y) + Return ``(min(x,y), max(x,y))``. See also: :func:`extrema` that returns ``(minimum(x), maximum(x))`` .. function:: clamp(x, lo, hi) - Return x if ``lo <= x <= hi``. If ``x < lo``, return ``lo``. If ``x > hi``, return ``hi``. Arguments are promoted to a common type. Operates elementwise over ``x`` if it is an array. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + abs(x) + Absolute value of ``x`` .. function:: abs2(x) + .. Docstring generated from Julia source + .. code-block:: julia + abs2(x) + Squared absolute value of ``x`` .. function:: copysign(x, y) + .. Docstring generated from Julia source + .. code-block:: julia + copysign(x, y) + Return ``x`` such that it has the same sign as ``y`` .. function:: sign(x) + .. Docstring generated from Julia source + :: + + sign(x) Return zero if ``x==0`` and :math:`x/|x|` otherwise (i.e., ±1 for real ``x``). .. function:: signbit(x) - Returns ``true`` if the value of the sign of ``x`` is negative, otherwise ``false``. + .. Docstring generated from Julia source + .. code-block:: julia + signbit(x) + + Returns ``true`` if the value of the sign of ``x`` is negative, otherwise ``false``\ . .. function:: flipsign(x, y) - Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``. + .. Docstring generated from Julia source + .. code-block:: julia + flipsign(x, y) + + Return ``x`` with its sign flipped if ``y`` is negative. For example ``abs(x) = flipsign(x,x)``\ . .. function:: sqrt(x) + .. Docstring generated from Julia source + :: + + sqrt(x) + 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) - Integer square root: the largest integer ``m`` such that ``m*m <= n``. + .. Docstring generated from Julia source + .. code-block:: julia + isqrt(n) + + Integer square root: the largest integer ``m`` such that ``m*m <= n``\ . .. function:: cbrt(x) + .. Docstring generated from Julia source + :: + + cbrt(x) + Return :math:`x^{1/3}`. The prefix operator ``∛`` is equivalent to ``cbrt``. .. function:: erf(x) + .. Docstring generated from Julia source + :: + + erf(x) + Compute the error function of ``x``, defined by :math:`\frac{2}{\sqrt{\pi}} \int_0^x e^{-t^2} dt` for arbitrary complex ``x``. .. function:: erfc(x) + .. Docstring generated from Julia source + :: + + erfc(x) + Compute the complementary error function of ``x``, defined by :math:`1 - \operatorname{erf}(x)`. .. function:: erfcx(x) + .. Docstring generated from Julia source + :: + + 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 @@ -997,54 +1573,108 @@ Mathematical Functions .. function:: erfi(x) + .. Docstring generated from Julia source + :: + + erfi(x) + Compute the imaginary error function of ``x``, defined by :math:`-i \operatorname{erf}(ix)`. .. function:: dawson(x) + .. Docstring generated from Julia source + :: + + 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)`. .. function:: erfinv(x) + .. Docstring generated from Julia source + :: + + erfinv(x) + Compute the inverse error function of a real ``x``, defined by :math:`\operatorname{erf}(\operatorname{erfinv}(x)) = x`. .. function:: erfcinv(x) + .. Docstring generated from Julia source + :: + + erfcinv(x) + Compute the inverse error complementary function of a real ``x``, defined by :math:`\operatorname{erfc}(\operatorname{erfcinv}(x)) = x`. .. function:: real(z) + .. Docstring generated from Julia source + .. code-block:: julia + real(z) + Return the real part of the complex number ``z`` .. function:: imag(z) + .. Docstring generated from Julia source + .. code-block:: julia + imag(z) + Return the imaginary part of the complex number ``z`` .. function:: reim(z) + .. Docstring generated from Julia source + .. code-block:: julia + reim(z) + Return both the real and imaginary parts of the complex number ``z`` .. function:: conj(z) + .. Docstring generated from Julia source + .. code-block:: julia + conj(z) + Compute the complex conjugate of a complex number ``z`` .. function:: angle(z) + .. Docstring generated from Julia source + .. code-block:: julia + angle(z) + Compute the phase angle in radians of a complex number ``z`` .. function:: cis(z) + .. Docstring generated from Julia source + :: + + cis(z) + Return :math:`\exp(iz)`. .. function:: binomial(n,k) + .. Docstring generated from Julia source + .. code-block:: julia + binomial(n,k) + Number of ways to choose ``k`` out of ``n`` items .. function:: factorial(n) + .. Docstring generated from Julia source + :: + + factorial(n) + Factorial of ``n``. If ``n`` is an :obj:`Integer`, the factorial is computed as an integer (promoted to at least 64 bits). Note that this may overflow if ``n`` is not small, but you can use @@ -1053,13 +1683,16 @@ Mathematical Functions equivalent to :func:`gamma(n+1) `. :: + factorial(n,k) Compute ``factorial(n)/factorial(k)`` .. function:: factorial(n,k) + .. Docstring generated from Julia source :: + factorial(n) Factorial of ``n``. If ``n`` is an :obj:`Integer`, the factorial @@ -1070,12 +1703,18 @@ Mathematical Functions equivalent to :func:`gamma(n+1) `. :: + factorial(n,k) Compute ``factorial(n)/factorial(k)`` .. function:: factor(n) -> Dict + .. Docstring generated from Julia source + :: + + factor(n) -> Dict + Compute the prime factorization of an integer ``n``. Returns a dictionary. The keys of the dictionary correspond to the factors, and hence are of the same type as ``n``. The value associated with each key indicates the number of times the factor appears in the factorization. .. doctest:: @@ -1087,14 +1726,27 @@ Mathematical Functions .. function:: gcd(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + gcd(x,y) + Greatest common (positive) divisor (or zero if x and y are both zero). .. function:: lcm(x,y) + .. Docstring generated from Julia source + .. code-block:: julia + lcm(x,y) + Least common (non-negative) multiple. .. function:: gcdx(x,y) + .. Docstring generated from Julia source + :: + + gcdx(x,y) + Computes the greatest common (positive) divisor of ``x`` and ``y`` and their Bézout coefficients, i.e. the integer coefficients ``u`` and ``v`` that satisfy :math:`ux+vy = d = gcd(x,y)`. .. doctest:: @@ -1113,188 +1765,392 @@ Mathematical Functions .. function:: ispow2(n) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + ispow2(n) -> Bool + Test whether ``n`` is a power of two .. function:: nextpow2(n) - The smallest power of two not less than ``n``. Returns 0 for ``n==0``, and returns - ``-nextpow2(-n)`` for negative arguments. + .. Docstring generated from Julia source + .. code-block:: julia + nextpow2(n) + + The smallest power of two not less than ``n``\ . Returns 0 for ``n==0``\ , and returns ``-nextpow2(-n)`` for negative arguments. .. function:: prevpow2(n) - The largest power of two not greater than ``n``. Returns 0 for ``n==0``, and returns - ``-prevpow2(-n)`` for negative arguments. + .. Docstring generated from Julia source + .. code-block:: julia + prevpow2(n) + + The largest power of two not greater than ``n``\ . Returns 0 for ``n==0``\ , and returns ``-prevpow2(-n)`` for negative arguments. .. function:: nextpow(a, x) - The smallest ``a^n`` not less than ``x``, where ``n`` is a non-negative integer. - ``a`` must be greater than 1, and ``x`` must be greater than 0. + .. Docstring generated from Julia source + .. code-block:: julia + nextpow(a, x) + + The smallest ``a^n`` not less than ``x``\ , where ``n`` is a non-negative integer. ``a`` must be greater than 1, and ``x`` must be greater than 0. .. function:: prevpow(a, x) - The largest ``a^n`` not greater than ``x``, where ``n`` is a non-negative integer. - ``a`` must be greater than 1, and ``x`` must not be less than 1. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + 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. .. function:: prevprod([k_1,k_2,...], n) + .. Docstring generated from Julia source + :: + + prevprod([k_1,k_2,...], n) + Previous integer not greater than ``n`` that can be written as :math:`\prod k_i^{p_i}` for integers :math:`p_1`, :math:`p_2`, etc. .. function:: invmod(x,m) + .. Docstring generated from Julia source + :: + + invmod(x,m) + Take the inverse of ``x`` modulo ``m``: ``y`` such that :math:`xy = 1 \pmod m` .. function:: powermod(x, p, m) + .. Docstring generated from Julia source + :: + + powermod(x, p, m) + Compute :math:`x^p \pmod m` .. function:: gamma(x) + .. Docstring generated from Julia source + .. code-block:: julia + gamma(x) + Compute the gamma function of ``x`` .. function:: lgamma(x) + .. Docstring generated from Julia source + :: + + lgamma(x) + Compute the logarithm of the absolute value of :func:`gamma` for :obj:`Real` ``x``, while for :obj:`Complex` ``x`` it computes the logarithm of ``gamma(x)``. .. function:: lfact(x) + .. Docstring generated from Julia source + .. code-block:: julia + lfact(x) + Compute the logarithmic factorial of ``x`` .. function:: digamma(x) - Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(x)``) + .. Docstring generated from Julia source + .. code-block:: julia + digamma(x) + + Compute the digamma function of ``x`` (the logarithmic derivative of ``gamma(x)``\ ) .. function:: invdigamma(x) - Compute the inverse digamma function of ``x``. + .. Docstring generated from Julia source + .. code-block:: julia + invdigamma(x) + + Compute the inverse digamma function of ``x``\ . .. function:: trigamma(x) - Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``) + .. Docstring generated from Julia source + .. code-block:: julia + trigamma(x) + + Compute the trigamma function of ``x`` (the logarithmic second derivative of ``gamma(x)``\ ) .. function:: polygamma(m, x) - Compute the polygamma function of order ``m`` of argument ``x`` (the ``(m+1)th`` derivative of the logarithm of ``gamma(x)``) + .. Docstring generated from Julia source + .. code-block:: julia + polygamma(m, x) + + Compute the polygamma function of order ``m`` of argument ``x`` (the ``(m+1)th`` derivative of the logarithm of ``gamma(x)``\ ) .. function:: airy(k,x) + .. Docstring generated from Julia source + :: + + airy(k,x) + kth derivative of the Airy function :math:`\operatorname{Ai}(x)`. .. function:: airyai(x) + .. Docstring generated from Julia source + :: + + airyai(x) + Airy function :math:`\operatorname{Ai}(x)`. .. function:: airyprime(x) + .. Docstring generated from Julia source + :: + + airyprime(x) + Airy function derivative :math:`\operatorname{Ai}'(x)`. .. function:: airyaiprime(x) + .. Docstring generated from Julia source + :: + + airyaiprime(x) + Airy function derivative :math:`\operatorname{Ai}'(x)`. .. function:: airybi(x) + .. Docstring generated from Julia source + :: + + airybi(x) + Airy function :math:`\operatorname{Bi}(x)`. .. function:: airybiprime(x) + .. Docstring generated from Julia source + :: + + airybiprime(x) + Airy function derivative :math:`\operatorname{Bi}'(x)`. .. function:: airyx(k,x) + .. Docstring generated from Julia source + :: + + 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:: besselj0(x) + .. Docstring generated from Julia source + :: + + besselj0(x) + Bessel function of the first kind of order 0, :math:`J_0(x)`. .. function:: besselj1(x) + .. Docstring generated from Julia source + :: + + besselj1(x) + Bessel function of the first kind of order 1, :math:`J_1(x)`. .. function:: besselj(nu, x) + .. Docstring generated from Julia source + :: + + besselj(nu, x) + Bessel function of the first kind of order ``nu``, :math:`J_\nu(x)`. .. function:: besseljx(nu, x) + .. Docstring generated from Julia source + :: + + besseljx(nu, x) + Scaled Bessel function of the first kind of order ``nu``, :math:`J_\nu(x) e^{- | \operatorname{Im}(x) |}`. .. function:: bessely0(x) + .. Docstring generated from Julia source + :: + + bessely0(x) + Bessel function of the second kind of order 0, :math:`Y_0(x)`. .. function:: bessely1(x) + .. Docstring generated from Julia source + :: + + bessely1(x) + Bessel function of the second kind of order 1, :math:`Y_1(x)`. .. function:: bessely(nu, x) + .. Docstring generated from Julia source + :: + + bessely(nu, x) + Bessel function of the second kind of order ``nu``, :math:`Y_\nu(x)`. .. function:: besselyx(nu, x) + .. Docstring generated from Julia source + :: + + besselyx(nu, x) + Scaled Bessel function of the second kind of order ``nu``, :math:`Y_\nu(x) e^{- | \operatorname{Im}(x) |}`. .. function:: hankelh1(nu, x) + .. Docstring generated from Julia source + :: + + hankelh1(nu, x) + Bessel function of the third kind of order ``nu``, :math:`H^{(1)}_\nu(x)`. .. function:: hankelh1x(nu, x) + .. Docstring generated from Julia source + :: + + hankelh1x(nu, x) + Scaled Bessel function of the third kind of order ``nu``, :math:`H^{(1)}_\nu(x) e^{-x i}`. .. function:: hankelh2(nu, x) + .. Docstring generated from Julia source + :: + + hankelh2(nu, x) + Bessel function of the third kind of order ``nu``, :math:`H^{(2)}_\nu(x)`. .. function:: hankelh2x(nu, x) + .. Docstring generated from Julia source + :: + + hankelh2x(nu, x) + Scaled Bessel function of the third kind of order ``nu``, :math:`H^{(2)}_\nu(x) e^{x i}`. .. function:: besselh(nu, k, x) - Bessel function of the third kind of order ``nu`` (Hankel function). - ``k`` is either 1 or 2, selecting ``hankelh1`` or ``hankelh2``, respectively. + .. Docstring generated from Julia source + .. code-block:: julia + besselh(nu, k, x) + + Bessel function of the third kind of order ``nu`` (Hankel function). ``k`` is either 1 or 2, selecting ``hankelh1`` or ``hankelh2``\ , respectively. .. function:: besseli(nu, x) + .. Docstring generated from Julia source + :: + + besseli(nu, x) + Modified Bessel function of the first kind of order ``nu``, :math:`I_\nu(x)`. .. function:: besselix(nu, x) + .. Docstring generated from Julia source + :: + + besselix(nu, x) + Scaled modified Bessel function of the first kind of order ``nu``, :math:`I_\nu(x) e^{- | \operatorname{Re}(x) |}`. .. function:: besselk(nu, x) + .. Docstring generated from Julia source + :: + + besselk(nu, x) + Modified Bessel function of the second kind of order ``nu``, :math:`K_\nu(x)`. .. function:: besselkx(nu, x) + .. Docstring generated from Julia source + :: + + besselkx(nu, x) + Scaled modified Bessel function of the second kind of order ``nu``, :math:`K_\nu(x) e^x`. .. function:: beta(x, y) + .. Docstring generated from Julia source + :: + + beta(x, y) + Euler integral of the first kind :math:`\operatorname{B}(x,y) = \Gamma(x)\Gamma(y)/\Gamma(x+y)`. .. function:: lbeta(x, y) + .. Docstring generated from Julia source + :: + + lbeta(x, y) + Natural logarithm of the absolute value of the beta function :math:`\log(|\operatorname{B}(x,y)|)`. .. function:: eta(x) + .. Docstring generated from Julia source + :: + + eta(x) + Dirichlet eta function :math:`\eta(s) = \sum^\infty_{n=1}(-)^{n-1}/n^{s}`. .. function:: zeta(s) + .. Docstring generated from Julia source + :: + + zeta(s) + Riemann zeta function :math:`\zeta(s)`. :: + zeta(s, z) Hurwitz zeta function :math:`\zeta(s, z)`. (This is equivalent to @@ -1302,12 +2158,15 @@ Mathematical Functions .. function:: zeta(s, z) + .. Docstring generated from Julia source :: + zeta(s) Riemann zeta function :math:`\zeta(s)`. :: + zeta(s, z) Hurwitz zeta function :math:`\zeta(s, z)`. (This is equivalent to @@ -1315,14 +2174,27 @@ Mathematical Functions .. function:: ndigits(n, b) - Compute the number of digits in number ``n`` written in base ``b``. + .. Docstring generated from Julia source + .. code-block:: julia + ndigits(n, b) + + Compute the number of digits in number ``n`` written in base ``b``\ . .. function:: widemul(x, y) - Multiply ``x`` and ``y``, giving the result as a larger type. + .. Docstring generated from Julia source + .. code-block:: julia + widemul(x, y) + + Multiply ``x`` and ``y``\ , giving the result as a larger type. .. function:: @evalpoly(z, c...) + .. Docstring generated from Julia source + :: + + @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 @@ -1334,281 +2206,287 @@ Statistics .. function:: mean(v[, region]) - Compute the mean of whole array ``v``, or optionally along the dimensions in ``region``. - Note: Julia does not ignore ``NaN`` values in the computation. - For applications requiring the handling of missing data, the ``DataArray`` - package is recommended. + .. Docstring generated from Julia source + .. code-block:: julia + mean(v[, region]) + + Compute the mean of whole array ``v``\ , or optionally along the dimensions in ``region``\ . Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. .. function:: mean!(r, v) - Compute the mean of ``v`` over the singleton dimensions of ``r``, and write results to ``r``. + .. Docstring generated from Julia source + .. code-block:: julia + mean!(r, v) + + Compute the mean of ``v`` over the singleton dimensions of ``r``\ , and write results to ``r``\ . .. function:: std(v[, region]) - Compute the sample standard deviation of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``. - Note: Julia does not ignore ``NaN`` values in the computation. - For applications requiring the handling of missing data, the ``DataArray`` - package is recommended. + .. Docstring generated from Julia source + .. code-block:: julia + std(v[, region]) + + Compute the sample standard deviation of a vector or array ``v``\ , optionally along dimensions in ``region``\ . The algorithm returns an estimator of the generative distribution's standard deviation under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sqrt(sum((v - mean(v)).^2) / (length(v) - 1))``\ . Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. .. function:: stdm(v, m) - Compute the sample standard deviation of a vector ``v`` with known mean ``m``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + stdm(v, m) + + Compute the sample standard deviation of a vector ``v`` with known mean ``m``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: var(v[, region]) - Compute the sample variance of a vector or array ``v``, optionally along dimensions in ``region``. The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``. - Note: Julia does not ignore ``NaN`` values in the computation. - For applications requiring the handling of missing data, the ``DataArray`` - package is recommended. + .. Docstring generated from Julia source + .. code-block:: julia + var(v[, region]) + + Compute the sample variance of a vector or array ``v``\ , optionally along dimensions in ``region``\ . The algorithm will return an estimator of the generative distribution's variance under the assumption that each entry of ``v`` is an IID drawn from that generative distribution. This computation is equivalent to calculating ``sum((v - mean(v)).^2) / (length(v) - 1)``\ . Note: Julia does not ignore ``NaN`` values in the computation. For applications requiring the handling of missing data, the ``DataArray`` package is recommended. .. function:: varm(v, m) - Compute the sample variance of a vector ``v`` with known mean ``m``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + varm(v, m) + + Compute the sample variance of a vector ``v`` with known mean ``m``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: middle(x) - Compute the middle of a scalar value, which is equivalent to ``x`` itself, - but of the type of ``middle(x, x)`` for consistency. + .. Docstring generated from Julia source + .. code-block:: julia + middle(x) - :: - middle(x, y) + Compute the middle of a scalar value, which is equivalent to ``x`` itself, but of the type of ``middle(x, x)`` for consistency. - Compute the middle of two reals ``x`` and ``y``, which is equivalent - in both value and type to computing their mean (``(x + y) / 2``). + .. code-block:: julia + middle(x, y) - :: - middle(range) + Compute the middle of two reals ``x`` and ``y``\ , which is equivalent in both value and type to computing their mean (``(x + y) / 2``\ ). - Compute the middle of 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. + .. code-block:: julia + middle(range) - :: - middle(array) + Compute the middle of a range, which consists in computing the mean of its extrema. Since a range is sorted, the mean is performed with the first and last element. - Compute the middle of an array, which consists in finding its extrema and - then computing their mean. + .. code-block:: julia + middle(array) + + Compute the middle of an array, which consists in finding its extrema and then computing their mean. .. function:: middle(x, y) - :: - middle(x) + .. Docstring generated from Julia source + .. code-block:: julia + middle(x) - Compute the middle of a scalar value, which is equivalent to ``x`` itself, - but of the type of ``middle(x, x)`` for consistency. + Compute the middle of a scalar value, which is equivalent to ``x`` itself, but of the type of ``middle(x, x)`` for consistency. - :: - middle(x, y) + .. code-block:: julia + middle(x, y) - Compute the middle of two reals ``x`` and ``y``, which is equivalent - in both value and type to computing their mean (``(x + y) / 2``). + Compute the middle of two reals ``x`` and ``y``\ , which is equivalent in both value and type to computing their mean (``(x + y) / 2``\ ). - :: - middle(range) + .. code-block:: julia + middle(range) - Compute the middle of a range, which consists in computing the mean of its extrema. - Since a range is sorted, the mean is performed with the first and last element. + Compute the middle of a range, which consists in computing the mean of its extrema. Since a range is sorted, the mean is performed with the first and last element. - :: - middle(array) + .. code-block:: julia + middle(array) - Compute the middle of an array, which consists in finding its extrema and - then computing their mean. + Compute the middle of an array, which consists in finding its extrema and then computing their mean. .. function:: middle(range) - :: - middle(x) + .. Docstring generated from Julia source + .. code-block:: julia + middle(x) - Compute the middle of a scalar value, which is equivalent to ``x`` itself, - but of the type of ``middle(x, x)`` for consistency. + Compute the middle of a scalar value, which is equivalent to ``x`` itself, but of the type of ``middle(x, x)`` for consistency. - :: - middle(x, y) + .. code-block:: julia + middle(x, y) - Compute the middle of two reals ``x`` and ``y``, which is equivalent - in both value and type to computing their mean (``(x + y) / 2``). + Compute the middle of two reals ``x`` and ``y``\ , which is equivalent in both value and type to computing their mean (``(x + y) / 2``\ ). - :: - middle(range) + .. code-block:: julia + middle(range) - Compute the middle of a range, which consists in computing the mean of its extrema. - Since a range is sorted, the mean is performed with the first and last element. + Compute the middle of a range, which consists in computing the mean of its extrema. Since a range is sorted, the mean is performed with the first and last element. - :: - middle(array) + .. code-block:: julia + middle(array) - Compute the middle of an array, which consists in finding its extrema and - then computing their mean. + Compute the middle of an array, which consists in finding its extrema and then computing their mean. .. function:: middle(array) - :: - middle(x) + .. Docstring generated from Julia source + .. code-block:: julia + middle(x) - Compute the middle of a scalar value, which is equivalent to ``x`` itself, - but of the type of ``middle(x, x)`` for consistency. + Compute the middle of a scalar value, which is equivalent to ``x`` itself, but of the type of ``middle(x, x)`` for consistency. - :: - middle(x, y) + .. code-block:: julia + middle(x, y) - Compute the middle of two reals ``x`` and ``y``, which is equivalent - in both value and type to computing their mean (``(x + y) / 2``). + Compute the middle of two reals ``x`` and ``y``\ , which is equivalent in both value and type to computing their mean (``(x + y) / 2``\ ). - :: - middle(range) + .. code-block:: julia + middle(range) - Compute the middle of a range, which consists in computing the mean of its extrema. - Since a range is sorted, the mean is performed with the first and last element. + Compute the middle of a range, which consists in computing the mean of its extrema. Since a range is sorted, the mean is performed with the first and last element. - :: - middle(array) + .. code-block:: julia + middle(array) - Compute the middle of an array, which consists in finding its extrema and - then computing their mean. + Compute the middle of an array, which consists in finding its extrema and then computing their mean. .. function:: median(v[, region]) - Compute the median of whole array ``v``, or optionally along the dimensions - in ``region``. ``NaN`` is returned if the data contains any ``NaN`` values. - For applications requiring the handling of missing data, the ``DataArrays`` - package is recommended. + .. Docstring generated from Julia source + .. code-block:: julia + median(v[, region]) + + Compute the median of whole array ``v``\ , or optionally along the dimensions in ``region``\ . ``NaN`` is returned if the data contains any ``NaN`` values. For applications requiring the handling of missing data, the ``DataArrays`` package is recommended. .. function:: median!(v) - Like ``median``, but may overwrite the input vector. + .. Docstring generated from Julia source + .. code-block:: julia + median!(v) + + Like ``median``\ , but may overwrite the input vector. .. function:: hist(v[, n]) -> e, counts - Compute the histogram of ``v``, optionally using approximately ``n`` - bins. The return values are a range ``e``, which correspond to the - edges of the bins, and ``counts`` containing the number of elements of - ``v`` in each bin. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + hist(v[, n]) -> e, counts - :: - hist(v, e) -> e, counts + Compute the histogram of ``v``\ , optionally using approximately ``n`` bins. The return values are a range ``e``\ , which correspond to the edges of the bins, and ``counts`` containing the number of elements of ``v`` in each bin. Note: Julia does not ignore ``NaN`` values in the computation. - Compute the histogram of ``v`` 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. + .. code-block:: julia + hist(v, e) -> e, counts + + Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length ``length(e) - 1``\ , such that the element at location ``i`` satisfies ``sum(e[i] .< v .<= e[i+1])``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: hist(v, e) -> e, counts - :: - hist(v[, n]) -> e, counts + .. Docstring generated from Julia source + .. code-block:: julia + hist(v[, n]) -> e, counts - Compute the histogram of ``v``, optionally using approximately ``n`` - bins. The return values are a range ``e``, which correspond to the - edges of the bins, and ``counts`` containing the number of elements of - ``v`` in each bin. - Note: Julia does not ignore ``NaN`` values in the computation. + Compute the histogram of ``v``\ , optionally using approximately ``n`` bins. The return values are a range ``e``\ , which correspond to the edges of the bins, and ``counts`` containing the number of elements of ``v`` in each bin. Note: Julia does not ignore ``NaN`` values in the computation. - :: - hist(v, e) -> e, counts + .. code-block:: julia + hist(v, e) -> e, counts - Compute the histogram of ``v`` using a vector/range ``e`` as the edges for - the bins. The result will be a vector of length ``length(e) - 1``, such that the - element at location ``i`` satisfies ``sum(e[i] .< v .<= e[i+1])``. - Note: Julia does not ignore ``NaN`` values in the computation. + Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length ``length(e) - 1``\ , such that the element at location ``i`` satisfies ``sum(e[i] .< v .<= e[i+1])``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: hist!(counts, v, e) -> e, counts - Compute the histogram of ``v``, using a vector/range ``e`` as the edges for the bins. - This function writes the resultant counts to a pre-allocated array ``counts``. + .. Docstring generated from Julia source + .. code-block:: julia + hist!(counts, v, e) -> e, counts + + Compute the histogram of ``v``\ , using a vector/range ``e`` as the edges for the bins. This function writes the resultant counts to a pre-allocated array ``counts``\ . .. function:: hist2d(M, e1, e2) -> (edge1, edge2, counts) - Compute a "2d histogram" of a set of N points specified by N-by-2 matrix ``M``. - Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as - integer bin counts or vectors of bin edges. The result is a tuple of - ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges - used in the second dimension), and ``counts``, a histogram matrix of size - ``(length(edge1)-1, length(edge2)-1)``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + hist2d(M, e1, e2) -> (edge1, edge2, counts) + + Compute a "2d histogram" of a set of N points specified by N-by-2 matrix ``M``\ . Arguments ``e1`` and ``e2`` are bins for each dimension, specified either as integer bin counts or vectors of bin edges. The result is a tuple of ``edge1`` (the bin edges used in the first dimension), ``edge2`` (the bin edges used in the second dimension), and ``counts``\ , a histogram matrix of size ``(length(edge1)-1, length(edge2)-1)``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: hist2d!(counts, M, e1, e2) -> (e1, e2, counts) - Compute a "2d histogram" with respect to the bins delimited by the edges given - in ``e1`` and ``e2``. This function writes the results to a pre-allocated - array ``counts``. + .. Docstring generated from Julia source + .. code-block:: julia + hist2d!(counts, M, e1, e2) -> (e1, e2, counts) + + Compute a "2d histogram" with respect to the bins delimited by the edges given in ``e1`` and ``e2``\ . This function writes the results to a pre-allocated array ``counts``\ . .. function:: histrange(v, n) - Compute *nice* bin ranges for the edges of a histogram of ``v``, using - approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 - multiplied by a power of 10. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + histrange(v, n) + + Compute *nice* bin ranges for the edges of a histogram of ``v``\ , using approximately ``n`` bins. The resulting step sizes will be 1, 2 or 5 multiplied by a power of 10. Note: Julia does not ignore ``NaN`` values in the computation. .. function:: midpoints(e) - Compute the midpoints of the bins with edges ``e``. The result is a - vector/range of length ``length(e) - 1``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + midpoints(e) + + Compute the midpoints of the bins with edges ``e``\ . The result is a vector/range of length ``length(e) - 1``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: quantile(v, p) - Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + quantile(v, p) - :: - quantile(v, p) + Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``\ . Note: Julia does not ignore ``NaN`` values in the computation. - Compute the quantile of a vector ``v`` at the probability ``p``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. code-block:: julia + quantile(v, p) + + Compute the quantile of a vector ``v`` at the probability ``p``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: quantile(v, p) - Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``. - Note: Julia does not ignore ``NaN`` values in the computation. + .. Docstring generated from Julia source + .. code-block:: julia + quantile(v, p) - :: - quantile(v, p) + Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``\ . Note: Julia does not ignore ``NaN`` values in the computation. + + .. code-block:: julia + quantile(v, p) - Compute the quantile of a vector ``v`` at the probability ``p``. - Note: Julia does not ignore ``NaN`` values in the computation. + Compute the quantile of a vector ``v`` at the probability ``p``\ . Note: Julia does not ignore ``NaN`` values in the computation. .. function:: quantile!(v, p) - Like ``quantile``, but overwrites the input vector. + .. Docstring generated from Julia source + .. code-block:: julia + quantile!(v, p) + + Like ``quantile``\ , but overwrites the input vector. .. function:: cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - Compute the Pearson covariance between the vector(s) in ``v1`` and ``v2``. - Here, ``v1`` and ``v2`` can be either vectors or matrices. + .. Docstring generated from Julia source + .. code-block:: julia + cov(v1[, v2][, vardim=1, corrected=true, mean=nothing]) - This function accepts three keyword arguments: + Compute the Pearson covariance between the vector(s) in ``v1`` and ``v2``\ . Here, ``v1`` and ``v2`` can be either vectors or matrices. - - ``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``. + This function accepts three keyword arguments: - - ``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. + * ``vardim``\ : the dimension of variables. When ``vardim = 1``\ , variables are considered in columns while observations in rows; when ``vardim = 2``\ , variables are in rows while observations in columns. By default, it is set to ``1``\ . + * ``corrected``\ : whether to apply Bessel's correction (divide by ``n-1`` instead of ``n``\ ). By default, it is set to ``true``\ . + * ``mean``\ : allow users to supply mean values that are known. By default, it is set to ``nothing``\ , which indicates that the mean(s) are unknown, and the function will compute the mean. Users can use ``mean=0`` to indicate that the input data are centered, and hence there's no need to subtract the mean. - The size of the result depends on the size of ``v1`` and ``v2``. When both - ``v1`` and ``v2`` are vectors, it returns the covariance between them as a - scalar. When either one is a matrix, it returns a covariance matrix of size - ``(n1, n2)``, where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and - ``v2``, which depend on the setting of ``vardim``. + The size of the result depends on the size of ``v1`` and ``v2``\ . When both ``v1`` and ``v2`` are vectors, it returns the covariance between them as a scalar. When either one is a matrix, it returns a covariance matrix of size ``(n1, n2)``\ , where ``n1`` and ``n2`` are the numbers of slices in ``v1`` and ``v2``\ , which depend on the setting of ``vardim``\ . - Note: ``v2`` can be omitted, which indicates ``v2 = v1``. + Note: ``v2`` can be omitted, which indicates ``v2 = v1``\ . .. function:: cor(v1[, v2][, vardim=1, mean=nothing]) - Compute the Pearson correlation between the vector(s) in ``v1`` and ``v2``. + .. Docstring generated from Julia source + .. code-block:: julia + cor(v1[, v2][, vardim=1, mean=nothing]) - Users can use the keyword argument ``vardim`` to specify the variable - dimension, and ``mean`` to supply pre-computed mean values. + Compute the Pearson correlation between the vector(s) in ``v1`` and ``v2``\ . + + Users can use the keyword argument ``vardim`` to specify the variable dimension, and ``mean`` to supply pre-computed mean values. Signal Processing ----------------- @@ -1646,30 +2524,44 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: fft!(A [, dims]) + .. Docstring generated from Julia source + :: + + fft!(A [, dims]) + Same as :func:`fft`, but operates in-place on ``A``, which must be an array of complex floating-point numbers. .. function:: ifft(A [, dims]) + .. Docstring generated from Julia source + .. code-block:: julia + ifft(A [, dims]) + Multidimensional inverse FFT. A one-dimensional inverse FFT computes - .. math:: - - \operatorname{IDFT}(A)[k] = \frac{1}{\operatorname{length}(A)} - \sum_{n=1}^{\operatorname{length}(A)} \exp\left(+i\frac{2\pi (n-1)(k-1)} - {\operatorname{length}(A)} \right) A[n]. + [\\operatorname{IDFT}(A)[k] = \\frac{1}{\\operatorname{length}(A)} \\sum_{n=1}^{\\operatorname{length}(A)} \\exp\\left(+i\\frac{2\\pi (n-1)(k-1)} {\\operatorname{length}(A)} \\right) A[n].] - A multidimensional inverse FFT simply performs this operation along each - transformed dimension of ``A``. + A multidimensional inverse FFT simply performs this operation along each transformed dimension of ``A``\ . .. function:: ifft!(A [, dims]) + .. Docstring generated from Julia source + :: + + ifft!(A [, dims]) + Same as :func:`ifft`, but operates in-place on ``A``. .. function:: bfft(A [, dims]) + .. Docstring generated from Julia source + :: + + bfft(A [, dims]) + Similar to :func:`ifft`, but computes an unnormalized inverse (backward) transform, which must be divided by the product of the sizes of the transformed dimensions in order to obtain the inverse. (This is slightly @@ -1682,10 +2574,20 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: bfft!(A [, dims]) + .. Docstring generated from Julia source + :: + + bfft!(A [, dims]) + Same as :func:`bfft`, but operates in-place on ``A``. .. function:: plan_fft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_fft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + 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 an object ``P`` which @@ -1720,28 +2622,58 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: plan_ifft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_ifft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + Same as :func:`plan_fft`, but produces a plan that performs inverse transforms :func:`ifft`. .. function:: plan_bfft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_bfft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + Same as :func:`plan_fft`, but produces a plan that performs an unnormalized backwards transform :func:`bfft`. .. function:: plan_fft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_fft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + Same as :func:`plan_fft`, but operates in-place on ``A``. .. function:: plan_ifft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_ifft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + Same as :func:`plan_ifft`, but operates in-place on ``A``. .. function:: plan_bfft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_bfft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + Same as :func:`plan_bfft`, but operates in-place on ``A``. .. function:: rfft(A [, dims]) + .. Docstring generated from Julia source + :: + + rfft(A [, dims]) + Multidimensional FFT of a real array A, exploiting the fact that the transform has conjugate symmetry in order to save roughly half the computational time and storage costs compared with :func:`fft`. @@ -1755,6 +2687,11 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: irfft(A, d [, dims]) + .. Docstring generated from Julia source + :: + + irfft(A, d [, dims]) + Inverse of :func:`rfft`: for a complex array ``A``, gives the corresponding real array whose FFT yields ``A`` in the first half. As for :func:`rfft`, ``dims`` is an optional subset of dimensions @@ -1768,6 +2705,11 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: brfft(A, d [, dims]) + .. Docstring generated from Julia source + :: + + brfft(A, d [, dims]) + Similar to :func:`irfft` but computes an unnormalized inverse transform (similar to :func:`bfft`), which must be divided by the product of the sizes of the transformed dimensions (of the real output array) @@ -1775,6 +2717,11 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: plan_rfft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_rfft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + 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 @@ -1782,6 +2729,11 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: plan_brfft(A, d [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_brfft(A, d [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + 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 @@ -1789,12 +2741,22 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: plan_irfft(A, d [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + .. Docstring generated from Julia source + :: + + plan_irfft(A, d [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf) + 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`. .. function:: dct(A [, dims]) + .. Docstring generated from Julia source + :: + + 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 @@ -1805,12 +2767,22 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: dct!(A [, dims]) + .. Docstring generated from Julia source + :: + + 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. .. function:: idct(A [, dims]) + .. Docstring generated from Julia source + :: + + idct(A [, dims]) + Computes the multidimensional inverse discrete cosine transform (DCT) of the array ``A`` (technically, a type-III DCT with the unitary normalization). @@ -1822,96 +2794,153 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. .. function:: idct!(A [, dims]) + .. Docstring generated from Julia source + :: + + idct!(A [, dims]) + Same as :func:`idct!`, but operates in-place on ``A``. .. function:: plan_dct(A [, dims [, flags [, timelimit]]]) + .. Docstring generated from Julia source + :: + + plan_dct(A [, dims [, flags [, timelimit]]]) + Pre-plan an optimized discrete cosine transform (DCT), similar to :func:`plan_fft` except producing a function that computes :func:`dct`. The first two arguments have the same meaning as for :func:`dct`. .. function:: plan_dct!(A [, dims [, flags [, timelimit]]]) + .. Docstring generated from Julia source + :: + + plan_dct!(A [, dims [, flags [, timelimit]]]) + Same as :func:`plan_dct`, but operates in-place on ``A``. .. function:: plan_idct(A [, dims [, flags [, timelimit]]]) + .. Docstring generated from Julia source + :: + + plan_idct(A [, dims [, flags [, timelimit]]]) + Pre-plan an optimized inverse discrete cosine transform (DCT), similar to :func:`plan_fft` except producing a function that computes :func:`idct`. The first two arguments have the same meaning as for :func:`idct`. .. function:: plan_idct!(A [, dims [, flags [, timelimit]]]) + .. Docstring generated from Julia source + :: + + plan_idct!(A [, dims [, flags [, timelimit]]]) + Same as :func:`plan_idct`, but operates in-place on ``A``. .. function:: fftshift(x) - Swap the first and second halves of each dimension of ``x``. + .. Docstring generated from Julia source + .. code-block:: julia + fftshift(x) - :: - fftshift(x,dim) + Swap the first and second halves of each dimension of ``x``\ . + + .. code-block:: julia + fftshift(x,dim) - Swap the first and second halves of the given dimension of array ``x``. + Swap the first and second halves of the given dimension of array ``x``\ . .. function:: fftshift(x,dim) - :: - fftshift(x) + .. Docstring generated from Julia source + .. code-block:: julia + fftshift(x) - Swap the first and second halves of each dimension of ``x``. + Swap the first and second halves of each dimension of ``x``\ . - :: - fftshift(x,dim) + .. code-block:: julia + fftshift(x,dim) - Swap the first and second halves of the given dimension of array ``x``. + Swap the first and second halves of the given dimension of array ``x``\ . .. function:: ifftshift(x, [dim]) - Undoes the effect of ``fftshift``. + .. Docstring generated from Julia source + .. code-block:: julia + ifftshift(x, [dim]) + + Undoes the effect of ``fftshift``\ . .. function:: filt(b, a, x, [si]) - Apply filter described by vectors ``a`` and ``b`` to vector ``x``, with an - optional initial filter state vector ``si`` (defaults to zeros). + .. Docstring generated from Julia source + .. code-block:: julia + filt(b, a, x, [si]) + + Apply filter described by vectors ``a`` and ``b`` to vector ``x``\ , with an optional initial filter state vector ``si`` (defaults to zeros). .. function:: filt!(out, b, a, x, [si]) + .. Docstring generated from Julia source + :: + + filt!(out, b, a, x, [si]) + Same as :func:`filt` but writes the result into the ``out`` argument, which may alias the input ``x`` to modify it in-place. .. function:: deconv(b,a) - Construct vector ``c`` such that ``b = conv(a,c) + r``. Equivalent to polynomial division. + .. Docstring generated from Julia source + .. code-block:: julia + deconv(b,a) + + Construct vector ``c`` such that ``b = conv(a,c) + r``\ . Equivalent to polynomial division. .. function:: conv(u,v) + .. Docstring generated from Julia source + .. code-block:: julia + conv(u,v) + Convolution of two vectors. Uses FFT algorithm. .. function:: conv2(u,v,A) - 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by - the vectors ``u`` and ``v``. Uses 2-D FFT algorithm + .. Docstring generated from Julia source + .. code-block:: julia + conv2(u,v,A) - :: - conv2(B,A) + 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by the vectors ``u`` and ``v``\ . Uses 2-D FFT algorithm - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm + .. code-block:: julia + conv2(B,A) + + 2-D convolution of the matrix ``B`` with the matrix ``A``\ . Uses 2-D FFT algorithm .. function:: conv2(B,A) - :: - conv2(u,v,A) + .. Docstring generated from Julia source + .. code-block:: julia + conv2(u,v,A) - 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by - the vectors ``u`` and ``v``. Uses 2-D FFT algorithm + 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by the vectors ``u`` and ``v``\ . Uses 2-D FFT algorithm - :: - conv2(B,A) + .. code-block:: julia + conv2(B,A) - 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm + 2-D convolution of the matrix ``B`` with the matrix ``A``\ . Uses 2-D FFT algorithm .. function:: xcorr(u,v) + .. Docstring generated from Julia source + .. code-block:: julia + xcorr(u,v) + Compute the cross-correlation of two vectors. The following functions are defined within the ``Base.FFTW`` module. @@ -1920,6 +2949,11 @@ The following functions are defined within the ``Base.FFTW`` module. .. function:: r2r(A, kind [, dims]) + .. Docstring generated from Julia source + :: + + 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 @@ -1943,17 +2977,32 @@ The following functions are defined within the ``Base.FFTW`` module. .. function:: r2r!(A, kind [, dims]) + .. Docstring generated from Julia source + :: + + 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. .. function:: plan_r2r(A, kind [, dims [, flags [, timelimit]]]) + .. Docstring generated from Julia source + :: + + plan_r2r(A, kind [, dims [, flags [, timelimit]]]) + Pre-plan an optimized r2r transform, similar to :func:`Base.plan_fft` except that the transforms (and the first three arguments) correspond to :func:`r2r` and :func:`r2r!`, respectively. .. function:: plan_r2r!(A, kind [, dims [, flags [, timelimit]]]) + .. Docstring generated from Julia source + :: + + plan_r2r!(A, kind [, dims [, flags [, timelimit]]]) + Similar to :func:`Base.plan_fft`, but corresponds to :func:`r2r!`. .. currentmodule:: Base @@ -1966,62 +3015,23 @@ 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.) + .. Docstring generated from Julia source + .. code-block:: julia + quadgk(f, a,b,c...; reltol=sqrt(eps), abstol=0, maxevals=10^7, order=7, norm=vecnorm) + + Numerically integrate the function ``f(x)`` from ``a`` to ``b``\ , and optionally over additional intervals ``b`` to ``c`` and so on. Keyword options include a relative error tolerance ``reltol`` (defaults to ``sqrt(eps)`` in the precision of the endpoints), an absolute error tolerance ``abstol`` (defaults to 0), a maximum number of function evaluations ``maxevals`` (defaults to ``10^7``\ ), and the ``order`` of the integration rule (defaults to 7). + + Returns a pair ``(I,E)`` of the estimated integral ``I`` and an estimated upper bound on the absolute error ``E``\ . If ``maxevals`` is not exceeded then ``E <= max(abstol, reltol*norm(I))`` will hold. (Note that it is useful to specify a positive ``abstol`` in cases where ``norm(I)`` may be zero.) + + The endpoints ``a`` etcetera can also be complex (in which case the integral is performed over straight-line segments in the complex plane). If the endpoints are ``BigFloat``\ , then the integration will be performed in ``BigFloat`` precision as well (note: it is advisable to increase the integration ``order`` in rough proportion to the precision, for smooth integrands). More generally, the precision is set by the precision of the integration endpoints (promoted to floating-point types). + + The integrand ``f(x)`` can return any numeric scalar, vector, or matrix type, or in fact any type supporting ``+``\ , ``-``\ , multiplication by real values, and a ``norm`` (i.e., any normed vector space). Alternatively, a different norm can be specified by passing a ``norm``\ -like function as the ``norm`` keyword argument (which defaults to ``vecnorm``\ ). + + [Only one-dimensional integrals are provided by this function. For multi-dimensional integration (cubature), there are many different algorithms (often much better than simple nested 1d integrals) and the optimal choice tends to be very problem-dependent. See the Julia external-package listing for available algorithms for multidimensional integration or other specialized tasks (such as integrals of highly oscillatory or singular functions).] + + The algorithm is an adaptive Gauss-Kronrod integration technique: the integral in each interval is estimated using a Kronrod rule (``2*order+1`` points) and the error is estimated using an embedded Gauss rule (``order`` points). The interval with the largest error is then subdivided into two intervals and the process is repeated until the desired error tolerance is achieved. + + These quadrature rules work best for smooth functions within each interval, so if your function has a known discontinuity or other singularity, it is best to subdivide your interval to put the singularity at an endpoint. For example, if ``f`` has a discontinuity at ``x=0.7`` and you want to integrate from 0 to 1, you should use ``quadgk(f, 0,0.7,1)`` to subdivide the interval at the point of discontinuity. The integrand is never evaluated exactly at the endpoints of the intervals, so it is possible to integrate functions that diverge at the endpoints as long as the singularity is integrable (for example, a ``log(x)`` or ``1/sqrt(x)`` singularity). + + For real-valued endpoints, the starting and/or ending points may be infinite. (A coordinate transformation is performed internally to map the infinite interval to a finite one.) diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 2312ae89f488fb..e45d4a365b7978 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -14,81 +14,133 @@ Data Formats .. function:: bin(n, [pad]) + .. Docstring generated from Julia source + .. code-block:: julia + bin(n, [pad]) + Convert an integer to a binary string, optionally specifying a number of digits to pad to. .. function:: hex(n, [pad]) + .. Docstring generated from Julia source + .. code-block:: julia + hex(n, [pad]) + Convert an integer to a hexadecimal string, optionally specifying a number of digits to pad to. .. function:: dec(n, [pad]) + .. Docstring generated from Julia source + .. code-block:: julia + dec(n, [pad]) + Convert an integer to a decimal string, optionally specifying a number of digits to pad to. .. function:: oct(n, [pad]) + .. Docstring generated from Julia source + .. code-block:: julia + oct(n, [pad]) + Convert an integer to an octal string, optionally specifying a number of digits to pad to. .. function:: base(base, n, [pad]) + .. Docstring generated from Julia source + .. code-block:: julia + 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)])``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + bits(n) + A string giving the literal bit representation of a number. .. function:: parse(type, str, [base]) - :: - parse(str, start; greedy=true, raise=true) + .. Docstring generated from Julia source + .. code-block:: julia + parse(str, start; greedy=true, raise=true) - Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``\ . If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. - :: - parse(str; raise=true) + .. code-block:: julia + parse(str; raise=true) - Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. - :: - parse(type, str, [base]) + .. code-block:: julia + parse(type, str, [base]) - Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. - If the string does not contain a valid number, an error is raised. + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. .. function:: tryparse(type, str, [base]) - Like ``parse``, but returns a ``Nullable`` of the requested type. - The result will be null if the string does not contain a valid number. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: signed(x) + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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 ``AbstractFloat`` data type. For numeric data, the smallest suitable ``AbstractFloat`` type is used. Converts strings to ``Float64``. + .. Docstring generated from Julia source + .. code-block:: julia + float(x) + + Convert a number, array, or string to a ``AbstractFloat`` data type. For numeric data, the smallest suitable ``AbstractFloat`` type is used. Converts strings to ``Float64``\ . .. function:: significand(x) + .. Docstring generated from Julia source + :: + + 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 @@ -104,30 +156,58 @@ Data Formats .. function:: exponent(x) -> Int + .. Docstring generated from Julia source + .. code-block:: julia + exponent(x) -> Int + Get the exponent of a normalized floating-point number. .. function:: complex(r, [i]) + .. Docstring generated from Julia source + .. code-block:: julia + complex(r, [i]) + Convert real numbers or arrays to complex. ``i`` defaults to zero. .. function:: bswap(n) + .. Docstring generated from Julia source + .. code-block:: julia + bswap(n) + Byte-swap an integer .. function:: num2hex(f) + .. Docstring generated from Julia source + .. code-block:: julia + num2hex(f) + Get a hexadecimal string of the binary representation of a floating point number .. function:: hex2num(str) + .. Docstring generated from Julia source + .. code-block:: julia + hex2num(str) + Convert a hexadecimal string to the floating point number it represents .. function:: hex2bytes(s::ASCIIString) + .. Docstring generated from Julia source + .. code-block:: julia + 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}) + .. Docstring generated from Julia source + .. code-block:: julia + 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 @@ -135,10 +215,18 @@ General Number Functions and Constants .. function:: one(x) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + zero(x) + Get the additive identity element for the type of x (x can also specify the type itself). .. data:: pi @@ -195,46 +283,91 @@ General Number Functions and Constants .. function:: issubnormal(f) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + issubnormal(f) -> Bool + Test whether a floating point number is subnormal .. function:: isfinite(f) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isfinite(f) -> Bool + Test whether a number is finite .. function:: isinf(f) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isinf(f) -> Bool + Test whether a number is infinite .. function:: isnan(f) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isnan(f) -> Bool + Test whether a floating point number is not a number (NaN) .. function:: inf(f) + .. Docstring generated from Julia source + .. code-block:: julia + inf(f) + Returns positive infinity of the floating point type ``f`` or of the same floating point type as ``f`` .. function:: nan(f) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + nextfloat(f) + Get the next floating point number in lexicographic order .. function:: prevfloat(f) -> AbstractFloat + .. Docstring generated from Julia source + .. code-block:: julia + prevfloat(f) -> AbstractFloat + Get the previous floating point number in lexicographic order .. function:: isinteger(x) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isinteger(x) -> Bool + Test whether ``x`` or all its elements are numerically equal to some integer .. function:: isreal(x) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isreal(x) -> Bool + Test whether ``x`` or all its elements are numerically equal to some real number .. function:: Float32(x [, mode::RoundingMode]) + .. Docstring generated from Julia source + :: + + Float32(x [, mode::RoundingMode]) + Create a Float32 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. @@ -250,6 +383,11 @@ General Number Functions and Constants .. function:: Float64(x [, mode::RoundingMode]) + .. Docstring generated from Julia source + :: + + Float64(x [, mode::RoundingMode]) + Create a Float64 from ``x``. If ``x`` is not exactly representable then ``mode`` determines how ``x`` is rounded. @@ -265,6 +403,11 @@ General Number Functions and Constants .. function:: BigInt(x) + .. Docstring generated from Julia source + :: + + 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``. @@ -274,6 +417,11 @@ General Number Functions and Constants .. function:: BigFloat(x) + .. Docstring generated from Julia source + :: + + 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 @@ -294,6 +442,11 @@ General Number Functions and Constants .. function:: get_rounding(T) + .. Docstring generated from Julia source + :: + + 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. @@ -303,6 +456,11 @@ General Number Functions and Constants .. function:: set_rounding(T, mode) + .. Docstring generated from Julia source + :: + + 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. @@ -313,8 +471,13 @@ General Number Functions and Constants .. 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:: + .. Docstring generated from Julia source + .. code-block:: julia + 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: + .. code-block:: julia old = get_rounding(T) set_rounding(T, mode) f() @@ -324,28 +487,32 @@ General Number Functions and Constants .. function:: get_zero_subnormals() -> Bool - Returns ``false`` if operations on subnormal floating-point values - ("denormals") obey rules for IEEE arithmetic, and ``true`` if they - might be converted to zeros. + .. Docstring generated from Julia source + .. code-block:: julia + get_zero_subnormals() -> Bool + + Returns ``false`` if operations on subnormal floating-point values ("denormals") obey rules for IEEE arithmetic, and ``true`` if they might be converted to zeros. .. function:: set_zero_subnormals(yes::Bool) -> Bool - If ``yes`` is ``false``, subsequent floating-point operations follow - rules for IEEE arithmetic on subnormal values ("denormals"). - Otherwise, floating-point operations are permitted (but not required) - to convert subnormal inputs or outputs to zero. Returns ``true`` - unless ``yes==true`` but the hardware does not support zeroing of - subnormal numbers. + .. Docstring generated from Julia source + .. code-block:: julia + set_zero_subnormals(yes::Bool) -> Bool + + If ``yes`` is ``false``\ , subsequent floating-point operations follow rules for IEEE arithmetic on subnormal values ("denormals"). Otherwise, floating-point operations are permitted (but not required) to convert subnormal inputs or outputs to zero. Returns ``true`` unless ``yes==true`` but the hardware does not support zeroing of subnormal numbers. - ``set_zero_subnormals(true)`` can speed up some computations on - some hardware. However, it can break identities such as - ``(x-y==0) == (x==y)``. + ``set_zero_subnormals(true)`` can speed up some computations on some hardware. However, it can break identities such as ``(x-y==0) == (x==y)``\ . Integers ~~~~~~~~ .. function:: count_ones(x::Integer) -> Integer + .. Docstring generated from Julia source + :: + + count_ones(x::Integer) -> Integer + Number of ones in the binary representation of ``x``. .. doctest:: @@ -355,6 +522,11 @@ Integers .. function:: count_zeros(x::Integer) -> Integer + .. Docstring generated from Julia source + :: + + count_zeros(x::Integer) -> Integer + Number of zeros in the binary representation of ``x``. .. doctest:: @@ -364,6 +536,11 @@ Integers .. function:: leading_zeros(x::Integer) -> Integer + .. Docstring generated from Julia source + :: + + leading_zeros(x::Integer) -> Integer + Number of zeros leading the binary representation of ``x``. .. doctest:: @@ -373,6 +550,11 @@ Integers .. function:: leading_ones(x::Integer) -> Integer + .. Docstring generated from Julia source + :: + + leading_ones(x::Integer) -> Integer + Number of ones leading the binary representation of ``x``. .. doctest:: @@ -382,6 +564,11 @@ Integers .. function:: trailing_zeros(x::Integer) -> Integer + .. Docstring generated from Julia source + :: + + trailing_zeros(x::Integer) -> Integer + Number of zeros trailing the binary representation of ``x``. .. doctest:: @@ -391,6 +578,11 @@ Integers .. function:: trailing_ones(x::Integer) -> Integer + .. Docstring generated from Julia source + :: + + trailing_ones(x::Integer) -> Integer + Number of ones trailing the binary representation of ``x``. .. doctest:: @@ -400,6 +592,11 @@ Integers .. function:: isprime(x::Integer) -> Bool + .. Docstring generated from Julia source + :: + + isprime(x::Integer) -> Bool + Returns ``true`` if ``x`` is prime, and ``false`` otherwise. .. doctest:: @@ -408,6 +605,7 @@ Integers true :: + isprime(x::BigInt, [reps = 25]) -> Bool Probabilistic primality test. Returns ``true`` if ``x`` is prime; and @@ -422,7 +620,9 @@ Integers .. function:: isprime(x::BigInt, [reps = 25]) -> Bool + .. Docstring generated from Julia source :: + isprime(x::Integer) -> Bool Returns ``true`` if ``x`` is prime, and ``false`` otherwise. @@ -433,6 +633,7 @@ Integers true :: + isprime(x::BigInt, [reps = 25]) -> Bool Probabilistic primality test. Returns ``true`` if ``x`` is prime; and @@ -447,14 +648,27 @@ Integers .. function:: primes([lo,] hi) - Returns a collection of the prime numbers (from ``lo``, if specified) up to ``hi``. + .. Docstring generated from Julia source + .. code-block:: julia + primes([lo,] hi) + + Returns a collection of the prime numbers (from ``lo``\ , if specified) up to ``hi``\ . .. function:: primesmask([lo,] hi) - Returns a prime sieve, as a ``BitArray``, of the positive integers (from ``lo``, if specified) up to ``hi``. Useful when working with either primes or composite numbers. + .. Docstring generated from Julia source + .. code-block:: julia + primesmask([lo,] hi) + + Returns a prime sieve, as a ``BitArray``\ , of the positive integers (from ``lo``\ , if specified) up to ``hi``\ . Useful when working with either primes or composite numbers. .. function:: isodd(x::Integer) -> Bool + .. Docstring generated from Julia source + :: + + isodd(x::Integer) -> Bool + Returns ``true`` if ``x`` is odd (that is, not divisible by 2), and ``false`` otherwise. .. doctest:: @@ -467,6 +681,11 @@ Integers .. function:: iseven(x::Integer) -> Bool + .. Docstring generated from Julia source + :: + + iseven(x::Integer) -> Bool + Returns ``true`` is ``x`` is even (that is, divisible by 2), and ``false`` otherwise. .. doctest:: @@ -483,20 +702,37 @@ The `BigFloat` type implements arbitrary-precision floating-point arithmetic usi .. function:: precision(num::AbstractFloat) + .. Docstring generated from Julia source + .. code-block:: julia + precision(num::AbstractFloat) + Get the precision of a floating point number, as defined by the effective number of bits in the mantissa. .. function:: get_bigfloat_precision() + .. Docstring generated from Julia source + .. code-block:: julia + get_bigfloat_precision() + Get the precision (in bits) currently used for BigFloat arithmetic. .. function:: set_bigfloat_precision(x::Int64) + .. Docstring generated from Julia source + .. code-block:: julia + 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:: + .. Docstring generated from Julia source + .. code-block:: julia + with_bigfloat_precision(f::Function,precision::Integer) + + Change the BigFloat arithmetic precision (in bits) for the duration of ``f``\ . It is logically equivalent to: + .. code-block:: julia old = get_bigfloat_precision() set_bigfloat_precision(precision) f() @@ -523,20 +759,35 @@ 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: MersenneTwister([seed]) + .. Docstring generated from Julia source + .. code-block:: julia + 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() + .. Docstring generated from Julia source + .. code-block:: julia + RandomDevice() + Create a ``RandomDevice`` RNG object. Two such objects will always generate different streams of random numbers. .. function:: rand([rng], [S], [dims...]) + .. Docstring generated from Julia source + :: + + 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 @@ -547,31 +798,59 @@ As ``BigInt`` represents unbounded integers, the interval must be specified (e.g .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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...]) + .. Docstring generated from Julia source + .. code-block:: julia + bitrand([rng], [dims...]) + Generate a ``BitArray`` of random boolean values. .. function:: randn([rng], [dims...]) + .. Docstring generated from Julia source + .. code-block:: julia + 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}) + .. Docstring generated from Julia source + .. code-block:: julia + 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...]) + .. Docstring generated from Julia source + .. code-block:: julia + 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}) + .. Docstring generated from Julia source + .. code-block:: julia + randexp!([rng], A::Array{Float64,N}) + Fill the array A with random numbers following the exponential distribution (with scale 1). .. function:: randjump(r::MersenneTwister, jumps, [jumppoly]) -> Vector{MersenneTwister} - Create an array of the size ``jumps`` of initialized ``MersenneTwister`` RNG objects where the first RNG object given as a parameter and following ``MersenneTwister`` RNGs in the array initialized such that a state of the RNG object in the array would be moved forward (without generating numbers) from a previous RNG object array element on a particular number of steps encoded by the jump polynomial ``jumppoly``. + .. Docstring generated from Julia source + .. code-block:: julia + randjump(r::MersenneTwister, jumps, [jumppoly]) -> Vector{MersenneTwister} + + Create an array of the size ``jumps`` of initialized ``MersenneTwister`` RNG objects where the first RNG object given as a parameter and following ``MersenneTwister`` RNGs in the array initialized such that a state of the RNG object in the array would be moved forward (without generating numbers) from a previous RNG object array element on a particular number of steps encoded by the jump polynomial ``jumppoly``\ . Default jump polynomial moves forward ``MersenneTwister`` RNG state by 10^20 steps. diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 6140b97b3b0edd..f2fa18fca88a69 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -9,174 +9,227 @@ Tasks .. function:: Task(func) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: current_task() + .. Docstring generated from Julia source + .. code-block:: julia + current_task() + Get the currently running Task. .. function:: istaskdone(task) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + istaskdone(task) -> Bool + Tell whether a task has exited. .. function:: istaskstarted(task) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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() + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + task_local_storage(symbol) + Look up the value of a symbol in the current task's task-local storage. - :: - task_local_storage(symbol, value) + .. code-block:: julia + 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) + .. code-block:: julia + task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which - ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or - lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``\ ; the previous value of ``symbol``\ , or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. .. function:: task_local_storage(symbol, value) - :: - task_local_storage(symbol) + .. Docstring generated from Julia source + .. code-block:: julia + task_local_storage(symbol) Look up the value of a symbol in the current task's task-local storage. - :: - task_local_storage(symbol, value) + .. code-block:: julia + 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) + .. code-block:: julia + task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which - ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or - lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``\ ; the previous value of ``symbol``\ , or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. .. function:: task_local_storage(body, symbol, value) - :: - task_local_storage(symbol) + .. Docstring generated from Julia source + .. code-block:: julia + task_local_storage(symbol) Look up the value of a symbol in the current task's task-local storage. - :: - task_local_storage(symbol, value) + .. code-block:: julia + 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) + .. code-block:: julia + task_local_storage(body, symbol, value) - Call the function ``body`` with a modified task-local storage, in which - ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or - lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``\ ; the previous value of ``symbol``\ , or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. .. function:: Condition() - Create an edge-triggered event source that tasks can wait for. Tasks - that call ``wait`` on a ``Condition`` are suspended and queued. - Tasks are woken up when ``notify`` is later called on the ``Condition``. - Edge triggering means that only tasks waiting at the time ``notify`` is - called can be woken up. For level-triggered notifications, you must - keep extra state to keep track of whether a notification has happened. - The ``Channel`` type does this, and so can be used for level-triggered - events. + .. Docstring generated from Julia source + .. code-block:: julia + 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 ``Channel`` 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + schedule(t::Task, [val]; error=false) + + Add a task to the scheduler's queue. This causes the task to run constantly when the system is otherwise idle, unless the task performs a blocking operation such as ``wait``\ . - If a second argument is provided, it will be passed to the task (via the - return value of ``yieldto``) when it runs again. If ``error`` is true, - the value is raised as an exception in the woken task. + 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 + .. Docstring generated from Julia source + .. code-block:: julia + @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. + .. Docstring generated from Julia source + .. code-block:: julia + @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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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" + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: Channel{T}(sz::Int) - Constructs a Channel that can hold a maximum of ``sz`` objects of type ``T``. ``put!`` calls - on a full channel block till an object is removed with ``take!``. + .. Docstring generated from Julia source + .. code-block:: julia + Channel{T}(sz::Int) + + Constructs a Channel that can hold a maximum of ``sz`` objects of type ``T``\ . ``put!`` calls on a full channel block till an object is removed with ``take!``\ . - Other constructors: - ``Channel()`` - equivalent to ``Channel{Any}(32)`` - ``Channel(sz::Int)`` equivalent to ``Channel{Any}(sz)`` + Other constructors: ``Channel()`` - equivalent to ``Channel{Any}(32)`` ``Channel(sz::Int)`` equivalent to ``Channel{Any}(sz)`` General Parallel Computing Support ---------------------------------- .. function:: addprocs(n::Integer; exeflags=``) -> List of process identifiers + .. Docstring generated from Julia source + :: + + addprocs(n::Integer; exeflags=``) -> List of process identifiers + Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. :: + addprocs() -> List of process identifiers Equivalent to ``addprocs(CPU_CORES)`` :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers Add processes on remote machines via SSH. @@ -216,6 +269,7 @@ General Parallel Computing Support the number of seconds a newly launched worker waits for connection establishment. :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -229,18 +283,22 @@ General Parallel Computing Support .. function:: addprocs() -> List of process identifiers + .. Docstring generated from Julia source :: + addprocs(n::Integer; exeflags=``) -> List of process identifiers Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. :: + addprocs() -> List of process identifiers Equivalent to ``addprocs(CPU_CORES)`` :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers Add processes on remote machines via SSH. @@ -280,6 +338,7 @@ General Parallel Computing Support the number of seconds a newly launched worker waits for connection establishment. :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -293,18 +352,22 @@ General Parallel Computing Support .. function:: addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + .. Docstring generated from Julia source :: + addprocs(n::Integer; exeflags=``) -> List of process identifiers Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. :: + addprocs() -> List of process identifiers Equivalent to ``addprocs(CPU_CORES)`` :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers Add processes on remote machines via SSH. @@ -344,6 +407,7 @@ General Parallel Computing Support the number of seconds a newly launched worker waits for connection establishment. :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -357,18 +421,22 @@ General Parallel Computing Support .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + .. Docstring generated from Julia source :: + addprocs(n::Integer; exeflags=``) -> List of process identifiers Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. :: + addprocs() -> List of process identifiers Equivalent to ``addprocs(CPU_CORES)`` :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers Add processes on remote machines via SSH. @@ -408,6 +476,7 @@ General Parallel Computing Support the number of seconds a newly launched worker waits for connection establishment. :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers Launches worker processes via the specified cluster manager. @@ -421,41 +490,72 @@ General Parallel Computing Support .. function:: nprocs() + .. Docstring generated from Julia source + .. code-block:: julia + nprocs() + Get the number of available processes. .. function:: nworkers() + .. Docstring generated from Julia source + .. code-block:: julia + nworkers() + Get the number of available worker processes. This is one less than nprocs(). Equal to nprocs() if nprocs() == 1. .. function:: procs() + .. Docstring generated from Julia source + .. code-block:: julia + procs() + Returns a list of all process identifiers. - :: - procs(S::SharedArray) + .. code-block:: julia + procs(S::SharedArray) Get the vector of processes that have mapped the shared array .. function:: workers() + .. Docstring generated from Julia source + .. code-block:: julia + workers() + Returns a list of all worker process identifiers. .. function:: rmprocs(pids...) + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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() + .. Docstring generated from Julia source + .. code-block:: julia + myid() + Get the id of the current process. .. function:: pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + .. Docstring generated from Julia source + :: + + pmap(f, lsts...; err_retry=true, err_stop=false, pids=workers()) + Transform collections ``lsts`` by applying ``f`` to each element in parallel. (Note that ``f`` must be made available to all worker processes; see :ref:`Code Availability and Loading Packages ` for details.) If ``nprocs() > 1``, the calling process will be dedicated to assigning tasks. @@ -466,10 +566,19 @@ General Parallel Computing Support .. function:: remotecall(id, func, args...) - Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. + .. Docstring generated from Julia source + .. code-block:: julia + remotecall(id, func, args...) + + Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``\ . .. function:: wait([x]) + .. Docstring generated from Julia source + :: + + wait([x]) + Block the current task until some event occurs, depending on the type of the argument: @@ -495,6 +604,11 @@ General Parallel Computing Support .. function:: fetch(x) + .. Docstring generated from Julia source + :: + + fetch(x) + Waits and fetches a value from ``x`` depending on the type of ``x``. Does not remove the item fetched: * ``RemoteRef``: Wait for and get the value of a remote reference. If the remote value is an exception, @@ -504,78 +618,98 @@ General Parallel Computing Support .. function:: remotecall_wait(id, func, args...) + .. Docstring generated from Julia source + .. code-block:: julia + remotecall_wait(id, func, args...) + Perform ``wait(remotecall(...))`` in one message. .. function:: remotecall_fetch(id, func, args...) - Perform ``fetch(remotecall(...))`` in one message. Any remote exceptions are captured in a ``RemoteException`` - and thrown. + .. Docstring generated from Julia source + .. code-block:: julia + remotecall_fetch(id, func, args...) + + Perform ``fetch(remotecall(...))`` in one message. Any remote exceptions are captured in a ``RemoteException`` and thrown. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + put!(RemoteRef, value) - :: - put!(Channel, 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. - Appends an item to the channel. Blocks if the channel is full. + .. code-block:: julia + put!(Channel, value) + + Appends an item to the channel. Blocks if the channel is full. .. function:: put!(Channel, value) - :: - put!(RemoteRef, value) + .. Docstring generated from Julia source + .. code-block:: julia + put!(RemoteRef, value) - Store a value to a remote reference. Implements "shared queue of length 1" semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. + Store a value to a remote reference. Implements "shared queue of length 1" semantics: if a value is already present, blocks until the value is removed with ``take!``\ . Returns its first argument. - :: - put!(Channel, value) + .. code-block:: julia + put!(Channel, value) - Appends an item to the channel. Blocks if the channel is full. + Appends an item to the channel. Blocks if the channel is full. .. function:: take!(RemoteRef) + .. Docstring generated from Julia source + .. code-block:: julia + take!(RemoteRef) + Fetch the value of a remote reference, removing it so that the reference is empty again. - :: - take!(Channel) + .. code-block:: julia + take!(Channel) - Removes and returns a value from a ``Channel``. Blocks till data is available. + Removes and returns a value from a ``Channel``\ . Blocks till data is available. .. function:: take!(Channel) - :: - take!(RemoteRef) + .. Docstring generated from Julia source + .. code-block:: julia + take!(RemoteRef) Fetch the value of a remote reference, removing it so that the reference is empty again. - :: - take!(Channel) + .. code-block:: julia + take!(Channel) - Removes and returns a value from a ``Channel``. Blocks till data is available. + Removes and returns a value from a ``Channel``\ . Blocks till data is available. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 ``RemoteRef`` as a proxy: + + .. code-block:: julia rr = RemoteRef() @async put!(rr, remotecall_fetch(p, long_computation)) isready(rr) # will not block .. function:: close(Channel) + .. Docstring generated from Julia source :: + close(stream) Close an I/O stream. Performs a ``flush`` first. :: + close(Channel) Closes a channel. An exception is thrown by: @@ -586,122 +720,159 @@ General Parallel Computing Support .. function:: RemoteRef() + .. Docstring generated from Julia source + .. code-block:: julia + RemoteRef() + Make an uninitialized remote reference on the local machine. - :: - RemoteRef(n) + .. code-block:: julia + RemoteRef(n) - Make an uninitialized remote reference on process ``n``. + Make an uninitialized remote reference on process ``n``\ . .. function:: RemoteRef(n) - :: - RemoteRef() + .. Docstring generated from Julia source + .. code-block:: julia + RemoteRef() Make an uninitialized remote reference on the local machine. - :: - RemoteRef(n) + .. code-block:: julia + RemoteRef(n) - Make an uninitialized remote reference on process ``n``. + Make an uninitialized remote reference on process ``n``\ . .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) - Waits till ``testcb`` returns ``true`` or for ``secs`` seconds, whichever is earlier. - ``testcb`` is polled every ``pollint`` seconds. + .. Docstring generated from Julia source + .. code-block:: julia + 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 - Creates a closure around an expression and runs it on an automatically-chosen process, returning a - ``RemoteRef`` to the result. + .. Docstring generated from Julia source + .. code-block:: julia + @spawn + + Creates a closure around an expression and runs it on an automatically-chosen process, returning a ``RemoteRef`` to the result. .. function:: @spawnat - Accepts two arguments, ``p`` and an expression. A closure is created around - the expression and run asynchronously on process ``p``. Returns a ``RemoteRef`` - to the result. + .. Docstring generated from Julia source + .. code-block:: julia + @spawnat + + Accepts two arguments, ``p`` and an expression. A closure is created around the expression and run asynchronously on process ``p``\ . Returns a ``RemoteRef`` to the result. .. function:: @fetch - Equivalent to ``fetch(@spawn expr)``. + .. Docstring generated from Julia source + .. code-block:: julia + @fetch + + Equivalent to ``fetch(@spawn expr)``\ . .. function:: @fetchfrom - Equivalent to ``fetch(@spawnat p expr)``. + .. Docstring generated from Julia source + .. code-block:: julia + @fetchfrom + + Equivalent to ``fetch(@spawnat p expr)``\ . .. function:: @async - Wraps an expression in a closure and schedules it to run on the local machine. Also - adds it to the set of items that the nearest enclosing ``@sync`` waits for. + .. Docstring generated from Julia source + .. code-block:: julia + @async + + Wraps an expression in a closure and schedules it to run on the local machine. Also adds 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. All exceptions thrown by - enclosed async operations are collected and thrown as a ``CompositeException``. + .. Docstring generated from Julia source + .. code-block:: julia + @sync + + Wait until all dynamically-enclosed uses of ``@async``\ , ``@spawn``\ , ``@spawnat`` and ``@parallel`` are complete. All exceptions thrown by enclosed async operations are collected and thrown as a ``CompositeException``\ . .. function:: @parallel - A parallel for loop of the form :: + .. Docstring generated from Julia source + .. code-block:: julia + @parallel + + A parallel for loop of the form : - @parallel [reducer] for var = range - body - end + .. code-block:: julia + @parallel [reducer] for var = range + body + end - The specified range is partitioned and locally executed across all workers. - In case an optional reducer function is specified, @parallel performs local - reductions on each worker with a final reduction on the calling process. + The specified range is partitioned and locally executed across all workers. In case an optional reducer function is specified, @parallel performs local reductions on each worker with a final reduction on the calling process. - Note that without a reducer function, @parallel executes asynchronously, - i.e. it spawns independent tasks on all available workers and returns - immediately without waiting for completion. To wait for completion, prefix - the call with ``@sync``, like :: + Note that without a reducer function, @parallel executes asynchronously, i.e. it spawns independent tasks on all available workers and returns immediately without waiting for completion. To wait for completion, prefix the call with ``@sync``\ , like : - @sync @parallel for var = range - body - end + .. code-block:: julia + @sync @parallel for var = range + body + end .. function:: @everywhere - Execute an expression on all processes. Errors on any of the processes are - collected into a `CompositeException` and thrown. + .. Docstring generated from Julia source + .. code-block:: julia + @everywhere + + Execute an expression on all processes. Errors on any of the processes are collected into a CompositeException and thrown. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, - it is called on all the participating workers. + If ``pids`` is left unspecified, the shared array will be mapped across all processes on the current host, including the master. But, ``localindexes`` and ``indexpids`` will only refer to worker processes. This facilitates work distribution code to use workers for actual computation with the master process acting as a driver. + + If an ``init`` function of the type ``initfn(S::SharedArray)`` is specified, it is called on all the participating workers. .. function:: procs(S::SharedArray) - :: - procs() + .. Docstring generated from Julia source + .. code-block:: julia + procs() Returns a list of all process identifiers. - :: - procs(S::SharedArray) + .. code-block:: julia + procs(S::SharedArray) Get the vector of processes that have mapped the shared array .. function:: sdata(S::SharedArray) + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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 ------------------------- @@ -712,12 +883,19 @@ 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: manage(manager::FooManager, pid::Int, config::WorkerConfig. op::Symbol) + .. Docstring generated from Julia source + :: + + 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: @@ -730,47 +908,48 @@ Cluster Manager Interface .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) - :: - kill(p::Process, signum=SIGTERM) + .. Docstring generated from Julia source + .. code-block:: julia + kill(p::Process, signum=SIGTERM) Send a signal to a process. The default is to terminate the process. - :: - kill(manager::FooManager, pid::Int, config::WorkerConfig) + .. code-block:: julia + kill(manager::FooManager, pid::Int, config::WorkerConfig) - Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified - by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` + Implemented by cluster managers. It is called on the master process, by ``rmprocs``\ . It should cause the remote worker specified by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` .. function:: init_worker(manager::FooManager) - Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. - Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets - for transport. + .. Docstring generated from Julia source + .. code-block:: julia + init_worker(manager::FooManager) + + Called by cluster managers implementing custom transports. It initializes a newly launched process as a worker. Command line argument ``--worker`` has the effect of initializing a process as a worker using TCP/IP sockets for transport. .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - :: - connect([host],port) -> TcpSocket + .. Docstring generated from Julia source + .. code-block:: julia + connect([host],port) -> TcpSocket Connect to the host ``host`` on port ``port`` - :: - connect(path) -> Pipe + .. code-block:: julia + connect(path) -> Pipe Connect to the Named Pipe/Domain Socket at ``path`` - :: - connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + .. code-block:: julia + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) - Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, - specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read - off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation - must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` - sets up TCP/IP socket connections in-between workers. + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``\ , specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off ``instrm``\ , while messages to be sent to ``pid`` will be written to ``outstrm``\ . The custom transport implementation must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` sets up TCP/IP socket connections in-between workers. .. function:: Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) - Called by cluster managers using custom transports. It should be called when the custom transport implementation receives the - first message from a remote worker. The custom transport must manage a logical connection to the remote worker and provide two - AsyncStream objects, one for incoming messages and the other for messages addressed to the remote worker. + .. Docstring generated from Julia source + .. code-block:: julia + Base.process_messages(instrm::AsyncStream, outstrm::AsyncStream) + + Called by cluster managers using custom transports. It should be called when the custom transport implementation receives the first message from a remote worker. The custom transport must manage a logical connection to the remote worker and provide two AsyncStream objects, one for incoming messages and the other for messages addressed to the remote worker. diff --git a/doc/stdlib/pkg.rst b/doc/stdlib/pkg.rst index 406a71aabdac0b..879e375a770c3c 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -9,242 +9,289 @@ 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. + .. Docstring generated from Julia source + .. code-block:: julia + dir() -> AbstractString - :: - dir(names...) -> AbstractString + Returns the absolute path of the package directory. This defaults to ``joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION.minor)")`` on all platforms (i.e. ``~/.julia/v0.4`` in UNIX shell syntax). If the ``JULIA_PKGDIR`` environment variable is set, then that path is used in the returned value as ``joinpath(ENV["JULIA_PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")``\ . If ``JULIA_PKGDIR`` is a relative path, it is interpreted relative to whatever the current working directory is. - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. - In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. + .. code-block:: julia + dir(names...) -> AbstractString + + Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``\ . .. function:: dir(names...) -> AbstractString - :: - dir() -> AbstractString + .. Docstring generated from Julia source + .. code-block:: julia + dir() -> AbstractString - Returns the absolute path of the package directory. - This defaults to ``joinpath(homedir(),".julia","v$(VERSION.major).$(VERSION.minor)")`` on all platforms - (i.e. ``~/.julia/v0.4`` in UNIX shell syntax). If the ``JULIA_PKGDIR`` environment variable is set, then - that path is used in the returned value as ``joinpath(ENV["JULIA_PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")``. - If ``JULIA_PKGDIR`` is a relative path, it is interpreted relative to whatever the current working directory is. + Returns the absolute path of the package directory. This defaults to ``joinpath(homedir(),".julia","v\$(VERSION.major).\$(VERSION.minor)")`` on all platforms (i.e. ``~/.julia/v0.4`` in UNIX shell syntax). If the ``JULIA_PKGDIR`` environment variable is set, then that path is used in the returned value as ``joinpath(ENV["JULIA_PKGDIR"],"v\$(VERSION.major).\$(VERSION.minor)")``\ . If ``JULIA_PKGDIR`` is a relative path, it is interpreted relative to whatever the current working directory is. - :: - dir(names...) -> AbstractString + .. code-block:: julia + dir(names...) -> AbstractString - Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. - In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. + Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``\ . .. function:: init(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH) - Initialize ``Pkg.dir()`` as a package directory. - This will be done automatically when the ``JULIA_PKGDIR`` is not set and ``Pkg.dir()`` uses its default value. - As part of this process, clones a local METADATA git repository from the site and branch specified by its arguments, which - are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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")``. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. function:: rm(pkg) - Remove all requirement entries for ``pkg`` from ``Pkg.dir("REQUIRE")`` and call ``Pkg.resolve()``. + .. Docstring generated from Julia source + .. code-block:: julia + rm(pkg) + + Remove all requirement entries for ``pkg`` from ``Pkg.dir("REQUIRE")`` and call ``Pkg.resolve()``\ . .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. code-block:: julia + clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``, clone it from that URL on the default branch. - The package does not need to have any registered versions. + If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``\ , clone it from that URL on the default branch. The package does not need to have any registered versions. .. function:: clone(pkg) - :: - clone(url, [pkg]) + .. Docstring generated from Julia source + .. code-block:: julia + clone(url, [pkg]) - Clone a package directly from the git URL ``url``. - The package does not need to be a registered in ``Pkg.dir("METADATA")``. - The package repo is cloned by the name ``pkg`` if provided; - if not provided, ``pkg`` is determined automatically from ``url``. + Clone a package directly from the git URL ``url``\ . The package does not need to be a registered in ``Pkg.dir("METADATA")``\ . The package repo is cloned by the name ``pkg`` if provided; if not provided, ``pkg`` is determined automatically from ``url``\ . - :: - clone(pkg) + .. code-block:: julia + clone(pkg) - If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``, clone it from that URL on the default branch. - The package does not need to have any registered versions. + If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``\ , clone it from that URL on the default branch. The package does not need to have any registered versions. .. function:: available() -> Vector{ASCIIString} + .. Docstring generated from Julia source + .. code-block:: julia + available() -> Vector{ASCIIString} + Returns the names of available packages. - :: - available(pkg) -> Vector{VersionNumber} + .. code-block:: julia + available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package ``pkg``. + Returns the version numbers available for package ``pkg``\ . .. function:: available(pkg) -> Vector{VersionNumber} - :: - available() -> Vector{ASCIIString} + .. Docstring generated from Julia source + .. code-block:: julia + available() -> Vector{ASCIIString} Returns the names of available packages. - :: - available(pkg) -> Vector{VersionNumber} + .. code-block:: julia + available(pkg) -> Vector{VersionNumber} - Returns the version numbers available for package ``pkg``. + Returns the version numbers available for package ``pkg``\ . .. function:: installed() -> Dict{ASCIIString,VersionNumber} + .. Docstring generated from Julia source + .. code-block:: julia + installed() -> Dict{ASCIIString,VersionNumber} + Returns a dictionary mapping installed package names to the installed version number of each package. - :: - installed(pkg) -> Void | VersionNumber + .. code-block:: julia + installed(pkg) -> Void | VersionNumber - If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. + If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``\ . .. function:: installed(pkg) -> Void | VersionNumber - :: - installed() -> Dict{ASCIIString,VersionNumber} + .. Docstring generated from Julia source + .. code-block:: julia + installed() -> Dict{ASCIIString,VersionNumber} Returns a dictionary mapping installed package names to the installed version number of each package. - :: - installed(pkg) -> Void | VersionNumber + .. code-block:: julia + installed(pkg) -> Void | VersionNumber - If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. + If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``\ . .. function:: status() + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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)`` + .. Docstring generated from Julia source + .. code-block:: julia + 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)`` + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. code-block:: julia + pin(pkg, version) - Pin ``pkg`` at registered version ``version``. + Pin ``pkg`` at registered version ``version``\ . .. function:: pin(pkg, version) - :: - pin(pkg) + .. Docstring generated from Julia source + .. code-block:: julia + pin(pkg) - Pin ``pkg`` at the current version. - To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` + Pin ``pkg`` at the current version. To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` - :: - pin(pkg, version) + .. code-block:: julia + pin(pkg, version) - Pin ``pkg`` at registered version ``version``. + Pin ``pkg`` at registered version ``version``\ . .. function:: free(pkg) - Free the package ``pkg`` to be managed by the package manager again. - It calls ``Pkg.resolve()`` to determine optimal package versions after. - This is an inverse for both ``Pkg.checkout`` and ``Pkg.pin``. + .. Docstring generated from Julia source + .. code-block:: julia + free(pkg) - You can also supply an iterable collection of package names, e.g., - ``Pkg.free(("Pkg1", "Pkg2"))`` to free multiple packages at once. + Free the package ``pkg`` to be managed by the package manager again. It calls ``Pkg.resolve()`` to determine optimal package versions after. This is an inverse for both ``Pkg.checkout`` and ``Pkg.pin``\ . + + You can also supply an iterable collection of package names, e.g., ``Pkg.free(("Pkg1", "Pkg2"))`` to free multiple packages at once. .. function:: build() + .. Docstring generated from Julia source + .. code-block:: julia + build() + Run the build scripts for all installed packages in depth-first recursive order. - :: - build(pkgs...) + .. code-block:: julia + build(pkgs...) - Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. - This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. + Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. .. function:: build(pkgs...) - :: - build() + .. Docstring generated from Julia source + .. code-block:: julia + build() Run the build scripts for all installed packages in depth-first recursive order. - :: - build(pkgs...) + .. code-block:: julia + build(pkgs...) - Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. - This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. + Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. .. function:: generate(pkg,license) - Generate a new package named ``pkg`` with one of these license keys: ``"MIT"``, ``"BSD"`` or ``"ASL"``. - If you want to make a package with a different license, you can edit it afterwards. - Generate creates a git repo at ``Pkg.dir(pkg)`` for the package and inside it ``LICENSE.md``, ``README.md``, ``REQUIRE``, the julia entrypoint ``$pkg/src/$pkg.jl``, and Travis and AppVeyor CI configuration files ``.travis.yml`` and ``appveyor.yml``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ , ``REQUIRE``\ , the julia entrypoint ``\$pkg/src/\$pkg.jl``\ , and Travis and AppVeyor CI configuration files ``.travis.yml`` and ``appveyor.yml``\ . .. function:: register(pkg, [url]) - Register ``pkg`` at the git URL ``url``, defaulting to the configured origin URL of the git repo ``Pkg.dir(pkg)``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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...) + .. code-block:: julia + test(pkgs...) - Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``\ . .. function:: test(pkgs...) - :: - test() + .. Docstring generated from Julia source + .. code-block:: julia + test() - Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``\ . - :: - test(pkgs...) + .. code-block:: julia + test(pkgs...) - Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``\ . diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 9b19d8d2d7214b..39ae837fa33c7b 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -10,19 +10,30 @@ .. function:: @profile - ``@profile `` runs your expression while taking - periodic backtraces. These are appended to an internal buffer of - backtraces. + .. Docstring generated from Julia source + .. code-block:: julia + @profile + + ``@profile `` runs your expression while taking periodic backtraces. These are appended to an internal buffer of backtraces. .. currentmodule:: Base.Profile The methods in :mod:`Base.Profile` are not exported and need to be called e.g. as ``Profile.print()``. .. function:: clear() + .. Docstring generated from Julia source + .. code-block:: julia + 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()) + .. Docstring generated from Julia source + :: + + 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 @@ -32,6 +43,7 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a 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 @@ -41,7 +53,9 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a .. function:: print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + .. Docstring generated from Julia source :: + 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 @@ -53,6 +67,7 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a 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 @@ -62,16 +77,19 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a .. 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)``. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + :: + + 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 @@ -82,15 +100,19 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: callers(funcname, [data, lidict], [filename=], [linerange=]) -> Vector{Tuple{count, linfo}} + .. Docstring generated from Julia source + :: + + 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 @@ -102,6 +124,11 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a .. function:: clear_malloc_data() + .. Docstring generated from Julia source + :: + + 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`. diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index d1ff0cceee9bcc..919de5a8083db7 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -119,39 +119,45 @@ 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. code-block:: julia + 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(v, [alg=,] [by=,] [lt=,] [rev=false]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. code-block:: julia + 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]) + .. Docstring generated from Julia source + :: + + 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 @@ -164,6 +170,11 @@ Sorting Functions .. function:: sortperm!(ix, v, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + .. Docstring generated from Julia source + :: + + 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)``. @@ -171,10 +182,18 @@ Sorting Functions .. function:: sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + .. Docstring generated from Julia source + .. code-block:: julia + sortrows(A, [alg=,] [by=,] [lt=,] [rev=false]) + Sort the rows of matrix ``A`` lexicographically. .. function:: sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + .. Docstring generated from Julia source + .. code-block:: julia + sortcols(A, [alg=,] [by=,] [lt=,] [rev=false]) + Sort the columns of matrix ``A`` lexicographically. Order-Related Functions @@ -182,59 +201,67 @@ 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``\ . .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: selectperm(v, k, [alg=,] [by=,] [lt=,] [rev=false]) - Return a partial permutation of the the vector ``v``, according to the order - specified by ``by``, ``lt`` and ``rev``, so that ``v[output]`` returns the - first ``k`` (or range of adjacent values if ``k`` is a range) values of a - fully sorted version of ``v``. If ``k`` is a single index (Integer), an - array of the first ``k`` indices is returned; if ``k`` is a range, an array - of those indices is returned. Note that the handling of integer values for - ``k`` is different from ``select`` in that it returns a vector of ``k`` - elements instead of just the ``k`` th element. Also note that this is - equivalent to, but more efficient than, calling ``sortperm(...)[k]`` + .. Docstring generated from Julia source + .. code-block:: julia + selectperm(v, k, [alg=,] [by=,] [lt=,] [rev=false]) + + Return a partial permutation of the the vector ``v``\ , according to the order specified by ``by``\ , ``lt`` and ``rev``\ , so that ``v[output]`` returns the first ``k`` (or range of adjacent values if ``k`` is a range) values of a fully sorted version of ``v``\ . If ``k`` is a single index (Integer), an array of the first ``k`` indices is returned; if ``k`` is a range, an array of those indices is returned. Note that the handling of integer values for ``k`` is different from ``select`` in that it returns a vector of ``k`` elements instead of just the ``k`` th element. Also note that this is equivalent to, but more efficient than, calling ``sortperm(...)[k]`` .. function:: selectperm!(ix, v, k, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) - Like ``selectperm``, but accepts a preallocated index vector ``ix``. If - ``initialized`` is ``false`` (the default), ix is initialized to contain the - values ``1:length(ix)``. + .. Docstring generated from Julia source + .. code-block:: julia + selectperm!(ix, v, k, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) + + Like ``selectperm``\ , but accepts a preallocated index vector ``ix``\ . If ``initialized`` is ``false`` (the default), ix is initialized to contain the values ``1:length(ix)``\ . Sorting Algorithms ------------------ diff --git a/doc/stdlib/strings.rst b/doc/stdlib/strings.rst index c0a32995829ef3..c175204edd6586 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,48 +6,54 @@ .. function:: length(s) - :: - length(A) -> Integer + .. Docstring generated from Julia source + .. code-block:: julia + length(A) -> Integer Returns the number of elements in A - :: - length(collection) -> Integer + .. code-block:: julia + 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) + .. code-block:: julia + length(s) - The number of characters in string ``s``. + The number of characters in string ``s``\ . .. function:: sizeof(s::AbstractString) - :: - sizeof(type) + .. Docstring generated from Julia source + .. code-block:: julia + sizeof(type) Size, in bytes, of the canonical binary representation of the given type, if any. - :: - sizeof(s::AbstractString) + .. code-block:: julia + sizeof(s::AbstractString) - The number of bytes in string ``s``. + The number of bytes in string ``s``\ . .. function:: *(s, t) + .. Docstring generated from Julia source :: + *(A, B) :noindex: Matrix multiplication :: + *(x, y...) Multiplication operator. ``x*y*z*...`` calls this function with all arguments, i.e. ``*(x, y, z, ...)``. :: + *(s, t) Concatenate strings. The ``*`` operator is an alias to this function. @@ -59,12 +65,15 @@ .. function:: ^(s, n) + .. Docstring generated from Julia source :: + ^(x, y) Exponentiation operator. :: + ^(s, n) Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. @@ -76,131 +85,161 @@ .. function:: string(xs...) + .. Docstring generated from Julia source + .. code-block:: julia + string(xs...) + Create a string from any values using the ``print`` function. .. function:: repr(x) + .. Docstring generated from Julia source + .. code-block:: julia + repr(x) + Create a string from any value using the ``showall`` function. .. function:: bytestring(::Ptr{UInt8}, [length]) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. code-block:: julia + bytestring(s) Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. .. function:: bytestring(s) - :: - bytestring(::Ptr{UInt8}, [length]) + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. code-block:: julia + 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}) + .. Docstring generated from Julia source + .. code-block:: julia + ascii(::Array{UInt8,1}) + Create an ASCII string from a byte array. - :: - ascii(s) + .. code-block:: julia + ascii(s) Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). - :: - ascii(::Ptr{UInt8}, [length]) + .. code-block:: julia + 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) - :: - ascii(::Array{UInt8,1}) + .. Docstring generated from Julia source + .. code-block:: julia + ascii(::Array{UInt8,1}) Create an ASCII string from a byte array. - :: - ascii(s) + .. code-block:: julia + ascii(s) Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). - :: - ascii(::Ptr{UInt8}, [length]) + .. code-block:: julia + ascii(::Ptr{UInt8}, [length]) Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. .. function:: ascii(::Ptr{UInt8}, [length]) - :: - ascii(::Array{UInt8,1}) + .. Docstring generated from Julia source + .. code-block:: julia + ascii(::Array{UInt8,1}) Create an ASCII string from a byte array. - :: - ascii(s) + .. code-block:: julia + ascii(s) Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). - :: - ascii(::Ptr{UInt8}, [length]) + .. code-block:: julia + 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}) + .. Docstring generated from Julia source + .. code-block:: julia + utf8(::Array{UInt8,1}) + Create a UTF-8 string from a byte array. - :: - utf8(::Ptr{UInt8}, [length]) + .. code-block:: julia + 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) + .. code-block:: julia + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). .. function:: utf8(::Ptr{UInt8}, [length]) - :: - utf8(::Array{UInt8,1}) + .. Docstring generated from Julia source + .. code-block:: julia + utf8(::Array{UInt8,1}) Create a UTF-8 string from a byte array. - :: - utf8(::Ptr{UInt8}, [length]) + .. code-block:: julia + 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) + .. code-block:: julia + utf8(s) Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). .. function:: utf8(s) - :: - utf8(::Array{UInt8,1}) + .. Docstring generated from Julia source + .. code-block:: julia + utf8(::Array{UInt8,1}) Create a UTF-8 string from a byte array. - :: - utf8(::Ptr{UInt8}, [length]) + .. code-block:: julia + 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) + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + 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 @@ -232,383 +271,528 @@ .. 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.) + .. Docstring generated from Julia source + .. code-block:: julia + graphemes(s) -> iterator over substrings of s + + Returns an iterator over substrings of ``s`` that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. (Roughly, these are what users would perceive as single characters, even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.) .. function:: isvalid(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`` + .. Docstring generated from Julia source + .. code-block:: julia + isvalid(value) -> Bool - :: - isvalid(T, value) -> Bool + Returns true if the given value is valid for its type, which currently can be one of ``Char``\ , ``ASCIIString``\ , ``UTF8String``\ , ``UTF16String``\ , or ``UTF32String`` - Returns true if the given value is valid for 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}`` + .. code-block:: julia + isvalid(T, value) -> Bool - :: - isvalid(str, i) + Returns true if the given value is valid for that type. Types currently can be ``Char``\ , ``ASCIIString``\ , ``UTF8String``\ , ``UTF16String``\ , or ``UTF32String`` Values for ``Char`` can be of type ``Char`` or ``UInt32`` Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` Values for ``UTF32String`` can be ``UTF32String``\ , ``Vector{Char}`` or ``Vector{UInt32}`` + + .. code-block:: julia + isvalid(str, i) Tells whether index ``i`` is valid for the given string .. function:: isvalid(T, value) -> Bool - :: - isvalid(value) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isvalid(value) -> Bool - Returns true if the given value is valid for its type, - which currently can be one of ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + Returns true if the given value is valid for its type, which currently can be one of ``Char``\ , ``ASCIIString``\ , ``UTF8String``\ , ``UTF16String``\ , or ``UTF32String`` - :: - isvalid(T, value) -> Bool + .. code-block:: julia + isvalid(T, value) -> Bool - Returns true if the given value is valid for that type. - Types currently can be ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` - Values for ``Char`` can be of type ``Char`` or ``UInt32`` - Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` - Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` - Values for ``UTF32String`` can be ``UTF32String``, ``Vector{Char}`` or ``Vector{UInt32}`` + Returns true if the given value is valid for that type. Types currently can be ``Char``\ , ``ASCIIString``\ , ``UTF8String``\ , ``UTF16String``\ , or ``UTF32String`` Values for ``Char`` can be of type ``Char`` or ``UInt32`` Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` Values for ``UTF32String`` can be ``UTF32String``\ , ``Vector{Char}`` or ``Vector{UInt32}`` - :: - isvalid(str, i) + .. code-block:: julia + isvalid(str, i) Tells whether index ``i`` is valid for the given string .. function:: is_assigned_char(c) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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]]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. Docstring generated from Julia source + .. code-block:: julia + 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} + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``. + .. Docstring generated from Julia source + .. code-block:: julia + 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``: + .. Docstring generated from Julia source + .. code-block:: julia + search(string, chars, [start]) + + Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression (though regular expressions are only allowed on contiguous strings, such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that ``s[search(s,x)] == x``\ : - ``search(string, "substring")`` = ``start:end`` such that ``string[start:end] == "substring"``, or ``0:-1`` if unmatched. + ``search(string, "substring")`` = ``start:end`` such that ``string[start:end] == "substring"``\ , or ``0:-1`` if unmatched. - ``search(string, 'c')`` = ``index`` such that ``string[index] == 'c'``, or ``0`` if unmatched. + ``search(string, 'c')`` = ``index`` such that ``string[index] == 'c'``\ , or ``0`` if unmatched. .. function:: rsearch(string, chars, [start]) - Similar to ``search``, but returning the last occurrence of the given characters within the given string, searching in reverse from ``start``. + .. Docstring generated from Julia source + .. code-block:: julia + rsearch(string, chars, [start]) + + Similar to ``search``\ , but returning the last occurrence of the given characters within the given string, searching in reverse from ``start``\ . .. function:: searchindex(string, substring, [start]) - Similar to ``search``, but return only the start index at which the substring is found, or 0 if it is not. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + 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. If ``pat`` is a regular expression and ``r`` is a ``SubstitutionString``, then capture group references in ``r`` are replaced with the corresponding matched text. + .. Docstring generated from Julia source + .. code-block:: julia + 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. If ``pat`` is a regular expression and ``r`` is a ``SubstitutionString``\ , then capture group references in ``r`` are replaced with the corresponding matched text. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + rsplit(string, [chars]; limit=0, keep=true) + + Similar to ``split``\ , but starting from the end of the string. .. function:: strip(string, [chars]) + .. Docstring generated from Julia source + .. code-block:: julia + 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]) + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. function:: rstrip(string, [chars]) + .. Docstring generated from Julia source + .. code-block:: julia + 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. .. 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + .. code-block:: julia + uppercase(string) + Returns ``string`` with all characters converted to uppercase. .. function:: lowercase(string) + .. Docstring generated from Julia source + .. code-block:: julia + lowercase(string) + Returns ``string`` with all characters converted to lowercase. .. function:: ucfirst(string) + .. Docstring generated from Julia source + .. code-block:: julia + ucfirst(string) + Returns ``string`` with the first character converted to uppercase. .. function:: lcfirst(string) + .. Docstring generated from Julia source + .. code-block:: julia + 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"``. + .. Docstring generated from Julia source + .. code-block:: julia + join(strings, delim, [last]) - ``strings`` can be any iterable over elements ``x`` which are convertible to strings via ``print(io::IOBuffer, x)``. + Join an array of ``strings`` into a single string, inserting the given delimiter between adjacent strings. If ``last`` is given, it will be used instead of ``delim`` between the last two strings. For example, ``join(["apples", "bananas", "pineapples"], ", ", " and ") == "apples, bananas and pineapples"``\ . + + ``strings`` can be any iterable over elements ``x`` which are convertible to strings via ``print(io::IOBuffer, x)``\ . .. function:: chop(string) + .. Docstring generated from Julia source + .. code-block:: julia + chop(string) + Remove the last character from a string .. function:: chomp(string) + .. Docstring generated from Julia source + .. code-block:: julia + chomp(string) + Remove a trailing newline from a string .. function:: ind2chr(string, i) + .. Docstring generated from Julia source + .. code-block:: julia + ind2chr(string, i) + Convert a byte index to a character index .. function:: chr2ind(string, i) + .. Docstring generated from Julia source + .. code-block:: julia + chr2ind(string, i) + Convert a character index to a byte index .. function:: isvalid(str, i) - :: - isvalid(value) -> Bool + .. Docstring generated from Julia source + .. code-block:: julia + isvalid(value) -> Bool - Returns true if the given value is valid for its type, - which currently can be one of ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + Returns true if the given value is valid for its type, which currently can be one of ``Char``\ , ``ASCIIString``\ , ``UTF8String``\ , ``UTF16String``\ , or ``UTF32String`` - :: - isvalid(T, value) -> Bool + .. code-block:: julia + isvalid(T, value) -> Bool - Returns true if the given value is valid for that type. - Types currently can be ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` - Values for ``Char`` can be of type ``Char`` or ``UInt32`` - Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` - Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` - Values for ``UTF32String`` can be ``UTF32String``, ``Vector{Char}`` or ``Vector{UInt32}`` + Returns true if the given value is valid for that type. Types currently can be ``Char``\ , ``ASCIIString``\ , ``UTF8String``\ , ``UTF16String``\ , or ``UTF32String`` Values for ``Char`` can be of type ``Char`` or ``UInt32`` Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` Values for ``UTF32String`` can be ``UTF32String``\ , ``Vector{Char}`` or ``Vector{UInt32}`` - :: - isvalid(str, i) + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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) + .. Docstring generated from Julia source + :: + + 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 `. .. function:: charwidth(c) + .. Docstring generated from Julia source + .. code-block:: julia + charwidth(c) + Gives the number of columns needed to print a character. .. function:: strwidth(s) + .. Docstring generated from Julia source + .. code-block:: julia + 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'. + .. Docstring generated from Julia source + .. code-block:: julia + 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'. .. 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'. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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'. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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. + .. Docstring generated from Julia source + .. code-block:: julia + 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 + .. Docstring generated from Julia source + .. code-block:: julia + symbol(x...) -> Symbol + Create a ``Symbol`` by concatenating the string representations of the arguments together. .. function:: escape_string(str::AbstractString) -> AbstractString + .. Docstring generated from Julia source + :: + + escape_string(str::AbstractString) -> AbstractString + General escaping of traditional C and Unicode escape sequences. See :func:`print_escaped` for more general escaping. .. function:: unescape_string(s::AbstractString) -> AbstractString + .. Docstring generated from Julia source + :: + + unescape_string(s::AbstractString) -> AbstractString + General unescaping of traditional C and Unicode escape sequences. Reverse of :func:`escape_string`. See also :func:`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. + .. Docstring generated from Julia source + .. code-block:: julia + utf16(s) - :: - utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) + 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. + + .. code-block:: julia + utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. .. function:: utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) - :: - utf16(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. + .. Docstring generated from Julia source + .. code-block:: julia + utf16(s) - :: - utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) + 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. + + .. code-block:: julia + 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) - :: - wstring(s) + .. Docstring generated from Julia source + .. code-block:: julia + wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, - depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. - The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` - is also provided. + This is a synonym for either ``utf32(s)`` or ``utf16(s)``\ , depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. .. function:: utf32(::Union{Ptr{Char},Ptr{UInt32},Ptr{Int32}} [, length]) - :: - wstring(s) + .. Docstring generated from Julia source + .. code-block:: julia + wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, - depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. - The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` - is also provided. + This is a synonym for either ``utf32(s)`` or ``utf16(s)``\ , depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. .. function:: wstring(s) - This is a synonym for either ``utf32(s)`` or ``utf16(s)``, - depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. - The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` - is also provided. + .. Docstring generated from Julia source + .. code-block:: julia + 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 514cb1a185b481..cc0b0c9bd0bfae 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -14,8 +14,11 @@ 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) + .. Docstring generated from Julia source + .. code-block:: julia + runtests([tests=["all"] [, numcores=iceil(CPU_CORES/2) ]]) + + Run the Julia unit tests listed in ``tests``\ , which can be either a string or an array of strings, using ``numcores`` processors. (not exported) .. module:: Base.Test Test Framework @@ -133,27 +136,44 @@ Macros .. function:: @test(ex) + .. Docstring generated from Julia source + .. code-block:: julia + @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. - The default handler returns the exception if it is of the expected type. + .. Docstring generated from Julia source + .. code-block:: julia + @test_throws(extype, ex) + + Test that the expression ``ex`` throws an exception of type ``extype`` and calls the current handler to handle the result. The default handler returns the exception if it is of the expected type. .. function:: @test_approx_eq(a, b) - Test two floating point numbers ``a`` and ``b`` for equality taking in account - small numerical errors. + .. Docstring generated from Julia source + .. code-block:: julia + @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``. + .. Docstring generated from Julia source + .. code-block:: julia + @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) + .. Docstring generated from Julia source + .. code-block:: julia + with_handler(f, handler) + Run the function ``f`` using the ``handler`` as the handler.