Function: nfeltval
Section: number_fields
C-Name: gpnfvalrem
Prototype: GGGD&
Help: nfeltval(nf,x,pr,{&y}): valuation of element x at the prime pr as output
 by idealprimedec.
Doc: given an element $x$ in
 \var{nf} and a prime ideal \var{pr} in the format output by
 \kbd{idealprimedec}, computes the valuation $v$ at \var{pr} of the
 element $x$. The valuation of $0$ is \kbd{+oo}.
 \bprog
 ? nf = nfinit(x^2 + 1);
 ? P = idealprimedec(nf, 2)[1];
 ? nfeltval(nf, x+1, P)
 %3 = 1
 @eprog\noindent
 This particular valuation can also be obtained using
 \kbd{idealval(\var{nf},x,\var{pr})}, since $x$ is then converted to a
 principal ideal.

 If the $y$ argument is present, sets $y = x \tau^{v}$, where $\tau$ is a
 fixed ``anti-uniformizer'' for \var{pr}: its valuation at \var{pr} is $-1$;
 its valuation is $0$ at other prime ideals dividing \kbd{\var{pr}.p} and
 nonnegative at all other primes. In other words $y$ is the part of $x$
 coprime to \var{pr}. If $x$ is an algebraic integer, so is $y$.
 \bprog
 ? nfeltval(nf, x+1, P, &y); y
 %4 = [0, 1]~
 @eprog
 For instance if $x = \prod_{i} x_{i}^{e_{i}}$ is known to be coprime to
 \var{pr}, where the $x_{i}$ are algebraic integers and $e_{i}\in\Z$ then,
 if $v_{i} = \kbd{nfeltval}(\var{nf}, x_{i}, \var{pr}, \&y_{i})$, we still
 have $x = \prod_{i} y_{i}^{e_{i}}$, where the $y_{i}$ are still algebraic
 integers but now all of them are coprime to \var{pr}. They can then be
 mapped to the residue field of \var{pr} more efficiently than if the product
 had been expanded beforehand: we can reduce mod \var{pr} after each ring
 operation.
Variant: Also available are
 \fun{long}{nfvalrem}{GEN nf, GEN x, GEN pr, GEN *y = NULL}, which returns
 \tet{LONG_MAX} if $x = 0$ and the valuation as a \kbd{long} integer,
 and \fun{long}{nfval}{GEN nf, GEN x, GEN pr}, which only returns the
 valuation ($y = \kbd{NULL}$).
