Data structure containing the CArb pointer

Createst a new CArf structure encapsulated in Arf.

Access to the C pointer in Arf structure.

arf_init x

Initializes the variable x for use. Its value is set to zero.

arf_clear x

Clears the variable x, freeing or recycling its allocated memory.

arf_allocated_bytes x

Returns the total number of bytes heap-allocated internally by this object. The count excludes the size of the structure itself. Add sizeof(arf_struct) to get the size of the object as a whole.

arf_zero res

arf_one res

arf_pos_inf res

arf_neg_inf res

arf_nan res

Sets res respectively to 0, 1, \(+\infty\), \(-\infty\), NaN.

arf_is_zero x

arf_is_one x

arf_is_pos_inf x

arf_is_neg_inf x

arf_is_nan x

Returns nonzero iff x respectively equals 0, 1, \(+\infty\), \(-\infty\), NaN.

arf_is_inf x

Returns nonzero iff x equals either \(+\infty\) or \(-\infty\).

arf_is_normal x

Returns nonzero iff x is a finite, nonzero floating-point value, i.e. not one of the special values 0, \(+\infty\), \(-\infty\), NaN.

arf_is_special x

Returns nonzero iff x is one of the special values 0, \(+\infty\), \(-\infty\), NaN, i.e. not a finite, nonzero floating-point value.

arf_is_finite x

Returns nonzero iff x is a finite floating-point value, i.e. not one of the values \(+\infty\), \(-\infty\), NaN. (Note that this is not equivalent to the negation of arf_is_inf.)

Arf rounding

Specifies that the result of an operation should be rounded to the nearest representable number in the direction towards zero.

Specifies that the result of an operation should be rounded to the nearest representable number in the direction away from zero.

Specifies that the result of an operation should be rounded to the nearest representable number in the direction towards minus infinity.

Specifies that the result of an operation should be rounded to the nearest representable number in the direction towards plus infinity.

Specifies that the result of an operation should be rounded to the nearest representable number, rounding to even if there is a tie between two values.

If passed as the precision parameter to a function, indicates that no rounding is to be performed. Warning: use of this value is unsafe in general. It must only be passed as input under the following two conditions:

• The operation in question can inherently be viewed as an exact operation in \(\mathbb{Z}[\tfrac{1}{2}]\) for all possible inputs, provided that the precision is large enough. Examples include addition, multiplication, conversion from integer types to arbitrary-precision floating-point types, and evaluation of some integer-valued functions.
• The exact result of the operation will certainly fit in memory. Note that, for example, adding two numbers whose exponents are far apart can easily produce an exact result that is far too large to store in memory.

The typical use case is to work with small integer values, double precision constants, and the like. It is also useful when writing test code. If in doubt, simply try with some convenient high precision instead of using this special value, and check that the result is exact.

arf_set res x

arf_set_mpz res x

arf_set_fmpz res x

arf_set_ui res x

arf_set_si res x

arf_set_mpfr res x

arf_set_d res x

Sets res to the exact value of x.

arf_swap x y

Swaps x and y efficiently.

arf_init_set_ui res x

arf_init_set_si res x

Initializes res and sets it to x in a single operation.

arf_set_round res x prec rnd

arf_set_round_si res x prec rnd

arf_set_round_ui res x prec rnd

arf_set_round_mpz res x prec rnd

arf_set_round_fmpz res x prec rnd

Sets res to x, rounded to prec bits in the direction specified by rnd.

arf_set_si_2exp_si res m e

arf_set_ui_2exp_si res m e

arf_set_fmpz_2exp res m e

Sets res to \(m \cdot 2^e\).

arf_set_round_fmpz_2exp res x e prec rnd

Sets res to \(x \cdot 2^e\), rounded to prec bits in the direction specified by rnd.

arf_get_fmpz_2exp m e x

Sets m and e to the unique integers such that \(x = m \cdot 2^e\) and m is odd, provided that x is a nonzero finite fraction. If x is zero, both m and e are set to zero. If x is infinite or NaN, the result is undefined.

arf_frexp m e x

Writes x as \(m \cdot 2^e\), where \(0.5 \le |m| < 1\) if x is a normal value. If x is a special value, copies this to m and sets e to zero. Note: for the inverse operation (ldexp), use arf_mul_2exp_fmpz.

arf_get_d x rnd

Returns x rounded to a double in the direction specified by rnd. This method rounds correctly when overflowing or underflowing the double exponent range (this was not the case in an earlier version).

arf_get_mpfr res x rnd

