Lib:Architecture/Base Layer/Basic Types Module
From GNUpdf
| Library Module | |
|---|---|
| Basic Types Module | |
| Layer | Base |
| API Documentation | Reference Manual |
| Source Files | src/base/pdf-types.h |
Contents |
Overview
This module provides a system-independent implementation of basic data types such as signed and unsigned integers, constants, etc.
Boolean Types
- pdf_bool_t
- A boolean variable.
The following constants defines the valid values to be hold in a pdf_bool_t variable:
- PDF_TRUE
- PDF_FALSE
Numeric Types
- pdf_i32_t
- Signed 32 bit integer.
- pdf_u32_t
- Unsigned 32 bit integer.
- pdf_i64_t
- Signed 64 bit integer.
The following constants are defined in order to define the valid value ranges for these data types:
- PDF_I32_MAX
- Maximum value able to be stored in a pdf_i32_t variable.
- PDF_I32_MIN
- Minimum value able to be stored in a pdf_i32_t variable.
- PDF_U32_MAX
- Maximum value able to be stored in a pdf_u32_t variable.
- PDF_U32_MIN
- Minimum value able to be stored in a pdf_u32_t variable.
64 bit integers
The pdf_i64_t type is a signed 64 bit integer designed to represent large numbers in 32 bit machines (e.g. embedded systems in printers, etc...). Negative numbers are represented in 2's-complement format. The way to initialise a 64 bit number is by using a 32 bit signed integer and a 32 bit unsigned integer (see API for details on this). One has to remember that the final result is in 2's complement so the user has to set the bits of each input integer accordingly so, when concatenated, they form the desired 64 bit signed integer.
Several methods related to this type are defined in the API. The initialisation function, pdf_i64_new, fulfils the tasks mentioned in the previous paragraph. Two other funcitons, pdf_i64_assign and pdf_i64_assign_quick, assign a value to the selected pdf_i64_t by using two 32 bit integers (one unsigned and one signed) for the former and one signed integer for the latter. Also included, is a basic copy method to copy data between pdf_i64_t type variables.
Several arithmetic operations are included in the API: addition, subtraction, multiplication, division, comparison, negation and absolute value.
The addition method is based on the classical addition algorithm included in Knuth's Art of Computer Programming (Vol 2). In this algorithm a convenient base is selected to represent the numbers to be added and a relatively simple carry system is used. In our case, due to the 32 bit limit imposed by the portability requirement of the pdf library, the unsigned 32 bit number and the signed 32 bit numbers are divided in two 16 bit ones each to be able to manage the intermediate storage. In other words, the addition is made in a 16 bit base (and not 32 bit) to avoid unwanted overflows during the process.
Regarding the subtraction, thanks to the nature of the 2's-complement system, it is simply carried out by negating the subtrahend and adding it up to the minuend. The negation function is used in this case. This function basically carries out the 2's-complement conversion of a 64-bit number type by inverting the integer's bits and adding one to the result. The absolute value of a pdf_64i_t number is carried out in a similar fashion.
The comparison of two pdf_i64_bit types starts with the 32 bit signed part of the structure and if they are the same, a comparison of the 32 bit unsigned part of the structure representing the least significant bits is carried out.
The multiplication operation is also based in one of the classical arithmetic algorithm's presented in Knuth's Art of Computer Programming (Vol 2). Overflows are more common in this case so an 8 bit base is chosen to avoid them during the calculations. Internally the method can handle results of 128 bits, but if the result needs more than 64 bits (in 2's complement format) to be represented then an error is flagged as an output of the function.
The long division is also based on an intuitive algorithm included and proved by Knuth in the same volume mentioned above.
