Chapter 3: Interface Semantics

Team-Fly

---

When people hear some words, they normally believe that there's some thought behind them.

—Goethe, Faust, Part 1

IN THE FOLLOWING WE SHALL set some fundamental properties that relate to the behavior of the interface and the use of FLINT/C functions. First we shall consider the textual representation of CLINT objects and FLINT/C functions, but primarily we wish to clarify some fundamentals of the implementation that are important to the use of the functions.

The functions of the FLINT/C package are identified with the convention that their names end with "_l"; for example, add_l denotes the addition function. Designators of CLINT objects likewise end with an underscore and an appended l. For the sake of simplicity we shall equate from now on, when conditions permit, a CLINT object n_l with the value that it represents.

The representation of a FLINT/C function begins with a header, which contains the syntactic and semantic description of the function interface. Such function headers typically look something like the following.

Function:	a brief description of the function
Syntax:	int f_l (CLINT a_l, CLINT b_l, CLINT c_l);
Input:	a_l, b_l (operands)
Output:	c_l (result)
Return:	0 if all is ok otherwise, a warning or error message

Here we distinguish, among other things, between output and return value: While output refers to the values that are stored by the function in the passed arguments, by return we mean the values that the function returns via a return command. Except for a few cases (for example, the functions ld_l(), Section 10.3, and twofact_l(), Section 10.4.1), the return value consists of status information or error messages.

Parameters other than those involved with output are not changed by the function. Calls of the form f_l(a_l, b_l, a_l), where a_l and b_l are used as arguments and a_l is overwritten with the return value at the end of the computation, are always possible, since the return variable is written to with the return value only after the complete execution of the operation. From assembler programming one says in this case that the variable a_l is used as an accumulator. This modus operandi is supported by all FLINT/C functions.

A CLINT object n_l possesses leading zeros if for a value l one has

 (DIGITS_L (n_l) == l) && (l > 0) && (n_l[l] == 0); 

Leading zeros are redundant, since although they lengthen the representation of a number, they have no effect on its value. However, leading zeros are allowed in the notation of a number, for which reason we should not simply ignore this option. The acceptance of leading zeros is, to be sure, a burdensome implementation detail, but it leads to increased tolerance of input from external sources and thus contributes to the stability of all the functions. CLINT numbers with leading zeros are thus accepted by all FLINT/C functions, but they are not generated by them.

A further setting is related to the behavior of arithmetic functions in the case of overflow, which occurs when the result of an arithmetic operation is too large to be represented in the result type. Although in some publications on C the behavior of a program in the case of arithmetic overflow is said to be implementation-dependent, the C standard nonetheless governs precisely the case of overflow in arithmetic operations with unsigned integer types: There it is stated that arithmetic modulo 2ⁿ should be executed when the data type can represent integers of n-bit length (see [Harb], Section 5.1.2). Accordingly, in the case of overflow the basic arithmetic functions described below reduce their results modulo (N_max + 1), which means that the remainder after whole-number division by N_max + 1 is output as the result (see Section 4.3 and Chapter 5). In the case of underflow, which occurs when the result of an operation is negative, a positive residue modulo (N_max + 1) is output. The FLINT/C functions thus behave in conformity with arithmetic according to the C standard.

If an overflow or underflow is detected, the arithmetic functions return the appropriate error code. This and all other error codes in Table 3.1 are defined in the header file flint.h.

Table 3.1: FLINT/C error codes

Error Code	Interpretation
E_CLINT_BOR	invalid basis in str2clint_l() (see Chapter 8)
E_CLINT_DBZ	division by zero
E_CLINT_MAL	error in memory allocation
E_CLINT_MOD	nonodd (even) modulus in Montgomery multiplication
E_CLINT_NOR	register unavailable (see Chapter 9)
E_CLINT_NPT	null pointer passed as argument
E_CLINT_OFL	overflow
E_CLINT_UFL	underflow

---

Team-Fly