From 96e5b62e95f79a64ab296001dd8cf748c63af806 Mon Sep 17 00:00:00 2001 From: Neven Sajko Date: Sun, 20 Aug 2023 15:05:35 +0200 Subject: [PATCH] docs: warn against `@big_str` not obeying rounding mode or precision (#50800) One of the big pitfalls when using `BigFloat`. --- base/int.jl | 9 +++++++++ doc/src/manual/integers-and-floating-point-numbers.md | 7 +++++++ 2 files changed, 16 insertions(+) diff --git a/base/int.jl b/base/int.jl index a0bfe24af89ec..05457d9cf55c3 100644 --- a/base/int.jl +++ b/base/int.jl @@ -754,6 +754,15 @@ julia> big"_" ERROR: ArgumentError: invalid number format _ for BigInt or BigFloat [...] ``` + +!!! warning + Using `@big_str` for constructing [`BigFloat`](@ref) values may not result + in the behavior that might be naively expected: as a macro, `@big_str` + obeys the global precision ([`setprecision`](@ref)) and rounding mode + ([`setrounding`](@ref)) settings as they are at *load time*. Thus, a + function like `() -> precision(big"0.3")` returns a constant whose value + depends on the value of the precision at the point when the function is + defined, **not** at the precision at the time when the function is called. """ macro big_str(s) message = "invalid number format $s for BigInt or BigFloat" diff --git a/doc/src/manual/integers-and-floating-point-numbers.md b/doc/src/manual/integers-and-floating-point-numbers.md index 173ca7847616e..8b45288f38efa 100644 --- a/doc/src/manual/integers-and-floating-point-numbers.md +++ b/doc/src/manual/integers-and-floating-point-numbers.md @@ -653,6 +653,13 @@ julia> setprecision(40) do 1.1000000000004 ``` +!!! warning + The relation between [`setprecision`](@ref) or [`setrounding`](@ref) and + [`@big_str`](@ref), the macro used for `big` string literals (such as + `big"0.3"`), might not be intuitive, as a consequence of the fact that + `@big_str` is a macro. See the [`@big_str`](@ref) documentation for + details. + ## [Numeric Literal Coefficients](@id man-numeric-literal-coefficients) To make common numeric formulae and expressions clearer, Julia allows variables to be immediately