code_conventions.txt

Code conventions
================

Language dialect
----------------

For greater portability, the code should be ANSI C compatible where possible.  
We note the following exceptions:

    - Inlined functions, inlined assembly.  We define alternative keywords 
      __asm__ and __inline__ in flint.h so that gcc allows compiling with 
      the flags "-ansi -pendatic" nonetheless.

Primitive types
---------------

Depending on the main interpretation of the value of a variable, where 
possible the following primitive datatype should be used:

    | bit counts up to a single limb         | unsigned long       |
    | bit counts, multiprecision             | mp_bitcnt_t         |
    | limb counts in multiprecision integers | mp_size_t           |
    | limbs                                  | mp_limb_t           |
    | mp_limb_t arrays                       | mp_ptr/ mp_srcptr   |
    | ui/ si function constants              | unsigned long/len_t |
    | polynomial lengths                     | len_t               |
    | number of indeterminates               | len_t               |
    | row/ column indices                    | len_t               |
    | precision for mpfr types               | mpfr_prec_t         |

The typical definitions of these in terms of primitive types are:

    | mp_bitcnt_t   | unsigned long, or unsigned long long               |
    | mp_size_t     | int, long, or long long                            |
    | mp_limb_t     | unsigned int, unsigned long, or unsigned long long |
    | mp_ptr        | mp_limb_t *                                        |
    | mp_srcptr     | const mp_limb_t *                                  |
    | len_t         | long                                               |

Type definitions
----------------

Aside from the more mathematical FLINT types, we also use the following 
definitions:

   | ulong | unsigned long |

Random functions
----------------

When writing functions which produce random values the order of operands should 
follow one of the following:

if the function returns its random value, the state comes first, e.g:

a = n_randint(state, n)

if the function sets its first argument to a random value, the state
comes second, e.g.

nmod_poly_randtest(poly, state, len, bits)

Conversion functions
--------------------

When naming functions which convert between objects of different modules, use
the convention module1_get_module2 and module1_set_module2, where module1 is
notionally the more complex of the two modules. E.g. fmpz_poly_get_nmod_poly.
The set function should set an object of module1 to the value of an object of
module2, and the get function should do the opposite.

Code formatting
---------------

The C code should follow the style produced by the following call to "indent",

    indent -bap -blf -bli0 -cbi0 -cdw -cli4 -cs -i4 -l79 -nbad -nbc -nce -npcs -nprs -nut -pmt -psl -saf -sai -saw -sbi0 -ss -ts4

which is explained as follows:

    -bap   Force blank lines after procedure bodies
    -blf   Put braces on line following function definition line
    -bli0  Indent braces 0 spaces
    -cbi0  Indent braces after a case label 0 spaces
    -cdw   Cuddle while of do {} while
    -cli4  Case label indent of 4 spaces
    -cs    Put a space after a cast operator
    -i4    Set indentation level to 4 spaces
    -l79   Set maximum line length for non-comment lines to 79
    -nbad  Do not force blank lines after declarations
    -nbc   Do not force newlines after commas in declarations
    -nce   Do not cuddle else
    -npcs  Do not put a space after the function in function calls
    -nprs  Do not put a space after every ( and before every )
    -nut   Use spaces instead of tabs
    -pmt   Preserve access and modificaion times on output files
    -psl   Put the type of a procedure on the line before its name
    -saf   Put a space before each for
    -sai   Space after each for
    -saw   Space after every while
    -sbi0  Indent braces of a struct, union or enum 0 spaces
    -ss    On one-line for and while statements, for a blank before ;
    -ts4   Set tab size to 4 spaces