From 96e430199b7104134e79a0daffe6c97caca84c90 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Mon, 29 May 2017 06:59:42 +0200 Subject: [PATCH] Reference all the numbers (#22107) * references for Rational * references for Complex * references for Number * references to Real * references for AbstractFloat * references for Integer * references for Signed * references for Unsigned * references to Bool * references for Float16 * references for Float32 * references for Float64 * references for Int8 * references for UInt8 * references for Int16 * references for UInt16 * references for Int32 * references for UInt32 * references for Int64 * references for UInt64 * references for Int128 * references for UInt128 * references for BigInt * references for BigFloat --- base/Enums.jl | 5 +- base/abstractarray.jl | 2 +- base/array.jl | 4 +- base/c.jl | 2 +- base/ctypes.jl | 22 +-- base/dates/accessors.jl | 17 +-- base/dates/adjusters.jl | 8 +- base/dates/conversions.jl | 4 +- base/dates/periods.jl | 2 +- base/dates/query.jl | 2 +- base/dates/rounding.jl | 4 +- base/dates/types.jl | 8 +- base/docs/basedocs.jl | 4 +- base/docs/helpdb/Base.jl | 22 +-- base/error.jl | 2 +- base/float.jl | 16 +-- base/floatfuncs.jl | 2 +- base/gmp.jl | 4 +- base/linalg/qr.jl | 4 +- base/math.jl | 19 +-- base/mpfr.jl | 18 +-- base/number.jl | 4 +- base/operators.jl | 7 +- base/promotion.jl | 4 +- base/random.jl | 17 +-- base/rational.jl | 4 +- base/reflection.jl | 4 +- base/rounding.jl | 8 +- base/show.jl | 2 +- base/socket.jl | 4 +- base/sparse/sparsematrix.jl | 4 +- base/sparse/umfpack.jl | 6 +- base/special/gamma.jl | 2 +- base/test.jl | 2 +- doc/src/devdocs/offset-arrays.md | 4 +- doc/src/devdocs/reflection.md | 2 +- doc/src/devdocs/types.md | 6 +- doc/src/manual/arrays.md | 4 +- doc/src/manual/calling-c-and-fortran-code.md | 8 +- doc/src/manual/constructors.md | 17 +-- doc/src/manual/control-flow.md | 4 +- doc/src/manual/conversion-and-promotion.md | 31 ++-- doc/src/manual/dates.md | 17 +-- doc/src/manual/documentation.md | 4 +- doc/src/manual/embedding.md | 12 +- doc/src/manual/environment-variables.md | 2 +- doc/src/manual/faq.md | 9 +- .../integers-and-floating-point-numbers.md | 52 +++---- doc/src/manual/mathematical-operations.md | 2 +- doc/src/manual/metaprogramming.md | 2 +- doc/src/manual/methods.md | 28 ++-- doc/src/manual/noteworthy-differences.md | 12 +- doc/src/manual/performance-tips.md | 22 +-- doc/src/manual/strings.md | 8 +- doc/src/manual/style-guide.md | 13 +- doc/src/manual/types.md | 136 ++++++++++-------- doc/src/stdlib/linalg.md | 8 +- doc/src/stdlib/numbers.md | 13 +- 58 files changed, 343 insertions(+), 312 deletions(-) diff --git a/base/Enums.jl b/base/Enums.jl index 9e8a144da1e58..13976a72d8e5f 100644 --- a/base/Enums.jl +++ b/base/Enums.jl @@ -45,8 +45,9 @@ julia> f(apple) "I'm a Fruit with value: 1" ``` -`BaseType`, which defaults to `Int32`, must be a primitive subtype of Integer. Member values can be converted between -the enum type and `BaseType`. `read` and `write` perform these conversions automatically. +`BaseType`, which defaults to [`Int32`](@ref), must be a primitive subtype of `Integer`. +Member values can be converted between the enum type and `BaseType`. `read` and `write` +perform these conversions automatically. """ macro enum(T,syms...) if isempty(syms) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 440372def4d58..af3bfe47825dd 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -503,7 +503,7 @@ julia> similar(trues(10,10), 2) false ``` -Since `BitArray`s can only store elements of type `Bool`, however, if you request a +Since `BitArray`s can only store elements of type [`Bool`](@ref), however, if you request a different element type it will create a regular `Array` instead: ```julia-repl diff --git a/base/array.jl b/base/array.jl index a4ae57bd971ae..80c04a30903dc 100644 --- a/base/array.jl +++ b/base/array.jl @@ -266,7 +266,7 @@ end eye([T::Type=Float64,] m::Integer, n::Integer) `m`-by-`n` identity matrix. -The default element type is `Float64`. +The default element type is [`Float64`](@ref). """ function eye(::Type{T}, m::Integer, n::Integer) where T a = zeros(T,m,n) @@ -287,7 +287,7 @@ eye(::Type{T}, n::Integer) where {T} = eye(T, n, n) eye([T::Type=Float64,] n::Integer) `n`-by-`n` identity matrix. -The default element type is `Float64`. +The default element type is [`Float64`](@ref). """ eye(n::Integer) = eye(Float64, n) diff --git a/base/c.jl b/base/c.jl index 410bb1e2f153e..80c58a4640614 100644 --- a/base/c.jl +++ b/base/c.jl @@ -45,7 +45,7 @@ Culong """ Cwchar_t -Equivalent to the native `wchar_t` c-type (`Int32`). +Equivalent to the native `wchar_t` c-type ([`Int32`](@ref)). """ Cwchar_t diff --git a/base/ctypes.jl b/base/ctypes.jl index 387fdd9d8c7dd..26640ed82bef5 100644 --- a/base/ctypes.jl +++ b/base/ctypes.jl @@ -6,7 +6,7 @@ """ Cuchar -Equivalent to the native `unsigned char` c-type (`UInt8`). +Equivalent to the native `unsigned char` c-type ([`UInt8`](@ref)). """ const Cuchar = UInt8 @@ -14,7 +14,7 @@ const Cuchar = UInt8 """ Cshort -Equivalent to the native `signed short` c-type (`Int16`). +Equivalent to the native `signed short` c-type ([`Int16`](@ref)). """ const Cshort = Int16 @@ -22,7 +22,7 @@ const Cshort = Int16 """ Cushort -Equivalent to the native `unsigned short` c-type (`UInt16`). +Equivalent to the native `unsigned short` c-type ([`UInt16`](@ref)). """ const Cushort = UInt16 @@ -30,7 +30,7 @@ const Cushort = UInt16 """ Cint -Equivalent to the native `signed int` c-type (`Int32`). +Equivalent to the native `signed int` c-type ([`Int32`](@ref)). """ const Cint = Int32 @@ -38,7 +38,7 @@ const Cint = Int32 """ Cuint -Equivalent to the native `unsigned int` c-type (`UInt32`). +Equivalent to the native `unsigned int` c-type ([`UInt32`](@ref)). """ const Cuint = UInt32 @@ -70,7 +70,7 @@ const Cssize_t = Int """ Cintmax_t -Equivalent to the native `intmax_t` c-type (`Int64`). +Equivalent to the native `intmax_t` c-type ([`Int64`](@ref)). """ const Cintmax_t = Int64 @@ -78,7 +78,7 @@ const Cintmax_t = Int64 """ Cuintmax_t -Equivalent to the native `uintmax_t` c-type (`UInt64`). +Equivalent to the native `uintmax_t` c-type ([`UInt64`](@ref)). """ const Cuintmax_t = UInt64 @@ -86,7 +86,7 @@ const Cuintmax_t = UInt64 """ Clonglong -Equivalent to the native `signed long long` c-type (`Int64`). +Equivalent to the native `signed long long` c-type ([`Int64`](@ref)). """ const Clonglong = Int64 @@ -94,7 +94,7 @@ const Clonglong = Int64 """ Culonglong -Equivalent to the native `unsigned long long` c-type (`UInt64`). +Equivalent to the native `unsigned long long` c-type ([`UInt64`](@ref)). """ const Culonglong = UInt64 @@ -102,7 +102,7 @@ const Culonglong = UInt64 """ Cfloat -Equivalent to the native `float` c-type (`Float32`). +Equivalent to the native `float` c-type ([`Float32`](@ref)). """ const Cfloat = Float32 @@ -110,6 +110,6 @@ const Cfloat = Float32 """ Cdouble -Equivalent to the native `double` c-type (`Float64`). +Equivalent to the native `double` c-type ([`Float64`](@ref)). """ const Cdouble = Float64 diff --git a/base/dates/accessors.jl b/base/dates/accessors.jl index d6ca886643001..27c41d118dfc8 100644 --- a/base/dates/accessors.jl +++ b/base/dates/accessors.jl @@ -74,7 +74,7 @@ for func in (:year, :month) @doc """ $($name)(dt::TimeType) -> Int64 - The $($name) of a `Date` or `DateTime` as an `Int64`. + The $($name) of a `Date` or `DateTime` as an [`Int64`](@ref). """ $func(dt::TimeType) end end @@ -83,9 +83,10 @@ end week(dt::TimeType) -> Int64 Return the [ISO week date](https://en.wikipedia.org/wiki/ISO_week_date) of a `Date` or -`DateTime` as an `Int64`. Note that the first week of a year is the week that contains the -first Thursday of the year which can result in dates prior to January 4th being in the last -week of the previous year. For example `week(Date(2005,1,1))` is the 53rd week of 2004. +`DateTime` as an [`Int64`](@ref). Note that the first week of a year is the week that +contains the first Thursday of the year which can result in dates prior to January 4th +being in the last week of the previous year. For example `week(Date(2005,1,1))` is the 53rd +week of 2004. """ week(dt::TimeType) @@ -95,7 +96,7 @@ for func in (:day, :dayofmonth) @doc """ $($name)(dt::TimeType) -> Int64 - The day of month of a `Date` or `DateTime` as an `Int64`. + The day of month of a `Date` or `DateTime` as an [`Int64`](@ref). """ $func(dt::TimeType) end end @@ -103,7 +104,7 @@ end """ hour(dt::DateTime) -> Int64 -The hour of day of a `DateTime` as an `Int64`. +The hour of day of a `DateTime` as an [`Int64`](@ref). """ hour(dt::DateTime) @@ -113,7 +114,7 @@ for func in (:minute, :second, :millisecond) @doc """ $($name)(dt::DateTime) -> Int64 - The $($name) of a `DateTime` as an `Int64`. + The $($name) of a `DateTime` as an [`Int64`](@ref). """ $func(dt::DateTime) end end @@ -137,7 +138,7 @@ for func in (:hour, :minute, :second, :millisecond, :microsecond, :nanosecond) @doc """ $($name)(t::Time) -> Int64 - The $($name) of a `Time` as an `Int64`. + The $($name) of a `Time` as an [`Int64`](@ref). """ $func(t::Time) end end diff --git a/base/dates/adjusters.jl b/base/dates/adjusters.jl index 357faec442a27..b93236e95bd9e 100644 --- a/base/dates/adjusters.jl +++ b/base/dates/adjusters.jl @@ -253,8 +253,8 @@ tonext(dt::TimeType, dow::Int; same::Bool=false) = adjust(ISDAYOFWEEK[dow], same tonext(func::Function, dt::TimeType; step=Day(1), 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`. +returns `true`. `func` must take a single `TimeType` argument and return a [`Bool`](@ref). +`same` allows `dt` to be considered in satisfying `func`. """ function tonext(func::Function, dt::TimeType; step::Period=Day(1), negate=nothing, limit::Int=10000, same::Bool=false) func = deprecate_negate(:tonext, func, "func,dt", negate) @@ -274,8 +274,8 @@ toprev(dt::TimeType, dow::Int; same::Bool=false) = adjust(ISDAYOFWEEK[dow], same toprev(func::Function, dt::TimeType; step=Day(-1), 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`. +returns `true`. `func` must take a single `TimeType` argument and return a [`Bool`](@ref). +`same` allows `dt` to be considered in satisfying `func`. """ function toprev(func::Function, dt::TimeType; step::Period=Day(-1), negate=nothing, limit::Int=10000, same::Bool=false) func = deprecate_negate(:toprev, func, "func,dt", negate) diff --git a/base/dates/conversions.jl b/base/dates/conversions.jl index 9016c5600d149..853f20b01cc77 100644 --- a/base/dates/conversions.jl +++ b/base/dates/conversions.jl @@ -53,7 +53,7 @@ end datetime2unix(dt::DateTime) -> Float64 Takes the given `DateTime` and returns the number of seconds -since the unix epoch `1970-01-01T00:00:00` as a `Float64`. +since the unix epoch `1970-01-01T00:00:00` as a [`Float64`](@ref). """ datetime2unix(dt::DateTime) = (value(dt) - UNIXEPOCH) / 1000.0 @@ -116,6 +116,6 @@ end datetime2julian(dt::DateTime) -> Float64 Takes the given `DateTime` and returns the number of Julian calendar days since the julian -epoch `-4713-11-24T12:00:00` as a `Float64`. +epoch `-4713-11-24T12:00:00` as a [`Float64`](@ref). """ datetime2julian(dt::DateTime) = (value(dt) - JULIANEPOCH) / 86400000.0 diff --git a/base/dates/periods.jl b/base/dates/periods.jl index 7fbba3d59f86f..27eafa5774ea1 100644 --- a/base/dates/periods.jl +++ b/base/dates/periods.jl @@ -33,7 +33,7 @@ for period in (:Year, :Month, :Week, :Day, :Hour, :Minute, :Second, :Millisecond $($period_str)(v) Construct a `$($period_str)` object with the given `v` value. Input must be - losslessly convertible to an `Int64`. + losslessly convertible to an [`Int64`](@ref). """ $period(v) end end diff --git a/base/dates/query.jl b/base/dates/query.jl index effdd68a1bbdf..2e632e239566b 100644 --- a/base/dates/query.jl +++ b/base/dates/query.jl @@ -101,7 +101,7 @@ dayofyear(y, m, d) = MONTHDAYS[m] + d + (m > 2 && isleapyear(y)) """ dayofweek(dt::TimeType) -> Int64 -Returns the day of the week as an `Int64` with `1 = Monday, 2 = Tuesday, etc.`. +Returns the day of the week as an [`Int64`](@ref) with `1 = Monday, 2 = Tuesday, etc.`. """ dayofweek(dt::TimeType) = dayofweek(days(dt)) diff --git a/base/dates/rounding.jl b/base/dates/rounding.jl index b1714fff075ef..8adbf80902b57 100644 --- a/base/dates/rounding.jl +++ b/base/dates/rounding.jl @@ -27,7 +27,7 @@ epochms2datetime(i) = DateTime(UTM(DATETIMEEPOCH + Int64(i))) date2epochdays(dt::Date) -> Int64 Takes the given `Date` and returns the number of days since the rounding epoch -(`0000-01-01T00:00:00`) as an `Int64`. +(`0000-01-01T00:00:00`) as an [`Int64`](@ref). """ date2epochdays(dt::Date) = value(dt) - DATEEPOCH @@ -35,7 +35,7 @@ date2epochdays(dt::Date) = value(dt) - DATEEPOCH datetime2epochms(dt::DateTime) -> Int64 Takes the given `DateTime` and returns the number of milliseconds since the rounding epoch -(`0000-01-01T00:00:00`) as an `Int64`. +(`0000-01-01T00:00:00`) as an [`Int64`](@ref). """ datetime2epochms(dt::DateTime) = value(dt) - DATETIMEEPOCH diff --git a/base/dates/types.jl b/base/dates/types.jl index 87871c9ee9f5a..12e3e62bf25f2 100644 --- a/base/dates/types.jl +++ b/base/dates/types.jl @@ -47,7 +47,7 @@ end Nanosecond(v) Construct a `Period` type with the given `v` value. Input must be losslessly convertible -to an `Int64`. +to an [`Int64`](@ref). """ Period(v) @@ -173,7 +173,7 @@ argerror() = Nullable{ArgumentError}() """ DateTime(y, [m, d, h, mi, s, ms]) -> DateTime -Construct a `DateTime` type by parts. Arguments must be convertible to `Int64`. +Construct a `DateTime` type by parts. Arguments must be convertible to [`Int64`](@ref). """ function DateTime(y::Int64, m::Int64=1, d::Int64=1, h::Int64=0, mi::Int64=0, s::Int64=0, ms::Int64=0) @@ -197,7 +197,7 @@ end """ Date(y, [m, d]) -> Date -Construct a `Date` type by parts. Arguments must be convertible to `Int64`. +Construct a `Date` type by parts. Arguments must be convertible to [`Int64`](@ref). """ function Date(y::Int64, m::Int64=1, d::Int64=1) err = validargs(Date, y, m, d) @@ -214,7 +214,7 @@ end """ Time(h, [mi, s, ms, us, ns]) -> Time -Construct a `Time` type by parts. Arguments must be convertible to `Int64`. +Construct a `Time` type by parts. Arguments must be convertible to [`Int64`](@ref). """ function Time(h::Int64, mi::Int64=0, s::Int64=0, ms::Int64=0, us::Int64=0, ns::Int64=0) err = validargs(Time, h, mi, s, ms, us, ns) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index 4221f061bfcc3..ece074d231a1a 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -81,7 +81,7 @@ Julia’s type system more than just a collection of object implementations. For abstract type Number end abstract type Real <: Number end -`Number` has no supertype, whereas `Real` is an abstract subtype of `Number`. +[`Number`](@ref) has no supertype, whereas [`Real`](@ref) is an abstract subtype of `Number`. """ kw"abstract type" @@ -124,7 +124,7 @@ primitive type declarations: The number after the name indicates how many bits of storage the type requires. Currently, only sizes that are multiples of 8 bits are supported. -The `Bool` declaration shows how a primitive type can be optionally +The [`Bool`](@ref) declaration shows how a primitive type can be optionally declared to be a subtype of some supertype. """ kw"primitive type" diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index d0e408c4cff3e..a3f2530e4fef3 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -243,7 +243,7 @@ determines how the bytes of the array are interpreted. Note that the file must b 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. +`dims` is a tuple or single [`Integer`](@ref) 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 @@ -1061,7 +1061,7 @@ For arrays, this constructs an array with the same binary data as the given array, but with the specified element type. For example, `reinterpret(Float32, UInt32(7))` interprets the 4 bytes corresponding to `UInt32(7)` as a -`Float32`. +[`Float32`](@ref). !!! warning @@ -1147,8 +1147,8 @@ searchsortedfirst """ big(x) -Convert a number to a maximum precision representation (typically `BigInt` or `BigFloat`). -See [`BigFloat`](@ref) for information about some pitfalls with floating-point numbers. +Convert a number to a maximum precision representation (typically [`BigInt`](@ref) or +`BigFloat`). See [`BigFloat`](@ref) for information about some pitfalls with floating-point numbers. """ big @@ -1434,10 +1434,10 @@ StackOverflowError """ ==(x, y) -Generic equality operator, giving a single `Bool` result. Falls back to `===`. Should be -implemented for all types with a notion of equality, based on the abstract value that an -instance represents. For example, all numeric types are compared by numeric value, ignoring -type. Strings are compared as sequences of characters, ignoring encoding. +Generic equality operator, giving a single [`Bool`](@ref) result. Falls back to `===`. +Should be implemented for all types with a notion of equality, based on the abstract value +that an instance represents. For example, all numeric types are compared by numeric value, +ignoring type. Strings are compared as sequences of characters, ignoring encoding. Follows IEEE semantics for floating-point numbers. @@ -1934,7 +1934,7 @@ done Convert `x` to a value of type `T`. -If `T` is an `Integer` type, an [`InexactError`](@ref) will be raised if `x` +If `T` is an [`Integer`](@ref) type, an [`InexactError`](@ref) will be raised if `x` is not representable by `T`, for example if `x` is not integer-valued, or is outside the range supported by `T`. @@ -1948,7 +1948,7 @@ Stacktrace: [1] convert(::Type{Int64}, ::Float64) at ./float.jl:680 ``` -If `T` is a `AbstractFloat` or `Rational` type, +If `T` is a [`AbstractFloat`](@ref) or [`Rational`](@ref) type, then it will return the closest value to `x` representable by `T`. ```jldoctest @@ -2160,7 +2160,7 @@ isvalid(value) isvalid(T, value) -> Bool Returns `true` if the given value is valid for that type. Types currently can -be either `Char` or `String`. Values for `Char` can be of type `Char` or `UInt32`. +be either `Char` or `String`. Values for `Char` can be of type `Char` or [`UInt32`](@ref). Values for `String` can be of that type, or `Vector{UInt8}`. """ isvalid(T,value) diff --git a/base/error.jl b/base/error.jl index 108f5c83716d4..f26df61ee91d8 100644 --- a/base/error.jl +++ b/base/error.jl @@ -98,7 +98,7 @@ end """ ExponentialBackOff(; n=1, first_delay=0.05, max_delay=10.0, factor=5.0, jitter=0.1) -A `Float64` iterator of length `n` whose elements exponentially increase at a +A [`Float64`](@ref) iterator of length `n` whose elements exponentially increase at a rate in the interval `factor` * (1 ± `jitter`). The first element is `first_delay` and all elements are clamped to `max_delay`. """ diff --git a/base/float.jl b/base/float.jl index 68d0d5138f0fe..65836552b2b31 100644 --- a/base/float.jl +++ b/base/float.jl @@ -5,25 +5,25 @@ """ Inf16 -Positive infinity of type `Float16`. +Positive infinity of type [`Float16`](@ref). """ const Inf16 = bitcast(Float16, 0x7c00) """ NaN16 -A not-a-number value of type `Float16`. +A not-a-number value of type [`Float16`](@ref). """ const NaN16 = bitcast(Float16, 0x7e00) """ Inf32 -Positive infinity of type `Float32`. +Positive infinity of type [`Float32`](@ref). """ const Inf32 = bitcast(Float32, 0x7f800000) """ NaN32 -A not-a-number value of type `Float32`. +A not-a-number value of type [`Float32`](@ref). """ const NaN32 = bitcast(Float32, 0x7fc00000) const Inf64 = bitcast(Float64, 0x7ff0000000000000) @@ -32,13 +32,13 @@ const NaN64 = bitcast(Float64, 0x7ff8000000000000) """ Inf -Positive infinity of type `Float64`. +Positive infinity of type [`Float64`](@ref). """ const Inf = Inf64 """ NaN -A not-a-number value of type `Float64`. +A not-a-number value of type [`Float64`](@ref). """ const NaN = NaN64 @@ -750,8 +750,8 @@ of `x` is different, then the larger of the two is taken, that is eps(x) == max(x-prevfloat(x), nextfloat(x)-x) The exceptions to this rule are the smallest and largest finite values -(e.g. `nextfloat(-Inf)` and `prevfloat(Inf)` for `Float64`), which round to the smaller of -the values. +(e.g. `nextfloat(-Inf)` and `prevfloat(Inf)` for [`Float64`](@ref)), which round to the +smaller of the values. The rationale for this behavior is that `eps` bounds the floating point rounding error. Under the default `RoundNearest` rounding mode, if ``y`` is a real number and ``x`` diff --git a/base/floatfuncs.jl b/base/floatfuncs.jl index e75486a46257c..a5973c7d99986 100644 --- a/base/floatfuncs.jl +++ b/base/floatfuncs.jl @@ -78,7 +78,7 @@ julia> round(pi, 3, 2) !!! note Rounding to specified digits in bases other than 2 can be inexact when - operating on binary floating point numbers. For example, the `Float64` + operating on binary floating point numbers. For example, the [`Float64`](@ref) value represented by `1.15` is actually *less* than 1.15, yet will be rounded to 1.2. diff --git a/base/gmp.jl b/base/gmp.jl index b78132e4b4856..07926f9865042 100644 --- a/base/gmp.jl +++ b/base/gmp.jl @@ -58,8 +58,8 @@ end BigInt(x) Create an arbitrary precision integer. `x` may be an `Int` (or anything that can be -converted to an `Int`). The usual mathematical operators are defined for this type, and -results are promoted to a `BigInt`. +converted to an `Int`). The usual mathematical operators are defined for this type, and +results are promoted to a [`BigInt`](@ref). Instances can be constructed from strings via [`parse`](@ref), or using the `big` string literal. diff --git a/base/linalg/qr.jl b/base/linalg/qr.jl index 2d6d723adefe1..13aa153575f1e 100644 --- a/base/linalg/qr.jl +++ b/base/linalg/qr.jl @@ -226,8 +226,8 @@ The returned object `F` stores the factorization in a packed format: - if `pivot == Val{true}` then `F` is a [`QRPivoted`](@ref) object, - - otherwise if the element type of `A` is a BLAS type (`Float32`, `Float64`, `Complex64` - or `Complex128`), then `F` is a [`QRCompactWY`](@ref) object, + - otherwise if the element type of `A` is a BLAS type ([`Float32`](@ref), [`Float64`](@ref), + `Complex64` or `Complex128`), then `F` is a [`QRCompactWY`](@ref) object, - otherwise `F` is a [`QR`](@ref) object. diff --git a/base/math.jl b/base/math.jl index 8861d2176e165..1956adf268260 100644 --- a/base/math.jl +++ b/base/math.jl @@ -161,7 +161,8 @@ log(b::T, x::T) where {T<:Number} = log(x)/log(b) """ log(b,x) -Compute the base `b` logarithm of `x`. Throws [`DomainError`](@ref) for negative `Real` arguments. +Compute the base `b` logarithm of `x`. Throws [`DomainError`](@ref) for negative +[`Real`](@ref) arguments. ```jldoctest julia> log(4,8) @@ -351,8 +352,8 @@ atanh(x) """ log(x) -Compute the natural logarithm of `x`. Throws [`DomainError`](@ref) for negative `Real` arguments. -Use complex negative arguments to obtain complex results. +Compute the natural logarithm of `x`. Throws [`DomainError`](@ref) for negative +[`Real`](@ref) 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. @@ -362,7 +363,8 @@ log(x) """ log2(x) -Compute the logarithm of `x` to base 2. Throws [`DomainError`](@ref) for negative `Real` arguments. +Compute the logarithm of `x` to base 2. Throws [`DomainError`](@ref) for negative +[`Real`](@ref) arguments. # Example ```jldoctest @@ -379,7 +381,7 @@ log2(x) log10(x) Compute the logarithm of `x` to base 10. -Throws [`DomainError`](@ref) for negative `Real` arguments. +Throws [`DomainError`](@ref) for negative [`Real`](@ref) arguments. # Example ```jldoctest @@ -395,7 +397,8 @@ log10(x) """ log1p(x) -Accurate natural logarithm of `1+x`. Throws [`DomainError`](@ref) for `Real` arguments less than -1. +Accurate natural logarithm of `1+x`. Throws [`DomainError`](@ref) for [`Real`](@ref) +arguments less than -1. There is an experimental variant in the `Base.Math.JuliaLibm` module, which is typically faster and more accurate. @@ -438,8 +441,8 @@ sqrt(x::Float32) = sqrt_llvm(x) """ sqrt(x) -Return ``\\sqrt{x}``. Throws [`DomainError`](@ref) for negative `Real` arguments. Use complex -negative arguments instead. The prefix operator `√` is equivalent to `sqrt`. +Return ``\\sqrt{x}``. Throws [`DomainError`](@ref) for negative [`Real`](@ref) arguments. +Use complex negative arguments instead. The prefix operator `√` is equivalent to `sqrt`. """ sqrt(x::Real) = sqrt(float(x)) diff --git a/base/mpfr.jl b/base/mpfr.jl index 4f04480babb69..40e0fd59cf0ac 100644 --- a/base/mpfr.jl +++ b/base/mpfr.jl @@ -70,9 +70,9 @@ end """ BigFloat(x) -Create an arbitrary precision floating point number. `x` may be an `Integer`, a `Float64` or -a `BigInt`. The usual mathematical operators are defined for this type, and results are -promoted to a `BigFloat`. +Create an arbitrary precision floating point number. `x` may be an [`Integer`](@ref), a +[`Float64`](@ref) or a [`BigInt`](@ref). The usual mathematical operators are defined for +this type, and results are promoted to a [`BigFloat`](@ref). Note that because decimal literals are converted to floating point numbers when parsed, `BigFloat(2.1)` may not yield what you expect. You may instead prefer to initialize @@ -133,7 +133,7 @@ float(::Type{BigInt}) = BigFloat """ BigFloat(x, prec::Int) -Create a representation of `x` as a `BigFloat` with precision `prec`. +Create a representation of `x` as a [`BigFloat`](@ref) with precision `prec`. """ function BigFloat(x, prec::Int) setprecision(BigFloat, prec) do @@ -144,7 +144,8 @@ end """ BigFloat(x, prec::Int, rounding::RoundingMode) -Create a representation of `x` as a `BigFloat` with precision `prec` and rounding mode `rounding`. +Create a representation of `x` as a [`BigFloat`](@ref) with precision `prec` and +rounding mode `rounding`. """ function BigFloat(x, prec::Int, rounding::RoundingMode) setrounding(BigFloat, rounding) do @@ -155,7 +156,8 @@ end """ BigFloat(x, rounding::RoundingMode) -Create a representation of `x` as a `BigFloat` with the current global precision and rounding mode `rounding`. +Create a representation of `x` as a [`BigFloat`](@ref) with the current global precision +and rounding mode `rounding`. """ function BigFloat(x::Union{Integer, AbstractFloat, String}, rounding::RoundingMode) BigFloat(x, precision(BigFloat), rounding) @@ -164,7 +166,7 @@ end """ BigFloat(x::String) -Create a representation of the string `x` as a `BigFloat`. +Create a representation of the string `x` as a [`BigFloat`](@ref). """ BigFloat(x::String) = parse(BigFloat, x) @@ -728,7 +730,7 @@ end """ precision(BigFloat) -Get the precision (in bits) currently used for `BigFloat` arithmetic. +Get the precision (in bits) currently used for [`BigFloat`](@ref) arithmetic. """ precision(::Type{BigFloat}) = DEFAULT_PRECISION[end] # precision of the type BigFloat itself diff --git a/base/number.jl b/base/number.jl index 704bf42fc0070..d34f3ba10a438 100644 --- a/base/number.jl +++ b/base/number.jl @@ -190,8 +190,8 @@ _default_type(::Type{Number}) = Int """ factorial(n) -Factorial of `n`. If `n` is an `Integer`, the factorial is computed as an -integer (promoted to at least 64 bits). Note that this may overflow if `n` is not small, +Factorial of `n`. If `n` is an [`Integer`](@ref), 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 [`gamma(n+1)`](@ref). diff --git a/base/operators.jl b/base/operators.jl index bbec5c09e28f3..47ac4b25de3ea 100644 --- a/base/operators.jl +++ b/base/operators.jl @@ -532,8 +532,8 @@ Unsigned right bit shift operator, `x >>> n`. For `n >= 0`, the result is `x` shifted right by `n` bits, where `n >= 0`, filling with `0`s. For `n < 0`, this is equivalent to `x << -n`. -For `Unsigned` integer types, this is equivalent to [`>>`](@ref). For -`Signed` integer types, this is equivalent to `signed(unsigned(x) >> n)`. +For [`Unsigned`](@ref) integer types, this is equivalent to [`>>`](@ref). For +[`Signed`](@ref) integer types, this is equivalent to `signed(unsigned(x) >> n)`. ```jldoctest julia> Int8(-14) >>> 2 @@ -545,7 +545,8 @@ julia> bits(Int8(-14)) julia> bits(Int8(60)) "00111100" ``` -`BigInt`s are treated as if having infinite size, so no filling is required and this + +[`BigInt`](@ref)s are treated as if having infinite size, so no filling is required and this is equivalent to [`>>`](@ref). See also [`>>`](@ref), [`<<`](@ref). diff --git a/base/promotion.jl b/base/promotion.jl index 4fbe3f7068a2c..5c55b3d1e34d3 100644 --- a/base/promotion.jl +++ b/base/promotion.jl @@ -137,8 +137,8 @@ promote_type(::Type{Bottom}, ::Type{T}) where {T} = (@_pure_meta; T) 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. +[`Float64`](@ref) even though strictly, not all [`Int64`](@ref) values can be represented +exactly as `Float64` values. ```jldoctest julia> promote_type(Int64, Float64) diff --git a/base/random.jl b/base/random.jl index 3697302a05153..847c61e2f9a1f 100644 --- a/base/random.jl +++ b/base/random.jl @@ -221,8 +221,8 @@ end Reseed the random number generator. If a `seed` is provided, the RNG will give a reproducible sequence of numbers, otherwise Julia will get entropy from the system. For -`MersenneTwister`, the `seed` may be a non-negative integer or a vector of `UInt32` integers. -`RandomDevice` does not support seeding. +`MersenneTwister`, the `seed` may be a non-negative integer or a vector of [`UInt32`](@ref) +integers. `RandomDevice` does not support seeding. """ srand(r::MersenneTwister) = srand(r, make_seed()) srand(r::MersenneTwister, n::Integer) = srand(r, make_seed(n)) @@ -258,9 +258,10 @@ Pick a random element or array of random elements from the set of values specifi * an indexable collection (for example `1:n` or `['x','y','z']`), or * a type: the set of values to pick from is then equivalent to `typemin(S):typemax(S)` for - integers (this is not applicable to `BigInt`), and to ``[0, 1)`` for floating point numbers; + integers (this is not applicable to [`BigInt`](@ref)), and to ``[0, 1)`` for floating + point numbers; -`S` defaults to `Float64`. +`S` defaults to [`Float64`](@ref). """ @inline rand() = rand(GLOBAL_RNG, CloseOpen) @inline rand(T::Type) = rand(GLOBAL_RNG, T) @@ -1181,9 +1182,9 @@ const ziggurat_exp_r = 7.6971174701310497140446280481 Generate a normally-distributed random number of type `T` with mean 0 and standard deviation 1. Optionally generate an array of normally-distributed random numbers. The `Base` module currently provides an implementation for the types -`Float16`, `Float32`, and `Float64` (the default), and their `Complex` counterparts. -When the type argument is complex, the values are drawn from the circularly symmetric -complex normal distribution. +[`Float16`](@ref), [`Float32`](@ref), and [`Float64`](@ref) (the default), and their +[`Complex`](@ref) counterparts. When the type argument is complex, the values are drawn +from the circularly symmetric complex normal distribution. """ @inline function randn(rng::AbstractRNG=GLOBAL_RNG) @inbounds begin @@ -1217,7 +1218,7 @@ end Generate a random number of type `T` according to the exponential distribution with scale 1. Optionally generate an array of such random numbers. The `Base` module currently provides an implementation for the types -`Float16`, `Float32`, and `Float64` (the default). +[`Float16`](@ref), [`Float32`](@ref), and [`Float64`](@ref) (the default). """ @inline function randexp(rng::AbstractRNG=GLOBAL_RNG) @inbounds begin diff --git a/base/rational.jl b/base/rational.jl index 1fe97049be83f..b3f901300399e 100644 --- a/base/rational.jl +++ b/base/rational.jl @@ -27,7 +27,7 @@ end """ //(num, den) -Divide two integers or rational numbers, giving a `Rational` result. +Divide two integers or rational numbers, giving a [`Rational`](@ref) result. ```jldoctest julia> 3 // 5 @@ -109,7 +109,7 @@ widen(::Type{Rational{T}}) where {T} = Rational{widen(T)} """ rationalize([T<:Integer=Int,] x; tol::Real=eps(x)) -Approximate floating point number `x` as a `Rational` number with components +Approximate floating point number `x` as a [`Rational`](@ref) number with components of the given integer type. The result will differ from `x` by no more than `tol`. If `T` is not provided, it defaults to `Int`. diff --git a/base/reflection.jl b/base/reflection.jl index 58d9b67e19177..eb8e279e11977 100644 --- a/base/reflection.jl +++ b/base/reflection.jl @@ -219,8 +219,8 @@ isstructtype(x) = (@_pure_meta; false) isbits(T) Return `true` if `T` is a "plain data" type, meaning it is immutable and contains no -references to other values. Typical examples are numeric types such as `UInt8`, `Float64`, -and `Complex{Float64}`. +references to other values. Typical examples are numeric types such as [`UInt8`](@ref), +[`Float64`](@ref), and [`Complex{Float64}`](@ref). ```jldoctest julia> isbits(Complex{Float64}) diff --git a/base/rounding.jl b/base/rounding.jl index 67f71d9dda57d..bcb9b6328ac15 100644 --- a/base/rounding.jl +++ b/base/rounding.jl @@ -37,7 +37,7 @@ Currently supported rounding modes are: - [`RoundNearestTiesAway`](@ref) - [`RoundNearestTiesUp`](@ref) - [`RoundToZero`](@ref) -- `RoundFromZero` (`BigFloat` only) +- `RoundFromZero` ([`BigFloat`](@ref) only) - [`RoundUp`](@ref) - [`RoundDown`](@ref) """ @@ -118,9 +118,9 @@ arithmetic functions ([`+`](@ref), [`-`](@ref), [`*`](@ref), functions may give incorrect or invalid values when using rounding modes other than the default `RoundNearest`. -Note that this may affect other types, for instance changing the rounding mode of `Float64` -will change the rounding mode of `Float32`. See [`RoundingMode`](@ref) for -available modes. +Note that this may affect other types, for instance changing the rounding mode of +[`Float64`](@ref) will change the rounding mode of [`Float32`](@ref). +See [`RoundingMode`](@ref) for available modes. !!! warning diff --git a/base/show.jl b/base/show.jl index f21483c699771..cdf7450f5713f 100644 --- a/base/show.jl +++ b/base/show.jl @@ -1570,7 +1570,7 @@ end summary(x) Return a string giving a brief description of a value. By default returns -`string(typeof(x))`, e.g. `Int64`. +`string(typeof(x))`, e.g. [`Int64`](@ref). For arrays, returns a string of size and type info, e.g. `10-element Array{Int64,1}`. diff --git a/base/socket.jl b/base/socket.jl index ae4e055c91325..108624be54917 100644 --- a/base/socket.jl +++ b/base/socket.jl @@ -24,7 +24,7 @@ end """ IPv4(host::Integer) -> IPv4 -Returns an IPv4 object from ip address `host` formatted as an `Integer`. +Returns an IPv4 object from ip address `host` formatted as an [`Integer`](@ref). ```jldoctest julia> IPv4(3223256218) @@ -76,7 +76,7 @@ end """ IPv6(host::Integer) -> IPv6 -Returns an IPv6 object from ip address `host` formatted as an `Integer`. +Returns an IPv6 object from ip address `host` formatted as an [`Integer`](@ref). ```jldoctest julia> IPv6(3223256218) diff --git a/base/sparse/sparsematrix.jl b/base/sparse/sparsematrix.jl index 58e363a2e299d..f3986e6b43b06 100644 --- a/base/sparse/sparsematrix.jl +++ b/base/sparse/sparsematrix.jl @@ -1357,7 +1357,7 @@ spones(S::SparseMatrixCSC{T}) where {T} = Create a sparse vector of length `m` or sparse matrix of size `m x n`. This sparse array will not contain any nonzero values. No storage will be allocated -for nonzero values during construction. The type defaults to `Float64` if not +for nonzero values during construction. The type defaults to [`Float64`](@ref) if not specified. ```jldoctest @@ -1411,7 +1411,7 @@ eye(S::SparseMatrixCSC) = speye(S) speye([type,]m[,n]) Create a sparse identity matrix of size `m x m`. When `n` is supplied, -create a sparse identity matrix of size `m x n`. The type defaults to `Float64` +create a sparse identity matrix of size `m x n`. The type defaults to [`Float64`](@ref) if not specified. `sparse(I, m, n)` is equivalent to `speye(Int, m, n)`, and diff --git a/base/sparse/umfpack.jl b/base/sparse/umfpack.jl index 5e44206760f0f..edb88f80304de 100644 --- a/base/sparse/umfpack.jl +++ b/base/sparse/umfpack.jl @@ -107,8 +107,8 @@ end Compute the LU factorization of a sparse matrix `A`. For sparse `A` with real or complex element type, the return type of `F` is -`UmfpackLU{Tv, Ti}`, with `Tv` = `Float64` or `Complex128` respectively and -`Ti` is an integer type (`Int32` or `Int64`). +`UmfpackLU{Tv, Ti}`, with `Tv` = [`Float64`](@ref) or `Complex128` respectively and +`Ti` is an integer type ([`Int32`](@ref) or [`Int64`](@ref)). The individual components of the factorization `F` can be accessed by indexing: @@ -133,7 +133,7 @@ The relation between `F` and `A` is !!! note `lufact(A::SparseMatrixCSC)` uses the UMFPACK library that is part of - SuiteSparse. As this library only supports sparse matrices with `Float64` or + SuiteSparse. As this library only supports sparse matrices with [`Float64`](@ref) or `Complex128` elements, `lufact` converts `A` into a copy that is of type `SparseMatrixCSC{Float64}` or `SparseMatrixCSC{Complex128}` as appropriate. """ diff --git a/base/special/gamma.jl b/base/special/gamma.jl index 479ab58adfc0a..7415200b409ce 100644 --- a/base/special/gamma.jl +++ b/base/special/gamma.jl @@ -37,7 +37,7 @@ lfact(x::Integer) = x < 0 ? throw(DomainError()) : lgamma(x + oneunit(x)) lgamma(x) Compute the logarithm of the absolute value of [`gamma`](@ref) for -`Real` `x`, while for `Complex` `x` it computes the +[`Real`](@ref) `x`, while for [`Complex`](@ref) `x` compute the principal branch cut of the logarithm of `gamma(x)` (defined for negative `real(x)` by analytic continuation from positive `real(x)`). """ diff --git a/base/test.jl b/base/test.jl index a64c9679b0264..9d7dc05bd553e 100644 --- a/base/test.jl +++ b/base/test.jl @@ -115,7 +115,7 @@ end Error The test condition couldn't be evaluated due to an exception, or -it evaluated to something other than a `Bool`. +it evaluated to something other than a [`Bool`](@ref). In the case of `@test_broken` it is used to indicate that an unexpected `Pass` `Result` occurred. """ diff --git a/doc/src/devdocs/offset-arrays.md b/doc/src/devdocs/offset-arrays.md index 9951c72231de9..689f856b48d62 100644 --- a/doc/src/devdocs/offset-arrays.md +++ b/doc/src/devdocs/offset-arrays.md @@ -108,8 +108,8 @@ Storage is often allocated with `Array{Int}(dims)` or `similar(A, args...)`. Whe to match the indices of some other array, this may not always suffice. The generic replacement for such patterns is to use `similar(storagetype, shape)`. `storagetype` indicates the kind of underlying "conventional" behavior you'd like, e.g., `Array{Int}` or `BitArray` or even `dims->zeros(Float32, dims)` -(which would allocate an all-zeros array). `shape` is a tuple of `Integer` or `AbstractUnitRange` -values, specifying the indices that you want the result to use. +(which would allocate an all-zeros array). `shape` is a tuple of [`Integer`](@ref) or +`AbstractUnitRange` values, specifying the indices that you want the result to use. Let's walk through a couple of explicit examples. First, if `A` has conventional indices, then `similar(Array{Int}, indices(A))` would end up calling `Array{Int}(size(A))`, and thus return diff --git a/doc/src/devdocs/reflection.md b/doc/src/devdocs/reflection.md index 9579a21eddaf6..d31188f80b9aa 100644 --- a/doc/src/devdocs/reflection.md +++ b/doc/src/devdocs/reflection.md @@ -50,7 +50,7 @@ of these fields is the `types` field observed in the example above. ## Subtypes The *direct* subtypes of any `DataType` may be listed using [`subtypes()`](@ref). For example, -the abstract `DataType``AbstractFloat` has four (concrete) subtypes: +the abstract `DataType` [`AbstractFloat`](@ref) has four (concrete) subtypes: ```jldoctest julia> subtypes(AbstractFloat) diff --git a/doc/src/devdocs/types.md b/doc/src/devdocs/types.md index 44a1a7480e4c5..5b3da02716a6c 100644 --- a/doc/src/devdocs/types.md +++ b/doc/src/devdocs/types.md @@ -14,8 +14,8 @@ have. A *concrete* type `T` describes the set of values whose direct tag, as returned by the `typeof` function, is `T`. An *abstract* type describes some possibly-larger set of values. -`Any` describes the entire universe of possible values. `Integer` is a subset of `Any` that includes -`Int`, `Int8`, and other concrete types. +`Any` describes the entire universe of possible values. [`Integer`](@ref) is a subset of +`Any` that includes `Int`, [`Int8`](@ref), and other concrete types. Internally, Julia also makes heavy use of another type known as `Bottom`, which can also be written as `Union{}`. This corresponds to the empty set. @@ -330,7 +330,7 @@ However, this interpretation causes some practical problems. First, a value of `T` needs to be available inside the method definition. For a call like `f(1, 1.0)`, it's not clear what `T` should be. -It could be `Union{Int,Float64}`, or perhaps `Real`. +It could be `Union{Int,Float64}`, or perhaps [`Real`](@ref). Intuitively, we expect the declaration `x::T` to mean `T === typeof(x)`. To make sure that invariant holds, we need `typeof(x) === typeof(y) === T` in this method. That implies the method should only be called for arguments of the exact same type. diff --git a/doc/src/manual/arrays.md b/doc/src/manual/arrays.md index 757ac1f384a77..b99ae2cb050df 100644 --- a/doc/src/manual/arrays.md +++ b/doc/src/manual/arrays.md @@ -10,7 +10,7 @@ on implementing a custom array type. An array is a collection of objects stored in a multi-dimensional grid. In the most general case, an array may contain objects of type `Any`. For most computational purposes, arrays should contain -objects of a more specific type, such as `Float64` or `Int32`. +objects of a more specific type, such as [`Float64`](@ref) or [`Int32`](@ref). In general, unlike many other technical computing languages, Julia does not expect programs to be written in a vectorized style for performance. Julia's compiler uses type inference and generates @@ -46,7 +46,7 @@ Many functions for constructing and initializing arrays are provided. In the fol such functions, calls with a `dims...` argument can either take a single tuple of dimension sizes or a series of dimension sizes passed as a variable number of arguments. Most of these functions also accept a first input `T`, which is the element type of the array. If the type `T` is -omitted it will default to `Float64`. +omitted it will default to [`Float64`](@ref). | Function | Description | |:---------------------------------- |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/doc/src/manual/calling-c-and-fortran-code.md b/doc/src/manual/calling-c-and-fortran-code.md index b8164f86ad8da..30da54ac330ad 100644 --- a/doc/src/manual/calling-c-and-fortran-code.md +++ b/doc/src/manual/calling-c-and-fortran-code.md @@ -66,7 +66,7 @@ julia> typeof(ans) Int32 ``` -`clock` takes no arguments and returns an `Int32`. One common gotcha is that a 1-tuple must be +`clock` takes no arguments and returns an [`Int32`](@ref). One common gotcha is that a 1-tuple must be written with a trailing comma. For example, to call the `getenv` function to get a pointer to the value of an environment variable, one makes a call like this: @@ -192,8 +192,8 @@ julia> const mycompare_c = cfunction(mycompare, Cint, (Ref{Cdouble}, Ref{Cdouble ``` [`cfunction()`](@ref) accepts three arguments: the Julia function (`mycompare`), the return type -(`Cint`), and a tuple of the argument types, in this case to sort an array of `Cdouble` (`Float64`) -elements. +(`Cint`), and a tuple of the argument types, in this case to sort an array of `Cdouble` +([`Float64`](@ref)) elements. The final call to `qsort` looks like this: @@ -298,7 +298,7 @@ same: * `Signed` Exactly corresponds to the `signed` type annotation in C (or any `INTEGER` type in Fortran). - Any Julia type that is not a subtype of `Signed` is assumed to be unsigned. + Any Julia type that is not a subtype of [`Signed`](@ref) is assumed to be unsigned. * `Ref{T}` diff --git a/doc/src/manual/constructors.md b/doc/src/manual/constructors.md index 607e702671211..e9b46b392a443 100644 --- a/doc/src/manual/constructors.md +++ b/doc/src/manual/constructors.md @@ -313,10 +313,10 @@ Point{Float64}(1.0, 2.0) As you can see, for constructor calls with explicit type parameters, the arguments are converted to the implied field types: `Point{Int64}(1,2)` works, but `Point{Int64}(1.0,2.5)` raises an -[`InexactError`](@ref) when converting `2.5` to `Int64`. When the type is implied by the arguments to -the constructor call, as in `Point(1,2)`, then the types of the arguments must agree -- otherwise -the `T` cannot be determined -- but any pair of real arguments with matching type may be given -to the generic `Point` constructor. +[`InexactError`](@ref) when converting `2.5` to [`Int64`](@ref). When the type is implied +by the arguments to the constructor call, as in `Point(1,2)`, then the types of the +arguments must agree -- otherwise the `T` cannot be determined -- but any pair of real +arguments with matching type may be given to the generic `Point` constructor. What's really going on here is that `Point`, `Point{Float64}` and `Point{Int64}` are all different constructor functions. In fact, `Point{T}` is a distinct constructor function for each type `T`. @@ -551,10 +551,11 @@ SummedArray{Int32,Int32}(Int32[1, 2, 3], 6) ``` The problem is that we want `S` to be a larger type than `T`, so that we can sum many elements -with less information loss. For example, when `T` is `Int32`, we would like `S` to be `Int64`. -Therefore we want to avoid an interface that allows the user to construct instances of the type -`SummedArray{Int32,Int32}`. One way to do this is to provide a constructor only for `SummedArray`, -but inside the `type` definition block to suppress generation of default constructors: +with less information loss. For example, when `T` is [`Int32`](@ref), we would like `S` to +be [`Int64`](@ref). Therefore we want to avoid an interface that allows the user to construct +instances of the type `SummedArray{Int32,Int32}`. One way to do this is to provide a +constructor only for `SummedArray`, but inside the `type` definition block to suppress +generation of default constructors: ```jldoctest julia> struct SummedArray{T<:Number,S<:Number} diff --git a/doc/src/manual/control-flow.md b/doc/src/manual/control-flow.md index 1bf0923b6cb40..1dc395b2a31d5 100644 --- a/doc/src/manual/control-flow.md +++ b/doc/src/manual/control-flow.md @@ -173,8 +173,8 @@ julia> if 1 ERROR: TypeError: non-boolean (Int64) used in boolean context ``` -This error indicates that the conditional was of the wrong type: `Int64` rather than the required -`Bool`. +This error indicates that the conditional was of the wrong type: [`Int64`](@ref) rather +than the required [`Bool`](@ref). The so-called "ternary operator", `?:`, is closely related to the `if`-`elseif`-`else` syntax, but is used where a conditional choice between single expression values is required, as opposed diff --git a/doc/src/manual/conversion-and-promotion.md b/doc/src/manual/conversion-and-promotion.md index b72d2715b6aeb..3ffd6e2e33856 100644 --- a/doc/src/manual/conversion-and-promotion.md +++ b/doc/src/manual/conversion-and-promotion.md @@ -101,13 +101,14 @@ is to it. For example, the method to convert a real number to a boolean is this: convert(::Type{Bool}, x::Real) = x==0 ? false : x==1 ? true : throw(InexactError()) ``` -The type of the first argument of this method is a [singleton type](@ref man-singleton-types), `Type{Bool}`, the only -instance of which is `Bool`. Thus, this method is only invoked when the first argument is the -type value `Bool`. Notice the syntax used for the first argument: the argument name is omitted -prior to the `::` symbol, and only the type is given. This is the syntax in Julia for a function -argument whose type is specified but whose value is never used in the function body. In this -example, since the type is a singleton, there would never be any reason to use its value within -the body. When invoked, the method determines whether a numeric value is true or false as a boolean, +The type of the first argument of this method is a [singleton type](@ref man-singleton-types), +`Type{Bool}`, the only instance of which is [`Bool`](@ref). Thus, this method is only invoked +when the first argument is the type value `Bool`. Notice the syntax used for the first +argument: the argument name is omitted prior to the `::` symbol, and only the type is given. +This is the syntax in Julia for a function argument whose type is specified but whose value +is never used in the function body. In this example, since the type is a singleton, there +would never be any reason to use its value within the body. When invoked, the method +determines whether a numeric value is true or false as a boolean, by comparing it to one and zero: ```jldoctest @@ -137,7 +138,8 @@ convert(::Type{T}, z::Complex) where {T<:Real} = ### [Case Study: Rational Conversions](@id man-rational-conversion) -To continue our case study of Julia's `Rational` type, here are the conversions declared in [`rational.jl`](https://github.com/JuliaLang/julia/blob/master/base/rational.jl), +To continue our case study of Julia's [`Rational`](@ref) type, here are the conversions declared in +[`rational.jl`](https://github.com/JuliaLang/julia/blob/master/base/rational.jl), right after the declaration of the type and its constructors: ```julia @@ -187,8 +189,8 @@ since the values are converted to a "greater" type -- i.e. one which can represe input values in a single common type. It is important, however, not to confuse this with object-oriented (structural) super-typing, or Julia's notion of abstract super-types: promotion has nothing to do with the type hierarchy, and everything to do with converting between alternate representations. -For instance, although every `Int32` value can also be represented as a `Float64` value, `Int32` -is not a subtype of `Float64`. +For instance, although every [`Int32`](@ref) value can also be represented as a [`Float64`](@ref) value, +`Int32` is not a subtype of `Float64`. Promotion to a common "greater" type is performed in Julia by the `promote` function, which takes any number of arguments, and returns a tuple of the same number of values, converted to a common @@ -286,10 +288,11 @@ promote_rule(::Type{UInt8}, ::Type{Int8}) = Int promote_rule(::Type{BigInt}, ::Type{Int8}) = BigInt ``` -In the latter case, the result type is `BigInt` since `BigInt` is the only type large enough to -hold integers for arbitrary-precision integer arithmetic. Also note that one does not need to -define both `promote_rule(::Type{A}, ::Type{B})` and `promote_rule(::Type{B}, ::Type{A})` -- the -symmetry is implied by the way `promote_rule` is used in the promotion process. +In the latter case, the result type is [`BigInt`](@ref) since `BigInt` is the only type +large enough to hold integers for arbitrary-precision integer arithmetic. Also note that +one does not need to define both `promote_rule(::Type{A}, ::Type{B})` and +`promote_rule(::Type{B}, ::Type{A})` -- the symmetry is implied by the way `promote_rule` +is used in the promotion process. The `promote_rule` function is used as a building block to define a second function called `promote_type`, which, given any number of type objects, returns the common type to which those values, as arguments diff --git a/doc/src/manual/dates.md b/doc/src/manual/dates.md index 70645cacd1d93..476314407e6ab 100644 --- a/doc/src/manual/dates.md +++ b/doc/src/manual/dates.md @@ -12,10 +12,10 @@ For example, since the [`Date`](@ref) type only resolves to the precision of a s no hours, minutes, or seconds), normal considerations for time zones, daylight savings/summer time, and leap seconds are unnecessary and avoided. -Both [`Date`](@ref) and [`DateTime`](@ref) are basically immutable `Int64` wrappers. The single -`instant` field of either type is actually a `UTInstant{P}` type, which represents a continuously -increasing machine timeline based on the UT second [^1]. The [`DateTime`](@ref) -type is not aware of time zones (*naive*, in Python parlance), +Both [`Date`](@ref) and [`DateTime`](@ref) are basically immutable [`Int64`](@ref) wrappers. +The single `instant` field of either type is actually a `UTInstant{P}` type, which +represents a continuously increasing machine timeline based on the UT second [^1]. The +[`DateTime`](@ref) type is not aware of time zones (*naive*, in Python parlance), analogous to a *LocalDateTime* in Java 8. Additional time zone functionality can be added through the [TimeZones.jl package](https://github.com/JuliaTime/TimeZones.jl/), which compiles the [IANA time zone database](http://www.iana.org/time-zones). Both [`Date`](@ref) and @@ -133,7 +133,7 @@ Finding the length of time between two [`Date`](@ref) or [`DateTime`](@ref) is s given their underlying representation as `UTInstant{Day}` and `UTInstant{Millisecond}`, respectively. The difference between [`Date`](@ref) is returned in the number of [`Day`](@ref), and [`DateTime`](@ref) in the number of [`Millisecond`](@ref). Similarly, comparing [`TimeType`](@ref) is a simple matter -of comparing the underlying machine instants (which in turn compares the internal `Int64` values). +of comparing the underlying machine instants (which in turn compares the internal [`Int64`](@ref) values). ```jldoctest julia> dt = Date(2012,2,29) @@ -190,7 +190,7 @@ julia> dt - dt2 ## Accessor Functions -Because the [`Date`](@ref) and [`DateTime`](@ref) types are stored as single `Int64` values, date +Because the [`Date`](@ref) and [`DateTime`](@ref) types are stored as single [`Int64`](@ref) values, date parts or fields can be retrieved through accessor functions. The lowercase accessors return the field as an integer: @@ -454,7 +454,8 @@ julia> Dates.lastdayofquarter(Date(2014,7,16)) # Adjusts to the last day of the The next two higher-order methods, [`tonext()`](@ref), and [`toprev()`](@ref), generalize working with temporal expressions by taking a `DateFunction` as first argument, along with a starting [`TimeType`](@ref). A `DateFunction` is just a function, usually anonymous, that takes a single -[`TimeType`](@ref) as input and returns a `Bool`, `true` indicating a satisfied adjustment criterion. +[`TimeType`](@ref) as input and returns a [`Bool`](@ref), `true` indicating a satisfied +adjustment criterion. For example: ```jldoctest @@ -511,7 +512,7 @@ Additional examples and tests are available in [`test/dates/adjusters.jl`](https Periods are a human view of discrete, sometimes irregular durations of time. Consider 1 month; it could represent, in days, a value of 28, 29, 30, or 31 depending on the year and month context. Or a year could represent 365 or 366 days in the case of a leap year. [`Period`](@ref) types are -simple `Int64` wrappers and are constructed by wrapping any `Int64` convertible type, i.e. `Year(1)` +simple [`Int64`](@ref) wrappers and are constructed by wrapping any `Int64` convertible type, i.e. `Year(1)` or `Month(3.0)`. Arithmetic between [`Period`](@ref) of the same type behave like integers, and limited `Period-Real` arithmetic is available. diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 59d1a23f2e43d..94499bf241f72 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -109,8 +109,8 @@ As in the example above, we recommend following some simple conventions when wri Calling `rand` and other RNG-related functions should be avoided in doctests since they will not produce consistent outputs during different Julia sessions. - Operating system word size (`Int32` or `Int64`) as well as path separator differences (`/` or - `\`) will also effect the reproducibility of some doctests. + Operating system word size ([`Int32`](@ref) or [`Int64`](@ref)) as well as path separator differences + (`/` or `\`) will also effect the reproducibility of some doctests. Note that whitespace in your doctest is significant! The doctest will fail if you misalign the output of pretty-printing an array, for example. diff --git a/doc/src/manual/embedding.md b/doc/src/manual/embedding.md index 77a132c5b3d20..032b57dcedc43 100644 --- a/doc/src/manual/embedding.md +++ b/doc/src/manual/embedding.md @@ -139,9 +139,9 @@ Now the build command is simply `make`. Real applications will not just need to execute expressions, but also return their values to the host program. `jl_eval_string` returns a `jl_value_t*`, which is a pointer to a heap-allocated -Julia object. Storing simple data types like `Float64` in this way is called `boxing`, and extracting -the stored primitive data is called `unboxing`. Our improved sample program that calculates the -square root of 2 in Julia and reads back the result in C looks as follows: +Julia object. Storing simple data types like [`Float64`](@ref) in this way is called `boxing`, +and extracting the stored primitive data is called `unboxing`. Our improved sample program that +calculates the square root of 2 in Julia and reads back the result in C looks as follows: ```c jl_value_t *ret = jl_eval_string("sqrt(2.0)"); @@ -157,9 +157,9 @@ else { In order to check whether `ret` is of a specific Julia type, we can use the `jl_isa`, `jl_typeis`, or `jl_is_...` functions. -By typing `typeof(sqrt(2.0))` into the Julia shell we can see that the return type is `Float64` -(`double` in C). To convert the boxed Julia value into a C double the `jl_unbox_float64` function -is used in the above code snippet. +By typing `typeof(sqrt(2.0))` into the Julia shell we can see that the return type is +[`Float64`](@ref) (`double` in C). To convert the boxed Julia value into a C double the +`jl_unbox_float64` function is used in the above code snippet. Corresponding `jl_box_...` functions are used to convert the other way: diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md index bbb2c41e27a91..d2fe606136b76 100644 --- a/doc/src/manual/environment-variables.md +++ b/doc/src/manual/environment-variables.md @@ -175,7 +175,7 @@ logical CPU cores available. ### `JULIA_WORKER_TIMEOUT` -A `Float64` that sets the value of `Base.worker_timeout()` (default: `60.0`). +A [`Float64`](@ref) that sets the value of `Base.worker_timeout()` (default: `60.0`). This function gives the number of seconds a worker process will wait for a master process to establish a connection before dying. diff --git a/doc/src/manual/faq.md b/doc/src/manual/faq.md index e019cce47fa78..4ff850b44ea00 100644 --- a/doc/src/manual/faq.md +++ b/doc/src/manual/faq.md @@ -214,9 +214,10 @@ julia> function unstable(flag::Bool) unstable (generic function with 1 method) ``` -It returns either an `Int` or a `Float64` depending on the value of its argument. Since Julia -can't predict the return type of this function at compile-time, any computation that uses it will -have to guard against both types possibly occurring, making generation of fast machine code difficult. +It returns either an `Int` or a [`Float64`](@ref) depending on the value of its argument. +Since Julia can't predict the return type of this function at compile-time, any computation +that uses it will have to guard against both types possibly occurring, making generation of +fast machine code difficult. ### [Why does Julia give a `DomainError` for certain seemingly-sensible operations?](@id faq-domain-errors) @@ -281,7 +282,7 @@ ideal for a high-level programming language to expose this to the user. For nume efficiency and transparency are at a premium, however, the alternatives are worse. One alternative to consider would be to check each integer operation for overflow and promote -results to bigger integer types such as `Int128` or [`BigInt`](@ref) in the case of overflow. +results to bigger integer types such as [`Int128`](@ref) or [`BigInt`](@ref) in the case of overflow. Unfortunately, this introduces major overhead on every integer operation (think incrementing a loop counter) – it requires emitting code to perform run-time overflow checks after arithmetic instructions and branches to handle potential overflows. Worse still, this would cause every computation diff --git a/doc/src/manual/integers-and-floating-point-numbers.md b/doc/src/manual/integers-and-floating-point-numbers.md index 5e1c54347bd3f..1b819938cc625 100644 --- a/doc/src/manual/integers-and-floating-point-numbers.md +++ b/doc/src/manual/integers-and-floating-point-numbers.md @@ -18,25 +18,25 @@ The following are Julia's primitive numeric types: * **Integer types:** -| Type | Signed? | Number of bits | Smallest value | Largest value | -|:--------- |:------- |:-------------- |:-------------- |:------------- | -| `Int8` | ✓ | 8 | -2^7 | 2^7 - 1 | -| `UInt8` |   | 8 | 0 | 2^8 - 1 | -| `Int16` | ✓ | 16 | -2^15 | 2^15 - 1 | -| `UInt16` |   | 16 | 0 | 2^16 - 1 | -| `Int32` | ✓ | 32 | -2^31 | 2^31 - 1 | -| `UInt32` |   | 32 | 0 | 2^32 - 1 | -| `Int64` | ✓ | 64 | -2^63 | 2^63 - 1 | -| `UInt64` |   | 64 | 0 | 2^64 - 1 | -| `Int128` | ✓ | 128 | -2^127 | 2^127 - 1 | -| `UInt128` |   | 128 | 0 | 2^128 - 1 | -| `Bool` | N/A | 8 | `false` (0) | `true` (1) | +| Type | Signed? | Number of bits | Smallest value | Largest value | +|:----------------- |:------- |:-------------- |:-------------- |:------------- | +| [`Int8`](@ref) | ✓ | 8 | -2^7 | 2^7 - 1 | +| [`UInt8`](@ref) |   | 8 | 0 | 2^8 - 1 | +| [`Int16`](@ref) | ✓ | 16 | -2^15 | 2^15 - 1 | +| [`UInt16`](@ref) |   | 16 | 0 | 2^16 - 1 | +| [`Int32`](@ref) | ✓ | 32 | -2^31 | 2^31 - 1 | +| [`UInt32`](@ref) |   | 32 | 0 | 2^32 - 1 | +| [`Int64`](@ref) | ✓ | 64 | -2^63 | 2^63 - 1 | +| [`UInt64`](@ref) |   | 64 | 0 | 2^64 - 1 | +| [`Int128`](@ref) | ✓ | 128 | -2^127 | 2^127 - 1 | +| [`UInt128`](@ref) |   | 128 | 0 | 2^128 - 1 | +| [`Bool`](@ref) | N/A | 8 | `false` (0) | `true` (1) | * **Floating-point types:** | Type | Precision | Number of bits | |:----------------- |:------------------------------------------------------------------------------ |:-------------- | -| `Float16` | [half](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) | 16 | +| [`Float16`](@ref) | [half](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) | 16 | | [`Float32`](@ref) | [single](https://en.wikipedia.org/wiki/Single_precision_floating-point_format) | 32 | | [`Float64`](@ref) | [double](https://en.wikipedia.org/wiki/Double_precision_floating-point_format) | 64 | @@ -206,7 +206,7 @@ true Thus, arithmetic with Julia integers is actually a form of [modular arithmetic](https://en.wikipedia.org/wiki/Modular_arithmetic). This reflects the characteristics of the underlying arithmetic of integers as implemented on modern computers. In applications where overflow is possible, explicit checking for wraparound produced -by overflow is essential; otherwise, the `BigInt` type in [Arbitrary Precision Arithmetic](@ref) +by overflow is essential; otherwise, the [`BigInt`](@ref) type in [Arbitrary Precision Arithmetic](@ref) is recommended instead. ### Division errors @@ -243,8 +243,8 @@ julia> 2.5e-4 0.00025 ``` -The above results are all `Float64` values. Literal `Float32` values can be entered by writing -an `f` in place of `e`: +The above results are all [`Float64`](@ref) values. Literal [`Float32`](@ref) values can be +entered by writing an `f` in place of `e`: ```jldoctest julia> 0.5f0 @@ -257,7 +257,7 @@ julia> 2.5f-4 0.00025f0 ``` -Values can be converted to `Float32` easily: +Values can be converted to [`Float32`](@ref) easily: ```jldoctest julia> Float32(-1.5) @@ -267,7 +267,7 @@ julia> typeof(ans) Float32 ``` -Hexadecimal floating-point literals are also valid, but only as `Float64` values: +Hexadecimal floating-point literals are also valid, but only as [`Float64`](@ref) values: ```jldoctest julia> 0x1p0 @@ -283,8 +283,8 @@ julia> typeof(ans) Float64 ``` -Half-precision floating-point numbers are also supported (`Float16`), but they are -implemented in software and use `Float32` for calculations. +Half-precision floating-point numbers are also supported ([`Float16`](@ref)), but they are +implemented in software and use [`Float32`](@ref) for calculations. ```jldoctest julia> sizeof(Float16(4.)) @@ -404,11 +404,11 @@ julia> eps() # same as eps(Float64) 2.220446049250313e-16 ``` -These values are `2.0^-23` and `2.0^-52` as `Float32` and `Float64` values, respectively. The -[`eps()`](@ref) function can also take a floating-point value as an argument, and gives the absolute -difference between that value and the next representable floating point value. That is, `eps(x)` -yields a value of the same type as `x` such that `x + eps(x)` is the next representable floating-point -value larger than `x`: +These values are `2.0^-23` and `2.0^-52` as [`Float32`](@ref) and [`Float64`](@ref) values, +respectively. The [`eps()`](@ref) function can also take a floating-point value as an +argument, and gives the absolute difference between that value and the next representable +floating point value. That is, `eps(x)` yields a value of the same type as `x` such that +`x + eps(x)` is the next representable floating-point value larger than `x`: ```jldoctest julia> eps(1.0) diff --git a/doc/src/manual/mathematical-operations.md b/doc/src/manual/mathematical-operations.md index 2727ec20cd853..a6ff8bdea53f8 100644 --- a/doc/src/manual/mathematical-operations.md +++ b/doc/src/manual/mathematical-operations.md @@ -21,7 +21,7 @@ are supported on all primitive numeric types: | `x ^ y` | power | raises `x` to the `y`th power | | `x % y` | remainder | equivalent to `rem(x,y)` | -as well as the negation on `Bool` types: +as well as the negation on [`Bool`](@ref) types: | Expression | Name | Description | |:---------- |:-------- |:---------------------------------------- | diff --git a/doc/src/manual/metaprogramming.md b/doc/src/manual/metaprogramming.md index 445049ec3cf39..1804f39559b20 100644 --- a/doc/src/manual/metaprogramming.md +++ b/doc/src/manual/metaprogramming.md @@ -972,7 +972,7 @@ julia> foo(4) 16 ``` -Note that there is no printout of `Int64`. We can see that the body of the generated function +Note that there is no printout of [`Int64`](@ref). We can see that the body of the generated function was only executed once here, for the specific set of argument types, and the result was cached. After that, for this example, the expression returned from the generated function on the first invocation was re-used as the method body. However, the actual caching behavior is an implementation-defined diff --git a/doc/src/manual/methods.md b/doc/src/manual/methods.md index bc649bf4c2f35..c8843e18b0635 100644 --- a/doc/src/manual/methods.md +++ b/doc/src/manual/methods.md @@ -58,7 +58,8 @@ julia> f(x::Float64, y::Float64) = 2x + y f (generic function with 1 method) ``` -This function definition applies only to calls where `x` and `y` are both values of type `Float64`: +This function definition applies only to calls where `x` and `y` are both values of type +[`Float64`](@ref): ```jldoctest fofxy julia> f(2.0, 3.0) @@ -87,12 +88,12 @@ julia> f("2.0", "3.0") ERROR: MethodError: no method matching f(::String, ::String) ``` -As you can see, the arguments must be precisely of type `Float64`. Other numeric types, such as -integers or 32-bit floating-point values, are not automatically converted to 64-bit floating-point, -nor are strings parsed as numbers. Because `Float64` is a concrete type and concrete types cannot -be subclassed in Julia, such a definition can only be applied to arguments that are exactly of -type `Float64`. It may often be useful, however, to write more general methods where the declared -parameter types are abstract: +As you can see, the arguments must be precisely of type [`Float64`](@ref). Other numeric +types, such as integers or 32-bit floating-point values, are not automatically converted +to 64-bit floating-point, nor are strings parsed as numbers. Because `Float64` is a concrete +type and concrete types cannot be subclassed in Julia, such a definition can only be applied +to arguments that are exactly of type `Float64`. It may often be useful, however, to write +more general methods where the declared parameter types are abstract: ```jldoctest fofxy julia> f(x::Number, y::Number) = 2x - y @@ -102,9 +103,10 @@ julia> f(2.0, 3) 1.0 ``` -This method definition applies to any pair of arguments that are instances of `Number`. They need -not be of the same type, so long as they are each numeric values. The problem of handling disparate -numeric types is delegated to the arithmetic operations in the expression `2x - y`. +This method definition applies to any pair of arguments that are instances of [`Number`](@ref). +They need not be of the same type, so long as they are each numeric values. The problem of +handling disparate numeric types is delegated to the arithmetic operations in the +expression `2x - y`. To define a function with multiple methods, one simply defines the function multiple times, with different numbers and types of arguments. The first method definition for a function creates the @@ -112,9 +114,9 @@ function object, and subsequent method definitions add new methods to the existi The most specific method definition matching the number and types of the arguments will be executed when the function is applied. Thus, the two method definitions above, taken together, define the behavior for `f` over all pairs of instances of the abstract type `Number` -- but with a different -behavior specific to pairs of `Float64` values. If one of the arguments is a 64-bit float but -the other one is not, then the `f(Float64,Float64)` method cannot be called and the more general -`f(Number,Number)` method must be used: +behavior specific to pairs of [`Float64`](@ref) values. If one of the arguments is a 64-bit +float but the other one is not, then the `f(Float64,Float64)` method cannot be called and +the more general `f(Number,Number)` method must be used: ```jldoctest fofxy julia> f(2.0, 3.0) diff --git a/doc/src/manual/noteworthy-differences.md b/doc/src/manual/noteworthy-differences.md index 5457f201dbd6d..98740263fc364 100644 --- a/doc/src/manual/noteworthy-differences.md +++ b/doc/src/manual/noteworthy-differences.md @@ -239,11 +239,11 @@ For users coming to Julia from R, these are some noteworthy differences: unsigned and/or signed vs. unsigned. Decimal literals are always signed, and hexadecimal literals (which start with `0x` like C/C++), are unsigned. Hexadecimal literals also, unlike C/C++/Java and unlike decimal literals in Julia, have a type based on the *length* of the literal, including - leading 0s. For example, `0x0` and `0x00` have type UInt8, `0x000` and `0x0000` have type `UInt16`, - then literals with 5 to 8 hex digits have type `UInt32`, 9 to 16 hex digits type `UInt64` and - 17 to 32 hex digits type `UInt128`. This needs to be taken into account when defining hexadecimal - masks, for example `~0xf == 0xf0` is very different from `~0x000f == 0xfff0`. 64 bit `Float64` - and 32 bit `Float32` bit literals are expressed as `1.0` and `1.0f0` respectively. Floating point + leading 0s. For example, `0x0` and `0x00` have type [`UInt8`](@ref), `0x000` and `0x0000` have type + [`UInt16`](@ref), then literals with 5 to 8 hex digits have type `UInt32`, 9 to 16 hex digits type + `UInt64` and 17 to 32 hex digits type `UInt128`. This needs to be taken into account when defining + hexadecimal masks, for example `~0xf == 0xf0` is very different from `~0x000f == 0xfff0`. 64 bit `Float64` + and 32 bit [`Float32`](@ref) bit literals are expressed as `1.0` and `1.0f0` respectively. Floating point literals are rounded (and not promoted to the `BigFloat` type) if they can not be exactly represented. Floating point literals are closer in behavior to C/C++. Octal (prefixed with `0o`) and binary (prefixed with `0b`) literals are also treated as unsigned. @@ -251,7 +251,7 @@ For users coming to Julia from R, these are some noteworthy differences: `"` characters without quoting it like `"\""` String literals can have values of other variables or expressions interpolated into them, indicated by `$variablename` or `$(expression)`, which evaluates the variable name or the expression in the context of the function. - * `//` indicates a `Rational` number, and not a single-line comment (which is `#` in Julia) + * `//` indicates a [`Rational`](@ref) number, and not a single-line comment (which is `#` in Julia) * `#=` indicates the start of a multiline comment, and `=#` ends it. * Functions in Julia return values from their last expression(s) or the `return` keyword. Multiple values can be returned from functions and assigned as tuples, e.g. `(a, b) = myfunction()` or diff --git a/doc/src/manual/performance-tips.md b/doc/src/manual/performance-tips.md index 14c91c0d9e379..92fd3bc55aa30 100644 --- a/doc/src/manual/performance-tips.md +++ b/doc/src/manual/performance-tips.md @@ -137,10 +137,10 @@ if (f = rand()) < .8 end ``` -Because `a` is a an array of abstract type `Real`, it must be able to hold any `Real` value. Since -`Real` objects can be of arbitrary size and structure, `a` must be represented as an array of -pointers to individually allocated `Real` objects. Because `f` will always be a [`Float64`](@ref), -we should instead, use: +Because `a` is a an array of abstract type [`Real`](@ref), it must be able to hold any +`Real` value. Since `Real` objects can be of arbitrary size and structure, `a` must be +represented as an array of pointers to individually allocated `Real` objects. Because `f` +will always be a [`Float64`](@ref), we should instead, use: ```julia a = Float64[] # typeof(a) = Array{Float64,1} @@ -188,9 +188,9 @@ MyAmbiguousType `b` and `c` have the same type, yet their underlying representation of data in memory is very different. Even if you stored just numeric values in field `a`, the fact that the memory representation -of a `UInt8` differs from a `Float64` also means that the CPU needs to handle them using two different -kinds of instructions. Since the required information is not available in the type, such decisions -have to be made at run-time. This slows performance. +of a [`UInt8`](@ref) differs from a [`Float64`](@ref) also means that the CPU needs to handle +them using two different kinds of instructions. Since the required information is not available +in the type, such decisions have to be made at run-time. This slows performance. You can do better by declaring the type of `a`. Here, we are focused on the case where `a` might be any one of several types, in which case the natural solution is to use parameters. For example: @@ -473,9 +473,9 @@ function foo(a::Array{Any,1}) end ``` -Here, we happened to know that the first element of `a` would be an `Int32`. Making an annotation -like this has the added benefit that it will raise a run-time error if the value is not of the -expected type, potentially catching certain bugs earlier. +Here, we happened to know that the first element of `a` would be an [`Int32`](@ref). Making +an annotation like this has the added benefit that it will raise a run-time error if the +value is not of the expected type, potentially catching certain bugs earlier. ### Declare types of keyword arguments @@ -1388,7 +1388,7 @@ code defined in `pos`. Starting at `2:`, the variable `y` is defined, and again annotated as a `Union` type. Next, we see that the compiler created the temporary variable `_var1` to hold the result of `y*x`. Because -a [`Float64`](@ref) times *either* an `Int64` or [`Float64`](@ref) yields a [`Float64`](@ref), +a [`Float64`](@ref) times *either* an [`Int64`](@ref) or `Float64` yields a `Float64`, all type-instability ends here. The net result is that `f(x::Float64)` will not be type-unstable in its output, even if some of the intermediate computations are type-unstable. diff --git a/doc/src/manual/strings.md b/doc/src/manual/strings.md index 4d4b9d5a0f158..a1298af12de5b 100644 --- a/doc/src/manual/strings.md +++ b/doc/src/manual/strings.md @@ -64,8 +64,8 @@ julia> typeof(ans) Int64 ``` -On 32-bit architectures, [`typeof(ans)`](@ref) will be `Int32`. You can convert an integer value -back to a `Char` just as easily: +On 32-bit architectures, [`typeof(ans)`](@ref) will be [`Int32`](@ref). You can convert an +integer value back to a `Char` just as easily: ```jldoctest julia> Char(120) @@ -778,8 +778,8 @@ for regular expressions containing quotation marks or newlines). ## [Byte Array Literals](@id man-byte-array-literals) Another useful non-standard string literal is the byte-array string literal: `b"..."`. This form -lets you use string notation to express literal byte arrays -- i.e. arrays of `UInt8` values. -The rules for byte array literals are the following: +lets you use string notation to express literal byte arrays -- i.e. arrays of +[`UInt8`](@ref) values. The rules for byte array literals are the following: * ASCII characters and ASCII escapes produce a single byte. * `\x` and octal escape sequences produce the *byte* corresponding to the escape value. diff --git a/doc/src/manual/style-guide.md b/doc/src/manual/style-guide.md index c4ac88ffc20a6..fccb5559d9272 100644 --- a/doc/src/manual/style-guide.md +++ b/doc/src/manual/style-guide.md @@ -32,11 +32,12 @@ complex(float(x)) The second version will convert `x` to an appropriate type, instead of always the same type. This style point is especially relevant to function arguments. For example, don't declare an argument -to be of type `Int` or `Int32` if it really could be any integer, expressed with the abstract -type `Integer`. In fact, in many cases you can omit the argument type altogether, unless it is -needed to disambiguate from other method definitions, since a [`MethodError`](@ref) will be thrown -anyway if a type is passed that does not support any of the requisite operations. (This is known -as [duck typing](https://en.wikipedia.org/wiki/Duck_typing).) +to be of type `Int` or [`Int32`](@ref) if it really could be any integer, expressed with the abstract +type [`Integer`](@ref). In fact, in many cases you can omit the argument type altogether, +unless it is needed to disambiguate from other method definitions, since a +[`MethodError`](@ref) will be thrown anyway if a type is passed that does not support any +of the requisite operations. (This is known as +[duck typing](https://en.wikipedia.org/wiki/Duck_typing).) For example, consider the following definitions of a function `addone` that returns one plus its argument: @@ -356,7 +357,7 @@ julia> g(1) As you can see, the second version, where we used an `Int` literal, preserved the type of the input argument, while the first didn't. This is because e.g. `promote_type(Int, Float64) == Float64`, -and promotion happens with the multiplication. Similarly, `Rational` literals are less type disruptive +and promotion happens with the multiplication. Similarly, [`Rational`](@ref) literals are less type disruptive than [`Float64`](@ref) literals, but more disruptive than `Int`s: ```jldoctest diff --git a/doc/src/manual/types.md b/doc/src/manual/types.md index 633ba5b47fac7..da93e407f2cf2 100644 --- a/doc/src/manual/types.md +++ b/doc/src/manual/types.md @@ -133,18 +133,19 @@ system: they form the conceptual hierarchy which makes Julia's type system more of object implementations. Recall that in [Integers and Floating-Point Numbers](@ref), we introduced a variety of concrete -types of numeric values: `Int8`, `UInt8`, `Int16`, `UInt16`, `Int32`, `UInt32`, `Int64`, `UInt64`, -`Int128`, `UInt128`, `Float16`, [`Float32`](@ref), and [`Float64`](@ref). Although they have -different representation sizes, `Int8`, `Int16`, `Int32`, `Int64` and `Int128` all have in common -that they are signed integer types. Likewise `UInt8`, `UInt16`, `UInt32`, `UInt64` and `UInt128` -are all unsigned integer types, while `Float16`, [`Float32`](@ref) and [`Float64`](@ref) are distinct -in being floating-point types rather than integers. It is common for a piece of code to make sense, -for example, only if its arguments are some kind of integer, but not really depend on what particular -*kind* of integer. For example, the greatest common denominator algorithm works for all kinds -of integers, but will not work for floating-point numbers. Abstract types allow the construction -of a hierarchy of types, providing a context into which concrete types can fit. This allows you, -for example, to easily program to any type that is an integer, without restricting an algorithm -to a specific type of integer. +types of numeric values: [`Int8`](@ref), [`UInt8`](@ref), [`Int16`](@ref), [`UInt16`](@ref), +[`Int32`](@ref), [`UInt32`](@ref), [`Int64`](@ref), [`UInt64`](@ref), [`Int128`](@ref), +[`UInt128`](@ref), [`Float16`](@ref), [`Float32`](@ref), and [`Float64`](@ref). Although +they have different representation sizes, `Int8`, `Int16`, `Int32`, `Int64` and `Int128` +all have in common that they are signed integer types. Likewise `UInt8`, `UInt16`, `UInt32`, +`UInt64` and `UInt128` are all unsigned integer types, while `Float16`, `Float32` and +`Float64` are distinct in being floating-point types rather than integers. It is common for +a piece of code to make sense, for example, only if its arguments are some kind of integer, +but not really depend on what particular *kind* of integer. For example, the greatest common +denominator algorithm works for all kinds of integers, but will not work for floating-point +numbers. Abstract types allow the construction of a hierarchy of types, providing a context +into which concrete types can fit. This allows you, for example, to easily program to any type +that is an integer, without restricting an algorithm to a specific type of integer. Abstract types are declared using the `abstract type` keyword. The general syntaxes for declaring an abstract type are: @@ -175,13 +176,14 @@ abstract type Signed <: Integer end abstract type Unsigned <: Integer end ``` -The `Number` type is a direct child type of `Any`, and `Real` is its child. In turn, `Real` has -two children (it has more, but only two are shown here; we'll get to the others later): `Integer` -and `AbstractFloat`, separating the world into representations of integers and representations -of real numbers. Representations of real numbers include, of course, floating-point types, but -also include other types, such as rationals. Hence, `AbstractFloat` is a proper subtype of `Real`, -including only floating-point representations of real numbers. Integers are further subdivided -into `Signed` and `Unsigned` varieties. +The [`Number`](@ref) type is a direct child type of `Any`, and [`Real`](@ref) is its child. +In turn, `Real` has two children (it has more, but only two are shown here; we'll get to +the others later): [`Integer`](@ref) and [`AbstractFloat`](@ref), separating the world into +representations of integers and representations of real numbers. Representations of real +numbers include, of course, floating-point types, but also include other types, such as +rationals. Hence, `AbstractFloat` is a proper subtype of `Real`, including only +floating-point representations of real numbers. Integers are further subdivided into +[`Signed`](@ref) and [`Unsigned`](@ref) varieties. The `<:` operator in general means "is a subtype of", and, used in declarations like this, declares the right-hand type to be an immediate supertype of the newly declared type. It can also be used @@ -268,19 +270,21 @@ primitive type «name» <: «supertype» «bits» end The number of bits indicates how much storage the type requires and the name gives the new type a name. A primitive type can optionally be declared to be a subtype of some supertype. If a supertype is omitted, then the type defaults to having `Any` as its immediate supertype. The declaration -of `Bool` above therefore means that a boolean value takes eight bits to store, and has `Integer` -as its immediate supertype. Currently, only sizes that are multiples of 8 bits are supported. -Therefore, boolean values, although they really need just a single bit, cannot be declared to -be any smaller than eight bits. - -The types `Bool`, `Int8` and `UInt8` all have identical representations: they are eight-bit chunks -of memory. Since Julia's type system is nominative, however, they are not interchangeable despite -having identical structure. A fundamental difference between them is that they have different -supertypes: `Bool`'s direct supertype is `Integer`, `Int8`'s is `Signed`, and `UInt8`'s is `Unsigned`. -All other differences between `Bool`, `Int8`, and `UInt8` are matters of behavior -- the way functions -are defined to act when given objects of these types as arguments. This is why a nominative type -system is necessary: if structure determined type, which in turn dictates behavior, then it would -be impossible to make `Bool` behave any differently than `Int8` or `UInt8`. +of [`Bool`](@ref) above therefore means that a boolean value takes eight bits to store, and has +[`Integer`](@ref) as its immediate supertype. Currently, only sizes that are multiples of +8 bits are supported. Therefore, boolean values, although they really need just a single bit, +cannot be declared to be any smaller than eight bits. + +The types [`Bool`](@ref), [`Int8`](@ref) and [`UInt8`](@ref) all have identical representations: +they are eight-bit chunks of memory. Since Julia's type system is nominative, however, they +are not interchangeable despite having identical structure. A fundamental difference between +them is that they have different supertypes: [`Bool`](@ref)'s direct supertype is [`Integer`](@ref), +[`Int8`](@ref)'s is [`Signed`](@ref), and [`UInt8`](@ref)'s is [`Unsigned`](@ref). All other +differences between [`Bool`](@ref), [`Int8`](@ref), and [`UInt8`](@ref) are matters of +behavior -- the way functions are defined to act when given objects of these types as +arguments. This is why a nominative type system is necessary: if structure determined type, +which in turn dictates behavior, then it would be impossible to make [`Bool`](@ref) behave +any differently than [`Int8`](@ref) or [`UInt8`](@ref). ## Composite Types @@ -586,14 +590,16 @@ have different representations in memory: * An instance of `Point{Float64}` can be represented compactly and efficiently as an immediate pair of 64-bit values; - * An instance of `Point{Real}` must be able to hold any pair of instances of `Real`. Since objects - that are instances of `Real` can be of arbitrary size and structure, in practice an instance of - `Point{Real}` must be represented as a pair of pointers to individually allocated `Real` objects. + * An instance of `Point{Real}` must be able to hold any pair of instances of [`Real`](@ref). + Since objects that are instances of `Real` can be of arbitrary size and structure, in + practice an instance of `Point{Real}` must be represented as a pair of pointers to + individually allocated `Real` objects. The efficiency gained by being able to store `Point{Float64}` objects with immediate values is magnified enormously in the case of arrays: an `Array{Float64}` can be stored as a contiguous memory block of 64-bit floating-point values, whereas an `Array{Real}` must be an array of pointers -to individually allocated `Real` objects -- which may well be [boxed](https://en.wikipedia.org/wiki/Object_type_%28object-oriented_programming%29#Boxing) +to individually allocated [`Real`](@ref) objects -- which may well be +[boxed](https://en.wikipedia.org/wiki/Object_type_%28object-oriented_programming%29#Boxing) 64-bit floating-point values, but also might be arbitrarily large, complex objects, which are declared to be implementations of the `Real` abstract type. @@ -607,7 +613,7 @@ end ``` A correct way to define a method that accepts all arguments of type `Point{T}` where `T` is -a subtype of `Real` is: +a subtype of [`Real`](@ref) is: ```julia function norm(p::Point{<:Real}) @@ -784,8 +790,8 @@ possible types. In such situations, one can constrain the range of `T` like so: julia> abstract type Pointy{T<:Real} end ``` -With such a declaration, it is acceptable to use any type that is a subtype of `Real` in place -of `T`, but not types that are not subtypes of `Real`: +With such a declaration, it is acceptable to use any type that is a subtype of +[`Real`](@ref) in place of `T`, but not types that are not subtypes of `Real`: ```jldoctest realpointytype julia> Pointy{Float64} @@ -811,8 +817,8 @@ end ``` To give a real-world example of how all this parametric type machinery can be useful, here is -the actual definition of Julia's `Rational` immutable type (except that we omit the constructor -here for simplicity), representing an exact ratio of integers: +the actual definition of Julia's [`Rational`](@ref) immutable type (except that we omit the +constructor here for simplicity), representing an exact ratio of integers: ```julia struct Rational{T<:Integer} <: Real @@ -822,8 +828,8 @@ end ``` It only makes sense to take ratios of integer values, so the parameter type `T` is restricted -to being a subtype of `Integer`, and a ratio of integers represents a value on the real number -line, so any `Rational` is an instance of the `Real` abstraction. +to being a subtype of [`Integer`](@ref), and a ratio of integers represents a value on the +real number line, so any [`Rational`](@ref) is an instance of the [`Real`](@ref) abstraction. ### Tuple Types @@ -1008,21 +1014,22 @@ Using explicit `where` syntax, any subset of parameters can be fixed. For exampl 1-dimensional arrays can be written as `Array{T,1} where T`. Type variables can be restricted with subtype relations. -`Array{T} where T<:Integer` refers to all arrays whose element type is some kind of `Integer`. +`Array{T} where T<:Integer` refers to all arrays whose element type is some kind of +[`Integer`](@ref). The syntax `Array{<:Integer}` is a convenient shorthand for `Array{T} where T<:Integer`. Type variables can have both lower and upper bounds. -`Array{T} where Int<:T<:Number` refers to all arrays of `Number`s that are able to contain `Int`s -(since `T` must be at least as big as `Int`). +`Array{T} where Int<:T<:Number` refers to all arrays of [`Number`](@ref)s that are able to +contain `Int`s (since `T` must be at least as big as `Int`). The syntax `where T>:Int` also works to specify only the lower bound of a type variable, and `Array{>:Int}` is equivalent to `Array{T} where T>:Int`. Since `where` expressions nest, type variable bounds can refer to outer type variables. -For example `Tuple{T,Array{S}} where S<:AbstractArray{T} where T<:Real` refers to 2-tuples whose first -element is some `Real`, and whose second element is an `Array` of any kind of array whose element type -contains the type of the first tuple element. +For example `Tuple{T,Array{S}} where S<:AbstractArray{T} where T<:Real` refers to 2-tuples +whose first element is some [`Real`](@ref), and whose second element is an `Array` of any +kind of array whose element type contains the type of the first tuple element. -The `where` keyword itself can be nested inside a more complex declaration. For example, consider the -two types created by the following declarations: +The `where` keyword itself can be nested inside a more complex declaration. For example, +consider the two types created by the following declarations: ```jldoctest julia> const T1 = Array{Array{T,1} where T, 1} @@ -1056,8 +1063,8 @@ element type. Sometimes it is convenient to introduce a new name for an already expressible type. This can be done with a simple assignment statement. -For example, `UInt` is aliased to either `UInt32` or `UInt64` as is appropriate -for the size of pointers on the system: +For example, `UInt` is aliased to either [`UInt32`](@ref) or [`UInt64`](@ref) as is +appropriate for the size of pointers on the system: ```julia-repl # 32-bit system: @@ -1080,11 +1087,12 @@ end ``` Of course, this depends on what `Int` is aliased to -- but that is predefined to be the correct -type -- either `Int32` or `Int64`. +type -- either [`Int32`](@ref) or [`Int64`](@ref). -(Note that unlike `Int`, `Float` does not exist as a type alias for a specific sized `AbstractFloat`. -Unlike with integer registers, the floating point register sizes are specified by the IEEE-754 standard. -Whereas the size of `Int` reflects the size of a native pointer on that machine.) +(Note that unlike `Int`, `Float` does not exist as a type alias for a specific sized +[`AbstractFloat`](@ref). Unlike with integer registers, the floating point register sizes +are specified by the IEEE-754 standard. Whereas the size of `Int` reflects the size of a +native pointer on that machine.) ## Operations on Types @@ -1175,11 +1183,13 @@ julia> Polar(r::Real,Θ::Real) = Polar(promote(r,Θ)...) Polar ``` -Here, we've added a custom constructor function so that it can take arguments of different `Real` -types and promote them to a common type (see [Constructors](@ref man-constructors) and [Conversion and Promotion](@ref conversion-and-promotion)). -(Of course, we would have to define lots of other methods, too, to make it act like a `Number`, -e.g. `+`, `*`, `one`, `zero`, promotion rules and so on.) By default, instances of this type display -rather simply, with information about the type name and the field values, as e.g. `Polar{Float64}(3.0,4.0)`. +Here, we've added a custom constructor function so that it can take arguments of different +[`Real`](@ref) types and promote them to a common type (see [Constructors](@ref man-constructors) +and [Conversion and Promotion](@ref conversion-and-promotion)). +(Of course, we would have to define lots of other methods, too, to make it act like a +[`Number`](@ref), e.g. `+`, `*`, `one`, `zero`, promotion rules and so on.) By default, +instances of this type display rather simply, with information about the type name and +the field values, as e.g. `Polar{Float64}(3.0,4.0)`. If we want it to display instead as `3.0 * exp(4.0im)`, we would define the following method to print the object to a given output object `io` (representing a file, terminal, buffer, etcetera; @@ -1247,7 +1257,7 @@ julia> show(STDOUT, "text/html", Polar(3.0,4.0)) In Julia, you can't dispatch on a *value* such as `true` or `false`. However, you can dispatch on parametric types, and Julia allows you to include "plain bits" values (Types, Symbols, Integers, floating-point numbers, tuples, etc.) as type parameters. A common example is the dimensionality -parameter in `Array{T,N}`, where `T` is a type (e.g., `Float64`) but `N` is just an `Int`. +parameter in `Array{T,N}`, where `T` is a type (e.g., [`Float64`](@ref)) but `N` is just an `Int`. You can create your own custom types that take values as parameters, and use them to control dispatch of custom types. By way of illustration of this idea, let's introduce a parametric type, `Val{T}`, diff --git a/doc/src/stdlib/linalg.md b/doc/src/stdlib/linalg.md index bee85bb152227..0f415013c51dc 100644 --- a/doc/src/stdlib/linalg.md +++ b/doc/src/stdlib/linalg.md @@ -154,13 +154,13 @@ Base.At_rdiv_Bt In Julia (as in much of scientific computation), dense linear-algebra operations are based on the [LAPACK library](http://www.netlib.org/lapack/), which in turn is built on top of basic linear-algebra -building-blocks known as the [BLAS](http://www.netlib.org/blas/). There are highly optimized +building-blocks known as the [BLAS](http://www.netlib.org/blas/). There are highly optimized implementations of BLAS available for every computer architecture, and sometimes in high-performance linear algebra routines it is useful to call the BLAS functions directly. `Base.LinAlg.BLAS` provides wrappers for some of the BLAS functions. Those BLAS functions that overwrite one of the input arrays have names ending in `'!'`. Usually, a BLAS function has -four methods defined, for `Float64`, `Float32`, `Complex128`, and `Complex64` arrays. +four methods defined, for [`Float64`](@ref), [`Float32`](@ref), `Complex128`, and `Complex64` arrays. ### [BLAS Character Arguments](@id stdlib-blas-chars) Many BLAS functions accept arguments that determine whether to transpose an argument (`trans`), @@ -245,8 +245,8 @@ Base.LinAlg.I `Base.LinAlg.LAPACK` provides wrappers for some of the LAPACK functions for linear algebra. Those functions that overwrite one of the input arrays have names ending in `'!'`. -Usually a function has 4 methods defined, one each for `Float64`, `Float32`, `Complex128` and -`Complex64` arrays. +Usually a function has 4 methods defined, one each for [`Float64`](@ref), [`Float32`](@ref), +`Complex128` and `Complex64` arrays. Note that the LAPACK API provided by Julia can and will change in the future. Since this API is not user-facing, there is no commitment to support/deprecate this specific set of functions in diff --git a/doc/src/stdlib/numbers.md b/doc/src/stdlib/numbers.md index df3a4f63ce637..af00def34e64e 100644 --- a/doc/src/stdlib/numbers.md +++ b/doc/src/stdlib/numbers.md @@ -117,7 +117,8 @@ Base.iseven ## BigFloats -The `BigFloat` type implements arbitrary-precision floating-point arithmetic using the [GNU MPFR library](http://www.mpfr.org/). +The [`BigFloat`](@ref) type implements arbitrary-precision floating-point arithmetic using +the [GNU MPFR library](http://www.mpfr.org/). ```@docs Base.precision @@ -143,10 +144,12 @@ dimension specifications `dims...` (which can be given as a tuple) to generate a values. A `MersenneTwister` or `RandomDevice` RNG can generate random numbers of the following types: -`Float16`, `Float32`, `Float64`, `Bool`, `Int8`, `UInt8`, `Int16`, `UInt16`, `Int32`, `UInt32`, -`Int64`, `UInt64`, `Int128`, `UInt128`, `BigInt` (or complex numbers of those types). Random floating -point numbers are generated uniformly in ``[0, 1)``. As `BigInt` represents unbounded integers, -the interval must be specified (e.g. `rand(big(1:6))`). +[`Float16`](@ref), [`Float32`](@ref), [`Float64`](@ref), [`Bool`](@ref), [`Int8`](@ref), +[`UInt8`](@ref), [`Int16`](@ref), [`UInt16`](@ref), [`Int32`](@ref), [`UInt32`](@ref), +[`Int64`](@ref), [`UInt64`](@ref), [`Int128`](@ref), [`UInt128`](@ref), [`BigInt`](@ref) +(or complex numbers of those types). Random floating point numbers are generated uniformly +in ``[0, 1)``. As `BigInt` represents unbounded integers, the interval must be specified +(e.g. `rand(big(1:6))`). ```@docs Base.Random.srand