definitions.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[/
    Boost.Optional

    Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]


[section Definitions]

[section Introduction]

This section provides definitions of terms used in the Numeric Conversion library.

[blurb [*Notation]
[_underlined text] denotes terms defined in the C++ standard.

[*bold face] denotes terms defined here but not in the standard.
]

[endsect]

[section Types and Values]

As defined by the [_C++ Object Model] (§1.7) the [_storage] or memory on which a
C++ program runs is a contiguous sequence of [_bytes] where each byte is a
contiguous sequence of bits.

An [_object] is a region of storage (§1.8) and has a type (§3.9).

A [_type] is a discrete set of values.

An object of type `T` has an [_object representation] which is the sequence of
bytes stored in the object (§3.9/4)

An object of type `T` has a [_value representation] which is the set of
bits that determine the ['value] of an object of that type (§3.9/4).
For [_POD] types (§3.9/10), this bitset is given by the object representation,
but not all the bits in the storage need to participate in the value
representation (except for character types): for example, some bits might
be used for padding or there may be trap-bits.

__SPACE__

The [*typed value] that is held by an object is the value which is determined
by its value representation.

An [*abstract value] (untyped) is the conceptual information that is
represented in a type (i.e. the number π).

The [*intrinsic value] of an object is the binary value of the sequence of
unsigned characters which form its object representation.

__SPACE__

['Abstract] values can be [*represented] in a given type.

To [*represent] an abstract value `V` in a type `T` is to obtain a typed value
`v` which corresponds to the abstract value `V`.

The operation is denoted using the `rep()` operator, as in: `v=rep(V)`.
`v` is the [*representation] of `V` in the type `T`.

For example, the abstract value π can be represented in the type
`double` as the `double value M_PI` and in the type `int` as the
`int value 3`

__SPACE__

Conversely, ['typed values] can be [*abstracted].

To [*abstract] a typed value `v` of type `T` is to obtain the abstract value `V`
whose representation in `T` is `v`.

The operation is denoted using the `abt()` operator, as in: `V=abt(v)`.

`V` is the [*abstraction] of `v` of type `T`.

Abstraction is just an abstract operation (you can't do it); but it is
defined nevertheless because it will be used to give the definitions in the
rest of this document.

[endsect]

[#numeric_conversion_cpp_arithmetic_types]

[section C++ Arithmetic Types]

The C++ language defines [_fundamental types] (§3.9.1). The following subsets of
the fundamental types are intended to represent ['numbers]:

[variablelist
[[[_signed integer types] (§3.9.1/2):][
`{signed char, signed short int, signed int, signed long int}`
Can be used to represent general integer numbers (both negative and positive).
]]
[[[_unsigned integer types] (§3.9.1/3):][
`{unsigned char, unsigned short int, unsigned int, unsigned long int}`
Can be used to represent positive integer numbers with modulo-arithmetic.
]]
[[[_floating-point types] (§3.9.1/8):][
`{float,double,long double}`
Can be used to represent real numbers.
]]
[[[_integral or integer types] (§3.9.1/7):][
`{{signed integers},{unsigned integers}, bool, char and wchar_t}`
]]
[[[_arithmetic types] (§3.9.1/8):][
`{{integer types},{floating types}}`
]]
]

The integer types are required to have a ['binary] value representation.

Additionally, the signed/unsigned integer types of the same base type
(`short`, `int` or `long`) are required to have the same value representation,
that is:

             int i = -3 ; // suppose value representation is: 10011 (sign bit + 4 magnitude bits)
    unsigned int u =  i ; // u is required to have the same 10011 as its value representation.

In other words, the integer types signed/unsigned X use the same value
representation but a different ['interpretation] of it; that is, their
['typed values] might differ.

Another consequence of this is that the range for signed X is always a smaller
subset of the range of unsigned X, as required by §3.9.1/3.

[note
Always remember that unsigned types, unlike signed types, have modulo-arithmetic;
that is, they do not overflow.
This means that:

[*-] Always be extra careful when mixing signed/unsigned types

[*-] Use unsigned types only when you need modulo arithmetic or very very large
numbers. Don't use unsigned types just because you intend to deal with
positive values only (you can do this with signed types as well).
]


[endsect]

[#numeric_conversion_definitions_numeric_types]

[section Numeric Types]

This section introduces the following definitions intended to integrate
arithmetic types with user-defined types which behave like numbers.
Some definitions are purposely broad in order to include a vast variety of
user-defined number types.

Within this library, the term ['number] refers to an abstract numeric value.

A type is [*numeric] if:

* It is an arithmetic type, or,
* It is a user-defined type which
    * Represents numeric abstract values (i.e. numbers).
    * Can be converted (either implicitly or explicitly) to/from at least one arithmetic type.
    * Has [link numeric_conversion_definitions_range range] (possibly unbounded) 
      and [link numeric_conversion_definitions_range precision] (possibly dynamic or
      unlimited).
    * Provides an specialization of `std::numeric_limits`.

A numeric type is [*signed] if the abstract values it represent include negative numbers.

A numeric type is [*unsigned] if the abstract values it represent exclude negative numbers.

A numeric type is [*modulo] if it has modulo-arithmetic (does not overflow).

A numeric type is [*integer] if the abstract values it represent are whole numbers.

A numeric type is [*floating] if the abstract values it represent are real numbers.

An [*arithmetic value] is the typed value of an arithmetic type

A [*numeric value] is the typed value of a numeric type

These definitions simply generalize the standard notions of arithmetic types and
values by introducing a superset called [_numeric]. All arithmetic types and values are
numeric types and values, but not vice versa, since user-defined numeric types are not
arithmetic types.

The following examples clarify the differences between arithmetic and numeric
types (and values):


    // A numeric type which is not an arithmetic type (is user-defined)
    // and which is intended to represent integer numbers (i.e., an 'integer' numeric type)
    class MyInt
    {
        MyInt ( long long v ) ;
        long long to_builtin();
    } ;
    namespace std {
    template<> numeric_limits<MyInt> { ... } ;
    }

    // A 'floating' numeric type (double) which is also an arithmetic type (built-in),
    // with a float numeric value.
    double pi = M_PI ;

    // A 'floating' numeric type with a whole numeric value.
    // NOTE: numeric values are typed valued, hence, they are, for instance,
    // integer or floating, despite the value itself being whole or including
    // a fractional part.
    double two = 2.0 ;

    // An integer numeric type with an integer numeric value.
    MyInt i(1234);


[endsect]

[#numeric_conversion_definitions_range]

[section Range and Precision]

Given a number set `N`, some of its elements are representable in a numeric type `T`.

The set of representable values of type `T`, or numeric set of `T`, is a set of numeric
values whose elements are the representation of some subset of `N`.

For example, the interval of `int` values `[INT_MIN,INT_MAX]` is the set of representable
values of type `int`, i.e. the `int` numeric set, and corresponds to the representation
of the elements of the interval of abstract values `[abt(INT_MIN),abt(INT_MAX)]` from
the integer numbers.

Similarly, the interval of `double` values `[-DBL_MAX,DBL_MAX]` is the `double`
numeric set, which corresponds to the subset of the real numbers from `abt(-DBL_MAX)` to
`abt(DBL_MAX)`.

__SPACE__

Let [*`next(x)`] denote the lowest numeric value greater than x.

Let [*`prev(x)`] denote the highest numeric value lower then x.

Let [*`v=prev(next(V))`] and [*`v=next(prev(V))`] be identities that relate a numeric
typed value `v` with a number `V`.

An ordered pair of numeric values `x`,`y` s.t. `x<y` are [*consecutive] iff `next(x)==y`.

The abstract distance between consecutive numeric values is usually referred to as a
[_Unit in the Last Place], or [*ulp] for short. A ulp is a quantity whose abstract
magnitude is relative to the numeric values it corresponds to: If the numeric set
is not evenly distributed, that is, if the abstract distance between consecutive
numeric values varies along the set -as is the case with the floating-point types-,
the magnitude of 1ulp after the numeric value `x` might be (usually is) different
from the magnitude of a 1ulp after the numeric value y for `x!=y`.

Since numbers are inherently ordered, a [*numeric set] of type `T` is an ordered sequence
of numeric values (of type `T`) of the form:

    REP(T)={l,next(l),next(next(l)),...,prev(prev(h)),prev(h),h}

where `l` and `h` are respectively the lowest and highest values of type `T`, called
the boundary values of type `T`.

__SPACE__

A numeric set is discrete. It has a [*size] which is the number of numeric values in the set,
a [*width] which is the abstract difference between the highest and lowest boundary values:
`[abt(h)-abt(l)]`, and a [*density] which is the relation between its size and width:
`density=size/width`.

The integer types have density 1, which means that there are no unrepresentable integer
numbers between `abt(l)` and `abt(h)` (i.e. there are no gaps). On the other hand,
floating types have density much smaller than 1, which means that there are real numbers
unrepresented between consecutive floating values (i.e. there are gaps).

__SPACE__

The interval of [_abstract values] `[abt(l),abt(h)]` is the range of the type `T`,
denoted `R(T)`.

A range is a set of abstract values and not a set of numeric values. In other