Sets the MPFR variable res to the value of x. If the precision of x is too small to allow res to be represented exactly, it is rounded in the specified MPFR rounding mode. The return value (-1, 0 or 1) indicates the direction of rounding, following the convention of the MPFR library.

If x has an exponent too large or small to fit in the MPFR type, the result overflows to an infinity or underflows to a (signed) zero, and the corresponding MPFR exception flags are set.

arf_get_fmpz res x rnd

Sets res to x rounded to the nearest integer in the direction specified by rnd. If rnd is ARFRND_NEAR, rounds to the nearest even integer in case of a tie. Returns inexact (beware: accordingly returns whether x is not an integer).

This method aborts if x is infinite or NaN, or if the exponent of x is so large that allocating memory for the result fails.

Warning: this method will allocate a huge amount of memory to store the result if the exponent of x is huge. Memory allocation could succeed even if the required space is far larger than the physical memory available on the machine, resulting in swapping. It is recommended to check that x is within a reasonable range before calling this method.

arf_get_si x rnd

Returns x rounded to the nearest integer in the direction specified by rnd. If rnd is ARFRND_NEAR, rounds to the nearest even integer in case of a tie. Aborts if x is infinite, NaN, or the value is too large to fit in a slong.

arf_get_fmpz_fixed_fmpz res x e

arf_get_fmpz_fixed_si res x e

Converts x to a mantissa with predetermined exponent, i.e. sets res to an integer y such that \(y \times 2^e \approx x\), truncating if necessary. Returns 0 if exact and 1 if truncation occurred.

The warnings for arf_get_fmpz apply.

arf_floor res x

arf_ceil res x

Sets res to \(\lfloor x \rfloor\) and \(\lceil x \rceil\) respectively. The result is always represented exactly, requiring no more bits to store than the input. To round the result to a floating-point number with a lower precision, call arf_set_round afterwards.

arf_get_fmpq res x

Set res to the exact rational value of x. This method aborts if x is infinite or NaN, or if the exponent of x is so large that allocating memory for the result fails.

arf_equal x y

arf_equal_si x y

arf_equal_ui x y

arf_equal_d x y

Returns nonzero iff x and y are exactly equal. NaN is not treated specially, i.e. NaN compares as equal to itself.

For comparison with a double, the values -0 and +0 are both treated as zero, and all NaN values are treated as identical.

arf_cmp x y

arf_cmp_si x y

arf_cmp_ui x y

arf_cmp_d x y

Returns negative, zero, or positive, depending on whether x is respectively smaller, equal, or greater compared to y. Comparison with NaN is undefined.

arf_cmpabs x y

arf_cmpabs_ui x y

arf_cmpabs_d x y

arf_cmpabs_mag x y

Compares the absolute values of x and y.

arf_cmp_2exp_si x e

arf_cmpabs_2exp_si x e

Compares x (respectively its absolute value) with \(2^e\).

arf_sgn x

Returns \(-1\), \(0\) or \(+1\) according to the sign of x. The sign of NaN is undefined.

arf_min res a b

arf_max res a b

Sets res respectively to the minimum and the maximum of a and b.

arf_bits x

Returns the number of bits needed to represent the absolute value of the mantissa of x, i.e. the minimum precision sufficient to represent x exactly. Returns 0 if x is a special value.

arf_is_int x

Returns nonzero iff x is integer-valued.

arf_is_int_2exp_si x e

Returns nonzero iff x equals \(n 2^e\) for some integer n.

arf_abs_bound_lt_2exp_fmpz res x

Sets res to the smallest integer b such that \(|x| < 2^b\). If x is zero, infinity or NaN, the result is undefined.

arf_abs_bound_le_2exp_fmpz res x

Sets res to the smallest integer b such that \(|x| \le 2^b\). If x is zero, infinity or NaN, the result is undefined.

arf_abs_bound_lt_2exp_si x

Returns the smallest integer b such that \(|x| < 2^b\), clamping the result to lie between -ARF_PREC_EXACT and ARF_PREC_EXACT inclusive. If x is zero, -ARF_PREC_EXACT is returned, and if x is infinity or NaN, ARF_PREC_EXACT is returned.

arf_get_mag res x

Sets res to an upper bound for the absolute value of x.

arf_get_mag_lower res x

Sets res to a lower bound for the absolute value of x.

arf_set_mag res x

Sets res to x. This operation is exact.

mag_init_set_arf res x

Initializes res and sets it to an upper bound for x.

mag_fast_init_set_arf res x

Initializes res and sets it to an upper bound for x. Assumes that the exponent of res is small (this function is unsafe).

