1Function: localprec
2Section: programming/specific
3C-Name: localprec
4Prototype: vG
5Help: localprec(p): set the real precision to p in the dynamic scope
6 and return p.
7Doc: set the real precision to $p$ in the dynamic scope and return $p$.
8 All computations are performed as if \tet{realprecision} was $p$:
9 transcendental constants (e.g.~\kbd{Pi}) and
10 conversions from exact to floating point inexact data use $p$ decimal
11 digits, as well as iterative routines implicitly using a floating point
12 accuracy as a termination criterion (e.g.~\tet{solve} or \tet{intnum}).
13 But \kbd{realprecision} itself is unaffected
14 and is ``unmasked'' when we exit the dynamic (\emph{not} lexical) scope.
15 In effect, this is similar to
16 \bprog
17 my(prec = default(realprecision));
18 default(realprecision,p);
19 ...
20 default(realprecision, prec);
21 @eprog\noindent but is both less cumbersome, cleaner (no need to manipulate
22 a global variable, which in fact never changes and is only temporarily masked)
23 and more robust: if the above computation is interrupted or an exception
24 occurs, \kbd{realprecision} will not be restored as intended.
25
26 Such \kbd{localprec} statements can be nested, the innermost one taking
27 precedence as expected. Beware that \kbd{localprec} follows the semantic of
28 \tet{local}, not \tet{my}: a subroutine called from \kbd{localprec} scope
29 uses the local accuracy:
30 \bprog
31 ? f()=precision(1.);
32 ? f()
33 %2 = 38
34 ? localprec(19); f()
35 %3 = 19
36 @eprog\noindent
37 \misctitle{Warning} Changing \kbd{realprecision} itself in programs is
38 now deprecated in favor of \kbd{localprec}. Think about the
39 \kbd{realprecision} default as an interactive command for the \kbd{gp}
40 interpreter, best left out of GP programs. Indeed, the above rules
41 imply that mixing both constructs yields surprising results:
42 \bprog
43 ? \p38
44 ? localprec(19); default(realprecision,100); Pi
45 %1 = 3.141592653589793239
46 ? \p
47     realprecision = 115 significant digits (100 digits displayed)
48 @eprog\noindent Indeed, \kbd{realprecision} itself is ignored within
49 \kbd{localprec} scope, so \kbd{Pi} is computed to a low accuracy. And when
50 we leave \kbd{localprec} scope, \kbd{realprecision} only regains precedence,
51 it is not ``restored'' to the original value.
52 %\syn{NO}
53