diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 093327f981d216..21edb749e3c863 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -127,11 +127,41 @@ _length(A) = length(A) endof(a::AbstractArray) = length(a) first(a::AbstractArray) = a[first(eachindex(a))] +""" + first(coll) + +Get the first element of an iterable collection. Returns the start point of a +`Range` even if it is empty. + +```jldoctest +julia> first(2:2:10) +2 + +julia> first([1; 2; 3; 4]) +1 +``` +""" function first(itr) state = start(itr) done(itr, state) && throw(ArgumentError("collection must be non-empty")) next(itr, state)[1] end + +""" + last(coll) + +Get the last element of an ordered collection, if it can be computed in O(1) time. This is +accomplished by calling [`endof`](@ref) to get the last index. Returns the end +point of a `Range` even if it is empty. + +```jldoctest +julia> last(1:2:10) +9 + +julia> last([1; 2; 3; 4]) +4 +``` +""" last(a) = a[end] """ diff --git a/base/array.jl b/base/array.jl index e25aa09b644178..75b3de357dbc74 100644 --- a/base/array.jl +++ b/base/array.jl @@ -169,6 +169,13 @@ function getindex(::Type{Any}, vals::ANY...) end getindex(::Type{Any}) = Array{Any,1}(0) +""" + fill!(A, x) + +Fill array `A` with the value `x`. If `x` is an object reference, all elements will refer to +the same object. `fill!(A, Foo())` will return `A` filled with the result of evaluating +`Foo()` once. +""" function fill!(a::Union{Array{UInt8}, Array{Int8}}, x::Integer) ccall(:memset, Ptr{Void}, (Ptr{Void}, Cint, Csize_t), a, x, length(a)) return a @@ -205,6 +212,73 @@ dims)` will return an array filled with the result of evaluating `Foo()` once. fill(v, dims::Dims) = fill!(Array{typeof(v)}(dims), v) fill(v, dims::Integer...) = fill!(Array{typeof(v)}(dims...), v) +""" + zeros(type, dims) + +Create an array of all zeros of specified type. +The type defaults to `Float64` if not specified. + +```jldoctest +julia> zeros(Int8, 2, 3) +2×3 Array{Int8,2}: + 0 0 0 + 0 0 0 +``` +""" +zeros + +""" + zeros(A) + +Create an array of all zeros with the same element type and shape as `A`. + +```jldoctest +julia> A = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> zeros(A) +2×2 Array{Int64,2}: + 0 0 + 0 0 +``` +""" +zeros + +""" + ones(type, dims) + +Create an array of all ones of specified type. The type defaults to `Float64` if not specified. + +```jldoctest +julia> ones(Complex128, 2, 3) +2×3 Array{Complex{Float64},2}: + 1.0+0.0im 1.0+0.0im 1.0+0.0im + 1.0+0.0im 1.0+0.0im 1.0+0.0im +``` +""" +ones + +""" + ones(A) + +Create an array of all ones with the same element type and shape as `A`. + +```jldoctest +julia> A = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> ones(A) +2×2 Array{Int64,2}: + 1 1 + 1 1 +``` +""" +ones + for (fname, felt) in ((:zeros,:zero), (:ones,:one)) @eval begin ($fname)(T::Type, dims...) = fill!(Array{T}(dims...), ($felt)(T)) diff --git a/base/bitarray.jl b/base/bitarray.jl index 46a56ce9345fde..726080162f6b56 100644 --- a/base/bitarray.jl +++ b/base/bitarray.jl @@ -1301,6 +1301,23 @@ function (|)(B::BitArray, x::Bool) end (|)(x::Bool, B::BitArray) = B | x +""" + xor(x, y) + ⊻(x, y) + +Bitwise exclusive or of `x` and `y`. The infix operation +`a ⊻ b` is a synonym for `xor(a,b)`, and +`⊻` can be typed by tab-completing `\\xor` +or `\\veebar` in the Julia REPL. + +```jldoctest +julia> [true; true; false] ⊻ [true; false; false] +3-element Array{Bool,1}: + false + true + false +``` +""" function xor(B::BitArray, x::Bool) x ? ~B : copy(B) end diff --git a/base/bool.jl b/base/bool.jl index 8a524dbb0d29e3..398572b2613b7a 100644 --- a/base/bool.jl +++ b/base/bool.jl @@ -14,6 +14,23 @@ typemax(::Type{Bool}) = true ## boolean operations ## +""" + !(x) + +Boolean not. + +```jldoctest +julia> !true +false + +julia> !false +true + +julia> ![true false true] +1×3 Array{Bool,2}: + false true false +``` +""" function !(x::Bool) ## We need a better heuristic to detect this automatically @_pure_meta diff --git a/base/complex.jl b/base/complex.jl index 95ca6ae4cdec2e..81240d9df361be 100644 --- a/base/complex.jl +++ b/base/complex.jl @@ -75,17 +75,66 @@ real(T::Type) = typeof(real(zero(T))) real{T<:Real}(::Type{T}) = T real{T<:Real}(::Type{Complex{T}}) = T +""" + isreal(x) -> Bool + +Test whether `x` or all its elements are numerically equal to some real number. + +```jldoctest +julia> isreal(5.) +true + +julia> isreal([4.; complex(0,1)]) +false +``` +""" isreal(x::Real) = true isreal(z::Complex) = iszero(imag(z)) + """ isimag(z) -> Bool Test whether `z` is purely imaginary, i.e. has a real part equal to 0. """ isimag(z::Number) = iszero(real(z)) + +""" + isinteger(x) -> Bool + +Test whether `x` or all its elements are numerically equal to some integer. + +```jldoctest +julia> isinteger(4.0) +true + +julia> isinteger([1; 2; 5.5]) +false +``` +""" isinteger(z::Complex) = isreal(z) & isinteger(real(z)) + +""" + isfinite(f) -> Bool + +Test whether a number is finite. + +```jldoctest +julia> isfinite(5) +true + +julia> isfinite(NaN32) +false +``` +""" isfinite(z::Complex) = isfinite(real(z)) & isfinite(imag(z)) isnan(z::Complex) = isnan(real(z)) | isnan(imag(z)) + + +""" + isinf(f) -> Bool + +Test whether a number is infinite. +""" isinf(z::Complex) = isinf(real(z)) | isinf(imag(z)) iszero(z::Complex) = iszero(real(z)) & iszero(imag(z)) @@ -115,6 +164,11 @@ Complex{Int64} complex{T<:Real}(::Type{T}) = Complex{T} complex{T<:Real}(::Type{Complex{T}}) = Complex{T} +""" + flipsign(x, y) + +Return `x` with its sign flipped if `y` is negative. For example `abs(x) = flipsign(x,x)`. +""" flipsign(x::Complex, y::Real) = ifelse(signbit(y), -x, x) function show(io::IO, z::Complex) @@ -175,6 +229,12 @@ Compute the complex conjugate of a complex number `z`. """ conj(z::Complex) = Complex(real(z),-imag(z)) abs(z::Complex) = hypot(real(z), imag(z)) + +""" + abs2(x) + +Squared absolute value of `x`. +""" abs2(z::Complex) = real(z)*real(z) + imag(z)*imag(z) inv(z::Complex) = conj(z)/abs2(z) inv{T<:Integer}(z::Complex{T}) = inv(float(z)) @@ -451,15 +511,48 @@ log(z::Complex) = log(float(z)) # Complex(re, angle(z)) # end +""" + log10(x) + +Compute the logarithm of `x` to base 10. +Throws [`DomainError`](@ref) for negative `Real` arguments. + +```jldoctest +julia> log10(100) +2.0 + +julia> log10(2) +0.3010299956639812 +``` +""" function log10(z::Complex) a = log(z) a/log(oftype(real(a),10)) end + +""" + log2(x) + +Compute the logarithm of `x` to base 2. Throws [`DomainError`](@ref) for negative `Real` arguments. + +```jldoctest +julia> log2(4) +2.0 + +julia> log2(10) +3.321928094887362 +``` +""" function log2(z::Complex) a = log(z) a/log(oftype(real(a),2)) end +""" + exp(x) + +Compute ``e^x``. +""" function exp(z::Complex) zr, zi = reim(z) if isnan(zr) @@ -482,6 +575,11 @@ function exp(z::Complex) end end +""" + expm1(x) + +Accurately compute ``e^x-1``. +""" function expm1(z::Complex) zr,zi = reim(z) if isnan(zr) @@ -506,6 +604,14 @@ function expm1(z::Complex) end end +""" + log1p(x) + +Accurate natural logarithm of `1+x`. Throws [`DomainError`](@ref) for `Real` arguments less than -1. + +There is an experimental variant in the `Base.Math.JuliaLibm` module, which is typically +faster and more accurate. +""" function log1p{T}(z::Complex{T}) zr,zi = reim(z) if isfinite(zr) @@ -524,6 +630,12 @@ function log1p{T}(z::Complex{T}) end end +""" + ^(x, y) + +Exponentiation operator. +""" +Base.:(^)(x, y) function ^{T<:AbstractFloat}(z::Complex{T}, p::Complex{T})::Complex{T} if p == 2 #square zr, zi = reim(z) @@ -565,6 +677,19 @@ function exp2{T}(z::Complex{T}) Complex(er*cos(theta), er*sin(theta)) end +""" + exp10(x) + +Compute ``10^x``. + +```jldoctest +julia> exp10(2) +100.0 + +julia> exp10(0.2) +1.5848931924611136 +``` +""" function exp10{T}(z::Complex{T}) er = exp10(real(z)) theta = imag(z) * log(convert(T, 10)) @@ -639,6 +764,11 @@ end n>=0 ? power_by_squaring(z,n) : power_by_squaring(inv(z),-n) ^{T<:Integer}(z::Complex{T}, n::Integer) = power_by_squaring(z,n) # DomainError for n<0 +""" + sin(x) + +Compute sine of `x`, where `x` is in radians. +""" function sin{T}(z::Complex{T}) F = float(T) zr, zi = reim(z) @@ -655,7 +785,11 @@ function sin{T}(z::Complex{T}) end end +""" + cos(x) +Compute cosine of `x`, where `x` is in radians. +""" function cos{T}(z::Complex{T}) F = float(T) zr, zi = reim(z) @@ -674,13 +808,22 @@ function cos{T}(z::Complex{T}) end end +""" + tan(x) +Compute tangent of `x`, where `x` is in radians. +""" function tan(z::Complex) zr, zi = reim(z) w = tanh(Complex(-zi, zr)) Complex(imag(w), -real(w)) end +""" + asin(x) + +Compute the inverse sine of `x`, where the output is in radians. +""" function asin(z::Complex) zr, zi = reim(z) if isinf(zr) && isinf(zi) @@ -695,6 +838,11 @@ function asin(z::Complex) Complex(ξ,η) end +""" + acos(x) + +Compute the inverse cosine of `x`, where the output is in radians +""" function acos{T<:AbstractFloat}(z::Complex{T}) zr, zi = reim(z) if isnan(zr) @@ -718,22 +866,42 @@ function acos{T<:AbstractFloat}(z::Complex{T}) end acos(z::Complex) = acos(float(z)) +""" + atan(x) + +Compute the inverse tangent of `x`, where the output is in radians. +""" function atan(z::Complex) w = atanh(Complex(-imag(z),real(z))) Complex(imag(w),-real(w)) end +""" + sinh(x) + +Compute hyperbolic sine of `x`. +""" function sinh(z::Complex) zr, zi = reim(z) w = sin(Complex(zi, zr)) Complex(imag(w),real(w)) end +""" + cosh(x) + +Compute hyperbolic cosine of `x`. +""" function cosh(z::Complex) zr, zi = reim(z) cos(Complex(zi,-zr)) end +""" + tanh(x) + +Compute hyperbolic tangent of `x`. +""" function tanh{T<:AbstractFloat}(z::Complex{T}) const Ω = prevfloat(typemax(T)) ξ, η = reim(z) @@ -755,11 +923,21 @@ function tanh{T<:AbstractFloat}(z::Complex{T}) end tanh(z::Complex) = tanh(float(z)) +""" + asinh(x) + +Compute the inverse hyperbolic sine of `x`. +""" function asinh(z::Complex) w = asin(Complex(-imag(z),real(z))) Complex(imag(w),-real(w)) end +""" + acosh(x) + +Compute the inverse hyperbolic cosine of `x`. +""" function acosh(z::Complex) zr, zi = reim(z) if isnan(zr) || isnan(zi) @@ -779,6 +957,11 @@ function acosh(z::Complex) Complex(ξ, η) end +""" + atanh(x) + +Compute the inverse hyperbolic tangent of `x`. +""" function atanh{T<:AbstractFloat}(z::Complex{T}) const Ω = prevfloat(typemax(T)) const θ = sqrt(Ω)/4 diff --git a/base/dict.jl b/base/dict.jl index 5950b8adb3aaac..a595115bac16e6 100644 --- a/base/dict.jl +++ b/base/dict.jl @@ -283,6 +283,23 @@ function sizehint!(d::Dict, newsz) rehash!(d, newsz) end +""" + empty!(collection) -> collection + +Remove all elements from a `collection`. + +```jldoctest +julia> A = Dict("a" => 1, "b" => 2) +Dict{String,Int64} with 2 entries: + "b" => 2 + "a" => 1 + +julia> empty!(A); + +julia> A +Dict{String,Int64} with 0 entries +``` +""" function empty!{K,V}(h::Dict{K,V}) fill!(h.slots, 0x0) sz = length(h.slots) diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index cb199b0d0c6c89..e09806c60cc709 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -2,22 +2,6 @@ # Base -""" - systemerror(sysfunc, iftrue) - -Raises a `SystemError` for `errno` with the descriptive string `sysfunc` if `iftrue` is `true` -""" -systemerror - -""" - fill!(A, x) - -Fill array `A` with the value `x`. If `x` is an object reference, all elements will refer to -the same object. `fill!(A, Foo())` will return `A` filled with the result of evaluating -`Foo()` once. -""" -fill! - """ read!(stream::IO, array::Union{Array, BitArray}) read!(filename::AbstractString, array::Union{Array, BitArray}) @@ -26,32 +10,6 @@ Read binary data from an I/O stream or file, filling in `array`. """ read! -""" - empty!(collection) -> collection - -Remove all elements from a `collection`. - -```jldoctest -julia> A = Dict("a" => 1, "b" => 2) -Dict{String,Int64} with 2 entries: - "b" => 2 - "a" => 1 - -julia> empty!(A); - -julia> A -Dict{String,Int64} with 0 entries -``` -""" -empty! - -""" - asin(x) - -Compute the inverse sine of `x`, where the output is in radians. -""" -asin - """ pointer(array [, index]) @@ -63,35 +21,6 @@ Calling `Ref(array[, index])` is generally preferable to this function. """ pointer -""" - //(num, den) - -Divide two integers or rational numbers, giving a `Rational` result. -""" -Base.:(//) - -""" - isinteger(x) -> Bool - -Test whether `x` or all its elements are numerically equal to some integer. - -```jldoctest -julia> isinteger(4.0) -true - -julia> isinteger([1; 2; 5.5]) -false -``` -""" -isinteger - -""" - prod!(r, A) - -Multiply elements of `A` over the singleton dimensions of `r`, and write results to `r`. -""" -prod! - """ cummin(A, [dim]) @@ -99,21 +28,6 @@ Cumulative minimum along a dimension. The dimension defaults to 1. """ cummin -""" - eigfact!(A, [B]) - -Same as [`eigfact`](@ref), but saves space by overwriting the input `A` (and -`B`), instead of creating a copy. -""" -eigfact! - -""" - cosh(x) - -Compute hyperbolic cosine of `x`. -""" -cosh - """ precision(num::AbstractFloat) @@ -122,24 +36,6 @@ the mantissa. """ precision -""" - promote_type(type1, type2) - -Determine a type big enough to hold values of each argument type without loss, whenever -possible. In some cases, where no type exists to which both types can be promoted -losslessly, some loss is tolerated; for example, `promote_type(Int64,Float64)` returns -`Float64` even though strictly, not all `Int64` values can be represented exactly as -`Float64` values. -""" -promote_type - -""" - backtrace() - -Get a backtrace object for the current program point. -""" -backtrace - """ -(x) @@ -253,13 +149,6 @@ Compute the hyperbolic secant of `x` """ sech -""" - acos(x) - -Compute the inverse cosine of `x`, where the output is in radians -""" -acos - """ unsafe_copy!(dest::Ptr{T}, src::Ptr{T}, N) @@ -382,14 +271,6 @@ Bessel function of the second kind of order 0, ``Y_0(x)``. """ bessely0 -""" - any!(r, A) - -Test whether any values in `A` along the singleton dimensions of `r` are `true`, and write -results to `r`. -""" -any! - """ filter!(function, collection) @@ -438,30 +319,6 @@ An operation tried to write to memory that is read-only. """ ReadOnlyMemoryError -""" - last(coll) - -Get the last element of an ordered collection, if it can be computed in O(1) time. This is -accomplished by calling [`endof`](@ref) to get the last index. Returns the end -point of a `Range` even if it is empty. - -```jldoctest -julia> last(1:2:10) -9 - -julia> last([1; 2; 3; 4]) -4 -``` -""" -last - -""" - sinh(x) - -Compute hyperbolic sine of `x`. -""" -sinh - """ ceil([T,] x, [digits, [base]]) @@ -482,21 +339,6 @@ Convert `y` to the type of `x` (`convert(typeof(x), y)`). """ oftype -""" - isfinite(f) -> Bool - -Test whether a number is finite. - -```jldoctest -julia> isfinite(5) -true - -julia> isfinite(NaN32) -false -``` -""" -isfinite - """ push!(collection, items...) -> collection @@ -519,14 +361,6 @@ Use [`append!`](@ref) to add all the elements of another collection to """ push! -""" - prevpow(a, x) - -The largest `a^n` not greater than `x`, where `n` is a non-negative integer. -`a` must be greater than 1, and `x` must not be less than 1. -""" -prevpow - """ promote(xs...) @@ -534,13 +368,6 @@ Convert all arguments to their common promotion type (if any), and return them a """ promote -""" - tan(x) - -Compute tangent of `x`, where `x` is in radians. -""" -tan - """ fd(stream) @@ -549,39 +376,6 @@ to synchronous `File`'s and `IOStream`'s not to any of the asynchronous streams. """ fd -""" - ones(type, dims) - -Create an array of all ones of specified type. The type defaults to `Float64` if not specified. - -```jldoctest -julia> ones(Complex128, 2, 3) -2×3 Array{Complex{Float64},2}: - 1.0+0.0im 1.0+0.0im 1.0+0.0im - 1.0+0.0im 1.0+0.0im 1.0+0.0im -``` -""" -ones(t,dims) - -""" - ones(A) - -Create an array of all ones with the same element type and shape as `A`. - -```jldoctest -julia> A = [1 2; 3 4] -2×2 Array{Int64,2}: - 1 2 - 3 4 - -julia> ones(A) -2×2 Array{Int64,2}: - 1 1 - 1 1 -``` -""" -ones(A) - """ reshape(A, dims) @@ -623,15 +417,6 @@ Like [`randsubseq`](@ref), but the results are stored in `S` """ randsubseq! -""" - maximum(A, dims) - -Compute the maximum value of an array over the given dimensions. See also the -[`max(a,b)`](@ref) function to take the maximum of two or more arguments, -which can be applied elementwise to arrays via `max.(a,b)`. -""" -maximum(A,dims) - """ redisplay(x) redisplay(d::Display, x) @@ -694,13 +479,6 @@ Determine whether Julia is running an interactive session. """ isinteractive -""" - sum!(r, A) - -Sum elements of `A` over the singleton dimensions of `r`, and write results to `r`. -""" -sum! - """ display(x) display(d::Display, x) @@ -753,22 +531,6 @@ original string, otherwise they must be from distinct character ranges. """ eachmatch -""" - log10(x) - -Compute the logarithm of `x` to base 10. -Throws [`DomainError`](@ref) for negative `Real` arguments. - -```jldoctest -julia> log10(100) -2.0 - -julia> log10(2) -0.3010299956639812 -``` -""" -log10 - """ num2hex(f) @@ -789,21 +551,6 @@ previously unallocated space with '\\0' if the file or buffer is grown. """ truncate -""" - exp10(x) - -Compute ``10^x``. - -```jldoctest -julia> exp10(2) -100.0 - -julia> exp10(0.2) -1.5848931924611136 -``` -""" -exp10 - """ &(x, y) @@ -819,14 +566,6 @@ julia> 4 & 12 """ & -""" - cumsum!(B, A, [dim]) - -Cumulative sum of `A` along a dimension, storing the result in `B`. The dimension defaults -to 1. -""" -cumsum! - """ select(v, k, [by=,] [lt=,] [rev=false]) @@ -1021,53 +760,6 @@ array. """ select! -""" - maximum!(r, A) - -Compute the maximum value of `A` over the singleton dimensions of `r`, and write results to `r`. -""" -maximum! - -""" - prod(A, dims) - -Multiply elements of an array over the given dimensions. - -```jldoctest -julia> A = [1 2; 3 4] -2×2 Array{Int64,2}: - 1 2 - 3 4 - -julia> prod(A, 1) -1×2 Array{Int64,2}: - 3 8 - -julia> prod(A, 2) -2×1 Array{Int64,2}: - 2 - 12 -``` -""" -prod(A, dims) - -""" - log1p(x) - -Accurate natural logarithm of `1+x`. Throws [`DomainError`](@ref) for `Real` arguments less than -1. - -There is an experimental variant in the `Base.Math.JuliaLibm` module, which is typically -faster and more accurate. -""" -log1p - -""" - flipsign(x, y) - -Return `x` with its sign flipped if `y` is negative. For example `abs(x) = flipsign(x,x)`. -""" -flipsign - """ randstring([rng,] len=8) @@ -1121,29 +813,6 @@ serialized as all-zero bit patterns (`NULL`). """ serialize -""" - sum(A, dims) - -Sum elements of an array over the given dimensions. - -```jldoctest -julia> A = [1 2; 3 4] -2×2 Array{Int64,2}: - 1 2 - 3 4 - -julia> sum(A, 1) -1×2 Array{Int64,2}: - 4 6 - -julia> sum(A, 2) -2×1 Array{Int64,2}: - 3 - 7 -``` -""" -sum(A, dims) - """ typemin(T) @@ -1252,14 +921,6 @@ respectively. """ cglobal -""" - one(x) - -Get the multiplicative identity element for the type of `x` (`x` can also specify the type -itself). For matrices, returns an identity matrix of the appropriate size and type. -""" -one - """ endof(collection) -> Integer @@ -1279,28 +940,6 @@ For a given iterable object and iteration state, return the current item and the """ next -""" - log2(x) - -Compute the logarithm of `x` to base 2. Throws [`DomainError`](@ref) for negative `Real` arguments. - -```jldoctest -julia> log2(4) -2.0 - -julia> log2(10) -3.321928094887362 -``` -""" -log2 - -""" - abs2(x) - -Squared absolute value of `x`. -""" -abs2 - """ sizehint!(s, n) @@ -1373,13 +1012,6 @@ floating point number. If the string does not contain a valid number, an error i """ parse(T::Type, str, base=Int) -""" - ^(x, y) - -Exponentiation operator. -""" -Base.:(^)(x, y) - """ position(s) @@ -1447,13 +1079,6 @@ Byte-swap an integer. """ bswap -""" - tanh(x) - -Compute hyperbolic tangent of `x`. -""" -tanh - """ maxintfloat(T) @@ -1522,13 +1147,6 @@ Compute a type that contains both `T` and `S`. """ typejoin -""" - sin(x) - -Compute sine of `x`, where `x` is in radians. -""" -sin - """ selectperm!(ix, v, k, [alg=,] [by=,] [lt=,] [rev=false,] [initialized=false]) @@ -1544,38 +1162,6 @@ Compile the given function `f` for the argument tuple (of types) `args`, but do """ precompile -""" - asinh(x) - -Compute the inverse hyperbolic sine of `x`. -""" -asinh - -""" - minimum(A, dims) - -Compute the minimum value of an array over the given dimensions. See also the -[`min(a,b)`](@ref) function to take the minimum of two or more arguments, -which can be applied elementwise to arrays via `min.(a,b)`. - -```jldoctest -julia> A = [1 2; 3 4] -2×2 Array{Int64,2}: - 1 2 - 3 4 - -julia> minimum(A, 1) -1×2 Array{Int64,2}: - 1 2 - -julia> minimum(A, 2) -2×1 Array{Int64,2}: - 1 - 3 -``` -""" -minimum(A,dims) - """ cot(x) @@ -1636,13 +1222,6 @@ Typically, any type that implements `hash` should also implement its own `==` (h """ hash -""" - atanh(x) - -Compute the inverse hyperbolic tangent of `x`. -""" -atanh - """ read(stream::IO, T) @@ -1779,29 +1358,6 @@ The highest value representable by the given (real) numeric `DataType`. """ typemax -""" - all(A, dims) - -Test whether all values along the given dimensions of an array are `true`. - -```jldoctest -julia> A = [true false; true true] -2×2 Array{Bool,2}: - true false - true true - -julia> all(A, 1) -1×2 Array{Bool,2}: - true false - -julia> all(A, 2) -2×1 Array{Bool,2}: - false - true -``` -""" -all(A::AbstractArray, dims) - """ DomainError() @@ -1809,13 +1365,6 @@ The arguments to a function or constructor are outside the valid domain. """ DomainError -""" - acosh(x) - -Compute the inverse hyperbolic cosine of `x`. -""" -acosh - """ IntSet([itr]) @@ -1959,13 +1508,6 @@ values such as `NaN`. """ isless -""" - expm1(x) - -Accurately compute ``e^x-1``. -""" -expm1 - """ showerror(io, e) @@ -2009,13 +1551,6 @@ Perform garbage collection. This should not generally be used. """ gc -""" - minimum!(r, A) - -Compute the minimum value of `A` over the singleton dimensions of `r`, and write results to `r`. -""" -minimum! - """ unsafe_trunc(T, x) @@ -2033,14 +1568,6 @@ it is not a view. """ parent -""" - nextpow(a, x) - -The smallest `a^n` not less than `x`, where `n` is a non-negative integer. `a` must be -greater than 1, and `x` must be greater than 0. -""" -nextpow - """ gc_enable(on::Bool) @@ -2050,20 +1577,6 @@ used only with extreme caution, as it can cause memory use to grow without bound """ gc_enable -""" - atan(x) - -Compute the inverse tangent of `x`, where the output is in radians. -""" -atan - -""" - isinf(f) -> Bool - -Test whether a number is infinite. -""" -isinf - """ secd(x) @@ -2120,21 +1633,6 @@ but deprecated. """ Array -""" - isreal(x) -> Bool - -Test whether `x` or all its elements are numerically equal to some real number. - -```jldoctest -julia> isreal(5.) -true - -julia> isreal([4.; complex(0,1)]) -false -``` -""" -isreal - """ issubtype(type1, type2) @@ -2211,13 +1709,6 @@ Test whether a string contains a match of the given regular expression. """ ismatch -""" - exp(x) - -Compute ``e^x``. -""" -exp - """ matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString} @@ -2267,63 +1758,6 @@ the integrity and correctness of data read from `stream`. """ deserialize -""" - first(coll) - -Get the first element of an iterable collection. Returns the start point of a -`Range` even if it is empty. - -```jldoctest -julia> first(2:2:10) -2 - -julia> first([1; 2; 3; 4]) -1 -``` -""" -first - -""" - median!(v) - -Like [`median`](@ref), but may overwrite the input vector. -""" -median! - -""" - cumprod!(B, A, [dim]) - -Cumulative product of `A` along a dimension, storing the result in `B`. The dimension defaults to 1. -""" -cumprod! - -""" - rethrow([e]) - -Throw an object without changing the current exception backtrace. The default argument is -the current exception (if called within a `catch` block). -""" -rethrow - -""" - !(x) - -Boolean not. - -```jldoctest -julia> !true -false - -julia> !false -true - -julia> ![true false true] -1×3 Array{Bool,2}: - false true false -``` -""" -Base.:(!) - """ length(collection) -> Integer @@ -2461,20 +1895,6 @@ Determine whether `x` is of the given `type`. """ isa -""" - catch_backtrace() - -Get the backtrace of the current exception, for use within `catch` blocks. -""" -catch_backtrace - -""" - cos(x) - -Compute cosine of `x`, where `x` is in radians. -""" -cos - """ done(iter, state) -> Bool @@ -2674,54 +2094,6 @@ Return `true` if `A` is a subset of or equal to `S`. """ issubset -""" - zero(x) - -Get the additive identity element for the type of `x` (`x` can also specify the type itself). -""" -zero - -""" - any(A, dims) - -Test whether any values along the given dimensions of an array are `true`. -""" -any(::AbstractArray,dims) - -""" - zeros(type, dims) - -Create an array of all zeros of specified type. -The type defaults to `Float64` if not specified. - -```jldoctest -julia> zeros(Int8, 2, 3) -2×3 Array{Int8,2}: - 0 0 0 - 0 0 0 -``` -""" -zeros(t,dims) - -""" - zeros(A) - -Create an array of all zeros with the same element type and shape as `A`. - -```jldoctest -julia> A = [1 2; 3 4] -2×2 Array{Int64,2}: - 1 2 - 3 4 - -julia> zeros(A) -2×2 Array{Int64,2}: - 0 0 - 0 0 -``` -""" -zeros(A) - """ Symbol(x...) -> Symbol @@ -2807,13 +2179,6 @@ string does not contain a valid number. """ tryparse -""" - all!(r, A) - -Test whether all values in `A` along the singleton dimensions of `r` are `true`, and write results to `r`. -""" -all! - """ exit([code]) @@ -2991,23 +2356,4 @@ DivideError Compute the Dawson function (scaled imaginary error function) of `x`, defined by ``\\frac{\\sqrt{\\pi}}{2} e^{-x^2} \\operatorname{erfi}(x)``. """ -dawson - -""" - xor(x, y) - ⊻(x, y) - -Bitwise exclusive or of `x` and `y`. The infix operation -`a ⊻ b` is a synonym for `xor(a,b)`, and -`⊻` can be typed by tab-completing `\\xor` -or `\\veebar` in the Julia REPL. - -```jldoctest -julia> [true; true; false] ⊻ [true; false; false] -3-element Array{Bool,1}: - false - true - false -``` -""" -Base.xor(x, y) +dawson \ No newline at end of file diff --git a/base/error.jl b/base/error.jl index 9beef3b93bdd72..464851e08bbe6d 100644 --- a/base/error.jl +++ b/base/error.jl @@ -21,16 +21,38 @@ error(s::AbstractString) = throw(ErrorException(s)) error(s...) = throw(ErrorException(Main.Base.string(s...))) +""" + rethrow([e]) + +Throw an object without changing the current exception backtrace. The default argument is +the current exception (if called within a `catch` block). +""" rethrow() = ccall(:jl_rethrow, Bottom, ()) rethrow(e) = ccall(:jl_rethrow_other, Bottom, (Any,), e) + +""" + backtrace() + +Get a backtrace object for the current program point. +""" backtrace() = ccall(:jl_backtrace_from_here, Array{Ptr{Void},1}, (Int32,), false) + +""" + catch_backtrace() + +Get the backtrace of the current exception, for use within `catch` blocks. +""" catch_backtrace() = ccall(:jl_get_backtrace, Array{Ptr{Void},1}, ()) ## keyword arg lowering generates calls to this ## kwerr(kw, args...) = throw(MethodError(typeof(args[1]).name.mt.kwsorter, (kw,args...))) ## system error handling ## +""" + systemerror(sysfunc, iftrue) +Raises a `SystemError` for `errno` with the descriptive string `sysfunc` if `iftrue` is `true` +""" systemerror(p, b::Bool; extrainfo=nothing) = b ? throw(Main.Base.SystemError(string(p), Libc.errno(), extrainfo)) : nothing ## assertion functions and macros ## diff --git a/base/intfuncs.jl b/base/intfuncs.jl index bdef46e9e9e11c..f3ddfea6123f6f 100644 --- a/base/intfuncs.jl +++ b/base/intfuncs.jl @@ -274,6 +274,12 @@ false """ ispow2(x::Integer) = x > 0 && count_ones(x) == 1 +""" + nextpow(a, x) + +The smallest `a^n` not less than `x`, where `n` is a non-negative integer. `a` must be +greater than 1, and `x` must be greater than 0. +""" # smallest a^n >= x, with integer n function nextpow(a::Real, x::Real) (a <= 1 || x <= 0) && throw(DomainError()) @@ -283,6 +289,13 @@ function nextpow(a::Real, x::Real) # guard against roundoff error, e.g., with a=5 and x=125 p >= x ? p : a^n end + +""" + prevpow(a, x) + +The largest `a^n` not greater than `x`, where `n` is a non-negative integer. +`a` must be greater than 1, and `x` must not be less than 1. +""" # largest a^n <= x, with integer n function prevpow(a::Real, x::Real) (a <= 1 || x < 1) && throw(DomainError()) diff --git a/base/linalg/eigen.jl b/base/linalg/eigen.jl index 93203248430e6e..43c0ad451cb722 100644 --- a/base/linalg/eigen.jl +++ b/base/linalg/eigen.jl @@ -25,6 +25,12 @@ end isposdef(A::Union{Eigen,GeneralizedEigen}) = isreal(A.values) && all(x -> x > 0, A.values) +""" + eigfact!(A, [B]) + +Same as [`eigfact`](@ref), but saves space by overwriting the input `A` (and +`B`), instead of creating a copy. +""" function eigfact!{T<:BlasReal}(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) n = size(A, 2) n == 0 && return Eigen(zeros(T, 0), zeros(T, 0, 0)) diff --git a/base/multidimensional.jl b/base/multidimensional.jl index eeeb92463b013e..18dcefecabc7e1 100644 --- a/base/multidimensional.jl +++ b/base/multidimensional.jl @@ -529,6 +529,12 @@ function accumulate_pairwise{T}(op, v::AbstractVector{T}) return accumulate_pairwise!(op, out, v) end +""" + cumsum!(B, A, [dim]) + +Cumulative sum of `A` along a dimension, storing the result in `B`. The dimension defaults +to 1. +""" function cumsum!(out, v::AbstractVector, axis::Integer=1) # for types prone to numerical stability issues, we want # accumulate_pairwise. @@ -594,6 +600,12 @@ julia> cumprod(a,2) ``` """ cumprod(A::AbstractArray, axis::Integer=1) = accumulate(*, A, axis) + +""" + cumprod!(B, A, [dim]) + +Cumulative product of `A` along a dimension, storing the result in `B`. The dimension defaults to 1. +""" cumprod!(B, A, axis::Integer=1) = accumulate!(*, B, A, axis) """ diff --git a/base/number.jl b/base/number.jl index 9ed1f47487331e..e628bbf6833fea 100644 --- a/base/number.jl +++ b/base/number.jl @@ -102,8 +102,20 @@ in(x::Number, y::Number) = x == y map(f, x::Number, ys::Number...) = f(x, ys...) +""" + zero(x) + +Get the additive identity element for the type of `x` (`x` can also specify the type itself). +""" zero(x::Number) = oftype(x,0) zero{T<:Number}(::Type{T}) = convert(T,0) + +""" + one(x) + +Get the multiplicative identity element for the type of `x` (`x` can also specify the type +itself). For matrices, returns an identity matrix of the appropriate size and type. +""" one(x::Number) = oftype(x,1) one{T<:Number}(::Type{T}) = convert(T,1) diff --git a/base/promotion.jl b/base/promotion.jl index 7edd37d3090561..2c85dacf251b56 100644 --- a/base/promotion.jl +++ b/base/promotion.jl @@ -130,6 +130,15 @@ promote_type{T}(::Type{T}, ::Type{T}) = (@_pure_meta; T) promote_type{T}(::Type{T}, ::Type{Bottom}) = (@_pure_meta; T) promote_type{T}(::Type{Bottom}, ::Type{T}) = (@_pure_meta; T) +""" + promote_type(type1, type2) + +Determine a type big enough to hold values of each argument type without loss, whenever +possible. In some cases, where no type exists to which both types can be promoted +losslessly, some loss is tolerated; for example, `promote_type(Int64,Float64)` returns +`Float64` even though strictly, not all `Int64` values can be represented exactly as +`Float64` values. +""" # Try promote_rule in both orders. Typically only one is defined, # and there is a fallback returning Bottom below, so the common case is # promote_type(T, S) => diff --git a/base/rational.jl b/base/rational.jl index 3304247d9783e3..95d2a5d91c5907 100644 --- a/base/rational.jl +++ b/base/rational.jl @@ -19,6 +19,11 @@ function divgcd(x::Integer,y::Integer) div(x,g), div(y,g) end +""" + //(num, den) + +Divide two integers or rational numbers, giving a `Rational` result. +""" //(n::Integer, d::Integer ) = Rational(n,d) function //(x::Rational, y::Integer ) diff --git a/base/reducedim.jl b/base/reducedim.jl index c0599cd3680e42..189d5defbf5d78 100644 --- a/base/reducedim.jl +++ b/base/reducedim.jl @@ -277,6 +277,158 @@ reducedim(op, A::AbstractArray, region) = mapreducedim(identity, op, A, region) ##### Specific reduction functions ##### +""" + sum(A, dims) + +Sum elements of an array over the given dimensions. + +```jldoctest +julia> A = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> sum(A, 1) +1×2 Array{Int64,2}: + 4 6 + +julia> sum(A, 2) +2×1 Array{Int64,2}: + 3 + 7 +``` +""" +function sum(A, dims) end + +""" + sum!(r, A) + +Sum elements of `A` over the singleton dimensions of `r`, and write results to `r`. +""" +function sum! end + +""" + prod(A, dims) + +Multiply elements of an array over the given dimensions. + +```jldoctest +julia> A = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> prod(A, 1) +1×2 Array{Int64,2}: + 3 8 + +julia> prod(A, 2) +2×1 Array{Int64,2}: + 2 + 12 +``` +""" +function prod(A, dims) end + +""" + prod!(r, A) + +Multiply elements of `A` over the singleton dimensions of `r`, and write results to `r`. +""" +function prod! end + +""" + maximum(A, dims) + +Compute the maximum value of an array over the given dimensions. See also the +[`max(a,b)`](@ref) function to take the maximum of two or more arguments, +which can be applied elementwise to arrays via `max.(a,b)`. +""" +function maximum(A, dims) end + +""" + maximum!(r, A) + +Compute the maximum value of `A` over the singleton dimensions of `r`, and write results to `r`. +""" +function maximum! end + +""" + minimum(A, dims) + +Compute the minimum value of an array over the given dimensions. See also the +[`min(a,b)`](@ref) function to take the minimum of two or more arguments, +which can be applied elementwise to arrays via `min.(a,b)`. + +```jldoctest +julia> A = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> minimum(A, 1) +1×2 Array{Int64,2}: + 1 2 + +julia> minimum(A, 2) +2×1 Array{Int64,2}: + 1 + 3 +``` +""" +function minimum(A, dims) end + +""" + minimum!(r, A) + +Compute the minimum value of `A` over the singleton dimensions of `r`, and write results to `r`. +""" +function minimum! end + +""" + all(A, dims) + +Test whether all values along the given dimensions of an array are `true`. + +```jldoctest +julia> A = [true false; true true] +2×2 Array{Bool,2}: + true false + true true + +julia> all(A, 1) +1×2 Array{Bool,2}: + true false + +julia> all(A, 2) +2×1 Array{Bool,2}: + false + true +``` +""" +function all(A::AbstractArray, dims) end + +""" + all!(r, A) + +Test whether all values in `A` along the singleton dimensions of `r` are `true`, and write results to `r`. +""" +function all! end + +""" + any(A, dims) + +Test whether any values along the given dimensions of an array are `true`. +""" +function any(::AbstractArray,dims) end + +""" + any!(r, A) + +Test whether any values in `A` along the singleton dimensions of `r` are `true`, and write +results to `r`. +""" +function any! end for (fname, op) in [(:sum, :+), (:prod, :*), (:maximum, :scalarmax), (:minimum, :scalarmin), diff --git a/base/statistics.jl b/base/statistics.jl index e4bc2f1c462afe..7bc582aaf99baa 100644 --- a/base/statistics.jl +++ b/base/statistics.jl @@ -561,6 +561,11 @@ julia> middle(a) """ middle(a::AbstractArray) = ((v1, v2) = extrema(a); middle(v1, v2)) +""" + median!(v) + +Like [`median`](@ref), but may overwrite the input vector. +""" function median!{T}(v::AbstractVector{T}) isempty(v) && throw(ArgumentError("median of an empty array is undefined, $(repr(v))")) if T<:AbstractFloat