diff --git a/NEWS.md b/NEWS.md index c0db3c4559975..233a0396b10cb 100644 --- a/NEWS.md +++ b/NEWS.md @@ -237,6 +237,8 @@ Library improvements * Rational arithmetic throws errors on overflow ([#8672]). + * Optional `log` and `log1p` functions implemented in pure Julia (experimental) ([#10008]). + * Random numbers * Streamlined random number generation APIs [#8246]. @@ -350,9 +352,11 @@ Deprecated or removed * Low-level functions from the C library and dynamic linker have been moved to modules `Libc` and `Libdl`, respectively ([#10328]). - * The functions `parseint`, `parsefloat`, `float32_isvalid`, and `float64_isvalid` - have been replaced by `parse` and `tryparse` with a type argument - ([#3631], [#5704], [#9487], [#10543]). + * The functions `parseint`, `parsefloat`, `float32_isvalid`, + `float64_isvalid`, and the string-argument `BigInt` and `BigFloat` have + been replaced by `parse` and `tryparse` with a type argument. The string + macro `big"xx"` can be used to construct `BigInt` and `BigFloat` literals. + ([#3631], [#5704], [#9487], [#10543], [#10955]). * the `--int-literals` compiler option is no longer accepted ([#9597]). diff --git a/doc/helpdb.jl b/doc/helpdb.jl index ea8dd2db3182f..178034617b3c6 100644 --- a/doc/helpdb.jl +++ b/doc/helpdb.jl @@ -1627,7 +1627,7 @@ Any[ julia> convert(Int, 3.5) ERROR: InexactError() - in convert at int.jl:185 + in convert at int.jl:196 If \"T\" is a \"FloatingPoint\" or \"Rational\" type, then it will return the closest value to \"x\" representable by \"T\". @@ -1896,10 +1896,11 @@ Any[ ("","@enum EnumName EnumValue1[=x] EnumValue2[=y]","@enum EnumName EnumValue1[=x] EnumValue2[=y] - Create an *Enum* type with name *EnumName* and enum member values - of *EnumValue1* and *EnumValue2* with optional assigned values of - *x* and *y*, respectively. *EnumName* can be used just like other - types and enum member values as regular values, such as + Create an \"Enum\" type with name \"EnumName\" and enum member + values of \"EnumValue1\" and \"EnumValue2\" with optional assigned + values of \"x\" and \"y\", respectively. \"EnumName\" can be used + just like other types and enum member values as regular values, + such as julia> @enum FRUIT apple=1 orange=2 kiwi=3 @@ -1911,26 +1912,6 @@ Any[ "), -("Base","apply","apply(f, x...) - - Accepts a function and several arguments, each of which must be - iterable. The elements generated by all the arguments are appended - into a single list, which is then passed to \"f\" as its argument - list. - - julia> function f(x, y) # Define a function f - x + y - end; - - julia> apply(f, [1 2]) # Apply f with 1 and 2 as arguments - 3 - - \"apply\" is called to implement the \"...\" argument splicing - syntax, and is usually not called directly: \"apply(f,x) === - f(x...)\" - -"), - ("Base","method_exists","method_exists(f, Tuple type) -> Bool Determine whether the given generic function has a method matching @@ -1975,7 +1956,7 @@ Any[ Applies a function to the preceding argument. This allows for easy function chaining. - julia> [1:5] |> x->x.^2 |> sum |> inv + julia> [1:5;] |> x->x.^2 |> sum |> inv 0.01818181818181818 "), @@ -3734,7 +3715,7 @@ Any[ intermediate collection needs to be created. See documentation for \"reduce()\" and \"map()\". - julia> mapreduce(x->x^2, +, [1:3]) # == 1 + 4 + 9 + julia> mapreduce(x->x^2, +, [1:3;]) # == 1 + 4 + 9 14 The associativity of the reduction is implementation-dependent. @@ -4249,7 +4230,7 @@ Any[ julia> deleteat!([6, 5, 4, 3, 2, 1], (2, 2)) ERROR: ArgumentError: indices must be unique and sorted - in deleteat! at array.jl:594 + in deleteat! at array.jl:631 "), @@ -7314,7 +7295,7 @@ popdisplay(d::Display) ("Base","eigvecs","eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix Returns a matrix \"M\" whose columns are the eigenvectors of \"A\". - (The \"k``th eigenvector can be obtained from the slice ``M[:, + (The \"k\"th eigenvector can be obtained from the slice \"M[:, k]\".) The \"permute\" and \"scale\" keywords are the same as for \"eigfact()\". @@ -7329,8 +7310,8 @@ popdisplay(d::Display) Computes the eigenvalue decomposition of \"A\", returning an \"Eigen\" factorization object \"F\" which contains the eigenvalues in \"F[:values]\" and the eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k``th eigenvector can be obtained from the - slice ``F[:vectors][:, k]\".) + \"F[:vectors]\". (The \"k\"th eigenvector can be obtained from the + slice \"F[:vectors][:, k]\".) The following functions are available for \"Eigen\" objects: \"inv\", \"det\". @@ -7356,8 +7337,8 @@ popdisplay(d::Display) \"B\", returning a \"GeneralizedEigen\" factorization object \"F\" which contains the generalized eigenvalues in \"F[:values]\" and the generalized eigenvectors in the columns of the matrix - \"F[:vectors]\". (The \"k``th generalized eigenvector can be - obtained from the slice ``F[:vectors][:, k]\".) + \"F[:vectors]\". (The \"k\"th generalized eigenvector can be + obtained from the slice \"F[:vectors][:, k]\".) "), @@ -8867,8 +8848,8 @@ popdisplay(d::Display) julia> B 2x2 Array{Float64,2}: - 3.0 3.0 - 7.0 7.0 + 3.0 3.0 + 7.0 7.0 "), @@ -9266,8 +9247,11 @@ popdisplay(d::Display) ("Base","log","log(x) Compute the natural logarithm of \"x\". Throws \"DomainError\" for - negative \"Real\" arguments. Use complex negative arguments - instead. + negative \"Real\" 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. "), @@ -9297,6 +9281,9 @@ popdisplay(d::Display) Accurate natural logarithm of \"1+x\". Throws \"DomainError\" for \"Real\" arguments less than -1. + There is an experimental variant in the \"Base.Math.JuliaLibm\" + module, which is typically faster and more accurate. + "), ("Base","frexp","frexp(val) @@ -11135,22 +11122,29 @@ golden ("Base","BigInt","BigInt(x) Create an arbitrary precision integer. \"x\" may be an \"Int\" (or - anything that can be converted to an \"Int\") or an - \"AbstractString\". The usual mathematical operators are defined - for this type, and results are promoted to a \"BigInt\". + anything that can be converted to an \"Int\"). The usual + mathematical operators are defined for this type, and results are + promoted to a \"BigInt\". + + Instances can be constructed from strings via \"parse()\", or using + the \"big\" string literal. "), ("Base","BigFloat","BigFloat(x) Create an arbitrary precision floating point number. \"x\" may be - an \"Integer\", a \"Float64\", an \"AbstractString\" or a - \"BigInt\". The usual mathematical operators are defined for this - type, and results are promoted to a \"BigFloat\". Note that because - floating-point numbers are not exactly-representable in decimal - notation, \"BigFloat(2.1)\" may not yield what you expect. You may - prefer to initialize constants using strings, e.g., - \"BigFloat(\"2.1\")\". + an \"Integer\", a \"Float64\" or a \"BigInt\". The usual + mathematical operators are defined for this type, and results are + promoted to a \"BigFloat\". + + 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 constants from strings + via \"parse()\", or using the \"big\" string literal. + + julia> big\"2.1\" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision "), @@ -11254,6 +11248,19 @@ golden "), +("Base","isprime","isprime(x::BigInt[, reps = 25]) -> Bool + + Probabilistic primality test. Returns \"true\" if \"x\" is prime; + and \"false\" if \"x\" is not prime with high probability. The + false positive rate is about \"0.25^reps\". \"reps = 25\" is + considered safe for cryptographic applications (Knuth, + Seminumerical Algorithms). + + julia> isprime(big(3)) + true + +"), + ("Base","primes","primes(n) Returns a collection of the prime numbers <= \"n\". diff --git a/doc/stdlib/math.rst b/doc/stdlib/math.rst index 75ed1a1400db5..4dea80104eb4f 100644 --- a/doc/stdlib/math.rst +++ b/doc/stdlib/math.rst @@ -608,7 +608,12 @@ Mathematical Functions .. function:: log(x) - Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative ``Real`` arguments. Use complex negative arguments instead. + Compute the natural logarithm of ``x``. Throws ``DomainError`` for negative + ``Real`` 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. .. function:: log(b,x) @@ -626,6 +631,9 @@ Mathematical Functions Accurate natural logarithm of ``1+x``. Throws ``DomainError`` for ``Real`` arguments less than -1. + There is an experimental variant in the ``Base.Math.JuliaLibm`` module, + which is typically faster and more accurate. + .. function:: frexp(val) Return ``(x,exp)`` such that ``x`` has a magnitude in the interval ``[1/2, 1)`` or 0, diff --git a/doc/stdlib/numbers.rst b/doc/stdlib/numbers.rst index 95eab48b63f56..026d3e62f2f72 100644 --- a/doc/stdlib/numbers.rst +++ b/doc/stdlib/numbers.rst @@ -253,18 +253,32 @@ General Number Functions and Constants .. function:: BigInt(x) - Create an arbitrary precision integer. ``x`` may be an ``Int`` (or anything that can be converted to an ``Int``) or an ``AbstractString``. - The usual mathematical operators are defined for this type, and results are promoted to a ``BigInt``. + 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``. + + Instances can be constructed from strings via :func:`parse`, or using the + ``big`` string literal. .. function:: BigFloat(x) Create an arbitrary precision floating point number. ``x`` may be - an ``Integer``, a ``Float64``, an ``AbstractString`` or a ``BigInt``. The + an ``Integer``, a ``Float64`` or a ``BigInt``. The usual mathematical operators are defined for this type, and results - are promoted to a ``BigFloat``. Note that because floating-point - numbers are not exactly-representable in decimal notation, - ``BigFloat(2.1)`` may not yield what you expect. You may prefer to - initialize constants using strings, e.g., ``BigFloat("2.1")``. + are promoted to a ``BigFloat``. + + 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 constants from strings via :func:`parse`, or using the + ``big`` string literal. + + .. doctest:: + julia> BigFloat(2.1) + 2.100000000000000088817841970012523233890533447265625e+00 with 256 bits of precision + + julia> big"2.1" + 2.099999999999999999999999999999999999999999999999999999999999999999999999999986e+00 with 256 bits of precision + .. function:: get_rounding(T)