Package it.unich.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_
orgmp_
) 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 prefixis
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
andexport
becomebufferImport
andbufferExport
respectively.
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
andmptype_clears
are only used internally and are not exposed by the high-level classes; - if
baseName
begins withrealloc2
,set
orswap
, we create a method calledbaseName
which calls the original function, implicitly usingthis
as the firstmptype
parameter; - if
baseName
begins withinit
, 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 methodbaseNameAssign
which calls the original function, implicitly usingthis
as the first non-constantmptype_t
parameter; - if the function has at least a non constant
mptype_t
parameter and a constant one, we create a methodbaseNameAssign
which calls the original function, implicitly usingthis
as both the first non-constantmptype_t
parameter and the most relevant constantmptype_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.
- if the function has at least a non constant
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
andlong
) Generally mapped to the respective Java types. This may cause truncation when the nativelong
is only 32 bit. If anint
is used to represent a boolean, then theboolean
type is used in JGMP.unsigned long
,size_t
,mp_bitcnt
,mp_size_t
andmp_exp_t
) Mapped tolong
. This may cause truncation when the native size of these types is only 32 bit. Note thatunsigned long
,size_t
andmp_bitcnt
are natively unsigned. Handle with care.mpz_t
) Mapped toMPZ
.mpq_t
) Mapped toMPQ
.mpf_t
) Mapped toMPF
.gmp_randstate_t
) Mapped toRandState
.const char*
) Mapped toString
.char*
) All functions requiring a non-constchar*
may be called with anull
pointer. Since this is much easier to handle, we choose to always follow this pattern. Therefore, non-constantchar*
are always removed from the input parameters. Whenchar*
is used a return value, it is mapped to aString
.void
) If a method would returnvoid
, we prefer to returnthis
instead, in order to ease chaining method calls.
-
Class Summary Class Description AllocationMonitor The allocation monitor keeps track of the amount of native memory allocated by GMP, and calls the Java garbage collector when it finds that too much native memory is being used.AllocationMonitor.JGMPAlloc The custom allocator function.AllocationMonitor.JGMPFree The custom deallocator.AllocationMonitor.JGMPRealloc The custom reallocator.GMP Collects global variables and static methods which do no fit in more specific classes.MPF Multi-precision floating point numbers.MPF.MPFCleaner Cleaning action for theMPF
class.MPQ Multi-precision rational numbers.MPQ.MPQCleaner Cleaning action for theMPQ
class.MPZ Multi-precision integer number.MPZ.MPZCleaner Cleaning action for theMPZ
class.RandState Current state of a random number generator.RandState.RandomStateCleaner Cleaning action for theRandState
class. -
Enum Summary Enum Description MPZ.PrimalityStatus Result enumeration for theMPZ.isProbabPrime(int)
method.