diff --git a/doc/devdocs/cartesian.rst b/doc/devdocs/cartesian.rst index 0e0bfd3608e1f..98fad0492420c 100644 --- a/doc/devdocs/cartesian.rst +++ b/doc/devdocs/cartesian.rst @@ -137,6 +137,8 @@ Macro reference ~~~~~~~~~~~~~~~ .. function:: @nloops N itersym rangeexpr bodyexpr + + :: @nloops N itersym rangeexpr preexpr bodyexpr @nloops N itersym rangeexpr preexpr postexpr bodyexpr @@ -191,6 +193,8 @@ Macro reference bounds-checking. .. function:: @nif N conditionexpr expr + + :: @nif N conditionexpr expr elseexpr Generates a sequence of ``if ... elseif ... else ... end`` statements. For example:: @@ -200,6 +204,7 @@ Macro reference would generate:: if i_1 > size(A, 1) + error("Dimension ", 1, " too big") elseif i_2 > size(A, 2) error("Dimension ", 2, " too big") diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index d137f4fe63974..d23098f5373f1 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -33,6 +33,16 @@ Basic functions Returns the number of elements in A + :: + length(collection) -> Integer + + For ordered, indexable collections, the maximum index ``i`` for which ``getindex(collection, i)`` is valid. For unordered collections, the number of elements. + + :: + length(s) + + The number of characters in string ``s``. + .. function:: 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). @@ -100,8 +110,23 @@ 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:: ind2sub(a, index) -> subscripts + :: + 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:: sub2ind(dims, i, j, k...) -> index @@ -121,23 +146,62 @@ Constructors 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. + The syntax ``a[i,j,...]`` is converted by the compiler to + ``getindex(a, i, j, ...)``. + .. function:: cell(dims) Construct an uninitialized cell array (heterogeneous array). ``dims`` can be either a tuple or a series of integer arguments. + .. function:: zeros(type, dims) Create an array of all zeros of specified type. The type defaults to Float64 if not specified. + :: + zeros(A) + + Create an array of all zeros with the same element type and shape as A. + .. function:: zeros(A) + :: + zeros(type, dims) + + Create an array of all zeros of specified type. The type defaults to Float64 if not specified. + + :: + zeros(A) + Create an array of all zeros with the same element type and shape as A. .. function:: ones(type, dims) Create an array of all ones of specified type. The type defaults to Float64 if not specified. + :: + ones(A) + + Create an array of all ones with the same element type and shape as A. + .. function:: ones(A) + :: + ones(type, dims) + + Create an array of all ones of specified type. The type defaults to Float64 if not specified. + + :: + ones(A) + Create an array of all ones with the same element type and shape as A. .. function:: trues(dims) @@ -178,12 +242,48 @@ Constructors n-by-n identity matrix + :: + eye(m, n) + + m-by-n identity matrix + + :: + eye(A) + + Constructs an identity matrix of the same dimensions and type as ``A``. + .. function:: eye(m, n) + :: + eye(n) + + n-by-n identity matrix + + :: + eye(m, n) + m-by-n identity matrix + :: + eye(A) + + Constructs an identity matrix of the same dimensions and type as ``A``. + .. function:: eye(A) + :: + eye(n) + + n-by-n identity matrix + + :: + eye(m, n) + + m-by-n identity matrix + + :: + eye(A) + Constructs an identity matrix of the same dimensions and type as ``A``. .. function:: linspace(start, stop, n=100) @@ -227,8 +327,23 @@ Indexing, Assignment, and Concatenation .. function:: getindex(A, inds...) + :: + 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. + The syntax ``a[i,j,...]`` is converted by the compiler to + ``getindex(a, i, j, ...)``. + .. function:: sub(A, inds...) Like :func:`getindex`, but returns a view into the parent array ``A`` with the given indices instead of making a copy. Calling :func:`getindex` or :func:`setindex!` on the returned :obj:`SubArray` computes the indices to the parent array on the fly without checking bounds. @@ -253,6 +368,13 @@ Indexing, Assignment, and Concatenation Store values from array ``X`` within some subset of ``A`` as specified by ``inds``. + :: + setindex!(collection, value, key...) + + Store the given value at the given key or index within a collection. + The syntax ``a[i,j,...] = x`` is converted by the compiler to + ``setindex!(a, x, i, j, ...)``. + .. function:: broadcast_getindex(A, inds...) 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. @@ -297,8 +419,24 @@ Indexing, Assignment, and Concatenation boolean array to an array of indexes of the ``true`` elements. + :: + find(f,A) + + Return a vector of the linear indexes of ``A`` where ``f`` returns true. + .. function:: find(f,A) + :: + find(A) + + Return a vector of the linear indexes of the non-zeros in ``A`` + (determined by ``A[i]!=0``). A common use of this is to convert a + boolean array to an array of indexes of the ``true`` + elements. + + :: + find(f,A) + Return a vector of the linear indexes of ``A`` where ``f`` returns true. .. function:: findn(A) @@ -315,36 +453,146 @@ Indexing, Assignment, and Concatenation Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + :: + findfirst(A,v) + + Return the index of the first element equal to ``v`` in ``A``. + + :: + findfirst(predicate, A) + + Return the index of the first element of ``A`` for which ``predicate`` returns true. + .. function:: findfirst(A,v) + :: + findfirst(A) + + Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + + :: + findfirst(A,v) + Return the index of the first element equal to ``v`` in ``A``. + :: + findfirst(predicate, A) + + Return the index of the first element of ``A`` for which ``predicate`` returns true. + .. function:: findfirst(predicate, A) + :: + findfirst(A) + + Return the index of the first non-zero value in ``A`` (determined by ``A[i]!=0``). + + :: + findfirst(A,v) + + Return the index of the first element equal to ``v`` in ``A``. + + :: + findfirst(predicate, A) + Return the index of the first element of ``A`` for which ``predicate`` returns true. .. function:: findlast(A) Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + :: + findlast(A, v) + + Return the index of the last element equal to ``v`` in ``A``. + + :: + findlast(predicate, A) + + Return the index of the last element of ``A`` for which ``predicate`` returns true. + .. function:: findlast(A, v) + :: + findlast(A) + + Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + + :: + findlast(A, v) + Return the index of the last element equal to ``v`` in ``A``. + :: + findlast(predicate, A) + + Return the index of the last element of ``A`` for which ``predicate`` returns true. + .. function:: findlast(predicate, A) + :: + findlast(A) + + Return the index of the last non-zero value in ``A`` (determined by ``A[i]!=0``). + + :: + findlast(A, v) + + Return the index of the last element equal to ``v`` in ``A``. + + :: + findlast(predicate, A) + Return the index of the last element of ``A`` for which ``predicate`` returns true. .. function:: findnext(A, i) Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + :: + findnext(predicate, A, i) + + Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + + :: + findnext(A, v, i) + + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), + or ``0`` if not found. + .. function:: findnext(predicate, A, i) + :: + findnext(A, i) + + Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + + :: + findnext(predicate, A, i) + Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + :: + findnext(A, v, i) + + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), + or ``0`` if not found. + .. function:: findnext(A, v, i) + :: + findnext(A, i) + + Find the next index >= ``i`` of a non-zero element of ``A``, or ``0`` if not found. + + :: + findnext(predicate, A, i) + + Find the next index >= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + + :: + findnext(A, v, i) + Find the next index >= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. @@ -352,12 +600,50 @@ Indexing, Assignment, and Concatenation Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + :: + findprev(predicate, A, i) + + Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + + :: + findprev(A, v, i) + + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), + or ``0`` if not found. + .. function:: findprev(predicate, A, i) + :: + findprev(A, i) + + Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + + :: + findprev(predicate, A, i) + Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + :: + findprev(A, v, i) + + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), + or ``0`` if not found. + .. function:: findprev(A, v, i) + :: + findprev(A, i) + + Find the previous index <= ``i`` of a non-zero element of ``A``, or 0 if not found. + + :: + findprev(predicate, A, i) + + Find the previous index <= ``i`` of an element of ``A`` for which ``predicate`` returns true, or ``0`` if not found. + + :: + findprev(A, v, i) + Find the previous index <= ``i`` of an element of ``A`` equal to ``v`` (using ``==``), or ``0`` if not found. @@ -404,7 +690,6 @@ Indexing, Assignment, and Concatenation Like ``randsubseq``, but the results are stored in ``S`` (which is resized as needed). - Array functions --------------- @@ -461,8 +746,22 @@ Array functions Rotate matrix ``A`` 180 degrees. + :: + rot180(A, k) + + Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. + If ``k`` is even, this is equivalent to a ``copy``. + .. function:: rot180(A, k) + :: + rot180(A) + + Rotate matrix ``A`` 180 degrees. + + :: + rot180(A, k) + Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``. @@ -470,8 +769,22 @@ Array functions Rotate matrix ``A`` left 90 degrees. + :: + rotl90(A, k) + + Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` + is zero or a multiple of four, this is equivalent to a ``copy``. + .. function:: rotl90(A, k) + :: + rotl90(A) + + Rotate matrix ``A`` left 90 degrees. + + :: + rotl90(A, k) + Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. @@ -479,8 +792,22 @@ Array functions Rotate matrix ``A`` right 90 degrees. + :: + rotr90(A, k) + + Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` + is zero or a multiple of four, this is equivalent to a ``copy``. + .. function:: rotr90(A, k) + :: + rotr90(A) + + Rotate matrix ``A`` right 90 degrees. + + :: + rotr90(A, k) + Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``. @@ -533,8 +860,22 @@ Combinatorics Compute the kth lexicographic permutation of a vector. + :: + nthperm(p) + + Return the ``k`` that generated permutation ``p``. + Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``. + .. function:: nthperm(p) + :: + nthperm(v, k) + + Compute the kth lexicographic permutation of a vector. + + :: + nthperm(p) + Return the ``k`` that generated permutation ``p``. Note that ``nthperm(nthperm([1:n], k)) == k`` for ``1 <= k <= factorial(n)``. @@ -619,16 +960,100 @@ Combinatorics partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n))``. + :: + partitions(n, m) + + Generate all arrays of ``m`` integers that sum to ``n``. Because + the number of partitions can be very large, this function returns an + iterator object. Use ``collect(partitions(n,m))`` to get an array of + all partitions. The number of partitions to generate can be efficiently + computed using ``length(partitions(n,m))``. + + :: + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + ``collect(partitions(array))`` to get an array of all partitions. + The number of partitions to generate can be efficiently + computed using ``length(partitions(array))``. + + :: + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m + subsets, represented as arrays of arrays. Because the number of + partitions can be very large, this function returns an iterator object. + Use ``collect(partitions(array,m))`` to get an array of all partitions. + The number of partitions into m subsets is equal to the Stirling number + of the second kind and can be efficiently computed using + ``length(partitions(array,m))``. + .. function:: partitions(n, m) + :: + partitions(n) + + Generate all integer arrays that sum to ``n``. Because the number of + partitions can be very large, this function returns an iterator + object. Use ``collect(partitions(n))`` to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using ``length(partitions(n))``. + + :: + partitions(n, m) + Generate all arrays of ``m`` integers that sum to ``n``. Because the number of partitions can be very large, this function returns an iterator object. Use ``collect(partitions(n,m))`` to get an array of all partitions. The number of partitions to generate can be efficiently computed using ``length(partitions(n,m))``. + :: + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + ``collect(partitions(array))`` to get an array of all partitions. + The number of partitions to generate can be efficiently + computed using ``length(partitions(array))``. + + :: + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m + subsets, represented as arrays of arrays. Because the number of + partitions can be very large, this function returns an iterator object. + Use ``collect(partitions(array,m))`` to get an array of all partitions. + The number of partitions into m subsets is equal to the Stirling number + of the second kind and can be efficiently computed using + ``length(partitions(array,m))``. + .. function:: partitions(array) + :: + partitions(n) + + Generate all integer arrays that sum to ``n``. Because the number of + partitions can be very large, this function returns an iterator + object. Use ``collect(partitions(n))`` to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using ``length(partitions(n))``. + + :: + partitions(n, m) + + Generate all arrays of ``m`` integers that sum to ``n``. Because + the number of partitions can be very large, this function returns an + iterator object. Use ``collect(partitions(n,m))`` to get an array of + all partitions. The number of partitions to generate can be efficiently + computed using ``length(partitions(n,m))``. + + :: + partitions(array) + Generate all set partitions of the elements of an array, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. Use @@ -636,8 +1061,50 @@ Combinatorics The number of partitions to generate can be efficiently computed using ``length(partitions(array))``. + :: + partitions(array, m) + + Generate all set partitions of the elements of an array into exactly m + subsets, represented as arrays of arrays. Because the number of + partitions can be very large, this function returns an iterator object. + Use ``collect(partitions(array,m))`` to get an array of all partitions. + The number of partitions into m subsets is equal to the Stirling number + of the second kind and can be efficiently computed using + ``length(partitions(array,m))``. + .. function:: partitions(array, m) + :: + partitions(n) + + Generate all integer arrays that sum to ``n``. Because the number of + partitions can be very large, this function returns an iterator + object. Use ``collect(partitions(n))`` to get an array of all + partitions. The number of partitions to generate can be efficiently + computed using ``length(partitions(n))``. + + :: + partitions(n, m) + + Generate all arrays of ``m`` integers that sum to ``n``. Because + the number of partitions can be very large, this function returns an + iterator object. Use ``collect(partitions(n,m))`` to get an array of + all partitions. The number of partitions to generate can be efficiently + computed using ``length(partitions(n,m))``. + + :: + partitions(array) + + Generate all set partitions of the elements of an array, + represented as arrays of arrays. Because the number of partitions + can be very large, this function returns an iterator object. Use + ``collect(partitions(array))`` to get an array of all partitions. + The number of partitions to generate can be efficiently + computed using ``length(partitions(array))``. + + :: + partitions(array, m) + Generate all set partitions of the elements of an array into exactly m subsets, represented as arrays of arrays. Because the number of partitions can be very large, this function returns an iterator object. @@ -665,8 +1132,21 @@ BitArrays Performs a left rotation operation on ``src`` and put the result into ``dest``. + :: + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on B. + .. function:: rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + :: + rol!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a left rotation operation on ``src`` and put the result into ``dest``. + + :: + rol!(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a left rotation operation on B. .. function:: rol(B::BitArray{1}, i::Integer) -> BitArray{1} @@ -677,8 +1157,21 @@ BitArrays Performs a right rotation operation on ``src`` and put the result into ``dest``. + :: + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on B. + .. function:: ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + :: + ror!(dest::BitArray{1}, src::BitArray{1}, i::Integer) -> BitArray{1} + + Performs a right rotation operation on ``src`` and put the result into ``dest``. + + :: + ror!(B::BitArray{1}, i::Integer) -> BitArray{1} + Performs a right rotation operation on B. .. function:: ror(B::BitArray{1}, i::Integer) -> BitArray{1} @@ -696,30 +1189,96 @@ Sparse matrices support much of the same set of operations as dense matrices. Th Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``. The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. + :: + sparse(A) + + Convert an AbstractMatrix ``A`` into a sparse matrix. + .. function:: sparsevec(I, V, [m, combine]) Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + :: + sparsevec(D::Dict, [m]) + + Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + + :: + sparsevec(A) + + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + .. function:: sparsevec(D::Dict, [m]) + :: + sparsevec(I, V, [m, combine]) + + Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + + :: + sparsevec(D::Dict, [m]) + Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + :: + sparsevec(A) + + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. + .. function:: issparse(S) Returns ``true`` if ``S`` is sparse, and ``false`` otherwise. .. function:: sparse(A) + :: + sparse(I,J,V,[m,n,combine]) + + Create a sparse matrix ``S`` of dimensions ``m x n`` such that ``S[I[k], J[k]] = V[k]``. The ``combine`` function is used to combine duplicates. If ``m`` and ``n`` are not specified, they are set to ``max(I)`` and ``max(J)`` respectively. If the ``combine`` function is not supplied, duplicates are added by default. + + :: + sparse(A) + Convert an AbstractMatrix ``A`` into a sparse matrix. .. function:: sparsevec(A) + :: + sparsevec(I, V, [m, combine]) + + Create a sparse matrix ``S`` of size ``m x 1`` such that ``S[I[k]] = V[k]``. Duplicates are combined using the ``combine`` function, which defaults to ``+`` if it is not provided. In julia, sparse vectors are really just sparse matrices with one column. Given Julia's Compressed Sparse Columns (CSC) storage format, a sparse column matrix with one column is sparse, whereas a sparse row matrix with one row ends up being dense. + + :: + sparsevec(D::Dict, [m]) + + Create a sparse matrix of size ``m x 1`` where the row values are keys from the dictionary, and the nonzero values are the values from the dictionary. + + :: + sparsevec(A) + Convert a dense vector ``A`` into a sparse matrix of size ``m x 1``. In julia, sparse vectors are really just sparse matrices with one column. .. function:: full(S) Convert a sparse matrix ``S`` into a dense matrix. + :: + full(F) + + Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. + + :: + full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` + object, i.e. in the compact WY format [Bischof1987]_, to a dense matrix. + + Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the + columns that span the rows of ``R`` in the QR factorization that are zero. + The resulting matrix is the ``Q`` in a thin QR factorization (sometimes + called the reduced QR factorization). If ``false``, returns a ``Q`` that + spans all rows of ``R`` in its corresponding QR factorization. + .. function:: nnz(A) Returns the number of stored (filled) elements in a sparse matrix. @@ -783,3 +1342,4 @@ Sparse matrices support much of the same set of operations as dense matrices. Th # perform sparse wizardry... end end + diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index 15d04f254a9e2..66a2eb5f30f7b 100644 --- a/doc/stdlib/base.rst +++ b/doc/stdlib/base.rst @@ -50,8 +50,21 @@ Getting Around Edit a file optionally providing a line number to edit at. Returns to the julia prompt when you quit the editor. + :: + edit(function, [types]) + + Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. + .. function:: edit(function, [types]) + :: + edit(file::AbstractString, [line]) + + Edit a file optionally providing a line number to edit at. Returns to the julia prompt when you quit the editor. + + :: + edit(function, [types]) + Edit the definition of a function, optionally specifying a tuple of types to indicate which method to edit. .. function:: @edit @@ -62,8 +75,21 @@ Getting Around Show a file using the default pager, optionally providing a starting line number. Returns to the julia prompt when you quit the pager. + :: + less(function, [types]) + + Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. + .. function:: less(function, [types]) + :: + less(file::AbstractString, [line]) + + Show a file using the default pager, optionally providing a starting line number. Returns to the julia prompt when you quit the pager. + + :: + less(function, [types]) + Show the definition of a function using the default pager, optionally specifying a tuple of types to indicate which method to see. .. function:: @less @@ -74,8 +100,21 @@ Getting Around Send a printed form of ``x`` to the operating system clipboard ("copy"). + :: + clipboard() -> AbstractString + + Return a string with the contents of the operating system clipboard ("paste"). + .. function:: clipboard() -> AbstractString + :: + clipboard(x) + + Send a printed form of ``x`` to the operating system clipboard ("copy"). + + :: + clipboard() -> AbstractString + Return a string with the contents of the operating system clipboard ("paste"). .. function:: require(module::Symbol) @@ -105,8 +144,25 @@ Getting Around If ``types`` is an abstract type, then the method that would be called by ``invoke`` is returned. + :: + which(symbol) + + Return the module in which the binding for the variable referenced + by ``symbol`` was created. + .. function:: which(symbol) + :: + which(f, types) + + Returns the method of ``f`` (a ``Method`` object) that would be called for arguments of the given types. + + If ``types`` is an abstract type, then the method that would be called by ``invoke`` + is returned. + + :: + which(symbol) + Return the module in which the binding for the variable referenced by ``symbol`` was created. @@ -159,6 +215,8 @@ All Objects ----------- .. function:: is(x, y) -> Bool + + :: ===(x,y) -> Bool ≡(x,y) -> Bool @@ -332,7 +390,10 @@ Types .. function:: <:(T1, T2) - Subtype operator, equivalent to ``issubtype(T1,T2)``. + :: + 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:: subtypes(T::DataType) @@ -362,13 +423,26 @@ Types Size, in bytes, of the canonical binary representation of the given type, if any. + :: + sizeof(s::AbstractString) + + The number of bytes in string ``s``. + .. function:: eps([type]) - The distance between 1.0 and the next larger representable floating-point value of ``type``. Only floating-point types are sensible arguments. If ``type`` is omitted, then ``eps(Float64)`` is returned. + :: + eps(::DateTime) -> Millisecond + eps(::Date) -> Day + + Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. .. function:: eps(x) - The distance between ``x`` and the next larger representable floating-point value of the same type as ``x``. + :: + eps(::DateTime) -> Millisecond + eps(::Date) -> Day + + Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. .. function:: promote_type(type1, type2) @@ -558,10 +632,34 @@ Syntax Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + :: + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. + + :: + parse(type, str, [base]) + + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. + If the string does not contain a valid number, an error is raised. + .. function:: parse(str; raise=true) + :: + parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + + :: + parse(str; raise=true) + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. + :: + parse(type, str, [base]) + + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. + If the string does not contain a valid number, an error is raised. Nullables --------- @@ -577,16 +675,60 @@ Nullables 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. + + This is intended to be called using ``do`` block syntax:: + + get(dict, key) do + # default value calculated here + .. function:: get(x, y) + :: + 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. + + This is intended to be called using ``do`` block syntax:: + + get(dict, key) do + # default value calculated here + .. function:: isnull(x) Is the ``Nullable`` object ``x`` null, i.e. missing a value? - System ------ @@ -619,6 +761,12 @@ System Send a signal to a process. The default is to terminate the process. + :: + kill(manager::FooManager, pid::Int, config::WorkerConfig) + + Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified + by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` + .. function:: open(command, mode::AbstractString="r", stdio=DevNull) Start running ``command`` asynchronously, and return a tuple @@ -629,13 +777,87 @@ System and ``stdio`` optionally specifies the process's standard output stream. + :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` + on the resulting read or write stream, then closes the stream + and waits for the process to complete. Returns the value returned + by ``f``. + + :: + open(file_name, [read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + open(file_name, [mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: + + ==== ================================= + r read + r+ read, write + w write, create, truncate + w+ read, write, create, truncate + a write, create, append + a+ read, write, create, append + ==== ================================= + + :: + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + **Example**: ``open(readall, "file.txt")`` + .. function:: open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + :: + open(command, mode::AbstractString="r", stdio=DevNull) + + Start running ``command`` asynchronously, and return a tuple + ``(stream,process)``. If ``mode`` is ``"r"``, then ``stream`` + reads from the process's standard output and ``stdio`` optionally + specifies the process's standard input stream. If ``mode`` is + ``"w"``, then ``stream`` writes to the process's standard input + and ``stdio`` optionally specifies the process's standard output + stream. + + :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` on the resulting read or write stream, then closes the stream and waits for the process to complete. Returns the value returned by ``f``. + :: + open(file_name, [read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + open(file_name, [mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: + + ==== ================================= + r read + r+ read, write + w write, create, truncate + w+ read, write, create, truncate + a write, create, append + a+ read, write, create, append + ==== ================================= + + :: + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + **Example**: ``open(readall, "file.txt")`` + .. function:: Sys.set_process_title(title::AbstractString) Set the process title. No-op on some operating systems. (not exported) @@ -689,8 +911,41 @@ System * ``run(pipe(`ls`, "out.txt"))`` * ``run(pipe("out.txt", `grep xyz`))`` + :: + pipe(command; stdin, stdout, stderr, append=false) + + Redirect I/O to or from the given ``command``. Keyword arguments specify which of + the command's streams should be redirected. ``append`` controls whether file output + appends to the file. + This is a more general version of the 2-argument ``pipe`` function. + ``pipe(from, to)`` is equivalent to ``pipe(from, stdout=to)`` when ``from`` is a + command, and to ``pipe(to, stdin=from)`` when ``from`` is another kind of + data source. + + **Examples**: + * ``run(pipe(`dothings`, stdout="out.txt", stderr="errs.txt"))`` + * ``run(pipe(`update`, stdout="log.txt", append=true))`` + .. function:: pipe(command; stdin, stdout, stderr, append=false) + :: + pipe(from, to, ...) + + Create a pipeline from a data source to a destination. The source and destination can + be commands, I/O streams, strings, or results of other ``pipe`` calls. At least one + argument must be a command. Strings refer to filenames. + When called with more than two arguments, they are chained together from left to right. + For example ``pipe(a,b,c)`` is equivalent to ``pipe(pipe(a,b),c)``. This provides a more + concise way to specify multi-stage pipelines. + + **Examples**: + * ``run(pipe(`ls`, `grep xyz`))`` + * ``run(pipe(`ls`, "out.txt"))`` + * ``run(pipe("out.txt", `grep xyz`))`` + + :: + pipe(command; stdin, stdout, stderr, append=false) + Redirect I/O to or from the given ``command``. Keyword arguments specify which of the command's streams should be redirected. ``append`` controls whether file output appends to the file. @@ -786,7 +1041,6 @@ System 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 ------ @@ -930,8 +1184,30 @@ Events Times are in seconds. A timer is stopped and has its resources freed by calling ``close`` on it. + :: + Timer(delay, repeat=0) + + Create a timer that wakes up tasks waiting for it (by calling ``wait`` on + the timer object) at a specified interval. + Waiting tasks are also woken up when the timer is closed (by ``close``). + Use ``isopen`` to check whether a timer is still active after a wakeup. + .. function:: Timer(delay, repeat=0) + :: + Timer(callback::Function, delay, repeat=0) + + Create a timer to call the given callback function. + The callback is passed one argument, the timer object itself. + The callback will be invoked after the specified initial delay, + and then repeating with the given ``repeat`` interval. + If ``repeat`` is ``0``, the timer is only triggered once. + Times are in seconds. + A timer is stopped and has its resources freed by calling ``close`` on it. + + :: + 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 also woken up when the timer is closed (by ``close``). @@ -993,8 +1269,21 @@ Reflection Returns a tuple ``(filename,line)`` giving the location of a method definition. + :: + functionloc(m::Method) + + Returns a tuple ``(filename,line)`` giving the location of a method definition. + .. function:: functionloc(m::Method) + :: + functionloc(f::Function, types) + + Returns a tuple ``(filename,line)`` giving the location of a method definition. + + :: + functionloc(m::Method) + Returns a tuple ``(filename,line)`` giving the location of a method definition. Internals @@ -1065,3 +1354,4 @@ Internals .. function:: precompile(f,args::Tuple{Vararg{Any}}) Compile the given function ``f`` for the argument tuple (of types) ``args``, but do not execute it. + diff --git a/doc/stdlib/c.rst b/doc/stdlib/c.rst index 2d24a41c6bb43..81fbf0084b7cc 100644 --- a/doc/stdlib/c.rst +++ b/doc/stdlib/c.rst @@ -90,8 +90,31 @@ on the pointers ``dest`` and ``src`` to ensure that they are valid. Incorrect usage may corrupt or segfault your program, in the same manner as C. + :: + unsafe_copy!(dest::Array, do, src::Array, so, N) + + Copy ``N`` elements from a source array to a destination, starting at offset ``so`` + in the source and ``do`` in the destination (1-indexed). + + The ``unsafe`` prefix on this function indicates that no validation is performed + to ensure that N is inbounds on either array. Incorrect usage may corrupt or segfault + your program, in the same manner as C. + .. function:: unsafe_copy!(dest::Array, do, src::Array, so, N) + :: + unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) + + Copy ``N`` elements from a source pointer to a destination, with no checking. The + size of an element is determined by the type of the pointers. + + The ``unsafe`` prefix on this function indicates that no validation is performed + on the pointers ``dest`` and ``src`` to ensure that they are valid. + Incorrect usage may corrupt or segfault your program, in the same manner as C. + + :: + unsafe_copy!(dest::Array, do, src::Array, so, N) + Copy ``N`` elements from a source array to a destination, starting at offset ``so`` in the source and ``do`` in the destination (1-indexed). @@ -103,8 +126,22 @@ Copy all elements from collection ``src`` to array ``dest``. Returns ``dest``. + :: + copy!(dest, do, src, so, N) + + Copy ``N`` elements from collection ``src`` starting at offset ``so``, to + array ``dest`` starting at offset ``do``. Returns ``dest``. + .. function:: copy!(dest, do, src, so, N) + :: + copy!(dest, src) + + Copy all elements from collection ``src`` to array ``dest``. Returns ``dest``. + + :: + copy!(dest, do, src, so, N) + Copy ``N`` elements from collection ``src`` starting at offset ``so``, to array ``dest`` starting at offset ``do``. Returns ``dest``. diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index d52c7ab836e41..03e4abe2892d2 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -125,8 +125,21 @@ General Collections .. function:: length(collection) -> Integer + :: + length(A) -> Integer + + Returns the number of elements in A + + :: + length(collection) -> Integer + For ordered, indexable collections, the maximum index ``i`` for which ``getindex(collection, i)`` is valid. For unordered collections, the number of elements. + :: + length(s) + + The number of characters in string ``s``. + .. function:: endof(collection) -> Integer Returns the last index of the collection. @@ -153,6 +166,8 @@ Iterable Collections -------------------- .. function:: in(item, collection) -> Bool + + :: ∈(item,collection) -> Bool ∋(collection,item) -> Bool ∉(item,collection) -> Bool @@ -214,8 +229,43 @@ Iterable Collections of Julia might change the algorithm. Note that the elements are not reordered if you use an ordered collection. + :: + reduce(op, itr) + + Like ``reduce(op, v0, itr)``. This cannot be used with empty + collections, except for some special cases (e.g. when ``op`` is one + of ``+``, ``*``, ``max``, ``min``, ``&``, ``|``) when Julia can + determine the neutral element of ``op``. + .. function:: reduce(op, itr) + :: + reduce(op, v0, itr) + + Reduce the given collection ``ìtr`` with the given binary operator + ``op``. ``v0`` must be a neutral element for ``op`` that will be + returned for empty collections. It is unspecified whether ``v0`` is + used for non-empty collections. + + Reductions for certain commonly-used operators have special + implementations which should be used instead: ``maximum(itr)``, + ``minimum(itr)``, ``sum(itr)``, ``prod(itr)``, ``any(itr)``, + ``all(itr)``. + + The associativity of the reduction is implementation dependent. + This means that you can't use non-associative operations like ``-`` + because it is undefined whether ``reduce(-,[1,2,3])`` should be + evaluated as ``(1-2)-3`` or ``1-(2-3)``. Use ``foldl`` or ``foldr`` + instead for guaranteed left or right associativity. + + Some operations accumulate error, and parallelism will also be + easier if the reduction can be executed in groups. Future versions + of Julia might change the algorithm. Note that the elements are not + reordered if you use an ordered collection. + + :: + reduce(op, itr) + Like ``reduce(op, v0, itr)``. This cannot be used with empty collections, except for some special cases (e.g. when ``op`` is one of ``+``, ``*``, ``max``, ``min``, ``&``, ``|``) when Julia can @@ -226,8 +276,24 @@ Iterable Collections Like :func:`reduce`, but with guaranteed left associativity. ``v0`` will be used exactly once. + :: + foldl(op, itr) + + Like ``foldl(op, v0, itr)``, but using the first element of ``itr`` + as ``v0``. In general, this cannot be used with empty collections + (see ``reduce(op, itr)``). + .. function:: foldl(op, itr) + :: + foldl(op, v0, itr) + + Like :func:`reduce`, but with guaranteed left associativity. ``v0`` + will be used exactly once. + + :: + foldl(op, itr) + Like ``foldl(op, v0, itr)``, but using the first element of ``itr`` as ``v0``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). @@ -237,8 +303,24 @@ Iterable Collections Like :func:`reduce`, but with guaranteed right associativity. ``v0`` will be used exactly once. + :: + foldr(op, itr) + + Like ``foldr(op, v0, itr)``, but using the last element of ``itr`` + as ``v0``. In general, this cannot be used with empty collections + (see ``reduce(op, itr)``). + .. function:: foldr(op, itr) + :: + foldr(op, v0, itr) + + Like :func:`reduce`, but with guaranteed right associativity. ``v0`` + will be used exactly once. + + :: + foldr(op, itr) + Like ``foldr(op, v0, itr)``, but using the last element of ``itr`` as ``v0``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). @@ -247,8 +329,21 @@ Iterable Collections Returns the largest element in a collection. + :: + maximum(A, dims) + + Compute the maximum value of an array over the given dimensions. + .. function:: maximum(A, dims) + :: + maximum(itr) + + Returns the largest element in a collection. + + :: + maximum(A, dims) + Compute the maximum value of an array over the given dimensions. .. function:: maximum!(r, A) @@ -260,8 +355,21 @@ Iterable Collections Returns the smallest element in a collection. + :: + minimum(A, dims) + + Compute the minimum value of an array over the given dimensions. + .. function:: minimum(A, dims) + :: + minimum(itr) + + Returns the smallest element in a collection. + + :: + minimum(A, dims) + Compute the minimum value of an array over the given dimensions. .. function:: minimum!(r, A) @@ -286,8 +394,22 @@ Iterable Collections Returns the maximum element and its index. + :: + findmax(A, dims) -> (maxval, index) + + For an array input, returns the value and index of the maximum over + the given dimensions. + .. function:: findmax(A, dims) -> (maxval, index) + :: + findmax(itr) -> (x, index) + + Returns the maximum element and its index. + + :: + findmax(A, dims) -> (maxval, index) + For an array input, returns the value and index of the maximum over the given dimensions. @@ -295,8 +417,22 @@ Iterable Collections Returns the minimum element and its index. + :: + findmin(A, dims) -> (minval, index) + + For an array input, returns the value and index of the minimum over + the given dimensions. + .. function:: findmin(A, dims) -> (minval, index) + :: + findmin(itr) -> (x, index) + + Returns the minimum element and its index. + + :: + findmin(A, dims) -> (minval, index) + For an array input, returns the value and index of the minimum over the given dimensions. @@ -304,8 +440,21 @@ Iterable Collections Compute the maximum absolute value of a collection of values. + :: + maxabs(A, dims) + + Compute the maximum absolute values over given dimensions. + .. function:: maxabs(A, dims) + :: + maxabs(itr) + + Compute the maximum absolute value of a collection of values. + + :: + maxabs(A, dims) + Compute the maximum absolute values over given dimensions. .. function:: maxabs!(r, A) @@ -317,8 +466,21 @@ Iterable Collections Compute the minimum absolute value of a collection of values. + :: + minabs(A, dims) + + Compute the minimum absolute values over given dimensions. + .. function:: minabs(A, dims) + :: + minabs(itr) + + Compute the minimum absolute value of a collection of values. + + :: + minabs(A, dims) + Compute the minimum absolute values over given dimensions. .. function:: minabs!(r, A) @@ -330,10 +492,33 @@ Iterable Collections Returns the sum of all elements in a collection. + :: + sum(A, dims) + + Sum elements of an array over the given dimensions. + + :: + sum(f, itr) + + Sum the results of calling function ``f`` on each element of ``itr``. + .. function:: sum(A, dims) + :: + sum(itr) + + Returns the sum of all elements in a collection. + + :: + sum(A, dims) + Sum elements of an array over the given dimensions. + :: + sum(f, itr) + + Sum the results of calling function ``f`` on each element of ``itr``. + .. function:: sum!(r, A) Sum elements of ``A`` over the singleton dimensions of ``r``, @@ -341,6 +526,19 @@ Iterable Collections .. function:: sum(f, itr) + :: + sum(itr) + + Returns the sum of all elements in a collection. + + :: + sum(A, dims) + + Sum elements of an array over the given dimensions. + + :: + sum(f, itr) + Sum the results of calling function ``f`` on each element of ``itr``. .. function:: sumabs(itr) @@ -348,8 +546,23 @@ Iterable Collections Sum absolute values of all elements in a collection. This is equivalent to `sum(abs(itr))` but faster. + :: + sumabs(A, dims) + + Sum absolute values of elements of an array over the given + dimensions. + .. function:: sumabs(A, dims) + :: + sumabs(itr) + + Sum absolute values of all elements in a collection. This is + equivalent to `sum(abs(itr))` but faster. + + :: + sumabs(A, dims) + Sum absolute values of elements of an array over the given dimensions. @@ -363,8 +576,23 @@ Iterable Collections Sum squared absolute values of all elements in a collection. This is equivalent to `sum(abs2(itr))` but faster. + :: + sumabs2(A, dims) + + Sum squared absolute values of elements of an array over the given + dimensions. + .. function:: sumabs2(A, dims) + :: + sumabs2(itr) + + Sum squared absolute values of all elements in a collection. This + is equivalent to `sum(abs2(itr))` but faster. + + :: + sumabs2(A, dims) + Sum squared absolute values of elements of an array over the given dimensions. @@ -377,8 +605,21 @@ Iterable Collections Returns the product of all elements of a collection. + :: + prod(A, dims) + + Multiply elements of an array over the given dimensions. + .. function:: prod(A, dims) + :: + prod(itr) + + Returns the product of all elements of a collection. + + :: + prod(A, dims) + Multiply elements of an array over the given dimensions. .. function:: prod!(r, A) @@ -390,10 +631,33 @@ Iterable Collections Test whether any elements of a boolean collection are true. + :: + any(A, dims) + + Test whether any values along the given dimensions of an array are true. + + :: + any(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for any elements of ``itr``. + .. function:: any(A, dims) + :: + any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + :: + any(A, dims) + Test whether any values along the given dimensions of an array are true. + :: + any(p, itr) -> Bool + + Determine whether predicate ``p`` returns true for any elements of ``itr``. + .. function:: any!(r, A) Test whether any values in ``A`` along the singleton dimensions of ``r`` are true, @@ -403,10 +667,43 @@ Iterable Collections 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``. + + .. doctest:: + + julia> all(i->(4<=i<=6), [4,5,6]) + true + .. function:: all(A, dims) + :: + 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``. + + .. doctest:: + + julia> all(i->(4<=i<=6), [4,5,6]) + true + .. function:: all!(r, A) Test whether all values in ``A`` along the singleton dimensions of ``r`` are true, @@ -418,10 +715,36 @@ Iterable Collections .. function:: any(p, itr) -> Bool + :: + any(itr) -> Bool + + Test whether any elements of a boolean collection are true. + + :: + any(A, dims) + + Test whether any values along the given dimensions of an array are true. + + :: + any(p, itr) -> Bool + Determine whether predicate ``p`` returns true for any elements of ``itr``. .. function:: all(p, itr) -> Bool + :: + 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``. .. doctest:: @@ -452,8 +775,23 @@ Iterable Collections In-place version of :func:`map`. + :: + map!(function, destination, collection...) + + Like :func:`map`, but stores the result in ``destination`` rather than a + new collection. ``destination`` must be at least as large as the first + collection. + .. function:: map!(function, destination, collection...) + :: + 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 new collection. ``destination`` must be at least as large as the first collection. @@ -482,8 +820,42 @@ Iterable Collections Use :func:`mapfoldl` or :func:`mapfoldr` instead for guaranteed left or right associativity and invocation of ``f`` for every value. + :: + mapreduce(f, op, itr) + + Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used + with empty collections (see ``reduce(op, itr)``). + .. function:: mapreduce(f, op, itr) + :: + mapreduce(f, op, v0, itr) + + Apply function ``f`` to each element in ``itr``, and then reduce + the result using the binary function ``op``. ``v0`` must be a + neutral element for ``op`` that will be returned for empty + collections. It is unspecified whether ``v0`` is used for non-empty + collections. + + :func:`mapreduce` is functionally equivalent to calling ``reduce(op, + v0, map(f, itr))``, but will in general execute faster since no + intermediate collection needs to be created. See documentation for + :func:`reduce` and :func:`map`. + + .. doctest:: + + julia> mapreduce(x->x^2, +, [1:3;]) # == 1 + 4 + 9 + 14 + + The associativity of the reduction is implementation-dependent. + Additionally, some implementations may reuse the return value of + ``f`` for elements that appear multiple times in ``itr``. + Use :func:`mapfoldl` or :func:`mapfoldr` instead for guaranteed + left or right associativity and invocation of ``f`` for every value. + + :: + mapreduce(f, op, itr) + Like ``mapreduce(f, op, v0, itr)``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). @@ -492,8 +864,24 @@ Iterable Collections 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 + ``itr`` as ``v0``. In general, this cannot be used with empty + collections (see ``reduce(op, itr)``). + .. function:: mapfoldl(f, op, itr) + :: + 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 ``itr`` as ``v0``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). @@ -503,8 +891,24 @@ Iterable Collections 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 + ``itr`` as ``v0``. In general, this cannot be used with empty + collections (see ``reduce(op, itr)``). + .. function:: mapfoldr(f, op, itr) + :: + 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 ``itr`` as ``v0``. In general, this cannot be used with empty collections (see ``reduce(op, itr)``). @@ -528,17 +932,38 @@ Iterable Collections Return an array of all items in a collection. For associative collections, returns (key, value) tuples. + :: + collect(element_type, collection) + + Return an array of type ``Array{element_type,1}`` of all items in a collection. + .. function:: collect(element_type, collection) + :: + collect(collection) + + Return an array of all items in a collection. For associative collections, returns (key, value) tuples. + + :: + collect(element_type, collection) + Return an array of type ``Array{element_type,1}`` of all items in a collection. .. function:: issubset(a, b) + + :: ⊆(A,S) -> Bool ⊈(A,S) -> Bool ⊊(A,S) -> Bool Determine whether every element of ``a`` is also in ``b``, using :func:`in`. + :: + issubset(A, S) -> Bool + ⊆(A,S) -> Bool + + True if A is a subset of or equal to S. + .. function:: filter(function, collection) Return a copy of ``collection``, removing elements for which ``function`` is false. @@ -549,18 +974,38 @@ Iterable Collections Update ``collection``, removing elements for which ``function`` is false. For associative collections, the function is passed two arguments (key and value). - Indexable Collections --------------------- .. function:: getindex(collection, key...) + :: + getindex(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. The syntax ``a[i,j,...]`` is converted by the compiler to ``getindex(a, i, j, ...)``. .. function:: setindex!(collection, value, key...) + :: + setindex!(A, X, inds...) + + Store values from array ``X`` within some subset of ``A`` as specified by ``inds``. + + :: + setindex!(collection, value, key...) + Store the given value at the given key or index within a collection. The syntax ``a[i,j,...] = x`` is converted by the compiler to ``setindex!(a, x, i, j, ...)``. @@ -629,16 +1074,62 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if .. function:: get(collection, key, default) + :: + 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. + + This is intended to be called using ``do`` block syntax:: + + get(dict, key) do + # default value calculated here + .. function:: get(f::Function, collection, key) + :: + 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. This is intended to be called using ``do`` block syntax:: get(dict, key) do # default value calculated here + time() end @@ -646,14 +1137,33 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if Return the value stored for the given key, or if no mapping for the key is present, store ``key => default``, and return ``default``. + :: + get!(f::Function, collection, key) + + Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``, and return ``f()``. + + This is intended to be called using ``do`` block syntax:: + + get!(dict, key) do + # default value calculated here + .. function:: get!(f::Function, collection, key) + :: + get!(collection, key, default) + + Return the value stored for the given key, or if no mapping for the key is present, store ``key => default``, and return ``default``. + + :: + get!(f::Function, collection, key) + Return the value stored for the given key, or if no mapping for the key is present, store ``key => f()``, and return ``f()``. This is intended to be called using ``do`` block syntax:: get!(dict, key) do # default value calculated here + time() end @@ -669,6 +1179,33 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if 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. + + .. doctest:: + + julia> A=[1, 2, 3, 4, 5, 6] + 6-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + 6 + + julia> pop!(A) + 6 + + julia> A + 5-element Array{Int64,1}: + 1 + 2 + 3 + 4 + 5 + .. function:: keys(collection) Return an iterator over all keys in a collection. ``collect(keys(d))`` returns an array of keys. @@ -740,6 +1277,8 @@ Set-Like Collections 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) Construct the union of two or more sets. Maintains order with arrays. @@ -749,6 +1288,8 @@ Set-Like Collections Union each element of ``iterable`` into set ``s`` in-place. .. function:: intersect(s1,s2...) + + :: ∩(s1,s2) Construct the intersection of two or more sets. Maintains order and multiplicity of the first argument for arrays and ranges. @@ -772,12 +1313,48 @@ Set-Like Collections The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + :: + symdiff!(s, itr) + + For each element in ``itr``, destructively toggle its inclusion in set ``s``. + + :: + symdiff!(s1, s2) + + Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + .. function:: symdiff!(s, itr) + :: + symdiff!(s, n) + + The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + + :: + symdiff!(s, itr) + For each element in ``itr``, destructively toggle its inclusion in set ``s``. + :: + symdiff!(s1, s2) + + Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. + .. function:: symdiff!(s1, s2) + :: + symdiff!(s, n) + + The set ``s`` is destructively modified to toggle the inclusion of integer ``n``. + + :: + symdiff!(s, itr) + + For each element in ``itr``, destructively toggle its inclusion in set ``s``. + + :: + symdiff!(s1, s2) + Construct the symmetric difference of sets ``s1`` and ``s2``, storing the result in ``s1``. .. function:: complement(s) @@ -793,6 +1370,17 @@ Set-Like Collections Intersects sets ``s1`` and ``s2`` and overwrites the set ``s1`` with the result. If needed, ``s1`` will be expanded to the size of ``s2``. .. function:: issubset(A, S) -> Bool + + :: + issubset(a, b) + ⊆(A,S) -> Bool + ⊈(A,S) -> Bool + ⊊(A,S) -> Bool + + Determine whether every element of ``a`` is also in ``b``, using :func:`in`. + + :: + issubset(A, S) -> Bool ⊆(A,S) -> Bool True if A is a subset of or equal to S. @@ -831,6 +1419,14 @@ Dequeues .. function:: pop!(collection) -> item + :: + 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. .. doctest:: @@ -927,8 +1523,47 @@ Dequeues 2 1 + :: + deleteat!(collection, itr) + + Remove the items at the indices given by ``itr``, and return the modified ``collection``. + Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. + + .. doctest:: + + julia> deleteat!([6, 5, 4, 3, 2, 1], 1:2:5) + 3-element Array{Int64,1}: + 5 + 3 + 1 + + .. doctest:: + + julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) + ERROR: ArgumentError: indices must be unique and sorted + in deleteat! at array.jl:533 + .. function:: deleteat!(collection, itr) + :: + deleteat!(collection, index) + + Remove the item at the given ``index`` and return the modified ``collection``. + Subsequent items are shifted to fill the resulting gap. + + .. doctest:: + + julia> deleteat!([6, 5, 4, 3, 2, 1], 2) + 5-element Array{Int64,1}: + 6 + 4 + 3 + 2 + 1 + + :: + deleteat!(collection, itr) + Remove the items at the indices given by ``itr``, and return the modified ``collection``. Subsequent items are shifted to fill the resulting gap. ``itr`` must be sorted and unique. @@ -992,8 +1627,85 @@ Dequeues To insert ``replacement`` before an index ``n`` without removing any items, use ``splice!(collection, n:n-1, replacement)``. + :: + splice!(collection, range, [replacement]) -> items + + Remove items in the specified index range, and return a collection containing the + removed items. Subsequent items are shifted down to fill the resulting gap. + If specified, replacement values from an ordered collection will be spliced in place + of the removed items. + + To insert ``replacement`` before an index ``n`` without removing any items, use + ``splice!(collection, n:n-1, replacement)``. + + .. doctest:: + + julia> splice!(A, 4:3, 2) + 0-element Array{Int64,1} + + julia> A + 8-element Array{Int64,1}: + -1 + -2 + -3 + 2 + 5 + 4 + 3 + -1 + .. function:: splice!(collection, range, [replacement]) -> items + :: + splice!(collection, index, [replacement]) -> item + + Remove the item at the given index, and return the removed item. Subsequent items + are shifted down to fill the resulting gap. If specified, replacement values from + an ordered collection will be spliced in place of the removed item. + + .. doctest:: + + julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5) + 2 + + julia> A + 5-element Array{Int64,1}: + 6 + 5 + 4 + 3 + 1 + + julia> splice!(A, 5, -1) + 1 + + julia> A + 5-element Array{Int64,1}: + 6 + 5 + 4 + 3 + -1 + + julia> splice!(A, 1, [-1, -2, -3]) + 6 + + julia> A + 7-element Array{Int64,1}: + -1 + -2 + -3 + 5 + 4 + 3 + -1 + + To insert ``replacement`` before an index ``n`` without removing any items, use + ``splice!(collection, n:n-1, replacement)``. + + :: + splice!(collection, range, [replacement]) -> items + Remove items in the specified index range, and return a collection containing the removed items. Subsequent items are shifted down to fill the resulting gap. If specified, replacement values from an ordered collection will be spliced in place diff --git a/doc/stdlib/dates.rst b/doc/stdlib/dates.rst index 0d0cbc54c4d10..ba6553e0236f5 100644 --- a/doc/stdlib/dates.rst +++ b/doc/stdlib/dates.rst @@ -52,13 +52,139 @@ alternatively, you could call ``using Dates`` to bring all exported functions in Construct a DateTime type by parts. Arguments must be convertible to ``Int64``. + :: + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. + DateTime parts not provided will default to the value of ``Dates.default(period)``. + + :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the + provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` + is never satisfied). + + :: + DateTime(dt::Date) -> DateTime + + Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond + parts of the new ``DateTime`` are assumed to be zero. + + :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the ``dt`` date string following the pattern given in + the ``format`` string. The following codes can be used for constructing format strings: + + =============== ========= =============================================================== + Code Matches Comment + --------------- --------- --------------------------------------------------------------- + ``y`` 1996, 96 Returns year of 1996, 0096 + ``m`` 1, 01 Matches 1 or 2-digit months + ``u`` Jan Matches abbreviated months according to the ``locale`` keyword + ``U`` January Matches full month names according to the ``locale`` keyword + ``d`` 1, 01 Matches 1 or 2-digit days + ``H`` 00 Matches hours + ``M`` 00 Matches minutes + ``S`` 00 Matches seconds + ``s`` .500 Matches milliseconds + ``e`` Mon, Tues Matches abbreviated days of the week + ``E`` Monday Matches full name days of the week + ``yyyymmdd`` 19960101 Matches fixed-width year, month, and day + =============== ========= =============================================================== + + All characters not listed above are treated as delimiters between date and time slots. + So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string + like "y-m-dTH:M:S.s". + + :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(periods::Period...) -> DateTime + :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to + ``Int64``. + + :: + DateTime(periods::Period...) -> DateTime + Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. DateTime parts not provided will default to the value of ``Dates.default(period)``. + :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the + provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` + is never satisfied). + + :: + DateTime(dt::Date) -> DateTime + + Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond + parts of the new ``DateTime`` are assumed to be zero. + + :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the ``dt`` date string following the pattern given in + the ``format`` string. The following codes can be used for constructing format strings: + + =============== ========= =============================================================== + Code Matches Comment + --------------- --------- --------------------------------------------------------------- + ``y`` 1996, 96 Returns year of 1996, 0096 + ``m`` 1, 01 Matches 1 or 2-digit months + ``u`` Jan Matches abbreviated months according to the ``locale`` keyword + ``U`` January Matches full month names according to the ``locale`` keyword + ``d`` 1, 01 Matches 1 or 2-digit days + ``H`` 00 Matches hours + ``M`` 00 Matches minutes + ``S`` 00 Matches seconds + ``s`` .500 Matches milliseconds + ``e`` Mon, Tues Matches abbreviated days of the week + ``E`` Monday Matches full name days of the week + ``yyyymmdd`` 19960101 Matches fixed-width year, month, and day + =============== ========= =============================================================== + + All characters not listed above are treated as delimiters between date and time slots. + So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string + like "y-m-dTH:M:S.s". + + :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to + ``Int64``. + + :: + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. + DateTime parts not provided will default to the value of ``Dates.default(period)``. + + :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + Create a DateTime through the adjuster API. The starting point will be constructed from the provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting @@ -66,13 +192,139 @@ alternatively, you could call ``using Dates`` to bring all exported functions in the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` is never satisfied). + :: + DateTime(dt::Date) -> DateTime + + Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond + parts of the new ``DateTime`` are assumed to be zero. + + :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the ``dt`` date string following the pattern given in + the ``format`` string. The following codes can be used for constructing format strings: + + =============== ========= =============================================================== + Code Matches Comment + --------------- --------- --------------------------------------------------------------- + ``y`` 1996, 96 Returns year of 1996, 0096 + ``m`` 1, 01 Matches 1 or 2-digit months + ``u`` Jan Matches abbreviated months according to the ``locale`` keyword + ``U`` January Matches full month names according to the ``locale`` keyword + ``d`` 1, 01 Matches 1 or 2-digit days + ``H`` 00 Matches hours + ``M`` 00 Matches minutes + ``S`` 00 Matches seconds + ``s`` .500 Matches milliseconds + ``e`` Mon, Tues Matches abbreviated days of the week + ``E`` Monday Matches full name days of the week + ``yyyymmdd`` 19960101 Matches fixed-width year, month, and day + =============== ========= =============================================================== + + All characters not listed above are treated as delimiters between date and time slots. + So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string + like "y-m-dTH:M:S.s". + + :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(dt::Date) -> DateTime + :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to + ``Int64``. + + :: + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. + DateTime parts not provided will default to the value of ``Dates.default(period)``. + + :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the + provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` + is never satisfied). + + :: + DateTime(dt::Date) -> DateTime + Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond parts of the new ``DateTime`` are assumed to be zero. + :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the ``dt`` date string following the pattern given in + the ``format`` string. The following codes can be used for constructing format strings: + + =============== ========= =============================================================== + Code Matches Comment + --------------- --------- --------------------------------------------------------------- + ``y`` 1996, 96 Returns year of 1996, 0096 + ``m`` 1, 01 Matches 1 or 2-digit months + ``u`` Jan Matches abbreviated months according to the ``locale`` keyword + ``U`` January Matches full month names according to the ``locale`` keyword + ``d`` 1, 01 Matches 1 or 2-digit days + ``H`` 00 Matches hours + ``M`` 00 Matches minutes + ``S`` 00 Matches seconds + ``s`` .500 Matches milliseconds + ``e`` Mon, Tues Matches abbreviated days of the week + ``E`` Monday Matches full name days of the week + ``yyyymmdd`` 19960101 Matches fixed-width year, month, and day + =============== ========= =============================================================== + + All characters not listed above are treated as delimiters between date and time slots. + So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string + like "y-m-dTH:M:S.s". + + :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to + ``Int64``. + + :: + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. + DateTime parts not provided will default to the value of ``Dates.default(period)``. + + :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the + provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` + is never satisfied). + + :: + DateTime(dt::Date) -> DateTime + + Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond + parts of the new ``DateTime`` are assumed to be zero. + + :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + Construct a DateTime type by parsing the ``dt`` date string following the pattern given in the ``format`` string. The following codes can be used for constructing format strings: @@ -97,12 +349,75 @@ alternatively, you could call ``using Dates`` to bring all exported functions in So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string like "y-m-dTH:M:S.s". + :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + + Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. + .. function:: 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 + :: + DateTime(y, [m, d, h, mi, s, ms]) -> DateTime + + Construct a DateTime type by parts. Arguments must be convertible to + ``Int64``. + + :: + DateTime(periods::Period...) -> DateTime + + Constuct a DateTime type by ``Period`` type parts. Arguments may be in any order. + DateTime parts not provided will default to the value of ``Dates.default(period)``. + + :: + DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) -> DateTime + + Create a DateTime through the adjuster API. The starting point will be constructed from the + provided ``y, m, d...`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (in the case that ``f::Function`` + is never satisfied). + + :: + DateTime(dt::Date) -> DateTime + + Converts a ``Date`` type to a ``DateTime``. The hour, minute, second, and millisecond + parts of the new ``DateTime`` are assumed to be zero. + + :: + DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime + + Construct a DateTime type by parsing the ``dt`` date string following the pattern given in + the ``format`` string. The following codes can be used for constructing format strings: + + =============== ========= =============================================================== + Code Matches Comment + --------------- --------- --------------------------------------------------------------- + ``y`` 1996, 96 Returns year of 1996, 0096 + ``m`` 1, 01 Matches 1 or 2-digit months + ``u`` Jan Matches abbreviated months according to the ``locale`` keyword + ``U`` January Matches full month names according to the ``locale`` keyword + ``d`` 1, 01 Matches 1 or 2-digit days + ``H`` 00 Matches hours + ``M`` 00 Matches minutes + ``S`` 00 Matches seconds + ``s`` .500 Matches milliseconds + ``e`` Mon, Tues Matches abbreviated days of the week + ``E`` Monday Matches full name days of the week + ``yyyymmdd`` 19960101 Matches fixed-width year, month, and day + =============== ========= =============================================================== + + All characters not listed above are treated as delimiters between date and time slots. + So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string + like "y-m-dTH:M:S.s". + + :: + DateTime(dt::AbstractString, df::DateFormat) -> DateTime + Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing. .. function:: Date(y, [m, d]) -> Date @@ -110,13 +425,97 @@ alternatively, you could call ``using Dates`` to bring all exported functions in Construct a ``Date`` type by parts. Arguments must be convertible to ``Int64``. + :: + Date(period::Period...) -> Date + + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. + Date parts not provided will default to the value of ``Dates.default(period)``. + + :: + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the + provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` + is never satisfied). + + :: + Date(dt::DateTime) -> Date + + Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond + parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + + :: + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a ``dt`` date string following the pattern given in + the ``format`` string. Follows the same conventions as ``DateTime`` above. + + :: + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(period::Period...) -> Date + :: + Date(y, [m, d]) -> Date + + Construct a ``Date`` type by parts. Arguments must be convertible to + ``Int64``. + + :: + Date(period::Period...) -> Date + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. Date parts not provided will default to the value of ``Dates.default(period)``. + :: + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the + provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` + is never satisfied). + + :: + Date(dt::DateTime) -> Date + + Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond + parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + + :: + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a ``dt`` date string following the pattern given in + the ``format`` string. Follows the same conventions as ``DateTime`` above. + + :: + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + :: + Date(y, [m, d]) -> Date + + Construct a ``Date`` type by parts. Arguments must be convertible to + ``Int64``. + + :: + Date(period::Period...) -> Date + + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. + Date parts not provided will default to the value of ``Dates.default(period)``. + + :: + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + Create a Date through the adjuster API. The starting point will be constructed from the provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting @@ -124,18 +523,144 @@ alternatively, you could call ``using Dates`` to bring all exported functions in the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` is never satisfied). + :: + Date(dt::DateTime) -> Date + + Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond + parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + + :: + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a ``dt`` date string following the pattern given in + the ``format`` string. Follows the same conventions as ``DateTime`` above. + + :: + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(dt::DateTime) -> Date + :: + Date(y, [m, d]) -> Date + + Construct a ``Date`` type by parts. Arguments must be convertible to + ``Int64``. + + :: + Date(period::Period...) -> Date + + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. + Date parts not provided will default to the value of ``Dates.default(period)``. + + :: + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the + provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` + is never satisfied). + + :: + Date(dt::DateTime) -> Date + Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + :: + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a ``dt`` date string following the pattern given in + the ``format`` string. Follows the same conventions as ``DateTime`` above. + + :: + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + :: + Date(y, [m, d]) -> Date + + Construct a ``Date`` type by parts. Arguments must be convertible to + ``Int64``. + + :: + Date(period::Period...) -> Date + + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. + Date parts not provided will default to the value of ``Dates.default(period)``. + + :: + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the + provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` + is never satisfied). + + :: + Date(dt::DateTime) -> Date + + Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond + parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + + :: + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + Construct a Date type by parsing a ``dt`` date string following the pattern given in the ``format`` string. Follows the same conventions as ``DateTime`` above. + :: + Date(dt::AbstractString, df::DateFormat) -> Date + + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. + .. function:: Date(dt::AbstractString, df::DateFormat) -> Date + :: + Date(y, [m, d]) -> Date + + Construct a ``Date`` type by parts. Arguments must be convertible to + ``Int64``. + + :: + Date(period::Period...) -> Date + + Constuct a Date type by ``Period`` type parts. Arguments may be in any order. + Date parts not provided will default to the value of ``Dates.default(period)``. + + :: + Date(f::Function, y[, m]; step=Day(1), negate=false, limit=10000) -> Date + + Create a Date through the adjuster API. The starting point will be constructed from the + provided ``y, m`` arguments, and will be adjusted until ``f::Function`` returns true. The step size in + adjusting can be provided manually through the ``step`` keyword. If ``negate=true``, then the adjusting + will stop when ``f::Function`` returns false instead of true. ``limit`` provides a limit to + the max number of iterations the adjustment API will pursue before throwing an error (given that ``f::Function`` + is never satisfied). + + :: + Date(dt::DateTime) -> Date + + Converts a ``DateTime`` type to a ``Date``. The hour, minute, second, and millisecond + parts of the ``DateTime`` are truncated, so only the year, month and day parts are used in construction. + + :: + Date(dt::AbstractString, format::AbstractString; locale="english") -> Date + + Construct a Date type by parsing a ``dt`` date string following the pattern given in + the ``format`` string. Follows the same conventions as ``DateTime`` above. + + :: + Date(dt::AbstractString, df::DateFormat) -> Date + Parse a date from a date string ``dt`` using a ``DateFormat`` object ``df``. .. function:: now() -> DateTime @@ -143,12 +668,29 @@ alternatively, you could call ``using Dates`` to bring all exported functions in Returns a DateTime corresponding to the user's system time including the system timezone locale. + :: + now(::Type{UTC}) -> DateTime + + Returns a DateTime corresponding to the user's system + time as UTC/GMT. + .. function:: now(::Type{UTC}) -> DateTime + :: + now() -> DateTime + + Returns a DateTime corresponding to the user's system + time including the system timezone locale. + + :: + now(::Type{UTC}) -> DateTime + Returns a DateTime corresponding to the user's system time as UTC/GMT. .. function:: eps(::DateTime) -> Millisecond + + :: eps(::Date) -> Day Returns ``Millisecond(1)`` for ``DateTime`` values and ``Day(1)`` for ``Date`` values. @@ -157,6 +699,8 @@ Accessor Functions ~~~~~~~~~~~~~~~~~~ .. function:: year(dt::TimeType) -> Int64 + + :: month(dt::TimeType) -> Int64 week(dt::TimeType) -> Int64 day(dt::TimeType) -> Int64 @@ -168,6 +712,8 @@ Accessor Functions 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 @@ -178,6 +724,19 @@ Accessor Functions 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``. + .. function:: yearmonth(dt::TimeType) -> (Int64, Int64) Simultaneously return the year and month parts of a Date or DateTime. @@ -298,12 +857,28 @@ Adjuster Functions ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current ``dt`` to be considered as the next ``dow``, allowing for no adjustment to occur. + :: + tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until + ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. + ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment + process terminate when ``func`` returns false instead of true. + .. function:: toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType Adjusts ``dt`` to the previous day of week corresponding to ``dow`` with ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current ``dt`` to be considered as the previous ``dow``, allowing for no adjustment to occur. + :: + toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType + + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until + ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. + ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment + process terminate when ``func`` returns false instead of true. + .. function:: tofirst(dt::TimeType,dow::Int;of=Month) -> TimeType Adjusts ``dt`` to the first ``dow`` of its month. Alternatively, ``of=Year`` @@ -316,6 +891,16 @@ Adjuster Functions .. 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 + + Adjusts ``dt`` to the next day of week corresponding to ``dow`` with + ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current + ``dt`` to be considered as the next ``dow``, allowing for no adjustment to occur. + + :: + tonext(func::Function,dt::TimeType;step=Day(1),negate=false,limit=10000,same=false) -> TimeType + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment @@ -323,6 +908,16 @@ Adjuster Functions .. 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 + + Adjusts ``dt`` to the previous day of week corresponding to ``dow`` with + ``1 = Monday, 2 = Tuesday, etc``. Setting ``same=true`` allows the current + ``dt`` to be considered as the previous ``dow``, allowing for no adjustment to occur. + + :: + toprev(func::Function,dt::TimeType;step=Day(-1),negate=false,limit=10000,same=false) -> TimeType + Adjusts ``dt`` by iterating at most ``limit`` iterations by ``step`` increments until ``func`` returns true. ``func`` must take a single ``TimeType`` argument and return a ``Bool``. ``same`` allows ``dt`` to be considered in satisfying ``func``. ``negate`` will make the adjustment @@ -335,11 +930,25 @@ Adjuster Functions 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 + + Return the field part of a Date or DateTime as a ``Period`` type. + + :: + Year(v) Month(v) Week(v) Day(v) @@ -394,7 +1003,6 @@ Conversion Functions Returns the number of Rata Die days since epoch from the given Date or DateTime. - Constants ~~~~~~~~~ diff --git a/doc/stdlib/file.rst b/doc/stdlib/file.rst index f53e41b6e3162..23424e96db4f9 100644 --- a/doc/stdlib/file.rst +++ b/doc/stdlib/file.rst @@ -13,8 +13,21 @@ Set the current working directory. + :: + cd(f, [dir]) + + Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. + .. function:: cd(f, [dir]) + :: + cd(dir::AbstractString) + + Set the current working directory. + + :: + cd(f, [dir]) + Temporarily changes the current working directory (HOME if not specified) and applies function f before returning. .. function:: readdir([dir]) -> Vector{ByteString} @@ -112,7 +125,7 @@ .. 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`. + "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 @@ -129,7 +142,7 @@ .. 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`. + "remove_destination=true" will first remove an existing `dst`. .. function:: rm(path::AbstractString; recursive=false) @@ -289,3 +302,4 @@ 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 abcc1816b95c7..8d3c12207148e 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -21,10 +21,80 @@ General I/O .. function:: open(file_name, [read, write, create, truncate, append]) -> IOStream + :: + open(command, mode::AbstractString="r", stdio=DevNull) + + Start running ``command`` asynchronously, and return a tuple + ``(stream,process)``. If ``mode`` is ``"r"``, then ``stream`` + reads from the process's standard output and ``stdio`` optionally + specifies the process's standard input stream. If ``mode`` is + ``"w"``, then ``stream`` writes to the process's standard input + and ``stdio`` optionally specifies the process's standard output + stream. + + :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` + on the resulting read or write stream, then closes the stream + and waits for the process to complete. Returns the value returned + by ``f``. + + :: + open(file_name, [read, write, create, truncate, append]) -> IOStream + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + :: + open(file_name, [mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: + + ==== ================================= + r read + r+ read, write + w write, create, truncate + w+ read, write, create, truncate + a write, create, append + a+ read, write, create, append + ==== ================================= + + :: + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + **Example**: ``open(readall, "file.txt")`` + .. function:: open(file_name, [mode]) -> IOStream + :: + open(command, mode::AbstractString="r", stdio=DevNull) + + Start running ``command`` asynchronously, and return a tuple + ``(stream,process)``. If ``mode`` is ``"r"``, then ``stream`` + reads from the process's standard output and ``stdio`` optionally + specifies the process's standard input stream. If ``mode`` is + ``"w"``, then ``stream`` writes to the process's standard input + and ``stdio`` optionally specifies the process's standard output + stream. + + :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` + on the resulting read or write stream, then closes the stream + and waits for the process to complete. Returns the value returned + by ``f``. + + :: + open(file_name, [read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + open(file_name, [mode]) -> IOStream + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: ==== ================================= @@ -36,9 +106,56 @@ General I/O a+ read, write, create, append ==== ================================= + :: + open(f::function, args...) + + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. + + **Example**: ``open(readall, "file.txt")`` .. function:: open(f::function, args...) + :: + open(command, mode::AbstractString="r", stdio=DevNull) + + Start running ``command`` asynchronously, and return a tuple + ``(stream,process)``. If ``mode`` is ``"r"``, then ``stream`` + reads from the process's standard output and ``stdio`` optionally + specifies the process's standard input stream. If ``mode`` is + ``"w"``, then ``stream`` writes to the process's standard input + and ``stdio`` optionally specifies the process's standard output + stream. + + :: + open(f::Function, command, mode::AbstractString="r", stdio=DevNull) + + Similar to ``open(command, mode, stdio)``, but calls ``f(stream)`` + on the resulting read or write stream, then closes the stream + and waits for the process to complete. Returns the value returned + by ``f``. + + :: + open(file_name, [read, write, create, truncate, append]) -> IOStream + + Open a file in a mode specified by five boolean arguments. The default is to open files for reading only. Returns a stream for accessing the file. + + :: + open(file_name, [mode]) -> IOStream + + Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of ``mode`` correspond to those from ``fopen(3)`` or Perl ``open``, and are equivalent to setting the following boolean groups: + + ==== ================================= + r read + r+ read, write + w write, create, truncate + w+ read, write, create, truncate + a write, create, append + a+ read, write, create, append + ==== ================================= + + :: + open(f::function, args...) + Apply the function ``f`` to the result of ``open(args...)`` and close the resulting file descriptor upon completion. **Example**: ``open(readall, "file.txt")`` @@ -47,16 +164,91 @@ General I/O Create an in-memory I/O stream. + :: + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + IOBuffer([data,],[readable,writable,[maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, + they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable + but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer(size::Int) + :: + IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + IOBuffer(size::Int) + Create a fixed size IOBuffer. The buffer will not grow dynamically. + :: + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + IOBuffer([data,],[readable,writable,[maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, + they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable + but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer(string) + :: + IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + IOBuffer(string) + Create a read-only IOBuffer on the data underlying the given string + :: + IOBuffer([data,],[readable,writable,[maxsize]]) + + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, + they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable + but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. + .. function:: IOBuffer([data,],[readable,writable,[maxsize]]) + :: + IOBuffer() -> IOBuffer + + Create an in-memory I/O stream. + + :: + IOBuffer(size::Int) + + Create a fixed size IOBuffer. The buffer will not grow dynamically. + + :: + IOBuffer(string) + + Create a read-only IOBuffer on the data underlying the given string + + :: + IOBuffer([data,],[readable,writable,[maxsize]]) + Create an IOBuffer, which may optionally operate on a pre-existing array. If the readable/writable arguments are given, they restrict whether or not the buffer may be read from or written to respectively. By default the buffer is readable but not writable. The last argument optionally specifies a size beyond which the buffer may not be grown. @@ -81,6 +273,15 @@ General I/O Close an I/O stream. Performs a ``flush`` first. + :: + close(Channel) + + Closes a channel. An exception is thrown by: + + * ``put!`` on a on a closed channel. + + * ``take!`` and ``fetch`` on an empty, closed channel. + .. function:: write(stream, x) Write the canonical binary representation of a value to the given stream. @@ -89,8 +290,21 @@ General I/O Read a value of the given type from a stream, in canonical binary representation. + :: + read(stream, type, dims) + + Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. + .. function:: read(stream, type, dims) + :: + read(stream, type) + + Read a value of the given type from a stream, in canonical binary representation. + + :: + read(stream, type, dims) + Read a series of values of the given type from a stream, in canonical binary representation. ``dims`` is either a tuple or a series of integer arguments specifying the size of ``Array`` to return. .. function:: read!(stream, array::Array) @@ -223,8 +437,25 @@ General I/O wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be replaced elsewhere. + :: + redirect_stdout(stream) + + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that `stream` must be a TTY, a Pipe or a + TcpSocket. + .. function:: redirect_stdout(stream) + :: + redirect_stdout() + + Create a pipe to which all C and Julia level STDOUT output will be redirected. Returns a tuple (rd,wr) + representing the pipe ends. Data written to STDOUT may now be read from the rd end of the pipe. The + wr end is given for convenience in case the old STDOUT object was cached by the user and needs to be + replaced elsewhere. + + :: + redirect_stdout(stream) + Replace STDOUT by stream for all C and julia level output to STDOUT. Note that `stream` must be a TTY, a Pipe or a TcpSocket. @@ -259,15 +490,27 @@ General I/O An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. + :: + PipeBuffer(data::Vector{UInt8},[maxsize]) + + Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. + .. function:: PipeBuffer(data::Vector{UInt8},[maxsize]) + :: + PipeBuffer() + + An IOBuffer that allows reading and performs writes by appending. Seeking and truncating are not supported. See IOBuffer for the available constructors. + + :: + PipeBuffer(data::Vector{UInt8},[maxsize]) + Create a PipeBuffer to operate on a data vector, optionally specifying a size beyond which the underlying Array may not be grown. .. function:: 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 -------- @@ -345,8 +588,22 @@ Text I/O Read the entire contents of an I/O stream as a string. + :: + readall(filename::AbstractString) + + Open ``filename``, read the entire contents as a string, then close the file. + Equivalent to ``open(readall, filename)``. + .. function:: readall(filename::AbstractString) + :: + readall(stream::IO) + + Read the entire contents of an I/O stream as a string. + + :: + readall(filename::AbstractString) + Open ``filename``, read the entire contents as a string, then close the file. Equivalent to ``open(readall, filename)``. @@ -388,24 +645,279 @@ Text I/O 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='#') + + Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + + If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + + Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. + + If ``skipblanks`` is ``true``, blank lines in the input will be ignored. + + If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + + If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. + + :: + readdlm(source, delim::Char, eol::Char; options...) + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + :: + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as ``\n``. + + :: + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + + :: + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, 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='#') + + Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + + If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + + Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. + + If ``skipblanks`` is ``true``, blank lines in the input will be ignored. + + If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + + If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. + + :: + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, delim::Char, T::Type; options...) + The end of line delimiter is taken as ``\n``. + :: + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + + :: + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, 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='#') + + Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + + If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + + Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. + + If ``skipblanks`` is ``true``, blank lines in the input will be ignored. + + If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + + If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. + + :: + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as ``\n``. + + :: + readdlm(source, delim::Char; options...) + The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + :: + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + + :: + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source, 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='#') + + Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + + If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + + Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. + + If ``skipblanks`` is ``true``, blank lines in the input will be ignored. + + If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + + If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. + + :: + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as ``\n``. + + :: + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, T::Type; options...) + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + :: + readdlm(source; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + .. function:: readdlm(source; options...) + :: + readdlm(source, delim::Char, T::Type, eol::Char; header=false, skipstart=0, skipblanks=true, use_mmap, ignore_invalid_chars=false, quotes=true, dims, comments=true, comment_char='#') + + Read a matrix from the source where each line (separated by ``eol``) gives one row, with elements separated by the given delimeter. The source can be a text file, stream or byte array. Memory mapped files can be used by passing the byte array representation of the mapped segment as source. + + If ``T`` is a numeric type, the result is an array of that type, with any non-numeric elements as ``NaN`` for floating-point types, or zero. Other useful values of ``T`` include ``ASCIIString``, ``AbstractString``, and ``Any``. + + If ``header`` is ``true``, the first row of data will be read as header and the tuple ``(data_cells, header_cells)`` is returned instead of only ``data_cells``. + + Specifying ``skipstart`` will ignore the corresponding number of initial lines from the input. + + If ``skipblanks`` is ``true``, blank lines in the input will be ignored. + + If ``use_mmap`` is ``true``, the file specified by ``source`` is memory mapped for potential speedups. Default is ``true`` except on Windows. On Windows, you may want to specify ``true`` if the file is large, and is only read once and not written to. + + If ``ignore_invalid_chars`` is ``true``, bytes in ``source`` with invalid character encoding will be ignored. Otherwise an error is thrown indicating the offending character position. + + If ``quotes`` is ``true``, column enclosed within double-quote (``) characters are allowed to contain new lines and column delimiters. Double-quote characters within a quoted field must be escaped with another double-quote. + + Specifying ``dims`` as a tuple of the expected rows and columns (including header, if any) may speed up reading of large files. + + If ``comments`` is ``true``, lines beginning with ``comment_char`` and text following ``comment_char`` in any line are ignored. + + :: + readdlm(source, delim::Char, eol::Char; options...) + + If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, delim::Char, T::Type; options...) + + The end of line delimiter is taken as ``\n``. + + :: + readdlm(source, delim::Char; options...) + + The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. + + :: + readdlm(source, T::Type; options...) + + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. + + :: + readdlm(source; options...) + The columns are assumed to be separated by one or more whitespaces. The end of line delimiter is taken as ``\n``. If all data is numeric, the result will be a numeric array. If some elements cannot be parsed as numbers, a cell array of numbers and strings is returned. .. function:: writedlm(f, A, delim='\\t') @@ -437,6 +949,8 @@ Text I/O read from ``istream``. .. function:: base64encode(writefunc, args...) + + :: base64encode(args...) Given a ``write``-like function ``writefunc``, which takes an I/O @@ -474,6 +988,8 @@ displays may be enabled by loading external modules or by using graphical Julia environments (such as the IPython-based IJulia notebook). .. function:: display(x) + + :: display(d::Display, x) display(mime, x) display(d::Display, mime, x) @@ -494,6 +1010,8 @@ Julia environments (such as the IPython-based IJulia notebook). (for binary MIME types). .. function:: redisplay(x) + + :: redisplay(d::Display, x) redisplay(mime, x) redisplay(d::Display, mime, x) @@ -506,6 +1024,8 @@ Julia environments (such as the IPython-based IJulia notebook). prompt. .. function:: displayable(mime) -> Bool + + :: displayable(d::Display, mime) -> Bool Returns a boolean value indicating whether the given ``mime`` type (string) @@ -601,6 +1121,7 @@ stack with: topmost backend that does not throw a ``MethodError``). .. function:: popdisplay() + popdisplay(d::Display) Pop the topmost backend off of the display-backend stack, or the @@ -625,6 +1146,8 @@ Memory-mapped I/O 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) + + :: 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. @@ -666,8 +1189,63 @@ 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. + + **Example**: ``B = Mmap.mmap(s, BitArray, (25,30000))`` + + This would create a 25-by-30000 ``BitArray``, linked to the file associated with stream ``s``. + .. function:: Mmap.mmap(io, BitArray, [dims, offset]) + :: + 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. + + The type is an ``Array{T,N}`` with a bits-type element of ``T`` and dimension ``N`` that determines how the bytes of the array are interpreted. Note that the file must be stored in binary format, and no format conversions are possible (this is a limitation of operating systems, not Julia). + + ``dims`` is a tuple or single ``Integer`` specifying the size or length of the array. + + The file is passed via the stream argument, either as an open ``IOStream`` or filename string. When you initialize the stream, use ``"r"`` for a "read-only" array, and ``"w+"`` to create a new array used to write values to disk. + + If no ``type`` argument is specified, the default is ``Vector{UInt8}``. + + Optionally, you can specify an offset (in bytes) if, for example, you want to skip over a header in the file. The default value for the offset is the current stream position for an ``IOStream``. + + The ``grow`` keyword argument specifies whether the disk file should be grown to accomodate the requested size of array (if the total file size is < requested array size). Write privileges are required to grow the file. + + The ``shared`` keyword argument specifies whether the resulting ``Array`` and changes made to it will be visible to other processes mapping the same file. + + For example, the following code:: + + # Create a file for mmapping + # (you could alternatively use mmap to do this step, too) + A = rand(1:20, 5, 30) + s = open("/tmp/mmap.bin", "w+") + # We'll write the dimensions of the array as the first two Ints in the file + write(s, size(A,1)) + write(s, size(A,2)) + # Now write the data + write(s, A) + close(s) + + # Test by reading it back in + s = open("/tmp/mmap.bin") # default is read-only + m = read(s, Int) + n = read(s, Int) + A2 = Mmap.mmap(s, Matrix{Int}, (m,n)) + + creates a ``m``-by-``n`` ``Matrix{Int}``, linked to the file associated with stream ``s``. + + A more portable file would need to encode the word size---32 bit or 64 bit---and endianness information in the header. In practice, consider encoding binary data using standard formats like HDF5 (which can be used with memory-mapping). + + :: + Mmap.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. **Example**: ``B = Mmap.mmap(s, BitArray, (25,30000))`` @@ -685,17 +1263,62 @@ Network I/O Connect to the host ``host`` on port ``port`` + :: + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at ``path`` + + :: + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, + specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read + off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation + must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` + sets up TCP/IP socket connections in-between workers. + .. function:: connect(path) -> Pipe + :: + connect([host],port) -> TcpSocket + + Connect to the host ``host`` on port ``port`` + + :: + connect(path) -> Pipe + Connect to the Named Pipe/Domain Socket at ``path`` + :: + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, + specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read + off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation + must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` + sets up TCP/IP socket connections in-between workers. + .. function:: listen([addr,]port) -> TcpServer Listen on port on the address specified by ``addr``. By default this listens on localhost only. To listen on all interfaces pass, ``IPv4(0)`` or ``IPv6(0)`` as appropriate. + :: + listen(path) -> PipeServer + + Listens on/Creates a Named Pipe/Domain Socket + .. function:: listen(path) -> PipeServer + :: + listen([addr,]port) -> TcpServer + + Listen on port on the address specified by ``addr``. By default this listens on localhost only. + To listen on all interfaces pass, ``IPv4(0)`` or ``IPv6(0)`` as appropriate. + + :: + listen(path) -> PipeServer + Listens on/Creates a Named Pipe/Domain Socket .. function:: getaddrinfo(host) diff --git a/doc/stdlib/libc.rst b/doc/stdlib/libc.rst index 959be71ab3e35..11f28895c713d 100644 --- a/doc/stdlib/libc.rst +++ b/doc/stdlib/libc.rst @@ -48,7 +48,10 @@ .. function:: time(t::TmStruct) - Converts a ``TmStruct`` struct to a number of seconds since the epoch. + :: + time() + + Get the system time in seconds since the epoch, with fairly high (typically, microsecond) resolution. .. function:: strftime([format], time) diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index ac42f9dddf848..e332f74009cf9 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -14,10 +14,24 @@ Standard Functions Linear algebra functions in Julia are largely implemented by calling functions from `LAPACK `_. Sparse factorizations call functions from `SuiteSparse `_. .. function:: *(A, B) + :noindex: Matrix multiplication + :: + *(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. + + .. doctest:: + .. function:: \\(A, B) :noindex: @@ -26,6 +40,8 @@ Linear algebra functions in Julia are largely implemented by calling functions f When ``A`` is sparse, a similar polyalgorithm is used. For indefinite matrices, the LDLt factorization does not use pivoting during the numerical factorization and therefore the procedure can fail even for invertible matrices. .. function:: dot(x, y) + + :: ⋅(x,y) Compute the dot product. For complex vectors, the first vector is conjugated. @@ -38,6 +54,8 @@ Linear algebra functions in Julia are largely implemented by calling functions f ``dot(x[i],y[i])``) as if they were vectors. .. function:: cross(x, y) + + :: ×(x,y) Compute the cross product of two 3-vectors. @@ -48,8 +66,28 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: full(F) + :: + full(S) + + Convert a sparse matrix ``S`` into a dense matrix. + + :: + full(F) + Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. + :: + full(QRCompactWYQ[, thin=true]) -> Matrix + + Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` + object, i.e. in the compact WY format [Bischof1987]_, to a dense matrix. + + Optionally takes a ``thin`` Boolean argument, which if ``true`` omits the + columns that span the rows of ``R`` in the QR factorization that are zero. + The resulting matrix is the ``Q`` in a thin QR factorization (sometimes + called the reduced QR factorization). If ``false``, returns a ``Q`` that + spans all rows of ``R`` in its corresponding QR factorization. + .. function:: lu(A) -> L, U, p Compute the LU factorization of ``A``, such that ``A[p,:] = L*U``. @@ -104,8 +142,40 @@ Linear algebra functions in Julia are largely implemented by calling functions f Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix ``A`` and return either a ``Cholesky`` if ``pivot==Val{false}`` or ``CholeskyPivoted`` if ``pivot==Val{true}``. ``LU`` may be ``:L`` for using the lower part or ``:U`` for the upper part. The default is to use ``:U``. The triangular matrix can be obtained from the factorization ``F`` with: ``F[:L]`` and ``F[:U]``. The following functions are available for ``Cholesky`` objects: ``size``, ``\``, ``inv``, ``det``. For ``CholeskyPivoted`` there is also defined a ``rank``. If ``pivot==Val{false}`` a ``PosDefException`` exception is thrown in case the matrix is not positive definite. The argument ``tol`` determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. + :: + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the Cholesky factorization of a sparse positive definite + matrix ``A``. A fill-reducing permutation is used. ``F = + cholfact(A)`` is most frequently used to solve systems of equations + with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` + are defined for ``F``. You can also extract individual factors + from ``F``, using ``F[:L]``. However, since pivoting is on by + default, the factorization is internally represented as ``A == + P'*L*L'*P`` with a permutation matrix ``P``; using just ``L`` + without accounting for ``P`` will give incorrect answers. To + include the effects of permutation, it's typically preferable to + extact "combined" factors like ``PtL = F[:PtL]`` (the equivalent of + ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). + + Setting optional ``shift`` keyword argument computes the factorization + of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, + it should be a permutation of `1:size(A,1)` giving the ordering to use + (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. + .. function:: cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + :: + cholfact(A, [LU=:U[,pivot=Val{false}]][;tol=-1.0]) -> Cholesky + + Compute the Cholesky factorization of a dense symmetric positive (semi)definite matrix ``A`` and return either a ``Cholesky`` if ``pivot==Val{false}`` or ``CholeskyPivoted`` if ``pivot==Val{true}``. ``LU`` may be ``:L`` for using the lower part or ``:U`` for the upper part. The default is to use ``:U``. The triangular matrix can be obtained from the factorization ``F`` with: ``F[:L]`` and ``F[:U]``. The following functions are available for ``Cholesky`` objects: ``size``, ``\``, ``inv``, ``det``. For ``CholeskyPivoted`` there is also defined a ``rank``. If ``pivot==Val{false}`` a ``PosDefException`` exception is thrown in case the matrix is not positive definite. The argument ``tol`` determines the tolerance for determining the rank. For negative values, the tolerance is the machine precision. + + :: + cholfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + Compute the Cholesky factorization of a sparse positive definite matrix ``A``. A fill-reducing permutation is used. ``F = cholfact(A)`` is most frequently used to solve systems of equations @@ -135,8 +205,42 @@ Linear algebra functions in Julia are largely implemented by calling functions f Compute a factorization of a positive definite matrix ``A`` such that ``A=L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector with non-negative elements. + :: + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + + Compute the LDLt factorization of a sparse symmetric or Hermitian + matrix ``A``. A fill-reducing permutation is used. ``F = + ldltfact(A)`` is most frequently used to solve systems of equations + with ``F\b``, but also the methods ``diag``, ``det``, ``logdet`` + are defined for ``F``. You can also extract individual factors from + ``F``, using ``F[:L]``. However, since pivoting is on by default, + the factorization is internally represented as ``A == P'*L*D*L'*P`` + with a permutation matrix ``P``; using just ``L`` without + accounting for ``P`` will give incorrect answers. To include the + effects of permutation, it's typically preferable to extact + "combined" factors like ``PtL = F[:PtL]`` (the equivalent of + ``P'*L``) and ``LtP = F[:UP]`` (the equivalent of ``L'*P``). The + complete list of supported factors is ``:L, :PtL, :D, :UP, :U, :LD, + :DU, :PtLD, :DUP``. + + Setting optional ``shift`` keyword argument computes the factorization + of ``A+shift*I`` instead of ``A``. If the ``perm`` argument is nonempty, + it should be a permutation of `1:size(A,1)` giving the ordering to use + (instead of CHOLMOD's default AMD ordering). + + The function calls the C library CHOLMOD and many other functions + from the library are wrapped but not exported. + .. function:: ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + :: + ldltfact(A) -> LDLtFactorization + + Compute a factorization of a positive definite matrix ``A`` such that ``A=L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector with non-negative elements. + + :: + ldltfact(A; shift=0, perm=Int[]) -> CHOLMOD.Factor + Compute the LDLt factorization of a sparse symmetric or Hermitian matrix ``A``. A fill-reducing permutation is used. ``F = ldltfact(A)`` is most frequently used to solve systems of equations @@ -216,8 +320,69 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. [Bischof1987] C Bischof and C Van Loan, The WY representation for products of Householder matrices, SIAM J Sci Stat Comput 8 (1987), s2-s13. doi:10.1137/0908009 .. [Schreiber1989] R Schreiber and C Van Loan, A storage-efficient WY representation for products of Householder transformations, SIAM J Sci Stat Comput 10 (1989), 53-57. doi:10.1137/0910005 + :: + qrfact(A) -> SPQR.Factorization + + Compute the QR factorization of a sparse matrix ``A``. A fill-reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. + .. function:: qrfact(A) -> SPQR.Factorization + :: + qrfact(A [,pivot=Val{false}]) -> F + + Computes the QR factorization of ``A``. The return type of ``F`` depends on the element type of ``A`` and whether pivoting is specified (with ``pivot==Val{true}``). + + ================ ================= ============== ===================================== + Return type ``eltype(A)`` ``pivot`` Relationship between ``F`` and ``A`` + ---------------- ----------------- -------------- ------------------------------------- + ``QR`` not ``BlasFloat`` either ``A==F[:Q]*F[:R]`` + ``QRCompactWY`` ``BlasFloat`` ``Val{false}`` ``A==F[:Q]*F[:R]`` + ``QRPivoted`` ``BlasFloat`` ``Val{true}`` ``A[:,F[:p]]==F[:Q]*F[:R]`` + ================ ================= ============== ===================================== + + ``BlasFloat`` refers to any of: ``Float32``, ``Float64``, ``Complex64`` or ``Complex128``. + + The individual components of the factorization ``F`` can be accessed by indexing: + + =========== ============================================= ================== ===================== ================== + Component Description ``QR`` ``QRCompactWY`` ``QRPivoted`` + ----------- --------------------------------------------- ------------------ --------------------- ------------------ + ``F[:Q]`` ``Q`` (orthogonal/unitary) part of ``QR`` ✓ (``QRPackedQ``) ✓ (``QRCompactWYQ``) ✓ (``QRPackedQ``) + ``F[:R]`` ``R`` (upper right triangular) part of ``QR`` ✓ ✓ ✓ + ``F[:p]`` pivot ``Vector`` ✓ + ``F[:P]`` (pivot) permutation ``Matrix`` ✓ + =========== ============================================= ================== ===================== ================== + + The following functions are available for the ``QR`` objects: ``size``, ``\``. When ``A`` is rectangular, ``\`` will return a least squares solution and if the solution is not unique, the one with smallest norm is returned. + + Multiplication with respect to either thin or full ``Q`` is allowed, i.e. both ``F[:Q]*F[:R]`` and ``F[:Q]*A`` are supported. A ``Q`` matrix can be converted into a regular matrix with :func:`full` which has a named argument ``thin``. + + .. note:: + + ``qrfact`` returns multiple types because LAPACK uses several representations that minimize the memory storage requirements of products of Householder elementary reflectors, so that the ``Q`` and ``R`` matrices can be stored compactly rather as two separate dense matrices. + + The data contained in ``QR`` or ``QRPivoted`` can be used to construct the ``QRPackedQ`` type, which is a compact representation of the rotation matrix: + + .. math:: + + Q = \prod_{i=1}^{\min(m,n)} (I - \tau_i v_i v_i^T) + + where :math:`\tau_i` is the scale factor and :math:`v_i` is the projection vector associated with the :math:`i^{th}` Householder elementary reflector. + + The data contained in ``QRCompactWY`` can be used to construct the ``QRCompactWYQ`` type, which is a compact representation of the rotation matrix + + .. math:: + + Q = I + Y T Y^T + + where ``Y`` is :math:`m \times r` lower trapezoidal and ``T`` is :math:`r \times r` upper triangular. The *compact WY* representation [Schreiber1989]_ is not to be confused with the older, *WY* representation [Bischof1987]_. (The LAPACK documentation uses ``V`` in lieu of ``Y``.) + + .. [Bischof1987] C Bischof and C Van Loan, The WY representation for products of Householder matrices, SIAM J Sci Stat Comput 8 (1987), s2-s13. doi:10.1137/0908009 + .. [Schreiber1989] R Schreiber and C Van Loan, A storage-efficient WY representation for products of Householder transformations, SIAM J Sci Stat Comput 10 (1989), 53-57. doi:10.1137/0910005 + + :: + qrfact(A) -> SPQR.Factorization + Compute the QR factorization of a sparse matrix ``A``. A fill-reducing permutation is used. The main application of this type is to solve least squares problems with ``\``. The function calls the C library SPQR and a few additional functions from the library are wrapped but not exported. .. function:: qrfact!(A [,pivot=Val{false}]) @@ -226,6 +391,19 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. function:: full(QRCompactWYQ[, thin=true]) -> Matrix + :: + full(S) + + Convert a sparse matrix ``S`` into a dense matrix. + + :: + full(F) + + Reconstruct the matrix ``A`` from the factorization ``F=factorize(A)``. + + :: + full(QRCompactWYQ[, thin=true]) -> Matrix + Converts an orthogonal or unitary matrix stored as a ``QRCompactWYQ`` object, i.e. in the compact WY format [Bischof1987]_, to a dense matrix. @@ -263,8 +441,39 @@ Linear algebra functions in Julia are largely implemented by calling functions f factorization to a tuple; where possible, using :func:`eigfact` is recommended. + :: + eig(A, B) -> D, V + + Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. + + ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the + factorization to a tuple; where possible, using :func:`eigfact` is + recommended. + .. function:: eig(A, B) -> D, V + :: + eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V + + Computes eigenvalues and eigenvectors of ``A``. See :func:`eigfact` for + details on the ``balance`` keyword argument. + + .. doctest:: + + julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0]) + ([1.0,3.0,18.0], + 3x3 Array{Float64,2}: + 1.0 0.0 0.0 + 0.0 1.0 0.0 + 0.0 0.0 1.0) + + ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the + factorization to a tuple; where possible, using :func:`eigfact` is + recommended. + + :: + eig(A, B) -> D, V + Computes generalized eigenvalues and vectors of ``A`` with respect to ``B``. ``eig`` is a wrapper around :func:`eigfact`, extracting all parts of the @@ -324,8 +533,44 @@ Linear algebra functions in Julia are largely implemented by calling functions f scales the matrix by its diagonal elements to make rows and columns more equal in norm. The default is ``true`` for both options. + :: + eigfact(A, B) -> GeneralizedEigen + + Computes the generalized eigenvalue decomposition of ``A`` and ``B``, + returning a ``GeneralizedEigen`` factorization object ``F`` which contains + the generalized eigenvalues in ``F[:values]`` and the generalized + eigenvectors in the columns of the matrix ``F[:vectors]``. (The ``k``\ th + generalized eigenvector can be obtained from the slice ``F[:vectors][:, + k]``.) + .. function:: eigfact(A, B) -> GeneralizedEigen + :: + eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen + + Computes the eigenvalue decomposition of ``A``, returning an ``Eigen`` + factorization object ``F`` which contains the eigenvalues in ``F[:values]`` + and the eigenvectors in the columns of the matrix ``F[:vectors]``. + (The ``k``\ th eigenvector can be obtained from the slice ``F[:vectors][:, k]``.) + + The following functions are available for ``Eigen`` objects: ``inv``, + ``det``. + + If ``A`` is :class:`Symmetric`, :class:`Hermitian` or :class:`SymTridiagonal`, + it is possible to calculate only a subset of the eigenvalues by specifying + either a :class:`UnitRange` ``irange`` covering indices of the sorted + eigenvalues or a pair ``vl`` and ``vu`` for the lower and upper boundaries + of the eigenvalues. + + For general nonsymmetric matrices it is possible to specify how the matrix + is balanced before the eigenvector calculation. The option ``permute=true`` + permutes the matrix to become closer to upper triangular, and ``scale=true`` + scales the matrix by its diagonal elements to make rows and columns more + equal in norm. The default is ``true`` for both options. + + :: + eigfact(A, B) -> GeneralizedEigen + Computes the generalized eigenvalue decomposition of ``A`` and ``B``, returning a ``GeneralizedEigen`` factorization object ``F`` which contains the generalized eigenvalues in ``F[:values]`` and the generalized @@ -350,6 +595,11 @@ Linear algebra functions in Julia are largely implemented by calling functions f Computes the Schur factorization of the matrix ``A``. The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``. The eigenvalues of ``A`` can be obtained with ``F[:values]``. + :: + schurfact(A, B) -> GeneralizedSchur + + Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``, the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``. The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``. + .. function:: schurfact!(A) Computes the Schur factorization of ``A``, overwriting ``A`` in the process. See :func:`schurfact` @@ -358,50 +608,214 @@ Linear algebra functions in Julia are largely implemented by calling functions f See :func:`schurfact` + :: + schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + + See :func:`schurfact` + .. function:: ordschur(Q, T, select) -> Schur Reorders the Schur factorization of a real matrix ``A=Q*T*Q'`` according to the logical array ``select`` returning a Schur object ``F``. The selected eigenvalues appear in the leading diagonal of ``F[:Schur]`` and the the corresponding leading columns of ``F[:vectors]`` form an orthonormal basis of the corresponding right invariant subspace. A complex conjugate pair of eigenvalues must be either both included or excluded via ``select``. + :: + ordschur(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 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 + :: + 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 + :: + 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 + + Computes the Schur factorization of the matrix ``A``. The (quasi) triangular Schur factor can be obtained from the ``Schur`` object ``F`` with either ``F[:Schur]`` or ``F[:T]`` and the unitary/orthogonal Schur vectors can be obtained with ``F[:vectors]`` or ``F[:Z]`` such that ``A=F[:vectors]*F[:Schur]*F[:vectors]'``. The eigenvalues of ``A`` can be obtained with ``F[:values]``. + + :: + schurfact(A, B) -> GeneralizedSchur + Computes the Generalized Schur (or QZ) factorization of the matrices ``A`` and ``B``. The (quasi) triangular Schur factors can be obtained from the ``Schur`` object ``F`` with ``F[:S]`` and ``F[:T]``, the left unitary/orthogonal Schur vectors can be obtained with ``F[:left]`` or ``F[:Q]`` and the right unitary/orthogonal Schur vectors can be obtained with ``F[:right]`` or ``F[:Z]`` such that ``A=F[:left]*F[:S]*F[:right]'`` and ``B=F[:left]*F[:T]*F[:right]'``. The generalized eigenvalues of ``A`` and ``B`` can be obtained with ``F[:alpha]./F[:beta]``. .. function:: schur(A,B) -> GeneralizedSchur[:S], GeneralizedSchur[:T], GeneralizedSchur[:Q], GeneralizedSchur[:Z] + :: + 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 + :: + 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 + :: + 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 + :: + 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 + :: + 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. + :: + svdfact(A, B) -> GeneralizedSVD + + Compute the generalized SVD of ``A`` and ``B``, returning a ``GeneralizedSVD`` Factorization object ``F``, such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``. + .. function:: 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. @@ -410,56 +824,142 @@ Linear algebra functions in Julia are largely implemented by calling functions f Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. Computes the SVD of A, returning ``U``, vector ``S``, and ``V`` such that ``A == U*diagm(S)*V'``. If ``thin`` is ``true``, an economy mode decomposition is returned. The default is to produce a thin decomposition. + :: + svd(A, B) -> U, V, Q, D1, D2, R0 + + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``, returning ``U``, ``V``, ``Q``, ``D1``, ``D2``, and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. + .. function:: svdvals(A) Returns the singular values of ``A``. + :: + svdvals(A, B) + + Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. + .. function:: svdvals!(A) Returns the singular values of ``A``, while saving space by overwriting the input. .. function:: svdfact(A, B) -> GeneralizedSVD + :: + svdfact(A, [thin=true]) -> SVD + + Compute the Singular Value Decomposition (SVD) of ``A`` and return an ``SVD`` object. ``U``, ``S``, ``V`` and ``Vt`` can be obtained from the factorization ``F`` with ``F[:U]``, ``F[:S]``, ``F[:V]`` and ``F[:Vt]``, such that ``A = U*diagm(S)*Vt``. If ``thin`` is ``true``, an economy mode decomposition is returned. The algorithm produces ``Vt`` and hence ``Vt`` is more efficient to extract than ``V``. The default is to produce a thin decomposition. + + :: + svdfact(A, B) -> GeneralizedSVD + Compute the generalized SVD of ``A`` and ``B``, returning a ``GeneralizedSVD`` Factorization object ``F``, such that ``A = F[:U]*F[:D1]*F[:R0]*F[:Q]'`` and ``B = F[:V]*F[:D2]*F[:R0]*F[:Q]'``. .. function:: svd(A, B) -> U, V, Q, D1, D2, R0 + :: + svd(A, [thin=true]) -> U, S, V + + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. Computes the SVD of A, returning ``U``, vector ``S``, and ``V`` such that ``A == U*diagm(S)*V'``. If ``thin`` is ``true``, an economy mode decomposition is returned. The default is to produce a thin decomposition. + + :: + svd(A, B) -> U, V, Q, D1, D2, R0 + Wrapper around ``svdfact`` extracting all parts the factorization to a tuple. Direct use of ``svdfact`` is therefore generally more efficient. The function returns the generalized SVD of ``A`` and ``B``, returning ``U``, ``V``, ``Q``, ``D1``, ``D2``, and ``R0`` such that ``A = U*D1*R0*Q'`` and ``B = V*D2*R0*Q'``. .. function:: svdvals(A, B) + :: + svdvals(A) + + Returns the singular values of ``A``. + + :: + svdvals(A, B) + Return only the singular values from the generalized singular value decomposition of ``A`` and ``B``. .. function:: triu(M) Upper triangle of a matrix. + :: + triu(M, k) + + Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal. + .. function:: triu(M, k) + :: + triu(M) + + Upper triangle of a matrix. + + :: + triu(M, k) + Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal. .. function:: triu!(M) Upper triangle of a matrix, overwriting ``M`` in the process. + :: + triu!(M, k) + + Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. + .. function:: triu!(M, k) + :: + triu!(M) + + Upper triangle of a matrix, overwriting ``M`` in the process. + + :: + triu!(M, k) + Returns the upper triangle of ``M`` starting from the ``k``\ th superdiagonal, overwriting ``M`` in the process. .. function:: tril(M) Lower triangle of a matrix. + :: + tril(M, k) + + Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal. + .. function:: tril(M, k) + :: + tril(M) + + Lower triangle of a matrix. + + :: + tril(M, k) + Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal. .. function:: tril!(M) Lower triangle of a matrix, overwriting ``M`` in the process. + :: + tril!(M, k) + + Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal, overwriting ``M`` in the process. + .. function:: tril!(M, k) + :: + tril!(M) + + Lower triangle of a matrix, overwriting ``M`` in the process. + + :: + tril!(M, k) + Returns the lower triangle of ``M`` starting from the ``k``\ th subdiagonal, overwriting ``M`` in the process. .. function:: diagind(M[, k]) @@ -475,8 +975,28 @@ Linear algebra functions in Julia are largely implemented by calling functions f Construct a diagonal matrix and place ``v`` on the ``k``\ th diagonal. .. function:: scale(A, b) + + :: + scale(b, A) + + Scale an array ``A`` by a scalar ``b``, returning a new array. + + If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` + scales each column ``i`` of ``A`` by ``b[i]`` (similar to + ``A*diagm(b)``), while ``scale(b,A)`` scales each row ``i`` of + ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), returning a new array. + + Note: for large ``A``, ``scale`` can be much faster than ``A .* b`` or + ``b .* A``, due to the use of BLAS. + .. function:: scale(b, A) + :: + scale(A, b) + + :: + scale(b, A) + Scale an array ``A`` by a scalar ``b``, returning a new array. If ``A`` is a matrix and ``b`` is a vector, then ``scale(A,b)`` @@ -488,8 +1008,27 @@ Linear algebra functions in Julia are largely implemented by calling functions f ``b .* A``, due to the use of BLAS. .. function:: scale!(A, b) + + :: + scale!(b, A) + + Scale an array ``A`` by a scalar ``b``, similar to :func:`scale` but + overwriting ``A`` in-place. + + If ``A`` is a matrix and ``b`` is a vector, then ``scale!(A,b)`` + scales each column ``i`` of ``A`` by ``b[i]`` (similar to + ``A*diagm(b)``), while ``scale!(b,A)`` scales each row ``i`` of + ``A`` by ``b[i]`` (similar to ``diagm(b)*A``), again operating in-place + on ``A``. + .. function:: scale!(b, A) + :: + scale!(A, b) + + :: + scale!(b, A) + Scale an array ``A`` by a scalar ``b``, similar to :func:`scale` but overwriting ``A`` in-place. @@ -632,8 +1171,30 @@ Linear algebra functions in Julia are largely implemented by calling functions f plot(x, y, "o") # Plot (x,y) points plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + :: + linreg(x, y, w) + + Weighted least-squares linear regression. + .. function:: linreg(x, y, w) + :: + linreg(x, y) -> [a; b] + + Linear Regression. Returns ``a`` and ``b`` such that ``a+b*x`` is the closest line to the given points ``(x,y)``. In other words, this function determines parameters ``[a, b]`` that minimize the squared error between ``y`` and ``a+b*x``. + + **Example**:: + + using PyPlot; + x = float([1:12]) + y = [5.5; 6.3; 7.6; 8.8; 10.9; 11.79; 13.48; 15.02; 17.77; 20.81; 22.0; 22.99] + a, b = linreg(x,y) # Linear regression + plot(x, y, "o") # Plot (x,y) points + plot(x, [a+b*i for i in x]) # Plot the line determined by the linear regression + + :: + linreg(x, y, w) + Weighted least-squares linear regression. .. function:: expm(A) @@ -902,8 +1463,25 @@ Usually a function has 4 methods defined, one each for ``Float64``, order ``size(A,2)`` with ``k`` super-diagonals stored in the argument ``A``. + :: + sbmv(uplo, k, A, x) + + Returns ``A*x`` where ``A`` is a symmetric band matrix of + order ``size(A,2)`` with ``k`` super-diagonals stored in the + argument ``A``. + .. function:: sbmv(uplo, k, A, x) + :: + sbmv(uplo, k, alpha, A, x) + + Returns ``alpha*A*x`` where ``A`` is a symmetric band matrix of + order ``size(A,2)`` with ``k`` super-diagonals stored in the + argument ``A``. + + :: + sbmv(uplo, k, A, x) + Returns ``A*x`` where ``A`` is a symmetric band matrix of order ``size(A,2)`` with ``k`` super-diagonals stored in the argument ``A``. @@ -919,8 +1497,23 @@ Usually a function has 4 methods defined, one each for ``Float64``, Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. + :: + gemm(tA, tB, A, B) + + Returns ``A*B`` or the other three variants + according to ``tA`` (transpose ``A``) and ``tB``. + .. function:: gemm(tA, tB, A, B) + :: + gemm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants + according to ``tA`` (transpose ``A``) and ``tB``. + + :: + gemm(tA, tB, A, B) + Returns ``A*B`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. @@ -935,8 +1528,22 @@ Usually a function has 4 methods defined, one each for ``Float64``, Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` (transpose ``A``). + :: + gemv(tA, A, x) + + Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). + .. function:: gemv(tA, A, x) + :: + gemv(tA, alpha, A, x) + + Returns ``alpha*A*x`` or ``alpha*A'x`` according to ``tA`` + (transpose ``A``). + + :: + gemv(tA, A, x) + Returns ``A*x`` or ``A'x`` according to ``tA`` (transpose ``A``). .. function:: symm!(side, ul, alpha, A, B, beta, C) @@ -951,13 +1558,57 @@ Usually a function has 4 methods defined, one each for ``Float64``, ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. + :: + symm(side, ul, A, B) + + Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed + to be symmetric. Only the ``ul`` triangle of ``A`` is used. + + :: + symm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants + according to ``tA`` (transpose ``A``) and ``tB``. + .. function:: symm(side, ul, A, B) + :: + symm(side, ul, alpha, A, B) + + Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``. + ``A`` is assumed to be symmetric. Only the ``ul`` triangle of + ``A`` is used. + + :: + symm(side, ul, A, B) + Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. + :: + symm(tA, tB, alpha, A, B) + + Returns ``alpha*A*B`` or the other three variants + according to ``tA`` (transpose ``A``) and ``tB``. + .. function:: symm(tA, tB, alpha, A, B) + :: + symm(side, ul, alpha, A, B) + + Returns ``alpha*A*B`` or ``alpha*B*A`` according to ``side``. + ``A`` is assumed to be symmetric. Only the ``ul`` triangle of + ``A`` is used. + + :: + symm(side, ul, A, B) + + Returns ``A*B`` or ``B*A`` according to ``side``. ``A`` is assumed + to be symmetric. Only the ``ul`` triangle of ``A`` is used. + + :: + symm(tA, tB, alpha, A, B) + Returns ``alpha*A*B`` or the other three variants according to ``tA`` (transpose ``A``) and ``tB``. @@ -972,8 +1623,23 @@ Usually a function has 4 methods defined, one each for ``Float64``, Returns ``alpha*A*x``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. + :: + symv(ul, A, x) + + Returns ``A*x``. ``A`` is assumed to be symmetric. Only the + ``ul`` triangle of ``A`` is used. + .. function:: symv(ul, A, x) + :: + symv(ul, alpha, A, x) + + Returns ``alpha*A*x``. ``A`` is assumed to be symmetric. Only the + ``ul`` triangle of ``A`` is used. + + :: + symv(ul, A, x) + Returns ``A*x``. ``A`` is assumed to be symmetric. Only the ``ul`` triangle of ``A`` is used. diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index 7bb80d5a049cf..1f42489a76bae 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -13,6 +13,11 @@ Mathematical Operators Unary minus operator. + :: + -(x, y) + + Subtraction operator. + .. _+: .. function:: +(x, y...) @@ -22,14 +27,38 @@ Mathematical Operators .. _-: .. function:: -(x, y) + :: + -(x) + + Unary minus operator. + + :: + -(x, y) + Subtraction operator. .. _*: .. function:: *(x, y...) + :: + *(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. + + .. doctest:: + .. _/: .. function:: /(x, y) @@ -47,6 +76,16 @@ Mathematical Operators Exponentiation operator. + :: + ^(s, n) + + Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. + + .. doctest:: + + julia> "Test "^3 + "Test Test Test " + .. _.+: .. function:: .+(x, y) @@ -92,6 +131,8 @@ Mathematical Operators ``fma``. .. function:: div(x, y) + + :: ÷(x, y) The quotient from Euclidean division. Computes ``x/y``, truncated to an integer. @@ -119,6 +160,8 @@ Mathematical Operators floating-point number 2pi. .. function:: rem(x, y) + + :: %(x, y) Remainder from Euclidean division, returning a value of the same sign @@ -207,6 +250,8 @@ Mathematical Operators .. _!=: .. function:: !=(x, y) + + :: ≠(x,y) Not-equals comparison operator. Always gives the opposite answer as ``==``. @@ -215,12 +260,18 @@ Mathematical Operators .. _===: .. function:: ===(x, y) - ≡(x,y) - See the :func:`is` operator + :: + 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``. .. _!==: .. function:: !==(x, y) + + :: ≢(x,y) Equivalent to ``!is(x, y)`` @@ -236,6 +287,8 @@ Mathematical Operators .. _<=: .. function:: <=(x, y) + + :: ≤(x,y) Less-than-or-equals comparison operator. @@ -248,6 +301,8 @@ Mathematical Operators .. _>=: .. function:: >=(x, y) + + :: ≥(x,y) Greater-than-or-equals comparison operator. @@ -259,6 +314,8 @@ Mathematical Operators .. _.!=: .. function:: .!=(x, y) + + :: .≠(x,y) Element-wise not-equals comparison operator. @@ -270,6 +327,8 @@ Mathematical Operators .. _.<=: .. function:: .<=(x, y) + + :: .≤(x,y) Element-wise less-than-or-equals comparison operator. @@ -281,6 +340,8 @@ Mathematical Operators .. _.>=: .. function:: .>=(x, y) + + :: .≥(x,y) Element-wise greater-than-or-equals comparison operator. @@ -336,7 +397,6 @@ Mathematical Operators .. function:: A_mul_B!(Y, A, B) -> Y - Calculates the matrix-matrix or matrix-vector product *A B* and stores the result in *Y*, overwriting the existing value of *Y*. @@ -413,7 +473,6 @@ Mathematical Operators Matrix operator A\ :sup:`T` / B\ :sup:`T` - Mathematical Functions ---------------------- @@ -615,8 +674,26 @@ Mathematical Functions There is an experimental variant in the ``Base.Math.JuliaLibm`` module, which is typically faster and more accurate. + :: + log(b,x) + + Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. + .. function:: log(b,x) + :: + log(x) + + Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative + ``Real`` arguments. Use complex negative arguments to obtain complex + results. + + There is an experimental variant in the ``Base.Math.JuliaLibm`` module, + which is typically faster and more accurate. + + :: + log(b,x) + Compute the base ``b`` logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. .. function:: log2(x) @@ -694,6 +771,14 @@ Mathematical Functions .. doctest:: + :: + round(z, RoundingModeReal, RoundingModeImaginary) + + Returns the nearest integral value of the same type as the complex-valued + ``z`` to ``z``, breaking ties using the specified :obj:`RoundingMode`\ s. + The first :obj:`RoundingMode` is used for rounding the real components while + the second is used for rounding the imaginary components. + julia> round(pi, 2) 3.14 @@ -761,6 +846,40 @@ Mathematical Functions .. function:: round(z, RoundingModeReal, RoundingModeImaginary) + :: + round([T,] x, [digits, [base]], [r::RoundingMode]) + + ``round(x)`` rounds ``x`` to an integer value according to the default + rounding mode (see :func:`get_rounding`), returning a value of the same type as + ``x``. By default (:obj:`RoundNearest`), this will round to the nearest + integer, with ties (fractional values of 0.5) being rounded to the even + integer. + + .. doctest:: + + julia> round(1.7) + 2.0 + + julia> round(1.5) + 2.0 + + julia> round(2.5) + 2.0 + + The optional :obj:`RoundingMode` argument will change how the number gets rounded. + + ``round(T, x, [r::RoundingMode])`` converts the result to type ``T``, throwing an + :exc:`InexactError` if the value is not representable. + + ``round(x, digits)`` rounds to the specified number of digits after the + decimal place (or before if negative). ``round(x, digits, base)`` rounds + using a base other than 10. + + .. doctest:: + + :: + round(z, RoundingModeReal, RoundingModeImaginary) + Returns the nearest integral value of the same type as the complex-valued ``z`` to ``z``, breaking ties using the specified :obj:`RoundingMode`\ s. The first :obj:`RoundingMode` is used for rounding the real components while @@ -788,13 +907,11 @@ Mathematical Functions .. function:: trunc([T,] x, [digits, [base]]) - ``trunc(x)`` returns the nearest integral value of the same type as ``x`` whose absolute - value is less than or equal to ``x``. + :: + trunc(dt::TimeType, ::Type{Period}) -> TimeType - ``trunc(T, x)`` converts the result to type ``T``, throwing an - ``InexactError`` if the value is not representable. - - ``digits`` and ``base`` work as for :func:`round`. + 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:: unsafe_trunc(T, x) @@ -934,8 +1051,26 @@ Mathematical Functions precision. If ``n`` is not an ``Integer``, ``factorial(n)`` is equivalent to :func:`gamma(n+1) `. + :: + factorial(n,k) + + Compute ``factorial(n)/factorial(k)`` + .. function:: factorial(n,k) + :: + factorial(n) + + Factorial of ``n``. If ``n`` is an :obj:`Integer`, the factorial + is computed as an integer (promoted to at least 64 bits). Note + that this may overflow if ``n`` is not small, but you can use + ``factorial(big(n))`` to compute the result exactly in arbitrary + precision. If ``n`` is not an ``Integer``, ``factorial(n)`` is + equivalent to :func:`gamma(n+1) `. + + :: + factorial(n,k) + Compute ``factorial(n)/factorial(k)`` .. function:: factor(n) -> Dict @@ -1158,8 +1293,22 @@ Mathematical Functions Riemann zeta function :math:`\zeta(s)`. + :: + zeta(s, z) + + Hurwitz zeta function :math:`\zeta(s, z)`. (This is equivalent to + the Riemann zeta function :math:`\zeta(s)` for the case of ``z=1``.) + .. function:: zeta(s, z) + :: + zeta(s) + + Riemann zeta function :math:`\zeta(s)`. + + :: + zeta(s, z) + Hurwitz zeta function :math:`\zeta(s, z)`. (This is equivalent to the Riemann zeta function :math:`\zeta(s)` for the case of ``z=1``.) @@ -1222,18 +1371,99 @@ Statistics 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) + + Compute the middle of two reals ``x`` and ``y``, which is equivalent + in both value and type to computing their mean (``(x + y) / 2``). + + :: + middle(range) + + Compute the middle of a range, which consists in computing the mean of its extrema. + Since a range is sorted, the mean is performed with the first and last element. + + :: + middle(array) + + Compute the middle of an array, which consists in finding its extrema and + then computing their mean. + .. function:: middle(x, y) + :: + middle(x) + + Compute the middle of a scalar value, which is equivalent to ``x`` itself, + but of the type of ``middle(x, x)`` for consistency. + + :: + middle(x, y) + Compute the middle of two reals ``x`` and ``y``, which is equivalent in both value and type to computing their mean (``(x + y) / 2``). + :: + middle(range) + + Compute the middle of a range, which consists in computing the mean of its extrema. + Since a range is sorted, the mean is performed with the first and last element. + + :: + middle(array) + + Compute the middle of an array, which consists in finding its extrema and + then computing their mean. + .. function:: middle(range) + :: + middle(x) + + Compute the middle of a scalar value, which is equivalent to ``x`` itself, + but of the type of ``middle(x, x)`` for consistency. + + :: + middle(x, y) + + Compute the middle of two reals ``x`` and ``y``, which is equivalent + in both value and type to computing their mean (``(x + y) / 2``). + + :: + middle(range) + Compute the middle of a range, which consists in computing the mean of its extrema. Since a range is sorted, the mean is performed with the first and last element. + :: + middle(array) + + Compute the middle of an array, which consists in finding its extrema and + then computing their mean. + .. function:: middle(array) + :: + middle(x) + + Compute the middle of a scalar value, which is equivalent to ``x`` itself, + but of the type of ``middle(x, x)`` for consistency. + + :: + middle(x, y) + + Compute the middle of two reals ``x`` and ``y``, which is equivalent + in both value and type to computing their mean (``(x + y) / 2``). + + :: + middle(range) + + Compute the middle of a range, which consists in computing the mean of its extrema. + Since a range is sorted, the mean is performed with the first and last element. + + :: + middle(array) + Compute the middle of an array, which consists in finding its extrema and then computing their mean. @@ -1256,8 +1486,28 @@ Statistics ``v`` in each bin. Note: Julia does not ignore ``NaN`` values in the computation. + :: + hist(v, e) -> e, counts + + Compute the histogram of ``v`` using a vector/range ``e`` as the edges for + the bins. The result will be a vector of length ``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 + + Compute the histogram of ``v``, optionally using approximately ``n`` + bins. The return values are a range ``e``, which correspond to the + edges of the bins, and ``counts`` containing the number of elements of + ``v`` in each bin. + Note: Julia does not ignore ``NaN`` values in the computation. + + :: + hist(v, e) -> e, counts + Compute the histogram of ``v`` using a vector/range ``e`` as the edges for the bins. The result will be a vector of length ``length(e) - 1``, such that the element at location ``i`` satisfies ``sum(e[i] .< v .<= e[i+1])``. @@ -1302,8 +1552,20 @@ Statistics Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``. Note: Julia does not ignore ``NaN`` values in the computation. + :: + quantile(v, p) + + Compute the quantile of a vector ``v`` at the probability ``p``. + Note: Julia does not ignore ``NaN`` values in the computation. + .. function:: quantile(v, p) + Compute the quantiles of a vector ``v`` at a specified set of probability values ``p``. + Note: Julia does not ignore ``NaN`` values in the computation. + + :: + quantile(v, p) + Compute the quantile of a vector ``v`` at the probability ``p``. Note: Julia does not ignore ``NaN`` values in the computation. @@ -1340,7 +1602,6 @@ Statistics 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``. @@ -1348,7 +1609,6 @@ Statistics Users can use the keyword argument ``vardim`` to specify the variable dimension, and ``mean`` to supply pre-computed mean values. - Signal Processing ----------------- @@ -1587,8 +1847,21 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. Swap the first and second halves of each dimension of ``x``. + :: + fftshift(x,dim) + + Swap the first and second halves of the given dimension of array ``x``. + .. function:: fftshift(x,dim) + :: + fftshift(x) + + Swap the first and second halves of each dimension of ``x``. + + :: + fftshift(x,dim) + Swap the first and second halves of the given dimension of array ``x``. .. function:: ifftshift(x, [dim]) @@ -1618,8 +1891,22 @@ multi-threading. Use `FFTW.set_num_threads(np)` to use `np` threads. 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by the vectors ``u`` and ``v``. Uses 2-D FFT algorithm + :: + conv2(B,A) + + 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm + .. function:: conv2(B,A) + :: + conv2(u,v,A) + + 2-D convolution of the matrix ``A`` with the 2-D separable kernel generated by + the vectors ``u`` and ``v``. Uses 2-D FFT algorithm + + :: + conv2(B,A) + 2-D convolution of the matrix ``B`` with the matrix ``A``. Uses 2-D FFT algorithm .. function:: xcorr(u,v) @@ -1669,7 +1956,6 @@ The following functions are defined within the ``Base.FFTW`` module. Similar to :func:`Base.plan_fft`, but corresponds to :func:`r2r!`. .. currentmodule:: Base - Numerical Integration --------------------- @@ -1737,3 +2023,4 @@ some built-in integration support in Julia. 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 d7f103dbfbd2a..b58a774379335 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -50,6 +50,19 @@ Data Formats .. function:: parse(type, str, [base]) + :: + parse(str, start; greedy=true, raise=true) + + Parse the expression string and return an expression (which could later be passed to eval for execution). Start is the index of the first character to start parsing. If ``greedy`` is true (default), ``parse`` will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return ``Expr(:incomplete, "(error message)")``. If ``raise`` is true (default), syntax errors other than incomplete expressions will raise an error. If ``raise`` is false, ``parse`` will return an expression that will raise an error upon evaluation. + + :: + parse(str; raise=true) + + Parse the whole string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If ``raise`` is true (default), syntax errors will raise an error; otherwise, ``parse`` will return an expression that will raise an error upon evaluation. + + :: + parse(type, str, [base]) + Parse a string as a number. If the type is an integer type, then a base can be specified (the default is 10). If the type is a floating point type, the string is parsed as a decimal floating point number. If the string does not contain a valid number, an error is raised. @@ -117,7 +130,6 @@ Data Formats Convert an array of bytes to its hexadecimal representation. All characters are in lower-case. Returns an ASCIIString. - General Number Functions and Constants -------------------------------------- @@ -280,7 +292,6 @@ General Number Functions and Constants julia> big"2.1" 2.099999999999999999999999999999999999999999999999999999999999999999999999999986 - .. function:: get_rounding(T) Get the current floating point rounding mode for type ``T``, controlling @@ -396,8 +407,34 @@ Integers julia> isprime(3) true + :: + isprime(x::BigInt, [reps = 25]) -> Bool + + Probabilistic primality test. Returns ``true`` if ``x`` is prime; and + ``false`` if ``x`` is not prime with high probability. The false positive + rate is about ``0.25^reps``. ``reps = 25`` is considered safe for + cryptographic applications (Knuth, Seminumerical Algorithms). + + .. doctest:: + + julia> isprime(big(3)) + true + .. function:: isprime(x::BigInt, [reps = 25]) -> Bool + :: + isprime(x::Integer) -> Bool + + Returns ``true`` if ``x`` is prime, and ``false`` otherwise. + + .. doctest:: + + julia> isprime(3) + true + + :: + isprime(x::BigInt, [reps = 25]) -> Bool + Probabilistic primality test. Returns ``true`` if ``x`` is prime; and ``false`` if ``x`` is not prime with high probability. The false positive rate is about ``0.25^reps``. ``reps = 25`` is considered safe for @@ -527,3 +564,4 @@ As ``BigInt`` represents unbounded integers, the interval must be specified (e.g .. function:: randexp!([rng], A::Array{Float64,N}) Fill the array A with random numbers following the exponential distribution (with scale 1). + diff --git a/doc/stdlib/parallel.rst b/doc/stdlib/parallel.rst index 31ec2abfb10ac..8de090be91295 100644 --- a/doc/stdlib/parallel.rst +++ b/doc/stdlib/parallel.rst @@ -46,12 +46,52 @@ Tasks Look up the value of a symbol in the current task's task-local storage. + :: + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local storage. + + :: + task_local_storage(body, symbol, value) + + Call the function ``body`` with a modified task-local storage, in which + ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or + lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + .. function:: task_local_storage(symbol, value) + :: + task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local storage. + + :: + task_local_storage(symbol, value) + Assign a value to a symbol in the current task's task-local storage. + :: + task_local_storage(body, symbol, value) + + Call the function ``body`` with a modified task-local storage, in which + ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or + lack thereof, is restored afterwards. Useful for emulating dynamic scoping. + .. function:: task_local_storage(body, symbol, value) + :: + task_local_storage(symbol) + + Look up the value of a symbol in the current task's task-local storage. + + :: + task_local_storage(symbol, value) + + Assign a value to a symbol in the current task's task-local storage. + + :: + task_local_storage(body, symbol, value) + Call the function ``body`` with a modified task-local storage, in which ``value`` is assigned to ``symbol``; the previous value of ``symbol``, or lack thereof, is restored afterwards. Useful for emulating dynamic scoping. @@ -123,7 +163,6 @@ Tasks ``Channel()`` - equivalent to ``Channel{Any}(32)`` ``Channel(sz::Int)`` equivalent to ``Channel{Any}(sz)`` - General Parallel Computing Support ---------------------------------- @@ -132,12 +171,142 @@ General Parallel Computing Support Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. + :: + addprocs() -> List of process identifiers + + Equivalent to ``addprocs(CPU_CORES)`` + + :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. + Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + ``machines`` is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string ``machine_spec`` or a tuple - ``(machine_spec, count)`` + + ``machine_spec`` is a string of the form ``[user@]host[:port] [bind_addr[:port]]``. ``user`` defaults + to current user, ``port`` to the standard ssh port. If ``[bind_addr[:port]]`` is specified, other + workers will connect to this worker at the specified ``bind_addr`` and ``port``. + + ``count`` is the number of workers to be launched on the specified host. If specified as ``:auto`` + it will launch as many workers as the number of cores on the specific host. + + + Keyword arguments: + + ``tunnel`` : if ``true`` then SSH tunneling will be used to connect to the worker from the master process. + + ``sshflags`` : specifies additional ssh options, e.g. :literal:`sshflags=\`-i /home/foo/bar.pem\`` . + + ``max_parallel`` : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + ``dir`` : specifies the working directory on the workers. Defaults to the host's current directory (as found by `pwd()`) + + ``exename`` : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + ``exeflags`` : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, + the worker treats it a fatal situation and terminates. This timeout can be controlled via environment + variable ``JULIA_WORKER_TIMEOUT``. The value of ``JULIA_WORKER_TIMEOUT`` on the master process, specifies + the number of seconds a newly launched worker waits for connection establishment. + + :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster manager implemented + in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be + specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when + using TCP/IP as transport. + .. function:: addprocs() -> List of process identifiers + :: + addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. + This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. + + :: + addprocs() -> List of process identifiers + Equivalent to ``addprocs(CPU_CORES)`` + :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. + Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + ``machines`` is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string ``machine_spec`` or a tuple - ``(machine_spec, count)`` + + ``machine_spec`` is a string of the form ``[user@]host[:port] [bind_addr[:port]]``. ``user`` defaults + to current user, ``port`` to the standard ssh port. If ``[bind_addr[:port]]`` is specified, other + workers will connect to this worker at the specified ``bind_addr`` and ``port``. + + ``count`` is the number of workers to be launched on the specified host. If specified as ``:auto`` + it will launch as many workers as the number of cores on the specific host. + + + Keyword arguments: + + ``tunnel`` : if ``true`` then SSH tunneling will be used to connect to the worker from the master process. + + ``sshflags`` : specifies additional ssh options, e.g. :literal:`sshflags=\`-i /home/foo/bar.pem\`` . + + ``max_parallel`` : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + ``dir`` : specifies the working directory on the workers. Defaults to the host's current directory (as found by `pwd()`) + + ``exename`` : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + ``exeflags`` : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, + the worker treats it a fatal situation and terminates. This timeout can be controlled via environment + variable ``JULIA_WORKER_TIMEOUT``. The value of ``JULIA_WORKER_TIMEOUT`` on the master process, specifies + the number of seconds a newly launched worker waits for connection establishment. + + :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster manager implemented + in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be + specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when + using TCP/IP as transport. + .. function:: addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + :: + addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. + This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. + + :: + addprocs() -> List of process identifiers + + Equivalent to ``addprocs(CPU_CORES)`` + + :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + Add processes on remote machines via SSH. Requires julia to be installed in the same location on each node, or to be available via a shared file system. @@ -174,9 +343,73 @@ General Parallel Computing Support variable ``JULIA_WORKER_TIMEOUT``. The value of ``JULIA_WORKER_TIMEOUT`` on the master process, specifies the number of seconds a newly launched worker waits for connection establishment. + :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + + Launches worker processes via the specified cluster manager. + + For example Beowulf clusters are supported via a custom cluster manager implemented + in package ``ClusterManagers``. + + The number of seconds a newly launched worker waits for connection establishment from the master can be + specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when + using TCP/IP as transport. .. function:: addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + :: + addprocs(n::Integer; exeflags=``) -> List of process identifiers + + Launches workers using the in-built ``LocalManager`` which only launches workers on the local host. + This can be used to take advantage of multiple cores. ``addprocs(4)`` will add 4 processes on the local machine. + + :: + addprocs() -> List of process identifiers + + Equivalent to ``addprocs(CPU_CORES)`` + + :: + addprocs(machines; tunnel=false, sshflags=``, max_parallel=10, exeflags=``) -> List of process identifiers + + Add processes on remote machines via SSH. + Requires julia to be installed in the same location on each node, or to be available via a shared file system. + + ``machines`` is a vector of machine specifications. Worker are started for each specification. + + A machine specification is either a string ``machine_spec`` or a tuple - ``(machine_spec, count)`` + + ``machine_spec`` is a string of the form ``[user@]host[:port] [bind_addr[:port]]``. ``user`` defaults + to current user, ``port`` to the standard ssh port. If ``[bind_addr[:port]]`` is specified, other + workers will connect to this worker at the specified ``bind_addr`` and ``port``. + + ``count`` is the number of workers to be launched on the specified host. If specified as ``:auto`` + it will launch as many workers as the number of cores on the specific host. + + + Keyword arguments: + + ``tunnel`` : if ``true`` then SSH tunneling will be used to connect to the worker from the master process. + + ``sshflags`` : specifies additional ssh options, e.g. :literal:`sshflags=\`-i /home/foo/bar.pem\`` . + + ``max_parallel`` : specifies the maximum number of workers connected to in parallel at a host. Defaults to 10. + + ``dir`` : specifies the working directory on the workers. Defaults to the host's current directory (as found by `pwd()`) + + ``exename`` : name of the julia executable. Defaults to "$JULIA_HOME/julia" or "$JULIA_HOME/julia-debug" as the case may be. + + ``exeflags`` : additional flags passed to the worker processes. + + Environment variables : + + If the master process fails to establish a connection with a newly launched worker within 60.0 seconds, + the worker treats it a fatal situation and terminates. This timeout can be controlled via environment + variable ``JULIA_WORKER_TIMEOUT``. The value of ``JULIA_WORKER_TIMEOUT`` on the master process, specifies + the number of seconds a newly launched worker waits for connection establishment. + + :: + addprocs(manager::ClusterManager; kwargs...) -> List of process identifiers + Launches worker processes via the specified cluster manager. For example Beowulf clusters are supported via a custom cluster manager implemented @@ -186,7 +419,6 @@ General Parallel Computing Support specified via variable ``JULIA_WORKER_TIMEOUT`` in the worker process's environment. Relevant only when using TCP/IP as transport. - .. function:: nprocs() Get the number of available processes. @@ -199,6 +431,11 @@ General Parallel Computing Support Returns a list of all process identifiers. + :: + procs(S::SharedArray) + + Get the vector of processes that have mapped the shared array + .. function:: workers() Returns a list of all worker process identifiers. @@ -227,7 +464,6 @@ General Parallel Computing Support If ``err_retry`` is true, it retries a failed application of ``f`` on a different worker. If ``err_stop`` is true, it takes precedence over the value of ``err_retry`` and ``pmap`` stops execution on the first error. - .. function:: remotecall(id, func, args...) Call a function asynchronously on the given arguments on the specified process. Returns a ``RemoteRef``. @@ -279,16 +515,42 @@ General Parallel Computing Support 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) + + Appends an item to the channel. Blocks if the channel is full. + .. function:: put!(Channel, value) + :: + put!(RemoteRef, value) + + Store a value to a remote reference. Implements "shared queue of length 1" semantics: if a value is already present, blocks until the value is removed with ``take!``. Returns its first argument. + + :: + put!(Channel, value) + Appends an item to the channel. Blocks if the channel is full. .. function:: take!(RemoteRef) Fetch the value of a remote reference, removing it so that the reference is empty again. + :: + take!(Channel) + + Removes and returns a value from a ``Channel``. Blocks till data is available. + .. function:: take!(Channel) + :: + take!(RemoteRef) + + Fetch the value of a remote reference, removing it so that the reference is empty again. + + :: + take!(Channel) + Removes and returns a value from a ``Channel``. Blocks till data is available. .. function:: isready(r::RemoteRef) @@ -308,6 +570,14 @@ General Parallel Computing Support .. function:: close(Channel) + :: + close(stream) + + Close an I/O stream. Performs a ``flush`` first. + + :: + close(Channel) + Closes a channel. An exception is thrown by: * ``put!`` on a on a closed channel. @@ -318,8 +588,21 @@ General Parallel Computing Support Make an uninitialized remote reference on the local machine. + :: + RemoteRef(n) + + Make an uninitialized remote reference on process ``n``. + .. function:: RemoteRef(n) + :: + RemoteRef() + + Make an uninitialized remote reference on the local machine. + + :: + RemoteRef(n) + Make an uninitialized remote reference on process ``n``. .. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1) @@ -401,6 +684,14 @@ Shared Arrays (Experimental, UNIX-only feature) .. function:: procs(S::SharedArray) + :: + procs() + + Returns a list of all process identifiers. + + :: + procs(S::SharedArray) + Get the vector of processes that have mapped the shared array .. function:: sdata(S::SharedArray) @@ -439,6 +730,14 @@ Cluster Manager Interface .. function:: kill(manager::FooManager, pid::Int, config::WorkerConfig) + :: + kill(p::Process, signum=SIGTERM) + + Send a signal to a process. The default is to terminate the process. + + :: + kill(manager::FooManager, pid::Int, config::WorkerConfig) + Implemented by cluster managers. It is called on the master process, by ``rmprocs``. It should cause the remote worker specified by ``pid`` to exit. ``Base.kill(manager::ClusterManager.....)`` executes a remote ``exit()`` on ``pid`` @@ -450,15 +749,28 @@ Cluster Manager Interface .. function:: connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + :: + connect([host],port) -> TcpSocket + + Connect to the host ``host`` on port ``port`` + + :: + connect(path) -> Pipe + + Connect to the Named Pipe/Domain Socket at ``path`` + + :: + connect(manager::FooManager, pid::Int, config::WorkerConfig) -> (instrm::AsyncStream, outstrm::AsyncStream) + Implemented by cluster managers using custom transports. It should establish a logical connection to worker with id ``pid``, specified by ``config`` and return a pair of ``AsyncStream`` objects. Messages from ``pid`` to current process will be read off ``instrm``, while messages to be sent to ``pid`` will be written to ``outstrm``. The custom transport implementation must ensure that messages are delivered and received completely and in order. ``Base.connect(manager::ClusterManager.....)`` sets up TCP/IP socket connections in-between workers. - .. function:: 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 57a580fe45d4b..406a71aabdac0 100644 --- a/doc/stdlib/pkg.rst +++ b/doc/stdlib/pkg.rst @@ -15,8 +15,26 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, that path is used in the returned value as ``joinpath(ENV["JULIA_PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")``. If ``JULIA_PKGDIR`` is a relative path, it is interpreted relative to whatever the current working directory is. + :: + dir(names...) -> AbstractString + + Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. + In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. + .. function:: dir(names...) -> AbstractString + :: + dir() -> AbstractString + + Returns the absolute path of the package directory. + This defaults to ``joinpath(homedir(),".julia","v$(VERSION.major).$(VERSION.minor)")`` on all platforms + (i.e. ``~/.julia/v0.4`` in UNIX shell syntax). If the ``JULIA_PKGDIR`` environment variable is set, then + that path is used in the returned value as ``joinpath(ENV["JULIA_PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")``. + If ``JULIA_PKGDIR`` is a relative path, it is interpreted relative to whatever the current working directory is. + + :: + dir(names...) -> AbstractString + Equivalent to ``normpath(Pkg.dir(),names...)`` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, ``Pkg.dir(pkg)`` returns the path to the package ``pkg``. @@ -54,8 +72,25 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, The package repo is cloned by the name ``pkg`` if provided; if not provided, ``pkg`` is determined automatically from ``url``. + :: + clone(pkg) + + If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``, clone it from that URL on the default branch. + The package does not need to have any registered versions. + .. function:: clone(pkg) + :: + clone(url, [pkg]) + + Clone a package directly from the git URL ``url``. + The package does not need to be a registered in ``Pkg.dir("METADATA")``. + The package repo is cloned by the name ``pkg`` if provided; + if not provided, ``pkg`` is determined automatically from ``url``. + + :: + clone(pkg) + If ``pkg`` has a URL registered in ``Pkg.dir("METADATA")``, clone it from that URL on the default branch. The package does not need to have any registered versions. @@ -63,16 +98,42 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, Returns the names of available packages. + :: + available(pkg) -> Vector{VersionNumber} + + Returns the version numbers available for package ``pkg``. + .. function:: available(pkg) -> Vector{VersionNumber} + :: + available() -> Vector{ASCIIString} + + Returns the names of available packages. + + :: + available(pkg) -> Vector{VersionNumber} + Returns the version numbers available for package ``pkg``. .. function:: installed() -> Dict{ASCIIString,VersionNumber} Returns a dictionary mapping installed package names to the installed version number of each package. + :: + installed(pkg) -> Void | VersionNumber + + If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. + .. function:: installed(pkg) -> Void | VersionNumber + :: + installed() -> Dict{ASCIIString,VersionNumber} + + Returns a dictionary mapping installed package names to the installed version number of each package. + + :: + installed(pkg) -> Void | VersionNumber + If ``pkg`` is installed, return the installed version number, otherwise return ``nothing``. .. function:: status() @@ -95,8 +156,22 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, Pin ``pkg`` at the current version. To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` + :: + pin(pkg, version) + + Pin ``pkg`` at registered version ``version``. + .. function:: pin(pkg, version) + :: + pin(pkg) + + Pin ``pkg`` at the current version. + To go back to using the newest compatible released version, use ``Pkg.free(pkg)`` + + :: + pin(pkg, version) + Pin ``pkg`` at registered version ``version``. .. function:: free(pkg) @@ -112,8 +187,22 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, Run the build scripts for all installed packages in depth-first recursive order. + :: + build(pkgs...) + + Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. + This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. + .. function:: build(pkgs...) + :: + build() + + Run the build scripts for all installed packages in depth-first recursive order. + + :: + build(pkgs...) + Run the build script in "deps/build.jl" for each package in ``pkgs`` and all of their dependencies in depth-first recursive order. This is called automatically by ``Pkg.resolve()`` on all installed or updated packages. @@ -142,6 +231,20 @@ to use them, you'll need to prefix each function call with an explicit ``Pkg.``, Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + :: + test(pkgs...) + + Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + .. function:: test(pkgs...) + :: + test() + + Run the tests for all installed packages ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + + :: + test(pkgs...) + Run the tests for each package in ``pkgs`` ensuring that each package's test dependencies are installed for the duration of the test. A package is tested by running its ``test/runtests.jl`` file and test dependencies are specified in ``test/REQUIRE``. + diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index 1ab214c5efdb1..9b19d8d2d7214 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -15,7 +15,6 @@ 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() @@ -32,8 +31,30 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a correspond to the same line of code. ``cols`` controls the width of the display. + :: + print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + + Prints profiling results to ``io``. This variant is used to examine + results exported by a previous call to :func:`retrieve`. + Supply the vector ``data`` of backtraces and a dictionary + ``lidict`` of line information. + .. function:: print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + :: + print([io::IO = STDOUT,] [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols()) + + Prints profiling results to ``io`` (by default, ``STDOUT``). If you + do not supply a ``data`` vector, the internal buffer of accumulated + backtraces will be used. ``format`` can be ``:tree`` or + ``:flat``. If ``C==true``, backtraces from C and Fortran code are + shown. ``combine==true`` merges instruction pointers that + correspond to the same line of code. ``cols`` controls the width + of the display. + + :: + print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols()) + Prints profiling results to ``io``. This variant is used to examine results exported by a previous call to :func:`retrieve`. Supply the vector ``data`` of backtraces and a dictionary @@ -86,3 +107,4 @@ The methods in :mod:`Base.Profile` are not exported and need to be called e.g. a (to force JIT-compilation), then call :func:`clear_malloc_data`. Then execute your command(s) again, quit Julia, and examine the resulting ``*.mem`` files. + diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 93d2c42c866fc..d1ff0cceee9bc 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -133,8 +133,21 @@ Sorting Functions Variant of ``sort!`` that returns a sorted copy of ``v`` leaving ``v`` itself unmodified. + :: + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + + Sort a multidimensional array ``A`` along the given dimension. + .. function:: sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + :: + sort(v, [alg=,] [by=,] [lt=,] [rev=false]) + + Variant of ``sort!`` that returns a sorted copy of ``v`` leaving ``v`` itself unmodified. + + :: + sort(A, dim, [alg=,] [by=,] [lt=,] [rev=false]) + Sort a multidimensional array ``A`` along the given dimension. .. function:: sortperm(v, [alg=,] [by=,] [lt=,] [rev=false]) @@ -164,7 +177,6 @@ Sorting Functions Sort the columns of matrix ``A`` lexicographically. - Order-Related Functions ----------------------- @@ -224,7 +236,6 @@ Order-Related Functions ``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 3649350f8435b..c0a32995829ef 100644 --- a/doc/stdlib/strings.rst +++ b/doc/stdlib/strings.rst @@ -6,14 +6,50 @@ .. function:: length(s) + :: + length(A) -> Integer + + Returns the number of elements in A + + :: + length(collection) -> Integer + + For ordered, indexable collections, the maximum index ``i`` for which ``getindex(collection, i)`` is valid. For unordered collections, the number of elements. + + :: + length(s) + The number of characters in string ``s``. .. function:: sizeof(s::AbstractString) + :: + sizeof(type) + + Size, in bytes, of the canonical binary representation of the given type, if any. + + :: + sizeof(s::AbstractString) + The number of bytes in string ``s``. .. function:: *(s, t) + :: + *(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. .. doctest:: @@ -23,6 +59,14 @@ .. function:: ^(s, n) + :: + ^(x, y) + + Exponentiation operator. + + :: + ^(s, n) + Repeat ``n`` times the string ``s``. The ``^`` operator is an alias to this function. .. doctest:: @@ -42,32 +86,117 @@ Create a string from the address of a C (0-terminated) string encoded in ASCII or UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + :: + bytestring(s) + + Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. + .. function:: bytestring(s) + :: + bytestring(::Ptr{UInt8}, [length]) + + Create a string from the address of a C (0-terminated) string encoded in ASCII or UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + + :: + bytestring(s) + Convert a string to a contiguous byte array representation appropriate for passing it to C functions. The string will be encoded as either ASCII or UTF-8. .. function:: ascii(::Array{UInt8,1}) Create an ASCII string from a byte array. + :: + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + + :: + ascii(::Ptr{UInt8}, [length]) + + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + .. function:: ascii(s) + :: + ascii(::Array{UInt8,1}) + + Create an ASCII string from a byte array. + + :: + ascii(s) + Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + :: + ascii(::Ptr{UInt8}, [length]) + + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + .. function:: ascii(::Ptr{UInt8}, [length]) + :: + ascii(::Array{UInt8,1}) + + Create an ASCII string from a byte array. + + :: + ascii(s) + + Convert a string to a contiguous ASCII string (all characters must be valid ASCII characters). + + :: + ascii(::Ptr{UInt8}, [length]) + Create an ASCII string from the address of a C (0-terminated) string encoded in ASCII. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. .. function:: utf8(::Array{UInt8,1}) Create a UTF-8 string from a byte array. + :: + utf8(::Ptr{UInt8}, [length]) + + Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + + :: + utf8(s) + + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: utf8(::Ptr{UInt8}, [length]) + :: + utf8(::Array{UInt8,1}) + + Create a UTF-8 string from a byte array. + + :: + utf8(::Ptr{UInt8}, [length]) + Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + :: + utf8(s) + + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). + .. function:: utf8(s) + :: + utf8(::Array{UInt8,1}) + + Create a UTF-8 string from a byte array. + + :: + utf8(::Ptr{UInt8}, [length]) + + Create a UTF-8 string from the address of a C (0-terminated) string encoded in UTF-8. A copy is made; the ptr can be safely freed. If ``length`` is specified, the string does not have to be 0-terminated. + + :: + utf8(s) + Convert a string to a contiguous UTF-8 string (all characters must be valid UTF-8 characters). .. function:: normalize_string(s, normalform::Symbol) @@ -114,8 +243,32 @@ Returns true if the given value is valid for its type, which currently can be one of ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + :: + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. + Types currently can be ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + Values for ``Char`` can be of type ``Char`` or ``UInt32`` + Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` + Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` + Values for ``UTF32String`` can be ``UTF32String``, ``Vector{Char}`` or ``Vector{UInt32}`` + + :: + isvalid(str, i) + + Tells whether index ``i`` is valid for the given string + .. function:: isvalid(T, value) -> Bool + :: + isvalid(value) -> Bool + + Returns true if the given value is valid for its type, + which currently can be one of ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + + :: + 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`` @@ -123,6 +276,11 @@ Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` Values for ``UTF32String`` can be ``UTF32String``, ``Vector{Char}`` or ``Vector{UInt32}`` + :: + isvalid(str, i) + + Tells whether index ``i`` is valid for the given string + .. function:: is_assigned_char(c) -> Bool Returns true if the given char or integer is an assigned Unicode code point. @@ -249,6 +407,25 @@ .. function:: isvalid(str, i) + :: + isvalid(value) -> Bool + + Returns true if the given value is valid for its type, + which currently can be one of ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + + :: + isvalid(T, value) -> Bool + + Returns true if the given value is valid for that type. + Types currently can be ``Char``, ``ASCIIString``, ``UTF8String``, ``UTF16String``, or ``UTF32String`` + Values for ``Char`` can be of type ``Char`` or ``UInt32`` + Values for ``ASCIIString`` and ``UTF8String`` can be of that type, or ``Vector{UInt8}`` + Values for ``UTF16String`` can be ``UTF16String`` or ``Vector{UInt16}`` + Values for ``UTF32String`` can be ``UTF32String``, ``Vector{Char}`` or ``Vector{UInt32}`` + + :: + isvalid(str, i) + Tells whether index ``i`` is valid for the given string .. function:: nextind(str, i) @@ -377,31 +554,56 @@ making a copy of the data and treating the NUL as a terminator rather than as part of the string. -.. function:: utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) + :: + utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. -.. function:: utf32(s) +.. function:: utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) - Create a UTF-32 string from a byte array, array of ``Char`` or ``UInt32``, or - any other string type. (Conversions of byte arrays check for a - byte-order marker in the first four bytes, and do not include it in - the resulting string.) + :: + 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 ``UTF32String`` data is terminated by the NUL - codepoint (32-bit zero), which is not treated as a character in the + 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 - `utf32(s)` conversion function. If you have a ``Char`` or ``UInt32`` array - ``A`` that is already NUL-terminated UTF-32 data, then you - can instead use `UTF32String(A)`` to construct the string without + `utf16(s)` conversion function. If you have a ``UInt16`` array + ``A`` that is already NUL-terminated valid UTF-16 data, then you + can instead use `UTF16String(A)`` to construct the string without making a copy of the data and treating the NUL as a terminator rather than as part of the string. + :: + utf16(::Union{Ptr{UInt16},Ptr{Int16}} [, length]) + + Create a string from the address of a NUL-terminated UTF-16 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. + +.. function:: utf32(s) + + :: + wstring(s) + + This is a synonym for either ``utf32(s)`` or ``utf16(s)``, + depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. + The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` + is also provided. + .. function:: utf32(::Union{Ptr{Char},Ptr{UInt32},Ptr{Int32}} [, length]) - Create a string from the address of a NUL-terminated UTF-32 string. A copy is made; the pointer can be safely freed. If ``length`` is specified, the string does not have to be NUL-terminated. + :: + wstring(s) + + This is a synonym for either ``utf32(s)`` or ``utf16(s)``, + depending on whether ``Cwchar_t`` is 32 or 16 bits, respectively. + The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` + is also provided. .. function:: wstring(s) @@ -410,4 +612,3 @@ The synonym ``WString`` for ``UTF32String`` or ``UTF16String`` is also provided. - diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst index c8a1266d924df..514cb1a185b48 100644 --- a/doc/stdlib/test.rst +++ b/doc/stdlib/test.rst @@ -17,9 +17,7 @@ binary install, you can run the test suite using ``Base.runtests()``. 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 --------------