diff --git a/base/abstractarray.jl b/base/abstractarray.jl index fbd2ff7547b8f..6a22e6e30d818 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -858,6 +858,16 @@ end # note: the following type definitions don't mean any AbstractArray is convertible to # a data Ref. they just map the array element type to the pointer type for # convenience in cases that work. + +""" + pointer(array [, index]) + +Get the native address of an array or string element. Be careful to ensure that a Julia +reference to `a` exists as long as this pointer will be used. This function is "unsafe" like +`unsafe_convert`. + +Calling `Ref(array[, index])` is generally preferable to this function. +""" pointer(x::AbstractArray{T}) where {T} = unsafe_convert(Ptr{T}, x) function pointer(x::AbstractArray{T}, i::Integer) where T @_inline_meta diff --git a/base/array.jl b/base/array.jl index afab05652f5fa..75a2f5883f756 100644 --- a/base/array.jl +++ b/base/array.jl @@ -212,6 +212,37 @@ 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. + +```jldoctest +julia> A = zeros(2,3) +2×3 Array{Float64,2}: + 0.0 0.0 0.0 + 0.0 0.0 0.0 + +julia> fill!(A, 2.) +2×3 Array{Float64,2}: + 2.0 2.0 2.0 + 2.0 2.0 2.0 + +julia> a = [1, 1, 1]; A = fill!(Vector{Vector{Int}}(3), a); a[1] = 2; A +3-element Array{Array{Int64,1},1}: + [2, 1, 1] + [2, 1, 1] + [2, 1, 1] + +julia> x = 0; f() = (global x += 1; x); fill!(Vector{Int}(3), f()) +3-element Array{Int64,1}: + 1 + 1 + 1 +``` +""" 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 diff --git a/base/boot.jl b/base/boot.jl index 31255bea909a5..4703c2dac2d9f 100644 --- a/base/boot.jl +++ b/base/boot.jl @@ -208,6 +208,12 @@ struct DomainError <: Exception end struct OverflowError <: Exception end struct InexactError <: Exception end struct OutOfMemoryError <: Exception end + +""" + ReadOnlyMemoryError() + +An operation tried to write to memory that is read-only. +""" struct ReadOnlyMemoryError<: Exception end struct SegmentationFault <: Exception end struct StackOverflowError <: Exception end diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index 42239e9eb79e5..5926ca20051ab 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -2,66 +2,6 @@ # Base -""" - 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. - -```jldoctest -julia> A = zeros(2,3) -2×3 Array{Float64,2}: - 0.0 0.0 0.0 - 0.0 0.0 0.0 - -julia> fill!(A, 2.) -2×3 Array{Float64,2}: - 2.0 2.0 2.0 - 2.0 2.0 2.0 - -julia> a = [1, 1, 1]; A = fill!(Vector{Vector{Int}}(3), a); a[1] = 2; A -3-element Array{Array{Int64,1},1}: - [2, 1, 1] - [2, 1, 1] - [2, 1, 1] - -julia> x = 0; f() = (global x += 1; x); fill!(Vector{Int}(3), f()) -3-element Array{Int64,1}: - 1 - 1 - 1 -``` -""" -fill! - -""" - read!(stream::IO, array::Union{Array, BitArray}) - read!(filename::AbstractString, array::Union{Array, BitArray}) - -Read binary data from an I/O stream or file, filling in `array`. -""" -read! - -""" - pointer(array [, index]) - -Get the native address of an array or string element. Be careful to ensure that a Julia -reference to `a` exists as long as this pointer will be used. This function is "unsafe" like -`unsafe_convert`. - -Calling `Ref(array[, index])` is generally preferable to this function. -""" -pointer - -""" - precision(num::AbstractFloat) - -Get the precision of a floating point number, as defined by the effective number of bits in -the mantissa. -""" -precision - """ -(x) @@ -174,14 +114,6 @@ Neither `convert` nor `cconvert` should take a Julia object and turn it into a ` """ cconvert -""" - assert(cond) - -Throw an [`AssertionError`](@ref) if `cond` is `false`. -Also available as the macro `@assert expr`. -""" -assert - """ sech(x) @@ -346,13 +278,6 @@ Stacktrace: """ sizeof(::Type) -""" - ReadOnlyMemoryError() - -An operation tried to write to memory that is read-only. -""" -ReadOnlyMemoryError - """ ceil([T,] x, [digits, [base]]) diff --git a/base/error.jl b/base/error.jl index f26df61ee91d8..5f57d3e70512f 100644 --- a/base/error.jl +++ b/base/error.jl @@ -65,6 +65,12 @@ systemerror(p, b::Bool; extrainfo=nothing) = b ? throw(Main.Base.SystemError(str ## assertion functions and macros ## +""" + assert(cond) + +Throw an [`AssertionError`](@ref) if `cond` is `false`. +Also available as the macro `@assert expr`. +""" assert(x) = x ? nothing : throw(Main.Base.AssertionError()) macro assert(ex, msgs...) msg = isempty(msgs) ? ex : msgs[1] diff --git a/base/float.jl b/base/float.jl index 65836552b2b31..ac7b8321053e0 100644 --- a/base/float.jl +++ b/base/float.jl @@ -561,10 +561,17 @@ hash(x::Union{Bool,Int8,UInt8,Int16,UInt16,Int32,UInt32}, h::UInt) = hash(Int64( hash(x::Float32, h::UInt) = hash(Float64(x), h) ## precision, as defined by the effective number of bits in the mantissa ## + +""" + precision(num::AbstractFloat) + +Get the precision of a floating point number, as defined by the effective number of bits in +the mantissa. +""" +precision(::T) where {T<:AbstractFloat} = precision(T) precision(::Type{Float16}) = 11 precision(::Type{Float32}) = 24 precision(::Type{Float64}) = 53 -precision(::T) where {T<:AbstractFloat} = precision(T) """ uabs(x::Integer) diff --git a/base/io.jl b/base/io.jl index 244165b37c73d..f2ece155abe09 100644 --- a/base/io.jl +++ b/base/io.jl @@ -384,22 +384,6 @@ to return. """ read(s::IO, ::Type{T}, dims::Dims) where {T} = read!(s, Array{T}(dims)) -@noinline function read!(s::IO, a::Array{UInt8}) # mark noinline to ensure the array is gc-rooted somewhere (by the caller) - unsafe_read(s, pointer(a), sizeof(a)) - return a -end - -@noinline function read!(s::IO, a::Array{T}) where T # mark noinline to ensure the array is gc-rooted somewhere (by the caller) - if isbits(T) - unsafe_read(s, pointer(a), sizeof(a)) - else - for i in eachindex(a) - a[i] = read(s, T) - end - end - return a -end - function read(s::IO, ::Type{Char}) ch = read(s, UInt8) if ch < 0x80 @@ -419,6 +403,28 @@ function read(s::IO, ::Type{Char}) return Char(c) end +""" + read!(stream::IO, array::Union{Array, BitArray}) + read!(filename::AbstractString, array::Union{Array, BitArray}) + +Read binary data from an I/O stream or file, filling in `array`. +""" +@noinline function read!(s::IO, a::Array{T}) where T # mark noinline to ensure the array is gc-rooted somewhere (by the caller) + if isbits(T) + unsafe_read(s, pointer(a), sizeof(a)) + else + for i in eachindex(a) + a[i] = read(s, T) + end + end + return a +end + +@noinline function read!(s::IO, a::Array{UInt8}) # mark noinline to ensure the array is gc-rooted somewhere (by the caller) + unsafe_read(s, pointer(a), sizeof(a)) + return a +end + # readuntil_string is useful below since it has # an optimized method for s::IOStream readuntil_string(s::IO, delim::UInt8) = String(readuntil(s, delim))