Package it.unich.jgmp

package it.unich.jgmp
This package contains all the high-level classes of JGMP.

Here are some guidelines we have followed in developing the API for the JGMP library. We tried to adhere to Java conventions, while keeping methods discoverable by people who already know the GMP library. These rules may be overriden in specific cases.

Naming conventions: the base name

For each GMP function, a base name is determined by the original name as follows:

  • the prefix (mpf_, mpq_, mpz_ or gmp_) is removed; the same happens to the components _si, _d and _str, if this does not clause signature clashes;
  • the component _ui is kept to help the user distinguish unsigned long parameters;
  • the postfix _p, which sometimes marks functions returning booleans, is either removed or replaced by the prefix is when this makes sense;
  • the rest of the name is transformed to camel case, by converting to uppercase the first letter after each underscore;
  • name which could cause conflicts with Java reserved words are modified: for example, import and export become bufferImport and bufferExport respectively.
The base name is then used to give a name to the corresponding Java method, according to the following rules.

Naming conventions: general rules

Given a GMP function, the following rules dictate how to derive name and signature for the corrisponding method in JGMP. Let mptype be the family of the function, which may be either mpf, mpq or mpz. The function becomes a method of the corresponding MPF, MPQ or MPZ class. In particular:

  • the function mptype_clear is only used internally;
  • the functions mptype_inits and mptype_clears are only used internally and are not exposed by the high-level classes;
  • if baseName begins with realloc2, set or swap, we create a method called baseName which calls the original function, implicitly using this as the first mptype parameter;
  • if baseName begins with init, we create a side-effect free static method (see later);
  • for all the other functions:
    • if the function has at least a non constant mptype_t parameter, then we create a method baseNameAssign which calls the original function, implicitly using this as the first non-constant mptype_t parameter;
    • if the function has at least a non constant mptype_t parameter and a constant one, we create a method baseNameAssign which calls the original function, implicitly using this as both the first non-constant mptype_t parameter and the most relevant constant mptype_t parameter, with the exception of a few cases where such as a method would not be particularly useful;
    • we create e side-effect free method called baseName, with the exception of a few cases where such as a method would not be particularly useful.
In general, all the parameters which are not provided implicitly to the original GMP function through this should be provided explicitly.

Other methods and constructors which conform to standard Java naming conventions might be provided.

Side-effect free methods

In order to simplify the development of code without side-effects, we enrich the API provided by JGMP with side-effect free methods, which builds new objects instead of modifying old ones. First of all, we distinguish between input and output parameters for the GMP function. Some parameters may have both an input and an output nature. The side-effect free method takes all input parameters in its signature, with the exception of the first input mptype_t parameter which is mapped to this. If there are no input mptype_t parameters, the method will be static. The method creates new objects for the output parameters, eventually cloning the ones also used as an input. After calling the GMP functions, the return value and all the output parameters are returned by the method, eventually packed in an org.javatuples.Tuple, from left to right according to the function signature. Sometimes, when the first mptype_t input parameter comes after other input parameters, this procedure may lead to a signature clash. In this case, the name of the method is changed into baseNameReverse.

Type mapping

The types of the formal parameters and return value of a GMP function are mapped to the types of the JGMP method as follows:

  • int and long) Generally mapped to the respective Java types. This may cause truncation when the native long is only 32 bit. If an int is used to represent a boolean, then the boolean type is used in JGMP.
  • unsigned long, size_t, mp_bitcnt, mp_size_t and mp_exp_t) Mapped to long. This may cause truncation when the native size of these types is only 32 bit. Note that unsigned long, size_t and mp_bitcnt are natively unsigned. Handle with care.
  • mpz_t) Mapped to MPZ.
  • mpq_t) Mapped to MPQ.
  • mpf_t) Mapped to MPF.
  • gmp_randstate_t) Mapped to RandState.
  • const char*) Mapped to String.
  • char*) All functions requiring a non-const char* may be called with a null pointer. Since this is much easier to handle, we choose to always follow this pattern. Therefore, non-constant char* are always removed from the input parameters. When char* is used a return value, it is mapped to a String.
  • void) If a method would return void, we prefer to return this instead, in order to ease chaining method calls.