From 2435f96f92ebe8635fd3c43efc93c94cc0ed291a Mon Sep 17 00:00:00 2001 From: Michael Abbott <32575566+mcabbott@users.noreply.github.com> Date: Mon, 19 Apr 2021 17:04:42 -0400 Subject: [PATCH] Add many "see also" links to docstrings (#38606) --- base/abstractarray.jl | 82 ++++++++++++++--- base/abstractarraymath.jl | 16 ++-- base/abstractset.jl | 14 ++- base/accumulate.jl | 2 + base/array.jl | 52 ++++++++++- base/bool.jl | 2 + base/combinatorics.jl | 7 ++ base/complex.jl | 17 ++++ base/div.jl | 16 +++- base/docs/basedocs.jl | 90 ++++++++++++++++--- base/essentials.jl | 13 ++- base/file.jl | 10 +++ base/float.jl | 56 +++++++++++- base/hashing.jl | 6 +- base/iddict.jl | 2 +- base/int.jl | 39 +++++++- base/irrationals.jl | 4 +- base/iterators.jl | 32 +++++++ base/math.jl | 48 +++++++++- base/mathconstants.jl | 28 ++++++ base/missing.jl | 4 +- base/multidimensional.jl | 2 + base/number.jl | 38 +++++++- base/operators.jl | 24 ++++- base/permuteddimsarray.jl | 20 +++-- base/promotion.jl | 19 +++- base/reduce.jl | 19 +++- base/reducedim.jl | 4 + base/reflection.jl | 27 +++++- base/set.jl | 11 ++- base/show.jl | 17 +++- base/some.jl | 4 +- base/sort.jl | 6 +- base/special/exp.jl | 18 +++- base/special/trig.jl | 8 ++ base/strings/io.jl | 6 +- base/strings/util.jl | 10 ++- base/threadingconstructs.jl | 8 ++ base/tuple.jl | 4 + doc/src/base/arrays.md | 2 + doc/src/base/base.md | 5 ++ doc/src/base/math.md | 2 + stdlib/Distributed/docs/src/index.md | 2 +- stdlib/InteractiveUtils/docs/src/index.md | 2 +- .../InteractiveUtils/src/InteractiveUtils.jl | 6 ++ stdlib/InteractiveUtils/src/macros.jl | 8 +- stdlib/LinearAlgebra/docs/src/index.md | 1 + stdlib/LinearAlgebra/src/dense.jl | 7 +- stdlib/LinearAlgebra/src/generic.jl | 4 + stdlib/Printf/docs/src/index.md | 2 +- 50 files changed, 747 insertions(+), 79 deletions(-) diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 6552e7128ef8b..45a6118412712 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -8,6 +8,8 @@ Supertype for `N`-dimensional arrays (or array-like types) with elements of type `T`. [`Array`](@ref) and other types are subtypes of this. See the manual section on the [`AbstractArray` interface](@ref man-interface-array). + +See also: [`AbstractVector`](@ref), [`AbstractMatrix`](@ref), [`eltype`](@ref), [`ndims`](@ref). """ AbstractArray @@ -24,6 +26,8 @@ dimension to just get the length of that dimension. Note that `size` may not be defined for arrays with non-standard indices, in which case [`axes`](@ref) may be useful. See the manual chapter on [arrays with custom indices](@ref man-custom-indices). +See also: [`length`](@ref), [`ndims`](@ref), [`eachindex`](@ref), [`sizeof`](@ref). + # Examples ```jldoctest julia> A = fill(1, (2,3,4)); @@ -75,6 +79,8 @@ end Return the tuple of valid indices for array `A`. +See also: [`size`](@ref), [`keys`](@ref), [`eachindex`](@ref). + # Examples ```jldoctest @@ -174,6 +180,8 @@ For dictionary types, this will be a `Pair{KeyType,ValType}`. The definition instead of types. However the form that accepts a type argument should be defined for new types. +See also: [`keytype`](@ref), [`typeof`](@ref). + # Examples ```jldoctest julia> eltype(fill(1f0, (2,2))) @@ -202,6 +210,8 @@ elsize(A::AbstractArray) = elsize(typeof(A)) Return the number of dimensions of `A`. +See also: [`size`](@ref), [`axes`](@ref). + # Examples ```jldoctest julia> A = fill(1, (3,4,5)); @@ -220,6 +230,8 @@ Return the number of elements in the collection. Use [`lastindex`](@ref) to get the last valid index of an indexable collection. +See also: [`size`](@ref), [`ndims`](@ref), [`eachindex`](@ref). + # Examples ```jldoctest julia> length(1:5) @@ -336,6 +348,8 @@ Return the last index of `collection`. If `d` is given, return the last index of The syntaxes `A[end]` and `A[end, end]` lower to `A[lastindex(A)]` and `A[lastindex(A, 1), lastindex(A, 2)]`, respectively. +See also: [`axes`](@ref), [`firstindex`](@ref), [`eachindex`](@ref), [`prevind`](@ref). + # Examples ```jldoctest julia> lastindex([1,2,4]) @@ -354,6 +368,11 @@ lastindex(a, d) = (@_inline_meta; last(axes(a, d))) Return the first index of `collection`. If `d` is given, return the first index of `collection` along dimension `d`. +The syntaxes `A[begin]` and `A[1, begin]` lower to `A[firstindex(A)]` and +`A[1, firstindex(A, 2)]`, respectively. + +See also: [`first`](@ref), [`axes`](@ref), [`lastindex`](@ref), [`nextind`](@ref). + # Examples ```jldoctest julia> firstindex([1,2,4]) @@ -374,6 +393,8 @@ first(a::AbstractArray) = a[first(eachindex(a))] Get the first element of an iterable collection. Return the start point of an [`AbstractRange`](@ref) even if it is empty. +See also: [`only`](@ref), [`firstindex`](@ref), [`last`](@ref). + # Examples ```jldoctest julia> first(2:2:10) @@ -395,6 +416,8 @@ end Get the first `n` elements of the iterable collection `itr`, or fewer elements if `itr` is not long enough. +See also: [`startswith`](@ref), [`Iterators.take`](@ref). + !!! compat "Julia 1.6" This method requires at least Julia 1.6. @@ -426,6 +449,8 @@ Get the last element of an ordered collection, if it can be computed in O(1) tim accomplished by calling [`lastindex`](@ref) to get the last index. Return the end point of an [`AbstractRange`](@ref) even if it is empty. +See also [`first`](@ref), [`endswith`](@ref). + # Examples ```jldoctest julia> last(1:2:10) @@ -472,6 +497,8 @@ end Return a tuple of the memory strides in each dimension. +See also: [`stride`](@ref). + # Examples ```jldoctest julia> A = fill(1, (3,4,5)); @@ -487,6 +514,8 @@ function strides end Return the distance in memory (in number of elements) between adjacent elements in dimension `k`. +See also: [`strides`](@ref). + # Examples ```jldoctest julia> A = fill(1, (3,4,5)); @@ -660,6 +689,8 @@ Return `true` if the given `index` is within the bounds of arrays can extend this method in order to provide a specialized bounds checking implementation. +See also [`checkbounds`](@ref). + # Examples ```jldoctest julia> checkindex(Bool, 1:20, 8) @@ -735,6 +766,7 @@ julia> similar(falses(10), Float64, 2, 4) 2.18425e-314 2.18425e-314 2.18425e-314 2.18425e-314 ``` +See also: [`undef`](@ref), [`isassigned`](@ref). """ similar(a::AbstractArray{T}) where {T} = similar(a, T) similar(a::AbstractArray, ::Type{T}) where {T} = similar(a, T, to_shape(axes(a))) @@ -791,6 +823,8 @@ similar(::Type{T}, dims::Dims) where {T<:AbstractArray} = T(undef, dims) Create an empty vector similar to `v`, optionally changing the `eltype`. +See also: [`empty!`](@ref), [`isempty`](@ref), [`isassigned`](@ref). + # Examples ```jldoctest @@ -815,6 +849,7 @@ elements in `dst`. If `dst` and `src` are of the same type, `dst == src` should hold after the call. If `dst` and `src` are multidimensional arrays, they must have equal [`axes`](@ref). + See also [`copyto!`](@ref). !!! compat "Julia 1.1" @@ -922,11 +957,12 @@ end """ copyto!(dest::AbstractArray, src) -> dest - Copy all elements from collection `src` to array `dest`, whose length must be greater than or equal to the length `n` of `src`. The first `n` elements of `dest` are overwritten, the other elements are left untouched. +See also [`copy!`](@ref Base.copy!), [`copy`](@ref). + # Examples ```jldoctest julia> x = [1., 0., 3., 0., 5.]; @@ -2130,18 +2166,28 @@ end foreach(f, c...) -> Nothing Call function `f` on each element of iterable `c`. -For multiple iterable arguments, `f` is called elementwise. -`foreach` should be used instead of `map` when the results of `f` are not +For multiple iterable arguments, `f` is called elementwise, and iteration stops when +any iterator is finished. + +`foreach` should be used instead of [`map`](@ref) when the results of `f` are not needed, for example in `foreach(println, array)`. # Examples ```jldoctest -julia> a = 1:3:7; +julia> tri = 1:3:7; res = Int[]; -julia> foreach(x -> println(x^2), a) -1 -16 -49 +julia> foreach(x -> push!(res, x^2), tri) + +julia> res +3-element Vector{$(Int)}: + 1 + 16 + 49 + +julia> foreach((x, y) -> println(x, " with ", y), tri, 'a':'z') +1 with a +4 with b +7 with c ``` """ foreach(f) = (f(); nothing) @@ -2162,6 +2208,8 @@ colons go in this expression. The results are concatenated along the remaining d For example, if `dims` is `[1,2]` and `A` is 4-dimensional, `f` is called on `A[:,:,i,j]` for all `i` and `j`. +See also [`eachcol`](@ref), [`eachslice`](@ref). + # Examples ```jldoctest julia> a = reshape(Vector(1:16),(2,2,2,2)) @@ -2308,9 +2356,9 @@ mapany(f, itr) = Any[f(x) for x in itr] map(f, c...) -> collection Transform collection `c` by applying `f` to each element. For multiple collection arguments, -apply `f` elementwise. +apply `f` elementwise, and stop when when any of them is exhausted. -See also: [`mapslices`](@ref) +See also: [`map!`](@ref), [`foreach`](@ref), [`mapreduce`](@ref), [`mapslices`](@ref), [`zip`](@ref), [`Iterators.map`](@ref). # Examples ```jldoctest @@ -2320,7 +2368,7 @@ julia> map(x -> x * 2, [1, 2, 3]) 4 6 -julia> map(+, [1, 2, 3], [10, 20, 30]) +julia> map(+, [1, 2, 3], [10, 20, 30, 400, 5000]) 3-element Vector{Int64}: 11 22 @@ -2365,7 +2413,9 @@ end map!(function, destination, collection...) Like [`map`](@ref), but stores the result in `destination` rather than a new -collection. `destination` must be at least as large as the first collection. +collection. `destination` must be at least as large as the smallest collection. + +See also: [`map`](@ref), [`foreach`](@ref), [`zip`](@ref), [`copyto!`](@ref). # Examples ```jldoctest @@ -2378,6 +2428,14 @@ julia> a 2.0 4.0 6.0 + +julia> map!(+, zeros(Int, 5), 100:999, 1:3) +5-element Vector{$(Int)}: + 101 + 103 + 105 + 0 + 0 ``` """ function map!(f::F, dest::AbstractArray, As::AbstractArray...) where {F} diff --git a/base/abstractarraymath.jl b/base/abstractarraymath.jl index b14c4816c8178..3545d33ec5cf5 100644 --- a/base/abstractarraymath.jl +++ b/base/abstractarraymath.jl @@ -36,7 +36,7 @@ julia> vec(1:3) 1:3 ``` -See also [`reshape`](@ref). +See also [`reshape`](@ref), [`dropdims`](@ref). """ vec(a::AbstractArray) = reshape(a,length(a)) vec(a::AbstractVector) = a @@ -52,6 +52,8 @@ Remove the dimensions specified by `dims` from array `A`. Elements of `dims` must be unique and within the range `1:ndims(A)`. `size(A,i)` must equal 1 for all `i` in `dims`. +See also: [`reshape`](@ref), [`vec`](@ref). + # Examples ```jldoctest julia> a = reshape(Vector(1:4),(2,2,1,1)) @@ -106,6 +108,8 @@ Return a view of all the data of `A` where the index for dimension `d` equals `i Equivalent to `view(A,:,:,...,i,:,:,...)` where `i` is in position `d`. +See also: [`eachslice`](@ref). + # Examples ```jldoctest julia> A = [1 2 3 4; 5 6 7 8] @@ -143,6 +147,8 @@ Circularly shift, i.e. rotate, the data in an array. The second argument is a tu vector giving the amount to shift in each dimension, or an integer to shift only in the first dimension. +See also: [`circshift!`](@ref), [`circcopy!`](@ref), [`bitrotate`](@ref), [`<<`](@ref). + # Examples ```jldoctest julia> b = reshape(Vector(1:16), (4,4)) @@ -190,8 +196,6 @@ julia> circshift(a, -1) 1 1 ``` - -See also [`circshift!`](@ref). """ function circshift(a::AbstractArray, shiftamt) circshift!(similar(a), a, map(Integer, (shiftamt...,))) @@ -204,6 +208,8 @@ end Construct an array by repeating array `A` a given number of times in each dimension, specified by `counts`. +See also: [`fill`](@ref), [`Iterators.repeated`](@ref), [`Iterators.cycle`](@ref). + # Examples ```jldoctest julia> repeat([1, 2, 3], 2) @@ -397,7 +403,7 @@ end#module Create a generator that iterates over the first dimension of vector or matrix `A`, returning the rows as `AbstractVector` views. -See also [`eachcol`](@ref) and [`eachslice`](@ref). +See also [`eachcol`](@ref), [`eachslice`](@ref), [`mapslices`](@ref). !!! compat "Julia 1.1" This function requires at least Julia 1.1. @@ -465,7 +471,7 @@ the data from the other dimensions in `A`. Only a single dimension in `dims` is currently supported. Equivalent to `(view(A,:,:,...,i,:,: ...)) for i in axes(A, dims))`, where `i` is in position `dims`. -See also [`eachrow`](@ref), [`eachcol`](@ref), and [`selectdim`](@ref). +See also [`eachrow`](@ref), [`eachcol`](@ref), [`mapslices`](@ref), and [`selectdim`](@ref). !!! compat "Julia 1.1" This function requires at least Julia 1.1. diff --git a/base/abstractset.jl b/base/abstractset.jl index 659417b7bfd4e..697a1ca275aae 100644 --- a/base/abstractset.jl +++ b/base/abstractset.jl @@ -13,6 +13,8 @@ copy!(dst::AbstractSet, src::AbstractSet) = union!(empty!(dst), src) Construct the union of sets. Maintain order with arrays. +See also: [`intersect`](@ref), [`isdisjoint`](@ref), [`vcat`](@ref), [`Iterators.flatten`](@ref). + # Examples ```jldoctest julia> union([1, 2], [3, 4]) @@ -101,6 +103,8 @@ end Construct the intersection of sets. Maintain order with arrays. +See also: [`setdiff`](@ref), [`isdisjoint`](@ref), [`issubset`](@ref Base.issubset), [`issetequal`](@ref). + # Examples ```jldoctest julia> intersect([1, 2, 3], [3, 4, 5]) @@ -145,6 +149,8 @@ intersect!(s::AbstractSet, itr) = Construct the set of elements in `s` but not in any of the iterables in `itrs`. Maintain order with arrays. +See also [`setdiff!`](@ref), [`union`](@ref) and [`intersect`](@ref). + # Examples ```jldoctest julia> setdiff([1,2,3], [3,4,5]) @@ -194,6 +200,8 @@ Construct the symmetric difference of elements in the passed in sets. When `s` is not an `AbstractSet`, the order is maintained. Note that in this case the multiplicity of elements matters. +See also [`symdiff!`](@ref), [`setdiff`](@ref), [`union`](@ref) and [`intersect`](@ref). + # Examples ```jldoctest julia> symdiff([1,2,3], [3,4,5], [4,5,6]) @@ -246,7 +254,7 @@ function ⊇ end Determine whether every element of `a` is also in `b`, using [`in`](@ref). -See also [`⊊`](@ref), [`⊈`](@ref). +See also [`⊊`](@ref), [`⊈`](@ref), [`∩`](@ref intersect), [`∪`](@ref union), [`contains`](@ref). # Examples ```jldoctest @@ -357,6 +365,8 @@ false Determine whether `a` and `b` have the same elements. Equivalent to `a ⊆ b && b ⊆ a` but more efficient when possible. +See also: [`isdisjoint`](@ref), [`union`](@ref). + # Examples ```jldoctest julia> issetequal([1, 2], [1, 2, 3]) @@ -390,6 +400,8 @@ end Return whether the collections `v1` and `v2` are disjoint, i.e. whether their intersection is empty. +See also: [`issetequal`](@ref), [`intersect`](@ref). + !!! compat "Julia 1.5" This function requires at least Julia 1.5. """ diff --git a/base/accumulate.jl b/base/accumulate.jl index f90f85b315d7c..c1ec372de9033 100644 --- a/base/accumulate.jl +++ b/base/accumulate.jl @@ -204,6 +204,8 @@ Cumulative product of an iterator. See also [`cumprod!`](@ref) to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). +See also [`cumprod!`](@ref), [`accumulate`](@ref), [`cumsum`](@ref). + !!! compat "Julia 1.5" `cumprod` on a non-array iterator requires at least Julia 1.5. diff --git a/base/array.jl b/base/array.jl index 7fd3ea8fb0bc2..c17d832d391f1 100644 --- a/base/array.jl +++ b/base/array.jl @@ -54,6 +54,8 @@ Array One-dimensional dense array with elements of type `T`, often used to represent a mathematical vector. Alias for [`Array{T,1}`](@ref). + +See also [`empty`](@ref), [`similar`](@ref) and [`zero`](@ref) for creating vectors. """ const Vector{T} = Array{T,1} @@ -62,6 +64,9 @@ const Vector{T} = Array{T,1} Two-dimensional dense array with elements of type `T`, often used to represent a mathematical matrix. Alias for [`Array{T,2}`](@ref). + +See also [`fill`](@ref), [`zeros`](@ref), [`undef`](@ref) and [`similar`](@ref) +for creating matrices. """ const Matrix{T} = Array{T,2} @@ -356,6 +361,8 @@ end Create a shallow copy of `x`: the outer structure is copied, but not all internal values. For example, copying an array produces a new array with identically-same elements as the original. + +See also [`copy!`](@ref Base.copy!), [`copyto!`](@ref). """ copy @@ -433,6 +440,8 @@ array of floats, with each element initialized to `1.0`. `dims` may be specified as either a tuple or a sequence of arguments. For example, the common idiom `fill(x)` creates a zero-dimensional array containing the single value `x`. +See also: [`fill!`](@ref), [`zeros`](@ref), [`ones`](@ref), [`similar`](@ref). + # Examples ```jldoctest julia> fill(1.0, (2,3)) @@ -469,7 +478,7 @@ fill(v, dims::Tuple{}) = (a=Array{typeof(v),0}(undef, dims); fill!(a, v); a) zeros([T=Float64,] dims...) Create an `Array`, with element type `T`, of all zeros with size specified by `dims`. -See also [`fill`](@ref), [`ones`](@ref). +See also [`fill`](@ref), [`ones`](@ref), [`zero`](@ref). # Examples ```jldoctest @@ -600,6 +609,8 @@ Return an `Array` of all items in a collection or iterator. For dictionaries, re [`HasShape`](@ref IteratorSize) trait, the result will have the same shape and number of dimensions as the argument. +Used by comprehensions to turn a generator into an `Array`. + # Examples ```jldoctest julia> collect(1:2:13) @@ -611,6 +622,13 @@ julia> collect(1:2:13) 9 11 13 + +julia> [x^2 for x in 1:8 if isodd(x)] +4-element Vector{Int64}: + 1 + 9 + 25 + 49 ``` """ collect(itr) = _collect(1:1 #= Array =#, itr, IteratorEltype(itr), IteratorSize(itr)) @@ -934,6 +952,8 @@ collection to it. The result of the preceding example is equivalent to `append!( 5, 6])`. For `AbstractSet` objects, [`union!`](@ref) can be used instead. See [`sizehint!`](@ref) for notes about the performance model. + +See also [`pushfirst!`](@ref). """ function push! end @@ -983,6 +1003,9 @@ themselves in another collection. The result of the preceding example is equival `push!([1, 2, 3], 4, 5, 6)`. See [`sizehint!`](@ref) for notes about the performance model. + +See also [`vcat`](@ref) for vectors, [`union!`](@ref) for sets, +and [`prepend!`](@ref) and [`pushfirst!`](@ref) for the opposite order. """ function append!(a::Vector, items::AbstractVector) itemindices = eachindex(items) @@ -1157,6 +1180,8 @@ Remove an item in `collection` and return it. If `collection` is an ordered container, the last item is returned; for unordered containers, an arbitrary element is returned. +See also: [`popfirst!`](@ref), [`popat!`](@ref), [`delete!`](@ref), [`deleteat!`](@ref), [`splice!`](@ref), and [`push!`](@ref). + # Examples ```jldoctest julia> A=[1, 2, 3] @@ -1205,7 +1230,8 @@ Remove the item at the given `i` and return it. Subsequent items are shifted to fill the resulting gap. When `i` is not a valid index for `a`, return `default`, or throw an error if `default` is not specified. -See also [`deleteat!`](@ref) and [`splice!`](@ref). + +See also: [`pop!`](@ref), [`popfirst!`](@ref), [`deleteat!`](@ref), [`splice!`](@ref). !!! compat "Julia 1.5" This function is available as of Julia 1.5. @@ -1278,6 +1304,8 @@ Remove the first `item` from `collection`. This function is called `shift` in many other programming languages. +See also: [`pop!`](@ref), [`popat!`](@ref), [`delete!`](@ref). + # Examples ```jldoctest julia> A = [1, 2, 3, 4, 5, 6] @@ -1316,6 +1344,8 @@ end Insert an `item` into `a` at the given `index`. `index` is the index of `item` in the resulting `a`. +See also: [`push!`](@ref), [`replace`](@ref), [`popat!`](@ref), [`splice!`](@ref). + # Examples ```jldoctest julia> insert!([6, 5, 4, 2, 1], 4, 3) @@ -1343,6 +1373,8 @@ end Remove the item at the given `i` and return the modified `a`. Subsequent items are shifted to fill the resulting gap. +See also: [`delete!`](@ref), [`popat!`](@ref), [`splice!`](@ref). + # Examples ```jldoctest julia> deleteat!([6, 5, 4, 3, 2, 1], 2) @@ -1454,6 +1486,8 @@ Subsequent items are shifted left to fill the resulting gap. If specified, replacement values from an ordered collection will be spliced in place of the removed item. +See also: [`replace`](@ref), [`delete!`](@ref), [`deleteat!`](@ref), [`pop!`](@ref), [`popat!`](@ref). + # Examples ```jldoctest julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5) @@ -1603,7 +1637,7 @@ end reverse(v [, start=1 [, stop=length(v) ]] ) Return a copy of `v` reversed from start to stop. See also [`Iterators.reverse`](@ref) -for reverse-order iteration without making a copy. +for reverse-order iteration without making a copy, and in-place [`reverse!`](@ref). # Examples ```jldoctest @@ -1806,6 +1840,8 @@ To search for other kinds of values, pass a predicate as the first argument. Indices or keys are of the same type as those returned by [`keys(A)`](@ref) and [`pairs(A)`](@ref). +See also: [`findall`](@ref), [`findnext`](@ref), [`findlast`](@ref), [`searchsortedfirst`](@ref). + # Examples ```jldoctest julia> A = [false, false, true, false] @@ -1947,6 +1983,8 @@ or `nothing` if not found. Indices are of the same type as those returned by [`keys(A)`](@ref) and [`pairs(A)`](@ref). +See also: [`findnext`](@ref), [`findfirst`](@ref), [`findall`](@ref). + # Examples ```jldoctest julia> A = [false, false, true, true] @@ -1992,6 +2030,8 @@ Return `nothing` if there is no `true` value in `A`. Indices or keys are of the same type as those returned by [`keys(A)`](@ref) and [`pairs(A)`](@ref). +See also: [`findfirst`](@ref), [`findprev`](@ref), [`findall`](@ref). + # Examples ```jldoctest julia> A = [true, false, true, false] @@ -2184,6 +2224,8 @@ To search for other kinds of values, pass a predicate as the first argument. Indices or keys are of the same type as those returned by [`keys(A)`](@ref) and [`pairs(A)`](@ref). +See also: [`findfirst`](@ref), [`searchsorted`](@ref). + # Examples ```jldoctest julia> A = [true, false, false, true] @@ -2241,6 +2283,8 @@ Return an array containing the first index in `b` for each value in `a` that is a member of `b`. The output array contains `nothing` wherever `a` is not a member of `b`. +See also: [`sortperm`](@ref), [`findfirst`](@ref). + # Examples ```jldoctest julia> a = ['a', 'b', 'c', 'b', 'd', 'a']; @@ -2374,6 +2418,8 @@ The function `f` is passed one argument. !!! compat "Julia 1.4" Support for `a` as a tuple requires at least Julia 1.4. +See also: [`filter!`](@ref), [`Iterators.filter`](@ref). + # Examples ```jldoctest julia> a = 1:10 diff --git a/base/bool.jl b/base/bool.jl index 297aa1863a64e..d42cfb0603279 100644 --- a/base/bool.jl +++ b/base/bool.jl @@ -14,6 +14,8 @@ typemax(::Type{Bool}) = true Boolean not. Implements [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic), returning [`missing`](@ref) if `x` is `missing`. +See also [`~`](@ref) for bitwise not. + # Examples ```jldoctest julia> !true diff --git a/base/combinatorics.jl b/base/combinatorics.jl index 7411de5b40043..daa534e068af6 100644 --- a/base/combinatorics.jl +++ b/base/combinatorics.jl @@ -228,8 +228,15 @@ invpermute!(a, p::AbstractVector) = invpermute!!(a, copymutable(p)) Return the inverse permutation of `v`. If `B = A[v]`, then `A == B[invperm(v)]`. +See also [`sortperm`](@ref), [`invpermute!`](@ref), [`isperm`](@ref), [`permutedims`](@ref). + # Examples ```jldoctest +julia> p = (2, 3, 1); + +julia> invperm(p) +(3, 1, 2) + julia> v = [2; 4; 3; 1]; julia> invperm(v) diff --git a/base/complex.jl b/base/complex.jl index 7cf266f2bc4de..4fe736a7c0465 100644 --- a/base/complex.jl +++ b/base/complex.jl @@ -7,6 +7,8 @@ Complex number type with real and imaginary part of type `T`. `ComplexF16`, `ComplexF32` and `ComplexF64` are aliases for `Complex{Float16}`, `Complex{Float32}` and `Complex{Float64}` respectively. + +See also: [`Real`](@ref), [`complex`](@ref), [`real`](@ref). """ struct Complex{T<:Real} <: Number re::T @@ -20,10 +22,15 @@ Complex(x::Real) = Complex(x, zero(x)) The imaginary unit. +See also: [`imag`](@ref), [`angle`](@ref), [`complex`](@ref). + # Examples ```jldoctest julia> im * im -1 + 0im + +julia> (2.0 + 3im)^2 +-5.0 + 12.0im ``` """ const im = Complex(false, true) @@ -54,6 +61,8 @@ float(::Type{Complex{T}}) where {T} = Complex{float(T)} Return the real part of the complex number `z`. +See also: [`imag`](@ref), [`reim`](@ref), [`complex`](@ref), [`isreal`](@ref), [`Real`](@ref). + # Examples ```jldoctest julia> real(1 + 3im) @@ -67,6 +76,8 @@ real(z::Complex) = z.re Return the imaginary part of the complex number `z`. +See also: [`conj`](@ref), [`reim`](@ref), [`adjoint`](@ref), [`angle`](@ref). + # Examples ```jldoctest julia> imag(1 + 3im) @@ -254,6 +265,8 @@ end Compute the complex conjugate of a complex number `z`. +See also: [`angle`](@ref), [`adjoint`](@ref). + # Examples ```jldoctest julia> conj(1 + 3im) @@ -533,6 +546,8 @@ end Return ``\\exp(iz)``. +See also [`cispi`](@ref), [`angle`](@ref). + # Examples ```jldoctest julia> cis(π) ≈ -1 @@ -574,6 +589,8 @@ end Compute the phase angle in radians of a complex number `z`. +See also: [`atan`](@ref), [`cis`](@ref). + # Examples ```jldoctest julia> rad2deg(angle(1 + im)) diff --git a/base/div.jl b/base/div.jl index d78220c530608..8b8361c4150ed 100644 --- a/base/div.jl +++ b/base/div.jl @@ -88,12 +88,16 @@ rem(x::Integer, y::Integer, r::RoundingMode{:Nearest}) = divrem(x, y, r)[2] Largest integer less than or equal to `x/y`. Equivalent to `div(x, y, RoundDown)`. -See also: [`div`](@ref) +See also: [`div`](@ref), [`cld`](@ref), [`fld1`](@ref). # Examples ```jldoctest julia> fld(7.3,5.5) 1.0 + +julia> fld.(-5:5, 3)' +1×11 adjoint(::Vector{Int64}) with eltype Int64: + -2 -2 -1 -1 -1 0 0 0 1 1 1 ``` Because `fld(x, y)` implements strictly correct floored rounding based on the true value of floating-point numbers, unintuitive situations can arise. For example: @@ -118,12 +122,16 @@ fld(a, b) = div(a, b, RoundDown) Smallest integer larger than or equal to `x/y`. Equivalent to `div(x, y, RoundUp)`. -See also: [`div`](@ref) +See also: [`div`](@ref), [`fld`](@ref). # Examples ```jldoctest julia> cld(5.5,2.2) 3.0 + +julia> cld.(-5:5, 3)' +1×11 adjoint(::Vector{Int64}) with eltype Int64: + -1 -1 -1 0 0 0 1 1 1 2 2 ``` """ cld(a, b) = div(a, b, RoundUp) @@ -136,6 +144,8 @@ The quotient and remainder from Euclidean division. Equivalent to `(div(x,y,r), rem(x,y,r))`. Equivalently, with the default value of `r`, this call is equivalent to `(x÷y, x%y)`. +See also: [`fldmod`](@ref), [`cld`](@ref). + # Examples ```jldoctest julia> divrem(3,7) @@ -211,6 +221,8 @@ end The floored quotient and modulus after division. A convenience wrapper for `divrem(x, y, RoundDown)`. Equivalent to `(fld(x,y), mod(x,y))`. + +See also: [`fld`](@ref), [`cld`](@ref), [`fldmod1`](@ref). """ fldmod(x,y) = divrem(x, y, RoundDown) diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl index 6c29a25aae3d9..d7c944ffed78c 100644 --- a/base/docs/basedocs.jl +++ b/base/docs/basedocs.jl @@ -718,7 +718,7 @@ See the manual section on [control flow](@ref man-conditional-evaluation) for mo ``` julia> x = 1; y = 2; -julia> println(x > y ? "x is larger" : "y is larger") +julia> x > y ? println("x is larger") : println("y is larger") y is larger ``` """ @@ -976,6 +976,19 @@ kw";" x && y Short-circuiting boolean AND. + +See also [`&`](@ref), the ternary operator `? :`, and the manual section on [control flow](@ref man-conditional-evaluation). + +# Examples +```jldoctest +julia> x = 3; + +julia> x > 1 && x < 10 && x isa Int +true + +julia> x < 0 && error("expected positive x") +false +``` """ kw"&&" @@ -983,6 +996,17 @@ kw"&&" x || y Short-circuiting boolean OR. + +See also: [`|`](@ref), [`xor`](@ref), [`&&`](@ref). + +# Examples +```jldoctest +julia> pi < 3 || ℯ < 3 +true + +julia> false || true || println("neither is true!") +true +``` """ kw"||" @@ -1206,6 +1230,8 @@ devnull Nothing A type with no fields that is the type of [`nothing`](@ref). + +See also: [`isnothing`](@ref), [`Some`](@ref), [`Missing`](@ref). """ Nothing @@ -1214,6 +1240,8 @@ Nothing The singleton instance of type [`Nothing`](@ref), used by convention when there is no value to return (as in a C `void` function) or when a variable or field holds no value. + +See also: [`isnothing`](@ref), [`something`](@ref), [`missing`](@ref). """ nothing @@ -1756,6 +1784,8 @@ NaN julia> false * NaN 0.0 ``` + +See also: [`digits`](@ref), [`iszero`](@ref), [`NaN`](@ref). """ Bool @@ -1842,10 +1872,18 @@ Symbol(x...) Construct a tuple of the given objects. +See also [`Tuple`](@ref), [`NamedTuple`](@ref). + # Examples ```jldoctest -julia> tuple(1, 'a', pi) -(1, 'a', π) +julia> tuple(1, 'b', pi) +(1, 'b', π) + +julia> ans === (1, 'b', π) +true + +julia> Tuple(Real[1, 2, pi]) # takes a collection +(1, 2, π) ``` """ tuple @@ -1908,6 +1946,8 @@ setfield! Get the concrete type of `x`. +See also [`eltype`](@ref). + # Examples ```jldoctest julia> a = 1//2; @@ -1964,7 +2004,7 @@ isdefined """ Vector{T}(undef, n) -Construct an uninitialized [`Vector{T}`](@ref) of length `n`. See [`undef`](@ref). +Construct an uninitialized [`Vector{T}`](@ref) of length `n`. # Examples ```julia-repl @@ -2014,14 +2054,19 @@ Vector{T}(::Missing, n) """ Matrix{T}(undef, m, n) -Construct an uninitialized [`Matrix{T}`](@ref) of size `m`×`n`. See [`undef`](@ref). +Construct an uninitialized [`Matrix{T}`](@ref) of size `m`×`n`. # Examples ```julia-repl julia> Matrix{Float64}(undef, 2, 3) 2×3 Array{Float64, 2}: - 6.93517e-310 6.93517e-310 6.93517e-310 - 6.93517e-310 6.93517e-310 1.29396e-320 + 2.36365e-314 2.28473e-314 5.0e-324 + 2.26704e-314 2.26711e-314 NaN + +julia> similar(ans, Int32, 2, 2) +2×2 Matrix{Int32}: + 490537216 1277177453 + 1 1936748399 ``` """ Matrix{T}(::UndefInitializer, m, n) @@ -2069,19 +2114,28 @@ containing elements of type `T`. `N` can either be supplied explicitly, as in `Array{T,N}(undef, dims)`, or be determined by the length or number of `dims`. `dims` may be a tuple or a series of integer arguments corresponding to the lengths in each dimension. If the rank `N` is supplied explicitly, then it must -match the length or number of `dims`. See [`undef`](@ref). +match the length or number of `dims`. Here [`undef`](@ref) is +the [`UndefInitializer`](@ref). # Examples ```julia-repl julia> A = Array{Float64, 2}(undef, 2, 3) # N given explicitly -2×3 Array{Float64, 2}: +2×3 Matrix{Float64}: 6.90198e-310 6.90198e-310 6.90198e-310 6.90198e-310 6.90198e-310 0.0 -julia> B = Array{Float64}(undef, 2) # N determined by the input -2-element Array{Float64, 1}: - 1.87103e-320 - 0.0 +julia> B = Array{Float64}(undef, 4) # N determined by the input +4-element Vector{Float64}: + 2.360075077e-314 + NaN + 2.2671131793e-314 + 2.299821756e-314 + +julia> similar(B, 2, 4, 1) # use typeof(B), and the given size +2×4×1 Array{Float64, 3}: +[:, :, 1] = + 2.26703e-314 2.26708e-314 0.0 2.80997e-314 + 0.0 2.26703e-314 2.26708e-314 0.0 ``` """ Array{T,N}(::UndefInitializer, dims) @@ -2158,10 +2212,12 @@ Alias for `UndefInitializer()`, which constructs an instance of the singleton ty [`UndefInitializer`](@ref), used in array initialization to indicate the array-constructor-caller would like an uninitialized array. +See also: [`missing`](@ref), [`similar`](@ref). + # Examples ```julia-repl julia> Array{Float64, 1}(undef, 3) -3-element Array{Float64, 1}: +3-element Vector{Float64}: 2.2752528595e-314 2.202942107e-314 2.275252907e-314 @@ -2197,6 +2253,8 @@ julia> +(1, 20, 4) Unary minus operator. +See also: [`abs`](@ref), [`flipsign`](@ref). + # Examples ```jldoctest julia> -1 @@ -2408,6 +2466,8 @@ number of trailing elements. `Vararg{T,N}` corresponds to exactly `N` elements o `Vararg{T}` corresponds to zero or more elements of type `T`. `Vararg` tuple types are used to represent the arguments accepted by varargs methods (see the section on [Varargs Functions](@ref) in the manual.) +See also [`NTuple`](@ref). + # Examples ```jldoctest julia> mytupletype = Tuple{AbstractString, Vararg{Int}} @@ -2440,6 +2500,8 @@ is considered an abstract type, and tuple types are only concrete if their param field names; fields are only accessed by index. See the manual section on [Tuple Types](@ref). + +See also [`Vararg`](@ref), [`NTuple`](@ref), [`tuple`](@ref), [`NamedTuple`](@ref). """ Tuple diff --git a/base/essentials.jl b/base/essentials.jl index c92167c553cb7..d9a9ab4b0d721 100644 --- a/base/essentials.jl +++ b/base/essentials.jl @@ -131,7 +131,8 @@ end Tests whether variable `s` is defined in the current scope. -See also [`isdefined`](@ref). +See also [`isdefined`](@ref) for field properties and [`isassigned`](@ref) for +array indexes or [`haskey`](@ref) for other mappings. # Examples ```jldoctest @@ -217,6 +218,8 @@ julia> y = convert(Vector{Int}, x); julia> y === x true ``` + +See also: [`round`](@ref), [`trunc`](@ref), [`oftype`](@ref), [`reinterpret`](@ref). """ function convert end @@ -249,6 +252,8 @@ argtail(x, rest...) = rest Return a `Tuple` consisting of all but the first component of `x`. +See also: [`front`](@ref Base.front), [`rest`](@ref Base.rest), [`first`](@ref), [`Iterators.peel`](@ref). + # Examples ```jldoctest julia> Base.tail((1,2,3)) @@ -809,6 +814,8 @@ values(itr) = itr A type with no fields whose singleton instance [`missing`](@ref) is used to represent missing values. + +See also: [`skipmissing`](@ref), [`nonmissingtype`](@ref), [`Nothing`](@ref). """ struct Missing end @@ -816,6 +823,8 @@ struct Missing end missing The singleton instance of type [`Missing`](@ref) representing a missing value. + +See also: [`NaN`](@ref), [`skipmissing`](@ref), [`nonmissingtype`](@ref). """ const missing = Missing() @@ -823,6 +832,8 @@ const missing = Missing() ismissing(x) Indicate whether `x` is [`missing`](@ref). + +See also: [`skipmissing`](@ref), [`isnothing`](@ref), [`isnan`](@ref). """ ismissing(x) = x === missing diff --git a/base/file.jl b/base/file.jl index e1e323700344f..3a038863107bc 100644 --- a/base/file.jl +++ b/base/file.jl @@ -34,6 +34,8 @@ export Get the current working directory. +See also: [`cd`](@ref), [`tempdir`](@ref). + # Examples ```julia-repl julia> pwd() @@ -67,6 +69,8 @@ end Set the current working directory. +See also: [`pwd`](@ref), [`mkdir`](@ref), [`mkpath`](@ref), [`mktempdir`](@ref). + # Examples ```julia-repl julia> cd("/home/JuliaUser/Projects/julia") @@ -673,6 +677,8 @@ the temporary directory is automatically deleted when the process exits. The `cleanup` keyword argument was added in Julia 1.3. Relatedly, starting from 1.3, Julia will remove the temporary paths created by `mktempdir` when the Julia process exits, unless `cleanup` is explicitly set to `false`. + +See also: [`mktemp`](@ref), [`mkdir`](@ref). """ function mktempdir(parent::AbstractString=tempdir(); prefix::AbstractString=temp_prefix, cleanup::Bool=true) @@ -707,6 +713,8 @@ end Apply the function `f` to the result of [`mktemp(parent)`](@ref) and remove the temporary file upon completion. + +See also: [`mktempdir`](@ref). """ function mktemp(fn::Function, parent::AbstractString=tempdir()) (tmp_path, tmp_io) = mktemp(parent, cleanup=false) @@ -730,6 +738,8 @@ end Apply the function `f` to the result of [`mktempdir(parent; prefix)`](@ref) and remove the temporary directory all of its contents upon completion. +See also: [`mktemp`](@ref), [`mkdir`](@ref). + !!! compat "Julia 1.2" The `prefix` keyword argument was added in Julia 1.2. """ diff --git a/base/float.jl b/base/float.jl index cb4000b51fac2..7344be40660d5 100644 --- a/base/float.jl +++ b/base/float.jl @@ -36,6 +36,20 @@ const Inf = Inf64 Inf, Inf64 Positive infinity of type [`Float64`](@ref). + +See also: [`isfinite`](@ref), [`typemax`](@ref), [`NaN`](@ref), [`Inf32`](@ref). + +# Examples +```jldoctest +julia> π/0 +Inf + +julia> +1.0 / -0.0 +-Inf + +julia> ℯ^-Inf +0.0 +``` """ Inf, Inf64 @@ -44,6 +58,20 @@ const NaN = NaN64 NaN, NaN64 A not-a-number value of type [`Float64`](@ref). + +See also: [`isnan`](@ref), [`missing`](@ref), [`NaN32`](@ref), [`Inf`](@ref). + +# Examples +```jldoctest +julia> 0/0 +NaN + +julia> Inf - Inf +NaN + +julia> NaN == NaN, isequal(NaN, NaN), NaN === NaN +(false, true, true) +``` """ NaN, NaN64 @@ -226,6 +254,17 @@ Bool(x::Float16) = x==0 ? false : x==1 ? true : throw(InexactError(:Bool, Bool, float(x) Convert a number or array to a floating point data type. + +See also: [`complex`](@ref), [`oftype`](@ref), [`convert`](@ref). + +# Examples +```jldoctest +julia> float(1:1000) +1.0:1.0:1000.0 + +julia> float(typemax(Int32)) +2.147483647e9 +``` """ float(x) = AbstractFloat(x) @@ -469,6 +508,8 @@ abs(x::Float64) = abs_float(x) Test whether a number value is a NaN, an indeterminate value which is neither an infinity nor a finite number ("not a number"). + +See also: [`iszero`](@ref), [`isone`](@ref), [`isinf`](@ref), [`ismissing`](@ref). """ isnan(x::AbstractFloat) = (x != x)::Bool isnan(x::Number) = false @@ -481,6 +522,8 @@ isfinite(x::Integer) = true isinf(f) -> Bool Test whether a number is infinite. + +See also: [`Inf`](@ref), [`iszero`](@ref), [`isfinite`](@ref), [`isnan`](@ref). """ isinf(x::Real) = !isnan(x) & !isfinite(x) @@ -641,7 +684,7 @@ uabs(x::BitSigned) = unsigned(abs(x)) nextfloat(x::AbstractFloat, n::Integer) The result of `n` iterative applications of `nextfloat` to `x` if `n >= 0`, or `-n` -applications of `prevfloat` if `n < 0`. +applications of [`prevfloat`](@ref) if `n < 0`. """ function nextfloat(f::IEEEFloat, d::Integer) F = typeof(f) @@ -686,6 +729,8 @@ end Return the smallest floating point number `y` of the same type as `x` such `x < y`. If no such `y` exists (e.g. if `x` is `Inf` or `NaN`), then return `x`. + +See also: [`prevfloat`](@ref), [`eps`](@ref), [`issubnormal`](@ref). """ nextfloat(x::AbstractFloat) = nextfloat(x,1) @@ -693,7 +738,7 @@ nextfloat(x::AbstractFloat) = nextfloat(x,1) prevfloat(x::AbstractFloat, n::Integer) The result of `n` iterative applications of `prevfloat` to `x` if `n >= 0`, or `-n` -applications of `nextfloat` if `n < 0`. +applications of [`nextfloat`](@ref) if `n < 0`. """ prevfloat(x::AbstractFloat, d::Integer) = nextfloat(x, -d) @@ -815,6 +860,8 @@ floatmin(x::T) where {T<:AbstractFloat} = floatmin(T) Return the largest finite number representable by the floating-point type `T`. +See also: [`typemax`](@ref), [`floatmin`](@ref), [`eps`](@ref). + # Examples ```jldoctest julia> floatmax(Float16) @@ -825,6 +872,9 @@ julia> floatmax(Float32) julia> floatmax() 1.7976931348623157e308 + +julia> typemax(Float64) +Inf ``` """ floatmax(x::T) where {T<:AbstractFloat} = floatmax(T) @@ -879,6 +929,8 @@ is the nearest floating point number to ``y``, then |y-x| \\leq \\operatorname{eps}(x)/2. ``` +See also: [`nextfloat`](@ref), [`issubnormal`](@ref), [`floatmax`](@ref). + # Examples ```jldoctest julia> eps(1.0) diff --git a/base/hashing.jl b/base/hashing.jl index 26b18f11c2fe2..580b27ab86ee0 100644 --- a/base/hashing.jl +++ b/base/hashing.jl @@ -10,10 +10,12 @@ optional second argument `h` is a hash code to be mixed with the result. New types should implement the 2-argument form, typically by calling the 2-argument `hash` method recursively in order to mix hashes of the contents with each other (and with `h`). -Typically, any type that implements `hash` should also implement its own `==` (hence -`isequal`) to guarantee the property mentioned above. Types supporting subtraction +Typically, any type that implements `hash` should also implement its own [`==`](@ref) (hence +[`isequal`](@ref)) to guarantee the property mentioned above. Types supporting subtraction (operator `-`) should also implement [`widen`](@ref), which is required to hash values inside heterogeneous arrays. + +See also: [`objectid`](@ref), [`Dict`](@ref), [`Set`](@ref). """ hash(x::Any) = hash(x, zero(UInt)) hash(w::WeakRef, h::UInt) = hash(w.value, h) diff --git a/base/iddict.jl b/base/iddict.jl index a03edbb60723b..7247a85c9afc8 100644 --- a/base/iddict.jl +++ b/base/iddict.jl @@ -3,7 +3,7 @@ """ IdDict([itr]) -`IdDict{K,V}()` constructs a hash table using object-id as hash and +`IdDict{K,V}()` constructs a hash table using [`objectid`](@ref) as hash and `===` as equality with keys of type `K` and values of type `V`. See [`Dict`](@ref) for further help. In the example below, The `Dict` diff --git a/base/int.jl b/base/int.jl index 02a9ace0fe3f1..85482f12a5c07 100644 --- a/base/int.jl +++ b/base/int.jl @@ -154,6 +154,8 @@ when `abs` is applied to the minimum representable value of a signed integer. That is, when `x == typemin(typeof(x))`, `abs(x) == x < 0`, not `-x` as might be expected. +See also: [`abs2`](@ref), [`unsigned`](@ref), [`sign`](@ref). + # Examples ```jldoctest julia> abs(-3) @@ -178,12 +180,17 @@ abs(x::Signed) = flipsign(x,x) Convert a number to an unsigned integer. If the argument is signed, it is reinterpreted as unsigned without checking for negative values. + +See also: [`signed`](@ref), [`sign`](@ref), [`signbit`](@ref). + # Examples ```jldoctest julia> unsigned(-2) 0xfffffffffffffffe + julia> unsigned(2) 0x0000000000000002 + julia> signed(unsigned(-2)) -2 ``` @@ -196,6 +203,8 @@ unsigned(x::BitSigned) = reinterpret(typeof(convert(Unsigned, zero(x))), x) Convert a number to a signed integer. If the argument is unsigned, it is reinterpreted as signed without checking for overflow. + +See also: [`unsigned`](@ref), [`sign`](@ref), [`signbit`](@ref). """ signed(x) = x % typeof(convert(Signed, zero(x))) signed(x::BitUnsigned) = reinterpret(typeof(convert(Signed, zero(x))), x) @@ -233,6 +242,8 @@ exceptions, see note below). type, and so rounding error may occur. In particular, if the exact result is very close to `y`, then it may be rounded to `y`. +See also: [`rem`](@ref), [`div`](@ref), [`fld`](@ref), [`mod1`](@ref), [`invmod`](@ref). + ```jldoctest julia> mod(8, 3) 2 @@ -248,6 +259,10 @@ julia> mod(eps(), 3) julia> mod(-eps(), 3) 3.0 + +julia> mod.(-5:5, 3)' +1×11 adjoint(::Vector{Int64}) with eltype Int64: + 1 2 0 1 2 0 1 2 0 1 2 ``` """ function mod(x::T, y::T) where T<:Integer @@ -272,6 +287,8 @@ rem(x::T, y::T) where {T<:BitUnsigned64} = checked_urem_int(x, y) Bitwise not. +See also: [`!`](@ref), [`&`](@ref), [`|`](@ref). + # Examples ```jldoctest julia> ~4 @@ -293,6 +310,8 @@ Bitwise and. Implements [three-valued logic](https://en.wikipedia.org/wiki/Three returning [`missing`](@ref) if one operand is `missing` and the other is `true`. Add parentheses for function application form: `(&)(x, y)`. +See also: [`|`](@ref), [`xor`](@ref), [`&&`](@ref). + # Examples ```jldoctest julia> 4 & 10 @@ -316,6 +335,8 @@ false Bitwise or. Implements [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic), returning [`missing`](@ref) if one operand is `missing` and the other is `false`. +See also: [`&`](@ref), [`xor`](@ref), [`||`](@ref). + # Examples ```jldoctest julia> 4 | 10 @@ -498,6 +519,8 @@ A negative value of `k` will rotate to the right instead. !!! compat "Julia 1.5" This function requires Julia 1.5 or later. +See also: [`<<`](@ref), [`circshift`](@ref), [`BitArray`](@ref). + ```jldoctest julia> bitrotate(UInt8(114), 2) 0xc9 @@ -559,7 +582,9 @@ is less than or equal to `x`. `trunc(T, x)` converts the result to type `T`, throwing an `InexactError` if the value is not representable. -`digits`, `sigdigits` and `base` work as for [`round`](@ref). +Keywords `digits`, `sigdigits` and `base` work as for [`round`](@ref). + +See also: [`%`](@ref rem), [`floor`](@ref), [`unsigned`](@ref). """ function trunc end @@ -574,7 +599,7 @@ equal to `x`. `floor(T, x)` converts the result to type `T`, throwing an `InexactError` if the value is not representable. -`digits`, `sigdigits` and `base` work as for [`round`](@ref). +Keywords `digits`, `sigdigits` and `base` work as for [`round`](@ref). """ function floor end @@ -589,7 +614,7 @@ equal to `x`. `ceil(T, x)` converts the result to type `T`, throwing an `InexactError` if the value is not representable. -`digits`, `sigdigits` and `base` work as for [`round`](@ref). +Keywords `digits`, `sigdigits` and `base` work as for [`round`](@ref). """ function ceil end @@ -702,6 +727,8 @@ function typemin end The highest value representable by the given (real) numeric `DataType`. +See also: [`floatmax`](@ref), [`typemin`](@ref), [`eps`](@ref). + # Examples ```jldoctest julia> typemax(Int8) @@ -709,6 +736,12 @@ julia> typemax(Int8) julia> typemax(UInt32) 0xffffffff + +julia> typemax(Float64) +Inf + +julia> floatmax(Float32) # largest finite floating point number +3.4028235f38 ``` """ function typemax end diff --git a/base/irrationals.jl b/base/irrationals.jl index 545d9091ee840..b1ecaf8557090 100644 --- a/base/irrationals.jl +++ b/base/irrationals.jl @@ -22,7 +22,9 @@ abstract type AbstractIrrational <: Real end Irrational{sym} <: AbstractIrrational Number type representing an exact irrational value denoted by the -symbol `sym`. +symbol `sym`, such as [`π`](@ref pi), [`ℯ`](@ref) and [`γ`](@ref Base.MathConstants.eulergamma). + +See also [`@irrational`], [`AbstractIrrational`](@ref). """ struct Irrational{sym} <: AbstractIrrational end diff --git a/base/iterators.jl b/base/iterators.jl index 618c3e04547cf..b9f2aaf882360 100644 --- a/base/iterators.jl +++ b/base/iterators.jl @@ -276,6 +276,8 @@ the `zip` iterator is a tuple of values of its subiterators. `zip` orders the calls to its subiterators in such a way that stateful iterators will not advance when another iterator finishes in the current iteration. +See also: [`enumerate`](@ref), [`splat`](@ref Base.splat). + # Examples ```jldoctest julia> a = 1:5 @@ -429,6 +431,12 @@ julia> foreach(println, f) 1 3 5 + +julia> [x for x in [1, 2, 3, 4, 5] if isodd(x)] # collects a generator over Iterators.filter +3-element Vector{Int64}: + 1 + 3 + 5 ``` """ filter(flt, itr) = Filter(flt, itr) @@ -526,6 +534,8 @@ end An iterator that yields the same elements as `iter`, but starting at the given `state`. +See also: [`Iterators.drop`](@ref), [`Iterators.peel`](@ref), [`Base.rest`](@ref). + # Examples ```jldoctest julia> collect(Iterators.rest([1,2,3,4], 2)) @@ -544,6 +554,8 @@ rest(itr) = itr Returns the first element and an iterator over the remaining elements. +See also: [`Iterators.drop`](@ref), [`Iterators.take`](@ref). + # Examples ```jldoctest julia> (a, rest) = Iterators.peel("abc"); @@ -622,6 +634,8 @@ end An iterator that generates at most the first `n` elements of `iter`. +See also: [`drop`](@ref Iterators.drop), [`peel`](@ref Iterators.peel), [`first`](@ref), [`take!`](@ref). + # Examples ```jldoctest julia> a = 1:2:11 @@ -833,6 +847,8 @@ end An iterator that cycles through `iter` forever. If `iter` is empty, so is `cycle(iter)`. +See also: [`Iterators.repeated`](@ref), [`repeat`](@ref). + # Examples ```jldoctest julia> for (i, v) in enumerate(Iterators.cycle("hello")) @@ -872,6 +888,8 @@ repeated(x) = Repeated(x) An iterator that generates the value `x` forever. If `n` is specified, generates `x` that many times (equivalent to `take(repeated(x), n)`). +See also: [`Iterators.cycle`](@ref), [`repeat`](@ref). + # Examples ```jldoctest julia> a = Iterators.repeated([1 2], 4); @@ -907,12 +925,17 @@ Return an iterator over the product of several iterators. Each generated element a tuple whose `i`th element comes from the `i`th argument iterator. The first iterator changes the fastest. +See also: [`zip`](@ref), [`Iterators.flatten`](@ref). + # Examples ```jldoctest julia> collect(Iterators.product(1:2, 3:5)) 2×3 Matrix{Tuple{Int64, Int64}}: (1, 3) (1, 4) (1, 5) (2, 3) (2, 4) (2, 5) + +julia> ans == [(x,y) for x in 1:2, y in 3:5] # collects a generator involving Iterators.product +true ``` """ product(iters...) = ProductIterator(iters) @@ -1042,6 +1065,15 @@ julia> collect(Iterators.flatten((1:2, 8:9))) 2 8 9 + +julia> [(x,y) for x in 0:1 for y in 'a':'c'] # collects generators involving Iterators.flatten +6-element Vector{Tuple{Int64, Char}}: + (0, 'a') + (0, 'b') + (0, 'c') + (1, 'a') + (1, 'b') + (1, 'c') ``` """ flatten(itr) = Flatten(itr) diff --git a/base/math.jl b/base/math.jl index b66a058e5ae9e..44da5e04ea5a5 100644 --- a/base/math.jl +++ b/base/math.jl @@ -47,15 +47,17 @@ end Return `x` if `lo <= x <= hi`. If `x > hi`, return `hi`. If `x < lo`, return `lo`. Arguments are promoted to a common type. +See also [`clamp!`](@ref), [`min`](@ref), [`max`](@ref). + # Examples ```jldoctest -julia> clamp.([pi, 1.0, big(10.)], 2., 9.) +julia> clamp.([pi, 1.0, big(10)], 2.0, 9.0) 3-element Vector{BigFloat}: 3.141592653589793238462643383279502884197169399375105820974944592307816406286198 2.0 9.0 -julia> clamp.([11,8,5],10,6) # an example where lo > hi +julia> clamp.([11, 8, 5], 10, 6) # an example where lo > hi 3-element Vector{Int64}: 6 6 @@ -73,12 +75,18 @@ clamp(x::X, lo::L, hi::H) where {X,L,H} = Clamp `x` between `typemin(T)` and `typemax(T)` and convert the result to type `T`. +See also [`trunc`](@ref). + # Examples ```jldoctest julia> clamp(200, Int8) 127 + julia> clamp(-200, Int8) -128 + +julia> trunc(Int, 4pi^2) +39 ``` """ clamp(x, ::Type{T}) where {T<:Integer} = clamp(x, typemin(T), typemax(T)) % T @@ -89,6 +97,19 @@ clamp(x, ::Type{T}) where {T<:Integer} = clamp(x, typemin(T), typemax(T)) % T Restrict values in `array` to the specified range, in-place. See also [`clamp`](@ref). + +# Examples +```jldoctest +julia> row = collect(-4:4)'; + +julia> clamp!(row, 0, Inf) +1×9 adjoint(::Vector{Int64}) with eltype Int64: + 0 0 0 0 0 1 2 3 4 + +julia> clamp.((-4:4)', 0, Inf) +1×9 Matrix{Float64}: + 0.0 0.0 0.0 0.0 0.0 1.0 2.0 3.0 4.0 +``` """ function clamp!(x::AbstractArray, lo, hi) @inbounds for i in eachindex(x) @@ -205,6 +226,8 @@ end @horner(x, p...) Evaluate `p[1] + x * (p[2] + x * (....))`, i.e. a polynomial via Horner's rule. + +See also [`@evalpoly`](@ref), [`evalpoly`](@ref). """ macro horner(x, p...) xesc, pesc = esc(x), esc.(p) @@ -224,6 +247,8 @@ that is, the coefficients are given in ascending order by power of `z`. This ma to efficient inline code that uses either Horner's method or, for complex `z`, a more efficient Goertzel-like algorithm. +See also [`evalpoly`](@ref). + # Examples ```jldoctest julia> @evalpoly(3, 1, 0, 1) @@ -273,6 +298,8 @@ rad2deg(z::AbstractFloat) = z * (180 / oftype(z, pi)) Convert `x` from degrees to radians. +See also: [`rad2deg`](@ref), [`sind`](@ref). + # Examples ```jldoctest julia> deg2rad(90) @@ -390,6 +417,8 @@ asinh(x::Number) sin(x) Compute sine of `x`, where `x` is in radians. + +See also [`sind`], [`sinpi`], [`sincos`], [`cis`]. """ sin(x::Number) @@ -397,6 +426,8 @@ sin(x::Number) cos(x) Compute cosine of `x`, where `x` is in radians. + +See also [`cosd`], [`cospi`], [`sincos`], [`cis`]. """ cos(x::Number) @@ -441,6 +472,8 @@ atanh(x::Number) Compute the natural logarithm of `x`. Throws [`DomainError`](@ref) for negative [`Real`](@ref) arguments. Use complex negative arguments to obtain complex results. +See also [`log1p`], [`log2`], [`log10`]. + # Examples ```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*" julia> log(2) @@ -462,6 +495,8 @@ log(x::Number) Compute the logarithm of `x` to base 2. Throws [`DomainError`](@ref) for negative [`Real`](@ref) arguments. +See also: [`exp2`](@ref), [`ldexp`](@ref). + # Examples ```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*" julia> log2(4) @@ -539,6 +574,8 @@ end Return ``\\sqrt{x}``. Throws [`DomainError`](@ref) for negative [`Real`](@ref) arguments. Use complex negative arguments instead. The prefix operator `√` is equivalent to `sqrt`. +See also: [`hypot`](@ref). + # Examples ```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*" julia> sqrt(big(81)) @@ -553,6 +590,13 @@ Stacktrace: julia> sqrt(big(complex(-81))) 0.0 + 9.0im + +julia> .√(1:4) +4-element Vector{Float64}: + 1.0 + 1.4142135623730951 + 1.7320508075688772 + 2.0 ``` """ sqrt(x) diff --git a/base/mathconstants.jl b/base/mathconstants.jl index a3d1be99becbb..156dc9e1ce39a 100644 --- a/base/mathconstants.jl +++ b/base/mathconstants.jl @@ -23,10 +23,17 @@ Base.@irrational catalan 0.91596559417721901505 catalan The constant pi. +Unicode `π` can be typed by writing `\\pi` then pressing tab in the Julia REPL, and in many editors. + +See also: [`sinpi`](@ref), [`sincospi`](@ref), [`deg2rad`](@ref). + # Examples ```jldoctest julia> pi π = 3.1415926535897... + +julia> 1/2pi +0.15915494309189535 ``` """ π, const pi = π @@ -37,10 +44,20 @@ julia> pi The constant ℯ. +Unicode `ℯ` can be typed by writing `\\euler` and pressing tab in the Julia REPL, and in many editors. + +See also: [`exp`](@ref), [`cis`](@ref), [`cispi`](@ref). + # Examples ```jldoctest julia> ℯ ℯ = 2.7182818284590... + +julia> log(ℯ) +1 + +julia> ℯ^(im)π ≈ -1 +true ``` """ ℯ, const e = ℯ @@ -55,6 +72,11 @@ Euler's constant. ```jldoctest julia> Base.MathConstants.eulergamma γ = 0.5772156649015... + +julia> dx = 10^-6; + +julia> sum(-exp(-x) * log(x) for x in dx:dx:100) * dx +0.5772078382499134 ``` """ γ, const eulergamma = γ @@ -69,6 +91,9 @@ The golden ratio. ```jldoctest julia> Base.MathConstants.golden φ = 1.6180339887498... + +julia> (2ans - 1)^2 ≈ 5 +true ``` """ φ, const golden = φ @@ -82,6 +107,9 @@ Catalan's constant. ```jldoctest julia> Base.MathConstants.catalan catalan = 0.9159655941772... + +julia> sum(log(x)/(1+x^2) for x in 1:0.01:10^6) * 0.01 +0.9159466120554123 ``` """ catalan diff --git a/base/missing.jl b/base/missing.jl index b89c394bea046..80b02015266ce 100644 --- a/base/missing.jl +++ b/base/missing.jl @@ -201,6 +201,8 @@ Use [`collect`](@ref) to obtain an `Array` containing the non-`missing` values i be a `Vector` since it is not possible to remove missings while preserving dimensions of the input. +See also [`coalesce`](@ref), [`ismissing`](@ref), [`something`](@ref). + # Examples ```jldoctest julia> x = skipmissing([1, missing, 2]) @@ -404,7 +406,7 @@ end Return the first value in the arguments which is not equal to [`missing`](@ref), if any. Otherwise return `missing`. -See also [`something`](@ref). +See also [`skipmissing`](@ref), [`something`](@ref). # Examples diff --git a/base/multidimensional.jl b/base/multidimensional.jl index d9251cdebe096..5ef46bb1da468 100644 --- a/base/multidimensional.jl +++ b/base/multidimensional.jl @@ -1160,6 +1160,8 @@ their indices; any offset results in a (circular) wraparound. If the arrays have overlapping indices, then on the domain of the overlap `dest` agrees with `src`. +See also: [`circshift`](@ref). + # Examples ```julia-repl julia> src = reshape(Vector(1:16), (4,4)) diff --git a/base/number.jl b/base/number.jl index 142796d3903ac..8dfa56aa0f61a 100644 --- a/base/number.jl +++ b/base/number.jl @@ -25,6 +25,8 @@ isinteger(x::Integer) = true Return `true` if `x == zero(x)`; if `x` is an array, this checks whether all of the elements of `x` are zero. +See also: [`isone`](@ref), [`isinteger`](@ref), [`isfinite`](@ref), [`isnan`](@ref). + # Examples ```jldoctest julia> iszero(0.0) @@ -110,6 +112,8 @@ copy(x::Number) = x # some code treats numbers as collection-like Returns `true` if the value of the sign of `x` is negative, otherwise `false`. +See also [`sign`](@ref) and [`copysign`](@ref). + # Examples ```jldoctest julia> signbit(-4) @@ -131,6 +135,23 @@ signbit(x::Real) = x < 0 sign(x) Return zero if `x==0` and ``x/|x|`` otherwise (i.e., ±1 for real `x`). + +See also [`signbit`](@ref), [`zero`](@ref), [`copysign`](@ref), [`flipsign`](@ref). + +# Examples +```jldoctest +julia> sign(-4.0) +-1.0 + +julia> sign(99) +1 + +julia> sign(-0.0) +-0.0 + +julia> sign(0 + im) +0.0 + 1.0im +``` """ sign(x::Number) = iszero(x) ? x/abs(oneunit(x)) : x/abs(x) sign(x::Real) = ifelse(x < zero(x), oftype(one(x),-1), ifelse(x > zero(x), one(x), typeof(one(x))(x))) @@ -222,10 +243,18 @@ inv(x::Number) = one(x)/x Multiply `x` and `y`, giving the result as a larger type. +See also [`promote`](@ref), [`Base.add_sum`](@ref). + # Examples ```jldoctest -julia> widemul(Float32(3.), 4.) -12.0 +julia> widemul(Float32(3.0), 4.0) isa BigFloat +true + +julia> typemax(Int8) * typemax(Int8) +1 + +julia> widemul(typemax(Int8), typemax(Int8)) # == 127^2 +16129 ``` """ widemul(x::Number, y::Number) = widen(x)*widen(y) @@ -243,6 +272,8 @@ map(f, x::Number, ys::Number...) = f(x, ys...) Get the additive identity element for the type of `x` (`x` can also specify the type itself). +See also [`iszero`](@ref), [`one`](@ref), [`oneunit`](@ref), [`oftype`](@ref). + # Examples ```jldoctest julia> zero(1) @@ -280,6 +311,9 @@ should return an identity value of the same precision If you want a quantity that is of the same type as `x`, or of type `T`, even if `x` is dimensionful, use [`oneunit`](@ref) instead. +See also the [`identity`](@ref) function, +and `I` in [`LinearAlgebra`](@ref man-linalg) for the identity matrix. + # Examples ```jldoctest julia> one(3.7) diff --git a/base/operators.jl b/base/operators.jl index fcd32cb0206ec..7269a15718a58 100644 --- a/base/operators.jl +++ b/base/operators.jl @@ -563,6 +563,8 @@ extrema(f, x::Real) = (y = f(x); (y, y)) The identity function. Returns its argument. +See also: [`one`](@ref), [`oneunit`](@ref), and [`LinearAlgebra`](@ref man-linalg)'s `I`. + # Examples ```jldoctest julia> identity("Well, what did you expect?") @@ -696,7 +698,7 @@ julia> bitstring(Int8(3)) julia> bitstring(Int8(12)) "00001100" ``` -See also [`>>`](@ref), [`>>>`](@ref). +See also [`>>`](@ref), [`>>>`](@ref), [`exp2`](@ref), [`ldexp`](@ref). """ function <<(x::Integer, c::Integer) @_inline_meta @@ -803,6 +805,8 @@ end Remainder from Euclidean division, returning a value of the same sign as `x`, and smaller in magnitude than `y`. This value is always exact. +See also: [`div`](@ref), [`mod`](@ref), [`mod1`](@ref), [`divrem`](@ref). + # Examples ```jldoctest julia> x = 15; y = 4; @@ -812,6 +816,10 @@ julia> x % y julia> x == div(x, y) * y + rem(x, y) true + +julia> rem.(-5:5, 3)' +1×11 adjoint(::Vector{Int64}) with eltype Int64: + -2 -1 0 -2 -1 0 1 2 0 1 2 ``` """ rem @@ -824,6 +832,8 @@ const % = rem The quotient from Euclidean (integer) division. Generally equivalent to a mathematical operation x/y without a fractional part. +See also: [`cld`](@ref), [`fld`](@ref), [`rem`](@ref), [`divrem`](@ref). + # Examples ```jldoctest julia> 9 ÷ 4 @@ -834,6 +844,10 @@ julia> -5 ÷ 3 julia> 5.0 ÷ 2 2.0 + +julia> div.(-5:5, 3)' +1×11 adjoint(::Vector{Int64}) with eltype Int64: + -1 -1 -1 0 0 0 0 0 1 1 1 ``` """ div @@ -1010,7 +1024,7 @@ julia> fs = [ julia> ∘(fs...)(3) 3.0 ``` -See also [`ComposedFunction`](@ref). +See also [`ComposedFunction`](@ref), [`!f::Function`](@ref). """ function ∘ end @@ -1070,6 +1084,8 @@ end Predicate function negation: when the argument of `!` is a function, it returns a function which computes the boolean negation of `f`. +See also [`∘`](@ref). + # Examples ```jldoctest julia> str = "∀ ε > 0, ∃ δ > 0: |x-y| < δ ⇒ |f(x)-f(y)| < ε" @@ -1090,6 +1106,8 @@ julia> filter(!isletter, str) A type representing a partially-applied version of the two-argument function `f`, with the first argument fixed to the value "x". In other words, `Fix1(f, x)` behaves similarly to `y->f(x, y)`. + +See also [`Fix2`](@ref Base.Fix2). """ struct Fix1{F,T} <: Function f::F @@ -1350,6 +1368,8 @@ julia> [1, 2] .∈ ([2, 3],) 0 1 ``` + +See also: [`insorted`](@ref), [`contains`](@ref), [`occursin`](@ref), [`issubset`](@ref). """ in diff --git a/base/permuteddimsarray.jl b/base/permuteddimsarray.jl index 3fc2a2340efdc..9c12616e5f265 100644 --- a/base/permuteddimsarray.jl +++ b/base/permuteddimsarray.jl @@ -24,7 +24,7 @@ Given an AbstractArray `A`, create a view `B` such that the dimensions appear to be permuted. Similar to `permutedims`, except that no copying occurs (`B` shares storage with `A`). -See also: [`permutedims`](@ref). +See also: [`permutedims`](@ref), [`invperm`](@ref). # Examples ```jldoctest @@ -83,10 +83,10 @@ end """ permutedims(A::AbstractArray, perm) -Permute the dimensions of array `A`. `perm` is a vector specifying a permutation of length -`ndims(A)`. +Permute the dimensions of array `A`. `perm` is a vector or a tuple of length `ndims(A)` +specifying the permutation. -See also: [`PermutedDimsArray`](@ref). +See also: [`permutedims!`](@ref), [`PermutedDimsArray`](@ref), [`transpose`](@ref), [`invperm`](@ref). # Examples ```jldoctest @@ -100,7 +100,7 @@ julia> A = reshape(Vector(1:8), (2,2,2)) 5 7 6 8 -julia> permutedims(A, [3, 2, 1]) +julia> permutedims(A, (3, 2, 1)) 2×2×2 Array{Int64, 3}: [:, :, 1] = 1 3 @@ -109,6 +109,16 @@ julia> permutedims(A, [3, 2, 1]) [:, :, 2] = 2 4 6 8 + +julia> B = randn(5, 7, 11, 13); + +julia> perm = [4,1,3,2]; + +julia> size(permutedims(B, perm)) +(13, 5, 11, 7) + +julia> size(B)[perm] == ans +true ``` """ function permutedims(A::AbstractArray, perm) diff --git a/base/promotion.jl b/base/promotion.jl index a6e6d8fdcac4e..43add6cbf5f62 100644 --- a/base/promotion.jl +++ b/base/promotion.jl @@ -5,7 +5,6 @@ """ typejoin(T, S) - Return the closest common ancestor of `T` and `S`, i.e. the narrowest type from which they both inherit. """ @@ -144,6 +143,17 @@ end Compute a type that contains both `T` and `S`, which could be either a parent of both types, or a `Union` if appropriate. Falls back to [`typejoin`](@ref). + +See instead [`promote`](@ref), [`promote_type`](@ref). + +# Examples +```jldoctest +julia> Base.promote_typejoin(Int, Float64) +Real + +julia> Base.promote_type(Int, Float64) +Float64 +``` """ function promote_typejoin(@nospecialize(a), @nospecialize(b)) c = typejoin(_promote_typesubtract(a), _promote_typesubtract(b)) @@ -191,6 +201,9 @@ tolerated; for example, `promote_type(Int64, Float64)` returns [`Float64`](@ref) even though strictly, not all [`Int64`](@ref) values can be represented exactly as `Float64` values. +See also: [`promote`](@ref), [`promote_typejoin`](@ref), [`promote_rule`](@ref). + +# Examples ```jldoctest julia> promote_type(Int64, Float64) Float64 @@ -254,6 +267,8 @@ promote_result(::Type{T},::Type{S},::Type{Bottom},::Type{Bottom}) where {T,S} = Convert all arguments to a common type, and return them all (as a tuple). If no arguments can be converted, an error is raised. +See also: [`promote_type`], [`promote_rule`]. + # Examples ```jldoctest julia> promote(Int8(1), Float16(4.5), Float32(4.1)) @@ -335,7 +350,7 @@ where usually `^ == Base.^` unless `^` has been defined in the calling namespace.) If `y` is a negative integer literal, then `Base.literal_pow` transforms the operation to `inv(x)^-y` by default, where `-y` is positive. - +# Examples ```jldoctest julia> 3^5 243 diff --git a/base/reduce.jl b/base/reduce.jl index 66fb9bd45de87..ca252a08922c3 100644 --- a/base/reduce.jl +++ b/base/reduce.jl @@ -518,6 +518,8 @@ for non-empty collections. !!! compat "Julia 1.6" Keyword argument `init` requires Julia 1.6 or later. +See also: [`reduce`](@ref), [`mapreduce`](@ref), [`count`](@ref), [`union`](@ref). + # Examples ```jldoctest julia> sum(1:20) @@ -572,6 +574,8 @@ for non-empty collections. !!! compat "Julia 1.6" Keyword argument `init` requires Julia 1.6 or later. +See also: [`reduce`](@ref), [`cumprod`](@ref), [`any`](@ref). + # Examples ```jldoctest julia> prod(1:5) @@ -806,6 +810,8 @@ Return the maximal element of the collection `itr` and its index or key. If there are multiple maximal elements, then the first one will be returned. Values are compared with `isless`. +See also: [`findmin`](@ref), [`argmax`](@ref), [`maximum`](@ref). + # Examples ```jldoctest @@ -863,6 +869,8 @@ Return the minimal element of the collection `itr` and its index or key. If there are multiple minimal elements, then the first one will be returned. `NaN` is treated as less than all other values except `missing`. +See also: [`findmax`](@ref), [`argmin`](@ref), [`minimum`](@ref). + # Examples ```jldoctest @@ -913,6 +921,8 @@ The collection must not be empty. Values are compared with `isless`. +See also: [`argmin`](@ref), [`findmax`](@ref). + # Examples ```jldoctest julia> argmax([8, 0.1, -9, pi]) @@ -950,7 +960,6 @@ julia> argmin(x -> -x^3 + x^2 - 10, -5:5) julia> argmin(acos, 0:0.1:1) 1.0 - ``` """ argmin(f, domain) = findmin(f, domain)[2] @@ -965,6 +974,8 @@ The collection must not be empty. `NaN` is treated as less than all other values except `missing`. +See also: [`argmax`](@ref), [`findmin`](@ref). + # Examples ```jldoctest julia> argmin([8, 0.1, -9, pi]) @@ -992,6 +1003,8 @@ If the input contains [`missing`](@ref) values, return `missing` if all non-miss values are `false` (or equivalently, if the input contains no `true` value), following [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic). +See also: [`all`](@ref), [`count`](@ref), [`sum`](@ref), [`|`](@ref), , [`||`](@ref). + # Examples ```jldoctest julia> a = [true,false,false,true] @@ -1028,6 +1041,8 @@ If the input contains [`missing`](@ref) values, return `missing` if all non-miss values are `true` (or equivalently, if the input contains no `false` value), following [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic). +See also: [`all!`](@ref), [`any`](@ref), [`count`](@ref), [`&`](@ref), , [`&&`](@ref), [`allunique`](@ref). + # Examples ```jldoctest julia> a = [true,false,false,true] @@ -1167,6 +1182,8 @@ to start counting from and therefore also determines the output type. !!! compat "Julia 1.6" `init` keyword was added in Julia 1.6. +See also: [`any`](@ref), [`sum`](@ref). + # Examples ```jldoctest julia> count(i->(4<=i<=6), [2,3,4,5,6]) diff --git a/base/reducedim.jl b/base/reducedim.jl index e21854ef31c18..c473049dd5fa0 100644 --- a/base/reducedim.jl +++ b/base/reducedim.jl @@ -590,6 +590,8 @@ Compute the maximum value of an array over the given dimensions. See also the [`max(a,b)`](@ref) function to take the maximum of two or more arguments, which can be applied elementwise to arrays via `max.(a,b)`. +See also: [`maximum!`](@ref), [`extrema`](@ref), [`findmax`](@ref), [`argmax`](@ref). + # Examples ```jldoctest julia> A = [1 2; 3 4] @@ -665,6 +667,8 @@ Compute the minimum value of an array over the given dimensions. See also the [`min(a,b)`](@ref) function to take the minimum of two or more arguments, which can be applied elementwise to arrays via `min.(a,b)`. +See also: [`minimum!`](@ref), [`extrema`](@ref), [`findmin`](@ref), [`argmin`](@ref). + # Examples ```jldoctest julia> A = [1 2; 3 4] diff --git a/base/reflection.jl b/base/reflection.jl index d9cd893474364..a8bfb04903816 100644 --- a/base/reflection.jl +++ b/base/reflection.jl @@ -20,6 +20,8 @@ nameof(m::Module) = ccall(:jl_module_name, Ref{Symbol}, (Any,), m) Get a module's enclosing `Module`. `Main` is its own parent. +See also: [`names`](@ref), [`nameof`](@ref), [`fullname`](@ref), [`@__MODULE__`](@ref). + # Examples ```jldoctest julia> parentmodule(Main) @@ -94,6 +96,8 @@ are also included. As a special case, all names defined in `Main` are considered \"exported\", since it is not idiomatic to explicitly export names from `Main`. + +See also: [`@locals`](@ref Base.@locals), [`@__MODULE__`](@ref). """ names(m::Module; all::Bool = false, imported::Bool = false) = sort!(ccall(:jl_module_names, Array{Symbol,1}, (Any, Cint, Cint), m, all, imported)) @@ -167,10 +171,15 @@ fieldname(t::Type{<:Tuple}, i::Integer) = Get a tuple with the names of the fields of a `DataType`. +See also [`propertynames`](@ref), [`hasfield`](@ref). + # Examples ```jldoctest julia> fieldnames(Rational) (:num, :den) + +julia> fieldnames(typeof(1+im)) +(:re, :im) ``` """ fieldnames(t::DataType) = (fieldcount(t); # error check to make sure type is specific enough @@ -287,6 +296,8 @@ end objectid(x) Get a hash value for `x` based on object identity. `objectid(x)==objectid(y)` if `x === y`. + +See also [`hash`](@ref), [`IdDict`](@ref). """ objectid(@nospecialize(x)) = ccall(:jl_object_id, UInt, (Any,), x) @@ -446,6 +457,8 @@ Return `true` iff value `v` is mutable. See [Mutable Composite Types](@ref) for a discussion of immutability. Note that this function works on values, so if you give it a type, it will tell you that a value of `DataType` is mutable. +See also [`isbits`](@ref), [`isstructtype`](@ref). + # Examples ```jldoctest julia> ismutable(1) @@ -519,6 +532,8 @@ This category of types is significant since they are valid as type parameters, may not track [`isdefined`](@ref) / [`isassigned`](@ref) status, and have a defined layout that is compatible with C. +See also [`isbits`](@ref), [`isprimitivetype`](@ref), [`ismutable`](@ref). + # Examples ```jldoctest julia> isbitstype(Complex{Float64}) @@ -533,7 +548,7 @@ isbitstype(@nospecialize(t::Type)) = (@_pure_meta; isa(t, DataType) && t.isbitst """ isbits(x) -Return `true` if `x` is an instance of an `isbitstype` type. +Return `true` if `x` is an instance of an [`isbitstype`](@ref) type. """ isbits(@nospecialize x) = (@_pure_meta; typeof(x).isbitstype) @@ -564,6 +579,8 @@ end Determine whether type `T` is a concrete type, meaning it could have direct instances (values `x` such that `typeof(x) === T`). +See also: [`isbits`](@ref), [`isabstracttype`](@ref), [`issingletontype`](@ref). + # Examples ```jldoctest julia> isconcretetype(Complex) @@ -927,6 +944,8 @@ A list of modules can also be specified as an array. !!! compat "Julia 1.4" At least Julia 1.4 is required for specifying a module. + +See also: [`which`](@ref) and `@which`. """ function methods(@nospecialize(f), @nospecialize(t), mod::Union{Tuple{Module},AbstractArray{Module},Nothing}=nothing) @@ -1291,6 +1310,8 @@ end Returns the method of `f` (a `Method` object) that would be called for arguments of the given `types`. If `types` is an abstract type, then the method that would be called by `invoke` is returned. + +See also: [`parentmodule`](@ref), and `@which` and `@edit` in [`InteractiveUtils`](@ref man-interactive-utils). """ function which(@nospecialize(f), @nospecialize(t)) if isa(f, Core.Builtin) @@ -1635,6 +1656,8 @@ as well to get the properties of an instance of the type. of the documented interface of `x`. If you want it to also return "private" fieldnames intended for internal use, pass `true` for the optional second argument. REPL tab completion on `x.` shows only the `private=false` properties. + +See also: [`hasproperty`](@ref), [`hasfield`](@ref). """ propertynames(x) = fieldnames(typeof(x)) propertynames(m::Module) = names(m) @@ -1647,5 +1670,7 @@ Return a boolean indicating whether the object `x` has `s` as one of its own pro !!! compat "Julia 1.2" This function requires at least Julia 1.2. + +See also: [`propertynames`](@ref), [`hasfield`](@ref). """ hasproperty(x, s::Symbol) = s in propertynames(x) diff --git a/base/set.jl b/base/set.jl index fb837fbf86166..0c8a8b95b10ce 100644 --- a/base/set.jl +++ b/base/set.jl @@ -17,6 +17,8 @@ Set() = Set{Any}() Construct a [`Set`](@ref) of the values generated by the given iterable object, or an empty set. Should be used instead of [`BitSet`](@ref) for sparse integer sets, or for sets of arbitrary objects. + +See also: [`push!`](@ref), [`empty!`](@ref), [`union!`](@ref), [`in`](@ref). """ Set(itr) = _Set(itr, IteratorEltype(itr)) @@ -105,6 +107,8 @@ as determined by [`isequal`](@ref), in the order that the first of each set of equivalent elements originally appears. The element type of the input is preserved. +See also: [`unique!`](@ref), [`allunique`](@ref). + # Examples ```jldoctest julia> unique([1, 2, 6, 2]) @@ -371,6 +375,8 @@ end Return `true` if all values from `itr` are distinct when compared with [`isequal`](@ref). +See also: [`unique`](@ref), [`issorted`](@ref). + # Examples ```jldoctest julia> a = [1; 2; 3] @@ -379,6 +385,9 @@ julia> a = [1; 2; 3] 2 3 +julia> allunique(a) +true + julia> allunique([a, a]) false ``` @@ -537,7 +546,7 @@ of the result will not include singleton types which are replaced with values of a different type: for example, `Union{T,Missing}` will become `T` if `missing` is replaced. -See also [`replace!`](@ref). +See also [`replace!`](@ref), [`splice!`](@ref), [`delete!`](@ref), [`insert!`](@ref). # Examples ```jldoctest diff --git a/base/show.jl b/base/show.jl index a601007eeedef..dca5f97f99830 100644 --- a/base/show.jl +++ b/base/show.jl @@ -1016,9 +1016,22 @@ end show_supertypes(typ::DataType) = show_supertypes(stdout, typ) """ - @show + @show exs... -Show an expression and result, returning the result. See also [`show`](@ref). +Prints one or more expressions, and their results, to `stdout`, and returns the last result. + +See also: [`show`](@ref), [`@info`](@ref Logging), [`println`](@ref). + +# Examples +```jldoctest +julia> x = @show 1+2 +1 + 2 = 3 +3 + +julia> @show x^2 x/2; +x ^ 2 = 9 +x / 2 = 1.5 +``` """ macro show(exs...) blk = Expr(:block) diff --git a/base/some.jl b/base/some.jl index 272ed0e00ce31..30fc36d32e13f 100644 --- a/base/some.jl +++ b/base/some.jl @@ -64,6 +64,8 @@ Return `true` if `x === nothing`, and return `false` if not. !!! compat "Julia 1.1" This function requires at least Julia 1.1. + +See also [`something`](@ref), [`notnothing`](@ref), [`ismissing`](@ref). """ isnothing(x) = x === nothing @@ -75,7 +77,7 @@ Return the first value in the arguments which is not equal to [`nothing`](@ref), if any. Otherwise throw an error. Arguments of type [`Some`](@ref) are unwrapped. -See also [`coalesce`](@ref). +See also [`coalesce`](@ref), [`skipmissing`](@ref). # Examples ```jldoctest diff --git a/base/sort.jl b/base/sort.jl index 1a994398bea04..d16de5904c8dd 100644 --- a/base/sort.jl +++ b/base/sort.jl @@ -307,6 +307,8 @@ according to the order specified by the `by`, `lt` and `rev` keywords, assuming is already sorted in that order. Return an empty range located at the insertion point if `a` does not contain values equal to `x`. +See also: [`insorted`](@ref), [`searchsortedfirst`](@ref), [`sort`](@ref), [`findall`](@ref). + # Examples ```jldoctest julia> searchsorted([1, 2, 4, 5, 5, 7], 4) # single match @@ -333,6 +335,8 @@ Return the index of the first value in `a` greater than or equal to `x`, accordi specified order. Return `length(a) + 1` if `x` is greater than all values in `a`. `a` is assumed to be sorted. +See also: [`searchsortedlast`](@ref), [`searchsorted`](@ref), [`findfirst`](@ref). + # Examples ```jldoctest julia> searchsortedfirst([1, 2, 4, 5, 5, 7], 4) # single match @@ -877,7 +881,7 @@ using the same keywords as [`sort!`](@ref). The permutation is guaranteed to be if the sorting algorithm is unstable, meaning that indices of equal elements appear in ascending order. -See also [`sortperm!`](@ref). +See also [`sortperm!`](@ref), [`partialsortperm`](@ref), [`invperm`](@ref), [`indexin`](@ref). # Examples ```jldoctest diff --git a/base/special/exp.jl b/base/special/exp.jl index 5591f3603eee2..c9d53ed8aa695 100644 --- a/base/special/exp.jl +++ b/base/special/exp.jl @@ -297,12 +297,17 @@ end @doc """ exp(x) -Compute the natural base exponential of `x`, in other words ``e^x``. +Compute the natural base exponential of `x`, in other words ``ℯ^x``. + +See also [`exp2`](@ref), [`exp10`](@ref) and [`cis`](@ref). # Examples ```jldoctest julia> exp(1.0) 2.718281828459045 + +julia> exp(im * pi) == cis(pi) +true ``` """ exp(x::Real) @@ -311,10 +316,18 @@ julia> exp(1.0) Compute the base 2 exponential of `x`, in other words ``2^x``. +See also [`ldexp`](@ref), [`<<`](@ref). + # Examples ```jldoctest julia> exp2(5) 32.0 + +julia> 2^5 +32 + +julia> exp2(63) > typemax(Int) +true ``` """ exp2(x) @@ -328,6 +341,9 @@ Compute the base 10 exponential of `x`, in other words ``10^x``. ```jldoctest julia> exp10(2) 100.0 + +julia> 10^2 +100 ``` """ exp10(x) diff --git a/base/special/trig.jl b/base/special/trig.jl index 6ebfd2f2932aa..e7b9e2085bb98 100644 --- a/base/special/trig.jl +++ b/base/special/trig.jl @@ -168,6 +168,8 @@ end Simultaneously compute the sine and cosine of `x`, where `x` is in radians, returning a tuple `(sine, cosine)`. + +See also [`cis`](@ref), [`sincospi`](@ref), [`sincosd`](@ref). """ function sincos(x::T) where T<:Union{Float32, Float64} if abs(x) < T(pi)/4 @@ -742,6 +744,8 @@ mulpi_ext(x::Real) = pi*x # Fallback sinpi(x) Compute ``\\sin(\\pi x)`` more accurately than `sin(pi*x)`, especially for large `x`. + +See also [`sind`](@ref), [`cospi`](@ref), [`sincospi`](@ref). """ function sinpi(x::T) where T<:AbstractFloat if !isfinite(x) @@ -863,6 +867,8 @@ where `x` is in radians), returning a tuple `(sine, cosine)`. !!! compat "Julia 1.6" This function requires Julia 1.6 or later. + +See also: [`cispi`](@ref), [`sincosd`](@ref), [`sinpi`](@ref). """ function sincospi(x::T) where T<:AbstractFloat if !isfinite(x) @@ -1069,6 +1075,8 @@ isinf_real(x::Number) = false sinc(x) Compute ``\\sin(\\pi x) / (\\pi x)`` if ``x \\neq 0``, and ``1`` if ``x = 0``. + +See also [`cosc`](@ref), its derivative. """ sinc(x::Number) = _sinc(float(x)) sinc(x::Integer) = iszero(x) ? one(x) : zero(x) diff --git a/base/strings/io.jl b/base/strings/io.jl index f80479dd79f90..3977f137510e3 100644 --- a/base/strings/io.jl +++ b/base/strings/io.jl @@ -64,10 +64,10 @@ Hello, world julia> io = IOBuffer(); -julia> println(io, "Hello, world") +julia> println(io, "Hello", ',', " world.") julia> String(take!(io)) -"Hello, world\\n" +"Hello, world.\\n" ``` """ println(io::IO, xs...) = print(io, xs..., "\n") @@ -172,6 +172,8 @@ highly efficient, then it may make sense to add a method to `string` and define `print(io::IO, x::MyType) = print(io, string(x))` to ensure the functions are consistent. +See also: [`String`](@ref), [`repr`](@ref), [`sprint`](@ref), [`show`](@ref @show). + # Examples ```jldoctest julia> string("a", 1, true) diff --git a/base/strings/util.jl b/base/strings/util.jl index 2d043b5a360a9..11161ce49af09 100644 --- a/base/strings/util.jl +++ b/base/strings/util.jl @@ -10,7 +10,7 @@ const Chars = Union{AbstractChar,Tuple{Vararg{AbstractChar}},AbstractVector{<:Ab Return `true` if `s` starts with `prefix`. If `prefix` is a vector or set of characters, test whether the first character of `s` belongs to that set. -See also [`endswith`](@ref). +See also [`endswith`](@ref), [`contains`](@ref). # Examples ```jldoctest @@ -30,7 +30,7 @@ startswith(str::AbstractString, chars::Chars) = !isempty(str) && first(str)::Abs Return `true` if `s` ends with `suffix`. If `suffix` is a vector or set of characters, test whether the last character of `s` belongs to that set. -See also [`startswith`](@ref). +See also [`startswith`](@ref), [`contains`](@ref). # Examples ```jldoctest @@ -77,6 +77,8 @@ Return `true` if `haystack` contains `needle`. This is the same as `occursin(needle, haystack)`, but is provided for consistency with `startswith(haystack, needle)` and `endswith(haystack, needle)`. +See also [`occursin`](@ref), [`in`](@ref), [`issubset`](@ref). + # Examples ```jldoctest julia> contains("JuliaLang is pretty cool!", "Julia") @@ -166,6 +168,8 @@ The call `chop(s)` removes the last character from `s`. If it is requested to remove more characters than `length(s)` then an empty string is returned. +See also [`chomp`](@ref), [`startswith`](@ref), [`first`](@ref). + # Examples ```jldoctest julia> a = "March" @@ -196,6 +200,8 @@ end Remove a single trailing newline from a string. +See also [`chop`](@ref). + # Examples ```jldoctest julia> chomp("Hello\\n") diff --git a/base/threadingconstructs.jl b/base/threadingconstructs.jl index f35cb37da990b..179bc3170fa52 100644 --- a/base/threadingconstructs.jl +++ b/base/threadingconstructs.jl @@ -15,6 +15,10 @@ threadid() = Int(ccall(:jl_threadid, Int16, ())+1) Get the number of threads available to the Julia process. This is the inclusive upper bound on [`threadid()`](@ref). + +See also: `BLAS.get_num_threads` and `BLAS.set_num_threads` in the +[`LinearAlgebra`](@ref man-linalg) standard library, and `nprocs()` in the +[`Distributed`](@ref man-distributed) standard library. """ nthreads() = Int(unsafe_load(cglobal(:jl_n_threads, Cint))) @@ -114,6 +118,10 @@ The default schedule (used when no `schedule` argument is present) is subject to !!! compat "Julia 1.5" The `schedule` argument is available as of Julia 1.5. + +See also: [`@spawn`](@ref Threads.@spawn), [`nthreads()`](@ref Threads.nthreads), +[`threadid()`](@ref Threads.threadid), `pmap` in [`Distributed`](@ref man-distributed), +`BLAS.set_num_threads` in [`LinearAlgebra`](@ref man-linalg). """ macro threads(args...) na = length(args) diff --git a/base/tuple.jl b/base/tuple.jl index 3894ec83139fc..55c00084c3c63 100644 --- a/base/tuple.jl +++ b/base/tuple.jl @@ -110,6 +110,8 @@ in assignments, like `a, b... = collection`. !!! compat "Julia 1.6" `Base.rest` requires at least Julia 1.6. +See also: [`first`](@ref first), [`Iterators.rest`](@ref). + # Examples ```jldoctest julia> a = [1 2; 3 4] @@ -186,6 +188,8 @@ safe_tail(t::Tuple{}) = () Return a `Tuple` consisting of all but the last component of `x`. +See also: [`first`](@ref), [`tail`](@ref Base.tail). + # Examples ```jldoctest julia> Base.front((1,2,3)) diff --git a/doc/src/base/arrays.md b/doc/src/base/arrays.md index ec8678361da60..f8c014677f6c9 100644 --- a/doc/src/base/arrays.md +++ b/doc/src/base/arrays.md @@ -40,6 +40,7 @@ Base.trues Base.falses Base.fill Base.fill! +Base.empty Base.similar ``` @@ -91,6 +92,7 @@ Base.Broadcast.result_style Base.getindex(::AbstractArray, ::Any...) Base.setindex!(::AbstractArray, ::Any, ::Any...) Base.copyto!(::AbstractArray, ::CartesianIndices, ::AbstractArray, ::CartesianIndices) +Base.copy! Base.isassigned Base.Colon Base.CartesianIndex diff --git a/doc/src/base/base.md b/doc/src/base/base.md index fe3e7e4ff498a..e747c9137bc09 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -158,6 +158,7 @@ Base.typejoin Base.typeintersect Base.promote_type Base.promote_rule +Base.promote_typejoin Base.isdispatchtuple ``` @@ -213,12 +214,14 @@ Core.Union Union{} Core.UnionAll Core.Tuple +Core.NTuple Core.NamedTuple Base.@NamedTuple Base.Val Core.Vararg Core.Nothing Base.isnothing +Base.notnothing Base.Some Base.something Base.Enums.Enum @@ -243,6 +246,7 @@ new Base.:(|>) Base.:(∘) Base.ComposedFunction +Base.splat ``` ## Syntax @@ -406,6 +410,7 @@ Base.isconst Base.nameof(::Function) Base.functionloc(::Any, ::Any) Base.functionloc(::Method) +Base.@locals ``` ## Internals diff --git a/doc/src/base/math.md b/doc/src/base/math.md index 8f8a038df83c0..177324abccfaa 100644 --- a/doc/src/base/math.md +++ b/doc/src/base/math.md @@ -67,6 +67,7 @@ Base.tan(::Number) Base.Math.sind Base.Math.cosd Base.Math.tand +Base.Math.sincosd Base.Math.sinpi Base.Math.cospi Base.Math.sincospi @@ -177,6 +178,7 @@ Base.nextprod Base.invmod Base.powermod Base.ndigits +Base.add_sum Base.widemul Base.Math.evalpoly Base.Math.@evalpoly diff --git a/stdlib/Distributed/docs/src/index.md b/stdlib/Distributed/docs/src/index.md index 1b1675eccc1a2..dc8cef5e22d92 100644 --- a/stdlib/Distributed/docs/src/index.md +++ b/stdlib/Distributed/docs/src/index.md @@ -1,4 +1,4 @@ -# Distributed Computing +# [Distributed Computing](@id man-distributed) ```@docs Distributed.addprocs diff --git a/stdlib/InteractiveUtils/docs/src/index.md b/stdlib/InteractiveUtils/docs/src/index.md index 6b996fb333fc5..71499744ecb1d 100644 --- a/stdlib/InteractiveUtils/docs/src/index.md +++ b/stdlib/InteractiveUtils/docs/src/index.md @@ -1,4 +1,4 @@ -# Interactive Utilities +# [Interactive Utilities](@id man-interactive-utils) This module is intended for interactive work. It is loaded automaticaly in [interactive mode](@ref command-line-options). diff --git a/stdlib/InteractiveUtils/src/InteractiveUtils.jl b/stdlib/InteractiveUtils/src/InteractiveUtils.jl index c0c6f2df05215..db87e9e5cba04 100644 --- a/stdlib/InteractiveUtils/src/InteractiveUtils.jl +++ b/stdlib/InteractiveUtils/src/InteractiveUtils.jl @@ -81,6 +81,8 @@ Print information about the version of Julia in use. The output is controlled with boolean keyword arguments: - `verbose`: print all additional information + +See also: [`VERSION`](@ref). """ function versioninfo(io::IO=stdout; verbose::Bool=false) println(io, "Julia Version $VERSION") @@ -261,6 +263,8 @@ subtypes(m::Module, x::Type) = _subtypes_in([m], x) Return a list of immediate subtypes of DataType `T`. Note that all currently loaded subtypes are included, including those not visible in the current module. +See also [`supertype`](@ref), [`supertypes`](@ref), [`methodswith`](@ref). + # Examples ```jldoctest julia> subtypes(Integer) @@ -279,6 +283,8 @@ Return a tuple `(T, ..., Any)` of `T` and all its supertypes, as determined by successive calls to the [`supertype`](@ref) function, listed in order of `<:` and terminated by `Any`. +See also [`subtypes`](@ref). + # Examples ```jldoctest julia> supertypes(Int) diff --git a/stdlib/InteractiveUtils/src/macros.jl b/stdlib/InteractiveUtils/src/macros.jl index 011a0034378b2..79473f6d5bb36 100644 --- a/stdlib/InteractiveUtils/src/macros.jl +++ b/stdlib/InteractiveUtils/src/macros.jl @@ -247,7 +247,9 @@ It calls out to the `functionloc` function. Applied to a function or macro call, it evaluates the arguments to the specified call, and returns the `Method` object for the method that would be called for those arguments. Applied to a variable, it returns the module in which the variable was bound. It calls out to the -`which` function. +[`which`](@ref) function. + +See also: [`@less`](@ref), [`@edit`](@ref). """ :@which @@ -256,6 +258,8 @@ to a variable, it returns the module in which the variable was bound. It calls o Evaluates the arguments to the function or macro call, determines their types, and calls the `less` function on the resulting expression. + +See also: [`@edit`](@ref), [`@which`](@ref), [`@code_lowered`](@ref). """ :@less @@ -264,6 +268,8 @@ function on the resulting expression. Evaluates the arguments to the function or macro call, determines their types, and calls the `edit` function on the resulting expression. + +See also: [`@less`](@ref), [`@which`](@ref). """ :@edit diff --git a/stdlib/LinearAlgebra/docs/src/index.md b/stdlib/LinearAlgebra/docs/src/index.md index 48d44d98f7ca0..baafe762cea3f 100644 --- a/stdlib/LinearAlgebra/docs/src/index.md +++ b/stdlib/LinearAlgebra/docs/src/index.md @@ -577,6 +577,7 @@ LinearAlgebra.BLAS.trmv LinearAlgebra.BLAS.trsv! LinearAlgebra.BLAS.trsv LinearAlgebra.BLAS.set_num_threads +LinearAlgebra.BLAS.get_num_threads ``` ## LAPACK functions diff --git a/stdlib/LinearAlgebra/src/dense.jl b/stdlib/LinearAlgebra/src/dense.jl index e21c4200f9394..e1294d7166d1d 100644 --- a/stdlib/LinearAlgebra/src/dense.jl +++ b/stdlib/LinearAlgebra/src/dense.jl @@ -75,7 +75,8 @@ isposdef!(A::AbstractMatrix) = Test whether a matrix is positive definite (and Hermitian) by trying to perform a Cholesky factorization of `A`. -See also [`isposdef!`](@ref) + +See also [`isposdef!`](@ref), [`cholesky`](@ref). # Examples ```jldoctest @@ -205,6 +206,8 @@ diagind(m::Integer, n::Integer, k::Integer=0) = An `AbstractRange` giving the indices of the `k`th diagonal of the matrix `M`. +See also: [`diag`](@ref), [`diagm`](@ref), [`Diagonal`](@ref). + # Examples ```jldoctest julia> A = [1 2 3; 4 5 6; 7 8 9] @@ -227,7 +230,7 @@ end The `k`th diagonal of a matrix, as a vector. -See also: [`diagm`](@ref) +See also: [`diagm`](@ref), [`diagind`](@ref), [`Diagonal`](@ref), [`isdiag`](@ref). # Examples ```jldoctest diff --git a/stdlib/LinearAlgebra/src/generic.jl b/stdlib/LinearAlgebra/src/generic.jl index 17a565ee76cb2..b74ac6cced810 100644 --- a/stdlib/LinearAlgebra/src/generic.jl +++ b/stdlib/LinearAlgebra/src/generic.jl @@ -1109,6 +1109,8 @@ When `A` is sparse, a similar polyalgorithm is used. For indefinite matrices, th factorization does not use pivoting during the numerical factorization and therefore the procedure can fail even for invertible matrices. +See also: [`factorize`](@ref), [`pinv`](@ref). + # Examples ```jldoctest julia> A = [1 0; 1 -2]; B = [32; -4]; @@ -1529,6 +1531,8 @@ end Matrix determinant. +See also: [`logdet`](@ref) and [`logabsdet`](@ref). + # Examples ```jldoctest julia> M = [1 0; 2 2] diff --git a/stdlib/Printf/docs/src/index.md b/stdlib/Printf/docs/src/index.md index 828e527ed0cad..48e38e2b2ce5b 100644 --- a/stdlib/Printf/docs/src/index.md +++ b/stdlib/Printf/docs/src/index.md @@ -1,4 +1,4 @@ -# Printf +# [Printf](@id man-printf) ```@docs Printf.@printf