Integer Models

Table of Contents

• Overview
• Basic integer types and NumberTraits
• How to add your own integer type

Authors:

David Coeurjolly, Jacques-Olivier Lachaud

Overview

When implementing digital geometry algorithms, the choice of integer type to implement or approximate \(Z\) is crucial in many situations. In DGtal, objects, datastructure and algorithms are orthogonal to this choice in the sense that the user can specify the best Integer type for his own pruposes.

First of all, approximation with built-in integer types with bounded ranges can be considered. For example, DGtal::int32_t defines OS independent 32 bits signed integers.

If more precision is required and if GMP (Gnu multiprecision library) is available, DGtal::BigInteger defines arbitrary precision integers. In this case, performances can be impacted.

As detailed in the Digital Spaces, Points, Vectors and Domains documentation, the integer type choice is specified as template parameter of templated classes (e.g. SpaceND). The main constraint on the type is that it induces a commutative ring with identity for the classical addition, and multiplication operators.

Note:

In DGtal, such type must be a model of CCommutativeRing concept. We use the boost concept checking system to check the consistency of a concept model during the compilation.

Basic integer types and NumberTraits

First of all, BasicTypes refines in DGtal classical built-in integer types such as DGtal::uint64_t or DGtal::int32_t. However, not all these types are models of the concept CCommutativeRing. Indeed, DGtal::uint64_t has no inverse for the addition operator.

Hence, if we have a templated class SpaceND with two arguments: a static dimension and a type of integer. And if we add a constraint that the integer type must be a model of CCommutativeRing, the following code:

typedef DGtal::SpaceND<2, DGtal::uint64_t> MySpace;

will produce a compiler error.

In DGtal algorithms, we sometimes need information or associated types attached to a integer type. NumberTraits structure is used to decorate integer types with tags (e.g. NumberTraits<T>::IsSigned), associated types (e.g. NumberTraits<T>::UnsignedVersion), constant values (e.g. NumberTraits<T>::ONE and NumberTraits<T>::ZERO), or conversion functions (e.g. NumberTraits<T>::castToDouble()).

How to add your own integer type

If you want to use your own integer type in DGtal, two things have to be done:

• Create a facade or a wrapper to make sure that your own type is a model of the CCommutativeRing concept.
• Add a specialization for your type in the NumberTraits structure.