arf_mag_set_ulp res x prec

Sets res to the magnitude of the unit in the last place (ulp) of x at precision prec.

arf_mag_add_ulp res x y prec

Sets res to an upper bound for the sum of x and the magnitude of the unit in the last place (ulp) of y at precision prec.

arf_mag_fast_add_ulp res x y prec

Sets res to an upper bound for the sum of x and the magnitude of the unit in the last place (ulp) of y at precision prec. Assumes that all exponents are small.

arf_init_set_shallow z x

arf_init_set_mag_shallow z x

Initializes z to a shallow copy of x. A shallow copy just involves copying struct data (no heap allocation is performed).

The target variable z may not be cleared or modified in any way (it can only be used as constant input to functions), and may not be used after x has been cleared. Moreover, after x has been assigned shallowly to z, no modification of x is permitted as slong as z is in use.

arf_init_neg_shallow z x

arf_init_neg_mag_shallow z x

Initializes z shallowly to the negation of x.

arf_randtest res state bits mag_bits

Generates a finite random number whose mantissa has precision at most bits and whose exponent has at most mag_bits bits. The values are distributed non-uniformly: special bit patterns are generated with high probability in order to allow the test code to exercise corner cases.

arf_randtest_not_zero res state bits mag_bits

Identical to arf_randtest, except that zero is never produced as an output.

arf_randtest_special res state bits mag_bits

Identical to arf_randtest, except that the output occasionally is set to an infinity or NaN.

arf_urandom res state bits rnd

Sets res to a uniformly distributed random number in the interval \([0, 1]\). The method uses rounding from integers to floats based on the rounding mode rnd.

arf_debug x

Prints information about the internal representation of x.

arf_print x

Prints x as an integer mantissa and exponent.

arf_printd x d

Prints x as a decimal floating-point number, rounding to d digits. Rounding is faithful (at most 1 ulp error).

arf_get_str x d

Returns x as a decimal floating-point number, rounding to d digits. Rounding is faithful (at most 1 ulp error).

arf_fprint file x

Prints x as an integer mantissa and exponent to the stream file.

arf_fprintd file y d

Prints x as a decimal floating-point number to the stream file, rounding to d digits. Rounding is faithful (at most 1 ulp error).

arf_dump_str x

Allocates a string and writes a binary representation of x to it that can be read by arf_load_str. The returned string needs to be deallocated with flint_free.

arf_load_str x str

Parses str into x. Returns a nonzero value if str is not formatted correctly.

arf_dump_file stream x

Writes a binary representation of x to stream that can be read by arf_load_file. Returns a nonzero value if the data could not be written.

arf_load_file x stream

Reads x from stream. Returns a nonzero value if the data is not formatted correctly or the read failed. Note that the data is assumed to be delimited by a whitespace or end-of-file, i.e., when writing multiple values with arf_dump_file make sure to insert a whitespace to separate consecutive values.

arf_abs res x

Sets res to the absolute value of x exactly.

arf_neg res x

Sets res to \(-x\) exactly.

arf_neg_round res x prec rnd

Sets res to \(-x\).

arf_add res x y prec rnd

arf_add_si res x y prec rnd

arf_add_ui res x y prec rnd

arf_add_fmpz res x y prec rnd

Sets res to \(x + y\).

arf_add_fmpz_2exp res x y e prec rnd

Sets res to \(x + y 2^e\).

arf_sub res x y prec rnd

arf_sub_si res x y prec rnd

arf_sub_ui res x y prec rnd

arf_sub_fmpz res x y prec rnd

Sets res to \(x - y\).

arf_mul_2exp_si res x e

arf_mul_2exp_fmpz res x e

Sets res to \(x 2^e\) exactly.

arf_mul res x y prec rnd

arf_mul_ui res x y prec rnd

arf_mul_si res x y prec rnd

arf_mul_mpz res x y prec rnd

arf_mul_fmpz res x y prec rnd

Sets res to \(x \cdot y\).

arf_addmul z x y prec rnd

arf_addmul_ui z x y prec rnd

arf_addmul_si z x y prec rnd

arf_addmul_mpz z x y prec rnd

arf_addmul_fmpz z x y prec rnd

Performs a fused multiply-add \(z = z + x \cdot y\), updating z in-place.

arf_submul z x y prec rnd

arf_submul_ui z x y prec rnd

arf_submul_si z x y prec rnd

arf_submul_mpz z x y prec rnd

arf_submul_fmpz z x y prec rnd

Performs a fused multiply-subtract \(z = z - x \cdot y\), updating z in-place.

