diff --git a/base/docs/helpdb.jl b/base/docs/helpdb.jl index c438c2087c1c8..fa4dd7b2738c9 100644 --- a/base/docs/helpdb.jl +++ b/base/docs/helpdb.jl @@ -328,7 +328,7 @@ Libdl.dlclose doc""" dlsym_e(handle, sym) -Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. +Look up a symbol from a shared library handle, silently return `NULL` pointer on lookup failure. """ Libdl.dlsym_e @@ -7119,13 +7119,6 @@ Sum absolute values of elements of `A` over the singleton dimensions of `r`, and """ sumabs! -doc""" - abs(x) - -Absolute value of `x` -""" -abs - doc""" Sys.set_process_title(title::AbstractString) diff --git a/base/int.jl b/base/int.jl index 6b845f09abef0..ea33ecf2f9424 100644 --- a/base/int.jl +++ b/base/int.jl @@ -46,25 +46,23 @@ copysign(x::Signed, y::Real) = copysign(x, -oftype(x,signbit(y))) abs(x::Unsigned) = x """ - abs(x::Signed) + abs(x) -The absolute value of x. When `abs` is applied to signed integers, +The absolute value of `x`. When `abs` is applied to signed integers, overflow may occur, resulting in the return of a negative value. This overflow occurs only when `abs` is applied to the minimum representable value of a signed integer. That is when `x == typemin(typeof(x))`, `abs(x) == x`, not `-x` as might be expected. - """ abs(x::Signed) = flipsign(x,x) """ - checked_abs(x::Signed) - -The absolute value of x, with signed integer overflow error trapping. -`checked_abs` will throw an `OverflowError` when `x == -typemin(typeof(x))`. Otherwise `checked_abs` behaves as `abs`, though -the overflow protection may impose a perceptible performance penalty. + Base.checked_abs(x::Signed) +The absolute value of `x`, with signed integer overflow error trapping. +`checked_abs` will throw an `OverflowError` when `x == typemin(typeof(x))`. +Otherwise `checked_abs` behaves as `abs`, though the overflow protection may +impose a perceptible performance penalty. """ function checked_abs{T<:Signed}(x::T) x == typemin(T) && throw(OverflowError()) diff --git a/base/linalg/generic.jl b/base/linalg/generic.jl index 02ae8a856974d..befb12cde9c6e 100644 --- a/base/linalg/generic.jl +++ b/base/linalg/generic.jl @@ -608,4 +608,3 @@ function normalize(v::AbstractVector, p::Real = 2) return T[] end end - diff --git a/base/linalg/qr.jl b/base/linalg/qr.jl index 2513c20944519..310e2ab3c7fed 100644 --- a/base/linalg/qr.jl +++ b/base/linalg/qr.jl @@ -122,7 +122,7 @@ Computes the polar decomposition of a vector. # See also -`normalize`, `normalize!`, `qr!` +`normalize`, `normalize!`, `LinAlg.qr!` """ function qr(v::AbstractVector) nrm = norm(v) @@ -136,15 +136,16 @@ function qr(v::AbstractVector) end """ - qr!(v::AbstractVector) + LinAlg.qr!(v::AbstractVector) -Computes the polar decomposition of a vector. +Computes the polar decomposition of a vector. Instead of returning a new vector +as `qr(v::AbstractVector)`, this function mutates the input vector `v` in place. # Input - `v::AbstractVector` - vector to normalize # Outputs -- `w` - A unit vector in the direction of `v` +- `w` - A unit vector in the direction of `v` (This is a mutation of `v`). - `r` - The norm of `v` # See also diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl index 1bf108b9f3020..1f253d6d51bc4 100644 --- a/doc/genstdlib.jl +++ b/doc/genstdlib.jl @@ -253,7 +253,7 @@ function translate(file) end end if doc == nothing || torst(doc, false) == nothing - info("no docs for $full in $mod") + info("$file: no docs for $full in $mod") println(io, l) doccing = false start_new_section() diff --git a/doc/stdlib/collections.rst b/doc/stdlib/collections.rst index 16fe7493af6d1..158a14831e377 100644 --- a/doc/stdlib/collections.rst +++ b/doc/stdlib/collections.rst @@ -538,6 +538,12 @@ Iterable Collections julia> all(i->(4<=i<=6), [4,5,6]) true +.. function:: foreach(f, c...) -> Void + + .. Docstring generated from Julia source + + Call function ``f`` on each element of iterable ``c``\ . For multiple iterable arguments, ``f`` is called elementwise. ``foreach`` should be used instead of ``map`` when the results of ``f`` are not needed, for example in ``foreach(println, array)``\ . + .. function:: map(f, c...) -> collection .. Docstring generated from Julia source @@ -884,17 +890,17 @@ Given a dictionary ``D``, the syntax ``D[x]`` returns the value of key ``x`` (if Suggest that collection ``s`` reserve capacity for at least ``n`` elements. This can improve performance. -.. function:: keytype(collection) +.. function:: keytype(type) .. Docstring generated from Julia source - For associative collection types, this will be the type of the Key, This is not defined for non-associative collections + Get the key type of an associative collection type. Behaves similarly to ``eltype``\ . -.. function:: valtype(collection) +.. function:: valtype(type) .. Docstring generated from Julia source - For associative collection types, this will be the type of the Value, This is not defined for non-associative collections + Get the value type of an associative collection type. Behaves similarly to ``eltype``\ . Fully implemented by: diff --git a/doc/stdlib/io-network.rst b/doc/stdlib/io-network.rst index 7aea241b86bca..6fa77d0f68272 100644 --- a/doc/stdlib/io-network.rst +++ b/doc/stdlib/io-network.rst @@ -237,7 +237,7 @@ General I/O .. Docstring generated from Julia source - Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``\ . The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. + Write an arbitrary value to a stream in an opaque format, such that it can be read back by ``deserialize``\ . The read-back value will be as identical as possible to the original. In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image. ``Ptr`` values are serialized as all-zero bit patterns (``NULL``\ ). .. function:: deserialize(stream) diff --git a/doc/stdlib/libdl.rst b/doc/stdlib/libdl.rst index fd7d80002ca46..aeb21d858d91b 100644 --- a/doc/stdlib/libdl.rst +++ b/doc/stdlib/libdl.rst @@ -60,7 +60,7 @@ .. Docstring generated from Julia source - Look up a symbol from a shared library handle, silently return NULL pointer on lookup failure. + Look up a symbol from a shared library handle, silently return ``NULL`` pointer on lookup failure. .. function:: dlclose(handle) diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index e901492b5c439..1956877f9702a 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -167,6 +167,56 @@ Linear algebra functions in Julia are largely implemented by calling functions f Same as ``ldltfact``\ , but saves space by overwriting the input ``A``\ , instead of creating a copy. +.. function:: qr(v::AbstractVector) + + .. Docstring generated from Julia source + + Computes the polar decomposition of a vector. + + Input + ***** + + + * ``v::AbstractVector`` - vector to normalize + + Outputs + ******* + + + * ``w`` - A unit vector in the direction of ``v`` + * ``r`` - The norm of ``v`` + + See also + ******** + + + ``normalize``\ , ``normalize!``\ , ``LinAlg.qr!`` + +.. function:: LinAlg.qr!(v::AbstractVector) + + .. Docstring generated from Julia source + + Computes the polar decomposition of a vector. Instead of returning a new vector as ``qr(v::AbstractVector)``\ , this function mutates the input vector ``v`` in place. + + Input + ***** + + + * ``v::AbstractVector`` - vector to normalize + + Outputs + ******* + + + * ``w`` - A unit vector in the direction of ``v`` (This is a mutation of ``v``\ ). + * ``r`` - The norm of ``v`` + + See also + ******** + + + ``normalize``\ , ``normalize!``\ , ``qr`` + .. function:: qr(A [,pivot=Val{false}][;thin=true]) -> Q, R, [p] .. Docstring generated from Julia source @@ -664,6 +714,56 @@ Linear algebra functions in Julia are largely implemented by calling functions f For example, if ``A`` is a matrix and ``p=2``\ , then this is equivalent to the Frobenius norm. +.. function:: normalize!(v, [p=2]) + + .. Docstring generated from Julia source + + Normalize the vector ``v`` in-place with respect to the ``p``\ -norm. + + Inputs + ****** + + + * ``v::AbstractVector`` - vector to be normalized + * ``p::Real`` - The ``p``\ -norm to normalize with respect to. Default: 2 + + Output + ****** + + + * ``v`` - A unit vector being the input vector, rescaled to have norm 1. The input vector is modified in-place. + + See also + ******** + + + ``normalize``\ , ``qr`` + +.. function:: normalize(v, [p=2]) + + .. Docstring generated from Julia source + + Normalize the vector ``v`` with respect to the ``p``\ -norm. + + Inputs + ****** + + + * ``v::AbstractVector`` - vector to be normalized + * ``p::Real`` - The ``p``\ -norm to normalize with respect to. Default: 2 + + Output + ****** + + + * ``v`` - A unit vector being a copy of the input vector, scaled to have norm 1 + + See also + ******** + + + ``normalize!``\ , ``qr`` + .. function:: cond(M, [p]) .. Docstring generated from Julia source @@ -733,8 +833,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f For more information, see [issue8859]_, [B96]_, [S84]_, [KY88]_. - .. [issue8859] Issue 8859, "Fix least squares", - https://github.com/JuliaLang/julia/pull/8859 + .. [issue8859] Issue 8859, "Fix least squares", https://github.com/JuliaLang/julia/pull/8859 .. [B96] Åke Björck, "Numerical Methods for Least Squares Problems", SIAM Press, Philadelphia, 1996, "Other Titles in Applied Mathematics", Vol. 51. `doi:10.1137/1.9781611971484 `_ diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index eaa6b0b5e6989..f283b231c7301 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -1070,7 +1070,13 @@ Mathematical Functions .. Docstring generated from Julia source - Absolute value of ``x`` + The absolute value of ``x``\ . When ``abs`` is applied to signed integers, overflow may occur, resulting in the return of a negative value. This overflow occurs only when ``abs`` is applied to the minimum representable value of a signed integer. That is when ``x == typemin(typeof(x))``\ , ``abs(x) == x``\ , not ``-x`` as might be expected. + +.. function:: Base.checked_abs(x::Signed) + + .. Docstring generated from Julia source + + The absolute value of ``x``\ , with signed integer overflow error trapping. ``checked_abs`` will throw an ``OverflowError`` when ``x == typemin(typeof(x))``\ . Otherwise ``checked_abs`` behaves as ``abs``\ , though the overflow protection may impose a perceptible performance penalty. .. function:: abs2(x)