arf_fma res x y z prec rnd

Sets res to \(x \cdot y + z\). This is equivalent to an addmul except that res and z can be separate variables.

arf_sosq res x y prec rnd

Sets res to \(x^2 + y^2\), rounded to prec bits in the direction specified by rnd.

arf_sum res terms len prec rnd

Sets res to the sum of the array terms of length len, rounded to prec bits in the direction specified by rnd. The sum is computed as if done without any intermediate rounding error, with only a single rounding applied to the final result. Unlike repeated calls to arf_add with infinite precision, this function does not overflow if the magnitudes of the terms are far apart. Warning: this function is implemented naively, and the running time is quadratic with respect to len in the worst case.

arf_approx_dot res initial subtract x xstep y ystep len prec rnd

Computes an approximate dot product, with the same meaning of the parameters as arb_dot. This operation is not correctly rounded: the final rounding is done in the direction rnd but intermediate roundings are implementation-defined.

arf_div res x y prec rnd

arf_div_ui res x y prec rnd

arf_ui_div res x y prec rnd

arf_div_si res x y prec rnd

arf_si_div res x y prec rnd

arf_div_fmpz res x y prec rnd

arf_fmpz_div res x y prec rnd

arf_fmpz_div_fmpz res x y prec rnd

Sets res to \(x / y\), rounded to prec bits in the direction specified by rnd, returning nonzero iff the operation is inexact. The result is NaN if y is zero.

arf_sqrt res x prec rnd

arf_sqrt_ui res x prec rnd

arf_sqrt_fmpz res x prec rnd

Sets res to \(\sqrt{x}\). The result is NaN if x is negative.

arf_rsqrt res x prec rnd

Sets res to \(1/\sqrt{x}\). The result is NaN if x is negative, and \(+\infty\) if x is zero.

arf_root res x k prec rnd

Sets res to \(x^{1/k}\). The result is NaN if x is negative. Warning: this function is a wrapper around the MPFR root function. It gets slow and uses much memory for large k. Consider working with arb_root_ui for large k instead of using this function directly.

arf_complex_mul e f a b c d prec rnd

arf_complex_mul_fallback e f a b c d prec rnd

Computes the complex product \(e + fi = (a + bi)(c + di)\), rounding both \(e\) and \(f\) correctly to prec bits in the direction specified by rnd. The first bit in the return code indicates inexactness of \(e\), and the second bit indicates inexactness of \(f\).

If any of the components a, b, c, d is zero, two real multiplications and no additions are done. This convention is used even if any other part contains an infinity or NaN, and the behavior with infinite/NaN input is defined accordingly.

The fallback version is implemented naively, for testing purposes. No squaring optimization is implemented.

arf_complex_sqr e f a b prec rnd

Computes the complex square \(e + fi = (a + bi)^2\). This function has identical semantics to arf_complex_mul (with \(c = a, b = d\)), but is faster.

_arf_get_integer_mpn y xp xn exp

Given a floating-point number x represented by xn limbs at xp and an exponent exp, writes the integer part of x to y, returning whether the result is inexact. The correct number of limbs is written (no limbs are written if the integer part of x is zero). Assumes that xp[0] is nonzero and that the top bit of xp[xn-1] is set.

_arf_set_mpn_fixed z xp xn fixn negative prec rnd

Sets z to the fixed-point number having xn total limbs and fixn fractional limbs, negated if negative is set, rounding z to prec bits in the direction rnd and returning whether the result is inexact. Both xn and fixn must be nonnegative and not so large that the bit shift would overflow an slong, but otherwise no assumptions are made about the input.

_arf_set_round_ui z x sgnbit prec rnd

Sets z to the integer x, negated if sgnbit is 1, rounded to prec bits in the direction specified by rnd. There are no assumptions on x.

_arf_set_round_uiui z fix hi lo sgnbit prec rnd

Sets the mantissa of z to the two-limb mantissa given by hi and lo, negated if sgnbit is 1, rounded to prec bits in the direction specified by rnd. Requires that not both hi and lo are zero. Writes the exponent shift to fix without writing the exponent of z directly.

_arf_set_round_mpn z exp_shift x xn sgnbit prec rnd

Sets the mantissa of z to the mantissa given by the xn limbs in x, negated if sgnbit is 1, rounded to prec bits in the direction specified by rnd. Returns the inexact flag. Requires that xn is positive and that the top limb of x is nonzero. If x has leading zero bits, writes the shift to exp_shift. This method does not write the exponent of z directly. Requires that x does not point to the limbs of z.